Procedure

1. Create an opaque Kubernetes Secret containing your operational credentials and query validation keys before applying the Backstage CR. Refer to the following key definitions for required environment variables:

   Important

   The Secret supplies only provider credentials and endpoints. To enable an inference provider, define it as an entry under the inference.providers section of the lightspeed-stack.yaml file. Adding a credential key to the Secret does not enable a provider on its own.

   Key	Description
   VLLM_URL	Specifies the target API endpoint URL for vLLM. The URL must end in /v1, for example, https://<api_endpoint>/v1.
   VLLM_API_KEY	Stores the authorization token for your vLLM platform.
   OPENAI_API_KEY	Stores the authorization secret key for OpenAI.
   VERTEX_AI_PROJECT	Specifies your Google Cloud project ID.
   VERTEX_AI_LOCATION	Specifies your target Google Cloud region.
   GOOGLE_APPLICATION_CREDENTIALS	Specifies the in-container file path of your mounted Google Cloud service account credentials JSON file.
   ENABLE_VALIDATION	Enables the question-validity shield when set to question_validity. Leave the variable unset, or set it to disabled, to keep validation disabled. A nonempty value such as true does not enable the shield.
   VALIDATION_PROVIDER	Specifies the type of the inference provider that runs the classification, for example, openai or vllm. A provider of this type must be enabled in inference.providers.
   VALIDATION_MODEL_NAME	Specifies the model that classifies each prompt, for example, gpt-4o-mini.

   The following code shows an example configuration Secret for vLLM with validation:

   apiVersion: v1
   kind: Secret
   metadata:
     name: intelligent-assistant-auth-secrets
   type: Opaque
   stringData:
     VLLM_URL: "https://<api_endpoint>/v1"
     VLLM_API_KEY: "<api_key>"
     ENABLE_VALIDATION: question_validity
     VALIDATION_PROVIDER: "vllm"
     VALIDATION_MODEL_NAME: "llama3.1"

   Note

   The VALIDATION_PROVIDER value is the inference provider type, such as vllm or openai. A provider of this type must be enabled in the inference.providers section of the lightspeed-stack.yaml file.

2. Enable at least one inference provider by defining it under the inference.providers section of the lightspeed-stack.yaml file. Creating the Secret alone does not enable a provider. For the provider entry format and the Secret keys that each provider requires, see the inference provider configuration reference for Developer Hub Intelligent Assistant.

3. Map your secret inside the extraEnvs section of the Backstage CR to complete container provisioning:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: intelligent-assistant-rhdh
   spec:
     application:
       extraEnvs:
         secrets:
           - name: intelligent-assistant-auth-secrets
             containers:
               - lightspeed-core

4. Optional: To protect settings such as Model Context Protocol (MCP) server additions from being overwritten during reconciliation loops, define a custom ConfigMap mapping in the extraFiles section of the CR:

       extraFiles:
         configMaps:
           - name: "my-custom-config"
             mountPath: /app-root
             key: lightspeed-stack.yaml
             containers:
               - lightspeed-core

5. Configure access rights by updating the RBAC policy inside your Backstage CR:

   To grant non-administrator teams access to the virtual assistant, append permission lines to the rbac-policies.csv section, replacing <team> with your target team name:

   p, role:default/<team>, intelligent-assistant.chat, use, allow 1

   <1>

   Grants full use of the Developer Hub Intelligent Assistant chat feature, including opening the chat window, sending messages, managing chat history, and saving and reusing chat prompts.

   For the complete list of AI feature permissions, including Notebooks, MCP tools, and skills, see AI feature permissions.

6. Apply the updated custom resource manifest to your cluster:

   $ oc apply -f <backstage_cr_file>.yaml

Verification

1. Log in to your console instance.
2. Verify that the Intelligent Assistant button appears on the home page.
3. Select the Intelligent Assistant button and confirm that the chat window initializes successfully.

Procedure

1. Create a Kubernetes Secret to store your provider credentials by adding the required keys to your Secret based on your provider requirements:

   Important

   The Secret supplies only provider credentials and endpoints. To enable an inference provider, define it as an entry under the inference.providers section of the lightspeed-stack.yaml file. Adding a credential key to the Secret does not enable a provider on its own.

   Key	Description
   VLLM_URL	Specifies the target API endpoint URL for vLLM. The URL must end in /v1, for example, https://<api_endpoint>/v1.
   VLLM_API_KEY	Stores the authorization token for your vLLM platform.
   OPENAI_API_KEY	Stores the authorization secret key for OpenAI.
   VERTEX_AI_PROJECT	Specifies your Google Cloud project ID.
   VERTEX_AI_LOCATION	Specifies your target Google Cloud region.
   GOOGLE_APPLICATION_CREDENTIALS	Specifies the in-container file path of your mounted Google Cloud service account credentials JSON file.
   ENABLE_VALIDATION	Enables the question-validity shield when set to question_validity. Leave the variable unset, or set it to disabled, to keep validation disabled. A nonempty value such as true does not enable the shield.
   VALIDATION_PROVIDER	Specifies the type of the inference provider that runs the classification, for example, openai or vllm. A provider of this type must be enabled in inference.providers.
   VALIDATION_MODEL_NAME	Specifies the model that classifies each prompt, for example, gpt-4o-mini.

   Note

   Vertex AI requires custom architecture mapping and has received limited testing.

   Tip

   To filter and reject off-topic user queries, you can optionally configure query validation within this Secret by defining the ENABLE_VALIDATION, VALIDATION_PROVIDER, and VALIDATION_MODEL_NAME keys.

2. Reference your Secret inside the values.yaml file:

   intelligentAssistant:
     existingSecret: "my-custom-secret"

3. Enable at least one inference provider by defining it under the inference.providers section of the lightspeed-stack.yaml file. Creating the Secret alone does not enable a provider. For the provider entry format and the Secret keys that each provider requires, see the inference provider configuration reference for Developer Hub Intelligent Assistant.

4. Optional: Configuration files such as lightspeed-stack.yaml and rhdh-profile.py are managed by the Helm deployment and are overwritten on helm upgrade runs. To protect changes to a file, create a custom config map and reference it in the values.yaml file:

   Important

   Provide only the name and key of your existing ConfigMap. The chart manages the mount path and file configuration.

   intelligentAssistant:
     config:
       stack:
         existingConfigMap:
           name: my-custom-stack
           key: lightspeed-stack.yaml

5. Configure access rights by updating your RBAC definitions:

   To grant non-administrator teams access to the virtual assistant, append permission lines to the rbac-policies.csv section, replacing <team> with your target team name:

   p, role:default/<team>, intelligent-assistant.chat, use, allow 1

   <1>

   Grants full use of the Developer Hub Intelligent Assistant chat feature, including opening the chat window, sending messages, managing chat history, and saving and reusing chat prompts.

   For the complete list of AI feature permissions, including Notebooks, MCP tools, and skills, see AI feature permissions.

6. Run the helm upgrade command to apply your configurations to the cluster.

Verification

1. Log in to your console instance.
2. Verify that the Intelligent Assistant button appears on the home page.
3. Select the Intelligent Assistant button and confirm that the chat window initializes successfully.

Procedure

1. Open your Backstage custom resource (CR) YAML file.

2. In the spec section, set the enabled flag to false for the intelligent-assistant flavour. This disables the chat interface and prevents the Operator from injecting unconfigured sidecar containers:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: intelligent-assistant-disabled
   spec:
     flavours:
       - name: intelligent-assistant
         enabled: false

