Skip to content

Commit ccebaff

Browse files
tisniktisnik
authored
Merge pull request #1856 from are-ces/lcore-2437-byok-pgvector-support-v2
LCORE-2437: Support pgvector in byok_rag enrichment script
2 parents 9e71ccc + 3feba12 commit ccebaff

8 files changed

Lines changed: 492 additions & 90 deletions

File tree

‎docs/byok_guide.md‎

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

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

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

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

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

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

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

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

392395
> [!NOTE]
393396
> For pgvector, ensure your PostgreSQL credentials are available via environment variables
394-
> (e.g., `POSTGRES_PASSWORD`).
397+
> (e.g., `POSTGRES_HOST`, `POSTGRES_PASSWORD`).
395398

396399
> [!TIP]
397400
> 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)