From f9f362b127156080abf12c7ed7e4972e5b69d15e Mon Sep 17 00:00:00 2001 From: are-ces <195810094+are-ces@users.noreply.github.com> Date: Tue, 9 Jun 2026 09:52:23 +0200 Subject: [PATCH] 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 --- docs/byok_guide.md | 8 +++ docs/migrations/v0.7.0.md | 128 ++++++++++++++++++++++++++++++++++++++ docs/rag_guide.md | 14 +++++ 3 files changed, 150 insertions(+) create mode 100644 docs/migrations/v0.7.0.md diff --git a/docs/byok_guide.md b/docs/byok_guide.md index aae702b29..48898d285 100644 --- a/docs/byok_guide.md +++ b/docs/byok_guide.md @@ -113,6 +113,14 @@ Before implementing BYOK, ensure you have: ## Configuration Guide +> [!WARNING] +> **Deprecated in 0.7.0**: The top-level `byok_rag`, `rag`, `okp`, and `reranker` sections +> are deprecated. In 0.7.0, all RAG-related configuration is unified under a single `rag` +> section: BYOK stores move to `rag.byok.stores` (with `backend` instead of `rag_type`), +> retrieval strategies move to `rag.retrieval.inline`/`rag.retrieval.tool`, OKP moves to +> `rag.okp`, and the reranker moves to `rag.retrieval.inline.reranker`. +> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for full details and examples. + ### Step 1: Prepare Your Knowledge Sources 1. **Collect your documents**: Gather all knowledge sources you want to include diff --git a/docs/migrations/v0.7.0.md b/docs/migrations/v0.7.0.md new file mode 100644 index 000000000..3e28063fb --- /dev/null +++ b/docs/migrations/v0.7.0.md @@ -0,0 +1,128 @@ +# Migrating to v0.7.0 + +## Table of Contents + +* [RAG Configuration](#rag-configuration) + +--- + +## RAG Configuration + +In v0.7.0, the RAG configuration in `lightspeed-stack.yaml` is unified under a single `rag` section. The four separate top-level sections (`byok_rag`, `rag`, `okp`, `reranker`) are replaced by a nested structure that groups BYOK stores, OKP settings, retrieval strategies, and reranker settings together. The `rag_type` field is renamed to `backend` and the `inline::`/`remote::` prefix is dropped (e.g. `inline::faiss` becomes `faiss`). Hardcoded chunk limit constants are now user-configurable fields with sensible defaults. + +### Field Mapping + +| Old config path | New config path | Notes | +|---|---|---| +| `byok_rag` (top-level list) | `rag.byok.stores` | Moved under `rag.byok` | +| `byok_rag[].rag_type` | `rag.byok.stores[].backend` | Drop the `inline::`/`remote::` prefix (e.g. `inline::faiss` becomes `faiss`) | +| `rag.inline` (list of IDs) | `rag.retrieval.inline.sources` | Moved under `rag.retrieval.inline` | +| `rag.tool` (list of IDs) | `rag.retrieval.tool.sources` | Moved under `rag.retrieval.tool` | +| `okp` (top-level section) | `rag.okp` | Moved under `rag` | +| `BYOK_RAG_MAX_CHUNKS` constant | `rag.byok.max_chunks` | Default: 10 | +| `OKP_RAG_MAX_CHUNKS` constant | `rag.okp.max_chunks` | Default: 5 | +| `INLINE_RAG_MAX_CHUNKS` constant | `rag.retrieval.inline.max_chunks` | Default: 10 | +| `TOOL_RAG_MAX_CHUNKS` constant | `rag.retrieval.tool.max_chunks` | Default: 10 | +| `reranker` (top-level section) | `rag.retrieval.inline.reranker` | Moved under `rag.retrieval.inline` | + +--- + +### Before / After Examples + +#### Full RAG Configuration Example + +**Before (v0.6.x):** + +```yaml +byok_rag: + - rag_id: ocp-docs + rag_type: inline::faiss + embedding_model: sentence-transformers/all-mpnet-base-v2 + embedding_dimension: 768 + vector_db_id: vs_123 + db_path: /tmp/ocp.faiss + score_multiplier: 1.0 + - rag_id: knowledge-base + rag_type: inline::faiss + embedding_model: sentence-transformers/all-mpnet-base-v2 + embedding_dimension: 768 + vector_db_id: vs_456 + db_path: /tmp/kb.faiss + score_multiplier: 1.2 + +rag: + inline: + - ocp-docs + - knowledge-base + - okp + tool: + - ocp-docs + - knowledge-base + +okp: + rhokp_url: ${env.RH_SERVER_OKP} + offline: true + # chunk_filter_query: "product:*ansible* AND product:*openshift*" + +reranker: + enabled: true + model: cross-encoder/ms-marco-MiniLM-L6-v2 +``` + +**After (v0.7.0):** + +```yaml +rag: + byok: + max_chunks: 10 # Was BYOK_RAG_MAX_CHUNKS constant + stores: + - rag_id: ocp-docs + backend: faiss # Was 'rag_type: inline::faiss' + embedding_model: sentence-transformers/all-mpnet-base-v2 + embedding_dimension: 768 + vector_db_id: vs_123 + db_path: /tmp/ocp.faiss + score_multiplier: 1.0 + - rag_id: knowledge-base + backend: faiss # Was 'rag_type: inline::faiss' + embedding_model: sentence-transformers/all-mpnet-base-v2 + embedding_dimension: 768 + vector_db_id: vs_456 + db_path: /tmp/kb.faiss + score_multiplier: 1.2 + + okp: + rhokp_url: ${env.RH_SERVER_OKP} + offline: true + max_chunks: 5 # Was OKP_RAG_MAX_CHUNKS constant + # chunk_filter_query: "product:*ansible* AND product:*openshift*" + + retrieval: + inline: + sources: + - ocp-docs + - knowledge-base + - okp + max_chunks: 10 # Was INLINE_RAG_MAX_CHUNKS constant + reranker: + enabled: true + model: cross-encoder/ms-marco-MiniLM-L6-v2 + tool: + sources: + - ocp-docs + - knowledge-base + max_chunks: 10 # Was TOOL_RAG_MAX_CHUNKS constant +``` + +--- + +### Chunk Limits + +Chunk limits were previously hardcoded as constants in `src/constants.py`. They are now configurable fields in `lightspeed-stack.yaml` with the same default values: + +| Old constant | New config field | Default | +|---|---|---| +| `BYOK_RAG_MAX_CHUNKS` | `rag.byok.max_chunks` | 10 | +| `OKP_RAG_MAX_CHUNKS` | `rag.okp.max_chunks` | 5 | +| `INLINE_RAG_MAX_CHUNKS` | `rag.retrieval.inline.max_chunks` | 10 | +| `TOOL_RAG_MAX_CHUNKS` | `rag.retrieval.tool.max_chunks` | 10 | diff --git a/docs/rag_guide.md b/docs/rag_guide.md index 490e413ef..54a910749 100644 --- a/docs/rag_guide.md +++ b/docs/rag_guide.md @@ -63,6 +63,14 @@ Download a local embedding model such as `sentence-transformers/all-mpnet-base-v ## Configure BYOK Knowledge Sources +> [!WARNING] +> **Deprecated in 0.7.0**: The top-level `byok_rag`, `rag`, `okp`, and `reranker` sections +> are deprecated. In 0.7.0, all RAG-related configuration is unified under a single `rag` +> section: stores move to `rag.byok.stores` (with `backend` instead of `rag_type`), +> retrieval strategies move to `rag.retrieval.inline`/`rag.retrieval.tool`, OKP moves to +> `rag.okp`, and the reranker moves to `rag.retrieval.inline.reranker`. +> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for full details and examples. + 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. ### FAISS example @@ -312,6 +320,12 @@ Example: **Chunk volume:** +> [!WARNING] +> **Deprecated in 0.7.0**: The chunk limit constants below are replaced by configurable +> fields in `lightspeed-stack.yaml` (`rag.byok.max_chunks`, `rag.okp.max_chunks`, +> `rag.retrieval.inline.max_chunks`, `rag.retrieval.tool.max_chunks`). +> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for details. + OKP and BYOK scores are not directly comparable (different scoring systems), so `score_multiplier` (a BYOK-only concept) does not apply to OKP results. To control the number of retrieved chunks, set the constants in `src/constants.py`: