Skip to content

Commit 94b5cf4

Browse files
are-cesclaude
are-ces
and
claude
committed
LCORE-2437: support pgvector in BYOK RAG enrichment
Add pgvector as a supported rag_type in the BYOK RAG enrichment pipeline. When rag_type is set to remote::pgvector, the enrichment script generates a pgvector provider config with PostgreSQL connection fields instead of the FAISS-style kv_sqlite storage backend. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 014a5ba commit 94b5cf4

8 files changed

Lines changed: 481 additions & 90 deletions

File tree

‎docs/byok_guide.md‎

Lines changed: 47 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -189,18 +189,33 @@ byok_rag:
189189
score_multiplier: 1.0 # Weight for Inline RAG result ranking (default: 1.0)
190190
```
191191
192-
**`byok_rag` field reference:**
192+
**Common fields (all providers):**
193193
194194
| Field | Required | Default | Description |
195195
|-----------------------|----------|-------------------------------------------|-------------------------------------------------------------------------------------------|
196196
| `rag_id` | Yes | — | Unique identifier for the knowledge source |
197-
| `rag_type` | No | `inline::faiss` | Vector store provider type |
197+
| `rag_type` | No | `inline::faiss` | Vector store provider type (`inline::faiss` or `remote::pgvector`) |
198198
| `embedding_model` | No | `sentence-transformers/all-mpnet-base-v2` | Embedding model identifier or path |
199199
| `embedding_dimension` | No | `768` | Embedding vector dimensionality |
200200
| `vector_db_id` | Yes | — | Vector store ID generated by rag-content (e.g. `vs_8c94967b-81cc-4028-a294-9cfac6fd9ae2`) |
201-
| `db_path` | Yes | — | Path to the vector database file |
202201
| `score_multiplier` | No | `1.0` | Weight for Inline RAG ranking (values > 1.0 boost; < 1.0 reduce) |
203202

203+
**FAISS fields** (`rag_type: inline::faiss`):
204+
205+
| Field | Required | Default | Description |
206+
|-----------|----------|---------|----------------------------------|
207+
| `db_path` | Yes | — | Path to the vector database file |
208+
209+
**pgvector fields** (`rag_type: remote::pgvector`):
210+
211+
| Field | Required | Default | Description |
212+
|------------|----------|--------------------------|---------------------|
213+
| `host` | No | `${env.POSTGRES_HOST}` | PostgreSQL host |
214+
| `port` | No | `${env.POSTGRES_PORT}` | PostgreSQL port |
215+
| `db` | No | `${env.POSTGRES_DATABASE}` | PostgreSQL database |
216+
| `user` | No | `${env.POSTGRES_USER}` | PostgreSQL user |
217+
| `password` | No | `${env.POSTGRES_PASSWORD}` | PostgreSQL password |
218+
204219
**Multiple knowledge sources:**
205220

206221
You can configure multiple BYOK sources. When using Inline RAG, `score_multiplier` adjusts the relative importance of each store's results:
@@ -283,28 +298,27 @@ byok_rag:
283298
### 2. pgvector (PostgreSQL)
284299
- **Type**: PostgreSQL with pgvector extension
285300
- **Best for**: Large-scale deployments, shared knowledge bases
286-
- **Configuration**: `remote::pgvector`
301+
- **Configuration**: `rag_type: remote::pgvector`
287302
- **Requirements**: PostgreSQL with pgvector extension
288303

289-
> [!NOTE]
290-
> pgvector is not yet supported via `byok_rag` in `lightspeed-stack.yaml` (see [LCORE-2437](https://redhat.atlassian.net/browse/LCORE-2437)).
291-
> It must be configured directly in the Llama Stack configuration file.
292-
293304
```yaml
294-
vector_io:
295-
- provider_id: pgvector-knowledge
296-
provider_type: remote::pgvector
297-
config:
298-
host: localhost
299-
port: 5432
300-
db: knowledge_db
301-
user: lightspeed_user
305+
byok_rag:
306+
- rag_id: pgvector-knowledge
307+
rag_type: remote::pgvector
308+
embedding_model: sentence-transformers/all-mpnet-base-v2
309+
embedding_dimension: 768
310+
vector_db_id: rhdocs
311+
host: ${env.POSTGRES_HOST}
312+
port: ${env.POSTGRES_PORT}
313+
db: ${env.POSTGRES_DATABASE}
314+
user: ${env.POSTGRES_USER}
302315
password: ${env.POSTGRES_PASSWORD}
303-
kvstore:
304-
type: sqlite
305-
db_path: .llama/distributions/pgvector/registry.db
306316
```
307317

318+
> [!NOTE]
319+
> Connection fields (`host`, `port`, `db`, `user`, `password`) default to
320+
> `${env.POSTGRES_*}` environment variable references when omitted.
321+
308322
**pgvector Table Schema:**
309323
- `id` (text): UUID identifier of the chunk
310324
- `document` (jsonb): JSON containing content and metadata
@@ -342,13 +356,7 @@ rag:
342356

343357
### Example 2: Multiple Knowledge Sources with pgvector
344358

345-
A configuration combining a local FAISS store (via `byok_rag`) with a remote pgvector store (configured directly in the Llama Stack configuration file):
346-
347-
> [!NOTE]
348-
> pgvector is not yet supported via `byok_rag` in `lightspeed-stack.yaml` (see [LCORE-2437](https://redhat.atlassian.net/browse/LCORE-2437)).
349-
> The pgvector provider must be configured directly in the Llama Stack configuration file.
350-
351-
**`lightspeed-stack.yaml`** — FAISS store and RAG strategy:
359+
A configuration combining a local FAISS store with a remote pgvector store:
352360

353361
```yaml
354362
name: Lightspeed Core Service (LCS)
@@ -365,34 +373,29 @@ byok_rag:
365373
vector_db_id: vs_e9d8c7b6-43af-4b2d-8e1f-0a9b8c7d6e5f
366374
db_path: /data/vector_dbs/local/faiss_store.db
367375
score_multiplier: 1.0
376+
- rag_id: enterprise-kb
377+
rag_type: remote::pgvector
378+
embedding_model: sentence-transformers/all-mpnet-base-v2
379+
embedding_dimension: 768
380+
vector_db_id: enterprise_docs
381+
host: ${env.POSTGRES_HOST}
382+
port: ${env.POSTGRES_PORT}
383+
db: ${env.POSTGRES_DATABASE}
384+
user: ${env.POSTGRES_USER}
385+
password: ${env.POSTGRES_PASSWORD}
368386
369387
rag:
370388
inline:
371389
- local-docs
390+
- enterprise-kb
372391
tool:
373392
- local-docs
374-
```
375-
376-
**Llama Stack configuration file** — pgvector provider:
377-
378-
```yaml
379-
vector_io:
380-
- provider_id: enterprise-kb
381-
provider_type: remote::pgvector
382-
config:
383-
host: localhost
384-
port: 5432
385-
db: knowledge_db
386-
user: lightspeed_user
387-
password: ${env.POSTGRES_PASSWORD}
388-
kvstore:
389-
type: sqlite
390-
db_path: .llama/distributions/pgvector/registry.db
393+
- enterprise-kb
391394
```
392395

393396
> [!NOTE]
394397
> For pgvector, ensure your PostgreSQL credentials are available via environment variables
395-
> (e.g., `POSTGRES_PASSWORD`).
398+
> (e.g., `POSTGRES_HOST`, `POSTGRES_PASSWORD`).
396399

397400
> [!TIP]
398401
> A complete working example combining BYOK and OKP is available at

‎docs/openapi.json‎

Lines changed: 73 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11818,7 +11818,7 @@
1181811818
"type": "string",
1181911819
"minLength": 1,
1182011820
"title": "RAG type",
11821-
"description": "Type of RAG database.",
11821+
"description": "Type of RAG database (e.g. 'inline::faiss', 'remote::pgvector').",
1182211822
"default": "inline::faiss"
1182311823
},
1182411824
"embedding_model": {
@@ -11842,24 +11842,92 @@
1184211842
"description": "Vector database identification."
1184311843
},
1184411844
"db_path": {
11845-
"type": "string",
11845+
"anyOf": [
11846+
{
11847+
"type": "string"
11848+
},
11849+
{
11850+
"type": "null"
11851+
}
11852+
],
1184611853
"title": "DB path",
11847-
"description": "Path to RAG database."
11854+
"description": "Path to RAG database. Required for inline::faiss."
1184811855
},
1184911856
"score_multiplier": {
1185011857
"type": "number",
1185111858
"exclusiveMinimum": 0.0,
1185211859
"title": "Score multiplier",
1185311860
"description": "Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them.",
1185411861
"default": 1.0
11862+
},
11863+
"host": {
11864+
"anyOf": [
11865+
{
11866+
"type": "string"
11867+
},
11868+
{
11869+
"type": "null"
11870+
}
11871+
],
11872+
"title": "PostgreSQL host",
11873+
"description": "PostgreSQL host for remote::pgvector. Defaults to ${env.POSTGRES_HOST} when rag_type is remote::pgvector."
11874+
},
11875+
"port": {
11876+
"anyOf": [
11877+
{
11878+
"type": "string"
11879+
},
11880+
{
11881+
"type": "null"
11882+
}
11883+
],
11884+
"title": "PostgreSQL port",
11885+
"description": "PostgreSQL port for remote::pgvector. Defaults to ${env.POSTGRES_PORT} when rag_type is remote::pgvector."
11886+
},
11887+
"db": {
11888+
"anyOf": [
11889+
{
11890+
"type": "string"
11891+
},
11892+
{
11893+
"type": "null"
11894+
}
11895+
],
11896+
"title": "PostgreSQL database",
11897+
"description": "PostgreSQL database name for remote::pgvector. Defaults to ${env.POSTGRES_DATABASE} when rag_type is remote::pgvector."
11898+
},
11899+
"user": {
11900+
"anyOf": [
11901+
{
11902+
"type": "string"
11903+
},
11904+
{
11905+
"type": "null"
11906+
}
11907+
],
11908+
"title": "PostgreSQL user",
11909+
"description": "PostgreSQL user for remote::pgvector. Defaults to ${env.POSTGRES_USER} when rag_type is remote::pgvector."
11910+
},
11911+
"password": {
11912+
"anyOf": [
11913+
{
11914+
"type": "string",
11915+
"format": "password",
11916+
"writeOnly": true
11917+
},
11918+
{
11919+
"type": "null"
11920+
}
11921+
],
11922+
"title": "PostgreSQL password",
11923+
"description": "PostgreSQL password for remote::pgvector. Defaults to ${env.POSTGRES_PASSWORD} when rag_type is remote::pgvector."
1185511924
}
1185611925
},
1185711926
"additionalProperties": false,
1185811927
"type": "object",
1185911928
"required": [
1186011929
"rag_id",
11861-
"vector_db_id",
11862-
"db_path"
11930+
"vector_db_id"
1186311931
],
1186411932
"title": "ByokRag",
1186511933
"description": "BYOK (Bring Your Own Knowledge) RAG configuration."

‎docs/rag_guide.md‎

Lines changed: 13 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,6 @@ See the full working [config example](../examples/lightspeed-stack-byok-okp-rag.
8888

8989
This example shows how to configure a remote PostgreSQL database with the [pgvector](https://github.com/pgvector/pgvector) extension for storing embeddings.
9090

91-
> [!NOTE]
92-
> pgvector is not yet supported via `byok_rag` in `lightspeed-stack.yaml` (see [LCORE-2437](https://redhat.atlassian.net/browse/LCORE-2437)).
93-
> It must be configured directly in the Llama Stack configuration file.
94-
9591
> You will need to install PostgreSQL with a matching version to pgvector, then log in with `psql` and enable the extension with:
9692
> ```sql
9793
> CREATE EXTENSION IF NOT EXISTS vector;
@@ -107,33 +103,22 @@ Each pgvector-backed table follows this schema:
107103
> The `vector_store_id` (e.g. `rhdocs`) is used to point to the table named `vector_store_rhdocs` in the specified database, which stores the vector embeddings.
108104

