RAG 检索链路

RAG 检索链路当前以 knowledge_chunks 为知识主表。生产运行使用 hybrid pipeline：先理解查询，再从知识主表召回候选，随后按场景过滤、rerank、证据裁剪、上下文压缩，最后把结构化上下文交给 LLM。

运行路径

用户问题query

安全前置SafetyFilter

查询理解intent / topics

知识召回knowledge_chunks

↴

重排过滤rerank / scene rules

证据与上下文evidence / context

模型生成LLM response

模块职责

模块	职责
query_understanding.py	按关键词与轻量 token 规则识别 intent 和 topic。
knowledge_chunk_search.py	调 DashScope embedding，查询 knowledge_chunks.embedding 的 cosine distance。
persistence_topology.py	定义 canonical 表、legacy 表、HNSW index 名和 rag_schema 过滤条件。
field_adapter.py	把 DB 记录转换为 RagChunk / RagTable 策略层结构。
scene_rules.py	对术后、前康复、居家等场景做候选过滤。
reranker.py	DashScope rerank 封装，带开关、超时、熔断和 similarity fallback。
evidence_policy.py	按 intent 选择主 chunk、主 table 和 supporting evidence。
context_formatter.py	把证据压缩成 LLM 可读的紧凑上下文，限制总长度和单块长度。
response_generation.py	构造系统提示词、用户消息、患者画像摘要，并调用 LLM。
retrieval_orchestration.py	串联 hybrid 主链并记录各阶段 timing。

知识召回

KnowledgeChunkSearchService.search_knowledge_chunks(...) 的检索步骤：

步骤	行为
Pipeline 解析	读取 RAG_PIPELINE_VERSION；非法值自动回退 legacy。
Schema 过滤	legacy 匹配空 meta_data.rag_schema；hybrid 匹配 RAG_HYBRID_SCHEMA_TAG。
Embedding	使用 DashScope TextEmbedding.Models.text_embedding_v1 为用户 query 生成向量。
pgvector 查询	按 KnowledgeChunk.embedding.cosine_distance(query_vector) 排序。
用户上下文过滤	如果有 cancer_type 或 stage，追加 JSON metadata 条件。
相似度阈值	similarity = 1 - distance，低于 threshold 的候选被丢弃。
返回字段	id、title、content、source、meta、similarity。

生产 hybrid 主链会把召回池扩大到 max(top_k, RAG_RETRIEVAL_CANDIDATES)；当前生产 RAG_RETRIEVAL_CANDIDATES=20。

排序与模型

阶段	当前实现	排序或裁剪规则
Query embedding	DashScope text-embedding-v1	为用户 query 生成向量，失败时返回检索错误。
初始召回	PostgreSQL pgvector cosine distance	按距离升序查询，换算为 similarity = 1 - distance。
Schema scope	RAG_PIPELINE_VERSION + RAG_HYBRID_SCHEMA_TAG	生产 hybrid 只取 meta_data.rag_schema = v1 的知识。
场景过滤	scene_rules.py	根据术后、前康复、居家等场景限制候选。
Rerank	DashScope gte-rerank-v2	生产启用；超时、异常、熔断时按 similarity 降序。
Evidence policy	apply_evidence_template(...)	按 intent 选择主 chunk、主 table 和 supporting evidence。
Context formatting	format_compact_context(...)	控制总长度和单证据块长度，只把精选证据交给 LLM。

证据结构

Hybrid 链路把知识记录分成两类：

类型	结构	典型用途
RagChunk	chunk_id、content、section_path、topic_type、use_when、source_filename、score	概念解释、风险提示、场景原则、正文段落证据。
RagTable	table_id、title、summary、rows_preview、notes、score	FITT-VP 参数、频率强度、场景化表格建议。

EvidenceResult 会输出主证据与辅助证据。不同 intent 的裁剪策略不同：概念问答偏向定义类 chunk，参数问答偏向运动处方表，禁忌风险问答优先安全、风险、监测和注意事项相关证据。

Rerank 与降级

情况	行为
RAG_ENABLE_RERANK=false	不调用 DashScope rerank，按 similarity 降序。
query 为空	跳过 rerank，按 similarity 降序。
rerank timeout	记录 warning，按 similarity 降级排序。
rerank exception	记录 warning，按 similarity 降级排序。
连续失败达到阈值	熔断器 open，冷却期内不再调用 rerank API。
冷却结束	进入 half-open，下一次成功后恢复 closed。

当前生产启用 rerank，模型为 gte-rerank-v2，单次 timeout 为 1.0 秒。

输出契约

safe_search_and_generate(...) 返回给 Chat 主链的核心字段：

字段	含义
intelligent_response	最终可展示的 AI 回复文本。
knowledge_context	传给 LLM 的压缩证据上下文；无证据时为空。
sources	证据来源，最多向上游返回前几个。
confidence	基于 rerank score 或 similarity score 的置信度估计。
information_source	基于专业知识库 或 基于一般常识。
knowledge_correlation	原始候选最高 similarity。
model_info.fallback	LLM 或知识不足时的 fallback 标记。
timing	hybrid 各阶段耗时。
hybrid_debug	intent、scene、topics、candidate_count。

Chat use case 不直接展示完整 knowledge_context，而是将 sources 截断后作为 rag_context 写入响应与对话日志。

失败路径

失败点	处理
安全过滤命中高风险并有建议文本	跳过检索，直接返回 suggested_response。
Embedding API 未配置或失败	返回检索错误；hybrid 失败时外层可回退 legacy。
DB 查询失败	返回 Database query failed，不返回业务行内容。
hybrid 主链异常	RAGEngine.safe_search_and_generate 自动回退 legacy 流程。
hybrid 召回为空	调用一般常识 fallback，不伪装成专业知识库引用。
LLM 生成失败但已有知识上下文	optimize_knowledge_response(...) 从上下文中整理简短建议。

验证入口

测试	覆盖点
tests/rag/test_retrieval_orchestration.py	hybrid 主链有证据和无结果两条路径。
tests/rag/test_reranker.py	rerank 成功、timeout fallback、熔断恢复和关闭开关。
tests/rag/test_evidence_policy.py	不同 intent 的证据裁剪策略。
tests/rag/test_context_formatter.py	compact context 格式化和截断。
tests/test_rag_hybrid_contract.py	Chat contract、hybrid error fallback、安全短路。
tests/test_rag_schema_filter_phase35_contract.py	legacy / hybrid 的 rag_schema 过滤条件。

来源锚点

• Search: apps/backend_service/app/core/rag/knowledge_chunk_search.py
• Orchestration: apps/backend_service/app/core/rag/retrieval_orchestration.py
• Evidence: apps/backend_service/app/core/rag/evidence_policy.py
• Context: apps/backend_service/app/core/rag/context_formatter.py
• Rerank: apps/backend_service/app/core/rag/reranker.py
• Topology: apps/backend_service/app/core/rag/persistence_topology.py
• Model: apps/backend_service/app/models/rag_knowledge.py
• DB reference: docs_site/database/knowledge-rag-tables.md