$ oc patch datasciencecluster <name> --type=merge -p {"spec":{"components":{"llamastackoperator":{"managementState":"Managed"}}}}
Info alert:Important Notice
Please note that more information about the previous v2 releases can be found here. You can use "Find a release" search bar to search for a particular release.
Working with RAG
- Overview of RAG
- Deploying a RAG stack in a data science project
- Activating the Llama Stack Operator
- Deploying a Llama model with KServe
- Testing your vLLM model endpoints
- Deploying a LlamaStackDistribution instance
- Ingesting content into a Llama model
- Querying ingested content in a Llama model
- Preparing documents with Docling for Llama Stack retrieval
- About Llama stack search types
Overview of RAG
Retrieval-augmented generation (RAG) in Open Data Hub enhances large language models (LLMs) by integrating domain-specific data sources directly into the model’s context. Domain-specific data sources can be structured data, such as relational database tables, or unstructured data, such as PDF documents.
RAG indexes content and builds an embedding store that data scientists and AI engineers can query. When data scientists or AI engineers pose a question to a RAG chatbot, the RAG pipeline retrieves the most relevant pieces of data, passes them to the LLM as context, and generates a response that reflects both the prompt and the retrieved content.
By implementing RAG, data scientists and AI engineers can obtain tailored, accurate, and verifiable answers to complex queries based on their own datasets within a data science project.
Audience for RAG
The target audience for RAG is practitioners who build data-grounded conversational AI applications using Open Data Hub infrastructure.
- For Data Scientists
-
Data scientists can use RAG to prototype and validate models that answer natural-language queries against data sources without managing low-level embedding pipelines or vector stores. They can focus on creating prompts and evaluating model outputs instead of building retrieval infrastructure.
- For MLOps Engineers
-
MLOps engineers typically deploy and operate RAG pipelines in production. Within Open Data Hub, they manage LLM endpoints, monitor performance, and ensure that both retrieval and generation scale reliably. RAG decouples vector store maintenance from the serving layer, enabling MLOps engineers to apply CI/CD workflows to data ingestion and model deployment alike.
- For Data Engineers
-
Data engineers build workflows to load data into storage that Open Data Hub indexes. They keep embeddings in sync with source systems, such as S3 buckets or relational tables to ensure that chatbot responses are accurate.
- For AI Engineers
-
AI engineers architect RAG chatbots by defining prompt templates, retrieval methods, and fallback logic. They configure agents and add domain-specific tools, such as OpenShift Container Platform job triggers, enabling rapid iteration.
Deploying a RAG stack in a data science project
As an OpenShift Container Platform cluster administrator, you can deploy a Retrieval‑Augmented Generation (RAG) stack in Open Data Hub. This stack provides the infrastructure, including LLM inference, vector storage, and retrieval services that data scientists and AI engineers use to build conversational workflows in their projects.
To deploy the RAG stack in a data science project, complete the following tasks:
-
Activate the Llama Stack Operator in Open Data Hub.
-
Enable GPU support on the OpenShift Container Platform cluster. This task includes installing the required NVIDIA Operators.
-
Deploy an inference model, for example, the llama-3.2-3b-instruct model. This task includes creating a storage connection and configuring GPU allocation.
-
Create a
LlamaStackDistribution
instance to enable RAG functionality. This action deploys LlamaStack alongside a Milvus vector store and connects both components to the inference model. -
Ingest domain data into Milvus by running Docling in a data science pipeline or Jupyter notebook. This process keeps the embeddings synchronized with the source data.
-
Expose and secure the model endpoints.
Activating the Llama Stack Operator
You can activate the Llama Stack Operator on your OpenShift Container Platform cluster by setting its managementState
to Managed
in the Open Data Hub Operator DataScienceCluster
custom resource (CR). This setting enables Llama-based model serving without reinstalling or directly editing Operator subscriptions. You can edit the CR in the OpenShift Container Platform web console or by using the OpenShift command-line interface (CLI).
Note
|
As an alternative to following the steps in this procedure, you can activate the Llama Stack Operator from the OpenShift command-line interface (CLI) by running the following command: Replace <name> with your |
-
You have cluster administrator privileges.
-
You installed the OpenShift command line interface (
oc
) as described in Installing the OpenShift CLI. -
You have installed the Open Data Hub Operator on your cluster.
-
You have a
DataScienceCluster
custom resource in your environment; the default isdefault-dsc
. -
Your infrastructure supports GPU-enabled instance types, for example,
g4dn.xlarge
on AWS. -
You have enabled GPU support in Open Data Hub, including installing the Node Feature Discovery and NVIDIA GPU Operators. For more information, see NVIDIA GPU Operator on Red Hat OpenShift Container Platform in the NVIDIA documentation.
-
You have created a
NodeFeatureDiscovery
resource instance on your cluster, as described in Installing the Node Feature Discovery Operator and creating a NodeFeatureDiscovery instance in the NVIDIA documentation. -
You have created a
ClusterPolicy
resource instance with default values on your cluster, as described in Creating the ClusterPolicy instance in the NVIDIA documentation.
-
Log in to the OpenShift Container Platform web console as a cluster administrator.
-
In the Administrator perspective, click Operators → Installed Operators.
-
Click the Open Data Hub Operator to open its details.
-
Click the Data Science Cluster tab.
-
On the DataScienceClusters page, click the
default-dsc
object. -
Click the YAML tab.
An embedded YAML editor opens, displaying the configuration for the
DataScienceCluster
custom resource. -
In the YAML editor, locate the
spec.components
section. If thellamastackoperator
field does not exist, add it. Then, set themanagementState
field toManaged
:spec: components: llamastackoperator: managementState: Managed
-
Click Save to apply your changes.
After you activate the Llama Stack Operator, verify that it is running in your cluster:
-
In the OpenShift Container Platform web console, click Workloads → Pods.
-
From the Project list, select the redhat-ods-applications namespace.
-
Confirm that a pod with the label
app.kubernetes.io/name=llama-stack-operator
appears and has a status of Running.
Deploying a Llama model with KServe
To use Llama Stack and retrieval-augmented generation (RAG) workloads in Open Data Hub, you must deploy a Llama model with a vLLM model server and configure KServe in standard deployment mode.
-
You have logged in to Open Data Hub.
-
You have cluster administrator privileges for your OpenShift Container Platform cluster.
-
You have installed the Llama Stack Operator. For more information, see Installing the Llama Stack Operator.
-
You have installed KServe.
-
You have enabled the single-model serving platform. For more information about enabling the single-model serving platform, see Enabling the single-model serving platform.
-
You can access the single-model serving platform in the dashboard configuration. For more information about setting dashboard configuration options, see Customizing the dashboard.
-
You have enabled GPU support in Open Data Hub, including installing the Node Feature Discovery Operator and NVIDIA GPU Operator. For more information, see NVIDIA GPU Operator on Red Hat OpenShift Container Platform in the NVIDIA documentation.
-
You have installed the OpenShift command line interface (
oc
) as described in Installing the OpenShift CLI. -
You have created a data science project.
-
The vLLM serving runtime is installed and available in your environment.
-
You have created a storage connection for your model that contains a
URI - v1
connection type. This storage connection must define the location of your Llama 3.2 model artifacts. For example,oci://quay.io/redhat-ai-services/modelcar-catalog:llama-3.2-3b-instruct
. For more information about creating storage connections, see Adding a connection to your data science project.
Important
|
Procedure
These steps are only supported in Open Data Hub versions 2.19 and later. |
-
In the Open Data Hub dashboard, navigate to the project details page and click the Models tab.
-
In the Single-model serving platform tile, click Select single-model.
-
Click the Deploy model button.
The Deploy model dialog opens.
-
Configure the deployment properties for your model:
-
In the Model deployment name field, enter a unique name for your deployment.
-
In the Serving runtime field, select
vLLM NVIDIA GPU serving runtime for KServe
from the drop-down list. -
In the Deployment mode field, select
Standard
from the drop-down list. -
Set Number of model server replicas to deploy to
1
. -
In the Model server size field, select
Custom
from the drop-down list.-
Set CPUs requested to
1 core
. -
Set Memory requested to
10 GiB
. -
Set CPU limit to
2 core
. -
Set Memory limit to
14 GiB
. -
Set Accelerator to
NVIDIA GPUs
. -
Set Accelerator count to
1
.
-
-
From the Connection type, select a relevant data connection from the drop-down list.
-
-
In the Additional serving runtime arguments field, specify the following recommended arguments:
--dtype=half --max-model-len=20000 --gpu-memory-utilization=0.95 --enable-chunked-prefill --enable-auto-tool-choice --tool-call-parser=llama3_json --chat-template=/app/data/template/tool_chat_template_llama3.2_json.jinja
-
Click Deploy.
NoteModel deployment can take several minutes, especially for the first model that is deployed on the cluster. Initial deployment may take more than 10 minutes while the relevant images download.
-
-
Verify that the
kserve-controller-manager
andodh-model-controller
pods are running:-
Open a new terminal window.
-
Log in to your OpenShift Container Platform cluster from the CLI:
-
In the upper-right corner of the OpenShift web console, click your user name and select Copy login command.
-
After you have logged in, click Display token.
-
Copy the Log in with this token command and paste it in the OpenShift command-line interface (CLI).
$ oc login --token=<token> --server=<openshift_cluster_url>
-
Enter the following command to verify that the
kserve-controller-manager
andodh-model-controller
pods are running:$ oc get pods -n opendatahub | grep -E 'kserve-controller-manager|odh-model-controller'
-
Confirm that you see output similar to the following example:
kserve-controller-manager-7c865c9c9f-xyz12 1/1 Running 0 4m21s odh-model-controller-7b7d5fd9cc-wxy34 1/1 Running 0 3m55s
-
If you do not see either of the
kserve-controller-manager
andodh-model-controller
pods, there could be a problem with your deployment. In addition, if the pods appear in the list, but theirStatus
is not set toRunning
, check the pod logs for errors:$ oc logs <pod-name> -n opendatahub
-
Check the status of the inference service:
$ oc get inferenceservice -n llamastack $ oc get pods -n <data science project name> | grep llama
-
The deployment automatically creates the following resources:
-
A
ServingRuntime
resource. -
An
InferenceService
resource, aDeployment
, a pod, and a service pointing to the pod.
-
-
Verify that the server is running. For example:
$ oc logs llama-32-3b-instruct-predictor-77f6574f76-8nl4r -n <data science project name>
Check for output similar to the following example log:
INFO 2025-05-15 11:23:52,750 __main__:498 server: Listening on ['::', '0.0.0.0']:8321 INFO: Started server process [1] INFO: Waiting for application startup. INFO 2025-05-15 11:23:52,765 __main__:151 server: Starting up INFO: Application startup complete. INFO: Uvicorn running on http://['::', '0.0.0.0']:8321 (Press CTRL+C to quit)
-
The deployed model displays in the Models tab on the Data Science project details page for the project it was deployed under.
-
-
-
If you see a
ConvertTritonGPUToLLVM
error in the pod logs when querying the/v1/chat/completions
API, and the vLLM server restarts or returns a500 Internal Server
error, apply the following workaround:Before deploying the model, remove the
--enable-chunked-prefill
argument from the Additional serving runtime arguments field in the deployment dialog.The error appears similar to the following:
/opt/vllm/lib64/python3.12/site-packages/vllm/attention/ops/prefix_prefill.py:36:0: error: Failures have been detected while processing an MLIR pass pipeline /opt/vllm/lib64/python3.12/site-packages/vllm/attention/ops/prefix_prefill.py:36:0: note: Pipeline failed while executing [`ConvertTritonGPUToLLVM` on 'builtin.module' operation]: reproducer generated at `std::errs, please share the reproducer above with Triton project.` INFO: 10.129.2.8:0 - "POST /v1/chat/completions HTTP/1.1" 500 Internal Server Error
Testing your vLLM model endpoints
To verify that your deployed Llama 3.2 model is accessible externally, ensure that your vLLM model server is exposed as a network endpoint. You can then test access to the model from outside both the OpenShift Container Platform cluster and the Open Data Hub interface.
Important
|
If you selected Make deployed models available through an external route during deployment, your vLLM model endpoint is already accessible outside the cluster. You do not need to manually expose the model server. Manually exposing vLLM model endpoints, for example, by using |
-
You have cluster administrator privileges for your OpenShift Container Platform cluster.
-
You have logged in to Open Data Hub.
-
You have activated the Llama Stack Operator in Open Data Hub.
-
You have deployed an inference model, for example, the llama-3.2-3b-instruct model.
-
You have installed the OpenShift command line interface (
oc
) as described in Installing the OpenShift CLI.
-
Open a new terminal window.
-
Log in to your OpenShift Container Platform cluster from the CLI:
-
In the upper-right corner of the OpenShift web console, click your user name and select Copy login command.
-
After you have logged in, click Display token.
-
Copy the Log in with this token command and paste it in the OpenShift command-line interface (CLI).
$ oc login --token=<token> --server=<openshift_cluster_url>
-
-
If you enabled Require token authentication during model deployment, retrieve your token:
$ export MODEL_TOKEN=$(oc get secret default-name-llama-32-3b-instruct-sa -n <project name> --template={{ .data.token }} | base64 -d)
-
Obtain your model endpoint URL:
-
If you enabled Make deployed models available through an external route during model deployment, click Endpoint details on the Model deployments page in the Open Data Hub dashboard to obtain your model endpoint URL.
-
In addition, if you did not enable Require token authentication during model deployment, you can also enter the following command to retrieve the endpoint URL:
$ export MODEL_ENDPOINT="https://$(oc get route llama-32-3b-instruct -n <project name> --template={{ .spec.host }})"
-
-
Test the endpoint with a sample chat completion request:
-
If you did not enable Require token authentication during model deployment, enter a chat completion request. For example:
$ curl -X POST $MODEL_ENDPOINT/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "llama-32-3b-instruct", "messages": [ { "role": "user", "content": "Hello" } ] }'
-
If you enabled Require token authentication during model deployment, include a token in your request. For example:
curl -s -k $MODEL_ENDPOINT/v1/chat/completions \ --header "Authorization: Bearer $MODEL_TOKEN" \ --header 'Content-Type: application/json' \ -d '{ "model": "llama-32-3b-instruct", "messages": [ { "role": "user", "content": "can you tell me a funny joke?" } ] }' | jq .
NoteThe
-k
flag disables SSL verification and should only be used in test environments or with self-signed certificates.
-
Confirm that you received a JSON response containing a chat completion. For example:
{
"id": "chatcmpl-05d24b91b08a4b78b0e084d4cc91dd7e",
"object": "chat.completion",
"created": 1747279170,
"model": "llama-32-3b-instruct",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Hello! It's nice to meet you. Is there something I can help you with or would you like to chat?",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": null
}],
"usage": {
"prompt_tokens": 37,
"total_tokens": 62,
"completion_tokens": 25,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
If you do not receive a response similar to the example, verify that the endpoint URL and token are correct, and ensure your model deployment is running.
Deploying a LlamaStackDistribution instance
You can integrate LlamaStack and its retrieval-augmented generation (RAG) capabilities with your deployed Llama 3.2 model served by vLLM. This integration enables you to build intelligent applications that combine large language models (LLMs) with real-time data retrieval, providing more accurate and contextually relevant responses for your AI workloads.
When you create a LlamaStackDistribution
custom resource (CR), specify the Llama Stack image quay.io/opendatahub/llama-stack:odh
in the spec.server.distribution.image
field. The image is hosted on Quay.io, a secure registry that provides vulnerability scanning, role‑based access control, and globally distributed content delivery. Using this Red Hat–validated image ensures that your deployment automatically receives the latest security patches and compatibility updates. For more information about working with Quay.io, see Quay.io overview.
Important
|
The Llama Stack image is hosted on Quay.io only during the Developer Preview phase of the Llama Stack integration with Open Data Hub. When the Llama Stack integration reaches general availability, the image will be available on registry.redhat.io. |
-
You have enabled GPU support. This includes installing the Node Feature Discovery and NVIDIA GPU Operators. For more information, see NVIDIA GPU Operator on Red Hat OpenShift Container Platform in the NVIDIA documentation.
-
You have cluster administrator privileges for your OpenShift Container Platform cluster.
-
You have logged in to Open Data Hub.
-
You have activated the Llama Stack Operator in Open Data Hub.
-
You have deployed an inference model with vLLM, for example, the llama-3.2-3b-instruct model, and you have selected Make deployed models available through an external route and Require token authentication during model deployment.
-
You have the correct inference model identifier, for example, llama-3-2-3b.
-
You have the model endpoint URL, ending with
/v1
, such ashttps://llama-32-3b-instruct-predictor:8443/v1
. -
You have the API token required to access the model endpoint.
-
You have installed the OpenShift command line interface (
oc
) as described in Installing the OpenShift CLI.
-
Open a new terminal window.
-
Log in to your OpenShift Container Platform cluster from the CLI:
-
In the upper-right corner of the OpenShift web console, click your user name and select Copy login command.
-
After you have logged in, click Display token.
-
Copy the Log in with this token command and paste it in the OpenShift command-line interface (CLI).
$ oc login --token=<token> --server=<openshift_cluster_url>
-
-
Create a secret containing the inference model environment variables:
export INFERENCE_MODEL="llama-3-2-3b" export VLLM_URL="https://llama-32-3b-instruct-predictor:8443/v1" export VLLM_TLS_VERIFY="false" # Use "true" in production! export VLLM_API_TOKEN="<token identifier>" oc create secret generic llama-stack-inference-model-secret \ --from-literal INFERENCE_MODEL="$INFERENCE_MODEL" \ --from-literal VLLM_URL="$VLLM_URL" \ --from-literal VLLM_TLS_VERIFY="$VLLM_TLS_VERIFY" \ --from-literal VLLM_API_TOKEN="$VLLM_API_TOKEN"
-
Log in to the OpenShift web console.
-
From the left-hand navigation, select Administrator view.
-
Click the Quick Create (
) icon and then click the Import YAML option.
-
In the YAML editor that appears, create a custom resource definition (CRD) similar to the following example:
apiVersion: llamastack.io/v1alpha1 kind: LlamaStackDistribution metadata: name: lsd-llama-milvus spec: replicas: 1 server: containerSpec: resources: requests: cpu: "250m" memory: "500Mi" limits: cpu: "2" memory: "12Gi" env: - name: INFERENCE_MODEL valueFrom: secretKeyRef: key: INFERENCE_MODEL name: llama-stack-inference-model-secret - name: VLLM_URL valueFrom: secretKeyRef: key: VLLM_URL name: llama-stack-inference-model-secret - name: VLLM_TLS_VERIFY valueFrom: secretKeyRef: key: VLLM_TLS_VERIFY name: llama-stack-inference-model-secret - name: VLLM_API_TOKEN valueFrom: secretKeyRef: key: VLLM_API_TOKEN name: llama-stack-inference-model-secret - name: MILVUS_DB_PATH value: ~/.llama/milvus.db - name: FMS_ORCHESTRATOR_URL value: "http://localhost" name: llama-stack port: 8321 distribution: image: quay.io/opendatahub/llama-stack:odh storage: size: "5Gi"
-
Click Create.
-
In the left-hand navigation, click Workloads → Pods and then verify that the LlamaStack pod is running in the correct namespace.
-
To verify that the LlamaStack server is running, click the pod name and select the Logs tab. Look for output similar to the following:
INFO 2025-05-15 11:23:52,750 __main__:498 server: Listening on ['::', '0.0.0.0']:8321 INFO: Started server process [1] INFO: Waiting for application startup. INFO 2025-05-15 11:23:52,765 __main__:151 server: Starting up INFO: Application startup complete. INFO: Uvicorn running on http://['::', '0.0.0.0']:8321 (Press CTRL+C to quit)
-
Confirm that a Service resource for the LlamaStack backend is present in your namespace and points to the running pod. You can check this by clicking Networking → Services in the web console.
Ingesting content into a Llama model
You can quickly customize and prototype your retrievable content by ingesting raw text into your model from inside a Jupyter notebook. This approach voids requiring a separate ingestion pipeline. By using the LlamaStack SDK, you can embed and store text in your vector store in real-time, enabling immediate RAG workflows.
-
You have deployed a Llama 3.2 model with a vLLM model server and you have integrated LlamaStack.
-
You have created a project workbench within a data science project.
-
You have opened a Jupyter notebook and it is running in your workbench environment.
-
You have a created and configured a vector database instance and you know its identifier.
-
In a new notebook cell, install the
llama_stack
client package:%pip install llama_stack
-
In a new notebook cell, import RAGDocument and LlamaStackClient:
from llama_stack_client import RAGDocument, LlamaStackClient
-
In a new notebook cell, assign your deployment endpoint to the
base_url
parameter to create a LlamaStackClient instance:client = LlamaStackClient(base_url="<your deployment endpoint>")
-
List the available models:
# Fetch all registered models models = client.models.list()
-
Verify that the list of registered models includes your Llama model and an embedding model. Here is an example of a list of registered models:
[Model(identifier='llama-32-3b-instruct', metadata={}, api_model_type='llm', provider_id='vllm-inference', provider_resource_id='llama-32-3b-instruct', type='model', model_type='llm'), Model(identifier='ibm-granite/granite-embedding-125m-english', metadata={'embedding_dimension': 768.0}, api_model_type='embedding', provider_id='sentence-transformers', provider_resource_id='ibm-granite/granite-embedding-125m-english', type='model', model_type='embedding')]
-
Select the first LLM and the first embedding model:
model_id = next(m.identifier for m in models if m.model_type == "llm") embedding_model = next(m for m in models if m.model_type == "embedding") embedding_model_id = embedding_model.identifier embedding_dimension = embedding_model.metadata["embedding_dimension"]
-
In a new notebook cell, define the following parameters:
-
vector_db_id
: a unique name that identifies your vector database, for example,my_milvus_db
. -
provider_id
: the connector key that your Llama Stack gateway has enabled. For the Milvus vector database, this connector key is"milvus"
. You can also list the available connectors:print(client.vector_dbs.list_providers()) # lists available connectors vector_db_id = "<your vector database ID>" provider_id = "<your provider ID>"
-
-
In a new notebook cell, register or confirm your vector database to store embeddings:
_ = client.vector_dbs.register( vector_db_id=vector_db_id, embedding_model=embedding_model_id, embedding_dimension=embedding_dimension, provider_id=provider_id, ) print(f"Registered vector DB: {vector_db_id}")
ImportantIf you skip this step, and as a result, you do not register your vector database with your vector database ID, an error occurs if you attempt to ingest text into your vector database.
-
In a new notebook cell, define the raw text that you want to ingest into the vector store:
# Example raw text passage raw_text = """ LlamaStack can embed raw text into a vector store for retrieval. This example ingests a small passage for demonstration. """
-
In a new notebook cell, create a RAGDocument object to contain the raw text:
document = RAGDocument( document_id="raw_text_001", content=raw_text, mime_type="text/plain", metadata={"source": "example_passage"}, )
-
In a new notebook cell, ingest the raw text:
client.tool_runtime.rag_tool.insert( documents=[document], vector_db_id=vector_db_id, chunk_size_in_tokens=100, ) print("Raw text ingested successfully")
-
In a new notebook cell, create a RAGDocument from an HTML source and ingest it into the vector store:
source = "https://www.paulgraham.com/greatwork.html" print("rag_tool> Ingesting document:", source) document = RAGDocument( document_id="document_1", content=source, mime_type="text/html", metadata={}, )
-
In a new notebook cell, ingest the content into the vector store:
client.tool_runtime.rag_tool.insert( documents=[document], vector_db_id=vector_db_id, chunk_size_in_tokens=50, ) print("Raw text ingested successfully")
-
Review the output to confirm successful ingestion. A typical response after ingestion includes the number of text chunks inserted and any warnings or errors.
-
The model list returned by
client.models.list()
includes your Llama 3.2 model and an embedding model.
Querying ingested content in a Llama model
You can use the LlamaStack SDK in your Jupyter notebook to query ingested content by running retrieval-augmented generation (RAG) queries on raw text or HTML sources stored in your vector database. When you query the ingested content, you can perform one-off lookups or start multi-turn conversational flows without setting up a separate retrieval service.
-
You have enabled GPU support. This includes installing the Node Feature Discovery and NVIDIA GPU Operators. For more information, see NVIDIA GPU Operator on Red Hat OpenShift Container Platform in the NVIDIA documentation.
-
If you are using GPU acceleration, you have at least one NVIDIA GPU available.
-
You have logged in to OpenShift Container Platform web console.
-
You have activated the Llama Stack Operator in Open Data Hub.
-
You have deployed an inference model, for example, the llama-3.2-3b-instruct model.
-
You have configured a Llama Stack deployment by creating a
LlamaStackDistribution
instance to enable RAG functionality. -
You have created a project workbench within a data science project.
-
You have opened a Jupyter notebook and it is running in your workbench environment.
-
You have ingested content into your model.
Note
|
This procedure does not require any specific type of content. It only requires that you have already ingested some text, HTML, or document data into your vector database, and that this content is available for retrieval. If you have previously ingested content, that content will be available to query. If you have not ingested any content yet, the queries in this procedure will return empty results or errors. |
-
In a new notebook cell, install the
llama_stack
client package:%pip install llama_stack_client
-
In a new notebook cell, import
Agent
,AgentEventLogger
, andLlamaStackClient
:from llama_stack_client import Agent, AgentEventLogger, LlamaStackClient
-
In a new notebook cell, assign your deployment endpoint to the
base_url
parameter to create aLlamaStackClient
instance. For example:client = LlamaStackClient(base_url="http://lsd-llama-milvus-service:8321/")
-
In a new notebook cell, list the available models:
models = client.models.list()
-
Verify that the list of registered models includes your Llama model and an embedding model. Here is an example of a list of registered models:
[Model(identifier='llama-32-3b-instruct', metadata={}, api_model_type='llm', provider_id='vllm-inference', provider_resource_id='llama-32-3b-instruct', type='model', model_type='llm'), Model(identifier='ibm-granite/granite-embedding-125m-english', metadata={'embedding_dimension': 768.0}, api_model_type='embedding', provider_id='sentence-transformers', provider_resource_id='ibm-granite/granite-embedding-125m-english', type='model', model_type='embedding')]
-
In a new notebook cell, select the first LLM in your list of registered models:
model_id = next(m.identifier for m in models if m.model_type == "llm")
-
In a new notebook cell, define the
vector_db_id
, which is a unique name that identifies your vector database, for example,my_milvus_db
. If you do not know your vector database ID, contact an administrator.vector_db_id = "<your vector database ID>"
-
In a new notebook cell, query the ingested content using the low-level RAG tool:
# Example RAG query for one-off lookups query = "What benefits do the ingested passages provide for retrieval?" result = client.tool_runtime.rag_tool.query( vector_db_ids=[vector_db_id], content=query, ) print("Low-level query result:", result)
-
In a new notebook cell, query the ingested content by using the high-level Agent API:
# Create an Agent for conversational RAG queries agent = Agent( client, model=model_id, instructions="You are a helpful assistant.", tools=[ { "name": "builtin::rag/knowledge_search", "args": {"vector_db_ids": [vector_db_id]}, } ], ) prompt = "How do you do great work?" print("Prompt>", prompt) # Create a session and run a streaming turn session_id = agent.create_session("rag_session") response = agent.create_turn( messages=[{"role": "user", "content": prompt}], session_id=session_id, stream=True, ) # Log and print the agent's response for log in AgentEventLogger().log(response): log.print()
-
The notebook prints query results for both the low-level RAG tool and the high-level Agent API.
-
No errors appear in the output, confirming the model can retrieve and respond to ingested content.
Preparing documents with Docling for Llama Stack retrieval
You can transform your source documents with a Docling-enabled data science pipeline and ingest the output into a Llama Stack vector store by using the Llama Stack SDK. This modular approach separates document preparation from ingestion, yet still delivers an end-to-end, retrieval-augmented generation (RAG) workflow.
The pipeline registers a Milvus vector database and downloads the source PDFs, then splits them for parallel processing and converts each batch to Markdown with Docling. It generates sentence-transformer embeddings from the Markdown and stores them in the vector store, making the documents instantly searchable in Llama Stack.
-
You have enabled GPU support. This includes installing the Node Feature Discovery and NVIDIA GPU Operators. For more information, see NVIDIA GPU Operator on Red Hat OpenShift Container Platform in the NVIDIA documentation.
-
You have logged in to OpenShift Container Platform web console.
-
You have a data science project and access to pipelines in the Open Data Hub dashboard.
-
You have created and configured a pipeline server within the data science project that contains your workbench.
-
You have activated the Llama Stack Operator in Open Data Hub.
-
You have deployed an inference model, for example, the llama-3.2-3b-instruct model.
-
You have configured a Llama Stack deployment by creating a
LlamaStackDistribution
instance to enable RAG functionality. -
You have created a project workbench within a data science project.
-
You have opened a Jupyter notebook and it is running in your workbench environment.
-
You have installed local object storage buckets and created connections, as described in Adding a connection to your data science project.
-
You have compiled to YAML a data science pipeline that includes a Docling transform, either one of the RAG demo samples or your own custom pipeline.
-
Your data science project quota allows between 500 millicores (0.5 CPU) and 4 CPU cores for the pipeline run.
-
Your data science project quota allows from 2 GiB up to 6 GiB of RAM for the pipeline run.
-
If you are using GPU acceleration, you have at least one NVIDIA GPU available.
-
In a new notebook cell, install the
llama_stack
client package:%pip install llama_stack_client
-
In a new notebook cell, import Agent, AgentEventLogger, and LlamaStackClient:
from llama_stack_client import Agent, AgentEventLogger, LlamaStackClient
-
In a new notebook cell, assign your deployment endpoint to the
base_url
parameter to create a LlamaStackClient instance:client = LlamaStackClient(base_url="<your deployment endpoint>")
-
List the available models:
models = client.models.list()
-
Select the first LLM and the first embedding model:
model_id = next(m.identifier for m in models if m.model_type == "llm") embedding_model = next(m for m in models if m.model_type == "embedding") embedding_model_id = embedding_model.identifier embedding_dimension = embedding_model.metadata["embedding_dimension"]
-
In a new notebook cell, define the following parameters:
-
vector_db_id
: a unique name that identifies your vector database, for example,my_milvus_db
. -
provider_id
: the connector key that your Llama Stack gateway has enabled. For the Milvus vector database, this connector key is"milvus"
. You can also list the available connectors:print(client.vector_dbs.list_providers()) # lists available connectors vector_db_id = "<your vector database ID>" provider_id = "<your provider ID>"
ImportantIf you are using the sample Docling pipeline from the RAG demo repository, the pipeline registers the database automatically and you can skip this step. However, if you are using your own pipeline, you must register the database yourself.
-
-
In a new notebook cell, register or confirm your vector database to store embeddings:
_ = client.vector_dbs.register( vector_db_id=vector_db_id, embedding_model=embedding_model_id, embedding_dimension=embedding_dimension, provider_id=provider_id, ) print(f"Registered vector DB: {vector_db_id}")
-
In the OpenShift Container Platform web console, import your YAML file containing your docling pipeline into your data science project, as described in Importing a pipeline version.
-
Create a pipeline run to execute your Docling pipeline, as described in Executing a pipeline run. The pipeline run inserts your PDF documents into the vector database. If you run the Docling pipeline from the RAG demo samples repository, you can optionally customize the following parameters before starting the pipeline run:
-
base_url
: The base URL to fetch PDF files from. -
pdf_filenames
: A comma-separated list of PDF filenames to download and convert. -
num_workers
: The number of parallel workers. -
vector_db_id
: The Milvus vector database ID. -
service_url
: The Milvus service URL. -
embed_model_id
: The embedding model to use. -
max_tokens
: The maximum tokens for each chunk. -
use_gpu
: Enable or disable GPU acceleration.
-
-
In your Jupyter notebook, query the LLM with a question that relates to the ingested content. For example:
from llama_stack_client import Agent, AgentEventLogger import uuid rag_agent = Agent( client, model=model_id, instructions="You are a helpful assistant", tools=[ { "name": "builtin::rag/knowledge_search", "args": {"vector_db_ids": [vector_db_id]}, } ], ) prompt = "What can you tell me about the birth of word processing?" print("prompt>", prompt) session_id = rag_agent.create_session(session_name=f"s{uuid.uuid4().hex}") response = rag_agent.create_turn( messages=[{"role": "user", "content": prompt}], session_id=session_id, stream=True, ) for log in AgentEventLogger().log(response): log.print()
-
Query chunks from the vector database:
query_result = client.vector_io.query( vector_db_id=vector_db_id, query="what do you know about?", ) print(query_result)
About Llama stack search types
Llama Stack supports keyword, vector, and hybrid search modes for retrieving context in retrieval-augmented generation (RAG) workloads. Each mode offers different tradeoffs in precision, recall, semantic depth, and computational cost.
Supported search modes
Keyword search
Keyword search applies lexical matching techniques, such as TF-IDF or BM25, to locate documents that contain exact or near-exact query terms. This approach is effective when precise term-matching is critical and remains widely used in information-retrieval systems. For more information, see The Probabilistic Relevance Framework: BM25 and Beyond.
Vector search
Vector search encodes documents and queries as dense numerical vectors, known as embeddings, and measures similarity with metrics such as cosine similarity or inner product. This approach captures contextual meaning and supports semantic matching beyond exact word overlap. For more information, see Billion-scale similarity search with GPUs.
Hybrid search
Hybrid search blends keyword and vector techniques, typically by combining individual scores with a weighted sum or methods, such as Reciprocal Rank Fusion (RRF). This approach returns results that balance exact matches with semantic relevance. For more information, see Sparse, Dense, and Hybrid Retrieval for Answer Ranking.
Retrieval database support
Milvus is the supported retrieval database for Llama Stack. It currently provides vector search. However, keyword and hybrid search capabilities are not currently supported.