109105
```yaml
110-
providers:
111-
[...]
112-
vector_io:
113-
- provider_id: pgvector-example
114-
provider_type: remote::pgvector
115-
config:
116-
host: localhost
117-
port: 5432
118-
db: pgvector_example # PostgreSQL database (psql -d pgvector_example)
119-
user: lightspeed # PostgreSQL user
120-
password: password123
121-
kvstore:
122-
type: sqlite
123-
db_path: .llama/distributions/pgvector/pgvector_registry.db
124-
vector_stores:
125-
- embedding_dimension: 768
126-
embedding_model: sentence-transformers/all-mpnet-base-v2
127-
provider_id: pgvector-example
128-
# A unique ID that becomes the PostgreSQL table name, prefixed with 'vector_store_'.
129-
# e.g., 'rhdocs' will create the table 'vector_store_rhdocs'.
130-
# If the table was already created, this value must match the ID used at creation.
131-
vector_store_id: rhdocs
106+
byok_rag:
107+
- rag_id: pgvector-example
108+
rag_type: remote::pgvector
109+
embedding_model: sentence-transformers/all-mpnet-base-v2
110+
embedding_dimension: 768
111+
vector_db_id: rhdocs # becomes PostgreSQL table 'vector_store_rhdocs'
112+
host: ${env.POSTGRES_HOST}
113+
port: ${env.POSTGRES_PORT}
114+
db: ${env.POSTGRES_DATABASE}
115+
user: ${env.POSTGRES_USER}
116+
password: ${env.POSTGRES_PASSWORD}
132117
```
133118

134119
> [!NOTE]
135-
> For pgvector, the PostgreSQL connection details (host, port, database, user, password) are configured
136-
> in the provider configuration. Use environment variables for credentials.
120+
> Connection fields (`host`, `port`, `db`, `user`, `password`) default to `${env.POSTGRES_*}`
121+
> environment variable references when omitted. Use environment variables for credentials.
137122

138123
---
139124

0 commit comments

Comments
 (0)