RAG 的起点不是向量数据库，而是一个能说明“答案来自哪里”的检索问答任务。把文件切块、嵌入并存起来，只完成了中间部分。本篇用虚构的社区自行车维修手册库，串起概念理解、最小知识库和检索优化。示例只用于软件学习；真实维修涉及的专业判断和安全事项仍应交由合格人员，不由问答系统代替。
场景一：先理解索引与问答两条链路
索引链路把有权使用的文档解析为文本，清理后分块，保留标题、版本、页码与权限等元数据，再生成检索所需索引。问答链路读取用户问题，在用户允许范围内找候选证据，排序与组装上下文，再让模型生成有引用的回答。RAG 通常不等于重新训练模型；文档更新需要更新索引与缓存，而不是期待模型自动记住新内容。
对维修手册库，用户问“折叠车的保养周期在哪里说明”，系统应返回相应型号与版本的来源位置。相似但不同型号的段落不能只因语义接近就混用。问题不在资料内时应明确没有依据，必要时给检索方向，而不是用模型常识补成手册规定。引用存在也不代表支持结论，必须核对引用的内容与适用范围。
先做十份左右已许可的脱敏文档和一组能人工检查的问题，涵盖明确条目、同义问法、型号编号、过期政策、资料缺失和无权访问。给每个问题指定相关来源与可接受结论。这个集合用于发现链路问题，不是完整生产验收；无需等到百万级数据才考虑权限、删除和版本要求。
场景二：搭建最小可核对知识库
建立文档清单：document_id、来源、许可或使用依据、版本、生效时间、权限标签、文件摘要和导入状态。先确认解析文本可读，尤其是 PDF 扫描、表格、页眉与多栏内容。表格的列标题与单位丢失会让检索到的片段无法正确解释，不能靠更多向量弥补。失败文件进入清单，不悄悄跳过。
分块先按标题与语义边界，保证关键条件和结论不被拆散，必要时保留少量重叠与父级上下文。块太短可能缺条件，太长可能引入无关内容；大小是实验参数，不是通用固定答案。块标识需稳定关联文档版本与位置，记录解析器、分块规则和嵌入模型版本，方便复现与删除。
查询与文档的嵌入模型及预处理须兼容。换模型可能改变向量维度、空间与相似度含义，应建新版本索引并评估，不混合旧向量假装无缝更新。小型教学基线可以先用简单本地存储或词项检索；真实选型还要看权限过滤、更新频率、持久化、运维、延迟和预算，不只看文档数量。
GitHub 的 Haystack 是可参考的 Apache-2.0 开源框架，提供检索、索引与生成的可组合组件。它适合复用已有链路能力，减少从零拼接的工作；实际采用前应核查版本、集成依赖、模型服务和维护成本。这里没有安装、部署或宣称一个教程示例已经达到生产要求。框架提供实现组件，技能方法也不能替代实际权限与验收。
最小查询先打印或记录受控的候选块编号与来源，再检查排序和最终上下文。只把用户可访问的材料交给模型，不能先让模型看到内部文档再要求它不要泄露。回答提示要求依据来源、区分未知和冲突，并把检索内容视为证据而不是新指令。模型生成后检查关键结论是否真有支持，避免引用装饰化。
实操：一次“文档有但答不出”的排查
假设问题是“型号 F-27 的维护附录在哪里”，系统却返回通用保养说明。先确认附录已导入且解析成功，再核对 F-27 是否被拆成错误字符、权限过滤是否误排除、该块是否进入候选、是否在重排后被挤出，以及组装上下文是否截断了标题。不要一开始就让生成模型写更长答案。
若候选已有正确片段但回答仍套错型号，问题可能在上下文或生成约束；若正确块根本没进入候选，先修索引或检索。记录问题编号、输入版本、候选排名、上下文块与回答，保留错误类别。修改分块或检索后重跑其他型号问题，防止只为 F-27 修好而破坏普通查询。
给 Agent 的任务可以写成：“仅使用 approved-manuals 中列明文件，先检查解析与来源元数据，再建立可删除的测试索引。对 query-set-v1 输出候选块、引用和无法回答的原因。不得上传未授权文档、连接生产数据库或提供无来源的维修指令。报告运行步骤与失败，不声称未执行的评估已通过。”
场景三：用证据比较检索优化
先建立简单基线，再比较词项检索、向量检索与混合检索。编号和专有词常需要精确匹配，同义描述可能受益于语义相似，但两者都可能失败。混合检索可合并两路候选，RRF 一类方法按排名融合；重排序再对候选相关性评分。优化是否值得，要用本项目问题集与延迟、成本验证，不因为资料少就一定跳过或因为名称高级就全部装上。
检索评估与回答评估分开。前者检查相关块是否出现在前 k 个结果、排名是否合理；若标注了全部相关块才可解释完整的 recall@k，标注不完整时说明限制。后者检查事实支持、引用适配、冲突处理、拒答与用户可理解性。每种语言、编号类、跨章节和无答案问题分别看，不用一个平均准确率掩盖边界。
改变分块、top_k、重排或压缩时一次比较一个主要变量，固定模型、索引版本和测试集。top_k 太大可能增加噪声和上下文成本；压缩可能丢掉否定条件与单位；多跳检索会增加链路与错误积累。先确认失败原因再引入复杂策略，保留回退配置。测试集不能只由模型生成并自行评分，至少人工复核关键样本与相反例子。
知识库还需更新与删除测试：新版本能被找到、旧版本不再被误用、撤回文档对应片段和缓存不再可返回。日志、备份和外部服务的保留政策另行明确，不能把删除一条向量说成所有副本已删除。隔离用户与团队权限，测试相同问题在不同身份下的可见来源，不能只检查最终回答没显示某个关键词。
界面验收与可关联 Skill 的范围
有可运行本地问答页面时，Webapp Testing 可用于这里的前端行为检查：提交问题、显示加载、空结果、错误状态和来源链接。需要 Python、Playwright 与浏览器依赖、启动命令、端口和获准测试数据。先观察实际 DOM 再选稳定控件，保存截图与日志。它不证明检索质量、后端删除、权限隔离或回答事实正确，这些仍需对应链路证据。
原文六个 RAG 名称未取得本次可核验匹配的 SkillPI 来源记录，因此不猜造安装关联。新候选要检查固定来源、许可、模型与向量库依赖、文件或网络权限以及真实输出，再用同一份脱敏手册集试用。不要把安装成功等同于自动调用，更不能把有一个可聊天页面等同于生产上线。
故障排查与 FAQ
先学向量库还是先做任务？先理解完整链路并用小样本检查，但权限、持久化和更新要求不能等规模大了才想。多久能搭好？取决于格式、环境、来源质量和验收范围，没有统一一下午完成的保证。检索到了却答错怎么办？看引用是否支持、上下文是否混版，以及生成是否超出证据。
RAG 能消除幻觉吗？不能，只能增加可检索依据并设计检查与拒答。为何换嵌入模型后效果变差？核对索引兼容、维度、预处理与检索参数，重新建版评估。界面通过测试能上线吗？还要评估来源许可、访问控制、更新删除、资源限制与失败恢复。最终交付文档清单、版本化索引说明、查询集、检索与回答评估及未完成项，让另一位同事能够重现结果。