AI Agent Engineer

AI Agent Engineer
个人学习进度

标记这门课程

课程正文公开可读；登录后可保存个人进度。

RAG

19 min read

RAG

知识库简介

RAG（Retrieval-Augmented Generation，检索增强生成）是在回答前从外部知识源取回证据，再让生成模型依据证据组织回答的系统方法。它把“模型参数里记住了什么”与“当前可查、可更新、可引用的资料”连接起来，适合内部知识问答、客服说明、研究助手和有来源要求的 Agent。

初学者最容易把 RAG 简化成“向量检索 + LLM”。工程上的 RAG 实际包含两条管线：

  • 离线知识管线：来源接入 → 解析 → 清洗 → chunk → 表示 → 索引 → 质量检查；
  • 在线回答管线：身份与路由 → 硬过滤 → 召回 → 重排 → 上下文选择 → 生成 → 引用校验 → 监控。

三个不保证

RAG 不自动保证来源正确、检索完整或回答忠实。检索到文档也不等于文档支持结论；出现引用标记也不等于引用有效；把私有文档放进向量库也不等于权限安全；完整的派生/哈希链也只说明可追溯或可比对，不能单独证明来源真实、已获准入或当前可访问。

在总路线中的位置

本库位于“检索与数据”知识域，是 RAG 角色路径的集成站。它把以下组件连成一条可验收的回答链：

完成本库后，再进入 Tool Calling、MCP 与 Agent 编排：知识问答走 RAG，实时状态和有副作用动作走受控工具，两者不能混为一谈。

学习目标

完成本库后，你应能：

  • 画出离线索引与在线回答管线，说明每层输入、输出和责任；
  • 为 source、parser、chunk、Embedding、索引、检索、reranker、prompt 和模型建立版本链；
  • 区分来源准入、派生 provenance、当前授权与相关性：它们需要不同证据，不能由一个相似度分数或 SHA-256 替代；
  • 区分闲聊、知识检索、实时工具、高风险拒绝和人工升级路由；
  • 先做 tenant、ACL、状态与有效期硬过滤，再做相关性排序；
  • 组合 sparse/dense 召回、融合、重排和可测量的降级路径；
  • 在上下文预算内完成 canonical 去重、来源覆盖、相邻段选择和冲突处理；
  • 将回答拆成可核查 claim，并验证引用确实来自本次上下文且支持 claim；
  • 将 citation 从 source/span/revision 逐层复算到 canonical、parse、chunk、index entry 与已发布 generation；
  • 为原生 Parser、KB 与 Chunking 的不兼容 ID/坐标/发布合同建立显式 scheme、crosswalk 与 release manifest；
  • 对无答案、权限不足、证据冲突、依赖故障和实时问题采取不同策略；
  • 分别评测检索、上下文、回答、引用、路由、安全、延迟与成本；
  • 用 trace 和回归样本定位错误层，而不是看到错答就只调 prompt。

前置知识

建议先完成本阶段前七库以及：

  • API：理解认证、超时、重试和错误契约；
  • JSON：定义结构化输入、输出与 trace；
  • 数据标注：构造 qrels、答案 rubric 和困难负例；
  • 概率统计：理解抽样、置信区间和线上波动。

不要求先训练模型。本库项目只使用 Python 3 标准库。

核心术语

术语初学者解释工程边界
source原始资料及其身份、版本和权限网页标题不是稳定来源 ID
source admission某一 source revision 已通过连接器、owner、许可、分类和发布规则provenance 记录“怎么来”，不等于它已获准入或事实正确
eligibility当前主体、策略、时效下可被搜索/显示的对象集合与“相关不相关”是不同判断，需在缓存和输出处重检
chunk可独立检索的证据单元不一定等于回答上下文
candidate第一阶段召回的候选还未必进入 prompt
evidence通过过滤、重排和预算选择的上下文必须保留来源与版本
grounding回答中的主张由给定证据支持“听起来合理”不算支持
claim可单独核查真假的陈述一个长段落通常含多个 claim
citationclaim 到 source/span/revision 的映射只有 [S1] 格式不够
abstention证据不足时不编答案应区分原因与下一步
trace各阶段输入、版本、候选、决策与故障记录对外结果不能泄露被过滤资料
manifest对一组对象、版本与 hash 的发布摘要摘要不一定携带可独立重建的完整 payload
artifact / bundle可序列化、版本化并由消费者验证的完整受保护产物自哈希只证明自洽，不能证明 producer 或来源真实
attestation某个主体对类型化 payload 作出的可验证声明attestation.mode: none 必须被诚实视为“没有证明”

推荐学习顺序