3. Apply the updated custom resource manifest to your cluster:

   oc apply -f <backstage_cr_file>.yaml

Verification

1. Log in to your console instance.
2. Verify that the Intelligent Assistant button no longer appears on the home page.

Procedure

1. Open your Helm values.yaml file.

2. Update the global.lightspeed.enabled parameter to false to disable the chat interface:

   global:
     lightspeed:
       enabled: false

3. Run the helm upgrade command to apply the configuration change to your cluster.

Verification

1. Log in to your console instance.
2. Verify that the Intelligent Assistant button no longer appears on the home page.

Procedure

1. Record the installed RHDH and Developer Hub Intelligent Assistant versions.
2. Back up your 1.10 Helm values or your Backstage custom resource (CR).
3. Export your customer-managed ConfigMaps, Secrets, app-config files, dynamic plugin configuration, role-based access control (RBAC) policies, Routes, Services, and persistent volume claims.
4. Record the Developer Hub Intelligent Assistant settings that you must reapply in 2.1: enabled inference providers and their model names, Model Context Protocol (MCP) server endpoints, query validation behavior, feedback and chat history storage settings, and prompt customizations and storage requirements.
5. Store credentials through your approved secret-management process. Do not add decoded Secret values to your migration workspace.

Verification

1. Confirm that you have a stored copy of your 1.10 Helm values or Backstage CR.
2. Confirm that you have a recorded list of the Developer Hub Intelligent Assistant settings that you must reapply in 2.1.
3. Confirm that your 1.10 deployment remains available for rollback.

Procedure

1. Keep the shipped runtime baseline:

   llama_stack:
     use_as_library_client: true
     config:
       baseline: byo-llm

   Do not point library_client_config_path at a config.yaml file, and do not carry a config.yaml file forward.

2. Re-create each enabled inference provider as an explicit entry under inference.providers. Give each provider a unique id, keep the sentence_transformers provider, and reference credentials through the Secret:

   inference:
     providers:
       - type: sentence_transformers
       - type: openai
         id: openai-primary
         api_key_env: OPENAI_API_KEY

   Note

   Replace the ENABLE_OPENAI, ENABLE_VLLM, ENABLE_VERTEX_AI, and ENABLE_OLLAMA switches with provider entries. Adding a Secret key alone does not enable a provider.

   For the configuration schema and Secret keys for each supported provider, see Inference provider configuration reference for Developer Hub Intelligent Assistant.

3. Keep the supplied vector_store section unless you customized vector storage in 1.10. Do not copy the old providers.vector_io or registered_resources.vector_stores blocks.

   Important

   Keeping the supplied configuration does not migrate existing vector data. If users must retain indexed notebook content, verify the source and destination volumes and plan the data movement separately.

4. Enable query validation. To use the validation that ships by default with 2.1, set ENABLE_VALIDATION to question_validity in the Secret. If you supplied a custom validation prompt in 1.10, reapply it to the prompt block under the top-level shields block in the shipped lightspeed-stack.yaml file. For more information, see Enable query validation to block off-topic AI responses.
5. Keep your existing top-level mcp_servers entries. The schema is unchanged from 1.10. Do not copy the internal tool_runtime provider from the old config.yaml file.
6. Leave every other section in the shipped 2.1 file unchanged. If you customized feedback collection, the conversation cache, authentication, or the prompt profile in 1.10, reapply only the values that you still need instead of replacing the whole section.
7. Complete the migration for your deployment method. For a Helm deployment, see Complete the Developer Hub Intelligent Assistant migration by using the Helm chart. For an Operator deployment, see Complete the Developer Hub Intelligent Assistant migration by using the Operator.

Procedure

1. Move your global.lightspeed.* customizations to the matching root intelligentAssistant.* keys.
2. Do not migrate the 1.10 name: server ConfigMap entry. The 2.1 chart provides only stack and profile entries.
3. Create the provider Secret, and then reference it by setting intelligentAssistant.existingSecret. For the credential and endpoint keys to include in the Secret, see Configure Developer Hub Intelligent Assistant by using the Helm chart.

4. If you customized the shipped configuration file, supply your unified stack ConfigMap through the intelligentAssistant.config.stack.existingConfigMap value:

   intelligentAssistant:
     existingSecret: intelligent-assistant-auth-secrets
     config:
       stack:
         existingConfigMap:
           name: my-lightspeed-stack
           key: lightspeed-stack.yaml

5. Install a fresh redhat-developer-hub 2.1 chart release. Do not run helm upgrade against the 1.x backstage release.

Procedure

1. Change any explicit lightspeed flavor name to intelligent-assistant.

2. Create the provider Secret, and inject it into the lightspeed-core container through the spec.application.extraEnvs.secrets section of the Backstage CR. For the credential and endpoint keys to include in the Secret, see Configure Developer Hub Intelligent Assistant by using the Operator.

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: intelligent-assistant-rhdh
   spec:
     application:
       extraEnvs:
         secrets:
           - name: intelligent-assistant-auth-secrets
             containers:
               - lightspeed-core

3. If you customized the shipped configuration file, create a unified lightspeed-stack.yaml ConfigMap, and mount it at /app-root in the lightspeed-core container through the spec.application.extraFiles.configMaps section:

       extraFiles:
         configMaps:
           - name: my-custom-lightspeed-stack
             mountPath: /app-root
             key: lightspeed-stack.yaml
             containers:
               - lightspeed-core

4. Do not carry a custom llama-stack-config mount or a config.yaml reference into the 2.1 CR.
5. Keep the flavor-managed rhdh-profile.py file unless you maintain a custom prompt profile.

6. Apply the updated custom resource:

   $ oc apply -f <backstage_cr_file>.yaml

Procedure

1. Confirm that the RHDH pod is ready and has the lightspeed-core container:

   $ oc get pods -n <namespace>

2. Confirm that /app-root/lightspeed-stack.yaml comes from the intended ConfigMap and that the pod has no /app-root/config.yaml mount.

3. Review the lightspeed-core logs for configuration, provider, credential, model, vector-store, and Model Context Protocol (MCP) connection errors. Do not print Secret values:

   $ oc logs -n <namespace> deployment/<deployment_name> -c lightspeed-core

4. Open the Intelligent Assistant and submit a development question to confirm that each enabled provider and allowed model responds.
5. If query validation is enabled, submit one development question and one unrelated question to confirm the expected results.
6. Test any required MCP tools, and confirm feedback and notebook behavior when those features are enabled.
7. Restart the pod and confirm the expected persistence behavior for feedback, cache, and vector data.

Procedure

1. Create a directory for the documents that you want the assistant to search. For example:

   custom_docs/
     installation-guide.md
     operations-guide.md

   Use clear headings and ordinary text wherever possible. Text embedded only in screenshots or scanned PDF pages must be converted with optical character recognition before it can be indexed reliably.

2. Process one document type per generation run and set --doc-type accordingly. This example uses markdown.

3. For Markdown content, add YAML frontmatter to identify the document and its canonical source URL:

   ---
   title: Example Operations Guide
   url: https://docs.example.com/operations-guide
   ---
   
   # Example Operations Guide
   
   Document content begins here.

   The metadata is stored with each generated chunk. Intelligent Assistant can use the title and URL when presenting retrieval sources and citations.

   Important

   Do not include secrets, credentials, personal data, or content that users of the assistant are not authorized to retrieve. Access controls on the source system are not automatically reproduced inside a vector store.

Procedure

