Skip to content

Commit 7ad310a

Browse files
are-cesclaude
are-ces
and
claude
authored
LCORE-2505: Add migration guide and deprecation notes for BYOK config refactoring (#1882)
* LCORE-2505: add migration guide and deprecation notes for BYOK config refactoring Add docs/migrations/v0.7.0.md with field mapping, full RAG before/after examples, and chunk limit migration table. Add deprecation callouts to byok_guide.md and rag_guide.md linking to the migration guide. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8efa018 commit 7ad310a

3 files changed

Lines changed: 150 additions & 0 deletions

File tree

‎docs/byok_guide.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,14 @@ Before implementing BYOK, ensure you have:
113113

114114
## Configuration Guide
115115

116+
> [!WARNING]
117+
> **Deprecated in 0.7.0**: The top-level `byok_rag`, `rag`, `okp`, and `reranker` sections
118+
> are deprecated. In 0.7.0, all RAG-related configuration is unified under a single `rag`
119+
> section: BYOK stores move to `rag.byok.stores` (with `backend` instead of `rag_type`),
120+
> retrieval strategies move to `rag.retrieval.inline`/`rag.retrieval.tool`, OKP moves to
121+
> `rag.okp`, and the reranker moves to `rag.retrieval.inline.reranker`.
122+
> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for full details and examples.
123+
116124
### Step 1: Prepare Your Knowledge Sources
117125

118126
1. **Collect your documents**: Gather all knowledge sources you want to include

‎docs/migrations/v0.7.0.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Migrating to v0.7.0
2+
3+
## Table of Contents
4+
5+
* [RAG Configuration](#rag-configuration)
6+
7+
---
8+
9+
## RAG Configuration
10+
11+
In v0.7.0, the RAG configuration in `lightspeed-stack.yaml` will be unified under a single `rag` section. The four separate top-level sections (`byok_rag`, `rag`, `okp`, `reranker`) will be replaced by a nested structure that groups BYOK stores, OKP settings, retrieval strategies, and reranker settings together. The `rag_type` field will be renamed to `backend` and the `inline::`/`remote::` prefix will be dropped (e.g. `inline::faiss` becomes `faiss`). Hardcoded chunk limit constants will become user-configurable fields with sensible defaults.
12+
13+
### Field Mapping
14+
15+
| Old config path | New config path | Notes |
16+
|---|---|---|
17+
| `byok_rag` (top-level list) | `rag.byok.stores` | Moved under `rag.byok` |
18+
| `byok_rag[].rag_type` | `rag.byok.stores[].backend` | Drop the `inline::`/`remote::` prefix (e.g. `inline::faiss` becomes `faiss`) |
19+
| `rag.inline` (list of IDs) | `rag.retrieval.inline.sources` | Moved under `rag.retrieval.inline` |
20+
| `rag.tool` (list of IDs) | `rag.retrieval.tool.sources` | Moved under `rag.retrieval.tool` |
21+
| `okp` (top-level section) | `rag.okp` | Moved under `rag` |
22+
| `BYOK_RAG_MAX_CHUNKS` constant | `rag.byok.max_chunks` | Default: 10 |
23+
| `OKP_RAG_MAX_CHUNKS` constant | `rag.okp.max_chunks` | Default: 5 |
24+
| `INLINE_RAG_MAX_CHUNKS` constant | `rag.retrieval.inline.max_chunks` | Default: 10 |
25+
| `TOOL_RAG_MAX_CHUNKS` constant | `rag.retrieval.tool.max_chunks` | Default: 10 |
26+
| `reranker` (top-level section) | `rag.retrieval.inline.reranker` | Moved under `rag.retrieval.inline` |
27+
28+
---
29+
30+
### Before / After Examples
31+
32+
#### Full RAG Configuration Example
33+
34+
**Before (v0.6.x):**
35+
36+
```yaml
37+
byok_rag:
38+
- rag_id: ocp-docs
39+
rag_type: inline::faiss
40+
embedding_model: sentence-transformers/all-mpnet-base-v2
41+
embedding_dimension: 768
42+
vector_db_id: vs_123
43+
db_path: /tmp/ocp.faiss
44+
score_multiplier: 1.0
45+
- rag_id: knowledge-base
46+
rag_type: inline::faiss
47+
embedding_model: sentence-transformers/all-mpnet-base-v2
48+
embedding_dimension: 768
49+
vector_db_id: vs_456
50+
db_path: /tmp/kb.faiss
51+
score_multiplier: 1.2
52+
53+
rag:
54+
inline:
55+
- ocp-docs
56+
- knowledge-base
57+
- okp
58+
tool:
59+
- ocp-docs
60+
- knowledge-base
61+
62+
okp:
63+
rhokp_url: ${env.RH_SERVER_OKP}
64+
offline: true
65+
# chunk_filter_query: "product:*ansible* AND product:*openshift*"
66+
67+
reranker:
68+
enabled: true
69+
model: cross-encoder/ms-marco-MiniLM-L6-v2
70+
```
71+
72+
**After (v0.7.0):**
73+
74+
```yaml
75+
rag:
76+
byok:
77+
max_chunks: 10 # Was BYOK_RAG_MAX_CHUNKS constant
78+
stores:
79+
- rag_id: ocp-docs
80+
backend: faiss # Was 'rag_type: inline::faiss'
81+
embedding_model: sentence-transformers/all-mpnet-base-v2
82+
embedding_dimension: 768
83+
vector_db_id: vs_123
84+
db_path: /tmp/ocp.faiss
85+
score_multiplier: 1.0
86+
- rag_id: knowledge-base
87+
backend: faiss # Was 'rag_type: inline::faiss'
88+
embedding_model: sentence-transformers/all-mpnet-base-v2
89+
embedding_dimension: 768
90+
vector_db_id: vs_456
91+
db_path: /tmp/kb.faiss
92+
score_multiplier: 1.2
93+
94+
okp:
95+
rhokp_url: ${env.RH_SERVER_OKP}
96+
offline: true
97+
max_chunks: 5 # Was OKP_RAG_MAX_CHUNKS constant
98+
# chunk_filter_query: "product:*ansible* AND product:*openshift*"
99+
100+
retrieval:
101+
inline:
102+
sources:
103+
- ocp-docs
104+
- knowledge-base
105+
- okp
106+
max_chunks: 10 # Was INLINE_RAG_MAX_CHUNKS constant
107+
reranker:
108+
enabled: true
109+
model: cross-encoder/ms-marco-MiniLM-L6-v2
110+
tool:
111+
sources:
112+
- ocp-docs
113+
- knowledge-base
114+
max_chunks: 10 # Was TOOL_RAG_MAX_CHUNKS constant
115+
```
116+
117+
---
118+
119+
### Chunk Limits
120+
121+
Chunk limits, currently hardcoded as constants, will be configurable fields in `lightspeed-stack.yaml` with the same default values:
122+
123+
| Old constant | New config field | Default |
124+
|---|---|---|
125+
| `BYOK_RAG_MAX_CHUNKS` | `rag.byok.max_chunks` | 10 |
126+
| `OKP_RAG_MAX_CHUNKS` | `rag.okp.max_chunks` | 5 |
127+
| `INLINE_RAG_MAX_CHUNKS` | `rag.retrieval.inline.max_chunks` | 10 |
128+
| `TOOL_RAG_MAX_CHUNKS` | `rag.retrieval.tool.max_chunks` | 10 |

‎docs/rag_guide.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,14 @@ Download a local embedding model such as `sentence-transformers/all-mpnet-base-v
6363

6464
## Configure BYOK Knowledge Sources
6565

66+
> [!WARNING]
67+
> **Deprecated in 0.7.0**: The top-level `byok_rag`, `rag`, `okp`, and `reranker` sections
68+
> are deprecated. In 0.7.0, all RAG-related configuration is unified under a single `rag`
69+
> section: stores move to `rag.byok.stores` (with `backend` instead of `rag_type`),
70+
> retrieval strategies move to `rag.retrieval.inline`/`rag.retrieval.tool`, OKP moves to
71+
> `rag.okp`, and the reranker moves to `rag.retrieval.inline.reranker`.
72+
> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for full details and examples.
73+
6674
BYOK knowledge sources are configured in the `byok_rag` section of `lightspeed-stack.yaml`. The required configuration is automatically generated at startup when using `make run`, `make run-stack`, `docker-compose`, or library mode — no manual enrichment is needed.
6775

6876
### FAISS example
@@ -297,6 +305,12 @@ Example:
297305

298306
**Chunk volume:**
299307

308+
> [!WARNING]
309+
> **Deprecated in 0.7.0**: The chunk limit constants below are replaced by configurable
310+
> fields in `lightspeed-stack.yaml` (`rag.byok.max_chunks`, `rag.okp.max_chunks`,
311+
> `rag.retrieval.inline.max_chunks`, `rag.retrieval.tool.max_chunks`).
312+
> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for details.
313+
300314
OKP and BYOK scores are not directly comparable (different scoring systems), so
301315
`score_multiplier` (a BYOK-only concept) does not apply to OKP results. To control
302316
the number of retrieved chunks, set the constants in `src/constants.py`:

0 commit comments

Comments
 (0)