Skip to content

Commit 5eb33cc

Browse files
bpareesbparees
committed
Add explicit docs for consuming OKP
1 parent 5b6d64d commit 5eb33cc

1 file changed

Lines changed: 204 additions & 0 deletions

File tree

‎docs/okp_guide.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# OKP Deployment and Configuration Guide
2+
3+
This document explains how to deploy the Offline Knowledge Portal (OKP) as a RAG source and configure Lightspeed Stack and Llama Stack to use it. You will:
4+
5+
* Deploy and verify the OKP Solr service
6+
* Configure Lightspeed Stack for OKP (inline or tool RAG)
7+
* Install dependencies and launch Lightspeed Stack
8+
* Confirm the end-to-end stack with a sample query
9+
10+
For general RAG concepts, BYOK vector stores, and manual Llama Stack configuration, see the [RAG Configuration Guide](rag_guide.md).
11+
12+
---
13+
14+
## Table of Contents
15+
16+
* [Introduction](#introduction)
17+
* [Prerequisites](#prerequisites)
18+
* [Step 1: Launch OKP](#step-1-launch-okp)
19+
* [Step 2: Setup llamamstack config environment variables](#step-2-setup-llamamstack-config-environment-variables)
20+
* [Step 3: Install Lightspeed Stack Dependencies](#step-3-install-lightspeed-stack-dependencies)
21+
* [Step 4: Configure Lightspeed Stack](#step-4-configure-lightspeed-stack)
22+
* [Step 5: Launch Lightspeed Stack](#step-6-launch-lightspeed-stack)
23+
* [Step 6: Verify the Stack](#step-7-verify-the-stack)
24+
25+
---
26+
27+
## Introduction
28+
29+
OKP (Offline Knowledge Portal) provides a Solr-backed RAG source that Lightspeed Stack can use for both **Inline RAG** (context injected before the LLM request) and **Tool RAG** (context retrieved on demand via the `file_search` tool). This guide walks through deploying the OKP container, enriching your Llama Stack config from Lightspeed Stack settings, and validating that queries return referenced chunks.
30+
31+
---
32+
33+
## Prerequisites
34+
35+
* [lightspeed-stack repository](https://github.com/lightspeed-core/lightspeed-stack) cloned
36+
* [lightspeed-providers repository](https://github.com/lightspeed-core/lightspeed-providers) cloned
37+
* [Podman](https://podman.io/) (or Docker) to run the OKP image
38+
* [uv](https://docs.astral.sh/uv/) for Python dependency management
39+
* An OpenAI API key (for inference when using OpenAI in your run config)
40+
41+
---
42+
43+
## Step 1: Launch OKP
44+
45+
> **Warning:** The image referenced below is a **prototype**. The official OKP RAG image is expected in **late March / early April** of 2026.
46+
47+
Start the OKP RAG service with Podman:
48+
49+
```bash
50+
podman run --rm -d -p 8983:8080 images.paas.redhat.com/offline-kbase/rhokp-rag:mar-9-2026
51+
```
52+
53+
> **Note:** Remove `-d` to run in the foreground.
54+
55+
* The service listens on **port 8983** on the host (mapped from 8080 in the container).
56+
* Confirm it is running by opening in a browser or with `curl`:
57+
58+
```bash
59+
curl -s http://localhost:8983
60+
```
61+
62+
Or visit: **http://localhost:8983**
63+
64+
---
65+
66+
## Step 2: Setup llamastack config environment variables
67+
68+
Set the required environment variables. The external providers path must point to the `external_providers` content inside the [lightspeed-providers](https://github.com/lightspeed-core/lightspeed-providers/tree/main/lightspeed_stack_providers/) repository:
69+
70+
```bash
71+
export EXTERNAL_PROVIDERS_DIR=../lightspeed-providers/resources/external_providers
72+
export OPENAI_API_KEY=<your-openai-api-key>
73+
```
74+
75+
Adjust `EXTERNAL_PROVIDERS_DIR` if your lightspeed-providers repo is in a different location relative to your lightspeed-stack directory.
76+
77+
---
78+
79+
## Step 3: Install Lightspeed Stack Dependencies
80+
81+
Then install dependencies and custom providers:
82+
83+
```bash
84+
uv sync --group dev --group llslibdev
85+
uv pip install -e ../lightspeed-providers # Path to lightspeed-providers repo
86+
```
87+
88+
* **`uv sync`**: Installs project and dev/llslibdev groups so that the app and tooling run correctly.
89+
* **`uv pip install -e ../lightspeed-providers`**: Installs the lightspeed stack providers from the local clone of the repository. Adjust the directory path as needed.
90+
91+
> **Note:** Running `uv sync` will remove the lightspeed-providers dependency installed by the `uv pip install` command, so you will need to rerun the `uv pip install` command if you rerun `uv sync`.
92+
93+
---
94+
95+
## Step 4: Configure Lightspeed Stack
96+
97+
### Enable OKP in Lightspeed Stack
98+
Edit your Lightspeed Stack config file (e.g. `lightspeed-stack.yaml`) and add the following top-level sections so that OKP is used for either inline or tool RAG:
99+
100+
Inline RAG:
101+
```yaml
102+
# RAG configuration
103+
rag:
104+
inline:
105+
- okp
106+
okp:
107+
offline: true
108+
```
109+
110+
Tool RAG:
111+
```yaml
112+
# RAG configuration
113+
rag:
114+
tool:
115+
- okp
116+
okp:
117+
offline: true
118+
```
119+
120+
* **`rag.inline`** and **`rag.tool`**: Enable OKP as the RAG source for inline context injection and for the RAG tool. Tool rag means the LLM will be provided a search tool it can choose to invoke to find relevant content and augment the user prompt. The tool may or may not be invoked. Inline means a rag search and prompt augmentation will always occur.
121+
* **`okp.offline`**: When `true`, source URLs use `parent_id` (offline/Mimir-style). When `false`, use `reference_url` (online).
122+
123+
If you want to filter the docs to a specific product, you can include a query filter such as:
124+
125+
```yaml
126+
okp:
127+
offline: true
128+
chunk_filter_query: "product:*openshift*"
129+
```
130+
131+
When you launch Lightspeed stack it will augment the Llamastack run.yaml with configuration for OKP.
132+
133+
### Configure Lightspeed Stack for library mode
134+
135+
For the simplest local development, configure `lightspeed-stack.yaml` to consume Llama Stack in library mode:
136+
137+
```yaml
138+
llama_stack:
139+
...
140+
use_as_library_client: true
141+
library_client_config_path: run.yaml
142+
# Comment these lines out if present
143+
# url: http://lama-stack:87321
144+
# api_key: xyzzy
145+
...
146+
```
147+
148+
---
149+
150+
## Step 5: Launch Lightspeed Stack
151+
152+
Then launch Lightspeed Stack using your Lightspeed Stack config(`lightspeed-stack.yaml`) which references the provided default Llamastack config file (`run.yaml`):
153+
154+
```bash
155+
make run
156+
```
157+
158+
Lightspeed Stack has launched successfully and is available when you see this log output:
159+
160+
```log
161+
INFO 2026-03-17 11:20:31,347 uvicorn.error:62 uncategorized: Application startup complete.
162+
INFO 2026-03-17 11:20:31,349 uvicorn.error:224 uncategorized: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
163+
```
164+
165+
> **Note:** Lightspeed stack will automatically enrich the llamastack configuration to add the necessary providers/resources for referencing OKP. This assumes your OKP instance is running on localhost:8983. If you need a different OKP url, you will need to run `uv run src/llama_stack_configuration.py -c lightspeed-stack.yaml -i run.yaml -o run_enriched.yaml` to generate the llamastack configuration, edit the `solr_url` value in that file, and then edit your lightspeed stack configuration to point to the enriched llamastack config file by setting `library_client_config_path: run_enriched.yaml`.
166+
167+
---
168+
169+
## Step 6: Verify the Stack
170+
171+
Confirm that the full stack (Lightspeed Stack + Llama Stack + OKP) is working by sending a query and checking that the response includes referenced chunks from OKP:
172+
173+
```bash
174+
curl -sX POST http://localhost:8080/v1/query \
175+
-H "Content-Type: application/json" \
176+
-d '{"query": "configure remote desktop using gnome"}' | jq .
177+
```
178+
179+
* Adjust the URL and port if your Lightspeed Stack API is exposed elsewhere.
180+
* In the JSON response, look for `rag_chunks` that indicate OKP/Solr results were retrieved.
181+
182+
Example response excerpt:
183+
```json
184+
"rag_chunks": [
185+
{
186+
"content": "You can connect from a Red Hat Enterprise Linux client to a remote desktop server by using the\n**Connections**\napplication. The connection depends on the remote server configuration.\n**Prerequisites**\n- Desktop sharing or remote login is enabled on the server. For more information, see [Enabling desktop sharing on the server by using GNOME](#enabling-desktop-sharing-on-the-server-by-using-gnome) or [Configuring GNOME remote login](#configuring-gnome-remote-login) .\n- For desktop sharing, a user is logged in to the GNOME graphical session on the server.\n- The `gnome-connections` package is installed on the client.\n**Procedure**\n1. On the client, launch the **Connections** application.\n2. Click the + button in the top bar to open a new connection.\n4. Enter the IP address of the server.\n5. Choose the connection type based on the operating system you want to connect to: Remote Desktop Protocol (RDP) Use RDP for connecting to Windows and RHEL 10 servers. Virtual Network Computing (VNC) Use VNC for connecting to servers with RHEL 9 and previous versions.\n6. Click Connect .\n**Verification**\n1. On the client, check that you can see the shared server desktop.\n2. On the server, a screen sharing indicator appears on the right side of the top panel: You can control screen sharing in the **System** menu of the server.",
187+
"source": "okp",
188+
"score": 826.40784,
189+
"attributes": {
190+
"doc_url": "https://mimir.corp.redhat.com/documentation/en-us/red_hat_enterprise_linux/10/html-single/administering_rhel_by_using_the_gnome_desktop_environment/index",
191+
"document_id": "/documentation/en-us/red_hat_enterprise_linux/10/html-single/administering_rhel_by_using_the_gnome_desktop_environment/index"
192+
}
193+
}
194+
],
195+
```
196+
197+
> **Note:** The first time you query the system the response may take additional time because it must first download the necessary embedding model to perform the vector search.
198+
199+
If you see no RAG context, verify:
200+
201+
1. OKP is up at http://localhost:8983
202+
2. `lightspeed-stack.yaml` has `okp` under `rag.inline` and/or `rag.tool` as in Step 4
203+
204+
---

0 commit comments

Comments
 (0)