1. Clone the rag-content repository and install its pinned dependencies:

   $ git clone https://github.com/lightspeed-core/rag-content.git
   $ cd rag-content
   $ uv sync

   Tip

   Use a specific release or commit in repeatable production workflows. The generator, query helper, and runtime dependencies must be kept compatible.

2. From the rag-content repository, generate a portable OGX FAISS vector store:

   $ uv run python scripts/generate_embeddings.py \
     --folder /path/to/custom_docs \
     --output /path/to/vector_db/custom_docs \
     --index custom-docs \
     --vector-store llamastack-faiss \
     --model-dir "" \
     --model-name sentence-transformers/all-mpnet-base-v2 \
     --doc-type markdown \
     --chunk-size 512 \
     --chunk-overlap 128

   The llamastack-faiss value is retained as a compatibility name in the rag-content command-line interface. Current rag-content releases use OGX to create this store.

   Passing an empty value to --model-dir records the Hugging Face model ID rather than a workstation-specific model path. This makes the generated store portable. At runtime, the same model ID is resolved by the sentence_transformers provider.

   Note

   This model-ID configuration can require network access when the model is not already cached. For a disconnected deployment, package the embedding model and configure its runtime filesystem path as described in Deploy BYOK RAG in a disconnected environment.

3. Confirm the output files. The output directory contains:

   • faiss_store.db: the vector store database required at runtime.
   • lightspeed-stack.yaml: an example Intelligent Assistant configuration generated for the store.
   • llama-stack.yaml: the OGX configuration used to create the store.

4. Read the unique vector store ID from the generated configuration:

   $ yq '.registered_resources.vector_stores[0].vector_store_id' \
     /path/to/vector_db/custom_docs/llama-stack.yaml

   Save this value. The runtime configuration must use the exact same ID.

5. Test retrieval before deployment by using the query helper from the same rag-content checkout:

   $ uv run python scripts/query_rag.py \
     --db-path /path/to/vector_db/custom_docs \
     --product-index custom-docs \
     --model-path "" \
     --top-k 5 \
     --query "Enter a question answered only by the custom documents" \
     --json

   Review the returned chunks, scores, titles, and source URLs. Use a question that contains a distinctive fact from the custom content so that the result is easy to distinguish from general model knowledge.

   Note

   Some combinations of OGX and rag-content can report that the vector store is already registered when query_rag.py opens a newly generated database. Do not edit the SQLite database manually. Use a compatible rag-content revision or continue validation through the deployed Intelligent Assistant vector store API, and report reproducible helper failures to the rag-content project.

Procedure

1. Create a Containerfile in the directory that contains your vector_db output. Use the variant that matches your deployment method:

   For the Operator, or any deployment that adds a dedicated BYOK init container alongside the product init container, use a minimal base image:

   FROM registry.access.redhat.com/ubi9-micro:latest
   COPY vector_db /byok/vector_db
   USER 1001

   For the Helm chart, which exposes a single global.lightspeed.initContainer that you must override, derive the image from the product RAG init image so that the overridden init container can deliver both the product-provided content and your BYOK vector store:

   ARG PRODUCT_RAG_IMAGE
   FROM ${PRODUCT_RAG_IMAGE}
   
   COPY vector_db /byok/vector_db
   USER 1001

   Set PRODUCT_RAG_IMAGE to the value of global.lightspeed.initContainer.image from your installed chart version. The derived image retains the product /rag directory and adds your custom database under /byok/vector_db.

2. Build the image:

   For the minimal UBI-based image:

   $ podman build --platform linux/amd64 \
     -t quay.io/your-organization/rhdh-byok:1.0.0 .

   For the Helm image derived from the product RAG init image, pass an immutable product image reference:

   $ podman build --platform linux/amd64 \
     --build-arg PRODUCT_RAG_IMAGE=<product_rag_image_reference> \
     -t quay.io/your-organization/rhdh-byok-with-product-rag:1.0.0 .

3. Push the image to an approved registry:

   $ podman push quay.io/your-organization/rhdh-byok:1.0.0
   $ podman push quay.io/your-organization/rhdh-byok-with-product-rag:1.0.0

   Important

   Use an immutable version tag or image digest in production. Ensure that the image architecture matches the OpenShift worker architecture.

4. Note the final path visible inside the Intelligent Assistant container. The db_path configuration must match that runtime path exactly. For example, if the database is copied to /rag-content/vector_db/custom_docs/faiss_store.db, use that complete path in the Intelligent Assistant configuration.

Procedure

1. Prepare a complete lightspeed-stack.yaml file with the BYOK sections added, then create a ConfigMap from it:

   Warning

   The mounted file replaces the product-provided lightspeed-stack.yaml in its entirety; it is not merged. If you create the ConfigMap from only the BYOK sections, you remove other supported or required settings, including the service, authentication, cache, user-data and profile, MCP, and other product configuration, and Intelligent Assistant can fail to start or lose required functionality. Always create the ConfigMap from the complete configuration for your RHDH version with the BYOK sections added to it.

   1. Copy or export the complete product-provided lightspeed-stack.yaml for your installed RHDH version to a local file.

   2. Ensure that the sentence_transformers embedding provider is present under inference.providers, then register the store under rag.byok.stores and activate it under rag.retrieval. Add the following fragment to the local file, merging it with the existing sections rather than replacing them:

      inference:
        providers:
          - type: sentence_transformers  # Add only if not already present
      rag:
        byok:
          stores:
            - rag_id: custom-docs
              backend: faiss
              embedding_model: sentence-transformers/all-mpnet-base-v2
              embedding_dimension: 768
              vector_db_id: vs_replace_with_generated_id
              db_path: /rag-content/vector_db/custom_docs/faiss_store.db
              score_multiplier: 1.0  # Used by Inline RAG only
        retrieval:
          tool:
            sources:
              - custom-docs

      rag_id

      The rag_id identifies the retrieval source. Use the same value under rag.retrieval.tool.sources.

      vector_db_id

      Replace with the vector_db_id value that you read from the generated llama-stack.yaml file. The runtime configuration must use the exact same ID.

      db_path

      Must match the path where the init container copies the database inside the Intelligent Assistant container.

      rag_id

      Must match rag_id. If you have other sources, such as product documentation, list each required source under sources.

   3. Create the ConfigMap from the completed local file:

      $ kubectl create configmap lightspeed-stack-byok \
          --from-file=lightspeed-stack.yaml \
          --dry-run=client -o yaml | kubectl apply -f -

2. Update your Helm values.yaml file to reference the custom ConfigMap and override the Intelligent Assistant init container so that it delivers both the product-provided RAG content and your BYOK vector store. The chart mounts the RAG volume (global.lightspeed.ragVolume) automatically into both the init container and the Intelligent Assistant container at /rag-content, so you do not define extra volumes or volume mounts:

   Important

   The global.lightspeed.configMaps value is a Helm list. If you provide only the customized stack entry, you replace the entire default list and remove the config and rhdh-profile entries. Retain every entry from your installed chart version and change only the stack entry to reference lightspeed-stack-byok. The following example shows the minimum entries to retain; match the exact list to your chart version.

   global:
     lightspeed:
       configMaps:
         - name: stack
           create: false
           nameOverride: lightspeed-stack-byok
           mountPath: /app-root/lightspeed-stack.yaml
           subPath: lightspeed-stack.yaml
           sourceFile: lightspeed-stack.yaml
           optional: false
         - name: config
           create: true
           nameOverride: ""
           mountPath: /app-root/config.yaml
           subPath: config.yaml
           sourceFile: config.yaml
           optional: false
         - name: rhdh-profile
           create: true
           nameOverride: ""
           mountPath: /app-root/rhdh-profile.py
           subPath: rhdh-profile.py
           sourceFile: rhdh-profile.py
           optional: false
       initContainer:  1
         image: quay.io/your-organization/rhdh-byok-with-product-rag:1.0.0
         command: ["sh", "-c"]
         args:
           - |
             set -eu
             mkdir -p /tmp/data /rag-content/vector_db
             cp -R --no-preserve=mode,ownership \
               /rag/vector_db/. /rag-content/vector_db/
             cp -R --no-preserve=mode,ownership \
               /rag/embeddings_model /rag-content/
             cp -R --no-preserve=mode,ownership \
               /byok/vector_db/. /rag-content/vector_db/
             mkdir -p /rag-content/vector_db/notebooks
             chmod -R a+rwX \
               /rag-content/embeddings_model /rag-content/vector_db

   Important

   The chart exposes a single global.lightspeed.initContainer. Overriding it replaces the default init container that delivers the product-provided RAG content. The combined image built from the product RAG init image is therefore required so that the overridden init container can deliver both the product-provided content and your BYOK vector store. Give each custom store its own directory under vector_db so that it does not overwrite a product store. Validate the result against your chart version before relying on it in production.

   lightspeed-stack.yaml

   Replace the default lightspeed-stack.yaml ConfigMap with your custom one that contains the BYOK configuration.

   initContainer

   Override the default init container so that it copies both the product-provided content and your BYOK vector database into the automatically mounted /rag-content RAG volume before Intelligent Assistant starts.

3. Run helm upgrade to apply the changes:

   $ helm upgrade <release_name> redhat-developer-hub \
       --repo https://charts.openshift.io/ \
       --version 2.1.0 \
       -f values.yaml

Procedure

1. Prepare a complete lightspeed-stack.yaml file with the BYOK sections added, then create a ConfigMap from it:

   Warning

   The mounted file replaces the product-provided lightspeed-stack.yaml in its entirety; it is not merged. If you create the ConfigMap from only the BYOK sections, you remove other supported or required settings, including the service, authentication, cache, user-data and profile, MCP, and other product configuration, and Intelligent Assistant can fail to start or lose required functionality. Always create the ConfigMap from the complete configuration for your RHDH version with the BYOK sections added to it.

   1. Copy or export the complete product-provided lightspeed-stack.yaml for your installed RHDH version to a local file.

   2. Ensure that the sentence_transformers embedding provider is present under inference.providers, then register the store under rag.byok.stores and activate it under rag.retrieval. Add the following fragment to the local file, merging it with the existing sections rather than replacing them:

      inference:
        providers:
          - type: sentence_transformers  # Add only if not already present
      rag:
        byok:
          stores:
            - rag_id: custom-docs
              backend: faiss
              embedding_model: sentence-transformers/all-mpnet-base-v2
              embedding_dimension: 768
              vector_db_id: vs_replace_with_generated_id
              db_path: /rag-content-byok/vector_db/custom_docs/faiss_store.db
              score_multiplier: 1.0  # Used by Inline RAG only
        retrieval:
          tool:
            sources:
              - custom-docs

      rag_id

      The rag_id identifies the retrieval source. Use the same value under rag.retrieval.tool.sources.

      vector_db_id

      Replace with the vector_db_id value that you read from the generated llama-stack.yaml file. The runtime configuration must use the exact same ID.

      db_path

      Must match the path where the init container copies the database inside the Intelligent Assistant container. This procedure uses the dedicated /rag-content-byok mount path so that the BYOK content does not replace or shadow any existing product-provided RAG content in /rag-content.

      rag_id

      Must match rag_id. If you have other sources, such as product documentation, list each required source under sources.

   3. Create the ConfigMap from the completed local file:

      $ oc create configmap lightspeed-stack-byok \
          --from-file=lightspeed-stack.yaml \
          --dry-run=client -o yaml | oc apply -f -

2. Update your Backstage custom resource (CR) to mount the custom ConfigMap, and use spec.deployment.patch to add the BYOK init container, shared volume, and volume mount. The spec.deployment.patch value is a deployment fragment that the Operator merges with the generated deployment, so the BYOK init container is added alongside any existing init containers, and the dedicated /rag-content-byok mount does not replace or shadow any existing product-provided RAG content:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: intelligent-assistant-rhdh
   spec:
     application:
       extraFiles:
         configMaps:
           - name: "lightspeed-stack-byok"
             mountPath: /app-root
             key: lightspeed-stack.yaml
             containers:
               - lightspeed-core
     deployment:
       patch:
         spec:
           template:
             spec:
               volumes:
                 - name: byok-rag
                   emptyDir: {}
               initContainers:
                 - name: byok-rag-init
                   image: quay.io/<your_organization>/rhdh-byok:1.0.0
                   imagePullPolicy: IfNotPresent
                   command: ["/bin/sh", "-c"]
                   args:
                     - |
                       set -eu
                       mkdir -p /rag-content-byok/vector_db
                       cp -R /byok/vector_db/. /rag-content-byok/vector_db/
                   volumeMounts:
                     - name: byok-rag
                       mountPath: /rag-content-byok
                   securityContext:
                     allowPrivilegeEscalation: false
                     readOnlyRootFilesystem: true
                     runAsNonRoot: true
                     capabilities:
                       drop: ["ALL"]
                     seccompProfile:
                       type: RuntimeDefault
               containers:
                 - name: lightspeed-core
                   volumeMounts:
                     - name: byok-rag
                       mountPath: /rag-content-byok

   ConfigMap

   References the ConfigMap created in the previous step. This replaces the default lightspeed-stack.yaml for the lightspeed-core container.

   initContainer

   The init container runs before Intelligent Assistant starts and copies the vector database to the shared byok-rag volume. The dedicated /rag-content-byok mount path does not replace or shadow any existing product-provided RAG content.

3. Apply the updated Backstage CR:

   $ oc apply -f <backstage_cr_file>.yaml

Procedure

1. On a connected build workstation, download the embedding model:

   $ mkdir -p embeddings_model
   
   $ uv run python scripts/download_embeddings_model.py \
     --local-dir ./embeddings_model \
     --hf-repo-id sentence-transformers/all-mpnet-base-v2

   The resulting directory includes the model weights, tokenizer, configuration, pooling, and normalization files needed by the sentence_transformers provider. Scan and transfer this directory according to your organization’s disconnected-content process.

   Note

   If the vector store is generated in a disconnected build environment, pass the local directory to --model-dir instead of an empty value. In either case, use the exact same model weights for generation and runtime. Changing the model requires regenerating the vector store.

2. Place the generated vector_db directory and downloaded embeddings_model directory in the container build context:

   byok-image/
     Containerfile
     vector_db/
       custom_docs/
         faiss_store.db
     embeddings_model/
       model.safetensors
       config.json
       tokenizer.json
       ...

3. Create an init-container image that contains both artifacts:

   FROM registry.access.redhat.com/ubi9/ubi-minimal:latest
   
   COPY vector_db /byok/vector_db
   COPY embeddings_model /byok/embeddings_model
   
   RUN chgrp -R 0 /byok && chmod -R g=u /byok
   USER 1001

   Important

   Pin the base image and resulting BYOK image by digest in production. The image reference is part of the Kubernetes deployment configuration. It is not an alternative value for db_path or embedding_model in the Intelligent Assistant BYOK configuration; those fields must identify paths visible inside the Intelligent Assistant container.

