# 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)
```