顺序课程学习产出
1系统边界与完整管线两条管线、版本契约与最小基线
2Query 理解、路由与改写路由表、改写边界与可信过滤条件
3检索、重排与降级编排安全候选链、融合、超时和 fallback
4上下文选择与组装预算、去重、顺序、冲突与不可信数据包装
5引用、生成与拒答claim-level 引用、校验与拒答分类
6失败分类与系统排查从数据到回答的可复现诊断流程
7端到端评测与监控分层指标、测试集、发布门禁与线上信号
8项目：离线可引用问答公共/审计双契约、有界 fixture、证据管线、分层发布报告、故障模拟和 73 项测试
9项目：从来源到引用的离线证据链精确 source span、事件身份、索引代际、撤权/删除与 72 项生命周期/资源边界/篡改测试
10项目：跨模块来源适配与原子发布fresh 调用 Parser/KB/Chunking，处理 ID scheme、坐标 crosswalk、原子 release 与 37 项路径/sidecar/篡改/生命周期回归
11项目：External Provenance Artifact v2完整 protected bundle、strict JSON、带外可信绑定、消费者 staged/local publish、route/coverage/live deny 红队回归

动手实践入口

文件用途
rag-fixture.json10 篇文档、8 类 query、可信授权版本、风险切片与离线 oracle
offline_cited_qa.py硬过滤、公共响应/受保护审计分离、claim 渲染、分层评测报告与 CLI
test_offline_cited_qa.py73 项 schema、文件/深度/集合资源边界、类型健壮性、非干扰、安全、审计绑定、故障、grounding、评测与 CLI 测试
provenance-fixture.jsonUTF-8 Markdown 来源事件、两租户 ACL、恶意字符串、runtime query 与独立 oracle
offline_provenance_pipeline.py来源规范化、parse/chunk/index 身份、generation 发布、检索与 citation 复算
provenance-artifact.schema.json评测 artifact v2 的 JSON Schema 2020-12 结构合同；自哈希不等于真实性
test_offline_provenance_pipeline.py72 项输入资源边界、事件身份、span、生命周期、完整性、外部类型/路由/failure/artifact 篡改、非泄露、报告与 CLI 测试
cross-layer-fixture.json两 tenant、byte-identical 来源、ACL 与独立 runtime/oracle 的 adapter fixture
cross_layer_adapter.py真实三模块导入、protected crosswalk、fresh rebuild、release、citation 与评测 CLI
cross-layer-eval-artifact.schema.json本课本地 evaluation artifact 的结构合同；不是当前 LLMOps 示例的 wire input，也不验证真实性
test_cross_layer_adapter.py37 项 strict contract、路径/symlink、身份冲突、授权、sidecar replay/checkpoint、篡改、生命周期、故障与 CLI 红队测试
external_provenance_v2.pyv2 strict importer、trusted policy、fresh semantic rebuild、消费者发布状态机与双投影 query
external-provenance-bundle-v2.schema.jsonprotected bundle 的 JSON Schema 2020-12 结构合同；自哈希、可信绑定、语义验证和 live gate 分层处理
test_external_provenance_v2.py42 项跨 JSON boundary 的 trust/identity/route/path/order/coordinate/coverage/host-auth/trace/publication/audit-delivery/non-leakage 回归

从项目根目录（同时包含 docs/ 与 .website/）运行：

$env:PYTHONDONTWRITEBYTECODE = '1'  # 禁止运行项目时在课程目录生成 __pycache__。
$env:PYTHONIOENCODING = 'utf-8'  # 强制 CLI 的标准输出和错误输出使用 UTF-8，保证中文 JSON 可读。
$script = '.\docs\RAG\examples\offline_cited_qa.py'  # 保存第 8 课离线问答脚本路径，避免重复输入。
$fixture = '.\docs\RAG\examples\rag-fixture.json'  # 保存严格教学 fixture 路径，所有命令共享同一份输入。
 
python -B -W error $script --fixture $fixture demo  # 运行内置演示，覆盖创建可引用回答的主路径。
python -B -W error $script --fixture $fixture ask --query-id Q-conflict  # 查看冲突证据时的公共响应，不暴露审计候选。
python -B -W error $script --fixture $fixture evaluate  # 在固定 oracle 上生成离线质量与安全评测报告。
python -B -W error $script --fixture $fixture inspect --query-id Q-refund --operator-view  # 仅在本地教学中请求受保护审计视图。

ask/demo 只输出公共响应；inspect 才显示含过滤统计和候选的受保护教学轨迹，--operator-view 只是显式确认，不是真实授权机制。该项目故意没有 Embedding、ANN、LLM 或工具执行。恶意文档样本只能证明控制字段未由文档文本读取，不能代表真实模型已经抵御间接提示注入。

继续运行第 9 课的 source-to-citation 项目：

$provenance = '.\docs\RAG\examples\provenance\offline_provenance_pipeline.py'  # 保存第 9 课来源到引用管线脚本路径。
$provenanceFixture = '.\docs\RAG\examples\provenance\provenance-fixture.json'  # 保存该项目独立的严格 fixture 路径。
 
python -B -W error $provenance --fixture $provenanceFixture manifest --operator-view  # 查看带 generation 的受保护来源清单。
python -B -W error $provenance --fixture $provenanceFixture ask --query-id Q-refund  # 生成仅含公共 citation 投影的回答。
python -B -W error $provenance --fixture $provenanceFixture evaluate  # 重建来源链并计算固定评测集结果。