4. Build the image on a connected system, scan it, and mirror it into a registry available to the disconnected OpenShift cluster:

   $ podman build -t registry.example.com/rhdh/byok-content:1.0.0 .
   $ podman push registry.example.com/rhdh/byok-content:1.0.0

5. Deliver the artifacts to the Intelligent Assistant runtime and configure offline operation. The supported customization paths differ for the Helm chart and the Operator, so use the variant that matches your RHDH installation.

   Helm chart

   Because the chart exposes a single global.lightspeed.initContainer, derive a combined image from the product RAG init image that also includes your custom vector database and local embedding model. Use a Containerfile such as:

   ARG PRODUCT_RAG_IMAGE
   FROM ${PRODUCT_RAG_IMAGE}
   
   COPY vector_db /byok/vector_db
   COPY embeddings_model /byok/embeddings_model
   USER 1001

   Build the combined image, passing the product RAG init image as the PRODUCT_RAG_IMAGE build argument, and push it to a registry available to the disconnected OpenShift cluster:

   $ podman build \
       --build-arg PRODUCT_RAG_IMAGE=<product_rag_image_reference> \
       -t registry.example.com/rhdh/byok-with-product-rag:1.0.0 .
   
   $ podman push registry.example.com/rhdh/byok-with-product-rag:1.0.0

   Override the single global.lightspeed.initContainer so that it copies the product content, your BYOK database, and the local model into the automatically mounted /rag-content volume, and set the offline environment variables under global.lightspeed.sidecar.env:

   global:
     lightspeed:
       sidecar:
         env:
           - name: HF_HUB_OFFLINE
             value: "1"
           - name: TRANSFORMERS_OFFLINE
             value: "1"
       initContainer:
         image: registry.example.com/rhdh/byok-with-product-rag:1.0.0
         command: ["sh", "-c"]
         args:
           - |
             set -eu
             mkdir -p /rag-content/vector_db
             cp -R --no-preserve=mode,ownership \
               /rag/vector_db/. /rag-content/vector_db/
             cp -R --no-preserve=mode,ownership \
               /byok/vector_db/. /rag-content/vector_db/
             cp -R --no-preserve=mode,ownership \
               /byok/embeddings_model /rag-content/embeddings_model
             chmod -R a+rwX \
               /rag-content/embeddings_model /rag-content/vector_db

   Operator

   Use spec.deployment.patch to add the byok-rag volume and the BYOK init container, mount the volume at /rag-content-byok in both the init container and lightspeed-core, copy both artifacts into it, and add the offline environment variables to lightspeed-core:

   spec:
     deployment:
       patch:
         spec:
           template:
             spec:
               volumes:
                 - name: byok-rag
                   emptyDir: {}
               initContainers:
                 - name: byok-rag-init
                   image: registry.example.com/rhdh/byok-content@sha256:replace_with_digest
                   imagePullPolicy: IfNotPresent
                   command: ["/bin/sh", "-c"]
                   args:
                     - |
                       set -eu
                       mkdir -p /rag-content-byok/vector_db /rag-content-byok/embeddings_model
                       cp -R /byok/vector_db/. /rag-content-byok/vector_db/
                       cp -R /byok/embeddings_model/. /rag-content-byok/embeddings_model/
                   volumeMounts:
                     - name: byok-rag
                       mountPath: /rag-content-byok
                   securityContext:
                     allowPrivilegeEscalation: false
                     readOnlyRootFilesystem: true
                     runAsNonRoot: true
                     capabilities:
                       drop: ["ALL"]
                     seccompProfile:
                       type: RuntimeDefault
               containers:
                 - name: lightspeed-core
                   env:
                     - name: HF_HUB_OFFLINE
                       value: "1"
                     - name: TRANSFORMERS_OFFLINE
                       value: "1"
                   volumeMounts:
                     - name: byok-rag
                       mountPath: /rag-content-byok

   Kubernetes init containers run before application containers, so the model and database are present when Intelligent Assistant starts.

   Note

   If several init containers populate the same volume, give each vector store a unique directory and ensure that later containers merge content instead of replacing the entire vector_db directory.

6. Register the disconnected store with local runtime paths that match your deployment method:

   For the Helm chart:

   rag:
     byok:
       stores:
         - rag_id: custom-docs
           backend: faiss
           embedding_model: /rag-content/embeddings_model
           embedding_dimension: 768
           vector_db_id: vs_replace_with_generated_id
           db_path: /rag-content/vector_db/custom_docs/faiss_store.db
           score_multiplier: 1.0
     retrieval:
       tool:
         sources:
           - custom-docs

   For the Operator:

   rag:
     byok:
       stores:
         - rag_id: custom-docs
           backend: faiss
           embedding_model: /rag-content-byok/embeddings_model
           embedding_dimension: 768
           vector_db_id: vs_replace_with_generated_id
           db_path: /rag-content-byok/vector_db/custom_docs/faiss_store.db
           score_multiplier: 1.0
     retrieval:
       tool:
         sources:
           - custom-docs

   embedding_model

   Using the local path prevents the sentence_transformers provider from attempting to resolve sentence-transformers/all-mpnet-base-v2 from Hugging Face when the pod starts or processes its first query.

   Verification

   • Verify the deployed vector store

Procedure

1. Verify the following conditions after deployment:

   1. The init container or file-delivery process completes successfully.
   2. The Intelligent Assistant container can read the configured faiss_store.db path.
   3. For a disconnected deployment that uses a local embedding model, the Intelligent Assistant container can read the local embedding model files, including model.safetensors, the tokenizer, and model configuration. A connected deployment that uses a Hugging Face model ID does not require these local files.
   4. The Intelligent Assistant readiness endpoint reports success.
   5. The BYOK source appears in the RAG and vector-store API responses.
   6. The Intelligent Assistant answers a distinctive question from the custom documents and displays the expected source metadata.

2. From inside the Intelligent Assistant container, test the exact db_path that you configured, then run the readiness and API checks. Use the path that matches your deployment method:

   # Helm example
   $ test -r /rag-content/vector_db/custom_docs/faiss_store.db
   
   # Operator example
   $ test -r /rag-content-byok/vector_db/custom_docs/faiss_store.db
   
   $ curl --fail http://127.0.0.1:8080/readiness
   $ curl --fail http://127.0.0.1:8080/v1/rags
   $ curl --fail http://127.0.0.1:8080/v1/vector-stores

   The exact host and port can differ depending on the installation. Protect administrative and diagnostic endpoints according to your organization’s security requirements.

   Note

   Run the following additional check only for a disconnected deployment that bundles a local embedding model. A connected deployment that uses a Hugging Face model ID, such as sentence-transformers/all-mpnet-base-v2, does not require this file. Test the configured embedding model path, which differs by deployment method:

   # Test <configured_embedding_model_path>/model.safetensors, for example:
   # Helm example
   $ test -r /rag-content/embeddings_model/model.safetensors
   
   # Operator example
   $ test -r /rag-content-byok/embeddings_model/model.safetensors

3. In the Intelligent Assistant, ask a question whose answer appears only in the custom content. Confirm both the answer and the cited title or URL.

   Note

   A plausible answer without the expected retrieval source does not prove that BYOK retrieval occurred.

Procedure

1. Regenerate the complete store from the authoritative document set.
2. Record the newly generated vector-store ID.
3. Build and publish a new immutable image or artifact version.
4. Update the runtime vector_db_id, db_path when necessary, and image reference together.

5. Roll out Intelligent Assistant and repeat the retrieval verification.

   Important

   Changing the embedding model requires regenerating the vector store. Do not reuse a database generated with a different model or embedding dimension.

