Incorporated some comments and added architecture image

pabel-rh · pabel-rh · commit 35c7a0debc59 · 2025-11-10T17:46:08.000+05:30
diff --git a/images/rhdh-plugins-reference/developer-lightspeed-architecture-1-8-0.png b/images/rhdh-plugins-reference/developer-lightspeed-architecture-1-8-0.png
diff --git a/modules/developer-lightspeed/con-llm-requirements.adoc b/modules/developer-lightspeed/con-llm-requirements.adoc
@@ -5,11 +5,10 @@
 
 {ls-short} follows a _Bring Your Own Model_ approach. This model means that to function, {ls-short} requires access to a large language model (LLM) which you must provide. An LLM is a type of generative AI that interprets natural language and generates human-like text or audio responses. When an LLM is used as a virtual assistant, the LLM can interpret questions and provide answers in a conversational manner.
 
-LLMs are usually provided by a service or server. Since {ls-short} does not provide an LLM for you, you must configure your preferred LLM provider during installation.
-You can use {ls-short} with a number of LLM providers that offer the OpenAI API interface including the following LLMS:
+LLMs are usually provided by a service or server. Since {ls-short} does not provide an LLM for you, you must configure your preferred LLM provider during installation. You can configure the underlying Llama Stack server to integrate with a number of LLM `providers`` that offer compatibility with the OpenAI API including the following LLMs:
 
 * OpenAI (cloud-based inference service)
-* Red Hat OpenShift AI (enterprise model builder & inference server)
-* Red Hat Enterprise Linux AI (enterprise inference server)
+* {rhoai-brand-name} (enterprise model builder & inference server)
+* {rhel} AI (enterprise inference server)
 * Ollama (popular desktop inference server)
 * vLLM (popular enterprise inference server)
diff --git a/modules/developer-lightspeed/con-rag-embeddings.adoc b/modules/developer-lightspeed/con-rag-embeddings.adoc
@@ -1,7 +1,7 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="con-rag-embeddings_{context}"]
-= Retrieval Augmented Generation (RAG) embeddings
+= Retrieval Augmented Generation embeddings
 
 The {product} documentation serves as the Retrieval-Augmented Generation (RAG) data source.
 
diff --git a/modules/developer-lightspeed/con-supported-architecture.adoc b/modules/developer-lightspeed/con-supported-architecture.adoc
@@ -7,5 +7,7 @@
 
 The {lcs-short} container acts as the intermediary layer, which interfaces with and manages the Llama Stack service.
 
+image::rhdh-plugins-reference/developer-lightspeed-architecture-1-8-0.png[]
+
 .Additional resources
 * link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle and supported platforms]
diff --git a/modules/developer-lightspeed/proc-installing-and-configuring-lightspeed.adoc b/modules/developer-lightspeed/proc-installing-and-configuring-lightspeed.adoc
@@ -3,7 +3,13 @@
 [id="proc-installing-and-configuring-lightspeed_{context}"]
 = Installing and configuring {ls-brand-name}
 
-You must install and configure the {ls-short}, the {lcs-name}, and Llama Stack containers manually.
+{ls-short} operates on a _Bring Your Own Model_ approach, meaning you must provide and configure access to your preferred Large Language Model (LLM) provider for the service to function. The {lcs-name} ({lcs-short}) acts as an intermediary and service layer for interfacing with LLM providers, relying on the Llama Stack service for core operations. {lcs-short} handles LLM provider setup, authentication, feedback, and Retrieval Augmented Generation (RAG). The {lcs-short} is designed to run as a sidecar container within the {product-very-short} Pod.
+
+[NOTE]
+====
+If you have already installed the previous {ls-short} (Developer Preview) with Road-Core Service (RCS), remove the previous {ls-short} configurations and settings and reinstall.
+This step is necessary as {ls-short} originally required the use of the {rcs-name} as a sidecar container for interfacing with LLM providers. The updated architecture removes and replaces RCS with the new Lightspeed Core Service (LCS) and Llama Stack, which require a new configuration for volumes, containers, and secrets.
+====
 
 .Prerequisites
 * You are logged into your {ocp-short} account.
@@ -13,6 +19,8 @@ You must install and configure the {ls-short}, the {lcs-name}, and Llama Stack c
 
 .Procedure
 
+You must install and configure the {ls-short}, the {lcs-name}, and Llama Stack containers manually.
+
 . Create the {lcs-short} ConfigMap (`lightspeed-stack.yaml`).
 +
 [IMPORTANT]
@@ -55,11 +63,9 @@ mcp_servers:
     provider_id: model-context-protocol
     url: https://<RHDH_HOST>/api/mcp-actions/v1
 ----
-+
 where:
 
-
-(Optional) `mcp_servers`:: Set this configuration if you want to integrate MCP. See {model-context-protocol-link}[{model-context-protocol-title}].
+`mcp_servers`:: Optional: Set this configuration if you want to integrate MCP. See {model-context-protocol-link}[{model-context-protocol-title}].
 `mcp_servers:name`:: This value must match the entry in the {ls-short} app config file for MCP servers.
 `model-context-protocol`:: This is the tool runtime provider defined and configured in the llama-stack `run.yaml` configuration for use in {lcs-short}.
 
@@ -140,7 +146,6 @@ providers:
         type: sqlite
     provider_id: meta-reference
     provider_type: inline::meta-reference
-   #START - Adding your LLM provider
   inference:
     - provider_id: vllm
       provider_type: remote::vllm
@@ -152,7 +157,6 @@ providers:
     - provider_id: sentence-transformers
       provider_type: inline::sentence-transformers
       config: {}
-  #END - Adding your LLM provider
   post_training:
   - config:
       checkpoint_format: huggingface
@@ -270,7 +274,7 @@ providers:
       kvstore:
         type: sqlite
         namespace: null
-        db_path: /app-root/vector_db/rhdh_product_docs/1.8/faiss_store.db
+        db_path: /app-root/vector_db/rhdh_product_docs/1.7/faiss_store.db
 scoring_fns: []
 server:
   auth: null
@@ -291,8 +295,11 @@ vector_dbs:
 - embedding_dimension: 768
   embedding_model: sentence-transformers/all-mpnet-base-v2
   provider_id: rhdh-docs
-  vector_db_id: rhdh-product-docs-1_8
+  vector_db_id: rhdh-product-docs-1_7
 ----
+where:
+`_<llm_server>_`:: Enter your LLM server details.
+`_<openai_api_key>_`:: Enter your OpenAI API key.
 
 . Create the {ls-short} ConfigMap.
 +
@@ -349,7 +356,27 @@ data:
 ----
 where:
 
-`lightspeed:mcpServers`:: Optional: Set this configuration if you want to integrate MCP.
+`mcp_servers`:: Optional: Set this configuration if you want to integrate MCP.
+
+. Create {ls-short} secret file.
+.. In the {ocp-short} web console, go to *Secrets*.
+.. Click *Create > Key/value secret*.
+.. In the *Create key/value secret* page, select the *YAML view* option in *Configure via*, and add the following example:
++
+[source,yaml]
+----
+kind: Secret
+apiVersion: v1
+metadata:
+  name: lightspeed-secrets
+  namespace: _<namespace>_ # Enter your rhdh instance namespace
+stringData:
+  LLM_SERVER_ID: _<server_id>_ # Enter your server ID (for example, `ollama` or `granite`)
+  LLM_SERVER_TOKEN: _<token>_ # Enter your server token value
+  LLM_SERVER_URL: _<server_url>_ # Enter your server URL
+type: Opaque
+----
+.. Click *Create*.
 
 . Create the Llama Stack secret file.
 .. In the {ocp-short} web console, go to *Secrets*.
@@ -382,7 +409,7 @@ stringData:
 includes:
   - dynamic-plugins.default.yaml
  plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:next__1.0.0
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:bs_1.39.1__0.5.7!red-hat-developer-hub-backstage-plugin-lightspeed
     disabled: false
     pluginConfig:
       lightspeed:
@@ -407,9 +434,16 @@ includes:
                 menuItem:
                   icon: LightspeedIcon
                   text: Lightspeed
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed-backend:next__1.0.1
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed-backend:bs_1.39.1__0.5.7!red-hat-developer-hub-backstage-plugin-lightspeed-backend
     disabled: false
     pluginConfig:
+      lightspeed:
+        # REQUIRED: Configure LLM servers with OpenAI API compatibility
+        servers:
+          - id: ${LLM_SERVER_ID}
+            url: ${LLM_SERVER_URL}
+            token: ${LLM_SERVER_TOKEN}
+
         # OPTIONAL: Port for lightspeed service (default: 8080)
         # servicePort: ${LIGHTSPEED_SERVICE_PORT}
 ----
@@ -443,28 +477,38 @@ includes:
 [source,yaml]
 ----
         volumeMounts:
-          - mountPath: /app-root/.llama
-            name: shared-storage
-          - mountPath: /app-root/embeddings_model
-            name: rag-data-volume
-            subPath: embeddings_model
-          - mountPath: /app-root/vector_db/rhdh_product_docs
-            name: rag-data-volume
-            subPath: rhdh_product_docs
-
+          - mountPath: /app-root/config/lightspeed-stack.yaml
+            name: lightspeed-stack
+            subPath: lightspeed-stack.yaml
+          - mountPath: /app-root/config/app-config-rhdh.yaml
+            name: lightspeed-app-config
+            subPath: app-config.yaml
+          - mountPath: /app-root-config/llama-stack/run.yaml
+            subPath: llama-stack/run.yaml
 ----
-... Add the Llama Stack Secret file as shown in the following example:
+... Add the {ls-short} and Llama Stack Secret file as shown in the following example:
 +
 [source,yaml]
 ----
         envFrom:
+          - secretRef:
+              name: lightspeed-secrets
           - secretRef:
               name: llama-stack-secrets
 ----
+... In your `deployment.patch.spec.template.spec.containers.env` section, set the {lcs-short} and Llama Stack environment variables as shown in the following example:
++
+[source,yaml]
+----
+    - name: PROJECT
+      value: rhdh
+    - name: LLAMA_CONFIG_FILE
+      value: /app-root/config/llama-stack/run.yaml
+----
 +
 [NOTE]
 ====
-* Your {product-very-short} container is typically already present in your Kubernetes custom resource (CR). You are adding the two additional container definitions for {lcs-short} and Llama Stack as the {lcs-short} sidecar.
+* Your {product-very-short} container is typically already present in your CR. You are adding the two additional container definitions for {lcs-short} and Llama Stack as the {lcs-short} sidecar.
 ====
 ... Click *Save*. The Pods are automatically restarted.
 +
@@ -515,10 +559,6 @@ spec:
                    subPath: lightspeed-stack.yaml
                  - mountPath: /tmp/data/feedback
                    name: shared-storage
-              # OPTIONAL: `llama-stack-config mount path configuration is only needed if you want to override the custom configuration
-                  - mountPath: /app-root/run.yaml
-                    name: llama-stack-config
-                    subPath: run.yaml
            volumes:
              - configMap:
                  name: lightspeed-stack
