feat: FastAPI+SSE API server, JRXML auto-reorder, session integrity fixes

2026-05-22 17:53:59 +08:00
parent 1144a86d02
commit 1e5ce9725b
32 changed files with 9189 additions and 309 deletions
@@ -0,0 +1,91 @@
+# RAG 知识库集成说明
+
+## 概述
+
+使用 `rag_jrxml` 子项目的语义分块管线替换原有的简单向量知识库。`rag_jrxml` 独立运行产出 ChromaDB，主项目通过 `backend/rag_adapter.py` 查询。
+
+## 架构
+
+```
+rag/                              ← git submodule (rag_jrxml)
+├── jrxml_source/                 ← 源数据目录 (242 .jrxml + 16 .md)
+├── models/                       ← 嵌入模型本地存放
+│   └── paraphrase-multilingual-MiniLM-L12-v2/   (449MB, 384维)
+├── jrxml_source_chunks/          ← 分块产物 (all_chunks.json, 15,510 chunks)
+├── embeddings/                   ← 向量产物 (embeddings.npy, 23MB)
+
+db/chroma/                        ← ChromaDB 持久化 (主项目查询端读取)
+│   集合: jrxml_chunks (15,510 条记录, cosine 距离)
+
+backend/rag_adapter.py            ← RAGSearcher: 加载模型 + 连接 ChromaDB + 搜索
+agent/nodes.py                    ← retrieve() 调用 search_chunks()
+```
+
+## 管线流程
+
+```
+源文件 (.jrxml + .md)
+  → batch_chunker.py    语义分块 (按 XML 元素/标题层级切分)
+  → embed_chunks.py     向量化 (Sentence-Transformers, CPU)
+  → import_to_chroma.py 导入 ChromaDB
+  → rag_adapter.py      主项目查询
+```
+
+## 当前数据
+
+| 指标 | 数值 |
+|---|---|
+| 源文件 | 258 (242 JRXML + 16 MD) |
+| Chunks 总数 | 15,510 |
+| 嵌入维度 | 384 |
+| 嵌入模型 | sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 |
+| 分块类型 | query, field, parameter, variable, band_*, chart, crosstab, element_*, section_* 等 |
+| 知识库大小 | embeddings.npy 23MB, ChromaDB ~50MB |
+
+## 主项目配置
+
+`.env` 中相关变量：
+
+```env
+# 嵌入模型 (本地路径优先)
+RAG_EMBED_MODEL=./rag/models/paraphrase-multilingual-MiniLM-L12-v2
+# ChromaDB 路径
+RAG_CHROMA_PATH=./db/chroma
+# 集合名称 (与 rag 子项目一致)
+RAG_COLLECTION_NAME=jrxml_chunks
+```
+
+## 全量构建
+
+```bash
+cd rag
+python batch_chunker.py jrxml_source
+python embed_chunks.py jrxml_source_chunks/all_chunks.json
+python import_to_chroma.py --chroma_path ../db/chroma
+```
+
+## 增量更新
+
+```bash
+# 1. 将新的 .jrxml / .md 放入 rag/jrxml_source/
+# 2. 增量运行
+cd rag
+python batch_chunker.py jrxml_source --incremental
+python embed_chunks.py --incremental
+python import_to_chroma.py --chroma_path ../db/chroma --incremental
+```
+
+## 更新 rag 子项目
+
+```bash
+git submodule update --remote rag
+```
+
+## 搜索接口
+
+```python
+from backend.rag_adapter import search_chunks
+
+# 返回拼接好的上下文字符串，可直接注入 LLM prompt
+context = search_chunks("如何创建饼图", k=5)
+```