Procedure

1. In your custom configuration file, such as lightspeed-stack.yaml, modify the user_data_collection block to configure your data preferences:

   • To enable feedback collection, set the feedback_enabled parameter to true:

     user_data_collection:
       feedback_enabled: true
       feedback_storage: "/tmp/data/feedback"
       transcripts_enabled: true
       transcripts_storage: "/tmp/data/transcripts"

   • To disable feedback collection, set the feedback_enabled parameter to false:

     user_data_collection:
       feedback_enabled: false
       feedback_storage: "/tmp/data/feedback"
       transcripts_enabled: true
       transcripts_storage: "/tmp/data/transcripts"

     Note

     Do not modify the feedback_storage or transcripts_storage data paths when disabling feedback. Altering these path strings prevents the service from locating existing historical logs.

2. Apply the updated configuration file changes to your cluster by running your platform’s standard deployment or upgrade sequence.

Procedure

1. In your app-config.yaml file, add or modify the systemPrompt parameter under the intelligent-assistant section, specifying your custom instruction string:

   intelligent-assistant:
     # ... other intelligent-assistant configurations
     systemPrompt: "You are a helpful assistant focused on Red Hat Developer Hub development."

2. Save the file.
3. Restart the RHDH service to apply the updated system prompt configuration.

Procedure

1. In your custom configuration file, such as lightspeed-stack.yaml, modify the conversation_cache block to specify your storage configuration:

   • To enable persistent storage, add your PostgreSQL database credentials and endpoint properties:

     conversation_cache:
       type: "postgres"
       postgres:
         host: _<your_database_host>_
         port: _<your_database_port>_
         db: _<your_database_name>_
         user: _<your_user_name>"_
         password: _<postgres_password>_

     • To retain the default non-persistent SQLite setup, verify that the parameters match the following paths:

       conversation_cache:
         type: "sqlite"
         sqlite:
           db_path: '/tmp/cache.db'

2. Restart the LCORE service to apply your new database configuration.

   Note

   Saved chat prompts are stored on the same backend as chat history. When you configure persistent storage, RHDH retains both chat history and saved prompts across system restarts.

Procedure

1. In your app-config.yaml file, add or modify the rateLimit block under the intelligent-assistant section:

   intelligent-assistant:
     rateLimit:
       expensive:
         max: 25
       general:
         max: 200

   expensive.max

   Maximum requests per minute per user for expensive endpoints such as LLM inference. Set to 0 to disable rate limiting for this tier.

   general.max

   Maximum requests per minute per user for general endpoints. Set to 0 to disable rate limiting for this tier.

   The following example shows a tightened configuration for a small deployment with limited LLM resources:

   lightspeed:
     rateLimit:
       expensive:
         max: 10
       general:
         max: 50

2. Save the file.
3. Restart the RHDH service to apply the updated configuration.

Verification

1. Log in to RHDH and submit requests to the Intelligent Assistant chat interface that exceed the configured expensive limit.
2. Confirm that the server returns an HTTP 429 Too Many Requests response with a Retry-After header indicating when to retry.

Procedure

1. In your custom lightspeed-stack.yaml file, add the mounted directory under skills.paths:

   skills:
     paths:
       - /app-root/skills

   A path can identify either a single skill directory or a parent directory that contains multiple skill directories.

2. Make the skills directory available to the lightspeed-core container.

   Note

   If you already mount a volume that contains your skills into the lightspeed-core container, you can skip the init-container configuration. Mount the existing volume at /app-root/skills, or update skills.paths to match its mount path.

   Otherwise, configure the volume, init container, and mount before you deploy or upgrade RHDH. This configuration ensures that the skills are present when the lightspeed-core container starts.

   1. For an Operator installation, add a strategic merge patch to the Backstage custom resource (CR):

      apiVersion: rhdh.redhat.com/v1alpha5
      kind: Backstage
      metadata:
        name: <rhdh_instance_name>
      spec:
        deployment:
          patch:
            spec:
              template:
                spec:
                  volumes:
                    - name: lightspeed-skills
                      emptyDir: {}
                  initContainers:
                    - name: fetch-lightspeed-skills
                      image: <image_with_git_client>
                      imagePullPolicy: IfNotPresent
                      command:
                        - /bin/sh
                        - -ec
                      args:
                        - |
                          git clone --depth 1 --branch <repository_ref> \
                            <skills_repository_url> /work/.source
                          test -d /work/.source/skills
                          cp -R /work/.source/skills/. /work/
                          rm -rf /work/.source
                      volumeMounts:
                        - name: lightspeed-skills
                          mountPath: /work
                  containers:
                    - name: lightspeed-core
                      volumeMounts:
                        - name: lightspeed-skills
                          mountPath: /app-root/skills

   2. For a Helm installation, add the following configuration to the values.yaml file. The chart appends these entries to the generated pod specification:

      intelligentAssistant:
        enabled: true
        core:
          extraVolumeMounts:
            - name: lightspeed-skills
              mountPath: /app-root/skills
      
      extraVolumes:
        - name: lightspeed-skills
          emptyDir: {}
      
      extraInitContainers:
        - name: fetch-lightspeed-skills
          image: <image_with_git_client>
          imagePullPolicy: IfNotPresent
          command:
            - /bin/sh
            - -ec
          args:
            - |
              git clone --depth 1 --branch <repository_ref> \
                <skills_repository_url> /work/.source
              test -d /work/.source/skills
              cp -R /work/.source/skills/. /work/
              rm -rf /work/.source
          volumeMounts:
            - name: lightspeed-skills
              mountPath: /work

      Replace the following values:

      <image_with_git_client>

      An approved image that contains Bash and Git.

      <skills_repository_url>

      The URL of the repository that contains the skills.

      <repository_ref>

      The branch or tag to retrieve.

3. Optional: Grant a team permission to view skills information by adding the intelligent-assistant.skills permission to your RBAC policy:

   p, role:default/<team>, intelligent-assistant.skills, use, allow

   Note

   The intelligent-assistant.skills permission controls visibility only. It does not control whether LCORE loads skills or whether configured skills influence answers. Users who do not have this permission still benefit from the configured skills when they use the Intelligent Assistant. Do not use this permission as a security boundary for confidential skill names or descriptions.

4. Apply the Backstage CR, or install or upgrade the Helm release.

   Important

   Define the configuration before the RHDH Deployment is created. When you update an existing installation, ensure that the change creates a new RHDH pod. The lightspeed-core container reads the mounted skills only during startup and does not reload changed skill files while the pod is running.

Verification

1. Verify that the RHDH pod is ready:

   $ oc get pods -l app.kubernetes.io/instance=<rhdh_instance_name>

2. Verify that the skill files are mounted in the lightspeed-core container:

   $ oc exec <rhdh_pod_name> -c lightspeed-core -- \
     find /app-root/skills -name SKILL.md -print

3. Open the Intelligent Assistant and send the following query:

   List available skills.

   Verify that the LLM responds with the skills that are available in the current deployment.

4. Ask a question that is covered by one of the configured skills, and verify that the response follows the skill instructions.

Procedure

1. Create a ConfigMap that contains each skill file. Give every file a unique ConfigMap key, including files in the references directory or other supporting directories:

   $ oc create configmap <skills_config_map> \
     --from-file=coding-standards-SKILL.md=skills/coding-standards/SKILL.md \
     --from-file=coding-standards-approved-libraries.md=skills/coding-standards/references/approved-libraries.md \
     --from-file=coding-standards-example-policy.yaml=skills/coding-standards/examples/example-policy.yaml

   Note

   Specify each file individually. When you pass a directory to --from-file, oc reads only the files in the top level of that directory and does not process subdirectories recursively. As a result, files in the references directory or other subdirectories are not included.

2. Mount the ConfigMap into the lightspeed-core container.

   1. For an Operator installation, use the same configMap volume definition in a strategic merge patch to the Backstage custom resource (CR):

      apiVersion: rhdh.redhat.com/v1alpha5
      kind: Backstage
      metadata:
        name: <rhdh_instance_name>
      spec:
        deployment:
          patch:
            spec:
              template:
                spec:
                  volumes:
                    - name: lightspeed-skills
                      configMap:
                        name: <skills_config_map>
                        items:
                          - key: coding-standards-SKILL.md
                            path: coding-standards/SKILL.md
                          - key: coding-standards-approved-libraries.md
                            path: coding-standards/references/approved-libraries.md
                          - key: coding-standards-example-policy.yaml
                            path: coding-standards/examples/example-policy.yaml
                  containers:
                    - name: lightspeed-core
                      volumeMounts:
                        - name: lightspeed-skills
                          mountPath: /app-root/skills

   2. For a Helm installation, use the following values.yaml configuration:

      intelligentAssistant:
        enabled: true
        core:
          extraVolumeMounts:
            - name: lightspeed-skills
              mountPath: /app-root/skills
      
      extraVolumes:
        - name: lightspeed-skills
          configMap:
            name: <skills_config_map>
            items:
              - key: coding-standards-SKILL.md
                path: coding-standards/SKILL.md
              - key: coding-standards-approved-libraries.md
                path: coding-standards/references/approved-libraries.md
              - key: coding-standards-example-policy.yaml
                path: coding-standards/examples/example-policy.yaml

3. Add the mount path under skills.paths in your custom lightspeed-stack.yaml file, and apply the Backstage CR or install or upgrade the Helm release. For more information, see Configure Agent Skills.

Procedure

1. Update the skills in the source repository, ConfigMap, or storage volume.
2. Create a new RHDH pod so that LCORE loads the updated skills. For an init-container deployment, a pod restart retrieves the configured repository reference again. For a ConfigMap deployment, update the ConfigMap before you create the new pod.

Procedure

1. Enable the notebook feature and define your model by adding the following configuration to your app-config.yaml file:

   intelligent-assistant:
     notebooks:
       enabled: true
       queryDefaults:
         model: ${NOTEBOOKS_QUERY_MODEL} # Use the exact model name
         provider_id: ${NOTEBOOKS_QUERY_PROVIDER_ID}

   Note

   If the model name is wrong, an error message is displayed in the logs and the user interface.

2. Grant user access through role-based access control (RBAC) policies by defining permissions in your rbac-policy-csv file:

   1. Add the permission policies:

      p, role:default/<your_team_name>, intelligent-assistant.notebooks, use, allow

   2. Assign the role to specific users:

      g, user:default/<your_user_name>, role:default/<your_team_name>

3. Apply the updated configuration and restart the service.

Verification

1. Log in to RHDH using an account assigned to the RBAC role defined in the configuration.
2. Confirm that the Notebooks tab is visible next to the Chat tab in the primary navigation bar.
3. Click the Notebooks tab and ensure the My Notebooks dashboard loads without error messages.

Procedure

1. In your lightspeed-stack.yaml config map, point the notebooks vector store provider at a path on the persistent mount. The provider stays faiss, so the FAISS index continues to persist as an on-disk file:

   vector_store:
     default_provider: notebooks
     providers:
       - id: notebooks
         type: faiss
         embedding_model: nomic-ai/nomic-embed-text-v1.5
         embedding_dimension: 768
         config:
           path: /var/lib/lightspeed-data/vector_db/notebooks/faiss_store.db

2. Update your deployment manifest to create the directory on the volume and mount the PVC into the Intelligent Assistant container. The config map mounts are already defined by the deployment and are unchanged:

   spec:
     template:
       spec:
         securityContext:
           fsGroup: 1000
         initContainers:
           - name: init-notebooks-storage
             image: registry.access.redhat.com/ubi9/ubi-minimal
             command:
               - sh
               - -c
               - mkdir -p /var/lib/lightspeed-data/vector_db/notebooks
             volumeMounts:
               - name: intelligent-assistant-notebooks
                 mountPath: /var/lib/lightspeed-data
         containers:
           - name: lightspeed-core
             volumeMounts:
               - name: intelligent-assistant-notebooks
                 mountPath: /var/lib/lightspeed-data
         volumes:
           - name: intelligent-assistant-notebooks
             persistentVolumeClaim:
               claimName: intelligent-assistant-notebooks-pvc

3. Apply the updated configuration and restart the service.

Verification

1. In Red Hat Developer Hub, create a Notebook and upload a test document.
2. Send a message to the virtual assistant and verify that the response is based on the document.

3. Restart the pod:

   $ oc delete pod <pod_name>

4. After the pod recovers, refresh the My Notebooks dashboard.
5. Verify that the Notebook and the uploaded file are still accessible.

Procedure

1. To enable query validation, add the following keys to the Secret that LCORE reads:

   stringData:
     ENABLE_VALIDATION: question_validity
     VALIDATION_PROVIDER: <provider_type>
     VALIDATION_MODEL_NAME: <model_name>

   where:

   ENABLE_VALIDATION

   Specifies whether the shield is enabled. You must set the value to question_validity. A nonempty value such as true does not enable the shield in RHDH 2.1.

   VALIDATION_PROVIDER

   Specifies the type of the inference provider that runs the classification, for example, openai or vllm. A provider of this type must be enabled in inference.providers.

   VALIDATION_MODEL_NAME

   Specifies the model that classifies each prompt. If the provider defines allowed_models, include this model in that list.

   For example, to run classification on an openai provider with the gpt-4o-mini model, set the following values:

   stringData:
     ENABLE_VALIDATION: question_validity
     VALIDATION_PROVIDER: openai
     VALIDATION_MODEL_NAME: gpt-4o-mini

2. To keep query validation disabled, leave ENABLE_VALIDATION unset, or set it to disabled:

   stringData:
     ENABLE_VALIDATION: __disabled__

   Important

   Running without query validation increases the risk of off-topic or harmful model output. Disable validation only in secure development environments.

3. Apply the updated Secret, and then restart the LCORE service so that the container reads the new environment variables.

Verification

1. Open the Intelligent Assistant and submit a development question, for example, How do I create a software template in RHDH?. Confirm that the assistant answers the question.
2. Submit a clearly unrelated question, for example, What is a good recipe for pizza?. Confirm that the assistant rejects the question when validation is enabled.

Procedure

1. In the lightspeed-stack.yaml file, add the allowed_models field under extra for each inference provider, and list the models that you want to expose to users:

   inference:
     providers:
       - type: openai
         id: openai
         api_key_env: OPENAI_API_KEY
         extra:
           allowed_models:
             - gpt-4o-mini

   where:

   allowed_models

   The list of models that appear in the model selection dropdown menu for that provider. Models that you omit from this list are hidden from users.

2. Apply the modified lightspeed-stack.yaml file by using a custom ConfigMap:

   For Operator-based deployments, see Configure the virtual assistant components.

   For Helm-based deployments, see Configure Developer Hub Intelligent Assistant by using the Helm chart.

3. Apply the updated configuration to your cluster, and restart the deployment if it does not trigger an automatic rollout.

Verification

1. Log in to your RHDH instance.
2. Open the chat dialog and select the model selection dropdown menu.
3. Confirm that the dropdown menu lists only the allowed models.

