jhzhang/rag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: RAG数据流程新增缓存/图片/VLM/切片/性能章节 + 待解决风险项

Browse Source 
- RAG数据流程.md: 更新模型配置为 deepseek-v4-flash，补充 v7.1 变更
- 新增十二~十六章节：缓存系统、图片选择管线、VLM 懒加载、
  文档解析与切片、性能插桩
- 待解决风险项.md: 记录 7 个已识别但未实施的风险项
This commit is contained in:
lacerate551
2026-06-21 20:25:25 +08:00
parent 6d5a4b5b5e
commit 475900e103
2 changed files with 446 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
docs/RAG数据流程.md
View File

@@ -67,18 +67,27 @@
| 用途 | 模型 | 说明 | | 用途 | 模型 | 说明 |
|------|------|------| |------|------|------|
| 主 LLM | qwen3.6-flash | 回答生成、上下文理解 | | 主 LLM | deepseek-v4-flash | 回答生成、上下文理解 |
| 意图分析 | qwen-turbo | 轻量快速，用于问题改写与意图判断 | | 意图分析 | deepseek-v4-flash | JSON 结构化输出（`INTENT_RESPONSE_FORMAT=True`） |
| VLM | qwen-vl-plus | 图片理解与描述生成 | | VLM | qwen-vl-plus | 图片理解与描述生成 |
| 云端重排序 | qwen3-rerank | DashScope API 调用，替代本地 BGE-reranker | | 云端重排序 | qwen3-rerank | DashScope API 调用 |
| 本地重排序 | bge-reranker-base | ONNX Runtime，用于图片 CrossEncoder 二次评分 |
| Embedding | bge-base-zh-v1.5 | 文本向量化 |
### 1.3 v7.0.0 架构变更要点 ### 1.3 架构变更要点
- **Reranker**：从本地 BGE-reranker 切换为云端 DashScope API（qwen3-rerank） - **Reranker**：从本地 BGE-reranker 切换为云端 DashScope API（qwen3-rerank），本地 reranker 保留用于图片 CrossEncoder 二次评分
- **MMR 去重**：使用文本相似度模式（`MMR_USE_EMBEDDING=false`），基于 Jaccard 系数 - **MMR 去重**：使用文本相似度模式（`MMR_USE_EMBEDDING=false`），基于 Jaccard 系数
- **Agentic 引擎**：拆分为多个子模块（agentic_search / agentic_answer / agentic_citation 等） - **Agentic 引擎**：拆分为多个子模块（agentic_search / agentic_answer / agentic_citation 等）
- **Graph RAG**：模块已清空，不再使用 - **Graph RAG**：模块已清空，不再使用
**v7.1 新增变更**：
- **性能插桩**：`/rag` 流式响应新增 `stages_ms` 字段，记录 8 个管线阶段耗时（intent / cache / search / vlm / image / rescue / llm / post）
- **CrossEncoder 图片二次评分**：`select_images` 最终排序前新增 P3 阶段，用本地 bge-reranker-base 对 `(query, vlm_desc)` 做语义精排，映射为 ±5 分调整量；CE 负分图片直接剔除
- **意图分析 JSON 强制输出**：新增 `INTENT_RESPONSE_FORMAT` 配置开关，推理模型需设为 False
- **缓存管理端点**：新增 `POST /cache/clear` 一键清除精确缓存 + 语义缓存
--- ---
## 二、请求入口 ## 二、请求入口
@@ -340,8 +349,11 @@ enhance_retrieved_chunks(contexts, query, kb_name)
| 查询类型 | 参数调整 | | 查询类型 | 参数调整 |
|----------|----------| |----------|----------|
| 精确图号查询（"图2.3"） | `MAX_IMAGES=2, MIN_SCORE=5.0` | | 精确图号查询（"图2.3"） | `MAX_IMAGES=2, MIN_SCORE=5.0` |
| 弱图片意图（"发电量图"） | `MAX_IMAGES=1` | | 数据驱动（检索含图片切片） | `MAX_IMAGES=5, MIN_SCORE=2.0` |
| 普通查询 | `MAX_IMAGES=2` | | 文本引用图表 | `MAX_IMAGES=3, MIN_SCORE=2.0` |
| 普通查询 | `MAX_IMAGES=2, MIN_SCORE=3.0` |
表格嵌入图片时 `MAX_IMAGES` 可扩展至 15。
**步骤二：提取图表引用** **步骤二：提取图表引用**
@@ -359,18 +371,37 @@ referenced_figures = {'2.3': {'source_file': 'xxx.pdf'}, ...}
|--------|------| |--------|------|
| 图号精确匹配（查询中有"图2.3"） | +10 分 | | 图号精确匹配（查询中有"图2.3"） | +10 分 |
| 表号精确匹配 | +10 分 | | 表号精确匹配 | +10 分 |
| 关键词匹配（"发电量"等） | +2 分/个 | | 关键词匹配（"发电量"等） | +2 分/个，上限 8 |
| 字符重叠 | +0.2 分/字符 | | 字符重叠 | +0.2 分/字符，上限 3 |
| 章节匹配 | +1.5 分 | | 章节匹配 | +1.5 分 |
| 图片类型（chart > image） | +2 / +1 分 | | 图片类型（chart > image） | +2 / +1 分 |
| 向量相似度 | +2 分（最高） |
| 引用匹配（需章节相关） | +8 分 |
**步骤四：图文关联补充** **步骤四：VLM 与章节关联调整**
遍历 top 5 文本块中引用的图表编号，查找对应的图片切片并补充到结果中。 | 条件 | 调整 |
|------|------|
| VLM 描述与查询相关（`_check_vlm_relevance >= 0.5`） | +2 分 |
| VLM 描述与查询不相关（`< 0.3`） | -3 分 |
| 图片章节与主检索不匹配（`section_similarity < 0.3`） | -5 分 |
| 图号/表号被文本引用 + 章节匹配 | +8~+13 分 |
| 来源文件匹配 primary_sources | +2 分 |
**步骤五：返回 top N 图片** **步骤五：CrossEncoder 语义精排（P3）**
对所有过线候选图片，用本地 bge-reranker-base 对 `(query, vlm_desc_or_caption)` 做二次评分：
```python
ce_scores = engine.reranker.predict([(query, desc) for desc in descriptions])
# 映射：ce_score > 0 → adjustment ∈ (0, +5]，ce_score < 0 → adjustment ∈ [-5, 0)
img['score'] += adjustment
# CE 负分图片直接剔除
```
**步骤六：后置过滤**
`_filter_images_by_answer()` 根据 LLM 回答内容反向筛选图片，过滤回答中未提及的无关图片。
**步骤七：返回 top N 图片**
```python ```python
scored_images.sort(key=lambda x: x['score'], reverse=True) scored_images.sort(key=lambda x: x['score'], reverse=True)
@@ -607,3 +638,279 @@ VLM 描述示例（更精准）：
| `parsers/mineru_parser.py` | 文档解析 | `parse_with_mineru()`, `MinerUChunk` | | `parsers/mineru_parser.py` | 文档解析 | `parse_with_mineru()`, `MinerUChunk` |
| `knowledge/manager.py` | 知识库管理 | `add_file_to_kb()`, `generate_lightweight_image_description()` | | `knowledge/manager.py` | 知识库管理 | `add_file_to_kb()`, `generate_lightweight_image_description()` |
| `knowledge/lazy_enhance.py` | 懒加载增强 | `lazy_vlm_description()`, `enhance_retrieved_chunks()` | | `knowledge/lazy_enhance.py` | 懒加载增强 | `lazy_vlm_description()`, `enhance_retrieved_chunks()` |
| `core/cache.py` | 三层精确缓存 | `RAGCacheManager`, `get_cache_manager()` |
| `core/semantic_cache.py` | 语义缓存 | `SemanticCache`, `get_semantic_cache()` |
| `knowledge/image_cleanup.py` | 孤儿文件清理 | `cleanup_image_orphans()`, `collect_referenced_images()` |
| `cleanup_orphans.py` | 孤儿文件清理脚本 | `--force` 执行删除，默认 dry-run |
| `sync_vlm_cache.py` | VLM 缓存同步 | `--re-embed` 强制重算 embedding |
| `eval_image_retrieval.py` | 图片检索评测 | 检索层 + 选择层分层评测 |
---
## 十二、缓存系统
### 12.1 三层精确缓存（core/cache.py）
`RAGCacheManager` 管理三个独立的 `LRUCache` 实例：
| 缓存层 | Key 构造 | TTL | 容量 | kb_version 关联 |
|--------|----------|-----|------|-----------------|
| Query Cache | `MD5(query:kb_name:kb_version)` | 1h | 500 | ✅ 版本失效 |
| Embedding Cache | `MD5(emb:{text})` | 24h | 2000 | ✅ 版本失效 |
| Rerank Cache | `MD5(rerank:{query}:{sorted_doc_ids})` | 1h | 1000 | ❌ 变更时全清空 |
**知识库版本失效机制**：
```python
def increment_kb_version(kb_name):
old_version = self._kb_versions.get(kb_name, 0)
self._kb_versions[kb_name] = old_version + 1
# 失效旧版本
self.query_cache.invalidate_by_version(old_version)
self.embedding_cache.invalidate_by_version(old_version)
self.rerank_cache.clear() # Rerank 无 kb_version，全量清空
```
`sync.py` 文档变更时调用 `increment_kb_version()` 触发失效。
**写入保护**：`CACHE_MIN_SCORE = 0.3`，检索结果最高分低于此值时不写缓存，避免低质量结果被缓存。
### 12.2 语义缓存（core/semantic_cache.py）
`SemanticCache` 使用 FAISS 向量索引实现语义级缓存：
```
查找：query_embedding → FAISS ANN 搜索 → 余弦相似度 > 0.92 → 候选
二次验证：Jaccard(query, cached._raw_query) >= 0.5 → 确认命中
存储：query_embedding + result → FAISS add
```
**Jaccard 二次验证**（字符级）：
```python
set_a = set(query) # 字符集合
set_b = set(cached_query)
similarity = |intersection| / |union|
```
**Intent 与 RAG 共用 FAISS 索引**，通过 `cache_type` 字段隔离：
| 缓存类型 | cache_type 值 | Embedding 输入 | 读取条件 |
|----------|---------------|---------------|---------|
| RAG 回答 | `"rag_answer"` | `embedding(query|collections)` | `cache_type == "rag_answer"` |
| 意图分析 | `"intent_analysis"` | `embedding(query)` | `cache_type != "rag_answer"` |
**容量管理**：默认 `max_size=10000`，达到上限时 `self.clear()` 全清空（非 LRU 淘汰）。
**Intent 精确缓存**（独立于 FAISS）：`_exact_cache: Dict[str, IntentAnalysis]`，key = `query + 最近2条历史摘要`，上限 500 条，无 TTL，满后停止接收新条目。
### 12.3 缓存命中链路
一个 `/rag` 请求依次经过以下缓存检查点：
```
请求进入 chat_routes.rag()
│
├─ ① 语义缓存读取（FAISS）
│ key = embedding(retrieval_query|collections)
│ 要求 cache_type == "rag_answer"
│ 二次验证: Jaccard >= 0.5
│ ├─ 命中 → 直接流式返回缓存答案，流程结束
│ └─ 未命中 → 继续
│
├─ ② intent_analyzer.analyze()
│ ├─ 精确缓存: key = query + 历史摘要
│ ├─ 语义缓存: key = embedding(query)，cache_type != "rag_answer"
│ └─ 未命中 → 调 LLM → 写入两层缓存
│
├─ ③ engine.search()
│ ├─ Query Cache: MD5(query:kb_name:kb_version)
│ ├─ Embedding Cache: MD5(emb:{text})
│ └─ Rerank Cache: MD5(rerank:{query}:{sorted_doc_ids})
│
├─ ④ LLM 生成回答
│
└─ ⑤ 语义缓存写入（FAISS）
存入 { cache_type: "rag_answer", answer, sources, images, _raw_query }
```
**缓存清除**：`POST /cache/clear` 端点清除 Query/Embedding/Rerank 缓存 + 语义缓存（需网关认证）。
---
## 十三、图片选择管线
### 13.1 评分流程（select_images）
完整的图片选择管线包含 7 个阶段：
```
score_image_relevance() ← P1: 基础分（关键词/图号/章节/类型）
↓
VLM 相关性调整 ← _check_vlm_relevance() -3 / +2 分
↓
章节关联惩罚 ← section_similarity < 0.3 → -5 分
↓
图号/表号引用加分 ← 文本引用匹配 → +8~+13 分
↓
来源文件加分 ← primary_sources 匹配 → +2 分
↓
MIN_SCORE 过滤 ← 动态阈值 2.0~5.0
↓
CrossEncoder 二次评分 ← P3: 本地 reranker 对 (query, desc) 精排
↓ 正相关 +5，负相关 -5 且直接剔除
MAX_IMAGES 预算控制 ← 动态上限 2~15 张
↓
_filter_images_by_answer() ← 后置过滤：LLM 回答关键词重叠
```
### 13.2 图片召回保障
图片切片在检索层面临 CrossEncoder 系统性低分（0.002~0.08 vs 文本 0.3~0.9），有多重保障机制：
| 机制 | 位置 | 说明 |
|------|------|------|
| 图片独立召回 | `engine._search_image_chunks()` | 对 image/chart 切片单独查询 ChromaDB |
| `_image_boost` 标记 | `chat_routes.py` | 图片意图查询时，为匹配的图片切片打 1.5x/2.0x boost 标记 |
| 章节聚类救援 | `_rescue_section_cluster()` | 当整章节切片全被 rerank 压制时，保底分配分数 |
| BM25 分歧救援 | `_rescue_bm25_divergence()` | BM25 高排名但 rerank 低分的切片被恢复 |
| 词法匹配救援 | `_rescue_lexical_match()` | 切片文本精确包含查询关键词时提升分数 |
---
## 十四、VLM 懒加载增强
**入口文件**：`knowledge/lazy_enhance.py`
**触发位置**：`chat_routes.py` `generate()` 函数
### 14.1 触发条件
| 切片类型 | 触发条件 | 调用模型 |
|----------|---------|---------|
| image / chart | `has_vlm_desc=False` 且 `image_path` 非空 | VLM（qwen-vl-plus） |
| table | `has_summary=False` 且 `score > 0.7` | LLM（表格摘要） |
| table + 关联图片 | `has_vlm_desc=False` 且 `image_path` 非空 | VLM |
### 14.2 增强流程
```
缓存检查（图片 MD5 哈希 → .data/cache/vlm/{hash}.txt）
├─ 缓存命中（内容 ≥ 5 字符）→ 直接返回
└─ 缓存未命中 →
├─ 调用 VLM/LLM 生成描述/摘要
├─ 空描述保护（< 5 字符）→ 不写缓存，不更新向量库
├─ 写入缓存文件
└─ 更新 ChromaDB
├─ metadata: { has_vlm_desc: True, vlm_desc: description }
├─ embedding: 用 VLM 描述重新计算向量（通过 RAGEngine 单例获取模型）
└─ document: 更新为 VLM 描述文本
```
**embedding 模型获取**：`KnowledgeBaseManager` 没有 `embedding_model` 属性，通过 `_get_embedding_model()` 从 `RAGEngine` 单例获取。
### 14.3 后台异步化
VLM/LLM 调用在后台线程执行，不阻塞主流程：
```python
# chat_routes.py 中
_bg_contexts = copy.deepcopy(contexts) # 深拷贝避免线程竞争
_t = threading.Thread(target=_background_enhance, daemon=True)
_t.start()
# 主流程继续 select_images + LLM 生成
```
后台线程使用 `asyncio.run()` + 60s 超时保护。首次查询时图片使用 caption + section 作为临时描述，后台生成完成后写入 ChromaDB，下次查询直接使用缓存。
---
## 十五、文档解析与切片
### 15.1 MinerU 解析流程
**入口文件**：`parsers/mineru_parser.py`
支持两种云端 API 模式：
| 模式 | 端点 | 延迟 | 适用场景 |
|------|------|------|---------|
| v4 precise | `/api/v4/` | 较长（需排队） | 高精度 PDF 解析 |
| v1 agent | `/api/v1/agent/` | ~10s | 轻量级文档处理 |
**V2 格式转换**（`_parse_v2_content_list`）：
MinerU 返回的 content_list 被转换为 `MinerUChunk` 对象，提取的字段包括：`_v2_table_type`、`_v2_table_nest_level`、`_v2_list_type`、`sub_type`（部分字段在下游切片时被丢弃）。
**标题检测**（`parsers/heading_rules.py`）：
基于规则的多级标题检测，`_validate_level()` 长度守卫防止长文本误判为标题：
| 级别 | 最大长度 | 超出后 |
|------|---------|--------|
| H1 | 40 字符 | 降级为普通文本 |
| H2 | 60 字符 | 降级为普通文本 |
| H3 | 50 字符 | 降级为普通文本 |
`chinese_article` 规则额外限制 `max_length=30`，`numeric_level1` 排除以标点结尾的误判。
### 15.2 切片后处理
**`_post_process_chunks`** 核心逻辑：
1. **连续标题链合并**：连续 title 类切片合并为一个 chunk（保留最高 text_level）
2. **body 合并后 text_level 重置**：body 合并进 title buffer 后执行 `buffer.text_level = 0`，防止下一个标题被错误合并
3. **元数据写入**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `chunk_type` | str | `text` / `title` / `table` / `image` / `chart` |
| `section` | str | 章节路径（如 `综述 > 2.3发电`） |
| `text_level` | int | 标题级别（0=body, 1=H1, 2=H2, 3=H3） |
| `image_path` | str | 图片文件名 |
| `bbox` | str | 页面坐标（仅 PDF） |
| `has_vlm_desc` | bool | 是否已有 VLM 描述 |
---
## 十六、性能插桩
**入口文件**：`api/chat_routes.py` `generate()` 函数
### 16.1 各阶段计时
在 SSE 流式生成器中初始化计时字典，记录 8 个管线阶段耗时：
| 阶段 key | 记录时机 | 覆盖范围 |
|----------|----------|----------|
| `intent` | 意图分析完成后 | IntentAnalyzer.analyze() |
| `cache` | 语义缓存检查后 | semantic_cache.lookup() |
| `search` | 混合检索+切片处理完成后 | engine.search() + 上下文提取 |
| `vlm` | VLM 懒加载完成后 | enhance_retrieved_chunks() |
| `image` | select_images 完成后 | 图片选择 |
| `rescue` | 救援管线+上下文构建完成后 | 聚类/BM25/预算 |
| `llm` | LLM 流式生成完成后 | engine.generate_answer_stream() |
| `post` | finish 事件构建完成后 | 答案对齐+debug 事件 |
### 16.2 数据输出
**SSE finish 事件**：
```json
{
"type": "finish",
"timing": {
"total_ms": 12345,
"stages_ms": {
"intent": 4200, "cache": 50, "search": 900,
"vlm": 10, "image": 30, "rescue": 200,
"llm": 6800, "post": 150
}
}
}
```
**服务端日志**：
```
[性能] 总12345ms | 意图4200 缓存50 检索900 VLM10 图片30 救援200 LLM6800 后处理150
```