该项目只对 UTF-8 Markdown 的 LF + NFC 规范字符 span 声明可复算能力。公共 citation 不暴露全局 generation 或过滤计数；受保护审计才把 selected entry 绑定到 generation、authorization 与 snapshot/tombstone 状态。第 8 课固定使用 enum privileged_audit，第 9 课固定使用 protected_audit；二者属于不同 schema，但中文概念统一称“受保护审计”。

最后运行第 10 课的真实模块 adapter：

$adapter = '.\docs\RAG\examples\integration\cross_layer_adapter.py'  # 保存第 10 课跨模块适配器的本地脚本路径。
 
python -B -W error $adapter manifest --operator-view  # 显式请求受保护 crosswalk/manifest 检查视图。
python -B -W error $adapter ask --query-id q-tenant-a-refund  # 运行 tenant-a 的公共回答路径。
python -B -W error $adapter evaluate --operator-view  # 执行跨层发布前的本地可信重跑。
python -B -W error $adapter evaluate --operator-view --failure retrieval_unavailable  # 模拟检索不可用，验证 fail-closed 发布/回答行为。

它导入现有 Parser、SQLite Knowledge Store 与 Chunking 实现，但不会把三套坐标强行改写成一种：公共引用保留 parser 行 locator、element lexical span 与 exact quote，并把尚未验证的 canonical char mapping 标为 unavailable。release 也明确声明尚未把外部 chunk 导入第 9 课 provenance engine。

37 项 adapter 测试覆盖 symlink/path、sidecar replay/checkpoint 与 publish-before-pointer fresh validation；artifact 的无密钥自哈希只证明内部一致，必须由可信 evaluate() 重跑 oracle/pipeline，不能当成签名或独立真实性证明。

第 11 课把第 10 课的完整 raw/parser/crosswalk/chunk/entry 载荷序列化为 external-provenance-bundle-v2。producer 的 published 不会自动授权 consumer：canonical bundle-value 必须先匹配带外 trusted digest/generation/pipeline/auth policy，再以 staged 状态完成 fresh semantic rebuild，最后通过 consumer 当前 auth、tombstone 与 deny gate 才能本地发布。query body 只含问题载荷，tenant/groups/auth 由 host-owned live state 签发的 snapshot-bound context 提供；原始 source locator 只写入 host-owned protected audit sink。该路径仍保持 document-revision-bridge，不会把可传输性误写成 canonical span、来源真实性或签名已验证。

掌握标准

  • 能分清 source、chunk、candidate、selected context、claim 和 citation。
  • 所有硬权限过滤在相关性打分前完成，fallback 也不能绕过。
  • 每个回答可追溯到 source/chunk/revision、各阶段 rank 与版本。
  • 能解释 candidate recall 高但回答仍错的至少三种原因。
  • 能为无答案、冲突、实时状态、无权限和依赖故障定义不同状态。
  • 每个可核查 claim 均有本次上下文中的支持证据。
  • 能从 citation 的 source locator 与半开 span 重构原文，并解释 parser/chunker/index/auth 版本如何使旧派生产物失效。
  • 能解释 byte-identical 跨 tenant 文档为何可共享原生内容 ID、却必须拥有不同授权命名空间 ID，并能读懂 crosswalk 的 scheme 与 loss profile。
  • 能区分 JSON Schema、自哈希、带外 trusted binding、语义重建与 live authorization 五类不同证据，并解释 producer published 为什么不等于 consumer published。
  • 内容更新失败可保留旧版，但 ACL 收紧、auth revision 不匹配和删除会立即阻断；stale snapshot 不能复活墓碑对象。
  • 公共响应与受保护审计轨迹使用不同 schema；未授权语料变化不改变公共响应。
  • 最终 answer 由已验证 status/claims 渲染，不允许出现 claim 外事实。
  • 离线集覆盖常见、长尾、时效、权限、冲突、攻击和无答案切片。
  • 发布门禁同时覆盖质量、安全、p95/p99、成本和 fallback。
  • 能运行项目与测试，并解释它没有验证真实模型质量的原因。

与其他知识库的关系

知识库关系
知识库构建管理来源、增量同步、删除传播与版本
语义搜索提供高召回、已授权的第一阶段候选
Reranking在候选窗口内提高证据前排质量
上下文工程管理总窗口、证据布局和状态
LLM API集成提供生成调用、schema、超时和可观测性
Tool Calling（含 Function Calling）承接实时查询和有副作用动作；路由结果仍需经过 allowlist、对象级授权与确认
MCP提供跨服务资源/工具协议；RAG 引用或资源 URI 不能替代本系统的身份、ACL 与来源验证
Agent 核心决定何时检索、何时用工具、何时停止
评测体系将组件指标联结到真实任务目标
AI安全覆盖间接提示注入、数据投毒、泄露与越权

主要参考资料

来源获取日期：2026-07-22。论文结论适用于其具体数据和实验设置；服务 API、模型窗口、产品能力、价格与 OWASP/NIST 页面会变化，实施时应锁定版本并用本地语料重新验证。

Backlinks