Procedure

1. Click the Open intelligent assistant floating action button (FAB) at the lower right of the screen to open the chat overlay.

   

2. Optional: Configure the interface display and server settings:

   • Click the Chatbot options icon (⋮) in the header to open the options menu.

     
   • In the Chatbot options menu, toggle Enable pinned chats or Disable pinned chats to show or hide the pinned chats. The system enables this option by default.
   • Available only if Model Context Protocol (MCP) is configured: In the Chatbot options menu, click MCP and Prompt Settings to manage Model Context Protocol connections.

   • In the Chatbot options menu, under Display mode, select any of the following views:

     • Overlay: A floating window is displayed over the current page content.

       

     • Dock to window: A panel attaches to the right side of the screen. Activating this mode automatically closes the Quick start panel if it is already open.

       

     • Fullscreen: A dedicated page opens for intensive chat sessions. This mode displays a revised header containing the Developer Hub Intelligent Assistant icon and a horizontal tab bar, which replaces the previous main menu. Bookmark the URL in your browser to save a direct link to the chat interface.

       

3. Start a chat or load an earlier session:

   • Enter a prompt: Type a query in the Enter a prompt for the intelligent assistant chat field and press Enter.
   • Use a sample: Click a prompt tile.

   • Change the AI model: Select a model from the model selector dropdown menu inside the prompt bar.

     

   • Attach a file: Click the (+) icon on the left of the prompt bar to upload a .yaml, .json, or .txt file. Descriptive text clarifies the function of the icon.

     
   • Use voice: Click the Use microphone icon. The microphone and send buttons are located on the right side of the prompt bar.

   • Control AI generation: Use the control buttons on the right side of the prompt bar. Click the Send (>) button to submit queries, or click the Stop button to halt AI generation.

     
     
   • Resume a chat: Select a title from the Chats list.

4. Organize your chat history:

   • Start a new topic: Click New chat to reset the assistant’s context. When the history panel is collapsed, click the New chat icon to create a new chat.

     
     
   • Search history: Enter a keyword in the Search field.

   • Rename a session: Click Options next to a chat title, select Rename, enter a new name in the Rename chat? dialog, and click Rename.

     
   • Pin a chat: Click Options next to a chat title and select Pin. The chat moves to the Pinned group.

   • Sort chats: Click the Sort control and choose a sorting criterion, such as Date (Newest first).

     

   • Delete a chat: Click Options next to a chat title and select Delete.

     
   • Collapse or expand a category: Click a category header, such as Pinned, Saved prompts, or Recent, to collapse or expand that section of the chat history sidebar.

   • Expand or collapse the panel: Click the Expand/collapse icon to toggle the history panel.

     
     
     Note

     The expanded panel is resizable up to a defined maximum width.

5. Optional: To hide the interface, if you are in the Overlay or Dock to window mode, click the Close intelligent assistant FAB to hide the window. If you are in Fullscreen mode, revert to the other modes and click the Close intelligent assistant FAB. The system preserves your active query and history.

Verification

1. The main window displays the active chat or selected history.
2. The chat history list reflects renamed, pinned, or deleted entries.

Procedure

1. Click the Open intelligent assistant floating action button (FAB) at the lower right of the screen to open the chat overlay.

2. Create a saved prompt:

   1. Click the Chatbot options icon (⋮) in the header and select MCP and Prompt Settings.

      

   2. Click the Saved prompts tab.

      
   3. Click + New prompt.

   4. Enter a Title of 128 characters or fewer and a Prompt of 5,000 characters or fewer.

      

   5. Click Save.

      Note

      By default, you can save up to 100 prompts. When you reach the limit, delete an existing prompt before you create a new one.

3. Reuse a saved prompt from the Saved prompts section of the chat history sidebar or from the Saved prompts tab:

   

   • To insert the prompt into the message field so that you can review or edit it before sending, click the prompt, or select Apply in input box from the prompt’s options menu.

     

   • To insert and submit the prompt immediately, select Send directly from the prompt’s options menu.

     
   Note

   When the sidebar lists more than five saved prompts, click Show all to display the remaining prompts, or click Show less to collapse the list.

4. Optional: To remove a saved prompt, select Delete from the prompt’s options menu, and then confirm the deletion. Deleting a saved prompt is permanent.

   

5. Optional: To open the Saved prompts settings directly, click the settings (gear) icon next to the Saved prompts section in the chat history sidebar.

   
6. Optional: To show or hide the Saved prompts feature, click the Chatbot options icon (⋮) in the header and toggle Enable saved prompts or Disable saved prompts. Saved prompts are enabled by default. When you disable the feature, RHDH hides the Saved prompts section and excludes your saved prompts from the default prompts offered in a new chat.

Verification

1. The Saved prompts tab displays the prompt count and your new prompt.
2. Clicking or sending a saved prompt applies its content in the message field.
3. Deleted prompts are removed from both the sidebar and the Saved prompts tab.

Procedure

1. Clone the evaluation repository and navigate to the directory:

   git clone https://github.com/lightspeed-core/lightspeed-evaluation
   cd lightspeed-evaluation

2. Synchronize the environment and install dependencies:

   uv sync

3. Configure the environment variables for the judge LLM. You can create a .env file in the root directory or export the keys directly to your terminal.

   • If you use Gemini, you must set the Gemini API key:

     export GEMINI_API_KEY="your-google-api-key"

   • If you use OpenAI, you must set the OpenAI API key:

     export OPENAI_API_KEY="your-key"

4. Optional: If you test with a live service, set your Developer Hub Intelligent Assistant service API key:

   export API_KEY="your-lightspeed-service-key"

Procedure

1. Download pre-generated data sets: Use this method to test the performance of specific RHDH releases. These data sets are generated using Ragas testset generation for RAG.

   1. In your terminal, navigate to the /dataset folder in the evaluation repository.
   2. Locate the .evaluation_dataset_yaml files. These files are pre-configured for the evaluation tool.

   3. To test a historical release, switch to the corresponding branch.

      For example, to access the Red Hat Developer Hub 1.8 data set, switch to the 1.8 branch.

      Important

      The main branch contains work-in-progress (WIP) data sets. Avoid using this branch for stable evaluations.

2. Generate custom data sets: Use this method to create a new test set from your own technical documentation.

   1. Generate a diverse set of question-and-answer (Q&A) pairs by following the Ragas test data generation documentation.
   2. Ensure your Q&A pairs match the required format by reviewing the evaluation data structure configuration.

Procedure

1. Download the system.yaml configuration template from the repository.

2. Configure the parameters in the system.yaml file based on your evaluation mode:

   Field	Description
   llm	Defines the judge LLM that scores the responses, such as gemini-2.5-pro.
   api.enabled	Set to false for static mode to use pre-filled data. Set to true for dynamic mode to call a live service.
   api.api_base	(Required for dynamic mode only) Provide the URL of your Developer Hub Intelligent Assistant service.
   api.endpoint_type	Specify the service configuration type: streaming or query.

3. Execute the evaluation by using the lightspeed-eval command:

   lightspeed-eval \
     --system-config config/system.yaml \
     --eval-data config/evaluation_data.yaml \
     --output-dir ./my_evaluation_results

Procedure

1. In the root of the repository, navigate to the version-specific folder within the /evaluation-result directory.

2. Open the following files to evaluate performance:

   • Model Pass Rate: Compare the overall performance between different LLMs.
   • Topic Pass Rate: Identify performance trends and gaps within specific documentation areas.