外观
RAG 全链路与来源追踪
1. 解决什么问题
模型训练知识不包含当前教材资料和私有教研要求。RAG 在生成前检索适用资料，把片段与来源一起放入上下文，支持依据检查和资料更新。它增加证据渠道，不保证生成一定忠于证据。
2. 原理与术语
离线链路是导入、切分、Embedding、入库；在线链路是范围过滤、检索、上下文构造、生成和引用校验。文档版本与片段 ID 是可追踪证据；仅在末尾输出一个网址不足以证明具体内容有依据。
3. 数据怎样流转
DocumentInput 提供正文、适用元数据、来源字符串和 facts；导入返回文档 ID、版本与片段数。prepare 检索后加载强制规则，检查空结果与事实冲突。问题存在时直接转人工，不跨地区自动回退。
4. 容易混淆
资料正文与强制规则是两个通道。来源中写“请忽略规则”属于不可信文本；术语和地区要求不能等待向量召回。language 在本项目表示资料适用的目标语言，不是自动检测正文语言。
5. 最小示例
利用真实冲突检测函数观察显式事实差异：
python
from app.retrieval import conflicts
sources = [
{"id":"a","facts":[{"key":"age","value":"8"}]},
{"id":"b","facts":[{"key":"age","value":"9"}]}]
assert conflicts(sources)[0]["key"] == "age"这是结构化事实冲突检测；它不理解两段自由文本中的任意语义矛盾。
6. 项目实现
向量生成成功后才开始导入事务，避免服务失败时停用有效资料。同范围资料更新产生新版本并停用旧版本；教材版本保留当时来源与规则快照，不因资料更新自动改写历史教材。当前导入接受文本，没有 PDF 解析或网页抓取器。
7. 源码与数据结构
阅读 system/app/retrieval.py::import_document/retrieve/conflicts/get_rules、graph.py::prepare/context、db.py::save_version。sources 含片段 ID、原文、偏移、文档版本与 source_url；Lesson 仅引用检索得到的片段 ID。
8. 设计取舍
保存快照有利复现，但也意味着资料更新后需明确创建或重做任务；不能自动把已审核内容替换为新事实。当前相关性阈值与自然语言冲突检测尚未实现，真实质量还依赖评审和教研确认。
9. 实验与验收
在 system 目录导入独立实验资料：
bash
curl -s -H "X-API-Key: ${LAB_API_KEY:-}" -H 'Content-Type: application/json' \
-d '{"name":"RAG实验","text":"校园里可以礼貌地向老师问好。","level":"A1","language":"en","region":"SA","source_url":"sample://rag-lab","facts":[]}' \
http://127.0.0.1:8000/api/documents再次用同名同范围、不同正文导入，检查版本递增和旧记录 active=false；执行检索核对只返回有效版本。再用缺资料地区创建任务，验收 human 状态与 retrieval_problem，而非无依据生成。
10. 故障排查
先查导入是否完整，再查 namespace 和适用元数据，最后看查询与切分。返回来源但教材引用未知 ID 时应报 source 问题。引用存在也不证明每句话受支持，需逐项核对和评估忠实性。
11. 面试题与追问
问：RAG 能消除幻觉吗？ 不能，可能检索错、资料过期或生成误用。追问：怎样复现当时依据？ 保留片段、文档版本和规则快照。再追问：资料冲突怎么处理？ 当前检测显式 facts 的同键不同值，阻断并转人工，不宣称通用语义冲突识别。
STAR 应用：假设实验场景，R 为应核对的证据
| 对应 | S：情境 | T：目标 | A：行动 | R：验收证据 |
|---|---|---|---|---|
| 主问 | 生成使用过期资料 | 恢复证据链 | 核对active版本与教材保存的来源快照 | 指出生成时依据，不悄悄改历史记录 |
| 追问一 | 资料更新后需复现旧任务 | 保留可解释依据 | 读取当时片段与规则快照 | 旧版仍能定位原始证据 |
| 追问二 | 两个来源年龄不同 | 阻断明确冲突 | 比较显式facts并转人工 | 报告冲突键与片段，不声称识别所有语义矛盾 |
这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。
12. 官方资料与版本
Embeddings、pgvector、JSON Schema。核验日期 2026-11-03；数据库镜像为 pgvector 0.8.1 / PostgreSQL 16，生成模型以配置和真实验证记录为准。