Compare commits
10 Commits
ee5295cc97
...
a31ee4bba0
| Author | SHA1 | Date | |
|---|---|---|---|
|
a31ee4bba0 | ||
|
|
b966be5417 | ||
|
|
789610d01f | ||
|
|
e761af6111 | ||
|
|
8268071fdc | ||
|
|
4753a53487 | ||
|
|
63a769540a | ||
|
|
f0e5426b4d | ||
|
|
eb177e11e5 | ||
|
|
5ba0d782e2 |
6174
api/chat_routes.py
6174
api/chat_routes.py
File diff suppressed because it is too large
Load Diff
23
config.py
23
config.py
@@ -20,9 +20,13 @@ DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY", "")
|
||||
DASHSCOPE_BASE_URL = os.getenv("DASHSCOPE_BASE_URL", "https://token-plan-cn.xiaomimimo.com/v1")
|
||||
DASHSCOPE_MODEL = os.getenv("DASHSCOPE_MODEL", "mimo-v2.5") # 文本生成模型
|
||||
RAG_CHAT_MODEL = os.getenv("RAG_CHAT_MODEL", "mimo-v2.5") # RAG 对话模型
|
||||
INTENT_MODEL = os.getenv("INTENT_MODEL", "mimo-v2.5") # 意图分析模型
|
||||
INTENT_MODEL = os.getenv("INTENT_MODEL", "mimo-v2.5") # 意图分析模型（百炼额度用尽，切回 mimo）
|
||||
VLM_MODEL = os.getenv("VLM_MODEL", "mimo-v2.5") # 视觉语言模型（图片描述）
|
||||
|
||||
# 百炼 API（阿里云 DashScope，用于意图分析等轻量任务）
|
||||
BAILIAN_API_KEY = os.getenv("BAILIAN_API_KEY", "")
|
||||
BAILIAN_BASE_URL = os.getenv("BAILIAN_BASE_URL", "https://dashscope.aliyuncs.com/compatible-mode/v1")
|
||||
|
||||
# 兼容旧变量名（逐步迁移到 DASHSCOPE_* 命名）
|
||||
API_KEY = DASHSCOPE_API_KEY
|
||||
BASE_URL = DASHSCOPE_BASE_URL
|
||||
@@ -97,11 +101,12 @@ RERANK_DEVICE = os.getenv("RERANK_DEVICE", os.getenv("DEVICE", "auto"))
|
||||
# ----- 通用问答 -----
|
||||
LLM_TEMPERATURE = 0.7 # 生成温度（0=确定性，1=随机性）
|
||||
LLM_MAX_TOKENS = 3000 # 最大输出 token 数
|
||||
LLM_DISABLE_THINKING = os.getenv("LLM_DISABLE_THINKING", "true").lower() != "false" # 关闭推理模型的思考模式（提速 + 让 temperature 生效）
|
||||
|
||||
# ----- 意图分析（轻量、确定性高）-----
|
||||
# INTENT_MODEL 在顶部「一、API 密钥与模型」中统一配置
|
||||
INTENT_TEMPERATURE = 0.1
|
||||
INTENT_MAX_TOKENS = 4096 # 推理模型思维链消耗大量 token，2048 偶发截断导致意图分析失败
|
||||
INTENT_MAX_TOKENS = 2048 # 推理模型需思考链预算（~1000 tokens），JSON 输出 ~200 tokens
|
||||
INTENT_HISTORY_WINDOW = 6 # 分析时取最近几条历史消息
|
||||
|
||||
# ==============================================================================
|
||||
@@ -286,3 +291,17 @@ def get_llm_client():
|
||||
"""获取 LLM 客户端实例"""
|
||||
from openai import OpenAI
|
||||
return OpenAI(api_key=DASHSCOPE_API_KEY, base_url=DASHSCOPE_BASE_URL)
|
||||
|
||||
|
||||
_intent_client = None
|
||||
|
||||
def get_intent_client():
|
||||
"""获取意图分析专用 LLM 客户端"""
|
||||
global _intent_client
|
||||
if _intent_client is None:
|
||||
# 百炼额度用尽，意图分析也使用 mimo API
|
||||
if not DASHSCOPE_API_KEY:
|
||||
raise ValueError("DASHSCOPE_API_KEY 未配置，请在 .env 中设置")
|
||||
from openai import OpenAI
|
||||
_intent_client = OpenAI(api_key=DASHSCOPE_API_KEY, base_url=DASHSCOPE_BASE_URL)
|
||||
return _intent_client
|
||||
|
||||
@@ -233,10 +233,10 @@ class IntentAnalyzer:
|
||||
self._exact_cache_max = 500
|
||||
|
||||
def _get_client(self):
|
||||
"""获取 LLM 客户端"""
|
||||
"""获取 LLM 客户端（百炼快速模型）"""
|
||||
if self._client is None:
|
||||
from config import get_llm_client
|
||||
self._client = get_llm_client()
|
||||
from config import get_intent_client
|
||||
self._client = get_intent_client()
|
||||
return self._client
|
||||
|
||||
def _get_cache(self):
|
||||
@@ -529,7 +529,16 @@ class IntentAnalyzer:
|
||||
"""解析 JSON 响应"""
|
||||
# 尝试直接解析
|
||||
try:
|
||||
return json.loads(content)
|
||||
parsed = json.loads(content)
|
||||
# mimo 等模型可能返回 JSON 数组而非对象，取第一个元素
|
||||
if isinstance(parsed, list) and len(parsed) > 0:
|
||||
first = parsed[0]
|
||||
if isinstance(first, dict):
|
||||
return first
|
||||
return None
|
||||
if isinstance(parsed, dict):
|
||||
return parsed
|
||||
return None
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
|
||||
@@ -11,6 +11,24 @@ from typing import List, Optional, Union, Iterator, Callable
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# MiMo 推理模型关键词（用于识别需要 thinking 参数的模型）
|
||||
_MIMO_MODEL_KEYWORDS = ('mimo',)
|
||||
|
||||
def _is_mimo_model(model_name: str) -> bool:
|
||||
"""判断是否为小米 MiMo 模型（支持 thinking 参数）"""
|
||||
if not model_name:
|
||||
return False
|
||||
return any(kw in model_name.lower() for kw in _MIMO_MODEL_KEYWORDS)
|
||||
|
||||
def _inject_mimo_thinking(kwargs: dict, model: str, disable_thinking: bool = True) -> dict:
|
||||
"""为 MiMo 模型注入 thinking 参数。返回更新后的 kwargs。"""
|
||||
if not _is_mimo_model(model):
|
||||
return kwargs
|
||||
extra = dict(kwargs.get('extra_body') or {})
|
||||
extra['thinking'] = {'type': 'disabled' if disable_thinking else 'enabled'}
|
||||
kwargs['extra_body'] = extra
|
||||
return kwargs
|
||||
|
||||
|
||||
def call_llm(
|
||||
client,
|
||||
@@ -57,6 +75,13 @@ def call_llm(
|
||||
if messages is None:
|
||||
messages = [{"role": "user", "content": prompt}]
|
||||
|
||||
# MiMo 模型自动注入 thinking 参数
|
||||
try:
|
||||
from config import LLM_DISABLE_THINKING
|
||||
except ImportError:
|
||||
LLM_DISABLE_THINKING = True
|
||||
kwargs = _inject_mimo_thinking(kwargs, model, disable_thinking=LLM_DISABLE_THINKING)
|
||||
|
||||
try:
|
||||
response = client.chat.completions.create(
|
||||
model=model,
|
||||
@@ -71,19 +96,38 @@ def call_llm(
|
||||
return response
|
||||
|
||||
content = response.choices[0].message.content
|
||||
|
||||
# 推理模型兼容：content 为空时尝试从 reasoning_content 提取
|
||||
|
||||
# 推理模型兼容（mimo-v2.5 等）：
|
||||
# 推理模型思考链消耗大量 token（~1000），max_tokens 不足时 content 为空，
|
||||
# 全部输出进入 reasoning_content。此处从思考链中提取有效内容。
|
||||
if not content or not content.strip():
|
||||
reasoning = getattr(response.choices[0].message, 'reasoning_content', None)
|
||||
if reasoning and reasoning.strip():
|
||||
# 从思维链中提取 JSON 块作为内容
|
||||
json_match = re.search(r'\{[\s\S]*\}', reasoning)
|
||||
if json_match:
|
||||
logger.info("LLM: content为空，从reasoning_content提取JSON")
|
||||
return json_match.group().strip()
|
||||
logger.warning("LLM 返回空 content（可能需要增大 max_tokens）")
|
||||
# 先去掉 <think>...</think> 标签
|
||||
cleaned = re.sub(r'', '', reasoning, flags=re.DOTALL).strip()
|
||||
if cleaned:
|
||||
logger.info("LLM: content为空，从reasoning_content提取内容")
|
||||
# 尝试提取 JSON 对象（兼容结构化响应场景）
|
||||
json_match = re.search(r'\{[\s\S]*\}', cleaned)
|
||||
if json_match:
|
||||
try:
|
||||
json.loads(json_match.group())
|
||||
return json_match.group().strip()
|
||||
except (json.JSONDecodeError, ValueError):
|
||||
pass
|
||||
# 尝试提取 JSON 数组
|
||||
bracket_match = re.search(r'\[[\s\S]*\]', cleaned)
|
||||
if bracket_match:
|
||||
try:
|
||||
json.loads(bracket_match.group())
|
||||
return bracket_match.group().strip()
|
||||
except (json.JSONDecodeError, ValueError):
|
||||
pass
|
||||
# 纯文本响应：直接返回清理后的内容
|
||||
return cleaned
|
||||
logger.warning("LLM 返回空 content 且 reasoning_content 也无法提取（可能需要增大 max_tokens）")
|
||||
return None
|
||||
|
||||
|
||||
return content.strip()
|
||||
except Exception as e:
|
||||
logger.warning(f"LLM 调用失败: {e}")
|
||||
@@ -95,7 +139,7 @@ def call_llm_stream(
|
||||
prompt: str,
|
||||
model: str,
|
||||
temperature: float = 0.3,
|
||||
max_tokens: int = 1000,
|
||||
max_tokens: int = 3000,
|
||||
messages: List[dict] = None,
|
||||
error_prefix: str = "[错误]",
|
||||
**kwargs
|
||||
@@ -104,13 +148,14 @@ def call_llm_stream(
|
||||
流式 LLM 调用（生成器封装）
|
||||
|
||||
自动处理流式响应，逐块 yield 文本内容。
|
||||
兼容推理模型（mimo-v2.5 等）：当 content 为空时回退到 reasoning_content。
|
||||
|
||||
Args:
|
||||
client: OpenAI 客户端实例
|
||||
prompt: 用户提示
|
||||
model: 模型名称
|
||||
temperature: 温度参数
|
||||
max_tokens: 最大 token 数
|
||||
max_tokens: 最大 token 数（推理模型需留足思考链预算）
|
||||
messages: 完整消息列表
|
||||
error_prefix: 错误时的前缀
|
||||
**kwargs: 其他参数
|
||||
@@ -125,6 +170,13 @@ def call_llm_stream(
|
||||
if messages is None:
|
||||
messages = [{"role": "user", "content": prompt}]
|
||||
|
||||
# MiMo 模型自动注入 thinking 参数
|
||||
try:
|
||||
from config import LLM_DISABLE_THINKING
|
||||
except ImportError:
|
||||
LLM_DISABLE_THINKING = True
|
||||
kwargs = _inject_mimo_thinking(kwargs, model, disable_thinking=LLM_DISABLE_THINKING)
|
||||
|
||||
try:
|
||||
stream = client.chat.completions.create(
|
||||
model=model,
|
||||
@@ -135,9 +187,33 @@ def call_llm_stream(
|
||||
**kwargs
|
||||
)
|
||||
|
||||
content_yielded = False
|
||||
reasoning_buffer = []
|
||||
|
||||
for chunk in stream:
|
||||
if chunk.choices and chunk.choices[0].delta.content:
|
||||
yield chunk.choices[0].delta.content
|
||||
if not chunk.choices:
|
||||
continue
|
||||
delta = chunk.choices[0].delta
|
||||
|
||||
# 正常 content 输出
|
||||
if hasattr(delta, 'content') and delta.content:
|
||||
content_yielded = True
|
||||
yield delta.content
|
||||
continue
|
||||
|
||||
# 推理模型：reasoning_content（思考链）
|
||||
rc = getattr(delta, 'reasoning_content', None)
|
||||
if rc:
|
||||
reasoning_buffer.append(rc)
|
||||
|
||||
# 回退：content 为空但 reasoning_content 有内容（推理模型 token 不足时）
|
||||
if not content_yielded and reasoning_buffer:
|
||||
reasoning_text = ''.join(reasoning_buffer)
|
||||
# 去掉 <think>...</think> 标签
|
||||
cleaned = re.sub(r'', '', reasoning_text, flags=re.DOTALL).strip()
|
||||
if cleaned:
|
||||
logger.info("流式 LLM: content为空，从reasoning_content提取内容")
|
||||
yield cleaned
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"LLM 流式调用失败: {e}")
|
||||
@@ -201,7 +277,13 @@ def parse_json_from_response(content: str) -> Optional[dict]:
|
||||
json_str = json_match.group(1) if json_match else content
|
||||
|
||||
try:
|
||||
return json.loads(json_str.strip())
|
||||
parsed = json.loads(json_str.strip())
|
||||
# mimo 等模型可能返回 JSON 数组而非对象，取第一个元素
|
||||
if isinstance(parsed, list) and len(parsed) > 0 and isinstance(parsed[0], dict):
|
||||
return parsed[0]
|
||||
if isinstance(parsed, dict):
|
||||
return parsed
|
||||
return None
|
||||
except (json.JSONDecodeError, TypeError, ValueError):
|
||||
return None
|
||||
|
||||
|
||||
@@ -364,7 +364,7 @@ DASHSCOPE_BASE_URL=<your-base-url>
|
||||
DASHSCOPE_MODEL=mimo-v2.5
|
||||
RAG_CHAT_MODEL=mimo-v2.5
|
||||
INTENT_MODEL=mimo-v2.5
|
||||
VLM_MODEL=qwen-vl-plus
|
||||
VLM_MODEL=mimo-v2.5
|
||||
|
||||
# MinerU 在线 API（可选，设置后无需本地模型）
|
||||
MINERU_API_TOKEN=<your-mineru-api-token>
|
||||
|
||||
460
docs/RAG性能分析报告.md
Normal file
460
docs/RAG性能分析报告.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# RAG 知识库问答系统 — 性能分析报告
|
||||
|
||||
> 基于 15 题基准测试 + 代码静态分析 | 2026-06-22
|
||||
>
|
||||
> 基准测试环境：本地 deepseek-v4-flash 模型，服务器使用 mimo-v2.5 时延迟特征可能不同
|
||||
|
||||
---
|
||||
|
||||
## 一、完整请求管线总览
|
||||
|
||||
一次 `/rag/stream` 请求经历 **10 个串行阶段**，每个阶段必须等待前一阶段完成后才能开始。SSE 流式响应在 LLM 生成阶段才开始产出用户可见内容，前 8 个阶段用户感知为"等待中"。
|
||||
|
||||
```
|
||||
用户提问
|
||||
│
|
||||
├─ 0. 输入校验 & 安全过滤 ~1ms
|
||||
├─ 1. 意图分析（LLM 调用） ~3500-5000ms ◄── 瓶颈 #1
|
||||
├─ 2. 语义缓存查找 ~50-200ms
|
||||
├─ 3. 混合检索（向量+BM25+图片） ~200-600ms
|
||||
├─ 4. RRF 融合 + Rerank ~300-800ms
|
||||
├─ 5. MMR 去重 ~5-20ms
|
||||
├─ 6. 救援管线（3层） ~5-30ms
|
||||
├─ 7. 图片选择 + VLM 增强 ~10-50ms
|
||||
├─ 8. 上下文构建 ~5-15ms
|
||||
├─ 9. LLM 流式生成 ~5000-15000ms ◄── 瓶颈 #2
|
||||
└─ 10. 后处理（对齐/引用/会话存储） ~50-200ms
|
||||
```
|
||||
|
||||
**总耗时**：典型请求 **10-20 秒**（含流式输出时间），其中 LLM 调用占 **80%以上**。
|
||||
|
||||
---
|
||||
|
||||
## 二、各阶段详细分析
|
||||
|
||||
### 阶段 1：意图分析 — 最大瓶颈之一
|
||||
|
||||
**位置**：`core/intent_analyzer.py` → `analyze()` 方法
|
||||
|
||||
**功能**：一次非流式 LLM 调用，同时完成问题改写、指代消解、意图分类、子查询生成。
|
||||
|
||||
**执行流程**：
|
||||
|
||||
```
|
||||
精确缓存查找（Dict, O(1)）
|
||||
↓ 未命中
|
||||
语义缓存查找（FAISS, cosine ≥ 0.92）
|
||||
↓ 未命中
|
||||
LLM 调用（非流式，JSON 输出） ◄── 主要耗时
|
||||
↓
|
||||
写入双层缓存 + 返回 IntentAnalysis
|
||||
```
|
||||
|
||||
**关键参数**：
|
||||
|
||||
| 参数 | 服务器值 | 说明 |
|
||||
|------|----------|------|
|
||||
| INTENT_MODEL | mimo-v2.5 | 与主模型共用，无法使用轻量模型 |
|
||||
| INTENT_TEMPERATURE | 0.1 | 低温度保证确定性输出 |
|
||||
| INTENT_MAX_TOKENS | 2048 | 推理模型思考链 ~1000 token + JSON 输出 ~200 token，配置合理 |
|
||||
| INTENT_HISTORY_WINDOW | 6 | 取最近 6 条历史消息 |
|
||||
| 精确缓存上限 | 500 条 | 内存 Dict，重启清零 |
|
||||
| 语义缓存阈值 | 0.92 | 余弦相似度，过于严格则命中率低 |
|
||||
|
||||
**实测耗时**（deepseek-v4-flash）：3500-5000ms。mimo-v2.5 因模型更大，预期 **4000-7000ms**。
|
||||
|
||||
**瓶颈分析**：
|
||||
|
||||
1. **非流式调用**：必须等待完整 JSON 响应才能解析，无法提前返回。这是所有阶段中唯一必须完整等待的 LLM 调用。
|
||||
2. **模型过重**：意图分析本质是分类+改写任务，不需要 mimo-v2.5 这样的推理大模型。换用轻量非推理模型可减少 30-40% 延迟，但百炼 deepseek-v4-flash 额度已尽，需寻找其他可用轻量模型。
|
||||
3. **MAX_TOKENS 配置合理**：mimo-v2.5 是推理模型，思考链消耗 ~1000 token，JSON 输出 ~200 token，2048 是必要预算（此前 1024 导致 content 为空、全部输出进入 reasoning_content 引发解析错误）。
|
||||
4. **缓存命中率低**：精确缓存 key 包含历史上下文，同一用户连续问不同问题时不会命中；语义缓存阈值 0.92 过于严格。
|
||||
|
||||
### 阶段 2：语义缓存查找
|
||||
|
||||
**位置**：`core/semantic_cache.py`
|
||||
|
||||
**功能**：FAISS 向量索引，用 embedding 余弦相似度匹配历史问答，命中则跳过整个检索+生成流程。
|
||||
|
||||
**查找逻辑**：
|
||||
1. 将 `"{query}|{collections}"` 编码为向量
|
||||
2. FAISS IndexFlatIP 搜索 top-1（向量已归一化，内积=余弦）
|
||||
3. 阈值 ≥ 0.92 → 命中
|
||||
4. 验证 `cache_type == "rag_answer"`（区分意图缓存和问答缓存）
|
||||
|
||||
**性能**：50-200ms（主要是 embedding 编码耗时，FAISS 搜索本身 <1ms）
|
||||
|
||||
**瓶颈分析**：此阶段本身不慢，但受限于 0.92 的高阈值，实际命中率较低。同一个问题的不同表述方式（如"智启平台支持哪些数据源" vs "智启能对接什么数据库"）余弦相似度可能在 0.85-0.91 之间，无法命中。降低阈值会引入误命中风险。
|
||||
|
||||
### 阶段 3：混合检索
|
||||
|
||||
**位置**：`core/engine.py` → `search_knowledge()`
|
||||
|
||||
**功能**：三路并行召回 + RRF 融合
|
||||
|
||||
**三路召回**：
|
||||
|
||||
| 召回路径 | 数量 | 后端 | 耗时 |
|
||||
|----------|------|------|------|
|
||||
| 向量检索 | recall_k = max(20, 30×3) = 90 | ChromaDB + bge-base-zh-v1.5 (CPU) | 100-300ms |
|
||||
| BM25 关键词 | top_k=30 | rank_bm25 (jieba 分词) | 10-30ms |
|
||||
| 图片独立召回 | n_results=5 | ChromaDB，过滤 chunk_type | 20-50ms |
|
||||
|
||||
**RRF 融合**（Reciprocal Rank Fusion）：
|
||||
|
||||
```
|
||||
score = weight / (k + rank + 1)，k = 60
|
||||
|
||||
动态权重（按查询长度自适应）：
|
||||
alpha = clamp((len(query) - 15) / 35, 0, 1)
|
||||
vector_weight = 0.3 + 0.4 × alpha # 短查询 0.3，长查询 0.7
|
||||
bm25_weight = 1.0 - vector_weight
|
||||
```
|
||||
|
||||
**性能**：总计 200-600ms。Embedding 编码是主要耗时（CPU 推理），ChromaDB 查询本身很快。
|
||||
|
||||
**瓶颈分析**：
|
||||
|
||||
1. **Embedding 在 CPU 上运行**：bge-base-zh-v1.5 编码 90 个候选文档需要 100-200ms。GPU 可降至 10-30ms，但当前服务器未配置 GPU。
|
||||
2. **召回数量偏大**：`recall_k=90` 意味着 embedding 编码量大。实际 Rerank 只取 20 个，多召回的 70 个是浪费。可降低 `RECALL_MULTIPLIER` 从 3 到 2。
|
||||
3. **BM25 无瓶颈**：纯内存计算，jieba 分词+BM25 打分共 10-30ms。
|
||||
|
||||
### 阶段 4：Rerank
|
||||
|
||||
**位置**：`core/engine.py` → `rerank_results()`
|
||||
|
||||
**功能**：CrossEncoder 精排，对融合后的候选重打分
|
||||
|
||||
**服务器配置**：`RERANK_BACKEND = "local"`，使用 ONNX 格式的 bge-reranker-base。云端备选为 `xop3qwen8breranker`（讯飞云 API），`RERANK_BACKEND = "cloud"` 或 `"fallback"` 时启用。
|
||||
|
||||
**流程**：
|
||||
1. 检查 Rerank 缓存（MD5 of query + sorted_doc_ids）
|
||||
2. 缓存未命中 → 调用 ONNX 推理，predict(query, doc) × N
|
||||
3. 按分数排序，截取 `RERANK_TOP_K=15`
|
||||
|
||||
**性能**：
|
||||
- 缓存命中：<1ms
|
||||
- 缓存未命中（20 个候选）：300-800ms（CPU ONNX 推理）
|
||||
|
||||
**瓶颈分析**：
|
||||
|
||||
1. **CPU 推理**：CrossEncoder 是最重的 CPU 计算任务。每个 (query, doc) pair 需要一次 forward pass。20 个候选 × ~30ms/pair ≈ 600ms。
|
||||
2. **max_length=512**：长文档截断到 512 token，避免 OOM 但可能丢失信息。
|
||||
3. **缓存效果好**：同一查询+同一文档集合直接命中缓存。但首次查询必经此阶段。
|
||||
|
||||
### 阶段 5：MMR 去重
|
||||
|
||||
**位置**：`core/mmr.py`
|
||||
|
||||
**当前配置**：`MMR_USE_EMBEDDING = False`（文本模式），使用 jieba 词级 Jaccard 相似度
|
||||
|
||||
**算法**：贪心选择，每次取与已选集合最不相似且与查询最相关的候选
|
||||
|
||||
**性能**：5-20ms（纯文本计算，无 embedding 开销）
|
||||
|
||||
**瓶颈分析**：**无瓶颈**。文本模式 Jaccard 非常轻量。
|
||||
|
||||
### 阶段 6：救援管线（3 层）
|
||||
|
||||
**位置**：`api/chat_routes.py` 内部函数 + `core/engine.py`
|
||||
|
||||
**第一层 — BM25 发散救援**：
|
||||
- 当 BM25 top-3 中的文档被 Rerank 打到极低分时，恢复其分数到 `CLUSTER_RESCUE_FLOOR=0.06`
|
||||
- 防止关键词完全匹配但语义分低的文档被丢弃
|
||||
|
||||
**第二层 — 词法匹配救援**：
|
||||
- 提取查询 bigram，对每个低分文档计算 bigram 匹配率
|
||||
- 匹配率 > 0.35 → 提升到 floor
|
||||
- 附带邻居救援：同文档 ±8 个 chunk_index 的邻居也被提升
|
||||
|
||||
**第三层 — 章节聚类救援**（engine.py `_section_cluster_boost`）：
|
||||
- 按 `(source, normalized_section)` 分组
|
||||
- 检测"全灭章节"：所有成员分数 < min_score
|
||||
- 要求 ≥ 3 成员 + ≥ 2 种 chunk_type
|
||||
- 提升最强聚类的 top-3 章节，每节最多 8 个 chunk
|
||||
|
||||
**性能**：5-30ms（纯规则计算）
|
||||
|
||||
**瓶颈分析**：**无瓶颈**。但在复杂表格/对比查询中，救援管线的效果直接影响回答质量。
|
||||
|
||||
### 阶段 7：图片选择
|
||||
|
||||
**位置**：`api/chat_routes.py` → `select_images()`
|
||||
|
||||
**评分体系**（多层叠加）：
|
||||
|
||||
| 评分因子 | 分值 | 条件 |
|
||||
|----------|------|------|
|
||||
| 图号精确匹配 | +10.0 | 查询提到"图2.3"且匹配 |
|
||||
| 表号精确匹配 | +10.0 | 查询提到"表1"且匹配 |
|
||||
| 关键词匹配 | +2.0/词 | jieba 分词后匹配，上限 +8.0 |
|
||||
| 字符重叠 | +0.2/字 | 上限 +3.0 |
|
||||
| 章节匹配 | +1.5/关键词 | 图片章节与查询关键词重叠 |
|
||||
| 图表类型 | +2.0 (chart) / +1.0 (image) | chunk_type 加分 |
|
||||
| 引用+章节匹配 | +8.0 + 5.0 | 被文本引用且章节/来源匹配 |
|
||||
| VLM 相关性 < 0.3 | -3.0 | VLM 描述与查询不相关 |
|
||||
| VLM 相关性 ≥ 0.5 | +2.0 | VLM 描述与查询相关 |
|
||||
| 章节距离过远 | -5.0 | section_similarity < 0.3 且非引用 |
|
||||
|
||||
**动态预算**：
|
||||
|
||||
| 场景 | MAX_IMAGES | MIN_SCORE |
|
||||
|------|------------|-----------|
|
||||
| 精确图号查询 | 2 | 5.0 |
|
||||
| 检索结果含图片数据 | 5 | 2.0 |
|
||||
| 文本中有图号引用 | 3 | 2.0 |
|
||||
| 默认 | 2 | 3.0 |
|
||||
|
||||
**性能**：10-50ms（规则计算 + VLM 相关性检查）
|
||||
|
||||
**瓶颈分析**：图片选择本身不慢。瓶颈在 **VLM 描述生成**（`knowledge/lazy_enhance.py`），需要调用 VLM 模型为每张图片生成文字描述。当前设计为懒加载（首次查询时生成并缓存），首次查询可能有 60s 超时。
|
||||
|
||||
**两管线断裂问题**：`select_images()` 独立于文本上下文管线选择图片，但图片描述可能因 `min_score` 过滤未进入 LLM 上下文。具体问题链：
|
||||
|
||||
1. **chart_contexts 降门槛**：CrossEncoder 对图片/图表打分系统性偏低（0.002-0.08 vs 文本 0.3-0.9），原 `min_score=0.05` 会过滤掉几乎所有图表。已修复为 `min_score * 0.5 = 0.025`。
|
||||
2. **P0 安全网**：即使降门槛后，图片描述仍可能被 `_build_context_with_budget()` 截断。安全网在 LLM 生成前检查：若 `selected_images` 的描述不在 `context_text` 中，强制追加缺失描述。日志标记为 `[P0] 图片描述未完整注入 context`。
|
||||
3. **答案后过滤鸡生蛋问题**：`_filter_images_by_answer()` 根据 LLM 答案内容过滤图片。若 LLM 因上下文缺失而回答"未找到某图表"，正确图片会被误过滤。P0 安全网可缓解此问题。
|
||||
|
||||
### 阶段 8：上下文构建
|
||||
|
||||
**位置**：`api/chat_routes.py` → `_build_context_with_budget()` / `_order_text_contexts_for_prompt()`
|
||||
|
||||
**预算控制**：
|
||||
|
||||
```
|
||||
CONTEXT_MAX_CHARS = 8000 # 硬上限（约 4000 token）
|
||||
CONTEXT_SOFT_LIMIT = 6000 # 软限制（超过后只接受高分 chunk）
|
||||
MAX_CONTEXT_CHUNKS = 20 # 最大切片数
|
||||
```
|
||||
|
||||
**排序策略**：
|
||||
1. 枚举/对比查询：保持原文顺序，注入 `━ section ━` 分隔符
|
||||
2. 普通查询：按 (source, section) 分组 → 组内按 chunk_index 排序 → 组间按 max_rerank_score 排序
|
||||
3. 表格保护：即使分数低于 min_score，只要同章节有高分文本 chunk，表格 chunk 也保留（floor = min_score × 0.3）
|
||||
|
||||
**性能**：5-15ms
|
||||
|
||||
**瓶颈分析**：**无瓶颈**。但上下文质量直接影响 LLM 生成质量。8000 字符 ≈ 4000 token，对于需要对比多个文档的查询可能不够。
|
||||
|
||||
### 阶段 9：LLM 流式生成 — 最大瓶颈
|
||||
|
||||
**位置**：`core/engine.py` → `generate_answer_stream()`
|
||||
|
||||
**功能**：将上下文 + 历史 + 查询组装成 prompt，调用 LLM 流式输出
|
||||
|
||||
**Prompt 结构**：
|
||||
```
|
||||
[System] 你是一个专业的知识库问答助手...（规则指令）
|
||||
[System] 参考资料：（context, 最多 8000 字符）
|
||||
[User×N] 历史对话（最多 10 轮）
|
||||
[User] 当前问题
|
||||
```
|
||||
|
||||
**关键参数**：
|
||||
|
||||
| 参数 | 服务器值 | 说明 |
|
||||
|------|----------|------|
|
||||
| MODEL | mimo-v2.5 | 主生成模型 |
|
||||
| LLM_TEMPERATURE | 0.7 | 较高温度，生成更发散 |
|
||||
| LLM_MAX_TOKENS | 3000 | 最大输出 token |
|
||||
| LLM_TOP_P | （未设置） | 默认 1.0 |
|
||||
|
||||
**实测耗时**（deepseek-v4-flash）：5000-15000ms（含流式输出）。mimo-v2.5 推理模型预计 **8000-20000ms**。
|
||||
|
||||
**瓶颈分析**：
|
||||
|
||||
1. **模型延迟不可控**：LLM API 的 TTFT（首 token 时间）和 TPS（token/秒）取决于服务端负载和网络。这是整个管线中唯一无法通过代码优化的瓶颈。
|
||||
2. **推理模型 content 为空问题**：mimo-v2.5 是推理模型，`max_tokens` 不足时思考链消耗全部预算，`content` 为空需从 `reasoning_content` 提取内容。当前 `LLM_MAX_TOKENS=3000` 足够，但若降低此值需注意思考链预算。
|
||||
3. **Prompt 长度影响 TTFT**：8000 字符上下文 + 10 轮历史 ≈ 6000-8000 input token。输入越长，TTFT 越高。
|
||||
4. **流式缓解**：用户看到第一个 token 的等待时间 = 意图分析 + 检索 + TTFT ≈ 6-12 秒。流式输出减少了感知等待，但总耗时不变。
|
||||
5. **MAX_TOKENS=3000 配置合理**：推理模型思考链占用部分预算，实际回答通常 500-1500 token，3000 平衡速度与质量。
|
||||
|
||||
### 阶段 10：后处理
|
||||
|
||||
**功能**：答案对齐、图片过滤、引用附加、会话存储、语义缓存写入
|
||||
|
||||
**子步骤**：
|
||||
|
||||
| 步骤 | 耗时 | 说明 |
|
||||
|------|------|------|
|
||||
| 图号引用提取 | ~5ms | 正则匹配答案中的图/表引用 |
|
||||
| 图片后过滤 | ~5ms | `_filter_images_by_answer()`，根据 LLM 答案内容裁剪不相关图片 |
|
||||
| 引用清理 | ~2ms | 去除 LLM 添加的 [N] 标记 |
|
||||
| 引用附加 | ~10ms | 添加结构化 [ref:chunk_id] |
|
||||
| 敏感内容过滤 | ~5ms | prompt_guard 检查 |
|
||||
| 会话存储 | ~20-100ms | SQLite 写入 |
|
||||
| 语义缓存写入 | ~10-50ms | FAISS 索引添加 |
|
||||
|
||||
**总计**：50-200ms。**无瓶颈**。
|
||||
|
||||
---
|
||||
|
||||
## 三、缓存体系分析
|
||||
|
||||
### 五层缓存架构
|
||||
|
||||
```
|
||||
精确缓存层
|
||||
├─ Query Cache LRU 500, TTL 1h 最终结果缓存（含 rerank 分数）
|
||||
├─ Embedding Cache LRU 2000, TTL 24h 文档向量缓存
|
||||
├─ Rerank Cache LRU 1000, TTL 1h CrossEncoder 分数缓存
|
||||
└─ Intent Cache Dict 500, 无 TTL 意图分析结果缓存
|
||||
|
||||
语义缓存层
|
||||
└─ FAISS Cache max 10000, 阈值 0.92 向量化相似问答缓存
|
||||
```
|
||||
|
||||
### 缓存命中场景
|
||||
|
||||
| 场景 | 命中层 | 节省时间 |
|
||||
|------|--------|----------|
|
||||
| 完全相同的问题 + 相同知识库 | Query Cache | 跳过整个检索（节省 ~1s） |
|
||||
| 相似问题（余弦 ≥ 0.92） | Semantic Cache | 跳过检索 + 生成（节省 ~10s） |
|
||||
| 相同文档集合被 rerank | Rerank Cache | 跳过 CrossEncoder（节省 ~600ms） |
|
||||
| 相同文档需要 embedding | Embedding Cache | 跳过编码（节省 ~100ms） |
|
||||
| 相同问题（意图层面） | Intent Cache | 跳过意图分析 LLM（节省 ~4s） |
|
||||
|
||||
### 缓存问题
|
||||
|
||||
1. **内存存储，重启清零**：所有缓存都在进程内存中，服务重启后第一次请求全部冷启动。
|
||||
2. **语义缓存阈值过高**：0.92 的余弦阈值导致换一种说法就命中不了。
|
||||
3. **Rerank 缓存不参与 kb_version 失效**：文档更新后 rerank 缓存可能返回旧分数。
|
||||
4. **语义缓存淘汰策略粗暴**：达到 10000 上限时全量清空（`clear()`），不是 LRU。
|
||||
|
||||
---
|
||||
|
||||
## 四、瓶颈总结与优化优先级
|
||||
|
||||
### 耗时分布（典型请求，基于 deepseek-v4-flash 实测）
|
||||
|
||||
```
|
||||
意图分析 ████████████████████ 25-35% ~4000ms
|
||||
LLM 生成 ████████████████████████████████ 45-60% ~8000ms
|
||||
检索+Rerank ████████ 10-15% ~1200ms
|
||||
其他阶段 ██ 3-5% ~400ms
|
||||
```
|
||||
|
||||
### 优化机会排序
|
||||
|
||||
| 优先级 | 方向 | 预期收益 | 难度 | 风险 |
|
||||
|--------|------|----------|------|------|
|
||||
| **P0** | 意图分析换轻量模型 | 节省 2-3s/请求 | 低 | 低（需寻找可用轻量模型，百炼 deepseek-v4-flash 额度已尽） |
|
||||
| **P0** | 主模型 API 优化（换供应商/批处理） | 节省 3-5s/请求 | 中 | 中（需要评估质量） |
|
||||
| **P1** | 意图分析结果缓存优化 | 重复问题节省 4s | 低 | 低 |
|
||||
| **P1** | 语义缓存阈值调优（0.92→0.88） | 提高命中率，节省 10s | 低 | 中（可能误命中） |
|
||||
| **P2** | RECALL_MULTIPLIER 降低（3→2） | 减少 embedding 编码量 ~30ms | 低 | 低 |
|
||||
| **P2** | LLM_TEMPERATURE 降低（0.7→0.3） | 减少发散，回答更精准 | 低 | 中（可能影响创造性） |
|
||||
| **P3** | Rerank 换 GPU 推理 | 节省 ~500ms | 高（需硬件） | 低 |
|
||||
| **P3** | Embedding 换 GPU 推理 | 节省 ~150ms | 高（需硬件） | 低 |
|
||||
| **P3** | 语义缓存改 LRU 淘汰 | 避免全量清空抖动 | 中 | 低 |
|
||||
|
||||
---
|
||||
|
||||
## 五、配置参数速查表
|
||||
|
||||
### 模型与服务
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| DASHSCOPE_MODEL | mimo-v2.5 | 主 LLM |
|
||||
| INTENT_MODEL | mimo-v2.5 | 意图分析模型 |
|
||||
| VLM_MODEL | mimo-v2.5 | 图片描述模型 |
|
||||
| EMBEDDING_MODEL_PATH | bge-base-zh-v1.5 | 本地 embedding |
|
||||
| RERANK_BACKEND | local | 本地 ONNX rerank（可选 cloud/fallback） |
|
||||
| RERANK_CLOUD_MODEL | xop3qwen8breranker | 云端 rerank（讯飞云 API） |
|
||||
|
||||
### 检索参数
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| RAG_SEARCH_TOP_K | 30 | 最终返回数 |
|
||||
| RECALL_MULTIPLIER | 3 | 向量召回倍数 |
|
||||
| RERANK_CANDIDATES | 20 | 送入 Rerank 的候选数 |
|
||||
| RERANK_TOP_K | 15 | Rerank 后保留数 |
|
||||
| RERANK_CONTEXT_MIN_SCORE | 0.05 | 最低 rerank 分数阈值 |
|
||||
| MMR_TOP_K | 30 | MMR 处理后保留数 |
|
||||
| MMR_LAMBDA | 0.5 | 相关性/多样性平衡 |
|
||||
| MMR_USE_EMBEDDING | False | 使用 jieba Jaccard |
|
||||
| RRF_K | 60 | RRF 平滑参数 |
|
||||
| DYNAMIC_RRF_ENABLED | True | 按查询长度自适应权重 |
|
||||
|
||||
### 上下文构建
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| CONTEXT_MAX_CHARS | 8000 | 上下文硬上限（字符） |
|
||||
| CONTEXT_SOFT_LIMIT | 6000 | 软限制（超此只接受高分） |
|
||||
| MAX_CONTEXT_CHUNKS | 20 | 最大切片数 |
|
||||
| MAX_HISTORY_ROUNDS | 10 | 对话历史上限 |
|
||||
|
||||
### LLM 生成
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| LLM_TEMPERATURE | 0.7 | 生成温度 |
|
||||
| LLM_MAX_TOKENS | 3000 | 最大输出 token |
|
||||
| LLM_TOP_P | 未设置 | 默认 1.0（不限制） |
|
||||
|
||||
### 缓存
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| QUERY_CACHE_SIZE | 500 | 查询缓存容量 |
|
||||
| QUERY_CACHE_TTL | 3600s | 查询缓存有效期 |
|
||||
| EMBEDDING_CACHE_SIZE | 2000 | 向量缓存容量 |
|
||||
| EMBEDDING_CACHE_TTL | 86400s | 向量缓存有效期 |
|
||||
| RERANK_CACHE_SIZE | 1000 | Rerank 缓存容量 |
|
||||
| RERANK_CACHE_TTL | 3600s | Rerank 缓存有效期 |
|
||||
| SEMANTIC_CACHE_THRESHOLD | 0.92 | 语义缓存余弦阈值 |
|
||||
|
||||
### 救援管线
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| CLUSTER_MIN_MEMBERS | 3 | 聚类最少成员数 |
|
||||
| CLUSTER_MIN_TYPES | 2 | 聚类最少类型数 |
|
||||
| CLUSTER_SEED_FLOOR | 0.35 | 种子分数下限 |
|
||||
| CLUSTER_RESCUE_FLOOR | 0.06 | 救援后分数 |
|
||||
| CLUSTER_MAX_SECTIONS | 3 | 最多救援章节数 |
|
||||
| BM25_DIVERGENCE_RESCUE_ENABLED | True | BM25 发散救援开关 |
|
||||
| BM25_DIVERGENCE_MAX_RANK | 3 | BM25 top-N 参与救援 |
|
||||
|
||||
### 置信度
|
||||
|
||||
| 参数 | 当前值 | 说明 |
|
||||
|------|--------|------|
|
||||
| CONFIDENCE_WARN_THRESHOLD | 0.15 | 低于此值：谨慎回答 |
|
||||
| CONFIDENCE_CAUTION_THRESHOLD | 0.30 | 低于此值：引用原文 |
|
||||
|
||||
---
|
||||
|
||||
## 六、架构层面的潜在风险
|
||||
|
||||
### 6.1 单点故障
|
||||
|
||||
- **LLM API 单点**：所有 LLM 调用（意图分析 + 生成）都走同一个 DASHSCOPE_BASE_URL。API 限流或故障时整个服务不可用。意图分析有降级兜底（默认 need_retrieval=True），但生成阶段无降级。
|
||||
- **ChromaDB 单点**：向量库文件损坏时所有检索失败。已有 ChromaDB corruption 风险分析文档。
|
||||
|
||||
### 6.2 内存压力
|
||||
|
||||
- **FAISS 语义缓存**：10000 条 × 768 维 float32 = ~30MB 向量数据 + 等量元数据。达到上限全量清空时可能有瞬间抖动。
|
||||
- **BM25 全量加载**：所有文档的全文 + jieba 分词结果都在内存中。知识库增长时内存线性增长。
|
||||
- **三层 LRU 缓存**：Query(500) + Embedding(2000) + Rerank(1000) = 最多 3500 条缓存。Embedding 缓存存 768 维向量，2000 条 ≈ 6MB。
|
||||
|
||||
### 6.3 并发安全
|
||||
|
||||
- gunicorn gthread 模式 2 线程 + ChromaDB 文件锁。并发写入 ChromaDB 时可能冲突。
|
||||
- FAISS 语义缓存使用 RLock，线程安全。
|
||||
- 精确缓存使用 RLock，线程安全。
|
||||
- IntentAnalyzer._exact_cache 是普通 Dict，Python GIL 保护下基本安全。
|
||||
|
||||
### 6.4 休眠模块
|
||||
|
||||
以下模块当前未接入生产流程，属于**独立休眠模块**（原属 AgenticRAG 类，该类已在 v4.0 删除）：
|
||||
|
||||
- `confidence_gate.py` — 置信度门控
|
||||
- `quality_assessor.py` — 质量评估器
|
||||
- `reasoning_reflector.py` — 推理反思器
|
||||
- `loop_guard.py` — 循环守卫
|
||||
|
||||
这些模块增加了代码库的维护负担但不影响运行时性能。可按需启用。
|
||||
549
docs/RAG数据流程.md
549
docs/RAG数据流程.md
@@ -1,7 +1,7 @@
|
||||
# RAG 数据流程
|
||||
|
||||
> 本文档基于 v7.0.0 架构，详细梳理 RAG 系统从用户查询到回答生成的完整数据流。
|
||||
> 涵盖意图分析、混合检索、云端重排序、MMR 去重、上下文构建、LLM 生成和引用溯源等核心环节。
|
||||
> 本文档基于当前代码实际逻辑梳理，详细记录 RAG 系统从用户查询到回答生成的完整数据流。
|
||||
> 涵盖意图分析、混合检索、重排序、救援管道、上下文构建、图片选择与注入、LLM 生成和引用溯源等核心环节。
|
||||
|
||||
---
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 1. 意图分析 (intent_analyzer) │
|
||||
│ 问题改写 · 指代消解 · 是否需要检索 · 重复提问检测 │
|
||||
│ 模型：qwen-turbo │
|
||||
│ 模型：mimo-v2.5 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
@@ -29,31 +29,37 @@
|
||||
│ └────────┬──────────┘ │
|
||||
│ ▼ │
|
||||
│ RRF 融合 (Reciprocal Rank Fusion) │
|
||||
│ │ │
|
||||
│ 查询缓存检查 (命中则跳过 3-7 步) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 3. 云端 Rerank (DashScope API) │
|
||||
│ 模型：qwen3-rerank │
|
||||
│ 3. 云端 Rerank │
|
||||
│ 模型：xop3qwen8breranker (讯飞云) │
|
||||
│ 结果缓存：rerank_cache (TTL=1h, 版本失效自动清除) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 4. MMR 去重 (文本 Jaccard 模式) │
|
||||
│ MMR_USE_EMBEDDING=false │
|
||||
│ 4. 救援管道 (chat_routes.py) │
|
||||
│ BM25 分歧救援 · 词法匹配救援 · 章节聚类救援 │
|
||||
│ 目的：挽救被 CrossEncoder 低估但实际相关的切片 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 5. 上下文扩展 + 图片选择 │
|
||||
│ 上下文增强 · 图文关联补充 · 懒加载 VLM 描述 │
|
||||
│ 5. 上下文构建 + 图片选择 │
|
||||
│ _order_text_contexts_for_prompt · _build_context_with_budget │
|
||||
│ select_images · VLM 相关性筛选 · CrossEncoder 精排 │
|
||||
│ 懒加载 VLM 描述 · 图片描述注入 · P0 安全网 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 6. LLM 生成 (AgenticRAG 引擎) │
|
||||
│ 模型：qwen3.6-flash（主 LLM）/ qwen-vl-plus（VLM） │
|
||||
│ 流式输出 · 引用标注 │
|
||||
│ 6. LLM 生成 │
|
||||
│ 模型：mimo-v2.5 │
|
||||
│ 流式输出 · 置信度指令 · 引用标注 · 图片后置过滤 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
@@ -65,19 +71,26 @@
|
||||
|
||||
### 1.2 模型配置一览
|
||||
|
||||
| 用途 | 模型 | 说明 |
|
||||
|------|------|------|
|
||||
| 主 LLM | qwen3.6-flash | 回答生成、上下文理解 |
|
||||
| 意图分析 | qwen-turbo | 轻量快速，用于问题改写与意图判断 |
|
||||
| VLM | qwen-vl-plus | 图片理解与描述生成 |
|
||||
| 云端重排序 | qwen3-rerank | DashScope API 调用，替代本地 BGE-reranker |
|
||||
| 用途 | 模型 | API 端点 | 说明 |
|
||||
|------|------|----------|------|
|
||||
| 主 LLM | mimo-v2.5 | xiaomimimo.com | 回答生成、上下文理解 |
|
||||
| 意图分析 | mimo-v2.5 | xiaomimimo.com | 问题改写与意图判断 |
|
||||
| VLM | mimo-v2.5 | xiaomimimo.com | 图片理解与描述生成 |
|
||||
| 云端重排序 | xop3qwen8breranker | 讯飞云 Maas API | 替代本地 BGE-reranker |
|
||||
| 向量编码 | bge-base-zh-v1.5 | 本地模型 | 查询与文档 embedding |
|
||||
|
||||
### 1.3 v7.0.0 架构变更要点
|
||||
> 模型可通过环境变量覆盖：`DASHSCOPE_MODEL`、`INTENT_MODEL`、`VLM_MODEL`、`RERANK_CLOUD_MODEL`
|
||||
|
||||
- **Reranker**：从本地 BGE-reranker 切换为云端 DashScope API（qwen3-rerank）
|
||||
- **MMR 去重**：使用文本相似度模式（`MMR_USE_EMBEDDING=false`），基于 Jaccard 系数
|
||||
- **Agentic 引擎**：拆分为多个子模块（agentic_search / agentic_answer / agentic_citation 等）
|
||||
- **Graph RAG**：模块已清空，不再使用
|
||||
### 1.3 关键配置参数
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `RERANK_CONTEXT_MIN_SCORE` | 0.05 | Rerank 分数低于此值的切片不送入 LLM |
|
||||
| `MAX_CONTEXT_CHUNKS` | 20 | 送给 LLM 的最大文本切片数 |
|
||||
| `CONTEXT_MAX_CHARS` | 8000 | 上下文最大字符数（约 4000 token） |
|
||||
| `CONTEXT_SOFT_LIMIT` | 6000 | 软限制，超过后只接受高分切片组 |
|
||||
| `CONFIDENCE_WARN_THRESHOLD` | 0.15 | top-3 均分低于此值时，提示 LLM 谨慎回答 |
|
||||
| `CONFIDENCE_CAUTION_THRESHOLD` | 0.30 | top-3 均分低于此值时，提示 LLM 优先引用原文 |
|
||||
|
||||
---
|
||||
|
||||
@@ -87,38 +100,41 @@
|
||||
|
||||
**入口文件**：`api/chat_routes.py`
|
||||
|
||||
用户通过 API 发送查询请求，由 `generate()` 函数统一调度：
|
||||
|
||||
```
|
||||
POST /rag 或 POST /chat
|
||||
Body: { "query": "用户问题", "kb_name": "知识库名称" }
|
||||
POST /chat — 普通聊天（不检索知识库，直接 LLM 回答）
|
||||
POST /rag — 知识库问答（检索 + LLM 生成）
|
||||
POST /search — 纯检索（返回切片，不生成回答）
|
||||
```
|
||||
|
||||
`generate()` 的职责：
|
||||
`/rag` 的核心函数 `rag()` 的职责：
|
||||
|
||||
1. 调用意图分析模块，获取改写后的查询与检索决策
|
||||
2. 若需要检索，调用混合检索管线
|
||||
3. 执行图片选择与上下文构建
|
||||
4. 调用 LLM 生成回答（流式输出）
|
||||
5. 组装最终响应（回答 + 引用来源 + 图片）
|
||||
2. 若需要检索，调用混合检索管线（`search_hybrid()`）
|
||||
3. 执行救援管道（BM25 分歧 / 词法匹配 / 章节聚类）
|
||||
4. 执行图片选择（`select_images()`）
|
||||
5. 构建 LLM 上下文（排序 + 预算截断 + 图片注入）
|
||||
6. 调用 LLM 生成回答（流式输出）
|
||||
7. 后置图片过滤（`_filter_images_by_answer()`）
|
||||
8. 组装最终响应（回答 + 引用来源 + 图片）
|
||||
|
||||
### 2.2 请求数据结构
|
||||
|
||||
```python
|
||||
# 请求
|
||||
{
|
||||
"query": "蓄水以来逐年发电量",
|
||||
"kb_name": "public_kb",
|
||||
"message": "用户问题",
|
||||
"history": [...] # 可选：对话历史
|
||||
}
|
||||
|
||||
# 响应
|
||||
{
|
||||
"type": "finish",
|
||||
"answer": "完整回答文本",
|
||||
"sources": [...], # 引用来源列表
|
||||
"images": [...] # 精选图片列表
|
||||
}
|
||||
# SSE 响应事件流
|
||||
data: {"type": "intent_result", "data": {...}}
|
||||
data: {"type": "chunks_retrieved", "data": {...}}
|
||||
data: {"type": "images_selected", "data": {...}}
|
||||
data: {"type": "context_built", "data": {...}}
|
||||
data: {"type": "chunk", "content": "部分回答"}
|
||||
data: {"type": "chunk", "content": "部分回答"}
|
||||
...
|
||||
data: {"type": "finish", "answer": "完整回答", "sources": [...], "images": [...]}
|
||||
```
|
||||
|
||||
---
|
||||
@@ -126,7 +142,7 @@ Body: { "query": "用户问题", "kb_name": "知识库名称" }
|
||||
## 三、意图分析
|
||||
|
||||
**入口文件**：`core/intent_analyzer.py`
|
||||
**使用模型**：qwen-turbo（轻量快速）
|
||||
**使用模型**：mimo-v2.5
|
||||
|
||||
### 3.1 核心功能
|
||||
|
||||
@@ -138,6 +154,8 @@ class IntentAnalysis:
|
||||
rewritten_query: str # 改写后的查询（指代消解、省略补全）
|
||||
use_context: bool # 是否使用历史上下文
|
||||
need_retrieval: bool # 是否需要检索知识库
|
||||
intent: str # 意图类型：factual/comparison/reasoning/instruction
|
||||
sub_queries: list # 子查询列表（对比/复杂查询拆分）
|
||||
```
|
||||
|
||||
### 3.2 处理逻辑
|
||||
@@ -147,7 +165,9 @@ class IntentAnalysis:
|
||||
| 问题改写 | 指代消解（"它" → 具体实体）、省略补全（补全缺失主语） |
|
||||
| 上下文判断 | 根据对话历史决定是否需要前文信息 |
|
||||
| 检索决策 | 判断是否需要查询知识库（闲聊类问题可跳过） |
|
||||
| 重复提问检测 | 用户重复提问相同问题时，强制设置 `need_retrieval=true` |
|
||||
| 意图分类 | 识别查询意图（事实查询/对比分析/推理/操作指导） |
|
||||
| 子查询拆分 | 对比类查询拆分为多个子查询并行检索 |
|
||||
| 语义缓存 | 相似度 ≥ 0.92 时复用历史意图分析结果 |
|
||||
|
||||
### 3.3 重复提问规则
|
||||
|
||||
@@ -170,9 +190,16 @@ if cached:
|
||||
return cached
|
||||
```
|
||||
|
||||
缓存层级（5 层）：
|
||||
1. `query_cache` — 精确查询结果缓存
|
||||
2. `embedding_cache` — embedding 向量缓存
|
||||
3. `rerank_cache` — rerank 分数缓存（TTL=1h，知识库版本变更自动失效）
|
||||
4. `semantic_cache` — 语义相似查询缓存（阈值 0.92）
|
||||
5. `intent_exact_cache` — 意图分析精确缓存
|
||||
|
||||
### 4.2 向量检索
|
||||
|
||||
使用 embedding 模型将查询编码为向量，在 ChromaDB 中执行 ANN 检索：
|
||||
使用本地 bge-base-zh-v1.5 模型将查询编码为向量，在 ChromaDB 中执行 ANN 检索：
|
||||
|
||||
```python
|
||||
query_vector = embedding_model.encode(query)
|
||||
@@ -211,13 +238,9 @@ fused_results = reciprocal_rank_fusion(
|
||||
)
|
||||
```
|
||||
|
||||
**融合参数**：
|
||||
### 4.5 子查询并行检索
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `recall_k` | 100 | 各通道召回候选数量 |
|
||||
| `VECTOR_WEIGHT` | 0.6 | 向量检索权重 |
|
||||
| `BM25_WEIGHT` | 0.4 | BM25 检索权重 |
|
||||
意图分析器拆分的子查询（如对比类查询）会并行检索，结果合并后再 rerank。
|
||||
|
||||
---
|
||||
|
||||
@@ -225,204 +248,233 @@ fused_results = reciprocal_rank_fusion(
|
||||
|
||||
### 5.1 云端 Rerank
|
||||
|
||||
**v7.0.0 变更**：从本地 BGE-reranker 切换为云端 DashScope API。
|
||||
|
||||
**调用模型**：qwen3-rerank
|
||||
**调用模型**：xop3qwen8breranker（讯飞云 Maas API）
|
||||
|
||||
RRF 融合后的候选结果通过云端 Reranker 进行精排，基于查询与文档的语义相关性重新打分排序：
|
||||
|
||||
```python
|
||||
reranked = rerank_results(
|
||||
query,
|
||||
fused_results,
|
||||
model="qwen3-rerank", # DashScope API
|
||||
top_k=15
|
||||
)
|
||||
reranked = rerank_results(query, fused_results, top_k=15)
|
||||
```
|
||||
|
||||
### 5.2 与旧版的区别
|
||||
**重要特征**：CrossEncoder 对不同类型切片的评分分布差异显著：
|
||||
|
||||
| 对比项 | 旧版（本地 BGE-reranker） | v7.0.0（云端 qwen3-rerank） |
|
||||
|--------|--------------------------|---------------------------|
|
||||
| 部署方式 | 本地模型加载 | DashScope API 远程调用 |
|
||||
| 资源占用 | 需要 GPU 显存 | 无本地资源消耗 |
|
||||
| 模型能力 | BGE-reranker（较小） | qwen3-rerank（更强） |
|
||||
| 延迟 | 低（本地推理） | 中等（网络往返） |
|
||||
| 切片类型 | 典型分数范围 | 说明 |
|
||||
|----------|------------|------|
|
||||
| 文本切片 | 0.3 ~ 0.99 | 正常分布 |
|
||||
| 表格切片 | 0.1 ~ 0.5 | 偏低，有专用救援逻辑 |
|
||||
| 图片/图表切片 | 0.002 ~ 0.08 | 系统性偏低，需要宽松阈值 |
|
||||
|
||||
### 5.2 Rerank 缓存
|
||||
|
||||
- 每个 (query, doc_id) 对的 rerank 分数独立缓存
|
||||
- TTL = 1 小时
|
||||
- 知识库版本号变更时自动失效
|
||||
|
||||
---
|
||||
|
||||
## 六、MMR 去重
|
||||
## 六、救援管道
|
||||
|
||||
### 6.1 配置
|
||||
**入口文件**：`api/chat_routes.py`
|
||||
**目的**：挽救被 CrossEncoder 低估但实际相关的切片
|
||||
|
||||
v7.0.0 采用文本相似度模式进行 MMR（Maximal Marginal Relevance）去重：
|
||||
在 `_order_text_contexts_for_prompt` 之前执行，三个救援管道按顺序运行：
|
||||
|
||||
```
|
||||
MMR_USE_EMBEDDING = false
|
||||
```
|
||||
### 6.1 BM25 分歧救援 `_rescue_bm25_divergence`
|
||||
|
||||
### 6.2 工作原理
|
||||
**触发条件**：BM25 排名 top-3 但 CrossEngineer 评分低于 min_score 的切片
|
||||
|
||||
使用文本 Jaccard 相似度（而非 embedding 向量余弦相似度）来衡量候选文档之间的重复程度：
|
||||
**逻辑**：BM25 是关键词精确匹配的强信号，如果 BM25 认为相关但 CE 误判，提升分数至保底值。
|
||||
|
||||
```python
|
||||
def _apply_mmr(query, candidates, top_k=30, lambda_param=0.7):
|
||||
"""
|
||||
MMR 去重：在相关性和多样性之间取得平衡
|
||||
|
||||
lambda_param=0.7: 70% 权重给相关性，30% 权重给多样性
|
||||
相似度度量：文本 Jaccard 系数（基于词集合交集/并集）
|
||||
"""
|
||||
selected = []
|
||||
for candidate in candidates:
|
||||
if not selected:
|
||||
selected.append(candidate)
|
||||
continue
|
||||
|
||||
# Jaccard 相似度（文本模式）
|
||||
max_sim = max(
|
||||
jaccard_similarity(candidate.tokens, s.tokens)
|
||||
for s in selected
|
||||
)
|
||||
|
||||
mmr_score = lambda_param * relevance - (1 - lambda_param) * max_sim
|
||||
if mmr_score > threshold:
|
||||
selected.append(candidate)
|
||||
|
||||
return selected[:top_k]
|
||||
# 配置
|
||||
BM25_DIVERGENCE_RESCUE_ENABLED = True
|
||||
BM25_DIVERGENCE_MAX_RANK = 3 # 仅救援 BM25 rank <= 3 的切片
|
||||
```
|
||||
|
||||
### 6.3 选择文本模式的原因
|
||||
### 6.2 词法匹配救援 `_rescue_lexical_match`
|
||||
|
||||
- **速度更快**：无需计算 embedding 向量之间的余弦相似度
|
||||
- **效果直观**：Jaccard 系数直接反映文本内容的重叠程度
|
||||
- **避免向量偏差**：embedding 模型可能对格式化内容（如图片描述）产生不准确的相似度
|
||||
**触发条件**：切片文本精确包含查询关键词（bigram 匹配率 > 35%）但 CE 评分低
|
||||
|
||||
**逻辑**：当切片文本直接包含查询中的关键词组合时，说明语义相关，CE 可能因为表述差异低估。
|
||||
|
||||
### 6.3 章节聚类救援 `_rescue_section_cluster`
|
||||
|
||||
**触发条件**：同一 section 内所有切片都被 min_score 过滤（"全灭 section"）
|
||||
|
||||
**逻辑**：如果同一章节的切片全部被过滤，但其他章节有切片通过，说明 CE 对该章节整体低估。为全灭 section 的切片分配保底分数（0.06）。
|
||||
|
||||
```python
|
||||
# 配置
|
||||
SECTION_CLUSTER_RESCUE_ENABLED = True
|
||||
CLUSTER_RESCUE_FLOOR = 0.06 # 略高于 RERANK_CONTEXT_MIN_SCORE=0.05
|
||||
```
|
||||
|
||||
### 6.4 表格救援 `_rescue_table_chunks`
|
||||
|
||||
**触发条件**：查询涉及表格但上下文中没有表格数据（表格被预算截断）
|
||||
|
||||
**逻辑**：从被截断的切片中补回表格数据。
|
||||
|
||||
---
|
||||
|
||||
## 七、上下文构建
|
||||
|
||||
### 7.1 检索结果处理
|
||||
### 7.1 切片排序与过滤 `_order_text_contexts_for_prompt`
|
||||
|
||||
**入口文件**：`api/chat_routes.py`
|
||||
**核心逻辑**：
|
||||
|
||||
将检索结果转换为 LLM 可用的上下文列表：
|
||||
1. **文本切片 + 表格切片** → 进入 `text_contexts`
|
||||
2. **图片/图表切片** → 进入 `chart_contexts`（独立处理）
|
||||
3. **min_score 过滤**：
|
||||
- `text_contexts`：使用 `RERANK_CONTEXT_MIN_SCORE`（0.05）
|
||||
- 表格保护：同 section 内如有切片通过阈值，table 切片保底分数为 `min_score * 0.3`
|
||||
- `chart_contexts`：使用宽松阈值 `min_score * 0.5`（0.025）
|
||||
- 原因：CrossEncoder 对图片描述评分系统性偏低
|
||||
- 实际内容相关性由 `select_images` 独立评分保证
|
||||
4. **合并**：`text_contexts + chart_contexts[:3]`
|
||||
|
||||
```python
|
||||
contexts = []
|
||||
for result in search_results:
|
||||
meta = result['metadata']
|
||||
if meta['chunk_type'] in ('image', 'chart'):
|
||||
# 图片切片：使用完整描述（而非轻量描述）
|
||||
doc = meta.get('full_description', result['document'])
|
||||
else:
|
||||
doc = result['document']
|
||||
contexts.append({'doc': doc, 'meta': meta})
|
||||
```
|
||||
### 7.2 预算构建 `_build_context_with_budget`
|
||||
|
||||
### 7.2 懒加载增强
|
||||
按字符预算构建上下文文本：
|
||||
|
||||
对没有 VLM 描述的图片切片，按需调用 VLM 生成更精准的语义描述：
|
||||
1. 按 (source, section) 分组
|
||||
2. 组内按 chunk_index 排序（保持原文连续性）
|
||||
3. 组间按组内最高 Rerank 分数降序
|
||||
4. 逐组加入直到达到 `CONTEXT_MAX_CHARS`（8000）
|
||||
5. 超过 `CONTEXT_SOFT_LIMIT`（6000）后收紧准入
|
||||
|
||||
```python
|
||||
enhance_retrieved_chunks(contexts, query, kb_name)
|
||||
# 对缺少 VLM 描述的图片 → 调用 qwen-vl-plus 生成描述
|
||||
```
|
||||
**特殊处理**：表格切片不受预算截断（结构化关键内容）
|
||||
|
||||
### 7.3 图片选择
|
||||
|
||||
**核心函数**：`select_images()`
|
||||
### 7.3 图片选择 `select_images()`
|
||||
|
||||
从检索结果中筛选与查询最相关的图片：
|
||||
|
||||
**步骤一：意图检测**
|
||||
**步骤一：动态预算**
|
||||
|
||||
| 查询类型 | 参数调整 |
|
||||
|----------|----------|
|
||||
| 精确图号查询（"图2.3"） | `MAX_IMAGES=2, MIN_SCORE=5.0` |
|
||||
| 弱图片意图（"发电量图"） | `MAX_IMAGES=1` |
|
||||
| 普通查询 | `MAX_IMAGES=2` |
|
||||
| 查询类型 | MAX_IMAGES | MIN_SCORE | 检测方式 |
|
||||
|----------|------------|-----------|----------|
|
||||
| 精确图号查询（"图2.3"） | 2 | 5.0 | 正则匹配 `图\s*(\d+\.?\d*)` |
|
||||
| 有图片数据（检索含 image/chart） | 5 | 2.0 | 检查检索结果 chunk_type |
|
||||
| 文本引用图表 | 3 | 2.0 | 提取 top-5 文本中的图号/表号 |
|
||||
| 普通查询 | 2 | 3.0 | 默认 |
|
||||
|
||||
**步骤二：提取图表引用**
|
||||
|
||||
从 top 5 文本块中提取 "见图2.3"、"如表2.2" 等引用，建立图号与来源文件的映射：
|
||||
从 top 5 文本块中提取 "见图2.3"、"如表2.2" 等引用，建立图号与来源文件的映射。
|
||||
|
||||
```python
|
||||
referenced_figures = {'2.3': {'source_file': 'xxx.pdf'}, ...}
|
||||
```
|
||||
|
||||
**步骤三：图片相关性打分**
|
||||
|
||||
`score_image_relevance()` 打分规则：
|
||||
**步骤三：图片相关性打分 `score_image_relevance()`**
|
||||
|
||||
| 匹配项 | 加分 |
|
||||
|--------|------|
|
||||
| 图号精确匹配（查询中有"图2.3"） | +10 分 |
|
||||
| 表号精确匹配 | +10 分 |
|
||||
| 关键词匹配（"发电量"等） | +2 分/个 |
|
||||
| 字符重叠 | +0.2 分/字符 |
|
||||
| 章节匹配 | +1.5 分 |
|
||||
| 图片类型（chart > image） | +2 / +1 分 |
|
||||
| 关键词匹配（jieba 分词） | +2 分/个，上限 8 分 |
|
||||
| 字符重叠 | +0.2 分/字符，上限 3 分 |
|
||||
| 章节匹配 | +1.5 分/关键词 |
|
||||
| 图片类型（chart） | +2 分 |
|
||||
| 图片类型（image） | +1 分 |
|
||||
| 向量相似度 | +2 分（最高） |
|
||||
| 引用匹配（需章节相关） | +8 分 |
|
||||
| 引用匹配 + 章节相关 | +8 分 + 5 分 |
|
||||
| VLM 相关性 < 0.3 | -3 分（VLM 描述与查询不相关） |
|
||||
| VLM 相关性 ≥ 0.5 | +2 分 |
|
||||
| 章节不相关 | -5 分（除非被文本引用） |
|
||||
|
||||
**步骤四：图文关联补充**
|
||||
**步骤四：VLM 相关性筛选**
|
||||
|
||||
遍历 top 5 文本块中引用的图表编号，查找对应的图片切片并补充到结果中。
|
||||
对有 VLM 描述的图片，使用关键词重叠率判断描述与查询的相关性：
|
||||
- 重叠率 < 0.3：降分 -3（描述与查询不相关）
|
||||
- 重叠率 ≥ 0.5：加分 +2
|
||||
|
||||
**步骤五：返回 top N 图片**
|
||||
**步骤五：CrossEncoder 精排**
|
||||
|
||||
对 `select_images` 候选用 CE 做语义精排：
|
||||
- CE < 0：直接剔除（语义不相关）
|
||||
- CE 0~2：保留但不加分（弱相关）
|
||||
- CE > 2：加分 `min((ce - 2) / 3, 1) * 5`
|
||||
|
||||
**步骤六：表格嵌入图片补充**
|
||||
|
||||
处理 `images_json` 字段的表格切片，补充表格中嵌入的图片。
|
||||
|
||||
**步骤七：文本引用图片补充**
|
||||
|
||||
从 top 5 文本块中提取 `referenced_images` 字段，补充未选中的关联图片。
|
||||
|
||||
**步骤八：返回 top N**
|
||||
|
||||
```python
|
||||
scored_images.sort(key=lambda x: x['score'], reverse=True)
|
||||
return scored_images[:MAX_IMAGES]
|
||||
```
|
||||
|
||||
### 7.4 构建 LLM Prompt
|
||||
### 7.4 图片描述注入
|
||||
|
||||
```python
|
||||
# 文本上下文
|
||||
context_text = "\n\n".join([ctx['doc'] for ctx in contexts[:5]])
|
||||
**核心逻辑**：将 `select_images` 选中的图片的 `full_description` 注入到 LLM context 中。
|
||||
|
||||
# 图片信息
|
||||
if selected_images:
|
||||
image_info = "【可用图片】\n" + 图片描述列表
|
||||
|
||||
# 最终上下文
|
||||
enhanced_context = context_text + image_info
|
||||
```
|
||||
context_text（文本切片）
|
||||
+
|
||||
【相关图片信息】
|
||||
【图片1】VLM 完整描述（来源：xxx 第N页）
|
||||
【图片2】VLM 完整描述（来源：xxx 第N页）
|
||||
+
|
||||
【回答要求】回答时请简要介绍每张图片的内容和用途。
|
||||
```
|
||||
|
||||
**P0 安全网**（防止图片描述被过滤遗漏）：
|
||||
|
||||
1. 若 `selected_images` 非空但 `【相关图片信息】` 未生成 → 补注入所有选中图片描述
|
||||
2. 若已有 `【相关图片信息】` 但遗漏部分图片 → 追加遗漏的描述
|
||||
3. DEV 模式日志：检查所有选中图片的 ID 是否出现在 context 中
|
||||
|
||||
### 7.5 置信度指令
|
||||
|
||||
根据 top-3 切片的平均 Rerank 分数注入不同的回答指令：
|
||||
|
||||
| 置信度范围 | 指令 |
|
||||
|-----------|------|
|
||||
| < 0.15 | "参考资料与问题的相关性较低，仅基于明确信息回答，不足则说明" |
|
||||
| 0.15 ~ 0.30 | "参考资料的相关性一般，优先引用资料原文，避免推测" |
|
||||
| ≥ 0.30 | 无额外指令 |
|
||||
|
||||
---
|
||||
|
||||
## 八、LLM 生成
|
||||
|
||||
### 8.1 AgenticRAG 引擎
|
||||
|
||||
v7.0.0 将 Agentic 引擎拆分为独立的子模块，各司其职：
|
||||
|
||||
| 子模块 | 职责 |
|
||||
|--------|------|
|
||||
| `agentic_search.py` | 检索调度：管理多轮检索、查询分解 |
|
||||
| `agentic_answer.py` | 回答生成：基于上下文生成最终回答 |
|
||||
| `agentic_citation.py` | 引用标注：在回答中插入来源引用标记 |
|
||||
| `agentic_context.py` | 上下文管理：上下文窗口控制、截断策略 |
|
||||
| `agentic_query.py` | 查询处理：查询改写、多查询生成 |
|
||||
| `agentic_media.py` | 多媒体处理：图片理解、表格解析 |
|
||||
| `agentic_quality.py` | 质量控制：回答质量评估、幻觉检测 |
|
||||
| `agentic_meta.py` | 元数据管理：知识库信息、检索统计 |
|
||||
|
||||
### 8.2 流式生成
|
||||
### 8.1 流式生成
|
||||
|
||||
使用 SSE（Server-Sent Events）实现流式输出：
|
||||
|
||||
```python
|
||||
for token in engine.generate_answer_stream(query, enhanced_context):
|
||||
for token in engine.generate_answer_stream(query, enhanced_context, history):
|
||||
yield token # 逐 token 推送给前端
|
||||
```
|
||||
|
||||
**主 LLM 模型**：qwen3.6-flash
|
||||
**VLM 模型**：qwen-vl-plus（处理图片理解任务）
|
||||
**LLM 模型**：mimo-v2.5
|
||||
|
||||
### 8.3 回答结构
|
||||
### 8.2 System Prompt
|
||||
|
||||
```
|
||||
你是一个严谨的知识库问答助手。
|
||||
你必须且只能根据用户提供的【参考资料】回答问题。
|
||||
如果参考资料中有答案，必须引用对应内容回答，并在回答末尾标注引用编号。
|
||||
如果参考资料中确实没有相关信息，简短说明即可，不要编造或补充资料外的内容。
|
||||
禁止使用参考资料以外的知识进行补充或推测。
|
||||
【重要-表格处理规则】当用户询问表格时，必须将 Markdown 表格原样输出...
|
||||
```
|
||||
|
||||
### 8.3 图片后置过滤 `_filter_images_by_answer`
|
||||
|
||||
LLM 生成回答后，根据回答内容对图片做最终过滤：
|
||||
|
||||
1. **候选 ≤ 1 张**：直接返回
|
||||
2. **无图意图早退**：回答和查询都不含图片引用词 → 返回空
|
||||
3. **图号精确豁免**：图片描述包含回答引用的具体图号/表号 → 无条件保留
|
||||
4. **主题一致性**：合并查询+回答关键词，图片描述重叠 ≥ 阈值才保留
|
||||
- 子章节惩罚：图片子章节与主要检索章节不一致时，阈值 +2
|
||||
5. **兜底**：过滤后为空且有图片意图 → 保留分数最高的 1 张
|
||||
|
||||
### 8.4 回答结构
|
||||
|
||||
```python
|
||||
{
|
||||
@@ -443,7 +495,8 @@ for token in engine.generate_answer_stream(query, enhanced_context):
|
||||
"type": "chart",
|
||||
"source": "三峡公报_2022.pdf",
|
||||
"page": 12,
|
||||
"description": "图2.3 柱状图：2003-2022年逐年发电量"
|
||||
"description": "图2.3 柱状图：2003-2022年逐年发电量",
|
||||
"full_description": "...完整 VLM 描述..."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -455,13 +508,10 @@ for token in engine.generate_answer_stream(query, enhanced_context):
|
||||
|
||||
### 9.1 引用标注机制
|
||||
|
||||
`agentic_citation.py` 负责在回答中插入引用标记，将回答内容与知识库来源关联：
|
||||
`_attach_citations()` 负责在回答中插入引用标记，将回答内容与知识库来源关联：
|
||||
|
||||
```
|
||||
根据统计数据[1]，2022年三峡电站年度发电量为787.90亿千瓦时[2]。
|
||||
|
||||
[1] 来源：三峡公报_2022.pdf，第12页，综述 > 2.3 发电
|
||||
[2] 来源：三峡公报_2022.pdf，第15页，表2.1
|
||||
根据统计数据[ref:三峡公报_text_24]，2022年三峡电站年度发电量为787.90亿千瓦时[ref:三峡公报_table_5]。
|
||||
```
|
||||
|
||||
### 9.2 引用数据来源
|
||||
@@ -476,10 +526,6 @@ for token in engine.generate_answer_stream(query, enhanced_context):
|
||||
| `chunk_id` | 切片唯一标识 |
|
||||
| `chunk_type` | 类型（text / table / image / chart） |
|
||||
|
||||
### 9.3 前端引用跳转
|
||||
|
||||
前端解析回答中的引用标记（如 `[1]`），渲染为可点击的链接，点击后跳转到对应的来源文件或页面。
|
||||
|
||||
---
|
||||
|
||||
## 十、文档入库流程（补充参考）
|
||||
@@ -510,28 +556,7 @@ MinerU 解析 PDF/Word/Excel 文件，输出结构化内容：
|
||||
| `image` | 图片 | content(=caption), image_path, context_before/after |
|
||||
| `chart` | 图表 | content(=caption), image_path, context_before/after |
|
||||
|
||||
### 10.2 MinerUChunk 数据结构
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class MinerUChunk:
|
||||
content: str # 文本内容
|
||||
chunk_type: str # 类型: text, table, image, chart
|
||||
page_start: int = 1 # 起始页码
|
||||
page_end: int = 1 # 结束页码
|
||||
text_level: int = 0 # 标题级别 (0=正文, 1=h1, 2=h2...)
|
||||
title: str = "" # 标题文本
|
||||
section_path: str = "" # 章节路径
|
||||
bbox: Optional[List[float]] = None # 边界框 [x0, y0, x1, y1]
|
||||
source_file: str = "" # 源文件名
|
||||
table_html: Optional[str] = None # 表格 HTML
|
||||
image_path: Optional[str] = None # 图片路径
|
||||
images: Optional[List[Dict]] = None # 关联图片列表
|
||||
context_before: str = "" # 图片前的文本上下文
|
||||
context_after: str = "" # 图片后的文本上下文
|
||||
```
|
||||
|
||||
### 10.3 切片入库
|
||||
### 10.2 切片入库
|
||||
|
||||
**入口文件**：`knowledge/manager.py`
|
||||
**核心函数**：`add_file_to_kb()`
|
||||
@@ -547,63 +572,95 @@ MinerUChunk 列表
|
||||
```
|
||||
|
||||
**图片描述策略**：
|
||||
1. 优先使用 VLM 缓存描述（语义更丰富，由 qwen-vl-plus 生成）
|
||||
1. 优先使用 VLM 缓存描述（由 mimo-v2.5 生成，语义更丰富）
|
||||
2. 若无缓存，生成轻量描述（基于文件名 + 章节路径 + 上下文）
|
||||
3. VLM 描述异步懒加载：首次检索命中时后台生成，下次查询即可使用
|
||||
|
||||
轻量描述示例：
|
||||
```
|
||||
图表：图2.3，位于「综述 > 2.3发电」，第12页
|
||||
前文：受长江流域性严重枯水影响，2022年三峡电站年度发电量为787.90亿千瓦时...
|
||||
后文：2.4航运 三峡船闸和葛洲坝船闸实行统一调度...
|
||||
```
|
||||
|
||||
VLM 描述示例（更精准）：
|
||||
```
|
||||
图2.3 柱状图 主要内容描述：该柱状图展示了2003年至2022年每年的发电量（单位：亿千瓦时）。
|
||||
发电量在2003年为86.07亿千瓦时，随后逐年波动上升，至2020年达到峰值1118.02亿千瓦时...
|
||||
```
|
||||
|
||||
### 10.4 ChromaDB 存储结构
|
||||
### 10.3 ChromaDB 存储结构
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `ids` | str | 切片唯一标识，如 `doc.pdf_text_24` |
|
||||
| `embeddings` | List[float] | 向量表示 |
|
||||
| `documents` | str | 切片内容（文本/描述/摘要） |
|
||||
| `documents` | str | 切片内容（文本/VLM 描述/摘要） |
|
||||
| `metadatas` | dict | 元数据（见下表） |
|
||||
|
||||
**图片切片 metadata 示例**：
|
||||
**图片切片 metadata 关键字段**：
|
||||
|
||||
```python
|
||||
{
|
||||
'source': '三峡公报_2022.pdf',
|
||||
'page': 12,
|
||||
'chunk_type': 'chart',
|
||||
'section': '综述 > 2.3发电',
|
||||
'figure_number': '2.3',
|
||||
'image_path': 'ab77281e7913.jpg',
|
||||
'has_vlm_desc': True,
|
||||
'preview': '图2.3 柱状图 主要内容...'
|
||||
'source': '三峡公报_2022.pdf', # 源文件名
|
||||
'page': 12, # 页码
|
||||
'chunk_type': 'chart', # 切片类型
|
||||
'section': '综述 > 2.3发电', # 章节路径
|
||||
'image_path': 'ab77281e7913.jpg', # 图片文件名
|
||||
'has_vlm_desc': True, # 是否有 VLM 描述
|
||||
'vlm_desc': '图2.3 柱状图...', # VLM 描述内容
|
||||
'chunk_id': '三峡公报_chart_5', # 切片唯一标识
|
||||
'version': 'v10', # 知识库版本号
|
||||
'status': 'active', # 状态
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**：ChromaDB metadata 中**没有** `full_description` 字段。图片的完整描述存储在 `vlm_desc` 字段或 `documents` 字段中。`full_description` 仅在 `select_images()` 运行时动态计算。
|
||||
|
||||
### 10.4 懒加载增强
|
||||
|
||||
**入口文件**：`knowledge/lazy_enhance.py`
|
||||
|
||||
对检索命中但没有 VLM 描述的图片切片，在后台线程异步调用 VLM 生成描述：
|
||||
|
||||
```python
|
||||
# 检索命中 → 后台线程调用 VLM → 写入文件缓存 + ChromaDB
|
||||
enhance_retrieved_chunks(contexts, query, kb_name, defer_chromadb=True)
|
||||
```
|
||||
|
||||
- **image/chart 切片**：更新 `ctx['doc']` 字段
|
||||
- **table 切片**：更新 `ctx['image_description']` 字段
|
||||
- **缓存目录**：`.data/cache/vlm/`、`.data/cache/llm/`
|
||||
|
||||
---
|
||||
|
||||
## 十一、缓存系统
|
||||
|
||||
### 11.1 缓存层级
|
||||
|
||||
| 层级 | 类 | 用途 | 容量 | TTL |
|
||||
|------|-----|------|------|-----|
|
||||
| query_cache | LRUCache | 精确查询结果缓存 | 500 | 无 |
|
||||
| embedding_cache | LRUCache | 查询 embedding 向量 | 500 | 无 |
|
||||
| rerank_cache | TTLCache | Rerank 分数缓存 | 500 | 1h |
|
||||
| semantic_cache | SemanticCache | 语义相似查询缓存 | 200 | 无 |
|
||||
| intent_exact_cache | LRUCache | 意图分析精确缓存 | 200 | 无 |
|
||||
|
||||
### 11.2 缓存失效
|
||||
|
||||
- **版本失效**：知识库版本号变更时，query_cache 和 rerank_cache 自动失效
|
||||
- **手动清除**：`POST /cache/clear`（DEV 模式）
|
||||
|
||||
### 11.3 缓存 API
|
||||
|
||||
```
|
||||
GET /cache/stats — 查看缓存统计
|
||||
POST /cache/clear — 清除所有缓存
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十一、关键文件索引
|
||||
## 十二、关键文件索引
|
||||
|
||||
| 文件 | 职责 | 关键函数/类 |
|
||||
|------|------|-------------|
|
||||
| `api/chat_routes.py` | API 路由与请求调度 | `generate()`, `select_images()`, `score_image_relevance()` |
|
||||
| `api/chat_routes.py` | API 路由与请求调度 | `rag()`, `select_images()`, `score_image_relevance()`, `_filter_images_by_answer()`, `_order_text_contexts_for_prompt()`, `_build_context_with_budget()` |
|
||||
| `core/engine.py` | 检索引擎核心 | `search_knowledge()`, `rerank_results()`, `generate_answer_stream()` |
|
||||
| `core/intent_analyzer.py` | 意图分析 | `analyze()`, `IntentAnalysis` |
|
||||
| `core/engine.py` | 检索引擎核心 | `search_knowledge()`, `reciprocal_rank_fusion()`, `rerank_results()` |
|
||||
| `core/agentic_search.py` | 检索调度 | 多轮检索、查询分解 |
|
||||
| `core/agentic_answer.py` | 回答生成 | 基于上下文生成最终回答 |
|
||||
| `core/agentic_citation.py` | 引用标注 | 来源引用标记插入 |
|
||||
| `core/agentic_context.py` | 上下文管理 | 上下文窗口控制、截断 |
|
||||
| `core/agentic_query.py` | 查询处理 | 查询改写、多查询生成 |
|
||||
| `core/agentic_media.py` | 多媒体处理 | 图片理解、表格解析 |
|
||||
| `core/agentic_quality.py` | 质量控制 | 回答质量评估、幻觉检测 |
|
||||
| `core/agentic_meta.py` | 元数据管理 | 知识库信息、检索统计 |
|
||||
| `core/bm25_index.py` | BM25 关键词检索 | `BM25Index.search()` |
|
||||
| `core/mmr.py` | MMR 去重 | `mmr_rerank()` |
|
||||
| `core/cache.py` | 缓存管理 | `RAGCacheManager`, `get_cache_manager()` |
|
||||
| `core/semantic_cache.py` | 语义缓存 | `SemanticCache` |
|
||||
| `core/chunker.py` | 语义分块器 | `SemanticChunker` |
|
||||
| `core/llm_utils.py` | LLM 调用工具 | `call_llm()`, `call_llm_stream()` |
|
||||
| `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()`, `KBManager` |
|
||||
| `knowledge/lazy_enhance.py` | 懒加载增强 | `lazy_vlm_description()`, `enhance_retrieved_chunks()` |
|
||||
| `config.py` | 配置集中管理 | 模型/参数/开关 |
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# RAG 系统完整指南
|
||||
|
||||
> **版本**: v4.0（统一编排 + 四层缓存修复）
|
||||
> **版本**: v4.1（模型切换 + 图片检索修复）
|
||||
> **生产入口**: `api/chat_routes.py::rag()` → `generate()` → `core/engine.py`
|
||||
> **最后更新**: 2026-06-05
|
||||
> **最后更新**: 2026-06-21
|
||||
>
|
||||
> 本次更新：删除未使用的 AgenticRAG 备用编排路径（10 个文件 ~2050 行），修复 Query Cache 键不匹配与阈值问题，将语义缓存集成至生产 `/rag` 端点。
|
||||
> 本次更新：LLM/意图/VLM 模型统一切换至 mimo-v2.5（xiaomimimo.com API），Reranker 切换至 xop3qwen8breranker（讯飞云 API），新增 chart_contexts 降门槛、P0 安全网、答案后过滤等图片检索修复逻辑。
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
@@ -14,12 +14,13 @@
|
||||
|------|------|----------|
|
||||
| **意图分析** | LLM 驱动的双层判断（是否需要检索）+ 查询改写 | `core/intent_analyzer.py` |
|
||||
| **混合检索** | 向量检索 + BM25 + RRF 融合 + Rerank 重排 | `core/engine.py` |
|
||||
| **四层缓存** | Query + Embedding + Rerank（LRU）+ 语义缓存（FAISS） | `core/cache.py` + `core/semantic_cache.py` |
|
||||
| **五层缓存** | Query + Embedding + Rerank（LRU）+ 语义缓存（FAISS）+ ChromaDB 元数据缓存 | `core/cache.py` + `core/semantic_cache.py` |
|
||||
| **流式生成** | SSE 流式答案输出，逐 token 推送 | `core/engine.py::generate_answer_stream()` |
|
||||
| **引用标注** | 自动标注信息来源和引用编号 | `api/chat_routes.py::_attach_citations()` |
|
||||
| **富媒体** | 图片/表格的智能提取与展示 | `api/chat_routes.py` |
|
||||
| **富媒体** | 图片/表格的智能提取与展示 + P0 安全网 + 答案后过滤 | `api/chat_routes.py` |
|
||||
| **查询理解** | 查询分解、扩展、MMR 去重、自适应 TopK | `core/` 各独立模块 |
|
||||
| **安全护栏** | 敏感信息过滤、Prompt 安全守卫 | `api/response_utils.py`、`core/prompt_guard.py` |
|
||||
| **救援管线** | BM25 散度救援、词法匹配救援、章节聚类救援、表格救援 | `core/engine.py` |
|
||||
|
||||
---
|
||||
|
||||
@@ -78,9 +79,12 @@
|
||||
│ │ FAQ 加权 │→ │ 黑名单过滤 │→ │ 时间衰减 │ │
|
||||
│ └───────────┘ └──────────────┘ └──────┬───────┘ │
|
||||
│ ↓ │
|
||||
│ ┌───────────────┐ ┌──────────────┐ │
|
||||
│ │ 上下文扩展 │→ │ 自适应 TopK │ │
|
||||
│ └───────────────┘ └──────────────┘ │
|
||||
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ 上下文扩展 │→ │ 自适应 TopK │→ │ 救援管线 │ │
|
||||
│ └───────────────┘ └──────────────┘ │ (BM25散度/ │ │
|
||||
│ │ 词法/章节/ │ │
|
||||
│ │ 表格救援) │ │
|
||||
│ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
@@ -105,7 +109,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 三、四层缓存架构
|
||||
## 三、五层缓存架构
|
||||
|
||||
### 3.1 缓存层次概览
|
||||
|
||||
@@ -115,6 +119,7 @@
|
||||
| L2 | Embedding Cache | LRU (OrderedDict) | 2000 条 | 24 小时 | 缓存向量化结果，避免重复调用 embedding 模型 |
|
||||
| L3 | Rerank Cache | LRU (OrderedDict) | 1000 条 | 1 小时 | 缓存 Rerank 分数，避免重复调用 Reranker |
|
||||
| L4 | Semantic Cache | FAISS IndexFlatIP | 10000 条 | 无过期 | 语义级缓存，相似查询也能命中 |
|
||||
| L5 | ChromaDB 元数据缓存 | 进程内 dict | 无限制 | 无过期 | 缓存 ChromaDB Collection 元数据（kb_version 等），避免频繁查询 ChromaDB |
|
||||
|
||||
### 3.2 Query Cache
|
||||
|
||||
@@ -288,9 +293,9 @@ search_knowledge(query, top_k=30)
|
||||
│
|
||||
├─ 7. 章节过滤（查询提到章节时优先匹配）
|
||||
│
|
||||
├─ 8. ★ Rerank 重排 ★（云端 DashScope qwen3-rerank 或本地 BGE）
|
||||
│ └─ rerank_results(query, results, top_k)
|
||||
│ └─ 由 RERANK_BACKEND 控制（local/cloud/fallback）
|
||||
├─ 8. ★ Rerank 重排 ★（云端讯飞 xop3qwen8breranker 或本地 BGE）
|
||||
│ └─ rerank_results(query, results, top_k)
|
||||
│ └─ 由 RERANK_BACKEND 控制（local/cloud/fallback）
|
||||
│
|
||||
├─ 9. MMR 去重
|
||||
│ ├─ 语义向量版（MMR_USE_EMBEDDING=True）
|
||||
@@ -306,7 +311,9 @@ search_knowledge(query, top_k=30)
|
||||
│
|
||||
├─ 14. 自适应 TopK（根据置信度调整返回数量）
|
||||
│
|
||||
└─ 15. 缓存写入 → 返回结果
|
||||
├─ 15. 救援管线（BM25散度/词法匹配/章节聚类/表格救援）
|
||||
│
|
||||
└─ 16. 缓存写入 → 返回结果
|
||||
```
|
||||
|
||||
### 5.2 混合检索代码示例
|
||||
@@ -330,7 +337,7 @@ image_results = collection.query(
|
||||
# RRF 融合（动态权重）
|
||||
fused = reciprocal_rank_fusion([vector_results, bm25_results], weights=[vector_w, bm25_w])
|
||||
|
||||
# Rerank 重排（云端 DashScope qwen3-rerank 或本地 BGE）
|
||||
# Rerank 重排（云端讯飞 xop3qwen8breranker 或本地 BGE）
|
||||
reranked = rerank_results(query, fused, top_k=15)
|
||||
|
||||
# MMR 去重
|
||||
@@ -359,7 +366,7 @@ RRF分数 = Σ (权重 / (k + 排名位置))
|
||||
|
||||
| RERANK_BACKEND | 说明 |
|
||||
|----------------|------|
|
||||
| `"cloud"` | 仅使用云端 DashScope `qwen3-rerank` API |
|
||||
| `"cloud"` | 仅使用云端讯飞 `xop3qwen8breranker` API |
|
||||
| `"local"` | 仅使用本地 `BAAI/bge-reranker-base`（CrossEncoder / ONNX） |
|
||||
| `"fallback"` | 优先云端，失败时自动回退本地（推荐生产环境） |
|
||||
|
||||
@@ -368,13 +375,13 @@ RRF分数 = Σ (权重 / (k + 排名位置))
|
||||
```python
|
||||
# config.py
|
||||
RERANK_BACKEND = os.getenv("RERANK_BACKEND", "local")
|
||||
RERANK_CLOUD_MODEL = "qwen3-rerank"
|
||||
RERANK_CLOUD_MODEL = "xop3qwen8breranker"
|
||||
RERANK_CLOUD_API_KEY = os.getenv("RERANK_CLOUD_API_KEY", DASHSCOPE_API_KEY)
|
||||
RERANK_CLOUD_BASE_URL = "https://dashscope.aliyuncs.com/compatible-api/v1/reranks"
|
||||
RERANK_CLOUD_BASE_URL = "https://maas-api.cn-huabei-1.xf-yun.com/v1/rerank"
|
||||
RERANK_CLOUD_TIMEOUT = 15
|
||||
```
|
||||
|
||||
`CloudReranker` 类（`core/engine.py`）封装 DashScope 的 `/compatible-api/v1/reranks` 接口，提供与本地 `CrossEncoder.predict()` / `ONNXReranker.predict()` 一致的调用接口。
|
||||
`CloudReranker` 类（`core/engine.py`）封装讯飞云的 `/v1/rerank` 接口，提供与本地 `CrossEncoder.predict()` / `ONNXReranker.predict()` 一致的调用接口。
|
||||
|
||||
**本地 Reranker（备选）**：
|
||||
|
||||
@@ -424,12 +431,16 @@ POST /rag (SSE 流式)
|
||||
├─ 5. 图片补充检索 + 图片打分选择 (select_images)
|
||||
│ └─[DEV] 发 SSE: images_selected
|
||||
├─ 6. 构建上下文 (_order_texts_for_prompt)
|
||||
│ └─ chart_contexts 使用 min_score * 0.5 降门槛
|
||||
│ └─[DEV] 发 SSE: context_built
|
||||
│
|
||||
├─ 6.5. P0 安全网 — 确保 selected_images 描述完整进入 LLM 上下文
|
||||
│
|
||||
├─ 7. 流式答案生成 engine.generate_answer_stream()
|
||||
│ └─ 逐 token 发 SSE: chunk
|
||||
│
|
||||
├─ 8. 答案图号对齐过滤
|
||||
├─ 8.5. 答案后过滤 (_filter_images_by_answer) — 根据 LLM 答案过滤不相关图片
|
||||
├─ 9. 引用标注 _attach_citations()
|
||||
├─ 10. 敏感信息过滤 filter_response()
|
||||
├─ 11. 语义缓存写入 SemanticCache.set() # 写入缓存供后续命中
|
||||
@@ -454,6 +465,76 @@ POST /rag (SSE 流式)
|
||||
|
||||
> 标注 [DEV] 的事件仅在 `IS_DEV=True` 时发送。
|
||||
|
||||
### 6.1 图片检索子系统
|
||||
|
||||
图片检索是独立于文本上下文管线的子系统，存在特有的"两管线断裂"问题，已通过多重修复保障完整性。
|
||||
|
||||
**图片检索流程**：
|
||||
|
||||
```
|
||||
search_knowledge() 返回混合检索结果
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ _order_text_contexts_for_prompt() — 上下文提取与构建 │
|
||||
│ │
|
||||
│ 1. 分离 text_contexts 和 chart_contexts │
|
||||
│ 2. chart_contexts 使用 min_score * 0.5 降门槛过滤 │
|
||||
│ （CrossEncoder 对图片打分系统性偏低：0.002-0.08） │
|
||||
│ 3. chart_contexts 的描述注入 context_text 【相关图片信息】 │
|
||||
│ 4. text_contexts 正常注入 context_text │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
↓ ↓
|
||||
┌──────────────────┐ ┌──────────────────────────────────────┐
|
||||
│ select_images() │ │ context_text 送入 LLM │
|
||||
│ 独立图片选择 │ │ （可能不包含所有选中图片的描述） │
|
||||
│ P1: BM25/向量 │ └──────────────────────────────────────┘
|
||||
│ P2: VLM 检查 │
|
||||
│ P3: CE 排名 │
|
||||
│ P4: 多样性去重 │
|
||||
└────────┬─────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ P0 安全网 — 保证 selected_images 描述完整进入 LLM 上下文│
|
||||
│ │
|
||||
│ 检查 context_text 中的 【相关图片信息】 部分， │
|
||||
│ 若 selected_images 的描述不在 context_text 中， │
|
||||
│ 强制追加缺失的描述。 │
|
||||
│ （解决两管线断裂：图片被选中但描述被 min_score 过滤掉） │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ _filter_images_by_answer() — 答案后过滤 │
|
||||
│ │
|
||||
│ LLM 生成答案后，根据答案内容过滤不相关图片。 │
|
||||
│ ⚠️ 鸡生蛋问题：若 LLM 因上下文缺失而回答"未找到"， │
|
||||
│ 会导致正确图片被误过滤。P0 安全网可缓解此问题。 │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**select_images 四阶段选择**：
|
||||
|
||||
| 阶段 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| P1 | BM25/向量召回 | 从检索结果中筛选 chunk_type 为 image/chart 的候选 |
|
||||
| P2 | VLM 相关性检查 | `_check_vlm_relevance()` 判断图片与查询的相关性，不相关者 -3.0 惩罚 |
|
||||
| P3 | CrossEncoder 排名 | CE<0 移除，CE 0~2 保留无加成，CE>2 加分 |
|
||||
| P4 | 多样性去重 | 同文档多图片按分数保留 TopN，避免单一文档图片垄断 |
|
||||
|
||||
**CrossEncoder 图片评分特征**：CrossEncoder 对图片/图表的打分系统性低于文本（0.002-0.08 vs 0.3-0.9），因此 `chart_contexts` 使用 `min_score * 0.5` 的降门槛策略。
|
||||
|
||||
**VLM 相关性检查**：`_check_vlm_relevance()` 使用 VLM 模型判断图片内容与查询的相关性，阈值 0.3，不相关图片会被施加 -3.0 的分数惩罚。
|
||||
|
||||
### 6.2 救援管线
|
||||
|
||||
当常规检索召回不足时，以下救援机制依次尝试补充结果：
|
||||
|
||||
| 救援类型 | 触发条件 | 策略 |
|
||||
|----------|----------|------|
|
||||
| BM25 散度救援 | 向量与 BM25 结果差异大 | 补充 BM25 独有但向量遗漏的高分结果 |
|
||||
| 词法匹配救援 | 专有名词/术语精确匹配 | 对查询中的关键术语做精确匹配补充 |
|
||||
| 章节聚类救援 | 同章节切片被部分召回 | 补充同章节内相邻切片（rerank 后、扩展前） |
|
||||
| 表格救援 | 表格数据被碎片化 | 对 table 类型切片做整表补充 |
|
||||
|
||||
---
|
||||
|
||||
## 七、API 调用方式
|
||||
@@ -530,14 +611,24 @@ curl http://localhost:5001/cache/stats \
|
||||
|
||||
```python
|
||||
# config.py
|
||||
DASHSCOPE_API_KEY = "your-api-key" # 通义千问 API
|
||||
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
DASHSCOPE_MODEL = "qwen3.6-flash" # 文本生成模型（主力 LLM）
|
||||
INTENT_MODEL = "qwen-turbo" # 意图分析模型（轻量快速）
|
||||
VLM_MODEL = "qwen-vl-plus" # 视觉语言模型（图片描述）
|
||||
RAG_CHAT_MODEL = "qwen3.6-flash" # RAG 对话模型
|
||||
DASHSCOPE_API_KEY = "your-api-key" # mimo API 密钥
|
||||
DASHSCOPE_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1"
|
||||
DASHSCOPE_MODEL = "mimo-v2.5" # 文本生成模型（主力 LLM）
|
||||
INTENT_MODEL = "mimo-v2.5" # 意图分析模型（轻量快速）
|
||||
VLM_MODEL = "mimo-v2.5" # 视觉语言模型（图片描述）
|
||||
RAG_CHAT_MODEL = "mimo-v2.5" # RAG 对话模型
|
||||
|
||||
# Embedding 模型（本地）
|
||||
EMBEDDING_MODEL_PATH = "models/bge-base-zh-v1.5"
|
||||
|
||||
# Reranker 模型
|
||||
RERANK_MODEL_PATH = "models/bge-reranker-base" # 本地备选
|
||||
RERANK_CLOUD_MODEL = "xop3qwen8breranker" # 云端（讯飞云）
|
||||
RERANK_CLOUD_BASE_URL = "https://maas-api.cn-huabei-1.xf-yun.com/v1/rerank"
|
||||
```
|
||||
|
||||
> **注意**：百炼 API（DashScope）额度用尽后，所有 LLM 调用已统一切换至 mimo API（xiaomimimo.com）。`get_intent_client()` 也使用 `DASHSCOPE_API_KEY` / `DASHSCOPE_BASE_URL`（即 mimo API），不再使用百炼 API。
|
||||
|
||||
### 8.2 检索参数
|
||||
|
||||
```python
|
||||
@@ -553,7 +644,7 @@ RECALL_MULTIPLIER = 3 # 候选池最小倍数
|
||||
# 重排序
|
||||
USE_RERANK = True # 启用重排序
|
||||
RERANK_BACKEND = "local" # "local"=本地模型, "cloud"=云端API, "fallback"=优先云端失败回退本地
|
||||
RERANK_CLOUD_MODEL = "qwen3-rerank"
|
||||
RERANK_CLOUD_MODEL = "xop3qwen8breranker"
|
||||
RERANK_CANDIDATES = 20 # 送入重排序的候选数
|
||||
RERANK_TOP_K = 15 # 重排序后保留数
|
||||
RERANK_USE_ONNX = True # ONNX 加速（仅本地模式，环境变量控制）
|
||||
@@ -701,10 +792,10 @@ config/ # 运行时配置
|
||||
| 检索方式 | 单一向量检索 | 向量 + BM25 + FAQ + 图片独立召回 |
|
||||
| 融合算法 | 无 | RRF 动态权重融合 |
|
||||
| 去重 | 无 | MMR 语义去重 |
|
||||
| 重排序 | 无 | 云端 qwen3-rerank API（支持本地 BGE 回退） |
|
||||
| 重排序 | 无 | 云端 xop3qwen8breranker API（讯飞云，支持本地 BGE 回退） |
|
||||
| 问题分解 | 无 | 自动拆分对比/推理类查询 |
|
||||
| 闲聊处理 | 无 | 意图分析自动判断 |
|
||||
| 缓存体系 | 无 | 四层缓存（Query + Embedding + Rerank + 语义缓存） |
|
||||
| 缓存体系 | 无 | 五层缓存（Query + Embedding + Rerank + 语义缓存 + 元数据缓存） |
|
||||
| 语义缓存 | 无 | FAISS 向量索引，相似查询复用（92x 加速） |
|
||||
| 自适应 TopK | 固定 top_k | 根据置信度动态调整 |
|
||||
| 上下文理解 | 无 | 多轮对话 + 历史上下文 |
|
||||
@@ -736,9 +827,9 @@ Rerank 在生产流程中有 **一个调用路径**：
|
||||
|--------|--------|------|
|
||||
| `USE_RERANK` | `True` | 总开关 |
|
||||
| `RERANK_BACKEND` | `"local"` | 后端选择 |
|
||||
| `RERANK_CLOUD_MODEL` | `"qwen3-rerank"` | 云端模型名称 |
|
||||
| `RERANK_CLOUD_MODEL` | `"xop3qwen8breranker"` | 云端模型名称 |
|
||||
| `RERANK_CLOUD_API_KEY` | 同 `DASHSCOPE_API_KEY` | 云端 API 密钥 |
|
||||
| `RERANK_CLOUD_BASE_URL` | `https://dashscope.aliyuncs.com/compatible-api/v1/reranks` | 云端 API 地址 |
|
||||
| `RERANK_CLOUD_BASE_URL` | `https://maas-api.cn-huabei-1.xf-yun.com/v1/rerank` | 云端 API 地址（讯飞云） |
|
||||
| `RERANK_CLOUD_TIMEOUT` | `15` | 云端请求超时（秒） |
|
||||
| `RERANK_MODEL_PATH` | `models/bge-reranker-base` | 本地模型路径 |
|
||||
| `RERANK_CANDIDATES` | `20` | 送入 Rerank 的候选数 |
|
||||
@@ -807,6 +898,26 @@ print({"hits": sc.hits, "misses": sc.misses, "total": sc.total_entries})
|
||||
|
||||
## 十三、演进记录
|
||||
|
||||
### v4.1（2026-06-21）— 模型切换 + 图片检索修复
|
||||
|
||||
**模型统一切换**：百炼 API（DashScope）额度用尽后，所有 LLM 调用统一切换至 mimo API（xiaomimimo.com）：
|
||||
- `DASHSCOPE_MODEL` / `RAG_CHAT_MODEL` / `INTENT_MODEL` / `VLM_MODEL`：`qwen3.6-flash` / `qwen-turbo` / `qwen-vl-plus` → `mimo-v2.5`
|
||||
- `DASHSCOPE_BASE_URL`：`dashscope.aliyuncs.com` → `token-plan-cn.xiaomimimo.com/v1`
|
||||
- `get_intent_client()`：从百炼 API 切换至 mimo API
|
||||
|
||||
**Reranker 切换**：
|
||||
- `RERANK_CLOUD_MODEL`：`qwen3-rerank` → `xop3qwen8breranker`（讯飞云）
|
||||
- `RERANK_CLOUD_BASE_URL`：`dashscope.aliyuncs.com` → `maas-api.cn-huabei-1.xf-yun.com/v1/rerank`
|
||||
|
||||
**图片检索修复**（P0 级）：
|
||||
1. **chart_contexts 降门槛**：CrossEncoder 对图片/图表打分系统性偏低（0.002-0.08 vs 文本 0.3-0.9），原 `min_score=0.05` 过滤掉几乎所有图表。修复为 `min_score * 0.5 = 0.025`。
|
||||
2. **P0 安全网**：`select_images` 独立于文本上下文管线选择图片，但图片描述可能因 min_score 过滤未进入 LLM 上下文。新增安全网检查：若 `selected_images` 的描述未出现在 `context_text` 中，强制注入。
|
||||
3. **答案后过滤**（`_filter_images_by_answer`）：LLM 生成答案后，根据答案内容过滤不相关图片。注意：若 LLM 因上下文缺失而回答"未找到"，会导致正确图片被误过滤（鸡生蛋问题）。
|
||||
|
||||
**救援管线**：新增 BM25 散度救援、词法匹配救援、章节聚类救援、表格救援等机制，确保低召回场景下的结果覆盖。
|
||||
|
||||
**缓存层扩展**：从四层缓存扩展为五层，新增 ChromaDB 元数据缓存（L5），避免频繁查询 ChromaDB 获取 kb_version 等元数据。
|
||||
|
||||
### v4.0（2026-06-05）— 统一编排 + 四层缓存修复
|
||||
|
||||
**删除未使用的备用编排路径**：移除了 `core/agentic.py` 及 8 个 Mixin 文件（共 10 个文件 ~2050 行）。这些文件实现了完整的决策循环编排（含置信度门控、质量评估、推理反思等），但从未接入任何 HTTP 路由。
|
||||
@@ -820,7 +931,7 @@ print({"hits": sc.hits, "misses": sc.misses, "total": sc.total_entries})
|
||||
|
||||
### v3.2 — 模型/Reranker/管线更新
|
||||
|
||||
引入云端 qwen3-rerank、ONNX 加速、动态 RRF 权重等。
|
||||
引入云端 Reranker（现 xop3qwen8breranker/讯飞云，原 qwen3-rerank/DashScope）、ONNX 加速、动态 RRF 权重等。
|
||||
|
||||
---
|
||||
|
||||
@@ -828,7 +939,7 @@ print({"hits": sc.hits, "misses": sc.misses, "total": sc.total_entries})
|
||||
|
||||
### Redis 缓存外部化
|
||||
|
||||
当前四层缓存均为进程内内存存储，在多 Worker / 多实例部署时无法共享。已规划 Redis 迁移方案（详见 `reports/redis_migration_plan.md`），核心设计：
|
||||
当前五层缓存均为进程内内存存储（L5 ChromaDB 元数据缓存除外），在多 Worker / 多实例部署时无法共享。已规划 Redis 迁移方案（详见 `reports/redis_migration_plan.md`），核心设计：
|
||||
|
||||
- `RedisCacheManager` 提供与 `RAGCacheManager` 相同的接口
|
||||
- 通过 `REDIS_CACHE_URL` 环境变量启用，向后兼容
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
>
|
||||
> 测试日期：2026-06-10（最近更新）| 生产服务器：`47.116.16.222` | 服务地址：`http://127.0.0.1:5001`
|
||||
>
|
||||
> 当前部署模型：`qwen-turbo`（DashScope）| 嵌入模型：`bge-base-zh-v1.5`（本地 CPU）| Rerank：`qwen3-rerank`（DashScope 云端 API）
|
||||
> 当前部署模型：`mimo-v2.5`（xiaomimimo.com API）| 嵌入模型：`bge-base-zh-v1.5`（本地 CPU）| Rerank：`xop3qwen8breranker`（讯飞云 API）
|
||||
|
||||
## 目录
|
||||
|
||||
@@ -2106,7 +2106,7 @@ curl -s -X POST "http://localhost:5001/collections/public_kb/reindex"
|
||||
|
||||
| 优化项 | 配置 | 效果 |
|
||||
|--------|------|------|
|
||||
| Reranker 云端化 | `RERANK_BACKEND=cloud`（qwen3-rerank） | 搜索阶段从 33-48s 降至 ~0.3s |
|
||||
| Reranker 云端化 | `RERANK_BACKEND=cloud`（xop3qwen8breranker/讯飞云） | 搜索阶段从 33-48s 降至 ~0.3s |
|
||||
| MMR 文本相似度 | `MMR_USE_EMBEDDING=false` | MMR 阶段从 ~36s 降至 ~0s |
|
||||
|
||||
### 耗时拆解（优化后 /rag 问答）
|
||||
@@ -2126,7 +2126,7 @@ curl -s -X POST "http://localhost:5001/collections/public_kb/reindex"
|
||||
└── 流式 token 生成 ~11s
|
||||
```
|
||||
|
||||
> **注**：LLM 生成阶段耗时取决于 qwen-turbo API 响应速度，非本地可优化。当前已使用 qwen-turbo（最快模型），如需进一步压缩可考虑减少检索切片数量或缩短 prompt。
|
||||
> **注**：LLM 生成阶段耗时取决于 mimo-v2.5 API 响应速度，非本地可优化。如需进一步压缩可考虑减少检索切片数量或缩短 prompt。
|
||||
|
||||
---
|
||||
|
||||
@@ -2174,14 +2174,14 @@ curl -s -X POST http://127.0.0.1:5001/collections/<kb_name>/reindex
|
||||
|
||||
### Reranker 配置
|
||||
|
||||
生产环境使用 DashScope 云端 Reranker 替代本地 CPU 推理，显著提升检索速度：
|
||||
生产环境使用讯飞云 Reranker 替代本地 CPU 推理，显著提升检索速度：
|
||||
|
||||
| 配置项 | 值 | 说明 |
|
||||
|--------|-----|------|
|
||||
| `RERANK_BACKEND` | `cloud` | 使用云端 API（可选 `local` / `cloud` / `fallback`） |
|
||||
| `RERANK_CLOUD_MODEL` | `qwen3-rerank` | DashScope 云端排序模型 |
|
||||
| `RERANK_CLOUD_API_KEY` | `sk-*` | DashScope 标准 API Key |
|
||||
| `RERANK_CLOUD_BASE_URL` | `https://dashscope.aliyuncs.com/compatible-api/v1/reranks` | OpenAI 兼容端点 |
|
||||
| `RERANK_CLOUD_MODEL` | `xop3qwen8breranker` | 讯飞云排序模型 |
|
||||
| `RERANK_CLOUD_API_KEY` | `sk-*` | API Key |
|
||||
| `RERANK_CLOUD_BASE_URL` | `https://maas-api.cn-huabei-1.xf-yun.com/v1/rerank` | 讯飞云 Rerank 端点 |
|
||||
| `MMR_USE_EMBEDDING` | `false` | MMR 使用文本相似度（零额外计算） |
|
||||
|
||||
> **fallback 模式**：`RERANK_BACKEND=fallback` 优先使用云端 API，如果云端不可用则自动回退到本地模型，适合生产环境高可用场景。
|
||||
|
||||
190
docs/出题系统测试报告.md
Normal file
190
docs/出题系统测试报告.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 出题系统测试报告
|
||||
|
||||
**测试日期**: 2026-06-22
|
||||
**测试环境**: mimo-v2.5（关闭推理模式）、2.docx（文明吸烟环境建设标准）
|
||||
**测试方式**: curl 接口测试 + 代码审查
|
||||
|
||||
---
|
||||
|
||||
## 一、测试总览
|
||||
|
||||
| # | 测试项 | 接口 | 结果 | 耗时 |
|
||||
|---|--------|------|------|------|
|
||||
| 1 | 参数出题 | POST /exam/generate | ✅ 成功 | ~87s (4题) |
|
||||
| 2 | AI一键出题 | POST /exam/generate-smart | ⚠️ 成功但有上限失控 | ~244s (50题) |
|
||||
| 3 | 偏门题型(纯主观) | POST /exam/generate | ✅ 成功 | ~87s (5题) |
|
||||
| 4 | 偏门题型(多选+填空) | POST /exam/generate | ✅ 成功 | ~60s (6题) |
|
||||
| 5 | 跨调用去重 | POST /exam/generate + exclude_stems | ✅ 去重有效 | ~60s (5题) |
|
||||
| 6 | 批题(4题型混合) | POST /exam/grade | ✅ 全部成功 | ~30s |
|
||||
|
||||
---
|
||||
|
||||
## 二、测试详情
|
||||
|
||||
### Test 1: 参数出题 (single_choice:2, fill_blank:1, true_false:1)
|
||||
- **结果**: 4题全部生成成功，题型匹配
|
||||
- **问题**:
|
||||
- ❌ 题目多样性不足：4题中3题考同一个知识点（"标准的解释机构"）
|
||||
- ❌ source_trace 数据缺失（chunk_id=?, page=?）
|
||||
|
||||
### Test 2: AI一键出题 (generate-smart)
|
||||
- **AI分析**: 检测到54个知识点，推荐50道题（20单选+15判断+10多选+5填空）
|
||||
- **结果**: 50题全部生成，12个不同章节，0题干重复
|
||||
- **问题**:
|
||||
- ❌ **P0 上限失控**: prompt 要求"不超过20"，但AI返回50，代码没有 enforce 上限校验
|
||||
- ⚠️ 50题意味着20-30次LLM调用，极易触发429限流
|
||||
|
||||
### Test 3: 纯主观题 (subjective:5)
|
||||
- **结果**: 5题全部生成，覆盖不同章节，scoring_points 完整
|
||||
- **耗时**: 87秒（关闭推理模式后正常）
|
||||
|
||||
### Test 4: 多选+填空 (multiple_choice:3, fill_blank:3)
|
||||
- **结果**: 6题全部生成
|
||||
- **问题**:
|
||||
- ❌ **填空题答案格式不一致**: `content.answer` 是 `[["消费水平较高"]]` (list of list)，但没有 `data.reference_answer` 字段，只有 `data.blank_count`
|
||||
- ⚠️ 与 grader 期望的格式可能不匹配
|
||||
|
||||
### Test 5: 跨调用去重 (exclude_stems)
|
||||
- **结果**: 3个排除题干全部未出现，去重有效 ✅
|
||||
|
||||
### Test 6: 批题 (grade)
|
||||
- **单选题答错**: score=0, correct=false ✅
|
||||
- **判断题答对**: score=2, correct=true ✅
|
||||
- **填空题部分对**: score=4.0 (满分4), blank_scores=[4.0] ✅
|
||||
- **主观题(低质量回答)**: score=2.0/10, 4个scoring_point逐项评分 ✅
|
||||
- **总评**: 得分率44.4%，评分合理
|
||||
|
||||
---
|
||||
|
||||
## 三、发现的问题（按严重度排序）
|
||||
|
||||
### P0 - 严重问题
|
||||
|
||||
#### 1. 🚨 AI一键出题上限失控 (generator.py:1053-1068)
|
||||
**位置**: `analyze_document_for_exam()` 函数
|
||||
**现象**: prompt 写了"所有数量之和不要超过 min(total_knowledge_points * 2, 20)"，但 LLM 返回50题，代码直接采纳
|
||||
**根因**: 代码只做了"题型合法性"校验，没有对总数做上限 enforce
|
||||
```python
|
||||
# 当前代码 (generator.py:1053-1059) - 只校验单题型合法性，无总数限制
|
||||
valid_types = ['single_choice', 'multiple_choice', 'true_false', 'fill_blank', 'subjective']
|
||||
question_types = {}
|
||||
for q_type in valid_types:
|
||||
count = result.get('question_types', {}).get(q_type, 0)
|
||||
if isinstance(count, int) and count >= 0:
|
||||
question_types[q_type] = count # 直接采纳，无上限
|
||||
```
|
||||
**建议**: 增加总数上限校验，超过 `max_questions`（建议20）时按比例缩减
|
||||
```python
|
||||
total = sum(question_types.values())
|
||||
max_questions = 20
|
||||
if total > max_questions:
|
||||
ratio = max_questions / total
|
||||
question_types = {k: max(0, round(v * ratio)) for k, v in question_types.items()}
|
||||
```
|
||||
|
||||
#### 2. 🚨 LLM 调用无限流机制，429 风暴 (generator.py:290-303, 540-543)
|
||||
**位置**: `generate_questions_structured()` 主循环 + `_generate_with_retry()` 重试
|
||||
**现象**: 并发出题时大量429错误，重试退避太短(1s/2s/4s)，3次全败后放弃该知识点
|
||||
**根因**:
|
||||
- 主循环 for 逐知识点调用 LLM，无请求间隔（补题函数有 sleep(1)，主循环没有）
|
||||
- 429 重试退避 `2^attempt` 秒 (1/2/4s) 对 API 限流不够
|
||||
- 无全局限流器（令牌桶/漏桶）
|
||||
**建议**:
|
||||
1. 主循环每次 LLM 调用后加 `time.sleep(1.5)` 最小间隔
|
||||
2. 429 退避改为指数+抖动: `min(30, 2 ** attempt + random.uniform(0, 2))`
|
||||
3. 长期: 引入 `tenacity` 或自实现令牌桶限流器
|
||||
|
||||
#### 3. 🚨 validate_questions_schema 只认 `type` 不认 `question_type` (generator.py:154)
|
||||
**位置**: `validate_questions_schema()` 函数
|
||||
**现象**: LLM 返回的题目可能用 `question_type` 字段，但校验只检查 `q.get('type')`，导致有效题目被丢弃
|
||||
**对比**: `_validate_question_types()` (第448行) 做了兼容: `q_type = q.get('question_type') or q.get('type')`
|
||||
```python
|
||||
# 当前代码 (generator.py:154) - 不兼容
|
||||
if q.get('type') not in VALID_TYPES:
|
||||
continue # question_type 字段的题目被丢弃！
|
||||
|
||||
# 应改为
|
||||
q_type = q.get('question_type') or q.get('type')
|
||||
if q_type not in VALID_TYPES:
|
||||
continue
|
||||
```
|
||||
|
||||
### P1 - 中等问题
|
||||
|
||||
#### 4. ⚠️ 填空题答案格式不一致
|
||||
**现象**: 出题返回 `content.answer = [["答案1"], ["答案2"]]` (list of list)，但无 `data.reference_answer`
|
||||
**影响**: 前端/本地数据库可能期望 `reference_answer` 字段
|
||||
**建议**: 统一在 `data` 中增加 `reference_answer` 字段，与 `content.answer` 保持一致
|
||||
|
||||
#### 5. ⚠️ grader max_tokens 对推理模型不足 (grader.py:438)
|
||||
**位置**: `_grade_subjective()` 方法
|
||||
**现象**: `max_tokens=_get_effective_max_tokens(1000, self.model)`
|
||||
- 推理模型关闭推理时: 1000 tokens 勉强够
|
||||
- 推理模型开启推理时: 思考链消耗 800+ tokens，content 为空
|
||||
**当前状态**: 关闭推理模式后本次测试通过，但**开启推理模式会再次失败**
|
||||
**建议**: 基础 max_tokens 从 1000 提升至 2000
|
||||
|
||||
#### 6. ⚠️ local_db._detect_question_type 使用旧格式 (local_db.py:378-383)
|
||||
**位置**: `_detect_question_type()` 方法
|
||||
**现象**: 检测 `options` 和 `reference_answer` 字段来判断题型，但新格式用 `content.data.options` 和 `content.answer`
|
||||
```python
|
||||
# 当前代码 - 检查顶层 options
|
||||
if 'options' in question and question['options']:
|
||||
return 'choice'
|
||||
elif 'reference_answer' in question:
|
||||
return 'short_answer'
|
||||
|
||||
# 应改为检查 content 内部结构
|
||||
content = question.get('content', {})
|
||||
data = content.get('data', {})
|
||||
if data.get('options'):
|
||||
return 'choice'
|
||||
elif question.get('question_type') in ('fill_blank', 'subjective', ...):
|
||||
return question['question_type']
|
||||
```
|
||||
|
||||
#### 7. ⚠️ 题目多样性不足
|
||||
**现象**: Test 1 中 4 题有 3 题考同一知识点（"标准的解释机构"）
|
||||
**根因**: `_assign_questions_to_kps()` 可能将多个题型分配给同一知识点
|
||||
**建议**: 增加"同一知识点最多出 N 道题"的限制（建议 N=2）
|
||||
|
||||
### P2 - 低优先级
|
||||
|
||||
#### 8. 💡 source_trace 数据偶尔缺失
|
||||
**现象**: Test 1 中部分题目的 chunk_id 和 page 显示为 `?`
|
||||
**可能原因**: `find_referenced_chunks` 匹配失败时的 fallback 显示
|
||||
|
||||
#### 9. 💡 多选题答案格式
|
||||
**现象**: 多选题 answer 为 `['A', 'B']` 或 `['A', 'B', 'D']` (list)，前端需处理
|
||||
**建议**: 在 API 文档中明确多选题 answer 格式为 list
|
||||
|
||||
#### 10. 💡 补题机制未与已有题目交叉去重
|
||||
**现象**: 补题时只检查本次生成的题干，不检查已有题目
|
||||
**建议**: 补题函数接受 `exclude_stems` 参数
|
||||
|
||||
---
|
||||
|
||||
## 四、测试通过项 ✅
|
||||
|
||||
1. **基础出题功能**: 5种题型均可正常生成
|
||||
2. **AI智能分析**: 文档分析→题型推荐→出题流程完整
|
||||
3. **补题机制**: 知识点出题失败后自动补题
|
||||
4. **跨调用去重**: exclude_stems 功能正常，排除的题干不再出现
|
||||
5. **批题功能**: 客观题精确匹配，填空题部分给分，主观题LLM逐项评分
|
||||
6. **source_trace**: 大部分题目有完整的溯源信息（chunk_id, section, snippet）
|
||||
7. **JSON解析**: mimo-v2.5 返回的 JSON 格式（含 markdown 包裹）可正常解析
|
||||
8. **题目格式**: 单选题 options 为 list of dict `[{key, content}]`，格式规范
|
||||
|
||||
---
|
||||
|
||||
## 五、建议修复优先级
|
||||
|
||||
| 优先级 | 问题 | 修复难度 | 影响范围 |
|
||||
|--------|------|----------|----------|
|
||||
| P0 | AI出题上限失控 | 简单 | smart 出题 |
|
||||
| P0 | LLM 429 限流 | 中等 | 全部出题 |
|
||||
| P0 | validate_questions_schema type 字段 | 简单 | 全部出题 |
|
||||
| P1 | 填空题答案格式统一 | 简单 | 填空题+批题 |
|
||||
| P1 | grader max_tokens | 简单 | 主观题批题 |
|
||||
| P1 | local_db 旧格式 | 中等 | 本地存储 |
|
||||
| P1 | 题目多样性控制 | 中等 | 出题质量 |
|
||||
@@ -138,19 +138,22 @@
|
||||
|
||||
#### 4a. 去重
|
||||
|
||||
`_deduplicate_questions(questions, exclude_stems)` — 三层去重：
|
||||
`_deduplicate_questions(questions, exclude_stems)` — 四层去重：
|
||||
|
||||
1. **题干前缀去重**：题干前 80 字相同 → 去掉。
|
||||
2. **知识点+题型去重**：题干前 30 字 + 题型相同 → 去掉。
|
||||
3. **跨调用去重**：`exclude_stems` 中已有题目的题干前 80 字预填入去重集合，新生成的题目如果与之冲突也会被过滤。
|
||||
2. **跨调用排除**（`_matches_exclude`）：`exclude_stems` 中已有题目的前缀（≤30 字），新题干前 30 字如果以此为前缀 → 去掉。用 `startswith()` 匹配，解决排除题干短于 30 字时的长度不匹配问题。
|
||||
3. **知识点+题型去重**：题干前 30 字 + 题型相同 → 去掉。
|
||||
4. **跨调用题干去重**：`exclude_stems` 中已有题目的题干前 80 字预填入去重集合，精确匹配过滤。
|
||||
|
||||
#### 4b. 题型平衡
|
||||
|
||||
`_balance_question_types(questions, target_types)` — 按题型分组，每种题型按目标数量截取（多了截断）。
|
||||
|
||||
#### 4c. 补题（仅 v1 结构化路径）
|
||||
#### 4c. 补题
|
||||
|
||||
v1 的 `generate_questions_structured()` 有补题机制 `_makeup_questions()`：如果某题型数量不足，用前 5 个 chunks 重新出一轮补充。v2 路径依赖分配阶段的精确控制，不额外补题。
|
||||
v1 的 `generate_questions_structured()` 有补题机制 `_makeup_questions()`：如果某题型数量不足，用前 5 个 chunks 重新出一轮补充。
|
||||
|
||||
v2 路径（`generate_questions_structured_v2`）同样支持补题：Phase 4.4 检查各题型是否达到目标数量，不足的题型调用 `_makeup_questions()` 补充，补题结果也经过去重处理。
|
||||
|
||||
---
|
||||
|
||||
@@ -272,7 +275,7 @@ v1 的 `generate_questions_structured()` 有补题机制 `_makeup_questions()`
|
||||
| `safe_parse_questions` | generator.py | JSON 安全解析 |
|
||||
| `validate_questions_schema` | generator.py | 题目 Schema 校验 |
|
||||
| `_enrich_with_source_trace` | generator.py | 补充溯源信息 |
|
||||
| `_deduplicate_questions` | generator.py | 三层去重 |
|
||||
| `_deduplicate_questions` | generator.py | 四层去重 |
|
||||
| `_balance_question_types` | generator.py | 题型数量平衡 |
|
||||
| `_generate_questions_fallback` | generator.py | 降级路径（无知识点时） |
|
||||
| `_makeup_questions` | generator.py | v1 补题机制 |
|
||||
|
||||
@@ -312,11 +312,11 @@ pip install -r requirements.txt
|
||||
```python
|
||||
# config.py - 必需配置
|
||||
|
||||
# 通义千问 API（必需）
|
||||
# LLM API（必需）
|
||||
DASHSCOPE_API_KEY = "your-api-key"
|
||||
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
DASHSCOPE_MODEL = "qwen-flash" # 文本模型
|
||||
DASHSCOPE_VL_MODEL = "qwen-vl-plus" # 视觉模型（图片描述）
|
||||
DASHSCOPE_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1"
|
||||
DASHSCOPE_MODEL = "mimo-v2.5" # 文本模型
|
||||
VLM_MODEL = "mimo-v2.5" # 视觉模型（图片描述）
|
||||
|
||||
# 兼容变量
|
||||
API_KEY = DASHSCOPE_API_KEY
|
||||
|
||||
@@ -84,9 +84,9 @@ ls models/bge-base-zh-v1.5/
|
||||
```python
|
||||
# API配置
|
||||
DASHSCOPE_API_KEY = "your-api-key"
|
||||
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
DASHSCOPE_MODEL = "qwen3.6-flash" # 主 LLM（文本生成 / RAG 对话）
|
||||
INTENT_MODEL = "qwen-turbo" # 意图分析模型（轻量、确定性高）
|
||||
DASHSCOPE_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1"
|
||||
DASHSCOPE_MODEL = "mimo-v2.5" # 主 LLM（文本生成 / RAG 对话）
|
||||
INTENT_MODEL = "mimo-v2.5" # 意图分析模型
|
||||
```
|
||||
|
||||
> **注意**: Graph RAG（Neo4j）功能已废弃，相关配置（NEO4J_URI、USE_GRAPH_RAG 等）已移除。
|
||||
|
||||
@@ -246,6 +246,7 @@ def api_generate_smart():
|
||||
"file_path": "public/产品手册.pdf",
|
||||
"collection": "public_kb",
|
||||
"difficulty": 3, // 可选，默认 3
|
||||
"max_total": 20, // 可选，AI出题总数上限。不传则不限制
|
||||
"options": {} // 可选
|
||||
}
|
||||
|
||||
@@ -267,6 +268,16 @@ def api_generate_smart():
|
||||
if diff_error:
|
||||
return error_response("INVALID_PARAMS", BAD_REQUEST, diff_error, http_status=400)
|
||||
|
||||
# 可选：AI出题总数上限（不传则不限制）
|
||||
max_total = data.get('max_total')
|
||||
if max_total is not None:
|
||||
try:
|
||||
max_total = int(max_total)
|
||||
if max_total <= 0:
|
||||
return error_response("INVALID_PARAMS", BAD_REQUEST, "max_total 必须为正整数", http_status=400)
|
||||
except (ValueError, TypeError):
|
||||
return error_response("INVALID_PARAMS", BAD_REQUEST, "max_total 必须为整数", http_status=400)
|
||||
|
||||
# 校验排除题干列表（可选）
|
||||
exclude_stems = data.get('exclude_stems')
|
||||
stems_error = validate_exclude_stems(exclude_stems)
|
||||
@@ -298,11 +309,11 @@ def api_generate_smart():
|
||||
f"AI智能出题: {os.path.basename(file_path)}"
|
||||
)
|
||||
|
||||
def _do_smart_generate(task, fp, coll, diff, opts, req_id, excl):
|
||||
def _do_smart_generate(task, fp, coll, diff, opts, req_id, excl, max_t):
|
||||
"""后台执行 AI 智能出题"""
|
||||
registry.update_progress(task.id, stage='AI分析', message='正在分析文档内容...')
|
||||
from exam_pkg.manager import analyze_file_for_exam
|
||||
ai_analysis = analyze_file_for_exam(file_path=fp, collection=coll)
|
||||
ai_analysis = analyze_file_for_exam(file_path=fp, collection=coll, max_total=max_t)
|
||||
|
||||
q_types = ai_analysis.get('question_types', {})
|
||||
if not q_types or sum(q_types.values()) == 0:
|
||||
@@ -325,7 +336,8 @@ def api_generate_smart():
|
||||
task.id, _do_smart_generate,
|
||||
file_path, collection,
|
||||
data.get('difficulty', 3), data.get('options', {}),
|
||||
data.get('request_id'), data.get('exclude_stems')
|
||||
data.get('request_id'), data.get('exclude_stems'),
|
||||
max_total
|
||||
)
|
||||
|
||||
return success_response(
|
||||
|
||||
@@ -26,19 +26,38 @@ import logging
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# 导入 LLM 工具函数
|
||||
from core.llm_utils import call_llm, parse_json_list_from_response
|
||||
from core.llm_utils import call_llm, parse_json_list_from_response, extract_json_list, extract_json_object
|
||||
|
||||
# 导入 LLM 配置
|
||||
try:
|
||||
from config import API_KEY, BASE_URL, MODEL
|
||||
from config import API_KEY, BASE_URL, MODEL, LLM_TEMPERATURE, LLM_MAX_TOKENS
|
||||
LLM_AVAILABLE = True
|
||||
except ImportError:
|
||||
API_KEY = None
|
||||
BASE_URL = None
|
||||
MODEL = None
|
||||
LLM_TEMPERATURE = 0.7
|
||||
LLM_MAX_TOKENS = 4000
|
||||
LLM_AVAILABLE = False
|
||||
|
||||
|
||||
# 推理模型识别：这些模型会消耗额外 token 用于思考链，需要更大的 max_tokens 预算
|
||||
_REASONING_MODEL_KEYWORDS = ('mimo', 'qwq', 'deepseek-r1', 'deepseek-reasoner', 'o1', 'o3')
|
||||
|
||||
def _is_reasoning_model(model_name: str) -> bool:
|
||||
"""判断是否为推理模型（需要额外思考链 token 预算）"""
|
||||
if not model_name:
|
||||
return False
|
||||
name_lower = model_name.lower()
|
||||
return any(kw in name_lower for kw in _REASONING_MODEL_KEYWORDS)
|
||||
|
||||
def _get_effective_max_tokens(base_max: int, model_name: str) -> int:
|
||||
"""根据模型类型计算实际 max_tokens。推理模型需要 1.5x 预算给思考链"""
|
||||
if _is_reasoning_model(model_name):
|
||||
return max(base_max, int(base_max * 1.5))
|
||||
return base_max
|
||||
|
||||
|
||||
# ==================== 辅助函数 ====================
|
||||
|
||||
def group_chunks_by_section(chunks: List[Dict]) -> Dict[str, List[Dict]]:
|
||||
@@ -131,8 +150,9 @@ def validate_questions_schema(questions: List[Dict]) -> List[Dict]:
|
||||
validated = []
|
||||
|
||||
for q in questions:
|
||||
# 必须有 type
|
||||
if q.get('type') not in VALID_TYPES:
|
||||
# 必须有 type 或 question_type
|
||||
q_type = q.get('question_type') or q.get('type')
|
||||
if q_type not in VALID_TYPES:
|
||||
continue
|
||||
|
||||
# 必须有 content
|
||||
@@ -145,7 +165,7 @@ def validate_questions_schema(questions: List[Dict]) -> List[Dict]:
|
||||
continue
|
||||
|
||||
# 选项题必须有 options
|
||||
if q['type'] in ['single_choice', 'multiple_choice']:
|
||||
if q_type in ['single_choice', 'multiple_choice']:
|
||||
if not content.get('data', {}).get('options'):
|
||||
continue
|
||||
|
||||
@@ -359,8 +379,8 @@ class QuestionGenerator:
|
||||
client=self.client,
|
||||
prompt=prompt,
|
||||
model=self.model,
|
||||
temperature=0.7,
|
||||
max_tokens=4000,
|
||||
temperature=LLM_TEMPERATURE,
|
||||
max_tokens=_get_effective_max_tokens(4000, self.model),
|
||||
messages=messages
|
||||
)
|
||||
if not content:
|
||||
@@ -493,25 +513,37 @@ class QuestionGenerator:
|
||||
return type_names.get(q_type, q_type)
|
||||
|
||||
def _call_llm(self, prompt: str) -> str:
|
||||
"""调用本地 LLM（OpenAI 兼容接口）"""
|
||||
"""调用本地 LLM（OpenAI 兼容接口），支持 429 限流重试"""
|
||||
if not self.client:
|
||||
raise ValueError("LLM 客户端未初始化，请检查 config.py 中的 API_KEY 配置")
|
||||
|
||||
import time
|
||||
|
||||
messages = [
|
||||
{"role": "system", "content": "你是一个专业的出题专家，擅长根据文档内容生成各类考试题目。你必须严格按照JSON格式输出，不要有任何其他内容。"},
|
||||
{"role": "user", "content": prompt}
|
||||
]
|
||||
result = call_llm(
|
||||
client=self.client,
|
||||
prompt=prompt,
|
||||
model=self.model,
|
||||
temperature=0.7,
|
||||
max_tokens=4000,
|
||||
messages=messages
|
||||
)
|
||||
if result is None:
|
||||
raise Exception("LLM 调用失败")
|
||||
return result
|
||||
|
||||
# 重试机制：429 限流时指数退避（最多重试 3 次）
|
||||
for attempt in range(4):
|
||||
result = call_llm(
|
||||
client=self.client,
|
||||
prompt=prompt,
|
||||
model=self.model,
|
||||
temperature=LLM_TEMPERATURE,
|
||||
max_tokens=_get_effective_max_tokens(4000, self.model),
|
||||
messages=messages
|
||||
)
|
||||
if result is not None:
|
||||
return result
|
||||
|
||||
# 可能是 429 限流，等待后重试
|
||||
if attempt < 3:
|
||||
wait_time = 2 ** attempt # 1s, 2s, 4s
|
||||
logger.warning(f" LLM 调用失败，{wait_time}s 后重试 ({attempt+1}/3)...")
|
||||
time.sleep(wait_time)
|
||||
|
||||
raise Exception("LLM 调用失败（已重试 3 次）")
|
||||
|
||||
def _get_format_examples(self) -> str:
|
||||
"""返回各题型格式示例（覆盖全部 5 种题型）"""
|
||||
@@ -610,7 +642,6 @@ class QuestionGenerator:
|
||||
)
|
||||
|
||||
# 清理纯标点符号
|
||||
import re
|
||||
all_content = re.sub(r'^[\s\*\-\d\.。、，：:；;]+$', '', all_content, flags=re.MULTILINE)
|
||||
all_content = all_content.strip()
|
||||
|
||||
@@ -645,27 +676,24 @@ class QuestionGenerator:
|
||||
|
||||
请直接输出 JSON 数组："""
|
||||
|
||||
try:
|
||||
response = self._call_llm(prompt)
|
||||
for _attempt in range(2):
|
||||
try:
|
||||
response = self._call_llm(prompt)
|
||||
if not response or not response.strip():
|
||||
continue
|
||||
|
||||
# 清理响应（移除可能的 markdown 标记）
|
||||
response = response.strip()
|
||||
if response.startswith('```'):
|
||||
lines = response.split('\n')
|
||||
response = '\n'.join(lines[1:-1] if lines[-1] == '```' else lines[1:])
|
||||
|
||||
# 解析 JSON
|
||||
result = json.loads(response)
|
||||
if isinstance(result, list):
|
||||
return [
|
||||
{"name": kp, "section": section}
|
||||
for kp in result[:max_points]
|
||||
if isinstance(kp, str) and 3 <= len(kp) <= 30
|
||||
]
|
||||
except json.JSONDecodeError as e:
|
||||
logger.error(f" 知识点 JSON 解析失败: {e}")
|
||||
except Exception as e:
|
||||
logger.error(f" 知识点提取失败: {e}")
|
||||
# 使用多策略 JSON 提取（支持 markdown 代码块、正则回退）
|
||||
result = extract_json_list(response)
|
||||
if isinstance(result, list) and result:
|
||||
return [
|
||||
{"name": kp, "section": section}
|
||||
for kp in result[:max_points]
|
||||
if isinstance(kp, str) and 3 <= len(kp) <= 30
|
||||
]
|
||||
# 解析结果无效，重试一次
|
||||
logger.warning(f" 知识点提取返回无效结果(尝试 {_attempt+1}/2)，重试中...")
|
||||
except Exception as e:
|
||||
logger.error(f" 知识点提取失败(尝试 {_attempt+1}/2): {e}")
|
||||
|
||||
return []
|
||||
|
||||
@@ -918,7 +946,7 @@ def generate_questions_from_content(
|
||||
return generator.generate_questions_structured(chunks, document_name, question_types, difficulty)
|
||||
|
||||
|
||||
def analyze_document_for_exam(chunks: List[Dict]) -> Dict[str, Any]:
|
||||
def analyze_document_for_exam(chunks: List[Dict], max_total: int = None) -> Dict[str, Any]:
|
||||
"""
|
||||
AI 智能分析文档内容，决定适合的题型和数量
|
||||
|
||||
@@ -1026,14 +1054,14 @@ def analyze_document_for_exam(chunks: List[Dict]) -> Dict[str, Any]:
|
||||
|
||||
try:
|
||||
response = generator._call_llm(prompt)
|
||||
response = response.strip()
|
||||
if not response or not response.strip():
|
||||
return _generate_default_question_types(total_knowledge_points)
|
||||
|
||||
# 清理 markdown 代码块
|
||||
if response.startswith('```'):
|
||||
lines = response.split('\n')
|
||||
response = '\n'.join(lines[1:-1] if lines[-1] == '```' else lines[1:])
|
||||
|
||||
result = json.loads(response)
|
||||
# 使用多策略 JSON 提取（支持 markdown 代码块、正则回退）
|
||||
result = extract_json_object(response)
|
||||
if not isinstance(result, dict):
|
||||
logger.error(f"AI 分析返回非对象类型: {type(result)}")
|
||||
return _generate_default_question_types(total_knowledge_points)
|
||||
|
||||
# 验证和清理结果
|
||||
valid_types = ['single_choice', 'multiple_choice', 'true_false', 'fill_blank', 'subjective']
|
||||
@@ -1046,6 +1074,24 @@ def analyze_document_for_exam(chunks: List[Dict]) -> Dict[str, Any]:
|
||||
# 过滤不适合的题型
|
||||
suitable_types = [t for t, c in question_types.items() if c > 0]
|
||||
|
||||
# 总数上限校验：如果指定了 max_total，超过时按比例缩减
|
||||
if max_total and max_total > 0:
|
||||
total = sum(question_types.values())
|
||||
if total > max_total:
|
||||
ratio = max_total / total
|
||||
question_types = {k: max(0, round(v * ratio)) for k, v in question_types.items()}
|
||||
# 修正四舍五入误差
|
||||
diff = max_total - sum(question_types.values())
|
||||
if diff > 0:
|
||||
# 把差额分配给最大的题型
|
||||
for k in sorted(question_types, key=question_types.get, reverse=True):
|
||||
question_types[k] += 1
|
||||
diff -= 1
|
||||
if diff <= 0:
|
||||
break
|
||||
logger.info(f" AI 推荐 {total} 题，按上限 {max_total} 缩减为 {sum(question_types.values())} 题")
|
||||
suitable_types = [t for t, c in question_types.items() if c > 0]
|
||||
|
||||
return {
|
||||
"total_knowledge_points": result.get('total_knowledge_points', total_knowledge_points),
|
||||
"suitable_types": suitable_types,
|
||||
@@ -1053,10 +1099,6 @@ def analyze_document_for_exam(chunks: List[Dict]) -> Dict[str, Any]:
|
||||
"reason": result.get('reason', 'AI 分析完成')
|
||||
}
|
||||
|
||||
except json.JSONDecodeError as e:
|
||||
logger.error(f"AI 分析结果 JSON 解析失败: {e}")
|
||||
# 降级：根据知识点数量生成默认配置
|
||||
return _generate_default_question_types(total_knowledge_points)
|
||||
except Exception as e:
|
||||
logger.error(f"AI 分析失败: {e}")
|
||||
return _generate_default_question_types(total_knowledge_points)
|
||||
@@ -1156,6 +1198,10 @@ def generate_questions_structured_v2(
|
||||
# 提取知识点
|
||||
kps = generator._extract_knowledge_points(section, section_chunks, max_points=3)
|
||||
|
||||
# API 限流保护：连续 LLM 调用间隔 1 秒
|
||||
import time
|
||||
time.sleep(1)
|
||||
|
||||
# 全局去重
|
||||
for kp in kps:
|
||||
kp_name = kp['name']
|
||||
@@ -1219,6 +1265,10 @@ def generate_questions_structured_v2(
|
||||
prompt, {q_type: 1}, kp_chunks, document_name, max_retries=2
|
||||
)
|
||||
|
||||
# API 限流保护：连续 LLM 调用间隔 1 秒
|
||||
import time
|
||||
time.sleep(1)
|
||||
|
||||
if success and questions:
|
||||
all_questions.extend(questions)
|
||||
else:
|
||||
@@ -1241,6 +1291,28 @@ def generate_questions_structured_v2(
|
||||
type_counts[q.get('question_type')] += 1
|
||||
logger.info(f" 题型分布: {dict(type_counts)}")
|
||||
|
||||
# 4.4 补题：如果某题型数量不足，使用 chunks 补充
|
||||
shortage_types = {}
|
||||
for q_type, target_count in question_types.items():
|
||||
actual_count = type_counts.get(q_type, 0)
|
||||
if actual_count < target_count:
|
||||
shortage_types[q_type] = target_count - actual_count
|
||||
|
||||
if shortage_types:
|
||||
logger.info(f" [v2] 补题: 缺少题型 {dict(shortage_types)}")
|
||||
for q_type, shortage in shortage_types.items():
|
||||
logger.info(f" 补充 {q_type} {shortage} 道...")
|
||||
extra = generator._makeup_questions(chunks, q_type, shortage, difficulty, document_name)
|
||||
# 补题也需去重
|
||||
extra_deduped = _deduplicate_questions(extra, exclude_stems=exclude_stems)
|
||||
final.extend(extra_deduped[:shortage])
|
||||
|
||||
# 补题后重新统计
|
||||
type_counts = defaultdict(int)
|
||||
for q in final:
|
||||
type_counts[q.get('question_type')] += 1
|
||||
logger.info(f" 补题后题型分布: {dict(type_counts)}")
|
||||
|
||||
return final
|
||||
|
||||
|
||||
@@ -1404,9 +1476,27 @@ def _deduplicate_questions(questions: List[Dict], exclude_stems: List[str] = Non
|
||||
|
||||
# 预填已有题目的题干前缀，使新生成的题目与已有题目冲突时被过滤
|
||||
if exclude_stems:
|
||||
_valid_types = ('single_choice', 'multiple_choice', 'true_false', 'fill_blank', 'subjective')
|
||||
for stem in exclude_stems:
|
||||
seen_stems.add(stem[:80])
|
||||
seen_kp_type.add(f"{stem[:30]}_") # 通配题型匹配
|
||||
# 用 exclude_stem 自身长度做前缀键（排除题干通常短于30字）
|
||||
# 新题目的 stem[:30] 如果以此前缀开头，[:len(prefix)] 后就能匹配
|
||||
_prefix = stem[:30]
|
||||
for _qt in _valid_types:
|
||||
seen_kp_type.add(f"{_prefix}_{_qt}")
|
||||
|
||||
# 辅助函数：检查新题干是否匹配任何 exclude 前缀
|
||||
_exclude_prefixes = []
|
||||
if exclude_stems:
|
||||
_exclude_prefixes = [s[:30] for s in exclude_stems]
|
||||
|
||||
def _matches_exclude(stem_text: str) -> bool:
|
||||
"""检查题干前30字是否以某个 exclude 前缀开头"""
|
||||
_stem30 = stem_text[:30]
|
||||
for _ep in _exclude_prefixes:
|
||||
if _stem30.startswith(_ep):
|
||||
return True
|
||||
return False
|
||||
|
||||
deduped = []
|
||||
|
||||
@@ -1419,6 +1509,10 @@ def _deduplicate_questions(questions: List[Dict], exclude_stems: List[str] = Non
|
||||
if stem_key in seen_stems:
|
||||
continue
|
||||
|
||||
# 跨调用排除：题干前缀匹配到 exclude_stems 则跳过
|
||||
if _matches_exclude(stem):
|
||||
continue
|
||||
|
||||
# 知识点 + 题型去重
|
||||
kp_type_key = f"{stem[:30]}_{q.get('question_type')}"
|
||||
if kp_type_key in seen_kp_type:
|
||||
|
||||
@@ -37,6 +37,21 @@ except ImportError:
|
||||
MODEL = None
|
||||
LLM_AVAILABLE = False
|
||||
|
||||
# 推理模型识别（与 generator.py 共享同一套关键词）
|
||||
_REASONING_MODEL_KEYWORDS = ('mimo', 'qwq', 'deepseek-r1', 'deepseek-reasoner', 'o1', 'o3')
|
||||
|
||||
def _is_reasoning_model(model_name: str) -> bool:
|
||||
if not model_name:
|
||||
return False
|
||||
name_lower = model_name.lower()
|
||||
return any(kw in name_lower for kw in _REASONING_MODEL_KEYWORDS)
|
||||
|
||||
def _get_effective_max_tokens(base_max: int, model_name: str) -> int:
|
||||
"""推理模型需要 1.5x token 预算给思考链"""
|
||||
if _is_reasoning_model(model_name):
|
||||
return max(base_max, int(base_max * 1.5))
|
||||
return base_max
|
||||
|
||||
|
||||
# ==================== 装饰器 ====================
|
||||
|
||||
@@ -169,19 +184,56 @@ def grade_fill_blank(answer: Dict) -> Dict:
|
||||
|
||||
def fuzzy_match(student_answer: str, correct_answer: str) -> bool:
|
||||
"""
|
||||
模糊匹配（支持同义词）
|
||||
模糊匹配（支持同义词和小编辑距离容错）
|
||||
|
||||
当前实现：精确匹配（忽略前后空格、大小写）
|
||||
TODO: 可以扩展为语义相似度匹配
|
||||
策略：
|
||||
1. 精确匹配（去空格、转小写、统一标点）
|
||||
2. 编辑距离容错（≥4字答案允许≤2字符差异）
|
||||
"""
|
||||
if not student_answer or not correct_answer:
|
||||
return False
|
||||
|
||||
# 标准化：去空格、转小写
|
||||
s = student_answer.strip().lower()
|
||||
c = correct_answer.strip().lower()
|
||||
# 标准化：去空格、转小写、统一标点
|
||||
def _normalize(text: str) -> str:
|
||||
t = text.strip().lower()
|
||||
# 统一常见中文标点变体
|
||||
t = t.replace('（', '(').replace('）', ')').replace('，', ',')
|
||||
t = t.replace('；', ';').replace('：', ':').replace('"', '"').replace('"', '"')
|
||||
return t
|
||||
|
||||
return s == c
|
||||
s = _normalize(student_answer)
|
||||
c = _normalize(correct_answer)
|
||||
|
||||
if s == c:
|
||||
return True
|
||||
|
||||
# 编辑距离容错：答案≥4字时允许≤2字符差异
|
||||
if len(s) >= 4 and len(c) >= 4:
|
||||
dist = _edit_distance(s, c)
|
||||
if dist <= 2:
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
|
||||
def _edit_distance(s1: str, s2: str) -> int:
|
||||
"""计算两个字符串的编辑距离（Levenshtein）"""
|
||||
if len(s1) < len(s2):
|
||||
return _edit_distance(s2, s1)
|
||||
if len(s2) == 0:
|
||||
return len(s1)
|
||||
|
||||
prev_row = list(range(len(s2) + 1))
|
||||
for i, c1 in enumerate(s1):
|
||||
curr_row = [i + 1]
|
||||
for j, c2 in enumerate(s2):
|
||||
# 插入、删除、替换
|
||||
insertions = prev_row[j + 1] + 1
|
||||
deletions = curr_row[j] + 1
|
||||
substitutions = prev_row[j] + (c1 != c2)
|
||||
curr_row.append(min(insertions, deletions, substitutions))
|
||||
prev_row = curr_row
|
||||
return prev_row[-1]
|
||||
|
||||
|
||||
# ==================== AnswerGrader 类 ====================
|
||||
@@ -237,7 +289,21 @@ class AnswerGrader:
|
||||
|
||||
# 🔥 P1 改进：并发调用 LLM 批阅主观题
|
||||
if llm_questions:
|
||||
self._grade_subjective_concurrently(llm_questions, results_map)
|
||||
try:
|
||||
self._grade_subjective_concurrently(llm_questions, results_map)
|
||||
except Exception as e:
|
||||
logger.error(f"主观题并发批阅整体异常: {e}")
|
||||
# 兜底：为所有未完成的主观题设置失败状态
|
||||
for ans in llm_questions:
|
||||
qid = ans.get('question_id')
|
||||
if qid not in results_map:
|
||||
results_map[qid] = {
|
||||
"question_id": qid,
|
||||
"score": 0,
|
||||
"max_score": ans.get('max_score', 10),
|
||||
"grading_status": "failed",
|
||||
"details": {"error": f"批阅系统异常: {str(e)}"}
|
||||
}
|
||||
|
||||
# 🔥 P1 改进：按原始顺序重组结果
|
||||
results = [results_map.get(ans.get('question_id')) for ans in answers]
|
||||
@@ -369,7 +435,7 @@ class AnswerGrader:
|
||||
prompt=prompt,
|
||||
model=self.model,
|
||||
temperature=0.3,
|
||||
max_tokens=1000,
|
||||
max_tokens=_get_effective_max_tokens(2000, self.model),
|
||||
messages=messages
|
||||
)
|
||||
if result is None:
|
||||
|
||||
@@ -154,7 +154,8 @@ def generate_questions_from_file(
|
||||
def analyze_file_for_exam(
|
||||
file_path: str,
|
||||
collection: str,
|
||||
top_k: int = 50
|
||||
top_k: int = 50,
|
||||
max_total: int = None
|
||||
) -> Dict[str, Any]:
|
||||
"""
|
||||
分析文件内容，返回 AI 推荐的题型和数量
|
||||
@@ -193,7 +194,7 @@ def analyze_file_for_exam(
|
||||
}
|
||||
|
||||
# 2. 调用 AI 分析
|
||||
return analyze_document_for_exam(chunks)
|
||||
return analyze_document_for_exam(chunks, max_total=max_total)
|
||||
|
||||
|
||||
def retrieve_file_chunks_for_analysis(
|
||||
@@ -311,6 +312,7 @@ def retrieve_file_chunks(
|
||||
engine = get_engine()
|
||||
|
||||
# 按优先级遍历 collections，找到文件即停止
|
||||
results = None
|
||||
for coll in collections:
|
||||
# 尝试两种格式：文件名和完整路径
|
||||
for source_filter in [filename, file_path]:
|
||||
@@ -330,7 +332,7 @@ def retrieve_file_chunks(
|
||||
break # 外层循环跳出
|
||||
|
||||
chunks = []
|
||||
if results.get('documents') and results['documents'][0]:
|
||||
if results and results.get('documents') and results['documents'][0]:
|
||||
for i, (doc, meta, score) in enumerate(zip(
|
||||
results['documents'][0],
|
||||
results['metadatas'][0],
|
||||
|
||||
@@ -331,6 +331,21 @@ class CollectionMixin:
|
||||
except Exception as e:
|
||||
logger.warning(f"清理版本记录失败: {e}")
|
||||
|
||||
# 清理不再被引用的图片和 VLM 缓存文件
|
||||
# 注意：此时 ChromaDB collection 已删除，cleanup_image_orphans 会扫描
|
||||
# 所有剩余 collection，仅该 collection 引用的图片会被识别为孤儿
|
||||
try:
|
||||
from knowledge.image_cleanup import cleanup_image_orphans
|
||||
cleanup_result = cleanup_image_orphans(self)
|
||||
if cleanup_result['deleted_images'] or cleanup_result['deleted_caches']:
|
||||
logger.info(
|
||||
f"清理孤儿文件: {cleanup_result['deleted_images']} 图片 + "
|
||||
f"{cleanup_result['deleted_caches']} VLM缓存, "
|
||||
f"释放 {cleanup_result['freed_bytes']/1024:.1f} KB"
|
||||
)
|
||||
except Exception as e:
|
||||
logger.warning(f"清理孤儿文件失败: {e}")
|
||||
|
||||
if kb_name in self._metadata.get("collections", {}):
|
||||
del self._metadata["collections"][kb_name]
|
||||
self._save_metadata()
|
||||
|
||||
@@ -72,6 +72,18 @@ class DocumentMixin:
|
||||
except Exception as e:
|
||||
logger.warning(f"清理版本记录失败: {e}")
|
||||
|
||||
# 清理不再被引用的图片和 VLM 缓存文件
|
||||
try:
|
||||
from knowledge.image_cleanup import cleanup_image_orphans
|
||||
cleanup_result = cleanup_image_orphans(self, collections=[kb_name])
|
||||
if cleanup_result['deleted_images'] or cleanup_result['deleted_caches']:
|
||||
logger.info(
|
||||
f"清理孤儿文件: {cleanup_result['deleted_images']} 图片 + "
|
||||
f"{cleanup_result['deleted_caches']} VLM缓存"
|
||||
)
|
||||
except Exception as e:
|
||||
logger.warning(f"清理孤儿文件失败: {e}")
|
||||
|
||||
logger.info(f"从 {kb_name} 删除文档: {filename}, 片段数: {deleted}")
|
||||
return deleted
|
||||
|
||||
|
||||
@@ -25,7 +25,20 @@ def compute_file_hash(file_path: str) -> str:
|
||||
return hashlib.md5(file_path.encode()).hexdigest()
|
||||
|
||||
|
||||
async def lazy_vlm_description(chunk_id: str, image_path: str, kb_name: str, metadata: dict = None) -> str:
|
||||
def _get_embedding_model():
|
||||
"""从 RAGEngine 获取 embedding 模型（KnowledgeBaseManager 上没有此属性）"""
|
||||
try:
|
||||
from core.engine import get_engine
|
||||
engine = get_engine()
|
||||
if not engine._initialized:
|
||||
engine.initialize()
|
||||
return engine.embedding_model
|
||||
except Exception as e:
|
||||
logger.warning(f"获取 embedding 模型失败: {e}")
|
||||
return None
|
||||
|
||||
|
||||
async def lazy_vlm_description(chunk_id: str, image_path: str, kb_name: str, metadata: dict = None, defer_chromadb: bool = False) -> str:
|
||||
"""
|
||||
懒加载 VLM 描述
|
||||
|
||||
@@ -36,6 +49,7 @@ async def lazy_vlm_description(chunk_id: str, image_path: str, kb_name: str, met
|
||||
image_path: 图片路径（相对路径或绝对路径）
|
||||
kb_name: 知识库名称
|
||||
metadata: 图片元数据（包含 section、page、caption、上下文等）
|
||||
defer_chromadb: 为 True 时跳过 ChromaDB 更新（仅写文件缓存），避免后台线程写锁竞争
|
||||
|
||||
Returns:
|
||||
VLM 生成的图片描述
|
||||
@@ -49,23 +63,45 @@ async def lazy_vlm_description(chunk_id: str, image_path: str, kb_name: str, met
|
||||
else:
|
||||
full_image_path = image_path
|
||||
|
||||
# 1. 检查缓存
|
||||
# 1. 检查缓存（空缓存视为无效，需重新生成）
|
||||
img_hash = compute_file_hash(full_image_path)
|
||||
cache_file = VLM_CACHE_DIR / f"{img_hash}.txt"
|
||||
if cache_file.exists():
|
||||
logger.info(f"VLM 缓存命中: {image_path}")
|
||||
return cache_file.read_text(encoding='utf-8')
|
||||
cached = cache_file.read_text(encoding='utf-8')
|
||||
if len(cached.strip()) >= 5:
|
||||
logger.info(f"VLM 缓存命中: {image_path}")
|
||||
return cached
|
||||
else:
|
||||
logger.warning(f"VLM 缓存内容过短({len(cached.strip())}字符)，删除并重新生成: {image_path}")
|
||||
try:
|
||||
cache_file.unlink()
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
# 2. 调用 VLM（传入元数据）
|
||||
logger.info(f"VLM 懒加载: {image_path}")
|
||||
kb_manager = get_kb_manager()
|
||||
description = kb_manager._generate_image_description(full_image_path, metadata=metadata)
|
||||
|
||||
# 3. 写入缓存
|
||||
# 3. 空描述保护：VLM 返回内容过短时不写入缓存和向量库
|
||||
if not description or len(description.strip()) < 5:
|
||||
logger.warning(f"VLM 返回描述过短({len(description.strip()) if description else 0}字符)，跳过缓存和向量库更新: {image_path}")
|
||||
return description or ''
|
||||
|
||||
# 4. 写入缓存
|
||||
VLM_CACHE_DIR.mkdir(parents=True, exist_ok=True)
|
||||
cache_file.write_text(description, encoding='utf-8')
|
||||
|
||||
# 4. 更新向量库（metadata + embedding）
|
||||
# 5. 更新向量库（metadata + embedding），需校验 chunk_id 非空
|
||||
# defer_chromadb=True 时跳过（后台线程只写缓存，避免 SQLite 写锁竞争）
|
||||
if defer_chromadb:
|
||||
logger.info(f"延迟 ChromaDB 更新(仅写缓存): {chunk_id}")
|
||||
return description
|
||||
|
||||
if not chunk_id:
|
||||
logger.warning("chunk_id 为空，跳过向量库更新")
|
||||
return description
|
||||
|
||||
try:
|
||||
collection = kb_manager.get_collection(kb_name)
|
||||
result = collection.get(ids=[chunk_id], include=['metadatas'])
|
||||
@@ -79,7 +115,7 @@ async def lazy_vlm_description(chunk_id: str, image_path: str, kb_name: str, met
|
||||
|
||||
# 更新 embedding（使用 VLM 描述重新计算向量）
|
||||
# 这样 VLM 描述中的关键词（如"发电量"）才能参与相似度检索
|
||||
embedding_model = kb_manager.embedding_model
|
||||
embedding_model = _get_embedding_model()
|
||||
if embedding_model:
|
||||
new_vector = embedding_model.encode(description).tolist()
|
||||
if isinstance(new_vector[0], list):
|
||||
@@ -91,20 +127,21 @@ async def lazy_vlm_description(chunk_id: str, image_path: str, kb_name: str, met
|
||||
embeddings=[new_vector],
|
||||
documents=[description] # 同时更新 document 字段
|
||||
)
|
||||
logger.info(f"已更新向量库 embedding: {chunk_id}")
|
||||
logger.info(f"已更新向量库(embedding+metadata): {chunk_id}")
|
||||
else:
|
||||
# 无 embedding 模型时只更新 metadata
|
||||
collection.update(
|
||||
ids=[chunk_id],
|
||||
metadatas=[new_metadata]
|
||||
)
|
||||
logger.info(f"已更新向量库(仅metadata,无embedding模型): {chunk_id}")
|
||||
except Exception as e:
|
||||
logger.warning(f"更新向量库失败: {e}")
|
||||
|
||||
return description
|
||||
|
||||
|
||||
async def lazy_table_summary(chunk_id: str, table_md: str, kb_name: str) -> str:
|
||||
async def lazy_table_summary(chunk_id: str, table_md: str, kb_name: str, defer_chromadb: bool = False) -> str:
|
||||
"""
|
||||
懒加载表格摘要
|
||||
|
||||
@@ -114,50 +151,76 @@ async def lazy_table_summary(chunk_id: str, table_md: str, kb_name: str) -> str:
|
||||
chunk_id: 切片 ID
|
||||
table_md: 表格 Markdown 内容
|
||||
kb_name: 知识库名称
|
||||
defer_chromadb: 为 True 时跳过 ChromaDB 更新（仅写文件缓存），避免后台线程写锁竞争
|
||||
|
||||
Returns:
|
||||
LLM 生成的表格摘要
|
||||
"""
|
||||
from knowledge.manager import get_kb_manager
|
||||
|
||||
# 1. 检查缓存
|
||||
# 1. 检查缓存（空缓存视为无效）
|
||||
table_hash = hashlib.md5(table_md.encode()).hexdigest()
|
||||
cache_file = LLM_CACHE_DIR / f"{table_hash}.txt"
|
||||
if cache_file.exists():
|
||||
logger.info(f"LLM 缓存命中: {chunk_id}")
|
||||
return cache_file.read_text(encoding='utf-8')
|
||||
cached = cache_file.read_text(encoding='utf-8')
|
||||
if len(cached.strip()) >= 5:
|
||||
logger.info(f"LLM 缓存命中: {chunk_id}")
|
||||
return cached
|
||||
else:
|
||||
logger.warning(f"LLM 缓存内容过短({len(cached.strip())}字符)，删除并重新生成: {chunk_id}")
|
||||
try:
|
||||
cache_file.unlink()
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
# 2. 调用 LLM
|
||||
logger.info(f"LLM 懒加载: {chunk_id}")
|
||||
kb_manager = get_kb_manager()
|
||||
summary = kb_manager._generate_table_summary(table_md, None)
|
||||
|
||||
# 空摘要保护
|
||||
if not summary or len(summary.strip()) < 5:
|
||||
logger.warning(f"LLM 返回摘要过短，跳过缓存和向量库更新: {chunk_id}")
|
||||
return summary or ''
|
||||
|
||||
# 3. 写入缓存
|
||||
LLM_CACHE_DIR.mkdir(parents=True, exist_ok=True)
|
||||
cache_file.write_text(summary, encoding='utf-8')
|
||||
|
||||
# 4. 更新向量库（可选）
|
||||
# 4. 更新向量库，需校验 chunk_id 非空
|
||||
# defer_chromadb=True 时跳过（后台线程只写缓存，避免 SQLite 写锁竞争）
|
||||
if defer_chromadb:
|
||||
logger.info(f"延迟 ChromaDB 更新(仅写缓存): {chunk_id}")
|
||||
return summary
|
||||
|
||||
if not chunk_id:
|
||||
logger.warning("chunk_id 为空，跳过表格向量库更新")
|
||||
return summary
|
||||
try:
|
||||
collection = kb_manager.get_collection(kb_name)
|
||||
result = collection.get(ids=[chunk_id], include=['metadatas'])
|
||||
if result['metadatas']:
|
||||
# 新增摘要切片
|
||||
embedding_model = kb_manager.embedding_model
|
||||
vector = embedding_model.encode(summary).tolist()
|
||||
if isinstance(vector[0], list):
|
||||
vector = vector[0]
|
||||
# 新增摘要切片（需要 embedding 模型）
|
||||
embedding_model = _get_embedding_model()
|
||||
if embedding_model:
|
||||
vector = embedding_model.encode(summary).tolist()
|
||||
if isinstance(vector[0], list):
|
||||
vector = vector[0]
|
||||
|
||||
collection.add(
|
||||
ids=[f"{chunk_id}_summary"],
|
||||
embeddings=[vector],
|
||||
documents=[summary],
|
||||
metadatas=[{
|
||||
**result['metadatas'][0],
|
||||
'is_summary': True,
|
||||
'original_doc_id': chunk_id
|
||||
}]
|
||||
)
|
||||
# 更新原切片标记
|
||||
collection.add(
|
||||
ids=[f"{chunk_id}_summary"],
|
||||
embeddings=[vector],
|
||||
documents=[summary],
|
||||
metadatas=[{
|
||||
**result['metadatas'][0],
|
||||
'is_summary': True,
|
||||
'original_doc_id': chunk_id
|
||||
}]
|
||||
)
|
||||
logger.info(f"已新增摘要切片(embedding): {chunk_id}_summary")
|
||||
else:
|
||||
logger.info(f"跳过摘要切片(无embedding模型): {chunk_id}")
|
||||
# 更新原切片标记（不依赖 embedding 模型）
|
||||
collection.update(
|
||||
ids=[chunk_id],
|
||||
metadatas=[{**result['metadatas'][0], 'has_summary': True}]
|
||||
@@ -168,7 +231,7 @@ async def lazy_table_summary(chunk_id: str, table_md: str, kb_name: str) -> str:
|
||||
return summary
|
||||
|
||||
|
||||
async def enhance_retrieved_chunks(contexts: list, query: str, kb_name: str):
|
||||
async def enhance_retrieved_chunks(contexts: list, query: str, kb_name: str, defer_chromadb: bool = False):
|
||||
"""
|
||||
检索后增强：按需调用 LLM/VLM
|
||||
|
||||
@@ -176,23 +239,24 @@ async def enhance_retrieved_chunks(contexts: list, query: str, kb_name: str):
|
||||
contexts: 检索上下文列表
|
||||
query: 用户查询
|
||||
kb_name: 知识库名称
|
||||
defer_chromadb: 为 True 时后台线程只写文件缓存，不更新 ChromaDB（避免写锁竞争）
|
||||
"""
|
||||
for ctx in contexts:
|
||||
meta = ctx.get('meta', {})
|
||||
chunk_type = meta.get('chunk_type', 'text')
|
||||
image_path = meta.get('image_path', '')
|
||||
import re
|
||||
|
||||
# 图片切片：懒加载 VLM 描述
|
||||
if chunk_type in ('image', 'chart') and not meta.get('has_vlm_desc'):
|
||||
if image_path:
|
||||
try:
|
||||
for ctx in contexts:
|
||||
try:
|
||||
meta = ctx.get('meta', {})
|
||||
chunk_type = meta.get('chunk_type', 'text')
|
||||
image_path = meta.get('image_path', '')
|
||||
|
||||
# 图片切片：懒加载 VLM 描述
|
||||
if chunk_type in ('image', 'chart') and not meta.get('has_vlm_desc'):
|
||||
if image_path:
|
||||
# 从 doc 字段中提取图号（上下文可能包含"见图2.5"等）
|
||||
doc_text = ctx.get('doc', '')
|
||||
import re
|
||||
|
||||
# 提取图号（从前文/后文中）
|
||||
figure_number = ""
|
||||
# 匹配 "见图2.5"、"图2.5"、"见图 2.5" 等
|
||||
fig_match = re.search(r'[见如]?图\s*(\d+\.?\d*)', doc_text)
|
||||
if fig_match:
|
||||
figure_number = fig_match.group(1)
|
||||
@@ -210,78 +274,73 @@ async def enhance_retrieved_chunks(contexts: list, query: str, kb_name: str):
|
||||
'page': meta.get('page'),
|
||||
'caption': meta.get('caption', ''),
|
||||
'source': meta.get('source', ''),
|
||||
'figure_number': figure_number, # 添加提取的图号
|
||||
'doc_text': doc_text # 添加完整文档文本
|
||||
'figure_number': figure_number,
|
||||
'doc_text': doc_text
|
||||
}
|
||||
vlm_desc = await lazy_vlm_description(
|
||||
meta.get('id', ''),
|
||||
meta.get('chunk_id', ''),
|
||||
image_path,
|
||||
kb_name,
|
||||
metadata=image_metadata
|
||||
metadata=image_metadata,
|
||||
defer_chromadb=defer_chromadb
|
||||
)
|
||||
ctx['doc'] = vlm_desc
|
||||
ctx['vlm_enhanced'] = True
|
||||
except Exception as e:
|
||||
logger.warning(f"VLM 懒加载失败: {e}")
|
||||
if vlm_desc:
|
||||
ctx['doc'] = vlm_desc
|
||||
ctx['vlm_enhanced'] = True
|
||||
|
||||
# 表格切片：同时处理摘要和关联图片的 VLM 描述
|
||||
elif chunk_type == 'table':
|
||||
doc_text = ctx.get('doc', '')
|
||||
# 表格切片：同时处理摘要和关联图片的 VLM 描述
|
||||
elif chunk_type == 'table':
|
||||
doc_text = ctx.get('doc', '')
|
||||
|
||||
# 1. 懒加载表格摘要（高分切片）
|
||||
if not meta.get('has_summary'):
|
||||
score = meta.get('score', 0)
|
||||
if score > 0.7: # 只对高相关表格生成摘要
|
||||
try:
|
||||
# 1. 懒加载表格摘要（高分切片）
|
||||
if not meta.get('has_summary'):
|
||||
score = ctx.get('score', 0)
|
||||
if score > 0.7:
|
||||
summary = await lazy_table_summary(
|
||||
meta.get('id', ''),
|
||||
meta.get('chunk_id', ''),
|
||||
doc_text,
|
||||
kb_name
|
||||
kb_name,
|
||||
defer_chromadb=defer_chromadb
|
||||
)
|
||||
# 摘要作为补充信息
|
||||
ctx['summary'] = summary
|
||||
ctx['llm_enhanced'] = True
|
||||
except Exception as e:
|
||||
logger.warning(f"表格摘要懒加载失败: {e}")
|
||||
|
||||
# 2. 表格有关联图片时，懒加载 VLM 描述
|
||||
if image_path and not meta.get('has_vlm_desc'):
|
||||
try:
|
||||
import re
|
||||
if summary:
|
||||
ctx['summary'] = summary
|
||||
ctx['llm_enhanced'] = True
|
||||
|
||||
# 2. 表格有关联图片时，懒加载 VLM 描述
|
||||
if image_path and not meta.get('has_vlm_desc'):
|
||||
# 提取表号（如 "表2.2"、"见表2.1"）
|
||||
table_number = ""
|
||||
# 匹配 "表2.2"、"见表2.2"、"见表 2.2" 等
|
||||
table_match = re.search(r'[见如]?表\s*(\d+\.?\d*)', doc_text)
|
||||
if table_match:
|
||||
table_number = table_match.group(1)
|
||||
|
||||
# 如果 doc 中没有，尝试从 section 中提取
|
||||
section = meta.get('section') or meta.get('section_path', '')
|
||||
if not table_number and section:
|
||||
table_match = re.search(r'[见如]?表\s*(\d+\.?\d*)', section)
|
||||
if table_match:
|
||||
table_number = table_match.group(1)
|
||||
|
||||
# 构建表格图片元数据
|
||||
table_image_metadata = {
|
||||
'section': section,
|
||||
'page': meta.get('page'),
|
||||
'caption': meta.get('caption', ''),
|
||||
'source': meta.get('source', ''),
|
||||
'table_number': table_number, # 表号
|
||||
'figure_number': table_number, # 兼容字段
|
||||
'table_number': table_number,
|
||||
'figure_number': table_number,
|
||||
'doc_text': doc_text,
|
||||
'is_table': True # 标记为表格图片
|
||||
'is_table': True
|
||||
}
|
||||
vlm_desc = await lazy_vlm_description(
|
||||
meta.get('id', ''),
|
||||
meta.get('chunk_id', ''),
|
||||
image_path,
|
||||
kb_name,
|
||||
metadata=table_image_metadata
|
||||
metadata=table_image_metadata,
|
||||
defer_chromadb=defer_chromadb
|
||||
)
|
||||
# 表格图片描述作为补充信息
|
||||
ctx['image_description'] = vlm_desc
|
||||
ctx['vlm_enhanced'] = True
|
||||
except Exception as e:
|
||||
logger.warning(f"表格图片 VLM 懒加载失败: {e}")
|
||||
if vlm_desc:
|
||||
ctx['image_description'] = vlm_desc
|
||||
ctx['vlm_enhanced'] = True
|
||||
|
||||
except Exception as e:
|
||||
chunk_id = ctx.get('meta', {}).get('chunk_id', '?')
|
||||
logger.warning(f"增强切片失败(chunk_id={chunk_id}): {e}")
|
||||
|
||||
@@ -39,6 +39,7 @@ from pathlib import Path
|
||||
import logging
|
||||
|
||||
import chromadb
|
||||
from bs4 import BeautifulSoup
|
||||
|
||||
# 从 base.py 导入基础类和常量
|
||||
from .base import (
|
||||
@@ -550,8 +551,39 @@ class KnowledgeBaseManager(
|
||||
curr_html = getattr(current, 'table_html', '') or ''
|
||||
next_html = getattr(next_chunk, 'table_html', '') or ''
|
||||
if curr_html and next_html:
|
||||
# 合并两个表格的 HTML
|
||||
current.table_html = curr_html + '\n' + next_html
|
||||
# 正确合并两个表格的 HTML：
|
||||
# 将第二个表格的 <tr> 行追加到第一个表格中
|
||||
# （而非简单拼接两个 <table>，否则 html_table_to_markdown
|
||||
# 的 soup.find('table') 只能找到第一个表格）
|
||||
try:
|
||||
soup1 = BeautifulSoup(curr_html, 'html.parser')
|
||||
soup2 = BeautifulSoup(next_html, 'html.parser')
|
||||
table1 = soup1.find('table')
|
||||
table2 = soup2.find('table')
|
||||
if table1 and table2:
|
||||
# 从第二个表格提取数据行
|
||||
next_rows = table2.find_all('tr')
|
||||
# 跳过与第一个表格表头重复的行
|
||||
# 对比第一行而非所有 th（find_all('th') 会匹配
|
||||
# 整个表格的 th，无法与单行做列表比较）
|
||||
first_row_t1 = table1.find('tr')
|
||||
if first_row_t1 and next_rows:
|
||||
row1_texts = [c.get_text(strip=True) for c in first_row_t1.find_all(['th', 'td'])]
|
||||
row2_texts = [c.get_text(strip=True) for c in next_rows[0].find_all(['th', 'td'])]
|
||||
if row1_texts and row2_texts and row1_texts == row2_texts:
|
||||
next_rows = next_rows[1:]
|
||||
logger.debug("跨页表格合并: 跳过了重复的表头行")
|
||||
for row in next_rows:
|
||||
table1.append(row)
|
||||
current.table_html = str(soup1)
|
||||
logger.debug(f"跨页表格 HTML 合并成功: 追加了 {len(next_rows)} 行")
|
||||
else:
|
||||
current.table_html = curr_html + '\n' + next_html
|
||||
except Exception as e:
|
||||
logger.warning(f"跨页表格 HTML 合并异常: {e}，回退到简单拼接")
|
||||
current.table_html = curr_html + '\n' + next_html
|
||||
elif not curr_html and next_html:
|
||||
current.table_html = next_html
|
||||
|
||||
# 合并 image_path 和嵌入图片到 images
|
||||
curr_img = getattr(current, 'image_path', None)
|
||||
@@ -622,7 +654,7 @@ class KnowledgeBaseManager(
|
||||
try:
|
||||
from config import get_llm_client, DASHSCOPE_MODEL
|
||||
client = get_llm_client()
|
||||
summary = call_llm(client, prompt, DASHSCOPE_MODEL, max_tokens=512)
|
||||
summary = call_llm(client, prompt, DASHSCOPE_MODEL, max_tokens=2048)
|
||||
return summary.strip() if summary else ""
|
||||
except Exception as e:
|
||||
logger.warning(f"生成表格摘要失败: {e}")
|
||||
@@ -681,13 +713,31 @@ class KnowledgeBaseManager(
|
||||
]
|
||||
}
|
||||
],
|
||||
max_tokens=512
|
||||
max_tokens=2048 # mimo-v2.5 推理模型思考链消耗 ~1000 token，需留足输出空间
|
||||
)
|
||||
|
||||
description = response.choices[0].message.content
|
||||
|
||||
# 推理模型兼容：content 为空时从 reasoning_content 提取
|
||||
if not description or not description.strip():
|
||||
reasoning = getattr(response.choices[0].message, 'reasoning_content', None)
|
||||
if reasoning and reasoning.strip():
|
||||
import re
|
||||
# 尝试从思考链中提取有用文本（去掉 <think> 标签后的内容）
|
||||
cleaned = re.sub(r'', '', reasoning, flags=re.DOTALL).strip()
|
||||
if cleaned:
|
||||
logger.info(f"VLM content为空，从reasoning_content提取描述: {image_path}")
|
||||
description = cleaned
|
||||
else:
|
||||
description = reasoning.strip()
|
||||
|
||||
if not description:
|
||||
logger.warning(f"VLM 返回空描述: {image_path}")
|
||||
return ""
|
||||
|
||||
# 缓存结果
|
||||
import hashlib
|
||||
import re as _re
|
||||
img_hash = hashlib.md5(img_path.read_bytes()).hexdigest()
|
||||
cache_dir = Path('.data/cache/vlm')
|
||||
cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
Reference in New Issue
Block a user