@@ -538,7 +578,7 @@ dynamic:
   includes:
   - dynamic-plugins.default.yaml
   plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:next__1.0.0
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:bs_1.39.1__0.5.7!red-hat-developer-hub-backstage-plugin-lightspeed
     disabled: false
     pluginConfig:
       lightspeed:
@@ -563,9 +603,15 @@ dynamic:
                 menuItem:
                   icon: LightspeedIcon
                   text: Lightspeed
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed-backend:next__1.0.1
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed-backend:bs_1.39.1__0.5.7!red-hat-developer-hub-backstage-plugin-lightspeed-backend
     disabled: false
     pluginConfig:
+      lightspeed:
+        # REQUIRED: Configure LLM servers with OpenAI API compatibility
+        servers:
+          - id: ${LLM_SERVER_ID}
+            url: ${LLM_SERVER_URL}
+            token: ${LLM_SERVER_TOKEN}
         # OPTIONAL: Port for lightspeed service (default: 8080)
         # servicePort: ${LIGHTSPEED_SERVICE_PORT}
 ----
@@ -594,23 +640,26 @@ extraVolumes:
       - mountPath: /app-root/config/lightspeed-stack.yaml
         name: lightspeed-stack
 ----
-... Add the Llama Stack Secret file as shown in the following example:
+... Add the {ls-short} and Llama Stack Secret file as shown in the following example:
 +
 [source,yaml]
 ----
  extraEnvVarsSecrets:
-      - llama-stack-secrets
+      - lightspeed-secrets
 ----
 ... Add the {lcs-short} image as shown in the following example:
 +
 [source,yaml,subs="+attributes"]
 ----
    extraContainers:
+      - env:
+          - name: PROJECT
+            value: rhdh
         envFrom:
           - secretRef:
-              name: llama-stack-secrets
+              name: lightspeed-secrets
         image: 'quay.io/redhat-ai-dev/llama-stack:latest'
-        name: llama-stack
+        name: road-core-sidecar
         ports:
           - containerPort: 8080
             name: lcs-backend
@@ -648,6 +697,11 @@ upstream:
      - configMapRef: llama-stack-config
        filename: run.yaml
    extraContainers:
+     - env:
+         - name: PROJECT
+           value: rhdh
+         - name: LLAMA_STACK_CONFIG_FILE
+           value: /app-root/run.yaml
        envFrom:
          - secretRef:
              name: lightspeed-secrets
@@ -661,6 +715,9 @@ upstream:
          - mountPath: /app-root/config/lightspeed-stack.yaml
            name: lightspeed-stack
            subPath: lightspeed-stack.yaml
+         - mountPath: /app-root/run.yaml
+           name: llama-stack-config
+           subPath: run.yaml
    extraEnvVars:
      ...
    extraEnvVarsSecrets:
