Procedure

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

   Important

   To disable an inference provider or configuration feature, you must leave the corresponding ENABLE_* variable completely unset. Setting an ENABLE_* variable to false does not disable the component because the underlying system checks only whether the variable is defined.

   Key	Description
   ENABLE_VLLM	Enables the vLLM platform when set to "true".
   VLLM_URL	Specifies the target API endpoint URL for vLLM (for example, https://<api_endpoint>/v1).
   VLLM_API_KEY	Stores the authorization token for your vLLM platform.
   ENABLE_OPENAI	Enables the OpenAI platform when set to "true".
   OPENAI_API_KEY	Stores the authorization secret key for OpenAI.
   ENABLE_VERTEX_AI	Enables the Vertex AI platform when set to "true".
   VERTEX_AI_PROJECT	Specifies your Google Cloud project ID.
   VERTEX_AI_LOCATION	Specifies your target Google Cloud region.
   GOOGLE_APPLICATION_CREDENTIALS	Specifies the file path of your mounted Google Cloud service account credentials JSON file.
   ENABLE_VALIDATION	Activates query safety validation guardrails when set to "true".
   VALIDATION_PROVIDER	Defines the active provider managing the verification routines (for example, openai or vllm).
   VALIDATION_MODEL_NAME	Specifies the exact verification model to use (for example, gpt-4o-mini).

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

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

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

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

3. 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

4. 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 Lightspeed for RHDH chat feature, including opening the chat window, sending messages, and managing chat history.

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

5. 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 manual Kubernetes Secret to store your provider credentials by adding the required keys to your Secret based on your provider requirements:

   Important

   To disable an inference provider or configuration feature, you must leave the corresponding ENABLE_* variable completely unset. Setting an ENABLE_* variable to false does not disable the component because the underlying system checks only whether the variable is defined.

   Key	Description
   ENABLE_VLLM	Enables the vLLM platform when set to "true".
   VLLM_URL	Specifies the target API endpoint URL for vLLM (for example, https://<api_endpoint>/v1).
   VLLM_API_KEY	Stores the authorization token for your vLLM platform.
   ENABLE_OPENAI	Enables the OpenAI platform when set to "true".
   OPENAI_API_KEY	Stores the authorization secret key for OpenAI.
   ENABLE_VERTEX_AI	Enables the Vertex AI platform when set to "true".
   VERTEX_AI_PROJECT	Specifies your Google Cloud project ID.
   VERTEX_AI_LOCATION	Specifies your target Google Cloud region.
   GOOGLE_APPLICATION_CREDENTIALS	Specifies the file path of your mounted Google Cloud service account credentials JSON file.
   ENABLE_VALIDATION	Activates query safety validation guardrails when set to "true".
   VALIDATION_PROVIDER	Defines the active provider managing the verification routines (for example, openai or vllm).
   VALIDATION_MODEL_NAME	Specifies the exact verification model to use (for example, gpt-4o-mini).

   Note

   • By default, the Helm installation creates a temporary Kubernetes Secret containing keys for various LLM providers. On subsequent helm upgrade cycles, the system overwrites this default Secret. Create a manual Kubernetes Secret to persist your credentials.
   • 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 safety validation guardrails within this Secret by defining the ENABLE_VALIDATION, VALIDATION_PROVIDER, and VALIDATION_MODEL_NAME keys.

2. Reference your manual secret inside the values.yaml file:

   global:
     lightspeed:
       secret:
         create: false
         name: "my-custom-secret"

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

   Important

   Only modify the create and nameOverride fields. Keep the default mount paths and file configurations unchanged.

   global:
     lightspeed:
       configMaps:
         - name: stack
           create: false
           nameOverride: "my-custom-stack"
           mountPath: /app-root/lightspeed-stack.yaml
           subPath: lightspeed-stack.yaml
           sourceFile: lightspeed-stack.yaml
           optional: false

4. 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 Lightspeed for RHDH chat feature, including opening the chat window, sending messages, and managing chat history.

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

5. 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 lightspeed flavour. This disables the chat interface and prevents the Operator from injecting unconfigured sidecar containers:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: lightspeed-disabled
   spec:
     flavours:
       - name: lightspeed
         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. 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. Developer Hub 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 database required at runtime.
   • lightspeed-stack.yaml: an example Developer Hub 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 Developer Hub 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

   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 Developer Hub 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 Developer Hub 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 Developer Hub 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  1
              backend: faiss
              embedding_model: sentence-transformers/all-mpnet-base-v2
              embedding_dimension: 768
              vector_db_id: vs_replace_with_generated_id  2
              db_path: /rag-content/vector_db/custom_docs/faiss_store.db  3
              score_multiplier: 1.0  # Used by Inline RAG only
        retrieval:
          tool:
            sources:
              - custom-docs  4

      <1>

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

      1 1 1

      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.

      2

      Must match the path where the init container copies the database inside the Developer Hub intelligent assistant container.

      3

      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 Developer Hub 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 Developer Hub 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  1
           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:  2
         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.

   <1>

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

   1

   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 Developer Hub 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 Developer Hub 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  1
              backend: faiss
              embedding_model: sentence-transformers/all-mpnet-base-v2
              embedding_dimension: 768
              vector_db_id: vs_replace_with_generated_id  2
              db_path: /rag-content-byok/vector_db/custom_docs/faiss_store.db  3
              score_multiplier: 1.0  # Used by Inline RAG only
        retrieval:
          tool:
            sources:
              - custom-docs  4

      <1>

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

      1

      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.

      2

      Must match the path where the init container copies the database inside the Developer Hub 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.

      3

      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: lightspeed-rhdh
   spec:
     application:
       extraFiles:
         configMaps:
           - name: "lightspeed-stack-byok"  1
             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  2
                   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

   <1>

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

   1

   The init container runs before Developer Hub 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 Developer Hub intelligent assistant BYOK configuration; those fields must identify paths visible inside the Developer Hub 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 Developer Hub 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

   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: quay.io/your-organization/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 Developer Hub 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  1
           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  1
           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

   <1>

   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 Developer Hub intelligent assistant container can read the configured faiss_store.db path.
   3. For a disconnected deployment that uses a local embedding model, the Developer Hub 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 Developer Hub intelligent assistant readiness endpoint reports success.
   5. The BYOK source appears in the RAG and vector-store API responses.
   6. The Developer Hub intelligent assistant answers a distinctive question from the custom documents and displays the expected source metadata.

2. From inside the Developer Hub 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 Developer Hub 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 Developer Hub 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 lightspeed section, specifying your custom instruction string:

   lightspeed:
     # ... other lightspeed 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.

Procedure

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

   lightspeed:
     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 Developer Hub 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 Developer Hub 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 Developer Hub 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:

   lightspeed:
     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. Update your custom config map llama-stack-configs/config.yaml file to point the kv_notebooks storage backend to your persistent mount point:

   spec:
     initContainers:
       - name: init-notebooks-dir
         # ... complete init container
     containers:
       - name: lightspeed-core
         image: quay.io/lightspeed-core/lightspeed-stack:0.5.1
         ports:
           - containerPort: 8080
         volumeMounts:
           - name: notebooks-storage
             mountPath: /var/lib/lightspeed-data
           - name: config  # ← Added all ConfigMap mounts
             mountPath: /app-root/config.yaml
             subPath: config.yaml
           - name: lightspeed-config
             mountPath: /app-root/lightspeed-stack.yaml
             subPath: lightspeed-stack.yaml
           - name: profile
             mountPath: /app-root/rhdh-profile.py
             subPath: rhdh-profile.py
         livenessProbe:  # ← Added health checks
           httpGet:
             path: /readiness
             port: 8080
         readinessProbe:
           httpGet:
             path: /readiness
             port: 8080
     volumes:  # ← Added all volume definitions
       - name: notebooks-storage
         persistentVolumeClaim:
           claimName: lightspeed-notebooks-pvc
       - name: config
         configMap:
           name: llama-stack-config
       - name: lightspeed-config
         configMap:
           name: lightspeed-core-config
       - name: profile
         configMap:
           name: rhdh-profile

2. Update your deployment manifest to include the init container, volume mounts, and volume definitions:

   spec:
     template:
       spec:
         initContainers:
           - name: init-notebooks-storage
             image: registry.access.redhat.com/ubi9/ubi-minimal
             command: ["sh", "-c", "mkdir -p /var/lib/lightspeed-data/notebooks && chmod -R 777 /var/lib/lightspeed-data/notebooks"]
             volumeMounts:
               - name: lightspeed-notebooks
                 mountPath: /var/lib/lightspeed-data
         containers:
           - name: lightspeed-stack
             image: quay.io/lightspeed-core/lightspeed-stack:0.5.1
             ports:
               - containerPort: 8080
             volumeMounts:
               - name: lightspeed-notebooks
                 mountPath: /var/lib/lightspeed-data
               - name: config
                 mountPath: /app-root/config.yaml
                 subPath: config.yaml
             livenessProbe:
               httpGet:
                 path: /readiness
                 port: 8080
             readinessProbe:
               httpGet:
                 path: /readiness
                 port: 8080
         volumes:
           - name: lightspeed-notebooks
             persistentVolumeClaim:
               claimName: lightspeed-notebooks-pvc
           - name: config
             configMap:
               name: llama-stack-config

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. Add the following YAML file as a config map to your namespace:

   version: 2
   image_name: redhat-ai-dev-llama-stack-no-guard
   apis:
     - agents
     - inference
     - safety
     - tool_runtime
     - vector_io
     - files
   container_image:
   external_providers_dir:
   providers:
     agents:
       - config:
           persistence:
             agent_state:
               namespace: agents
               backend: kv_default
             responses:
               table_name: responses
               backend: sql_default
         provider_id: meta-reference
         provider_type: inline::meta-reference
     inference:
       - provider_id: ${env.ENABLE_VLLM:+vllm}
         provider_type: remote::vllm
         config:
           url: ${env.VLLM_URL:=}
           api_token: ${env.VLLM_API_KEY:=}
           max_tokens: ${env.VLLM_MAX_TOKENS:=4096}
           tls_verify: ${env.VLLM_TLS_VERIFY:=true}
       - provider_id: ${env.ENABLE_OPENAI:+openai}
         provider_type: remote::openai
         config:
           api_key: ${env.OPENAI_API_KEY:=}
       - provider_id: ${env.ENABLE_VERTEX_AI:+vertexai}
         provider_type: remote::vertexai
         config:
           project: ${env.VERTEX_AI_PROJECT:=}
           location: ${env.VERTEX_AI_LOCATION:=us-central1}
       - provider_id: sentence-transformers
         provider_type: inline::sentence-transformers
         config: {}
     tool_runtime:
       - provider_id: model-context-protocol
         provider_type: remote::model-context-protocol
         config: {}
       - provider_id: rag-runtime
         provider_type: inline::rag-runtime
         config: {}
     vector_io:
       - provider_id: faiss
         provider_type: inline::faiss
         config:
           persistence:
             namespace: vector_io::faiss
             backend: faiss_kv
     files:
       - provider_id: localfs
         provider_type: inline::localfs
         config:
           storage_dir: /tmp/llama-stack-files
           metadata_store:
             table_name: files_metadata
             backend: sql_files
   storage:
     backends:
       kv_default:
         type: kv_sqlite
         db_path: /tmp/kvstore.db
       sql_default:
         type: sql_sqlite
         db_path: /tmp/sql_store.db
       sql_files:
         type: sql_sqlite
         db_path: /rag-content/vector_db/rhdh_product_docs/1.9/files_metadata.db
       faiss_kv:
         type: kv_sqlite
         db_path: /rag-content/vector_db/rhdh_product_docs/1.9/faiss_store.db
     stores:
       metadata:
         namespace: registry
         backend: faiss_kv
       inference:
         table_name: inference_store
         backend: sql_default
         max_write_queue_size: 10000
         num_writers: 4
       conversations:
         table_name: openai_conversations
         backend: sql_default
   registered_resources:
     models:
       - model_id: sentence-transformers/all-mpnet-base-v2
         metadata:
           embedding_dimension: 768
         model_type: embedding
         provider_id: sentence-transformers
         provider_model_id: /rag-content/embeddings_model
     tool_groups:
       - provider_id: rag-runtime
         toolgroup_id: builtin::rag
     vector_dbs:
       - vector_db_id: rhdh-product-docs-1_8
         embedding_model: sentence-transformers/all-mpnet-base-v2
         embedding_dimension: 768
         provider_id: faiss
   server:
     auth:
     host:
     port: 8321
     quota:
     tls_cafile:
     tls_certfile:
     tls_keyfile:

2. Mount the config map to your Llama Stack container at /app-root/run.yaml to make sure it overrides the default image file:

   name: llama-stack
   volumeMounts:
   - mountPath: /app-root/run.yaml
     subPath: run.yaml
     name: llama-stack-config

3. Configure the required volume:

   volumes:
   - name: llama-stack-config
     configMap:
       name: llama-stack-config

   where:

   llama-stack-config

   The config map where you added the new no-guard configuration file.

4. Restart the deployment if it does not trigger an automatic rollout.

Procedure

1. Click the Open intelligent assistant floating action button 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 MCP is configured: In the Chatbot options menu, click MCP 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 Lightspeed logo 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 Send a message 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.

     
     1. Click the attached file name to open the Preview attachment window.
     2. View the read-only content, or click Edit to modify the file.
   • 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 Sort control and choose a sorting criteria, such as Date (Newest first).

     

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

     

   • 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 icon (X) to hide the window. If you are in Fullscreen mode, revert to the other modes and click the Close intelligent assistant icon (X). The system preserves your active query and history.
6. Optional: In Fullscreen mode, bookmark the URL in your browser to save a direct link to the chat interface.

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. 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 Lightspeed for RHDH 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 Lightspeed for RHDH 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.