125
docs/待解决风险项.md Normal file
View File

@@ -0,0 +1,125 @@
# 待解决风险项
> 本文档记录已识别但尚未实施修复的风险项，供后续迭代参考。
> 更新日期：2026-06-21
---
## P1: SemanticCache 满容量全清空
**文件**：`core/semantic_cache.py:161-164`
**现状**：当 FAISS 索引达到 `max_size`（默认 10000）时，执行 `self.clear()` 全清空，而非 LRU 淘汰最旧条目。
**影响**：高使用量下缓存命中率周期性断崖式下降，下一波请求全部 miss。
**建议方案**：
- 短期：可接受，断崖后缓存会重新积累
- 长期：改为分批淘汰（每次淘汰最旧 N 条），或引入 TTL 自动过期
**风险等级**：中（性能波动，不影响正确性）
---
## P2: _exact_cache 满后永久拒绝新条目
**文件**：`core/intent_analyzer.py:412-413`
**现状**：
```python
if len(self._exact_cache) < self._exact_cache_max: # 500
self._exact_cache[exact_key] = analysis
```
500 条满后不再接受新条目，且无淘汰机制。服务运行一段时间后，精确缓存变为固定快照。
**影响**：后续查询的精确缓存命中率逐渐归零，退化为每次都走语义缓存或 LLM 调用。
**建议方案**：改用 `OrderedDict` + 淘汰最旧条目，与 `LRUCache` 保持一致。
**风险等级**：低（性能退化，不影响正确性）
---
## P3: Jaccard 字符级阈值偏松
**文件**：`core/intent_analyzer.py:450-473`
**现状**：语义缓存二次验证使用字符级 Jaccard 相似度，阈值 0.5。中文短句共享大量单字（如"如何申请" vs "如何拒绝"），Jaccard = 2/4 = 0.5 刚好过线。
**影响**：语义相似但意图不同的查询可能误命中缓存。
**建议方案**：
- 方案 A：提升阈值到 0.6
- 方案 B：改用 bigram Jaccard（相邻字对作为集合元素）
**风险等级**：低（误命中概率不高，且有 embedding 0.92 阈值前置过滤）
---
## P4: /cache/clear 无 DEV_MODE 守卫
**文件**：`api/sync_routes.py:322`
**现状**：`POST /cache/clear` 端点仅使用 `@require_gateway_auth`，没有 `DEV_MODE` 检查。生产环境任何认证用户都能清缓存。其他 dev-only 端点（如 `document_routes.py` 的预览接口）有 `DEV_MODE` 守卫。
**影响**：生产环境缓存被误清，导致短暂的性能下降。
**建议方案**：添加 `DEV_MODE` 检查，或限制为 admin 角色。
**风险等级**：中（生产环境影响）
---
## P5: PDF TOC 目录数据未单独处理
**文件**：`parsers/mineru_parser.py`
**现状**：PDF 文档的目录页（TOC）被 MinerU 解析为多个 text_level=1 的标题切片，内容包含 `....1` 等页码标记。这些目录切片入库后污染 section 元数据，干扰章节过滤和上下文扩展。
**影响**：RAG 检索时目录切片可能被误判为相关章节，干扰上下文扩展的 section 精确匹配。
**建议方案**：
- 解析阶段检测 TOC 模式（连续短标题 + 页码标记）
- 标记 `chunk_type: 'toc'` 或直接跳过不入库
**风险等级**：中（影响检索质量）
---
## P6: PDF chart VLM 描述缺失
**文件**：`knowledge/lazy_enhance.py`、`parsers/mineru_parser.py`
**现状**：部分 PDF 图表切片的 VLM 描述为空。原因可能是：
1. MinerU VLM API 对部分图表返回空 content（上游问题）
2. 解析阶段的提取条件过严（如要求 `'|' in markdown` 才提取 chart_markdown）
**影响**：无 VLM 描述的图表切片退化为纯关键词匹配，图片选择准确率下降。
**建议方案**：
- 上游：跟进 MinerU API 的空 content 问题
- 本地兜底：用 `caption + section + 上下文文本` 拼接作为 fallback 描述
- 定期重算：用 `sync_vlm_cache.py --re-embed` 批量重算
**风险等级**：低（有 lazy_enhance 兜底，首次查询后补生成）
---
## P7: 图片选择负面用例误召回
**文件**：`api/chat_routes.py`
**现状**：定义/原则类查询（如"五化终端定义"、"防洪调度原则"）不应返回图片，但 `select_images` 仍返回了 2-3 张。根因：
1. `_filter_images_by_answer` 的关键词重叠阈值对长回答偏宽松
2. 兜底逻辑：过滤后为空时保留分数最高的 1 张
**影响**：用户看到不相关的图片，降低信任度。
**建议方案**：
- 增加查询意图判断：纯定义/原则类查询不应触发图片返回
- 移除兜底逻辑或提高兜底阈值
- 增加"不应返回图片"的负面评测用例
**风险等级**：中（影响用户体验）