RAG 架构方案

当前架构设计

整体流程

用户提问
    ↓
pipeline.ask(question, session_id)
    ↓
router.classify_intent(question) → intent
    ↓
retriever.search(query, top_k=3)  # 仅 kb_query / complex 时调用
    ↓
router.route(question, context, intent) → ModelConfig
    ↓
robot.ask(question, history, model_config)
    ↓
LLM 返回答案

核心组件

组件	当前实现	说明
向量库	chromadb	本地持久化存储，零运维
检索框架	LlamaIndex	直接读取 md 文件，支持向量检索
Embedding 模型	qwen/qwen3-embedding-8b	OpenRouter API，中文优化模型
索引构建	部署时自动重建	每次部署清空旧索引并重建
文档分块	MarkdownNodeParser	chunk_size=1024, chunk_overlap=100
检索策略	相似度 Top-K	默认 top_k=3

配置位置

Embedding 配置：router.py 的 EMBED_CONFIG
检索实现：retriever.py 的 search() 方法
索引路径：/srv/kb_index（环境变量 INDEX_PATH）
知识库路径：/srv/knowledge_base（环境变量 KB_PATH）

待优化事项

1. 替换为中文 Embedding 模型 ✅

现状：已替换为 qwen/qwen3-embedding-8b，针对中文语义优化。

实现方案：

在 router.py 中更新 EMBED_CONFIG 为 qwen/qwen3-embedding-8b
通过 OpenRouter API 调用，无需本地部署
重建索引后生效

体感验证方法：

相似度分数对比：
- 用相同问题查询，观察返回的 scores 是否更高
- 中文模型对中文问题的相似度通常 > 0.7，英文模型可能 < 0.5
检索准确性：
- 测试问题：「JVM 垃圾回收算法有哪些？」
- 观察返回的文档片段是否精准命中相关章节
- 中文模型应该能准确匹配「垃圾回收」「GC」等同义词
边界 case：
- 测试口语化问题：「怎么优化 Redis 性能」
- 中文模型对口语化表达的理解更好

预期提升：

检索召回率提升 15~30%
相似度分数平均提升 0.1~0.2
对同义词、口语化表达的匹配更准确

注意：需要重建索引（python retriever.py）才能使用新模型的向量。

2. 优化文档分块策略（Chunk）✅

现状：已实现自定义分块策略。

实现方案：

使用 MarkdownNodeParser 按 markdown 标题层级智能分块
配置 chunk_size=1024 和 chunk_overlap=100（可通过环境变量调整）
保留文档元信息（filename_as_id=True）

参数说明：

chunk_size (1024 字符)：每个分块的最大字符数
- 对于 100~~500 行的技术文档（约 4000~~20000 字符）
- 会被切分为 4~20 个分块
- 确保每个分块足够小以精准匹配问题
chunk_overlap (100 字符)：相邻分块的重叠部分
- 避免关键信息在边界被切断
- 提高检索召回率（边界内容在两个块中都存在）

索引重建：

部署时自动重建索引（约 50 个文档，耗时 < 1 分钟）
手动重建：python retriever.py
修改分块参数后需重建索引才能生效

实现位置：retriever.py 的 _get_node_parser() 和 _load_index()

3. 增量索引更新机制

现状：部署时全量 embedding，知识库更新需要重新构建全部索引。

目标：

支持增量更新：检测文件变更（新增/修改/删除）
只对变更文件重新 embedding
减少索引构建时间

方案：

记录文件 hash 或修改时间
对比变更文件列表
删除旧向量 + 插入新向量

4. 检索结果重排序（Rerank）

现状：直接使用向量相似度 Top-K，可能存在语义漂移。

目标：

引入 Rerank 模型（如 bge-reranker-large 或 LLM-based rerank）
先召回 Top-10，再精排 Top-3
提升检索精准度

5. 混合检索（Hybrid Search）

现状：纯向量检索，对关键词匹配不敏感。

目标：

结合 BM25 关键词检索 + 向量语义检索
融合两种检索结果（加权或 RRF）
提升召回率

6. 检索评估体系

现状：无量化指标，依赖人工判断。

目标：

构建测试问题集（Q&A pairs）
计算 MRR、NDCG、Recall@K
对比不同配置的检索效果

后续迭代

每完成一个事项，更新本文档的「当前架构设计」部分，记录：

修改的配置/代码位置
效果对比数据
遇到的问题与解决方案

参考资料

LLM Application 分层方案
LLM Router 成本控制方案
LlamaIndex 文档：https://docs.llamaindex.ai/
ChromaDB 文档：https://docs.trychroma.com/

2026-03-08-RAG架构方案