mongodb-rag is a sample application that demonstrates the
Retrieval-Augmented Generation (RAG)
pattern on the Jakarta EE / MicroProfile stack.
The goal is to answer natural-language questions about a company’s HR policies grounded in a private knowledge base, rather than relying on what the language model already knows. Policy text is embedded into vectors and stored in MongoDB; at query time the most relevant passages are retrieved and handed to the chat model as context, so answers stay faithful to the ingested documents.
The application exposes two REST endpoints:
-
POST /hr/policies/context— ingest a piece of HR policy text into the knowledge base. The text is embedded and stored, skipping near-duplicates. -
POST /hr/policies/ask— ask a question; the service retrieves the most relevant policy passages and lets the agent generate a grounded answer.
-
Java 21
-
Helidon MP 4 — MicroProfile runtime (CDI, JAX-RS, MicroProfile Config, Health, Metrics, OpenAPI).
-
LangChain4j — orchestrates the RAG pipeline (embeddings, retrieval, and the AI service agent), wired into CDI through the LangChain4j CDI extension.
-
OpenAI —
text-embedding-3-smallfor embeddings and a chat model for answer generation. -
MongoDB Atlas Vector Search — the vector store that persists embeddings and performs similarity search.
|
Tip
|
Configuration such as the OpenAI API key, model names, and the MongoDB
connection string lives in src/main/resources/META-INF/microprofile-config.properties
and can be overridden with environment variables via MicroProfile Config.
|
The application exposes two endpoints under /hr/policies. First ingest some
HR policy context into the knowledge base, then ask questions about it.
Send policy text to be embedded and stored. Near-duplicates are skipped.
curl -X POST http://localhost:8080/hr/policies/context \ -H "Content-Type: application/json" \ -d '{"context": "Remote work is permitted on Tuesdays and Thursdays. The annual hardware stipend has been increased to $1,500. Core hours are 10:00 AM to 3:00 PM EST."}'
When the context is new it is ingested and the API responds with 201 Created:
{"inserted":true,"message":"The HR policy context was added to the knowledge base."}If a similar context already exists the API responds with 200 OK and skips ingestion:
{"inserted":false,"message":"Similar HR policy context already exists."}Ask a natural-language question; the service retrieves the most relevant policy passages and the agent generates a grounded answer.
curl -X POST http://localhost:8080/hr/policies/ask \ -H "Content-Type: application/json" \ -d '{"question": "What is my hardware stipend limit?"}'
Example response:
{"question":"What is my hardware stipend limit?","answer":"Your annual hardware stipend is $1,500."}The generation of native binaries requires an installation of GraalVM 22.1.0+.
You can build a native binary using Maven as follows:
mvn -Pnative-image install -DskipTests
The generation of the executable binary may take a few minutes to complete depending on
your hardware and operating system. When completed, the executable file will be available
under the target directory and be named after the artifact ID you have chosen during the
project generation phase.
# Prometheus Format curl -s -X GET http://localhost:8080/metrics # TYPE base:gc_g1_young_generation_count gauge . . . # JSON Format curl -H 'Accept: application/json' -X GET http://localhost:8080/metrics {"base":... . . .
docker run --rm -p 8080:8080 mongodb-rag:latest
Exercise the application as described above.
If you don’t have access to a Kubernetes cluster, you can install one on your desktop.
kubectl cluster-info # Verify which cluster kubectl get pods # Verify connectivity to cluster
kubectl create -f app.yaml # Deploy application kubectl get pods # Wait for quickstart pod to be RUNNING kubectl get service mongodb-rag # Get service info kubectl port-forward service/mongodb-rag 8081:8080 # Forward service port to 8081
You can now exercise the application as you did before but use the port number 8081.
After you’re done, cleanup.
kubectl delete -f app.yaml
Build the custom runtime image using the jlink image profile:
mvn package -Pjlink-image
This uses the helidon-maven-plugin to perform the custom image generation. After the build completes it will report some statistics about the build including the reduction in image size.
The target/mongodb-rag-jri directory is a self contained custom image of your application. It contains your application,
its runtime dependencies and the JDK modules it depends on. You can start your application using the provide start script:
./target/mongodb-rag-jri/bin/start
Class Data Sharing (CDS) Archive Also included in the custom image is a Class Data Sharing (CDS) archive that improves your application’s startup performance and in-memory footprint. You can learn more about Class Data Sharing in the JDK documentation.
The CDS archive increases your image size to get these performance optimizations. It can be of significant size (tens of MB). The size of the CDS archive is reported at the end of the build output.
If you’d rather have a smaller image size (with a slightly increased startup time) you can skip the creation of the CDS archive by executing your build like this:
mvn package -Pjlink-image -Djlink.image.addClassDataSharingArchive=false
For more information on available configuration options see the helidon-maven-plugin documentation.