Skip to content

Commit 539c7f0

Browse files
bpareesbparees
committed
Add explicit docs for consuming OKP
1 parent 84faf9f commit 539c7f0

1 file changed

Lines changed: 196 additions & 0 deletions

File tree

‎docs/okp_guide.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
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+
* Configure Lightspeed Stack for OKP (inline or tool RAG)
6+
* Run the configuration enrichment step
7+
* Deploy and verify the OKP Solr service
8+
* Install dependencies and launch Lightspeed Stack
9+
* Confirm the end-to-end stack with a sample query
10+
11+
For general RAG concepts, BYOK vector stores, and manual Llama Stack configuration, see the [RAG Configuration Guide](rag_guide.md).
12+
13+
---
14+
15+
## Table of Contents
16+
17+
* [Introduction](#introduction)
18+
* [Prerequisites](#prerequisites)
19+
* [Step 1: Configure Lightspeed Stack for OKP](#step-1-configure-lightspeed-stack-for-okp)
20+
* [Step 2: Run Configuration Enrichment](#step-2-run-configuration-enrichment)
21+
* [Step 3: Launch OKP](#step-3-launch-okp)
22+
* [Step 4: Install Dependencies and Launch Lightspeed Stack](#step-4-install-dependencies-and-launch-lightspeed-stack)
23+
* [Step 5: Verify the Stack](#step-5-verify-the-stack)
24+
* [OKP Configuration Reference](#okp-configuration-reference)
25+
* [References](#references)
26+
27+
---
28+
29+
## Introduction
30+
31+
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.
32+
33+
---
34+
35+
## Prerequisites
36+
37+
* Lightspeed Stack repository cloned and ready to run
38+
* [lightspeed-providers](https://github.com/lightspeed-core/lightspeed-providers) repository cloned
39+
* A base Llama Stack config file (e.g. `run.yaml`) that defines inference and other providers you need
40+
* [Podman](https://podman.io/) (or Docker) to run the OKP image
41+
* [uv](https://docs.astral.sh/uv/) for Python dependency management
42+
* An OpenAI API key (for inference when using OpenAI in your run config)
43+
44+
---
45+
46+
## Step 1: Configure Lightspeed Stack for OKP
47+
48+
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:
49+
50+
Inline RAG:
51+
```yaml
52+
# RAG configuration
53+
rag:
54+
tool:
55+
- okp
56+
okp:
57+
offline: true
58+
chunk_filter_query: "is_chunk:true"
59+
```
60+
61+
Tool RAG:
62+
```yaml
63+
# RAG configuration
64+
rag:
65+
tool:
66+
- okp
67+
okp:
68+
offline: true
69+
chunk_filter_query: "is_chunk:true"
70+
```
71+
72+
* **`rag.inline`** and **`rag.tool`**: Enable OKP as the RAG source for inline context injection and for the RAG tool.
73+
* **`okp.offline`**: When `true`, source URLs use `parent_id` (offline/Mimir-style). When `false`, use `reference_url` (online).
74+
* **`okp.chunk_filter_query`**: Solr filter query applied to every OKP search (e.g. `"is_chunk:true"` to restrict to chunk documents). You can extend this with Solr boolean syntax (see [RAG Guide - Query Filtering](rag_guide.md#query-filtering)).
75+
76+
---
77+
78+
## Step 2: Run Configuration Enrichment
79+
80+
Enrich your base Llama Stack config with OKP (and any BYOK) settings from `lightspeed-stack.yaml` using the configuration script:
81+
82+
```bash
83+
uv run src/llama_stack_configuration.py -c lightspeed-stack.yaml -i run.yaml -o run_enriched_new.yaml
84+
```
85+
86+
* **`-c`**: Lightspeed Stack config (e.g. `lightspeed-stack.yaml`)
87+
* **`-i`**: Input Llama Stack config (e.g. `run.yaml`)
88+
* **`-o`**: Output enriched config (e.g. `run_enriched_new.yaml`)
89+
90+
Use the **output file** (e.g. `run_enriched_new.yaml`) when starting Llama Stack / Lightspeed Stack so that OKP vector IO and related resources are registered.
91+
92+
> [!TIP]
93+
> Re-run this command whenever you change RAG or OKP settings in `lightspeed-stack.yaml` so that the enriched run file stays in sync.
94+
95+
---
96+
97+
## Step 3: Launch OKP
98+
99+
Start the OKP RAG service with Podman:
100+
101+
```bash
102+
podman run --rm -d -p 8983:8080 images.paas.redhat.com/offline-kbase/rhokp-rag:mar-9-2026
103+
```
104+
105+
Note: remove `-d` to run in the foreground
106+
107+
* The service listens on **port 8983** on the host (mapped from 8080 in the container).
108+
* Confirm it is running by opening in a browser or with `curl`:
109+
110+
```bash
111+
curl -s http://localhost:8983
112+
```
113+
114+
Or visit: **http://localhost:8983**
115+
116+
Ensure Lightspeed Stack is configured to use this OKP endpoint (the enrichment step typically adds the correct Solr/OKP URL; if you need a different host/port, adjust the `solr_url` config value accordingly).
117+
118+
---
119+
120+
## Step 4: Install Lightspeed Stack Dependencies
121+
122+
Then install dependencies and (if needed) your custom providers:
123+
124+
```bash
125+
uv sync --group dev --group llslibdev
126+
uv pip install -e ../lightspeed-providers # Path to lightspeed-providers repo
127+
```
128+
129+
* **`EXTERNAL_PROVIDERS_DIR`**: Path to external providers in the lightspeed-providers repo (e.g. `../lightspeed-providers/resources/external_providers`). Required for Lightspeed Stack to load OKP and other external providers.
130+
* **`OPENAI_API_KEY`**: Your OpenAI API key; required when your run config uses OpenAI for inference.
131+
* **`uv sync`**: Installs project and dev/llslibdev groups so that the app and tooling run correctly.
132+
* **`uv pip install -e $PROVIDERS_DIR`**: Installs the lightspeed stack providers.
133+
134+
Note: Running `uv sync` will break the symlink created by the `uv pip install` command, so you will need to
135+
rerun the `uv pip install` command if you rerun `uv sync`.
136+
137+
138+
## Step 5: Setup llamamstack config environment variables
139+
140+
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:
141+
142+
```bash
143+
export EXTERNAL_PROVIDERS_DIR=../lightspeed-providers/resources/external_providers
144+
export OPENAI_API_KEY=<your-openai-api-key>
145+
```
146+
147+
Adjust `EXTERNAL_PROVIDERS_DIR` if your lightspeed-providers repo is in a different location relative to your current working directory.
148+
149+
## Step 6: Launch Lightspeed Stack
150+
151+
Then launch Lightspeed Stack using your **enriched** Llama Stack config (e.g. `run_enriched_new.yaml`) and your Lightspeed Stack config, following your usual run instructions (e.g. pointing to the enriched run file and the correct port).
152+
153+
```bash
154+
make run
155+
```
156+
157+
158+
---
159+
160+
## Step 7: Verify the Stack
161+
162+
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:
163+
164+
```bash
165+
curl -sX POST http://localhost:8080/v1/query \
166+
-H "Content-Type: application/json" \
167+
-d '{"query": "configure remote desktop using gnome"}' | jq .
168+
```
169+
170+
* Adjust the URL and port if your Lightspeed Stack API is exposed elsewhere.
171+
* In the JSON response, look for `rag_chunks` that indicate OKP/Solr results were retrieved.
172+
173+
Example response excerpt:
174+
```json
175+
"rag_chunks": [
176+
{
177+
"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.",
178+
"source": "okp",
179+
"score": 826.40784,
180+
"attributes": {
181+
"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",
182+
"document_id": "/documentation/en-us/red_hat_enterprise_linux/10/html-single/administering_rhel_by_using_the_gnome_desktop_environment/index"
183+
}
184+
}
185+
],
186+
```
187+
188+
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.
189+
190+
If you see no RAG context, verify:
191+
192+
1. OKP is up at http://localhost:8983
193+
2. You started Lightspeed Stack with the **enriched** run file from Step 2
194+
3. `lightspeed-stack.yaml` has `okp` under `rag.inline` and/or `rag.tool` as in Step 1
195+
196+
---

0 commit comments

Comments
 (0)