《企业级 Agent 平台工程：从数据智能底座到 AI 原生业务系统》

本书面向企业级 Agent 平台建设，讨论从数据智能底座、模型推理、知识工程、Agent Runtime、工具生态到评估、部署、前端、安全和组织治理的完整工程体系。当前版本聚焦已经形成稳定论证的技术主线、可验证的图表和代码引用，以及可本地构建的网页电子书工程。

核心设计原则

本书在讨论企业级 Agent 平台工程时，贯穿以下六条核心设计原则：

1. 基础硬件固定——所有硬件、数据库、大模型 API 在部署阶段确定，后续不通过训练修改
2. 规则手动输入——所有不可变规则逻辑以框架形式给出，管理员手动修改配置表
3. 流程训练获得——各 Agent 的业务流程、审批链、动态参数通过训练管道获得和优化
4. 知识库规则化——知识库内容由存储数据+联网数据+LLM 共同获得，归入规则项目管理
5. 训练优先——凡是能通过训练处理的内容，不做固定编程实现
6. 文件技能插件化——图片/PDF/Word/Excel 读写技能按需加载，不具备时自动联网安装

版本入口

卷前页面

快速导航

阅读路径

本地验证

bash scripts/check_all.sh
python -m mkdocs build --strict --clean --site-dir /tmp/enterprise-agent-book-site

第一条命令检查章节结构、术语、敏感信息和 mini-platform 测试；第二条命令检查电子书站点能否按严格模式构建。两条命令合在一起，基本覆盖了这本书在提交前最需要守住的本地质量门槛。

>开始阅读 Part I Start with English Edition >阅读卷末说明

缩写表

本表用于统一中文早期中的英文缩写、中文译名和本书采用的工程口径。正文首次出现缩写时仍应给出全称或简短定义；本页用于回查，不替代章节中的概念解释。

序言

企业建设 Agent 平台时，最容易低估的是系统边界。一个可以演示的 Agent 往往只需要模型、提示词和几个工具；一个能够长期运行的企业级 Agent 平台，还要回答任务定义、工具授权、数据解释、运行审计、失败恢复、成本控制和风险治理等问题。

这本书围绕这些工程问题展开。全书关注企业系统中的接口、状态、证据、权限、评估和组织协作：模型只是其中一层能力，数据底座、知识工程、运行时、工具注册、可观测性、部署和安全治理共同决定了 Agent 能否进入生产。DataAgent 的主线也会从 NL2SQL 扩展到语义层、权限、执行、解释、评估和人工复核。

中文早期采用“平台工程”视角组织内容。前半部分先建立 Agent 平台的基本语言，解释模型、数据、检索和 Runtime 之间的关系；中间部分以 DataAgent 为主线，把语义层、NL2SQL、Python 分析、可视化报告和评估串成可交付链路；后半部分回到可观测性、成本、部署、安全、合规和组织演进。读者可以按顺序阅读，也可以把本书当成架构评审、方案设计和问题排查时的参考手册。

当前版本聚焦已经形成稳定论证的技术主线。业务案例需要真实材料、脱敏过程和事实核对，因此案例部分以准入方法和复审标准为主。希望这本书能帮助读者从“做一个 Agent”推进到“建设一套可治理的平台能力”，让团队在真实业务、真实权限、真实数据和真实故障中持续交付。

致谢

卷前导读：全书结构、阅读路径与版本说明

一、卷前导读的作用

这本书覆盖模型推理、数据基础设施、知识工程、Agent Runtime、DataAgent、评估、部署、前端、安全和组织治理。第一次阅读时，可以先判断自己当前面对的问题类型，再进入对应篇章；完整顺读适合建立体系，按问题跳读适合方案评审和故障排查。

本页先说明全书主线，再给出按角色和按问题类型的阅读路径，最后说明当前版本的内容范围。读者进入正文前可以先建立方向感，也可以把章节、图表、附录和检查清单组合成工作参考。

二、全书结构总览

全书可以看成四层。

第一层是平台观。Part I 说明什么是 Agent、为什么企业需要平台、AI 原生业务系统和普通软件有什么不同，以及后续章节如何组合成一张参考架构地图。

第二层是能力底座。Part II 到 Part IV 分别讨论模型推理、数据基础设施、向量检索与知识工程。它们回答的是：Agent 需要怎样的模型、数据和知识环境，才能把回答、检索和执行变成可治理能力。

第三层是 Agent 与 DataAgent 主线。Part V 讨论 Runtime、Tool Registry、MCP、Planner、Workflow、Memory、多 Agent、协议和 HITL；Part VI 则把这些平台能力落到 DataAgent 产品形态、语义层、NL2SQL、Python 分析、可视化报告和生态对标。

第四层是生产治理。Part VII 到 Part X 处理可观测性、评估、成本、SLO、部署、网关、前端、多模态、安全、合规和组织演进。它们决定系统能否从单点原型进入长期运行。

Part XI 讨论案例方法论和案例准入规则。业务案例需要真实材料、脱敏过程和事实核对；缺少这些条件时，本书只讨论方法和复审标准。

三、按角色阅读

四、按问题阅读

如果当前问题是“模型应该怎么选”，先读 Part II，再回到 Part VII 的评估与成本章节。模型榜单只能提供初筛线索，任务画像、数据边界、输出契约、延迟和回滚才是生产评审的核心材料。

如果当前问题是“DataAgent 为什么回答不稳定”，先读 Part III、Part VI 和 Part VII。许多问题来自语义层、表关系、权限过滤、SQL 执行、证据引用和评测口径，需要沿着数据链路一起排查。

如果当前问题是“Agent 如何从原型进入生产”，先读 Part V、Part VIII 和 Part X。Runtime 状态机、工具注册、网关、多租户、安全策略、人工接管和审计链路是生产化的基础。

如果当前问题是“团队如何治理这套平台”，先读 Part I、Part VII、Part X 和附录。平台需要共同的术语、门禁、日志、Owner 和复盘机制，单个应用团队通常难以独立承担这些长期责任。

五、图表、附录与检查项的用法

本书中的图用于建立系统边界、流程和状态关系；表用于表达决策取舍、字段契约、风险控制和检查项。阅读时可以把图表作为方案评审和团队沟通的模板。

附录承担执行层支撑。安装、术语、API、评测集、写作规范、延伸阅读、技术对标和合规清单，都适合在项目落地时反复回查。正文建立判断框架，附录帮助团队把判断转成可执行动作。

六、当前版本的内容范围

当前版本优先处理三类稳定内容：已经成章的技术主线、可验证的图表和代码引用、可本地构建的网页电子书工程。案例章节采用准入与复审方法，避免把缺少证据的客户背景、上线规模或收益数字写成确定事实。

引用本书时，建议记录阅读日期、章节号和页面路径，便于在内容调整后继续定位原始语境。

贡献者

Part I 总论与平台观

4 章 · 作为全书开篇，负责建立共同语言、平台视角与阅读地图

Part I 用四章建立全书的共同语言：

1. Agent 到底是什么，和 RAG、Copilot、Workflow 有什么边界？
2. 企业为什么需要平台来承载多条智能项目线？
3. 什么叫 AI 原生业务系统，它和“在旧系统上加 AI 功能”有什么差别？
4. 后续 55 章为什么按现在这个顺序组织，应该如何阅读？

这四章承担“卷首总论”的角色，不直接进入组件实现，而是先把后续技术章节需要依赖的判断框架立起来。读完这一部分，读者应能先形成一套统一的判断口径，再带着它进入后文的工程细节。具体说来，至少要能完成下面三类判断：

• 区分 Agent、RAG、Copilot 与 Workflow 的边界；
• 用平台视角重新看企业 AI 项目的共性问题；
• 理解后续章节为什么按模型、数据、知识、运行时、评估、部署、安全和前端组织。

四章之间的关系

这一部分最适合怎么读

第一次接触企业级 Agent 平台的读者，建议顺序读完四章。四章之间是一条递进论证链：先界定 Agent，再界定平台，随后讨论 AI 原生业务系统，最后进入全书地图。如果你已经有一些项目经验，则可以按下面的方式跳读：

Part I 读完之后，读者应能建立三种能力：

• 能区分不同类型的大模型系统；
• 能用平台视角重新看企业 AI 项目；
• 能知道后续每个技术主题为什么存在。

带着这三种能力进入 Part II，后面的模型、数据、知识、Runtime、评估、安全和前端章节，会逐渐拼成一张完整的企业级 Agent 平台工程图。这样读下去，后续每个技术点都应该放在平台工程链路中定位，孤立模块只是局部视角。

第1章 Agent 的边界：从对话助手到任务执行系统

场景引入

一个报价助手从“查资料、写草稿”变成“生成可发送报价单”时，系统边界已经变了。前者答错，销售通常还能人工改；后者一旦调用了折扣规则、库存系统和审批接口，错误就会进入真实业务流程。很多企业第一次做 Agent，都会在这里误判：演示里的对话很顺，任务看起来也完成了，但系统是否已经在替人做决策、是否产生副作用、是否需要审批和审计，并没有被同步设计。图 1-1 要说明的就是这条分界线：系统从给出建议转向推进任务时，工程责任也随之改变。

一家制造企业曾经把报价助手作为大模型试点。早期版本只做三件事：查询历史合同，整理同类客户的折扣范围，帮销售写一版报价说明。这个版本看起来不够“自动”，但风险很清楚。系统给出建议，销售判断是否采用，正式报价仍然走原来的审批链。即使模型把某个历史项目理解错了，错误也停留在草稿层，销售和主管还有机会发现。

试点得到认可后，业务团队希望把流程再往前推一步。销售不想在合同系统、库存系统、折扣规则和邮件系统之间来回切换，于是团队把这些工具接给模型，让它根据一句“客户本周要签，给一个有竞争力的价格”直接生成报价单。表面上看，用户体验只是少了几次点击；系统责任却完全不同。模型开始决定查哪些规则、套用哪个客户等级、是否触发审批，以及把结果以什么格式交给销售。销售看到的不再是一段可修改建议，而是一份可以被转发给客户的业务文件。

真正的问题往往发生在这种灰色地带。系统没有主动发邮件，也没有自动签合同，所以团队容易认为风险还在可控范围内。但它已经把过期促销规则写进了报价草稿，又把“有竞争力”理解成向大客户折扣靠拢，最后还没有提醒销售这份折扣必须先经过区域总监确认。销售如果在忙乱中直接复制发送，后果就不再是“回答不准确”，而是价格承诺、审批绕过和客户预期管理的问题。这类事故很少能靠一句“模型要更准”解决。模型确实需要更准确，但系统还需要知道哪些数据是权威版本，哪些动作只是建议，哪些动作会改变业务状态，谁有权确认，出了问题以后怎样回放当时的输入、工具调用和中间判断。企业讨论 Agent 的第一步，应该先把这些责任摊开，而非急着给所有智能功能贴上同一个名字。

图1-1：从对话助手到任务执行系统。来源：本书自绘。Alt text：左侧“对话助手”接收提问并返回答案，右侧“任务执行系统”在目标驱动下调用工具、推进多步动作并产生带业务后果的结果，箭头标出二者在决策与副作用上的分界。

Agent 的关键变化不在表达能力，而在任务推进方式：它开始把数据、工具、流程和责任边界组织到同一条任务链中。本书讨论的 Agent，是企业系统里被约束、被观察、可回放、可降级的一类任务执行能力。读者不应把演示视频里的“自动完成一切”当成建设目标，而应关心系统进入真实流程后承担了哪些责任。本书会区分智能交互、任务执行和平台责任，避免把所有能力都装进同一个概念里。后续每一章都会回到同一个问题：当模型输出开始影响真实业务动作时，系统需要补上哪些工程责任。

本章先处理概念边界。读完这一章，读者应能用三个朴素问题判断一个系统是否进入 Agent 范围：最终决策由谁做，任务路径是否会动态变化，系统动作是否会产生业务副作用。知识查找问题优先考虑 RAG，内容起草问题优先考虑 Copilot，路径稳定的问题优先考虑 Workflow。只有当任务需要跨系统推进、根据反馈调整步骤，并且每一步都可能改变后续选择时，Agent 才真正有必要登场。这种判断的目的在于减少上线时的错配，技术标签只是辅助。把 RAG 当 Agent，会让项目背上不必要的审批和运行时负担；把 Agent 当聊天助手，又会漏掉权限、审计、失败恢复和人工确认。企业级 Agent 的设计从边界开始，本章讨论的每个概念，后面都会落到具体平台组件上。

1.1 从“会回答”到“会执行”：Agent 的根本转折

一家多业务线企业的制造板块曾经做过一个报价助手。最初它只是帮助销售查询历史合同、参考折扣区间、生成报价草稿。演示时效果很好：用户提出需求，系统几秒钟内给出一份结构化报价建议，还能整理过去类似项目的参考案例。团队很快产生了一个自然但危险的判断：既然它已经能“看懂问题、找到信息、写出结果”，那不如再往前走一步，让它直接帮销售完成报价动作。于是报价助手被接上真实工具：合同系统、库存系统、折扣策略、审批接口，甚至还可以自动生成对客户的报价邮件草稿。问题很快暴露出来。有一次，一位销售输入：“客户希望这周签约，给一个尽量有竞争力的价格。”系统按照历史案例推断出 12% 的折扣方案，并生成了报价单。表面上，这只是“把建议变成草稿”；实际链路已经变成企业任务：理解意图、判断价格策略、调用工具、产出带业务后果的结果。

事后复盘发现三处问题。第一，系统调用了过期的促销规则，没有意识到当天生效的新限价。第二，它默认把“尽量有竞争力”理解为“向历史大客户靠拢”，却忽略了这个客户并不具备同等级折扣权限。第三，它把本应进入审批链的结果提前送到了销售手里，用户稍不留神就可能转发给客户。这个案例揭示了一个经常被低估的转折点：系统一旦开始替人推进任务，讨论对象就会从问答质量转向执行责任。问答系统出错，常常只是答案不好；执行系统出错，可能意味着权限越界、流程绕过、数据误用、责任不清。按照这个边界看，Agent 应被当成任务执行系统处理，而非被当成更聪明的聊天助手。后续章节讨论 Runtime、工具注册、HITL、Trace 和评测时，也都会沿着这条责任边界展开。

1.2 RAG、Copilot、Workflow、Agent：四类系统的边界

企业讨论 Agent 时，最大的混乱之一来自命名。很多项目只要用了大模型，就自称 Agent；很多固定流程系统，也被包装成 Agent。后续章节要讨论平台、工具和治理，先需要把四类常见形态分开。RAG 的核心工作是找资料、给答案和补上下文，最终决策仍由用户完成，系统通常不直接推进业务状态。Copilot 更进一步，它会陪用户起草、修改、补全和建议，但主导权仍在人手里。Workflow 解决的是确定性流程，把规则和路径预先写好，系统按既定步骤推进。Agent 则不同，它围绕目标动态判断下一步，调用工具、接收反馈，并在任务状态变化后继续推进。这四类经常组合出现。一个成熟系统可能用 RAG 提供知识与上下文，用 Copilot 帮用户起草或修改结果，用 Workflow 固定高风险、强合规的环节，再把无法提前写死、需要跨系统推进的部分交给 Agent。

判断重点不在名字，而在系统承担的职责。系统如果主要在企业知识库里找答案，大概率是 RAG；始终由人主导，模型只是在旁边给建议，更像 Copilot；从第一步到收尾路径都固定，则更接近 Workflow。系统围绕目标理解上下文、选择动作、接收反馈并继续推进时，才进入本书所说的 Agent 范围。更实用的问法是：“这件事的难点在哪里？”如果困难主要在知识查找，RAG 往往已经够用；如果困难在内容起草，Copilot 更容易落地；如果困难在流程规范，Workflow 的稳定性更高；只有当困难集中在多步判断、跨系统推进和实时调整上，才值得把它作为 Agent 任务处理。

图1-2：RAG、Copilot、Workflow 与 Agent 的边界。来源：本书自绘。Alt text：四类系统沿“决策主体”和“执行确定性”两个维度排布，RAG 与 Copilot 由用户主导、偏低执行，Workflow 路径固定，Agent 在目标驱动下动态选择动作，虚线表示成熟系统常将四者组合使用。

图 1-2 提醒团队先看责任边界，再谈系统名称。成熟系统可以组合 RAG、Copilot、Workflow 和 Agent，但组合方式必须服从决策主体、流程确定性和执行责任这三个约束；只要某个环节开始替用户推进业务动作，就要按 Agent 的工程责任处理。

1.3 Agent 的任务闭环：目标、上下文、决策、行动与反馈

本节把 Agent 放回任务回路里定义，而非从模型能力或产品名称出发。这样做的好处是，后续讨论工具、记忆、审批和评测时，都能回到同一个问题：系统是否真的围绕任务持续推进。用一句尽可能朴素的话说：

Agent 是围绕任务目标组织感知、决策、行动和反馈的系统闭环。

这个定义的重心在“闭环”。一个企业级 Agent 通常要处理五类对象；表 1-1 将它们拆成五个问题，便于后续映射到 Runtime、Planner、工具调用和 Trace。

表1-1：Agent 任务闭环的五个要素及各自回答的问题。来源：本书整理。

这些环节少掉任何一个，系统都会退回到更弱的形态。没有目标，它会变成泛对话；没有上下文，它会在错误信息上做看似合理的判断；没有决策，它只能生成文字；没有行动，它停留在建议层；没有反馈，它很难纠错，也难以收敛。很多“看起来像 Agent”的产品更接近高级 Copilot：有对话、有工具、有结果，但任务没有形成反馈链路。对企业来说，闭环还会带来责任问题：谁允许系统这么做，它依据什么信息判断，什么条件下要停下，做错以后怎样发现、复盘和修正。这些问题无法靠单个应用自行消化，最终都会回到平台层。

1.3.1 Agent 概念快速泛化的原因

“Agent”这个词的快速流行，既来自学术定义，也来自几股力量叠加。模型能力先发生了变化。过去的企业 AI 系统大多擅长分类、预测、检索和生成某个局部结果，很少让系统自己决定“下一步做什么”。大模型把自然语言理解、跨域知识调用和结构化输出能力拉高之后，企业开始看到一种可能性：系统可以从回答者变成任务参与者。工具调用能力也在成熟。早期大模型应用即使回答质量不错，也常常停留在文本世界里。Function Calling、结构化输出、Code Interpreter、MCP 这类能力逐渐成熟之后，模型不再只是“说”，也能比较稳定地“做”。这使企业需要认真面对执行边界。

企业软件形态本身也在变化。过去十几年，企业软件的主导范式是模块化 SaaS：CRM 是一个系统，ERP 是一个系统，BI 是一个系统，工单又是一个系统。大模型出现之后，用户更明确地提出一种期待：不想在系统之间来回切换，只想把任务交给系统。热度来得太快，“Agent”也就容易被拿来包装任何大模型功能。判断一个系统是否真的进入 Agent 范畴，还是要回到它承担了多少任务责任。

1.4 Agent 适配任务的场景分型、风险分级与价值判断

企业做 Agent 时，常见问题是边界铺得太泛。很多团队一旦有了大模型和几个工具，就把所有智能需求都归到 Agent 下面，治理压力也随之放大。更可控的方式，是先给企业任务分型。查询型任务的难点在于找到准确信息，优先使用检索、RAG、语义层或 BI；草稿型任务的难点在于快速生成可修改结果，更适合 Copilot 或内容生成助手；诊断型任务需要组合多源信息并逐步缩小问题范围，才开始显出 Agent 的价值；执行型任务会调用工具、跨系统推进并产生副作用，通常需要 Agent、Workflow 和审批链共同承担。

放到具体场景里，这个判断会更清楚。“查一下某客户近三个月投诉记录”首先是查询型任务，RAG 加 CRM 查询就能覆盖大部分价值；“根据这周销售数据起草经营复盘”主要是草稿型任务，Copilot 或低风险任务型 Agent 就够用；“解释华东区毛利率为什么异常”需要跨指标、订单、库存和历史解释逐步诊断，更接近 DataAgent；“生成报价并进入审批”已经触达业务动作，必须把 Agent 和 Workflow、审批、审计放在一起设计。这套分类法有两个用处：避免过度设计，也帮助团队判断哪些场景会拉动平台能力。诊断型和执行型任务，通常会稳定需要 Runtime、Registry、Policy、Trace。任务适配度和风险等级是两张不同的表。一个任务可能非常适合 Agent，但风险等级很高，因此只能在强审批前提下推进；也可能风险不高，但其实根本不需要 Agent。企业经常把这两件事混为一谈，于是该快的场景做得很慢，该谨慎的场景又做得太冒进。

表1-2：任务的五级风险分级与对应的执行控制方式。来源：本书整理。

更可控的做法，是先判断“这个任务结构上是否适合 Agent”，再判断“即使适合，它允许 Agent 自主到什么程度”。本书把 Agent 的定义、平台边界和 AI 原生系统分成三章来讲，原因也在这里：任务适配、治理约束和系统形态属于不同层次。

1.5 企业级 Agent 的难点：边界、责任与组织语言

消费级 Agent 最吸引人的地方，是它看起来什么都能做；企业级 Agent 最难的地方，是它要清楚自己停在哪里。一旦放进企业环境，Agent 面对的是组织边界、权限边界、流程边界和责任边界。也因此，企业级 Agent 的困难通常不先出现在“模型会不会回答”，而会出现在下面五类失败上。

表1-3：企业级 Agent 的五类失败及其常见根因。来源：本书整理。

这套失败谱系有一个重要作用：防止团队把一切问题都归咎于模型。很多企业项目一出错，第一反应是“换模型”或者“继续调 Prompt”。但问题也可能来自工具契约、权限、语义层或审批链。把问题分类，是在恢复系统分析能力。在企业里，失败处理有优先级。治理失败决定能否上线，执行失败决定系统是否稳定，理解与规划失败决定结果质量，产品失败决定用户能否长期使用。企业场景先看可控，再看体验是否足够出彩。

1.5.1 “数字员工”类比的局限

市场宣传里很喜欢把 Agent 称为“数字员工”“AI 同事”“虚拟专员”。这些说法容易传播，但在工程上很危险。因为一旦把 Agent 想象成“员工”，团队就很容易期待它像人一样理解语境、承担责任、知道分寸、自动补全上下文。但真实系统并不会天然拥有这些能力。它只是在给定上下文、工具、策略和模型能力下生成下一步动作。更准确的说法是：Agent 是任务链中的系统组件，承担部分感知、决策和执行工作。它可以提高人的杠杆率，企业责任链仍然由组织、流程和系统共同承担。把 Agent 当成员工，讨论会滑向“它够不够聪明”；把 Agent 当成任务执行系统，讨论会回到“它在什么边界内可靠”。企业要回答的是后一个问题。

1.5.2 从业务语言到系统语言

企业里提出 Agent 需求的人，往往是业务负责人、产品经理、运营团队或职能部门，而非工程师。他们不会说“我需要一个带 Runtime、Tool Registry 和 Policy 的任务执行系统”，他们通常会说：“希望系统自动帮我分析异常”“希望它像助理一样跟进客户”“希望它把月结材料先整理出来”。这些表达都是真实需求，但还不是系统需求。Agent 平台工程师首先要把业务语言翻译成系统语言。这种翻译过程看似是需求澄清，实际决定项目能否落地。业务方说“自动帮我分析异常”时，系统要追问异常定义、数据来源和诊断步骤；业务方说“像助理一样跟进客户”时，系统要区分提醒、内部待办、客户触达和审批责任；业务方说“把月结材料整理出来”时，系统要区分必须准确的数据、可以人工修改的草稿和需要审计的结论；业务方说“看懂制度然后告诉我怎么处理”时，系统要确认制度来源是否权威、答案是否需要引用、是否能形成具体动作。

很多失败项目的根因不在模型能力，而在需求没有被拆成目标、上下文、工具、风险和验收标准。以报价助手为例，“给一个有竞争力的价格”在业务语言里很自然，但在系统语言里至少要拆成五个问题：有竞争力是相对历史同类客户，还是相对当前库存压力？客户等级和销售权限允许的折扣上限是多少？当前是否存在区域限价、活动政策或临时禁售规则？系统生成的是建议、草稿，还是可以直接进入报价流程？超出什么阈值必须进入审批？只有完成这种翻译，Agent 才能从“会听懂人话”走向“能在企业边界内做事”。

补充：双通道意图识别架构

在企业级 Agent 落地中，一个关键的设计决策是双通道意图识别。系统将用户输入分为两类完全不同的处理路径，从架构层面隔离业务操作与管理咨询的风险：

这种设计的核心价值在于：业务操作必须经过完整的安全审核链，而管理咨询则通过知识库和 LLM 的联想能力回答，两条通道在数据访问和安全管控上完全隔离。这避免了咨询类对话意外触发业务操作的风险，也防止了业务数据通过咨询通道泄露。

设计启示：协调 Agent 负责意图识别和任务调度（"派谁干"），审核引擎负责安全校验（"能不能干"），两者职责分离，不可混淆。协调 Agent 不碰业务数据，审核引擎不做业务决策。

1.6 从试点到生产：生命周期、任务组合与运营门槛

很多企业在早期设计 Agent 时，会把注意力放在一次交互上：用户输入一句话，系统输出一个结果。这个视角适合演示，却不足以理解企业级 Agent。企业里有价值的任务，往往是一段持续过程，而非一次问答。经营分析问出“毛利为什么下降”之后，还会进入会议、行动项、责任人和下周复盘。报价生成草稿之后，还要进入审批、客户沟通、合同签署和履约跟踪。客服质检发现异常之后，还要进入人员培训、知识库修订和服务策略调整。Agent 一旦进入企业，就会从“一次执行”变成“长期运行”。随之而来的是几项基本要求。

任务状态需要被保存。系统除了最终答案，还要知道任务从哪里开始、经历了哪些步骤、哪些地方被人确认过、哪些地方还在等待。任务结果需要能被后续消费。经营分析 Agent 生成的行动项，可能要进入项目管理或会议系统；报价 Agent 生成的草稿，可能要进入审批系统；票据 Agent 发现的异常，可能要进入财务复核队列。Agent 的结果如果只是聊天记录，就很难成为企业工作的一部分。任务经验也要能沉淀。用户每一次修改、驳回、确认和反馈，都是系统改进的依据。企业级 Agent 上线后，仍要通过持续反馈贴近企业真实工作方式。

1.6.1 试点到生产的五道门槛

很多 Agent 项目并非卡在试点，而是试点成功后过早进入生产。从试点到生产，至少有五道门槛。

表1-4：从试点到生产的五道门槛在两阶段的不同状态。来源：本书整理。

这五道门槛属于 Agent 系统本身，是上线前要处理的工程责任。Agent 的价值来自执行；进入执行之后，稳定性、可信度、控制边界、复核能力和运营机制都要跟上。还有一个常被忽略的门槛，是业务团队是否已经接受“部分自动化”的现实。很多试点在演示时追求一口气完成任务，生产时却需要把动作拆成可自动执行、需要确认、必须审批和默认禁止几类。报价助手可以自动整理历史案例，可以生成折扣建议，也可以把报价单写入草稿区；但超过折扣阈值、触达客户邮件、提交正式审批这些动作，应由人或既有流程接住。这样的拆分看起来降低了自动化程度，实际是在保护系统能长期运行。

从这个角度看，Agent 上线前最该准备的不是一段更长的 Prompt。团队更需要一份任务责任表。表里要写清楚输入来自哪里，工具能做什么，哪些步骤会改变业务状态，哪些结果只作为建议，哪些异常必须停下。工程团队用它设计工具权限和 Runtime，业务团队用它确认流程责任，安全和内控用它判断审批要求。没有这份责任表，系统即使能跑通，也很难进入生产。责任表还会暴露一个现实：同一个任务在不同组织里边界不同。总部报价、区域报价和渠道报价可能使用不同折扣权限；内部经营复盘和对外客户邮件也对应不同审批要求。Agent 设计如果只看任务名称，就会忽略折扣权限、审批要求和对外承诺这类流程差异。真正要判断的是它进入哪条业务流程。一旦企业开始认真面对这些门槛，它就不可能只做一个孤立 Agent，而必然要进入平台问题。这正是第二章的起点。

1.7 企业 Agent 边界的评审方法

边界评审最好发生在原型之前，而不是演示之后。原型阶段一旦把工具、数据和界面都接起来，团队很容易被“已经能跑通”牵着走，反而不愿意重新拆任务责任。更稳妥的做法，是把候选 Agent 需求先写成一条任务链：用户提出什么目标，系统需要读取哪些数据，可能调用哪些工具，每一步是否改变业务状态，哪些节点需要人确认，最终产物会被谁使用。只要这条链写不完整，就说明项目还停留在想法层，不能直接进入生产承诺。

评审时可以先看三个输入。第一是任务目标，必须写成可验收的业务结果，而不是“让系统更智能”。“解释华东区毛利异常”比“做一个经营分析助手”更适合评审，因为前者能继续追问指标口径、数据范围、异常定义和输出格式。第二是执行边界，必须列出系统允许做的动作和默认禁止的动作。查询指标、整理历史案例、生成草稿、写入审批草稿区、触达客户、提交正式单据，对应完全不同的风险控制。第三是证据要求，必须说明结果需要哪些引用、Trace、工具响应和人工确认记录。没有证据要求的 Agent，即使短期体验很好，也很难在事故和复盘中站得住。

边界评审还要做降级判断。并不是每个候选需求都应该被做成 Agent。若任务主要是查资料，RAG 加引用和权限过滤可能更合适；若任务主要是写文案或整理材料，Copilot 形态通常更容易被用户接管；若流程路径稳定，Workflow 的确定性和审计性更可靠。Agent 适合那些路径会随中间结果变化、需要跨系统推进、并且需要在执行中持续判断的任务。把简单查询做成 Agent，会增加运行时、审批和评测负担；把高风险执行伪装成 Copilot，则会漏掉工具权限、人工确认和失败恢复。

评审结果应形成三类产物。第一类是任务责任表，记录目标、参与角色、工具、数据、风险等级和人工节点。第二类是运行证据要求，说明 Trace 至少要记录哪些输入、输出、工具调用、策略命中和人工操作。第三类是准入结论，明确当前需求适合 RAG、Copilot、Workflow、Agent，还是只适合继续做探索原型。这样的结论看起来比“做一个智能助手”更慢，却能减少后续返工。企业级 Agent 的可靠性要从边界评审开始，把责任写进系统设计；上线后的运营只能修正问题，无法替代前期边界设计。

1.8 从概念边界到平台责任

本章讨论 Agent 的边界，是为了明确企业系统要承担哪些新责任，而不是给行业术语下一个固定定义。一个系统一旦从“回答问题”走向“拆解任务、调用工具、推进状态”，它就不再只是模型应用。平台必须能回答：谁授权它执行，执行了哪些动作，依据哪些证据，失败后如何恢复，结果由谁复核。读者在后续章节中会反复看到这个边界。第22章的 Runtime 负责把任务变成可管理的 Run，第23章的 Tool Registry 负责让动作可登记和可审计，第30章的 HITL 负责让高风险动作停下来等人判断，第38章的 Trace 负责让过程可回放。没有这些平台责任，Agent 很容易停留在演示阶段：它能生成一个合理答案，却无法成为企业生产系统。判断一个场景是否适合 Agent 时，模型能不能理解用户意图只是起点。团队还要看任务是否需要跨步骤推进，是否会触达企业数据和工具，是否需要证据链和责任链。这个判断会直接影响全书的阅读方式：前几章建立平台观，后续章节逐层补齐模型、数据、工具、运行时、评测、安全和组织治理。

1.9 读者预期与章节主线

本章给出的边界判断，会贯穿后续所有章节。读者不必把 Agent 当作一个更聪明的聊天界面来理解，而应把它看成会进入企业任务链的运行系统。只要系统开始拆解目标、选择工具、读取数据、写入状态或生成可交付产物，它就需要平台来管理授权、执行、证据和回滚。后续章节讨论模型、知识库、工具、Runtime、DataAgent、Trace、安全和组织治理时，都会回到同一个问题：这次自动化到底改变了哪一个业务状态，谁允许它改变，系统留下了什么证据。

阅读本书时，可以先用三条线索串起内容。第一条线索是执行线：模型如何从自然语言变成任务计划，Runtime 如何管理中间状态，工具如何被登记、授权和调用，HITL 如何接住高风险动作。第二条线索是证据线：RAG 引用、语义层口径、工具响应、Trace、Eval 和人工确认如何共同说明一次结果可信。第三条线索是治理线：成本、SLO、安全、合规、组织责任和案例准入如何限制 Agent 的扩张速度。这三条线索共同决定 Agent 能否从演示进入生产。

初学者容易把 Agent 的难点理解成“模型还不够强”。模型能力当然重要，但企业落地的主要矛盾往往出现在模型之外：上下文来源不稳定，工具契约不清，权限没有透传，审批状态无法恢复，Trace 不能回放，错误样本没有进入评测。把这些问题提前说清，是为了让读者在后续章节中看到各个技术模块的真实位置。比如第8章的结构化输出承担工具执行前的契约职责；第23章的 Tool Registry 汇集权限、schema 和审计入口；第38章的 Trace 支撑事故定位和评测回放。

因此，早期平台不需要一开始覆盖所有场景。更合理的起点，是选一条边界清楚、证据充分、工具副作用有限的任务链，把目标、数据、工具、人工节点和回滚条件写成可审查材料。平台先把这条链跑稳，再逐步扩展到更多业务域。这样读者在后续章节看到复杂架构时，不会把它理解成一次性建设的大工程，而会理解成企业 Agent 在生产中被迫补齐的一组能力。

1.10 边界评审样本与读者自检

读者可以用一组样本来检验本章边界。第一个样本是知识问答：用户问制度条款，系统检索文档、给出引用、不产生外部动作。这通常更接近 RAG。第二个样本是写作辅助：用户要求生成会议纪要或邮件草稿，系统输出可编辑文本，由人决定是否发送。这更接近 Copilot。第三个样本是固定审批流：用户提交报销材料，系统按确定规则校验、流转、归档。这更接近 Workflow。第四个样本是经营异常分析：系统要澄清指标、查数、分析原因、生成图表、等待负责人确认，并把结论带入下次复盘。这才更接近 Agent。

这组样本的用途，是帮助团队把需求放到正确形态里。若团队把所有样本都叫 Agent，后续就会为简单任务引入过重运行时，也会为高风险任务遗漏审批和 Trace。边界评审服务于责任分配，让不同系统形态承担合适责任。RAG 要做好证据和权限，Copilot 要做好可编辑和接管，Workflow 要做好确定性和审计，Agent 要做好状态、工具、恢复和责任链。

读者自检时可以问五个问题。系统是否会改变业务状态？是否需要跨步骤记住中间结果？是否会根据工具返回改变下一步？是否需要在异常时恢复或转人工？是否需要证明每个动作由谁授权、基于什么证据？如果多数答案是否定的，项目可能暂时不需要 Agent 形态；如果多数答案是肯定的，就应尽早引入平台能力，而不是把所有责任压到 Prompt 上。

这个自检会影响后续阅读。把项目判定为 RAG，就优先读第19章到第21章和第40章；判定为工具增强 Copilot，就优先读第8章、第23章和第47章；判定为长任务 Agent，就要读 Runtime、Planner、Memory、HITL、Trace 和安全章节。第一章给出入口判断，后续章节负责把这些判断落成工程实现。

1.11 边界判断对后续章节的约束

本章的边界判断会约束后续章节的阅读方式。读模型章节时，读者要同时关注推理服务的回答质量和任务执行支撑能力；读工具章节时，要关注工具调用是否改变业务状态，以及状态变化是否留下证据；读 Memory、Planner 和 Runtime 章节时，要关注系统是否拥有跨步骤决策能力，以及这种能力是否受到权限、预算和审批限制；读 DataAgent、观测、评测和安全章节时，要关注 Agent 行动之后是否能被复盘、评估和恢复。Agent 是多项平台能力组合后的运行形态，跨越模型、工具、运行时、证据和治理边界。

这种约束能帮助读者避免两类误读。第一类误读是把所有对话式体验都理解为 Agent，于是过早引入 Planner、Memory 和多工具编排，结果增加了成本和风险；第二类误读是把 Agent 只理解为模型推理，于是忽视工具权限、审批、Trace、Eval 和安全门禁，系统上线后无法承担真实业务责任。全书采用平台视角，是因为企业场景里的问题通常不会停在单一模型或单一应用。一个任务能否进入 Agent 化改造，要同时看决策主体、动作副作用、失败恢复、证据保留和组织责任。

因此，第一章提供的是后续工程判断的入口。读者可以在每一章反复回到本章的问题：这个能力是否让系统更接近可执行任务，是否带来新的责任边界，是否需要平台治理承接。如果答案清楚，扩展功能才有意义；如果答案模糊，就应先补边界、证据和恢复路径，再谈更复杂的 Agent 能力。

1.12 术语边界的团队对齐

Agent、Copilot、Workflow、RAG 这些词在企业内部很容易被不同团队用成不同含义。产品团队可能把任何对话入口叫 Agent，模型团队可能把工具调用叫 Agent，业务团队可能把自动化流程叫 Agent，安全团队关心的是系统是否产生副作用。术语没有对齐时，评审会就会变成概念争论，真正需要决定的权限、证据和恢复路径反而被推迟。

团队对齐可以从任务样本开始。先把任务拆开：用户提出什么目标，系统读取哪些上下文，是否调用工具，是否改变业务状态，是否需要人工确认，失败后如何恢复。样本拆清后，系统形态自然会显现。术语应服务工程判断，工程判断不应被术语标签牵着走。

本书后续章节也采用这种方式。每次引入能力，都尽量说明它解决哪一段任务链路、承担什么责任、留下什么证据。读者如果在自己的团队里使用本书，可以先用第1章的边界样本做内部校准，再进入具体技术选型。术语一致后，平台建设会少很多无效争论。

1.13 边界判断的验收证据

Agent 边界判断需要验收证据。团队不能只说某个系统“已经是 Agent”，而要能展示目标、上下文、决策、行动、反馈和责任记录。若系统只能回答问题，没有可审计动作，就应归入 RAG 或 Copilot；若系统能发起工具调用，但缺少审批、回滚和 Trace，就还没有进入企业级生产边界。

验收时可以抽取几条真实任务链，检查用户意图如何转成计划，工具调用如何被授权，失败如何恢复，人工如何确认，最终产物如何进入下游流程。这样的证据会让概念边界服务工程判断，也为后续平台章节建立共同语言。

1.14 边界评审台账与后续追踪

边界评审不能只停留在一次会议结论。企业里同一个 Agent 需求会经历原型、灰度、上线、扩展和下线，边界也会随着工具接入、数据范围扩大、用户群变化而移动。第一章给出的 RAG、Copilot、Workflow、Agent 分类，应进入一份轻量台账，记录需求最初为什么被归到某一类、哪些证据支持这个判断、哪些条件变化后需要重新评审。台账不需要复杂系统，一张结构化记录就足够：任务目标、用户角色、系统动作、数据来源、工具副作用、人工节点、证据要求、当前形态、下一次复审时间。

这份台账能解决一个常见问题：原型阶段被判定为 Copilot 的能力，后续逐渐接入工具、审批和自动写入，却没有重新进入 Agent 评审。比如一个合同摘要助手最初只生成可编辑草稿，风险很低；几个月后它接入合同库、风险条款库和审批草稿工具，开始影响法务工作流。若团队仍按 Copilot 管理，就会缺少 Tool Registry、HITL、Trace 和权限复核。台账中的触发条件可以提醒团队重新分类：新增写操作、接入敏感数据、结果进入正式流程、用户范围扩大、自动化比例上升，都应触发边界复审。

边界台账还应保留被拒绝和被降级的需求。一个需求没有进入 Agent 形态，可能是因为任务路径稳定，适合 Workflow；也可能是因为证据不足，只能先做 RAG 或 Copilot。把这些结论留下来，后续业务再次提出同类需求时，团队能看到之前的判断依据和缺口，而不是重新争论术语。被降级的需求也会反向推动平台建设：缺 Trace，就补运行记录；缺权限模型，就补策略；缺评测样本，就补质量门禁。这样边界评审不会变成阻拦创新的流程，而会变成平台成熟度的反馈入口。

台账还要和后续章节衔接。第22章的 Runtime 可以读取任务形态决定状态机复杂度；第23章的 Registry 可以根据风险等级设置工具准入；第30章的 HITL 可以根据人工节点定义审批语义；第38章的 Trace 可以按证据要求决定记录粒度；第50章和第51章可以根据数据和动作边界设置安全样本。第一章的概念边界一旦进入台账，就能转成后续章节的工程输入。读者在自己的项目里也可以用同样方法：先记录边界，再根据边界决定需要哪些平台能力。

1.15 边界判断的反例复盘

理解 Agent 边界时，反例比定义更有用。很多项目失败并非模型回答能力不足，而是团队把普通自动化、检索问答或流程编排包装成 Agent，又没有补齐行动责任、状态恢复和审计证据。演示阶段看起来顺畅，生产阶段却会在写操作、审批、权限和异常路径上暴露缺口。第1章需要提醒读者：判断一个系统是不是 Agent，不能只看界面是不是对话式，也不能只看是否调用了模型。

反例复盘可以从任务后果开始。一个系统只检索政策并生成摘要，通常属于知识问答；一个系统根据固定规则流转审批，通常属于 Workflow；一个系统能解释下一步建议，但不会自动执行，可能是 Copilot；一个系统能选择工具、发起动作、处理失败并保留证据，才进入 Agent 边界。若系统会改变业务状态，却没有 Runtime、Policy、HITL 和 Trace，就属于边界设计不足，而不是“还缺几个功能”。

反例还可以帮助团队收敛范围。早期项目可以先停在 Copilot 或 Workflow 形态，不必强行升级为 Agent。对于风险高、证据不足、责任不清的任务，先让系统给建议和草稿，人工确认后再执行；等工具契约、权限、评测和恢复链路稳定后，再扩大自动化范围。这个节奏能减少试点失败，也能让平台建设有明确顺序。

早期可以要求每个 Agent 立项都写一段反例说明：为什么它不是普通 RAG，为什么固定 Workflow 不够，哪些动作需要模型参与决策，哪些动作必须人工确认。反例说明会迫使团队把边界讲清楚，也为后续章节的 Runtime、Tool Registry、HITL 和 Trace 铺好入口。

1.16 Agent 边界的反例复盘

理解 Agent 边界，最有效的方式之一是复盘反例。很多团队第一次做 Agent，会把一次顺畅演示当成能力成立：用户提问，模型调用工具，页面返回结果。真正上线后，问题往往出在演示没有覆盖的地方。模型是否替用户做了不可逆决策，工具是否产生副作用，回答是否有证据，失败后谁负责恢复，这些才决定系统能否进入企业流程。

反例复盘可以从三类样本开始。第一类是“看起来完成了，但责任不清”的样本，例如 Agent 自动发送报告，却没有确认接收者和权限。第二类是“答案正确，但证据不足”的样本，例如模型给出合规建议，却无法说明引用了哪个制度版本。第三类是“流程顺畅，但无法审计”的样本，例如工具调用成功，Trace 却没有保存参数、审批和输出 artifact。每一类样本都能把 Agent 与 Copilot、Workflow、RAG 的边界讲清楚。

早期平台可以把这些反例放进准入材料。一个新 Agent 上线前，团队先回答它会不会替用户行动，行动是否有副作用，证据是否可追踪，失败是否可恢复，责任 owner 是否明确。若这些问题没有答案，就应停留在助手或工作流增强阶段。这样全书后续讨论的 Runtime、工具、Memory、HITL、Trace 和 Guardrails，都会回到同一条边界线。

1.17 Agent 边界的运行证据

Agent 边界进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把决策主体、工具副作用、审批点、执行回执和审计记录记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第22章 Runtime、第30章 HITL 和第50章安全相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括演示阶段任务看似完成，生产阶段却无法证明谁做了决策、谁批准了副作用。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

Agent 边界应通过运行证据确认，帮助读者区分交互体验和责任转移。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

本章小结

Agent 不是大模型应用的总称。它是一类围绕任务目标组织感知、决策、行动和反馈的系统。RAG、Copilot、Workflow 和 Agent 各有边界，企业项目里的许多问题看起来像模型能力不足，根源常在需求分类一开始就做错了。企业级 Agent 的难点不在于让系统更像人，而在于让系统知道哪些动作可以自动完成，哪些动作需要确认，哪些动作必须留下证据。本书从平台讲起，也是因为系统一旦能在企业里推进任务，问题就会进入运行、权限、审计和治理层，无法停留在模型层。下一章会继续讨论平台边界：企业建设的是一组 Agent 共享的基础设施，而非孤立 Agent。应用、框架和低代码工具都可以参与其中，平台层仍要承担模型接入、工具治理、运行状态、评测、安全和审计责任。

参考文献

Yao, S. et al. (2023). ReAct: Synergizing Reasoning and Acting in Language Models. ICLR.

Schick, T. et al. (2023). Toolformer: Language Models Can Teach Themselves to Use Tools. NeurIPS.

Russell, S. & Norvig, P. (2020). Artificial Intelligence: A Modern Approach. Pearson.

OpenAI. (n.d.). Function calling guide.

第2章 企业级 Agent 平台的边界

场景引入

第一个 Agent 通常由业务团队自己推进：找一个场景，接几个工具，做出能演示的闭环。第二个、第三个 Agent 出现后，问题会变成平台问题。报价 Agent、经营分析 Agent 和工单 Agent 可能都在调用模型、读取客户数据、写入业务系统，却没有统一的身份、权限、审计和成本口径。平台的价值不在“再做一个更大的 Agent”，而在把这些共性能力收回到同一条治理线上。图 2-1 展示的是这个边界：业务 Agent 可以不同，底层模型、数据、工具、流程和治理能力需要进入统一契约。

第一年做 Agent，很多企业会感觉进展很快。制造板块用一个报价 Agent 跑通了合同查询和报价草稿，零售板块用经营分析 Agent 生成周会材料，客服中心用工单 Agent 做摘要和分派建议，财务共享中心用票据 Agent 做发票识别和凭证草稿。每个项目都能展示价值，业务负责人也能说出节省了多少时间。第二年，问题开始从单点效果转向共同责任。安全团队问：哪些 Agent 可以读取客户明细，哪些只能看汇总？财务团队问：模型调用成本算到哪个部门，临时分析和正式报告用的是不是同一套指标？平台团队问：如果一个 Agent 调错工具，能不能按 run_id 找到当时的输入、模型版本、工具参数和审批状态？业务团队则问得更直接：为什么同样问“销售额”，不同 Agent 给出的口径不一样？

这些问题很难归因于某个应用写得不够好。多个应用同时运行后，系统问题一定会浮出水面。第一个 Agent 可以靠项目组经验撑住，第二个还能靠几位核心工程师记住约定，到了十几个 Agent 同时接入时，口头规则就会失效。工具是谁注册的，权限谁审批，日志写到哪里，失败后谁值班，模型升级影响哪些场景，这些都需要稳定的公共机制。平台由此出现。它不会把所有业务逻辑收走，也不会替业务团队做产品决策。平台要做的是把重复出现、影响权限和成本、关系到审计与恢复的能力沉淀下来，让每个业务 Agent 在相同的底线上运行。业务可以有不同节奏，底层的模型访问、工具契约、运行状态、trace 字段、评估样本和审批策略需要保持一致。

图2-1：多 Agent 共享平台边界。来源：本书自绘。Alt text：上层是报价、经营分析、工单、票据等面向不同任务的业务 Agent，下层是模型、数据、工具、流程、治理五类共享能力，箭头表示所有业务 Agent 都通过统一平台层访问这些能力。

业务 Agent 可以面向不同任务，但模型、数据、工具、流程和治理能力必须沉淀到统一平台层。读者在阅读本章时要避免一个误解：平台边界不是组织架构图，也不是采购清单。它是一套“哪些责任必须统一承担”的判断方法。后续章节会介绍模型网关、Tool Registry、Runtime、Trace、Eval、Guardrails 等组件，但这些组件只有在承担统一责任时才构成平台；如果只是各项目的局部实现，就仍然只是应用内部能力。

本章会把三个层次分开：Agent 应用解决某个具体业务任务，Agent 框架帮助工程师编排单个 Agent，Agent 平台负责让多个 Agent 共享基础能力并接受同一套约束。这个区分很重要。企业可以允许应用团队选不同框架，也可以允许不同业务域保留自己的策略；但只要涉及模型入口、工具注册、权限审批、运行记录和评估回放，就必须有统一契约。否则平台只是名字，企业仍然在运行一组互不相认的试点。平台也有反向边界。平台太薄，会退化成模型代理；平台太厚，又会把业务规则吞进公共层，最后每次改折扣、改工单优先级、改报表模板都要等平台排期。合理的平台只在必须统一的地方强约束，在业务变化快、试错频繁的地方留出插槽。本章讨论平台边界，就是为了让后续的组件设计有判断标准。

2.1 平台化能力与孤立 Agent 的差异

单个 Agent 从“回答”走向“执行”时，问题主要集中在任务边界、工具调用和责任归属上。视角再往上抬一层，如果一家多业务线企业先做报价助手，随后又做经营分析 Agent、工单 Agent、票据 Agent，新的矛盾会很快出现。直觉上，这应该是一件好事。企业找到了 AI 落地的多个切口，每个团队都在形成自己的成果。现实却常常相反。一家多业务线企业第一年做了四个试点。制造板块的报价 Agent 负责读合同、看库存、生成报价草稿；零售板块的经营分析 Agent 负责问数、找异常、写复盘；客服中心的工单 Agent 负责总结投诉、建议处置动作；财务共享中心的票据 Agent 负责识别发票、匹配订单、生成凭证草稿。

四个试点都证明了“单点可行”。困难出现在集团想把这些能力纳入统一治理之后。平台负责人很快会问一串问题：哪些 Agent 能访问客户身份信息？哪些工具会产生真实业务副作用？哪个模型用得最多、最贵、最容易出错？哪些 Agent 必须接审批，哪些可以自动执行？一个任务出错后，系统能否完整回放它的决策过程？如果这些问题没有统一答案，企业其实还没有进入平台阶段，只是拥有了一组彼此割裂的智能项目。单点 Agent 做出来以后，治理问题会集中到一处：怎样让一组 Agent 在同一套规则下长期运行。

2.2 应用、框架、平台：三层边界与平台化风险

Agent 领域里最常见的概念误用，就是把应用、框架、平台混在一起谈。它们相关，但并不处在同一层。

表2-1：Agent 应用、框架与平台三层各自解决的问题。来源：本书整理。

框架关注的是“如何把一个 Agent 写出来”；平台关注的是“如何让很多 Agent 在企业里长期存在，同时避免彼此打架、重复造轮子和失去治理能力”。企业可以同时坚持两条原则：应用团队可以自由选择合适的框架，所有 Agent 也必须走统一的平台契约。这两句话并不冲突。平台不替代框架，它承接的是框架之上的企业复杂度。低代码工具、Agent Studio、可视化流程编辑器之类的产品，也需要放回这个三层结构里看。它们可能很好地解决了“搭一个 Agent 应用很快”的问题，但这不自动等于它们解决了平台问题。判断一个产品或内部系统是否进入平台层，重点不在控制台或拖拽能力，而在它是否回答得了三类问题：多个 Agent 的模型调用如何统一管理，工具能力如何统一定义、分级和版本化，权限、审批、trace、评估如何统一接入。如果这些问题还停留在“各项目自己处理”，系统仍处在应用集合阶段，还谈不上平台。

2.3 平台管理的五类共性问题：模型、数据、工具、流程、治理

企业级 Agent 平台看起来像一堆组件，实际管理的是五类共性问题。模型问题决定调用哪个模型、怎样路由、如何限流、如何归集成本；数据问题决定能看哪些数据、使用哪套口径、以什么身份访问、如何脱敏；工具问题决定有哪些能力、谁能调用、参数是否合法、动作是否会产生副作用；流程问题决定什么可以自动执行、什么必须等待人工、长任务失败后怎样恢复；治理问题决定如何评估、记录、回放、审计和持续改进。把平台理解成“五类共性问题的统一解法”，比理解成“八个模块的集合”更接近企业现实。企业通常不是先有架构图，再长出问题；更常见的路径是重复问题先出现，平台随后被逼出来。

一家多业务线企业前四个试点为什么很快碰到平台问题？因为它们虽然业务不同，但这五类问题几乎完全相同：都要调模型，都要读数据或文档，都要调用工具，都要判断风险，都要在出错后被解释和复盘。很多企业在这一点上会联想到自己曾经做过的数据中台、技术中台、能力中台。这个联想并不奇怪，但需要格外小心。数据平台关注的是数据资产的汇聚、治理和使用；应用平台关注的是研发效率和服务复用；而 Agent 平台关注的是以模型为决策核心的任务执行链路。它会借用数据平台和应用平台的资产，但自己承担的是另一类问题：模型决策、工具副作用、人工审批、任务回放、版本评估。图 2-2 将这些问题收束为模型、数据、工具、流程和治理五类能力，它们共同决定企业级 Agent 能否从单点试点走向长期运行。

图2-2：平台管理的五类共性问题。来源：本书自绘。Alt text：模型、数据、工具、流程、治理五个并列区块，每个区块下列出对应的共性问题（如模型的路由与成本、工具的权限与副作用、治理的审批与回放），表示这些问题在多个业务 Agent 间重复出现、应由平台统一承接。

2.4 平台边界划分：统一能力与业务自主权

接受“平台是在统一解决共性问题”以后，下一个实际问题就来了：哪些能力应该由平台负责，哪些能力仍应留在应用层？这里没有放之四海而皆准的规则。比较可靠的做法，是先问四个问题：

1. 这个能力会不会跨多个 Agent 重复使用？
2. 它会不会影响权限、成本、审计或评估？
3. 它是不是依赖某个业务域的特殊规则？
4. 平台化它，会不会降低后续接入成本？

这四个问题是划分平台责任的入口。表 2-2 用常见能力做例子，说明哪些能力应收归平台，哪些能力更适合留在业务侧。评审时不要只把它们当成形式化 checklist，而要看能力归属改变后，后续权限、成本、审计和运维责任会怎样变化。

表2-2：常见能力更适合归平台还是留给业务及其原因。来源：本书整理。

平台边界没有“越大越好”或“越薄越现代”的固定答案。平台太薄，会退化成模型网关；平台太厚，又会吞掉业务逻辑。成熟平台通常只在需要统一的地方强约束，在允许差异的地方提供插槽。还有一个常被低估的判断维度：变化速度。如果一类能力变化极快、试错频繁、又高度依赖具体业务反馈，过早平台化反而会拖慢业务创新；相反，如果一类能力变化相对慢，却需要稳定一致地被复用，越早平台化越好。

2.4.1 平台化建设的触发条件

并不是每家企业一做两个 Agent 就要成立平台团队。更务实的判断方式，是看企业是否已经出现以下三个信号。

表2-3：提示该把能力收归平台的几个信号及其含义。来源：本书整理。

只要这三个信号同时出现，平台化就已经从可选项变成基础条件；继续放任各团队各自建设，会拖垮后续落地效率。很多企业会有一个错觉：前两个试点做得很顺，第三个开始突然变慢。原因很直接：前两个项目还能靠“各做各的”推进；从第三个项目开始，基础设施和治理成本就会集中爆发。预算审批会追问模型账单归谁，安全团队会追问谁能访问什么数据，业务团队会追问为什么同样的问题不同 Agent 给出不同结论。平台就是在这种压力下被逼出来的。

2.5 平台采用：协作机制、准入流程与治理委员会

企业里谈平台，除了技术边界，还要谈责任边界。平台一旦存在，很多原来分散在各团队手里的决策权都会重新分配。进入平台阶段后，很多决策主体会发生变化。模型选择要进入平台策略，应用提出需求和约束；工具接入要先进入统一契约，业务补充领域细节；高风险动作由平台和安全共同定义审批规则，不能只靠业务团队口头约定；trace 要统一 run 语义和字段口径，避免各写各的日志；版本好坏要由平台与业务共同维护评测口径，而非靠演示印象判断。这组变化指向一个现实问题：平台不是一个“大家都喜欢的公共服务中心”。它会重新分配标准制定权、准入权和部分发布权。因此，平台建设既是技术工程，也是组织协商。平台团队常遇到的阻力不只来自技术。业务团队担心平台让接入变慢、限制灵活性、把快速试错拉进统一流程；安全与治理团队担心平台集中放大风险、给系统过大的决策权、制造新的审计黑箱。成熟的平台团队要同时回答这两边的问题：接入效率要保住，边界也要管住。

2.5.1 新 Agent 的平台准入流程

平台一旦成立，除了给已有项目复用，还要面对一个现实问题：新的业务团队如何接入？一个可执行的最小准入流程，至少包括五步。

表2-4：Agent 准入评审各步骤要回答的问题。来源：本书整理。

这五步看起来是在加门槛，实际是在降低后续代价。平台需要准入流程，目的在于防止每个新 Agent 都重新制造技术债，而非让业务团队排队。从企业沟通的角度说，这五步也承担了翻译层作用。它把业务方口中的“我想做一个智能助手”，翻译成平台团队能接住的问题：任务边界是什么、工具清单是什么、风险等级是什么、如何验收、是否走统一运行链路。新 Agent 从任务定义到生产监控，需要经过工具审查、风险分级、评测准备和运行接入等共同门槛。

图2-3：平台准入与治理机制。来源：本书自绘。Alt text：一条从左到右的准入流程，业务 Agent 按风险分级走不同路径，低风险走标准准入，中风险由平台与安全联合评审，高风险进入治理委员会，右侧汇入统一的上线与持续治理环节。

2.5.2 平台治理委员会的边界

当企业只有一两个 Agent 试点时，很多决策可以靠项目组临时协商。但当一家多业务线企业同时推进经营分析、报价、客服质检、财务票据、知识助手等多个场景时，临时协商很快会失效。这时需要一个轻量但正式的治理机制。可以叫平台治理委员会，也可以叫 AI 平台评审会，名字不重要，职责是回答三类问题。治理机制通常要稳定处理三类决策。第一类是准入决策：哪些 Agent 可以进入生产，哪些只能留在试点，平台、业务、产品和安全都要参与。第二类是风险决策：哪些动作必须审批，哪些动作禁止自动执行，这需要平台、安全、法务和内控共同确定。第三类是路线决策：哪些能力沉到平台，哪些仍留在应用，需要平台、架构、数据和业务一起判断。

治理委员会的价值，是让决策口径稳定。否则，A 部门的 Agent 可以自动发客户邮件，B 部门却连内部通知都不允许；一个场景的 trace 要求很严格，另一个场景完全不记录；一个团队能接高风险工具，另一个团队被要求重做评审。这样的不一致会迅速消耗平台信用。治理机制如果变成沉重审批，业务团队会绕开平台。它应重点处理跨场景、跨部门、涉及责任边界的问题，不应干预每个提示词、每个页面、每个业务文案。治理委员会负责评审企业 Agent 的边界，不承担产品评审会或代码评审会的职责。

2.6 长期运营：反向边界、成本、目录与成熟度

定义平台边界时，很多团队只写平台“应该提供什么”。这还不够。成熟平台还要清楚说明自己“不应该做什么”。否则平台会不断膨胀，拖慢业务，还会背上不该背的责任。平台替业务团队定义业务目标，会造成责任错位。经营分析 Agent 到底服务周会、月会还是专项复盘，报价 Agent 到底服务大客户销售还是渠道销售，这些目标应由业务和产品定义。平台可以提供任务模板和评审方法，但不能替业务判断什么最重要。平台吞掉所有业务规则，也会让公共层被业务变化拖垮。折扣策略、客服质检细则、财务报销口径、法务条款偏好，都有强烈的业务域属性。平台可以要求这些规则以可治理的方式接入，但不应把它们全部写进平台核心。

同样，平台不宜把所有场景都拉进统一节奏。低风险探索场景需要快，高风险生产场景需要稳。平台应该提供分级路径，避免用同一套流程管理所有项目。平台也不宜替代旧有企业平台。数据平台、身份平台、审批平台、服务治理平台仍然有自己的职责。Agent 平台应该连接和增强它们，避免另起一套完全平行的系统。平台以治理之名消灭创新，业务方最终会选择绕开平台。早期 Agent 场景必然有试错。平台要管住生产边界，也要给沙盒、试点和低风险探索留下空间。

表2-5：平台不该做的事、越界后果与更合理的边界。来源：本书整理。

因此，平台成熟度不取决于组件数量，而取决于它是否清楚自己该负责什么、不该负责什么。边界说不清的平台，很容易一边重复建设基础能力，一边把业务变化压进公共层。

2.6.1 平台运营：上线以后才进入长期管理

很多企业把平台建设理解成“交付一组能力”。Agent 平台更接近长期运营系统，而非一次性交付物。原因很直接：Agent 的运行环境会不断变化。模型版本会变，业务规则会变，工具接口会变，数据口径会变，用户使用方式也会变。一个今天表现稳定的 Agent，三个月后可能因为促销规则更新、指标口径调整或模型升级而表现下降。没有平台运营，系统会慢慢失真。平台运营至少包括五类工作。场景运营要持续跟踪哪些 Agent 被使用、哪些需求应该合并或下线；质量运营要更新评估样本、沉淀失败案例、分类用户反馈；成本运营要看模型调用、任务成本、部门预算和收益关系；风险运营要定期复查高风险工具、审批策略和敏感数据访问；生态运营要维护文档、模板、培训、样例和支持机制。

一家多业务线企业如果第一年做了四个 Agent，第二年做了二十个，那么平台运营会变得比平台建设更重要。因为从这个阶段开始，企业面对的问题从“有没有能力”变成“这么多能力是否仍然可信、可控、值得继续存在”。平台运营还会改变团队的日常工作方式。早期项目组关注的是把一个场景做出来，运营阶段关注的是哪些场景应该继续投入、哪些场景应该降级、哪些工具应该下线、哪些提示词和评测样本需要更新。一个报价 Agent 如果半年没有产生有效草稿，却持续消耗模型调用和人工复核资源，就不该因为“已经上线”而继续占用平台配额。一个经营分析 Agent 如果每周都被用户修改同一类口径说明，平台就要把这类反馈回写到语义层和模板，而非让用户反复纠正。

这也是平台目录的重要性。企业需要知道当前有哪些 Agent，分别服务哪些业务流程，调用哪些工具，属于什么风险等级，由谁负责运营，最近一次评估是什么时候。没有目录，平台团队只能被动响应事故；有了目录，才能主动发现重复建设、低使用率、高成本和高风险场景。平台目录要让每个 Agent 都有可追踪的责任归属和生命周期，不能只是展示一批 Agent 的静态页面。目录还要和准入、监控、成本视图连在一起。一个 Agent 新接入高风险工具时，目录中的风险等级要同步变化；一个 Agent 长期失败率升高时，目录应提示负责人复查；一个部门反复建设相似能力时，平台团队也能据此推动复用。没有这些运营动作，目录就会退化成静态清单。

2.6.2 供应商和外部产品的接入条件

大多数企业不会完全自研所有 Agent 能力。一家多业务线企业可能采购知识库产品、客服质检产品、模型网关产品，也可能引入行业解决方案。关键问题不在于能不能采购，而在于采购产品能不能纳入统一平台边界。外部产品接入 Agent 平台时，至少要看六件事：是否支持统一身份和权限，是否支持工具和数据访问边界，是否支持 trace 或导出关键运行记录，是否能纳入评估机制，是否能纳入成本视图，是否允许企业掌握关键配置和治理策略。这才是“混合路线”的含义。无论采购还是自研，都要进入同一套平台契约。供应商产品可以成为平台生态的一部分，但要避免变成治理孤岛。

2.7 平台运营模型与责任分工

平台边界写清以后，还要落到日常运营模型。很多企业在平台建设初期会把工作全部压给平台团队：模型接入找平台，工具接入找平台，评测报表找平台，出了事故也找平台。这样做短期看起来集中，长期会让平台团队变成所有业务 Agent 的交付和背锅中心。更合理的方式，是把平台运营拆成平台责任、业务责任、数据责任和安全责任。平台团队负责统一入口、运行证据、公共工具契约、评测框架和发布门禁；业务团队负责场景目标、验收样本、运营指标和用户反馈；数据团队负责口径、权限、质量和血缘；安全、法务和内控团队负责策略、审批和审计要求。

这种分工要写进 Agent 的生命周期。需求进入平台前，业务团队要说明任务目标和验收方式，平台团队负责判断是否已有可复用能力，数据团队确认数据和口径是否可用，安全团队判断风险等级。开发阶段，平台团队提供 Runtime、Gateway、Registry、Trace 和 Eval 接入方式，业务团队补充领域规则和样本，数据团队提供语义层和权限配置。上线阶段，平台检查运行证据、评测结果、审批策略和回滚方案，业务团队确认产物能否进入真实流程。运营阶段，平台看质量、成本和风险趋势，业务团队看使用率、产出质量和用户反馈，数据团队处理口径和质量变化，安全团队复查高风险动作。

责任分工还要有退出机制。一个 Agent 进入平台目录以后，并不意味着它永久存在。低使用率、持续高成本、长期无人维护、风险等级升高但无人接管，都是下线或降级信号。平台应支持把生产 Agent 降级成试点，把自动执行改成人工确认，把高风险工具临时冻结，把长期无效场景从目录中退役。没有退出机制的平台，会不断积累历史包袱。企业要把 Agent 当成需要运营的能力，而不是一次上线后就固定不变的功能。

2.8 平台边界的落地判断

企业级 Agent 平台的边界不能只靠组织架构划分。更可靠的判断方式，是看某项能力是否需要跨业务复用，是否承载风险，是否需要统一证据，是否会影响成本和稳定性。模型路由、工具登记、运行状态、权限策略、Trace、评测和发布门禁，都符合这些条件，应该进入平台层。业务流程、行业规则、验收样本和运营目标，则应由业务团队负责。平台过薄会导致每个 Agent 重复建设。业务团队会各自接模型、写工具、存日志、做审批，短期看很快，长期会在权限、成本和事故复盘上付出代价。平台过厚也有问题：如果平台团队试图接管所有业务逻辑，交付会变慢，业务差异也会被抹平。合适的边界，是平台管住不可妥协的工程责任，给业务留下可配置和可扩展空间。后续章节的分层都服务这个判断。模型层解决能力和成本，数据层解决可信上下文，Agent 能力层解决运行和动作，DataAgent 主线把这些能力串成任务，可观测和安全章节负责上线后的治理。读者可以把本章作为全书的边界检查表：每引入一项能力，都要问它应属于平台、业务应用，还是外部生态。

2.9 早期平台的采用节奏

早期企业 Agent 平台应先控制范围，再扩大能力。很多团队一开始就想统一所有模型、所有工具、所有业务流程，结果公共层还没有稳定，业务团队已经等不及绕开平台。更稳的节奏，是先把生产风险最高、跨场景复用最多的能力纳入统一边界：模型网关、工具登记、运行状态、Trace、基础评测、策略拦截和发布记录。业务应用仍然保留场景规则、交互方式和验收样本。这样平台先承担不可重复建设的工程责任，业务团队仍能根据自己的流程推进。

采用节奏还要和风险分级绑定。低风险知识问答可以走标准接入：统一身份、统一模型调用、引用记录和基本评测即可。中风险场景，例如报价草稿、经营分析和客服质检，需要补充工具审查、数据口径确认、人工确认节点和失败样本。高风险场景，例如自动发客户邮件、提交审批、修改主数据和财务处理，应进入正式评审，要求 Policy Engine、HITL、Trace、回滚和事故响应都可用。不同风险使用不同接入路径，平台才不会在低风险场景上过度消耗，也不会在高风险场景上留下缺口。

平台采用还需要一个清晰的迁移策略。已有 Agent 或供应商产品接入时，不必要求第一天就完全重构。可以先接统一身份和审计，再接模型网关和成本视图，然后接工具策略、评测和发布门禁。每一步迁移都应带来可见收益：权限更清楚、成本更可见、事故可回放、质量可比较、风险可拦截。若平台接入只增加流程负担，却没有改善运行证据，业务团队会把它看成审批系统而非基础设施。

退出和降级也属于采用节奏。一个 Agent 如果长期使用率低、人工退回率高、成本超过收益、负责人缺失或风险等级升高，就应从生产目录降级为试点，或者暂停高风险工具。平台要把这些规则写进运营机制，而不是等事故后才讨论。早期平台的成熟度，不在于覆盖多少场景，而在于每个进入平台的场景都有明确准入、证据、责任、降级和退出路径。

2.10 平台目录与年度复审

企业级 Agent 平台一旦进入多场景阶段，就需要平台目录来承接运营。目录应成为每个 Agent 的运行档案，而不是展示页。至少要记录业务 owner、平台 owner、数据 owner、风险等级、接入工具、使用模型、调用数据域、评测集版本、最近一次发布、最近一次复审、成本归属和退出条件。这样平台团队才能知道哪些 Agent 仍在被使用，哪些已经无人维护，哪些因为接入新工具而风险等级变化，哪些因为业务流程变化需要重新评估。

年度复审要看生命周期，而不只看功能是否仍能访问。一个知识助手如果长期没有用户、文档版本已经过期、owner 已经变更，就应退回试点或下线；一个 DataAgent 如果业务继续使用，但语义层版本、评测样本和权限策略已经变化，就需要重新跑准入检查；一个供应商 Agent 如果合同范围变化或日志无法导出，就应限制在低风险场景。目录把这些变化显性化，避免平台变成一堆历史项目的集合。

复审还要连接成本和责任。模型调用成本、工具执行成本、人工复核成本和事故处理成本，都应归到具体 Agent 和业务流程。若一个场景成本持续升高，却没有对应的业务采纳和质量提升，平台应推动降级或优化，而不是继续扩大使用范围。若一个高风险场景收益明显，但缺少 owner 或审批链不稳定，也不能因为业务价值高就放松准入。平台目录的价值在于让这些取舍有证据，而非靠会议印象。

早期可以先做轻量目录。每个进入生产的 Agent 都有一条记录，记录 owner、风险、工具、数据、评测、Trace 和退出条件；每季度更新一次使用、成本和事故情况；每年做一次正式复审。随着场景增多，目录再接入自动指标和平台控制台。目录建设不需要等完整平台完成，它本身就是平台边界落地的第一批治理资产。

2.11 平台采用节奏与业务自主权

平台化建设容易出现两种节奏失衡：平台团队一次性收走过多决策，业务团队觉得效率下降；业务团队继续各自搭建工具，平台只能事后补审计和成本治理。更稳定的采用节奏，是先把高风险、强共性的能力纳入平台，例如模型网关、工具注册、权限策略、Trace、Eval 和安全门禁；再把低风险、强业务差异的体验留给应用团队，例如页面布局、业务文案、局部流程配置和领域样本维护。这样平台提供统一边界，业务保留足够的迭代空间。

采用节奏还要和组织成熟度匹配。早期平台不必要求所有 Agent 都迁入统一框架，但应要求所有生产 Agent 遵守最低运行契约：模型从统一网关进入，工具通过 Registry 注册，高风险动作经过审批，Trace 能关联用户、工具和证据，安全样本进入发布门禁。满足这些契约后，业务团队可以继续保留自己的框架和界面。平台的价值体现在运行边界和复用能力，而不是把所有应用改造成同一套代码。

平台目录是采用节奏的管理工具。某个能力如果被多个业务重复实现，目录应推动其沉淀为共享能力；某个能力如果只有单一业务使用，且风险可控，可以继续留在应用侧；某个能力如果涉及敏感数据、写操作或外部披露，即使只有一个业务使用，也应进入平台治理。通过这种方式，平台边界会随着业务证据逐步扩展，而不会靠组织命令一次性划死。

2.12 平台边界的反向校验

平台边界还需要反向校验。不是所有能力都应该进入平台层。某些业务规则变化快、只服务一个团队、风险低、复用价值有限，放在应用侧更合适；某些能力涉及模型接入、工具权限、审计、评测、安全和成本，即使只有一个业务先使用，也应进入平台治理。判断边界时，要同时看复用性、风险、变更频率和责任归属。

反向校验可以避免平台过厚。平台如果把所有业务逻辑都收走，会拖慢业务迭代，也会让平台团队承担不该承担的业务判断；平台如果过薄，只提供模型网关，就无法治理工具、数据和运行状态。合适的边界应让平台承担共性风险和共性能力，让业务团队保留领域判断和体验创新。

每次新增平台能力，都应回答两个问题：它是否解决多个业务都会遇到的问题，它是否承接了单个业务无法独立承担的风险。如果答案都不成立，就先留在应用侧试验；如果答案成立，就进入平台目录、owner、SLO、评测和复审流程。这样平台边界会随着证据扩展，而不是随着组织偏好摆动。

2.13 平台边界的验收材料

平台边界要通过材料验收。一个能力是否应该进入平台，不看它是否被多个团队提到，而看它是否具备可复用契约、运行证据、owner、成本口径和退出方式。若一个工具只服务单一业务流程，规则变化快，且没有复用价值，就可以留在应用层；若多个业务场景都需要同类审批、Trace、评测或工具治理，就应进入平台层。

验收材料应记录能力来源、复用场景、依赖系统、数据和权限范围、SLO、成本归属、支持团队和下线条件。这样平台不会被试点需求无限拉宽，也不会把真正共性的治理能力留在各个应用里重复建设。

2.14 平台边界变更的运行证据

平台边界不会一次划定后长期不变。一个能力刚进入平台时，可能只是为了统一模型调用；随着业务接入工具、写操作、审批和外部用户，同一能力会逐步承担更多运行责任。边界变化需要证据支持。平台团队应保存能力进入平台前后的对比材料：业务团队原来如何接模型、如何记录工具调用、如何处理失败、如何统计成本；接入平台后，这些责任由哪些公共能力承接，哪些仍留在业务侧。没有这组证据，平台边界会变成组织口号，业务团队也难以理解为什么某些能力要迁入平台。

边界变更还要记录触发原因。常见触发包括多业务重复建设、工具权限风险上升、成本归因不清、审计要求变化、故障复盘缺少 Trace、供应商能力更替和安全策略调整。每次触发都应对应一个明确动作：沉淀共享工具、收口模型路由、补充评测门禁、增加人工审批、冻结高风险能力或退回应用侧试验。这样平台扩张和收缩都有依据，不会因为一次会议决定就改变工程责任。

早期平台可以把边界变更写入目录复审。每个季度检查哪些能力从应用侧进入平台，哪些能力继续留在业务侧，哪些平台能力因低使用率或责任不清需要退役。复审材料要能回答：这次边界变化减少了哪些重复建设，降低了哪些风险，增加了哪些平台维护成本，后续由谁负责。平台化的成熟度，体现在边界能随证据调整，而不是体现在平台一次性覆盖所有能力。

2.15 平台边界争议的复盘方法

平台建设进入多个业务团队后，边界争议会反复出现。业务团队可能认为平台管得太细，影响交付速度；平台团队可能认为业务绕过统一入口，带来安全和运维风险；安全、法务和财务团队又会从权限、数据出域和成本归集角度提出要求。第2章需要给读者一个判断方法：边界争议不能靠“谁拥有更多资源”解决，要回到任务链路、风险后果和复用价值。

复盘时可以先把争议拆成三类。第一类是执行责任争议，例如某个工具调用失败后由业务修还是平台修；第二类是治理责任争议，例如审批、审计和权限策略由谁维护；第三类是资产责任争议，例如 Prompt 模板、评测样本、Trace 和运行台账归谁管理。不同争议对应不同材料。执行责任看接口契约和运行日志，治理责任看合规要求和风险等级，资产责任看复用范围和迁移成本。

平台边界复盘还要避免把所有能力都收进平台。共享能力进入平台会降低重复建设，但也会引入排队、发布门禁和跨团队协调成本。业务侧保留自主空间，可以加快局部试验，但要接受平台对高风险动作、运行证据和公共资产的约束。早期平台可以先要求业务团队接入 Runtime、Registry、Trace 和 Policy，至于 UI、场景流程和低风险 Prompt 模板，可以保留在业务应用内迭代。

边界争议的结论应形成可执行动作。某个能力迁入平台，要写清接入入口、owner、SLO、迁移窗口和退役路径；某个能力留在业务侧，要写清平台保留的审计接口、评测样本和安全限制；某个能力暂时观察，要写清触发迁移的阈值。这样企业级 Agent 平台的边界不会停留在组织口号，而会随着运行证据逐步稳定。

2.16 平台边界的读者预期管理

读者进入本书时，容易把企业级 Agent 平台理解成“把常见 Agent 功能集合起来”。这会低估平台化的难度。平台边界首先是一组责任划分：哪些能力由平台统一提供，哪些能力留给业务团队配置，哪些动作必须进入审批和审计，哪些能力暂时只允许试点。边界清楚后，后续章节里的 Runtime、工具、Memory、DataAgent、观测、部署和治理才有共同语境。

本书后续不会把每个章节都写成独立功能介绍。模型推理章节服务于成本、延迟和路由；数据基础设施章节服务于可查、可证和可控；Agent 能力章节服务于任务执行；观测和评测章节服务于复盘和发布；安全组织章节服务于责任和风险。读者可以把平台边界当作全书主线：每新增一个能力，都要问它归谁维护、怎样验证、失败后怎样恢复、是否可以下线。

早期平台不需要覆盖所有能力，但需要保留扩展位置。一个团队可以先统一模型网关、工具注册、Trace 和评测样本，再逐步纳入 Memory、HITL、DataAgent 和多模态入口。边界管理的价值在于让平台建设有节奏，而不是让每个业务场景重新发明一套不兼容的 Agent 运行方式。

2.17 平台边界的组织确认

企业级 Agent 平台进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把能力目录、共享底座、业务 owner、安全门禁和运营证据记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第22章 Runtime、第50章安全和第53章组织治理相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括平台团队承接所有业务逻辑、业务团队绕开统一底座、安全团队只在上线前出现。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

平台边界应写入准入规则和运营节奏，让每类能力有 owner 和复审方式。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

2.18 平台建设的阶段性边界

企业级 Agent 平台不需要第一天就覆盖所有能力。更稳妥的节奏是先选少量高价值场景，验证 Runtime、工具、Trace、Eval、人工复核和安全策略能共同运行；再把可复用能力抽到平台层；最后开放更多业务团队自助接入。每个阶段的边界不同，不能用同一套成熟度要求管理探索和生产。

探索阶段允许快速试错，但必须有数据和工具边界。生产阶段要求发布证据、owner、SLO、成本归因和事故路径。规模化阶段才适合强调模板、标准库、治理委员会和组合管理。若顺序反过来，平台会过早承担复杂流程；若长期停在探索阶段，业务会积累大量无法治理的 Agent。

早期读者应带着阶段意识看后续章节。不是每家公司都需要立刻实现所有模块，但每家公司都需要知道哪些能力缺失会阻止生产化。章节的目的，是帮助团队识别当前阶段的最小平台边界和下一步补齐顺序。

本章小结

企业的难点不止是写出一个 Agent，还包括管理一组 Agent。应用、框架、平台处在三层；混在一起讨论，后续建设目标会很快变形。平台管理模型、数据、工具、流程、治理五类共性问题。边界不能薄到只剩模型网关，也不能厚到吞掉业务逻辑。该统一的地方强约束，该允许差异的地方留空间。多 Agent 阶段会把标准、准入、责任和运营口径推到台前。下一章继续讨论“AI 原生业务系统”和“在旧系统里加 AI 功能”的差别。

参考文献

NIST. (2023). Artificial Intelligence Risk Management Framework (AI RMF 1.0).

OWASP. (n.d.). Top 10 for Large Language Model Applications.

Model Context Protocol. (n.d.). Specification and documentation.

Kubernetes. (n.d.). Documentation.

补充：统一规则引擎与七层审核链

企业级 Agent 平台的安全核心是统一规则引擎和七层审核链。这两个机制确保所有业务操作在执行前经过完整的安全校验。

统一规则引擎

统一规则引擎是一个约 200 行的 Python 核心组件，从 business_rules 配置表读取规则并执行。它不包含任何业务逻辑，仅做三件事：

• 规则加载：从配置表读取规则定义（条件、动作、优先级）
• 规则执行：按优先级匹配条件，执行拦截或告警
• 审计记录：记录每次规则执行的输入、输出和结果

规则分为两类：bypass=false 的安全规则（阻断操作，不可训练）和 bypass=true 的业务参数（记录告警，可训练调整）。这种分类确保了安全底线不可逾越，同时业务参数保持灵活可调。

七层审核链

所有业务操作必经七层审核，每层校验一种安全维度：

关键原则：七层审核链不可绕过、不可跳层、不可训练修改。它是平台的安全底线，所有 Agent 的业务操作必须逐层通过。

模块独立性

平台采用模块独立设计：每个 Agent 模块可独立启用或停用（通过 module_toggles 配置），任何一个模块的故障不影响其他模块的正常运行。这种设计确保了系统的容错能力——即使某个 Agent 未激活或出现异常，其他 Agent 仍能正常处理业务。

第3章 AI 原生业务系统：Agent 重塑企业软件

场景引入

一家企业已经给 BI、CRM、ERP 和工单系统都加上了 AI 功能。单看每个系统，问数、摘要、异常提示都比过去方便；但经营分析会前，负责人仍要在多个系统之间切换，自己拼数据、找原因、写材料。AI 被加进了旧页面，任务却仍然靠人串起来。AI 原生业务系统要改变的是这个分工。用户不再从某个页面开始操作，而是把“准备经营分析”“处理客户投诉”“生成报价材料”这类任务交给系统，由 Agent 编排底层工具。图 3-1 对比的正是旧系统加 AI 与任务中心系统之间的差别。

过去几年，很多企业软件都增加了 AI 入口。BI 页面多了自然语言问数，CRM 页面能总结客户近况，ERP 页面能提示库存异常，工单系统能自动归类投诉，知识库能做语义搜索。单看每个功能，它们都能节省时间，也确实改善了局部体验。但到了真实工作现场，用户仍然要自己决定先看哪个系统、再查哪张表、把哪个结论写进材料、哪些问题需要找人确认。经营分析会是一个典型例子。周五下午，运营负责人要准备下周一的材料。他先在 BI 里看销售和毛利，再到库存系统查缺货，再到客服系统看投诉，再翻上月促销复盘，最后把数据、图表和解释拼成一份 PPT。每个系统旁边都有 AI 助手，但这些助手只对自己所在页面负责。BI 助手不知道库存是否断货，工单助手不知道促销节奏，知识库助手也不会把查询结果写进会议材料。人还是那条任务链的编排者。

AI 原生业务系统要改的是这件事。用户从“打开某个页面并完成某个操作”，转向“提出一个任务并管理任务执行”。系统收到“准备华东区经营分析材料”以后，需要确认时间范围和指标口径，调用 BI、库存、客服、知识库等工具，发现冲突时暂停让用户选择，最后输出带证据的图表、结论和待办。旧系统没有消失，它们变成可调用的工具；用户也没有退出责任链，而是把精力放在目标、约束、确认和裁决上。这个变化容易被低估，因为界面上看起来可能只是多了一个对话框。但真正发生变化的是系统组织原则。传统企业软件以页面和模块为中心，把用户训练成系统操作者；AI 原生软件以任务为中心，把用户放到任务发起者和结果确认者的位置。设计对象也从“这个按钮放在哪里”扩展到“这个任务现在处于什么状态、用了哪些证据、哪里需要人工确认、失败后怎样继续”。

AI 原生不会把所有旧系统推翻重做。ERP、CRM、BI、工单和财务系统仍然承载事实、规则、权限和事务一致性。Agent 要在允许范围内调用这些系统，把原来由人手工串联的步骤组织成可观察、可接管、可审计的任务链。本章讨论 AI 原生业务系统，重点就在于这次分工变化：旧系统继续保存企业事实，Agent 负责围绕任务重新编排能力，用户负责给出目标和判断结果是否能进入业务流程。

图3-1：旧系统加 AI 与 AI 原生业务系统对比。来源：本书自绘。Alt text：左侧"旧系统加 AI"在原有页面旁挂一个助手、用户仍逐个操作功能，右侧"AI 原生"以任务为中心、用户提出目标后由系统编排多个旧系统完成，对比凸显交互入口从页面转向任务。

旧系统是在原有模块里增加局部智能，AI 原生业务系统则把业务任务作为入口，由 Agent 重新编排底层系统能力。读完这一章，读者应能区分 AI 增强和 AI 原生：前者让某个页面更聪明，后者让系统承担更完整的任务组织责任。也要理解一个更现实的判断：并非所有业务都适合立刻 AI 原生化。优先级通常来自任务是否跨系统、是否文档密集、是否需要反复诊断，以及风险能否被确认和审批控住。经营分析、合同审阅、客服质检这类任务往往更早受益；付款、签约、主数据删除这类强事务动作，仍然需要非常谨慎。

3.1 “旧系统加 AI”与 AI 原生的差异

一家多业务线企业的信息化并不落后。零售板块有 BI，制造板块有 ERP，客服中心有工单系统，财务共享中心有票据平台，总部有知识库。过去几年，这些系统都逐步加上了 AI 功能。BI 能做自然语言问数，CRM 能自动总结客户状态，ERP 能提示库存异常，工单系统能自动摘要与分类，知识库能做语义搜索。这些能力都是真实进步，但它们没有根本改变业务协作方式。例如，集团经营分析会前，运营负责人仍然需要重复同样的动作：打开 BI 看销售数据，打开库存系统查缺货，打开客服系统看投诉，打开知识库翻上月活动复盘，再把这些信息整理成一份材料。每个系统里的 AI 都在局部帮忙，但没有一个系统对“准备一份可开会使用的经营分析材料”这个任务整体负责。差别就在这里。AI 增强是在旧系统里增加更聪明的能力；AI 原生把“完成任务”重新放到系统中心。前者提升局部效率，后者改写系统分工。

3.2 从页面中心到任务中心的系统变化

很多团队一听“AI 原生”，第一反应是界面变化：按钮变成对话，表单变成聊天框。只停留在这个层面，很容易低估它对系统分工的影响。AI 原生业务系统至少改变四件事：入口从模块转向任务，流程从预设路径转向动态编排，责任从单系统模块转向端到端结果，协作从人工拼接转向人机共同约束。第一，入口从页面转向任务。传统系统要求用户先判断该进哪个模块，再在模块里完成操作；AI 原生系统则允许用户先提出目标，例如“准备华东区经营分析材料”，系统再决定需要调用哪些能力。第二，流程从预先写死的页面路径，变成围绕目标动态组织的步骤。第三，责任不再只停留在单个系统模块内，Agent 需要对一段任务结果负责，至少要解释自己调用了哪些工具、采用了哪些证据、在哪些节点等待人工确认。第四，协作方式发生变化。过去是人在系统之间切换和拼接结果，AI 原生阶段则是系统在工具之间切换，人负责补充约束、判断风险和确认结果是否进入业务流程。

在传统模式下，用户的工作是“自己去拼”；在 AI 原生模式下，用户的工作逐渐变成“定义目标、补充约束、判断是否采纳结果”。用户心智也随之从“操作系统”转向“管理任务”。还有一个更深层的变化常常被忽略：在传统系统里，页面是系统的第一组织原则；在 AI 原生系统里，任务开始取代页面。过去企业软件把人训练成“模块使用者”，AI 原生则在把人训练成“任务发起者”。这两种训练方式会反过来塑造产品设计、数据组织方式，甚至部门协作方式。这个变化会让企业软件的许多传统假设失效。过去，系统设计的核心问题是“用户在哪个页面完成哪个动作”；现在，系统设计开始转向“用户提出目标后，系统如何组织一条可控任务链”。产品经理仍要关心页面路径，但还要关心任务状态是否透明、证据是否充分、风险节点是否可确认、失败后是否能继续。

3.2.1 AI 原生与数字化、自动化、智能化的关系

企业过去已经经历过多轮系统升级：数字化、自动化、智能化。AI 原生接续了这些阶段的积累，并把任务组织方式推到前台。数字化先把业务对象和流程搬进系统，形成 ERP、CRM、OA、数据仓库等基础设施。它解决了“业务是否有系统记录”的问题，也留下了系统多、模块硬、用户需要自己拼接的现实。自动化进一步把稳定流程交给规则执行，Workflow、RPA 和审批流都属于这一阶段。它适合路径确定、规则清楚的场景，但遇到开放任务和模糊目标时就会变得笨重。智能化在局部功能里加入预测、推荐、生成和语义搜索，让单个系统更会理解用户，却仍然让人承担端到端组织任务的工作。AI 原生接过这些积累，把任务目标放到系统组织中心，用 Agent 工作台、任务型 Agent 和生成式界面重新连接底层能力。

这段演进并不否定前几个阶段。没有数字化，就没有可调用的数据和系统；没有自动化，就没有可嵌入的流程节点；没有智能化积累，就没有足够的局部能力。AI 原生是在这些基础上，把“任务”提升为新的组织中心。一家多业务线企业如果没有 ERP、BI、CRM、工单系统和知识库，经营分析 Agent 根本没有东西可调用；如果没有审批流，报价 Agent 也无法安全进入业务流程。AI 原生依赖过去的信息化资产，只是把任务入口和执行链路重新组织起来。

3.3 旧系统会被工具化和重新编排

谈 AI 原生时，还有一个常见误解：以为未来所有旧系统都会被一个对话入口替代。这个判断过于简单。ERP、CRM、BI、工单、财务系统不会因为 Agent 出现就消失。原因很直接：它们承载着企业事实、规则、权限、审计和事务一致性。Agent 要把这些系统变成可调用、可解释、可治理的工具，而非绕过它们另建一套事实。ERP 在过去主要由用户直接进入页面操作，到了 AI 原生阶段，它会更多提供订单、库存、采购、财务等工具能力。CRM 过去要求销售维护客户与机会，后续会向 Agent 提供客户上下文、沟通历史和动作建议。BI 过去让用户查看报表，后续还要提供指标查询、语义层和数据解释能力。工单系统仍然保存事件流和处置状态，只是部分状态变更和建议动作会被 Agent 调用。知识库也不会被聊天框替代，它要提供可引用的制度、案例和说明文档，让系统回答时知道依据来自哪里。

AI 原生系统要做的，是把旧系统从用户亲自操作的界面，逐渐改造成 Agent 可以在权限范围内调用的工具。做得好，用户体验会简化；做得不好，Agent 就可能绕过系统，带来权限失控和结果不可追溯。第二章讲平台边界时强调 Tool Registry、Policy、Trace，原因也在这里。旧系统工具化之后，工具的风险等级、调用权限和结果记录，都会进入平台管理范围。

3.3.1 用户心智的同步变化

很多企业低估了用户心智变化这一层。系统能力已经上线，用户却还在按旧方式使用，价值释放自然很慢。传统系统训练出来的用户心智是这样的：我应该先去哪个页面？这个字段该填什么？哪个按钮能进入下一步？我怎样导出结果再交给别人？AI 原生系统要求的是另一套能力：我到底想完成什么任务？我应该给系统哪些约束？这个任务现在进行到哪一步？结果是否可信，是否需要我在高风险节点确认？这是一次明显的角色变化。用户不再主要是“系统操作者”，而更像“任务发起者”和“结果裁决者”。如果企业不帮助用户完成这种心智迁移，AI 原生系统就会出现很典型的问题：技术上能跑，业务上却用不起来。

3.4 AI 原生化的场景排序与迁移优先级

各业务域不会同时进入 AI 原生阶段。现实中，最先被改造的往往是那些“跨系统、跨知识源、跨角色”的任务；高度结构化、强事务、一步到位的操作通常不会排在最前面。

表3-1：适合优先 AI 原生化的任务类型及企业内的例子。来源：本书整理。

相反，完全结构化、一次性、强事务性的流程，通常不会最先被 Agent 化。付款、签约、主数据删除这类动作，不会因为“AI 原生”四个字就突然适合自动化。如果一家多业务线企业一年只能重点推进三到五个 AI 原生场景，排序依据不能只是哪个部门最积极。更可靠的做法，是同时看业务价值、任务结构、数据准备度和风险可控性。

表3-2：典型场景在价值、结构、数据、风险各维度的评分与建议。来源：本书整理。

这个排序不追求绝对正确，重点是让决策透明。很多 AI 项目失败，并非因为场景没有价值，而是因为一开始选了一个价值高、风险也极高、数据又没准备好的场景，最终消耗了组织信任。

3.4.1 AI 原生系统的信任建立

AI 原生系统能否被业务采用，最终取决于信任。这里的信任指向一个具体判断：用户是否敢把真实任务交给系统，也不能只看觉得模型回答得聪明。企业用户的信任通常来自五个来源。

表3-3：建立用户信任所需的几类系统供给。来源：本书整理。

如果一个 Agent 输出很漂亮，但不给证据，业务用户最多会觉得它“有启发”；如果它能给证据、给状态、给审批入口，用户才会开始把它当成工作系统。AI 原生工作台需要超出聊天框。聊天框擅长表达，但很难承载完整的信任机制。任务状态、证据区、审批控件、回放入口，这些看起来没有“智能感”的东西，反而决定企业是否愿意采用。

3.5 AI 原生产品形态：任务助手、嵌入式 Copilot 与 Agent 工作台

用一家多业务线企业的路径来概括，企业大致会经历三个阶段。第一阶段是 AI 增强。每个系统都加上一点智能能力，但系统边界和协作方式没有实质变化。BI 还是 BI，CRM 还是 CRM，只是它们更会理解自然语言、更会总结内容。第二阶段是 Agent 嵌入。这时会出现一些跨系统任务的 Agent，它们能够组织一小段任务链，超出单点功能的范围。经营分析 Agent、报价 Agent、客服质检 Agent，往往都属于这个阶段。

第三阶段才是 AI 原生业务系统。用户面对的是以任务为中心的工作台，而不再主要面对某个旧系统。系统自己组织步骤、生成中间结果、发起审批、沉淀证据，旧系统则逐渐退居工具层。多数企业会长期停留在第一阶段和第二阶段之间。第三阶段不会一次完成，也不会让所有部门同步进入。它通常从最适合的业务域开始，然后再逐步扩散。企业通常会从旧系统内的 AI 增强，走向跨系统 Agent 嵌入，最终形成任务中心的 AI 原生业务系统。

图3-2：AI 原生业务系统的三阶段迁移。来源：本书自绘。Alt text：从左到右三个阶段，数字化（业务搬进系统）、AI 增强（旧系统加助手）、AI 原生（以任务为中心重构），箭头表示能力逐级累积而非推倒重来。

3.5.1 AI 原生系统应走向任务工作台

一说到 AI 原生前端，常见误解是：把搜索框换成聊天框，就算 AI 原生。这样远远不够。一个可用的 AI 原生工作台，至少要让用户看到五类东西。

表3-4：任务工作台各要素的作用。来源：本书整理。

AI 原生前端通常会变成“对话 + 任务流 + 结构化结果 + 审批控件”的组合，单个大输入框很难承载完整任务链路。用户输入“生成经营分析材料”之后，不该只是等待系统吐出一段长文。更好的体验是：系统先显示任务目标和范围，让用户确认本次分析聚焦华东区、毛利率、上周数据；随后展示它准备查询哪些指标、引用哪些数据源；中间如果发现某个指标口径有两个版本，系统暂停让用户选择；输出阶段给出图表、结论、引用和待办，并允许用户把结果提交给会议材料审批流。这类体验才接近 AI 原生工作台；单纯在聊天框里塞一份报告，还停留在旧交互模式里。企业级任务工作台需要同时呈现任务状态、执行过程、证据引用、结构化结果、人工接管和审批确认。

图3-3：AI 原生任务工作台结构。来源：本书自绘。Alt text：工作台分为任务目标、执行进度、证据来源、人工确认入口等区域，中间是系统调用多个工具推进任务的主流程，体现"任务"而非"页面"作为组织中心。

3.6 经营分析会案例：从手工拼材料到任务工作台

可以用经营分析会这个案例，看 AI 原生业务系统怎样改变工作方式。一家多业务线企业每周一上午开经营分析会。传统模式下，周五下午开始，运营负责人会让各区域提交数据，数据团队导出销售、毛利、库存、促销、客诉等报表，运营专员把多个系统里的结果整理到 PPT，再找区域经理确认原因。到周一开会时，材料通常已经有了，但它有三个问题：一是数据口径容易不一致；二是异常追因常常依赖人工经验；三是会议上的行动项和后续跟进容易散落在邮件和群消息里。如果只是 AI 增强，每个系统都会变聪明一点。BI 能回答“华东区上周毛利率是多少”，工单系统能总结投诉，知识库能检索促销复盘。用户体验会改善，但运营负责人仍然要自己拼接。

如果进入 Agent 嵌入阶段，经营分析 Agent 可以接管一段任务链。用户提出目标：“准备下周一经营分析会材料，重点看华东区毛利率异常。”系统会先确认分析范围：时间、区域、指标、会议模板。随后它查询销售、毛利、促销、库存、客诉等数据，发现毛利率下降主要集中在两个品类，并进一步检查是否与促销折扣、物流成本、缺货替代销售相关。如果某个指标口径存在冲突，系统暂停让用户选择口径。最终，它生成的是一组会议材料：异常摘要、图表、证据引用、可能原因、待确认问题、建议行动项。用户可以修改结论，也可以把行动项派给区域负责人。如果进一步发展成 AI 原生经营工作台，变化会更明显。经营分析从每周临时拼材料，变成持续运行的任务空间。系统平时监控关键指标，发现异常后生成任务、积累证据，并提醒相关负责人补充解释。会议前，材料汇总这一周的任务状态、证据和决策建议；会议后，行动项继续在同一个工作台里跟进。三个阶段的差别可以概括为：

表3-5：经营分析会从传统模式到任务工作台各阶段的人机分工。来源：本书整理。

这个案例里，AI 原生改变的是经营分析的组织方式：它从一次临时材料准备，变成持续的任务管理过程。系统除了生成内容，还会重组数据、证据、会议和行动之间的关系。AI 原生系统把跨系统取数、异常追因、证据沉淀、报告生成和行动项跟进组织成连续任务链。

图3-4：经营分析会从手工拼材料到任务工作台。来源：本书自绘。Alt text：上方"传统模式"中运营人员在 BI、库存、客服等系统间手动查询拼接材料，下方"任务工作台"中用户提出分析目标、系统自动取数诊断并生成带证据的材料，对比两条路径的步骤数差异。

3.6.1 用户培训应转向任务模板

很多企业上线 AI 原生系统后，会立刻组织“提示词培训”。这当然有用，但如果只教用户怎么写 prompt，反而会把问题带偏。企业用户更需要学习的是如何把工作表达成可执行任务。比如“帮我分析一下华东区”这个输入太宽泛。更好的任务表达应包含范围、目标、约束和交付物：“分析上周华东区毛利率下降原因，重点比较促销、库存和物流成本影响，输出会议材料草稿，并标明需要区域经理确认的问题。”这里考验的是任务定义能力，不是提示词技巧。因此，AI 原生系统应提供任务模板。任务模板帮助用户表达目标，也帮助系统稳定理解边界，比空白输入框更适合高频业务任务。

表3-6：经营分析任务模板各要素的作用。来源：本书整理。

一家多业务线企业可以为不同场景准备一组任务模板：经营分析模板、报价草稿模板、客服质检模板、票据异常模板、合同条款审阅模板。用户从业务任务开始，不必从空白对话开始。这样能降低使用门槛，也让平台更容易评估和治理。任务模板还有一个额外价值：它把组织经验固化下来。优秀运营经理如何准备经营分析会，资深销售如何判断报价风险，财务主管如何检查票据异常，这些经验都可以逐步沉淀进模板。AI 原生系统的长期价值，正是在这种沉淀中出现。AI 原生业务系统应围绕不同角色的高价值任务建立工作空间，并保留必要的功能模块入口作为支撑。

图3-5：从功能菜单到角色任务地图。来源：本书自绘。Alt text：左侧是按系统模块组织的功能菜单树，右侧是按运营、销售、客服等角色组织的高频任务地图，箭头表示产品组织方式从"功能优先"转为"角色任务优先"。

3.7 AI 原生迁移的评审方法

AI 原生迁移不能只看界面是否有对话入口，也不能只看模型是否能生成一段完整答案。更合适的评审对象是一条任务链。团队可以从三个角度判断一个现有流程是否适合迁移。第一，看任务是否存在明显的跨系统拼接。若用户每天都在 BI、CRM、工单、知识库和审批系统之间复制信息，说明任务入口已经有重组价值。第二，看任务是否需要解释和证据。经营分析、合同审阅、客服质检这类任务，用户不会只接受结论，还要知道依据来自哪里、哪些地方需要确认。第三，看任务是否能被分成自动、确认、审批和禁止几类动作。若所有动作都强事务、强合规、不可撤销，迁移时就应先停在辅助和草稿层。

评审还要识别旧系统的权威边界。AI 原生工作台可以组织任务，但不能替代系统 of record。客户主数据仍应由 CRM 管，订单和库存仍应由 ERP 管，指标事实仍应由数据平台和语义层管，合同版本仍应由合同系统或文档治理体系管。Agent 可以调用这些能力、解释这些结果、把它们组织成任务产物，但不能在旁边维护一套难以审计的影子事实。很多 AI 原生项目失败，原因常常在于团队为了追求体验流畅，绕开了原系统里的权威数据、审批责任和变更记录。

迁移评审最好输出一张“任务迁移说明”。它要写清楚当前人工流程有哪些步骤，哪些步骤保留在旧系统，哪些步骤变成工具调用，哪些步骤由 Agent 编排，哪些节点需要人工确认，哪些产物可以进入后续流程。这样产品、平台、数据和安全团队可以围绕同一份材料讨论，而不是分别讨论界面、模型、数据和权限。AI 原生迁移的目标，是把高频、高价值、可验证的任务链逐步移到可观察的系统里，而不是把所有操作一次性变成自动执行。

3.8 AI 原生系统的迁移路径

AI 原生业务系统不是把所有页面改成聊天框。更现实的迁移路径，是先识别哪些业务流程已经存在大量跨系统切换、人工复制、指标解释和审批等待，再把这些流程改造成任务入口。Agent 在这里承担的是任务协调角色：理解目标、调用工具、组织证据、等待确认、生成产物。界面形态可以是对话，也可以是工作台、报告页或嵌入式 Copilot。迁移时要保护既有系统边界。CRM、ERP、BI、数据仓库和工单系统仍然是权威系统。Agent 如果绕过它们直接维护另一套事实，后续对账、审计和权限都会出问题。AI 原生层更像一层任务编排和解释界面，把既有系统的能力组织成更顺的工作流。这样做的好处是风险可控：业务数据仍由原系统治理，Agent 平台负责意图、状态、证据和动作协调。这也是本书强调平台而非单个 Agent 的原因。单个 Agent 可以改善一个入口，但 AI 原生系统需要统一的模型路由、工具治理、语义层、状态机、可观测性和安全策略。没有平台，业务系统会出现许多孤立 Copilot；有了平台，企业才有机会把这些入口连接成可运营的任务网络。

3.9 迁移节奏与验证证据

AI 原生迁移要有节奏。第一步通常从原系统中的高频任务链开始，让用户在熟悉入口中看到 AI 如何减少查找、复制、解释和整理。比如在 BI 页面中加入异常解释 Copilot，在客服系统中加入质检摘要，在合同系统中加入条款审阅草稿。这一步应收集真实问题、真实样本和真实边界，暂时不追求完整自动化。用户是否愿意采用、哪些答案经常被修改、哪些数据口径最容易争议，都会成为后续平台化的材料。

第二步是把跨系统链路抽出来。若一个任务稳定地需要读取多个系统、组织证据、生成草稿并等待确认，就可以进入 Agent 编排。此时系统要明确状态：任务已创建、证据已收集、工具调用中、等待用户确认、等待审批、已生成产物、已提交下游流程或已失败。状态清楚后，产品和工程团队才能讨论恢复策略。比如经营分析材料生成失败时，是重新查数、降级为草稿、转给人工，还是推迟会议材料提交；这些判断都要写进任务链。

第三步是把重复任务沉淀成角色工作台。工作台把模板、状态、证据、结构化产物、审批、行动项和复盘放在同一个空间，承担的职责超过聊天窗口。到了这个阶段，AI 原生系统的价值来自生成内容，也来自任务知识的积累：哪些异常经常出现，哪些解释被业务接受，哪些行动项能真正改善指标，哪些审批节点总是阻塞。平台可以把这些记录反馈给语义层、评测集、模板和工具策略，让系统越用越贴近组织真实工作。

迁移是否成功，要看证据而非看演示。团队至少应保存四类材料：迁移前人工流程的步骤和耗时，迁移后任务链的状态记录，用户修改和退回的样本，进入下游流程的产物质量。若只看到模型生成了一份漂亮报告，却看不到数据口径、引用来源、人工确认和行动项执行情况，就不能说明迁移已经成功。AI 原生项目的验收应围绕工作是否被更稳定地完成，而不是围绕界面是否更像对话。

3.10 任务工作台的验收材料

AI 原生工作台的验收材料要面向真实工作，而非面向演示流程。第一类材料是任务前后的流程对比：原来用户要打开哪些系统、复制哪些字段、等待哪些人确认；迁移后这些步骤分别由工具调用、Agent 编排、人工确认还是审批流程承担。第二类材料是证据与状态记录：任务何时创建，哪些数据源被读取，哪些证据被引用，哪些节点暂停，谁确认了最终产物。第三类材料是用户改动样本：用户删掉了哪些结论，补充了哪些解释，退回了哪些行动项。这些样本能说明系统离真实工作还有多远。

工作台还要验证组织适配。一个经营分析工作台如果只让运营负责人生成材料，却不能把待确认问题发给区域经理，不能把行动项进入任务系统，不能把会议后的跟进状态带回下一次分析，就仍然停留在内容生成层。AI 原生迁移的价值，要体现在任务持续运行上：异常有负责人，证据有来源，决策有记录，行动有跟踪，下一次任务能复用这些历史。验收材料覆盖这些环节后，团队才能判断工作台是否真正改变了业务组织方式。

3.11 AI 原生系统的迁移边界

AI 原生业务系统并不要求企业推翻已有系统。更常见的路径，是先识别哪些任务需要自然语言理解、工具编排、证据引用和人工复核，再把这些任务从旧系统中抽出一条可管理的链路。订单、客户、合同、工单、报表、审批仍然可以留在原系统；Agent 平台负责在这些系统之间组织任务、保留证据和处理异常。这样迁移不会变成一次大规模重构，而是围绕具体任务逐步建立新的运行层。

迁移边界要写清楚读写责任。只读查询可以先进入 Agent；会改变业务状态的动作，需要 Tool Registry、Policy Engine、HITL 和 Trace 同时准备好；跨系统写入要先确定幂等、补偿和回滚方式。很多项目失败的原因不在模型能力，而在写操作接管过早：旧系统没有提供可恢复接口，业务团队也没有定义责任人。AI 原生系统的建设顺序应从证据充足、风险可控的任务开始。

迁移还要保留用户习惯。企业用户已经熟悉原系统里的筛选器、审批流、报表和字段名称。Agent 可以用自然语言降低入口门槛，但不能把所有原有操作都藏进黑盒。早期更适合让 Agent 解释当前任务、推荐下一步、调用受控工具，并把结果写回原系统的可审计位置。等运行证据稳定后，再逐步把更多流程改造成 AI 原生体验。

3.12 迁移后的组织验收信号

AI 原生迁移完成后，验收不能只看用户是否打开新入口。更有价值的信号来自任务是否真的改变：用户是否少在系统之间复制信息，异常是否能带着证据进入会议，行动项是否进入下游系统，人工修改是否被平台记录并回流。若用户仍然把 Agent 输出复制到文档里再手工处理，说明系统只是增加了一个生成入口，任务组织方式还没有改变。

组织验收还要观察责任是否更清楚。旧系统里，责任通常落在操作人身上；AI 原生工作台引入 Agent 后，责任会分散到数据 owner、工具 owner、审批人、报告 reviewer 和平台 owner。上线验收应检查每个关键节点是否能找到负责人，尤其是数据口径冲突、自动建议出错、审批超时和行动项未完成这些场景。责任不清时，体验越流畅，风险越容易被隐藏。

早期 AI 原生迁移可以设定少量可观察指标：任务完成时间、跨系统切换次数、用户改写比例、人工退回原因、证据点击率、行动项完成率和异常复盘次数。这些指标不会一次证明系统成功，但能让团队看到迁移是否沿着正确方向推进。AI 原生系统的成熟，不在于界面有多像对话，而在于组织是否开始围绕任务、证据和责任运转。

3.13 任务工作台的复盘材料

任务工作台上线后，应保留复盘材料。材料包括任务模板、用户输入、系统调用、证据引用、人工修改、行动项和最终状态。没有这些材料，团队只能评价界面是否顺手，无法判断 AI 原生迁移是否真的减少了跨系统复制、指标争议和会议后遗漏。

复盘材料还帮助产品持续收敛。用户反复删掉某类结论，说明报告模板或证据选择有问题；用户总是补充同一类解释，说明语义层或知识库缺内容；行动项长期没人接收，说明工作台没有接到真实组织流程。AI 原生迁移要靠这些运行记录逐步修正。

3.14 AI 原生迁移的反向修正

AI 原生迁移还需要反向修正机制。上线后的真实任务会暴露前期设计看不到的问题：某些工具被频繁绕过，说明任务链没有贴近用户习惯；某些报告经常被人工重写，说明模板或证据选择不稳定；某些行动项无人接收，说明工作台没有接入真实组织流程；某些审批节点长期超时，说明责任人和通知链路没有设计好。这些问题不能只归类为用户培训不足。它们应回写到任务设计、语义层、工具契约、审批流程和评测样本中。

反向修正要有固定入口。任务工作台可以每月抽样一批真实 Run，查看用户改写、工具失败、证据替换、审批退回和行动项关闭情况。产品团队据此修正工作台流程，数据团队补语义层和知识库，平台团队修 Runtime、Registry 和 Trace，安全团队补策略样本。这样 AI 原生迁移会形成持续改进，而不是一次上线后等待下一个大版本。

早期可以把反向修正控制在少量高频任务上。比如经营分析工作台只跟踪异常解释、证据引用、行动项分派和会议材料导出；客服工作台只跟踪质检摘要、知识引用、工单创建和人工接管。每类任务都有复盘样本、owner 和下一次修订计划。迁移的质量不在于一次把系统设计完整，而在于真实任务能不断修正平台能力。

3.15 AI 原生迁移后的运行校准

AI 原生迁移完成后，团队还需要做运行校准。原来的系统通常以页面、按钮和审批流为边界，迁移后则以任务、Run、工具调用和 artifact 为边界。用户可能觉得任务入口更自然，但也可能因为系统自动拆解步骤而看不清进度；业务 owner 可能看到交付速度变快，却发现责任记录、人工复核和异常恢复不够清楚。迁移验收不能只看新界面是否可用，还要看运行语义是否稳定。

运行校准应从真实任务样本开始。团队可以选择一组迁移前后都存在的任务，例如会议材料准备、合同条款查找、经营指标解释、工单分派和报告发布。比较时不只看完成时间，还要看用户输入是否变短、系统澄清是否合理、工具调用是否减少人工复制、证据是否完整、审批是否进入正确节点、异常是否能恢复。这样迁移收益会落到任务链路，而不是停留在“界面更智能”的主观感受。

校准也要处理用户习惯变化。AI 原生系统会把一些原先显式的操作藏到后台，用户可能失去控制感；也会把一些原先隐性的判断显式化，用户可能觉得流程变长。产品设计要把高风险动作、等待状态、证据引用和人工节点展示出来，让用户知道系统正在处理什么。对于低风险任务，可以减少中间确认；对于会改变业务状态的任务，则应保留明确确认和撤回路径。

早期可以在每个迁移场景上线后做一次 30 天复盘。复盘材料包括任务完成率、人工接管、用户取消、工具失败、报告退回、审批超时和用户反馈。若结果显示用户频繁绕回旧系统，说明任务入口或运行解释不足；若结果显示 Agent 完成率高但争议多，说明证据和责任记录不足。AI 原生迁移的质量，要通过运行校准持续验证。

3.16 AI 原生迁移的用户工作方式变化

AI 原生迁移最终会改变用户的工作方式。传统系统把用户带到页面、菜单和字段里，用户自己判断下一步；任务工作台则把目标、证据、工具和产物放在一个运行链路中。用户不再只是点击按钮，还会确认计划、补充证据、复核产物、处理异常和决定是否发布。若产品设计仍按页面功能组织，AI 能力只会变成新的入口，不能改变任务完成方式。

这种变化需要提前管理预期。用户需要知道哪些动作由 Agent 自动完成，哪些动作需要自己确认，哪些结论只是草稿，哪些输出已经进入正式流程。业务 owner 也需要知道系统会保存哪些证据、哪些反馈会进入评测、哪些错误会触发人工复核。AI 原生系统的可用性不只取决于模型能力，还取决于用户是否理解自己在任务链路中的位置。

早期迁移可以选择一个高频但可控的任务，例如经营分析材料准备、合同条款初审或客服知识问答。团队先把输入、工具、证据、审批和产物治理跑通，再扩展到更多流程。这样 AI 原生迁移会从“界面里加一个助手”推进到“围绕任务重组系统”，也能让读者理解后续平台工程章节为何必要。

3.17 AI 原生系统的工程判断

AI 原生业务系统进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把任务边界、数据契约、人工复核、系统反馈和运营指标记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第22章 Runtime、第32章 DataAgent 和第53章组织治理相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括把对话入口当成业务系统、把模型建议当成流程状态、缺少复核和撤回机制。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

AI 原生系统应从业务状态和责任链设计开始，再决定模型如何参与。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

3.18 AI 原生业务系统的上线门槛

AI 原生业务系统的上线门槛应高于普通对话应用。系统如果会改变工单状态、生成经营报告、触发审批、调用外部工具或影响客户沟通，就已经进入业务流程。此时验收不能只看模型回答是否流畅，还要看状态是否可追踪、工具动作是否可撤回、人工复核是否有效、用户是否知道当前结果的可信范围。

上线门槛可以分成三层。第一层是任务边界，明确哪些请求能自动处理，哪些进入辅助模式。第二层是运行证据，确保每次 Run 有输入、计划、工具、输出、人工动作和最终 artifact。第三层是组织责任，确认业务 owner、平台 owner、数据 owner 和安全联系人都存在。三层缺一项，系统可以继续试点，但不应扩大到关键业务流程。

本章小结

本章把“AI 原生业务系统”拆回几个可判断的问题。AI 原生的核心变化，是系统开始围绕任务组织自己；页面仍然存在，但不再是组织业务流程的唯一中心。旧系统会退到工具层，但不会消失；它们仍然提供事实、规则、权限、审计和事务一致性。最适合优先进入 AI 原生阶段的，是那些跨系统、跨知识源、可生成草稿、可做诊断的任务。前端也应按任务工作台设计，让目标、证据、状态、风险确认和产物交付同时可见；单纯放大聊天界面，很难承载这些工作。AI 原生会牵动产品、数据、平台、安全与业务协作方式，按纯技术项目推进会很快遇到组织边界。下一章会把这些判断收束到一张完整地图中，说明本书为什么要按模型、数据、知识、平台、评估、安全这条路线展开。

参考文献

Yao, S. et al. (2023). ReAct: Synergizing Reasoning and Acting in Language Models. ICLR.

Schick, T. et al. (2023). Toolformer: Language Models Can Teach Themselves to Use Tools. NeurIPS.

Model Context Protocol. (n.d.). Specification and documentation.

NIST. (2023). AI RMF 1.0.

第4章 全书地图：平台参考架构与阅读路径

前三章分别讨论了 Agent 的边界、平台化的原因和 AI 原生业务系统。读到这里，概念已经不少：Runtime、Tool Registry、RAG、语义层、评估、网关、安全、组织分工。若没有一张地图，后续章节很容易变成组件堆叠，读者也很难判断一个问题应该放到哪一层解决。企业建设 Agent 平台时，最常见的混乱并非缺少名词，而是名词之间没有关系。业务负责人说“我们需要一个经营分析 Agent”，数据团队听成 NL2SQL，平台团队听成 Runtime 和工具调用，安全团队听成权限和审计，前端团队听成聊天工作台。大家都在谈 Agent，却在解决不同层的问题。没有一张共同地图，项目会在模型、数据、工具、界面和治理之间来回摆动。

本章的作用，是把前三章的概念判断收束成可使用的阅读地图。企业级 Agent 平台可分为四层：业务任务、运行能力、数据与知识底座、治理与运营底座。围绕这四层，后续章节会反复回到八个能力簇。DataAgent 贯穿全书，是因为它能同时暴露模型、数据、工具、评测、安全和前端问题。一个经营指标异常问题，几乎会穿过全书所有关键能力。这张地图也能帮助读者定位当前痛点。模型回答慢，不一定该换模型，可能是推理服务、上下文和网关策略问题；问数答不准，不一定是 NL2SQL 模型弱，可能是语义层、字段权限和评估集缺失；工具调用乱，不一定是框架问题，可能是 Registry、Policy 和 Trace 没建好；前端像聊天机器人，不一定是 UI 不够漂亮，可能是任务状态、证据和业务动作没有进入交互模型。

本章讨论参考架构、能力簇、平台分层、DataAgent 主线、阅读路径和建设路线。读者不需要在这一章记住所有模块名，而要建立一种判断方式：一个平台问题发生在哪一层，依赖哪些前置能力，后续应该看哪些章节。这样后面读到模型推理、数据契约、RAG、Runtime、前端、安全或组织章节时，都能把它们放回同一条任务执行链路里。这张地图还可以作为团队评审工具。每当一个新 Agent 场景被提出，团队可以沿四层逐项询问：业务任务是否足够清楚，运行时是否支持暂停、恢复和人工确认，数据与知识是否有权限和口径，治理层是否有评估、审计和成本边界。若这些问题答不上来，项目可能仍适合试点，但不宜直接承诺生产化。地图的价值就在于把“能不能做”拆成“哪些前置条件还没满足”。

图 4-1 更接近本书的阅读坐标，而非产品架构蓝图。它把业务任务、Agent 能力、数据与知识、治理与基础设施放在同一张图里，帮助读者理解后续章节为什么按这个顺序展开。

图4-1：企业级 Agent 平台四层参考架构。来源：本书自绘。Alt text：自上而下四层，业务任务层、Agent 能力层、数据与知识层、治理与基础设施层，每层标注核心职责，箭头表示上层任务依赖下层能力、下层为上层提供约束与支撑。

从业务任务层、Agent 能力层、智能与数据层，到基础设施与治理层，平台能力需要围绕任务执行链路形成整体。本章不要求读者记住所有模块名，而是建立一个阅读预期：后续章节不会按“哪个技术最热门”展开，而会按企业平台依赖关系展开。一个章节如果看似偏底层，例如模型路由、数据契约或 GPU 调度，它仍然服务于同一个目标：让 Agent 的任务执行链路可控、可复用、可评估。一个章节如果看似偏产品，例如对话 UI 或 Generative UI，也不能脱离证据、权限和运行状态单独理解。

4.1 总论地图的收束作用

前三章分别回答了三个问题：什么是 Agent，为什么企业会走向平台化，什么是 AI 原生业务系统。到这里，读者已经能判断一个系统是否属于 Agent，也能理解平台、框架和 AI 原生系统的区别。但如果没有一张全局地图，这些判断仍然容易散开。企业级 Agent 平台不能按单点技术理解，也不能停留在组件列表。它同时牵涉模型、数据、知识、工具、流程、前端、评估、安全、部署和组织协同。读者如果只记住“Runtime”“语义层”“评估”这些关键词，却不知道它们之间的依赖关系，后面阅读就会变成碎片化知识积累。一家多业务线企业的平台负责人需要回答“有哪些模块可以做”，也要回答更具体的问题：

• 第一个生产级 Agent 上线前，哪些底座能力必须先有？
• DataAgent 为什么不能简化为“NL2SQL + 图表”？
• Runtime、Tool Registry、审批、trace、评估之间是什么关系？
• 为什么本书先讲模型、数据、知识，再讲 Agent 能力和业务系统？
• 不同读者应该顺序读完，还是按角色跳读？

第四章把前三章的概念判断压缩成一张可执行的阅读地图。它不复述目录，而是说明后面每一章在整个平台中处于什么位置、解决哪类问题、和哪些章节存在前后依赖。

4.2 四层参考架构：从业务任务到治理底座

企业级 Agent 平台常见的画法问题，是一上来就罗列太多组件。总论更适合先用四层理解全局。第一层是业务任务层。这里是用户感知价值的地方：DataAgent、报价 Agent、工单 Agent、经营分析工作台、销售任务工作台，以及后续各种 AI 原生业务系统。它回答“企业用 Agent 完成什么任务”。第二层是 Agent 能力层。这里决定 Agent 如何被组织和运行：任务状态、工具调用、规划策略、长任务、人工介入、多 Agent 协作、协议与框架选型。它回答“Agent 如何把任务推进下去”。

第三层是智能与数据层。这里为 Agent 提供能力原料：模型推理、结构化输出、RAG、知识工程、语义层、湖仓、OLAP、元数据、血缘、指标口径。它回答“Agent 凭什么理解、判断和生成结果”。第四层是基础设施与治理层。这里保证系统能长期运行：模型部署、网关、多租户、可观测性、评估、成本、限流、降级、安全、合规和组织机制。它回答“Agent 如何被稳定、可信、可控地运行”。

表4-1：四层参考架构各层的核心问题与对应章节。来源：本书整理。

四层结构的作用，是帮助读者把问题放回正确位置。没有这张层次图，企业很容易发生两种误判：把所有问题都下沉成模型问题，或者把所有问题都抬高成业务问题。明明是语义层缺失、工具契约混乱、审批边界不清，却被归咎于“模型不够强”；明明是 trace 不统一、评估样本缺失、运行状态不可恢复，却被说成“业务场景太复杂”。四层架构提供的，正是定位这两类问题的共同语言。

四层之间还有依赖顺序。业务任务层提出目标，但不能绕过运行能力直接调用模型；Agent 能力层推进任务，但必须从数据与知识层拿到可信上下文；数据与知识层提供证据，但要接受基础设施与治理层的权限、审计和成本约束。把依赖顺序讲清后，平台建设才不会变成并行堆功能。比如前端工作台可以先做原型，但没有 trace 和审批事件，它就无法承担高风险动作；DataAgent 可以先做 NL2SQL，但没有语义层和权限，它就不能直接面向多部门开放。

4.3 八个能力簇：平台骨架、智能放大与反馈系统

在四层之中，构成 Agent 平台骨架的，是一组会反复出现在后续章节里的能力簇。本书把它们收束成八个。这八个能力簇各自回答不同问题。Runtime 处理任务如何被创建、推进、暂停、恢复和终止；Registry 处理工具、Agent、能力和版本如何统一管理；Planner 处理系统如何决定下一步，避免停留在文本生成；Memory 处理会话状态、长期偏好和任务上下文如何延续；RAG / Knowledge 处理文档、元数据和知识上下文如何进入 Agent；Observability 处理 trace、日志、指标和会话回放如何统一记录；Eval 处理如何判断版本变好还是变坏；Policy 处理权限、脱敏、审批和安全边界如何被执行。这八个能力簇不能当成功能清单。它们对应企业平台需要长期维护的三类能力。

没有 Runtime，系统只能演示，不能可靠执行。没有 Registry，工具会越来越多、越来越乱。没有 Planner，模型会在错误路径上自由发挥。没有 Memory，长任务和多轮任务会迅速失真。没有 RAG 和知识工程，系统难以连接企业上下文。没有 Observability，出错后无法解释。没有 Eval，版本好坏只能靠感觉。没有 Policy，越权、泄漏和绕过审批迟早出现。也可以换一种方式理解这八个能力簇：Runtime、Registry 和 Policy 构成执行骨架，让 Agent 能被统一运行和约束；Planner、Memory 和 RAG / Knowledge 构成智能放大器，让 Agent 能理解上下文并动态推进；Observability 和 Eval 构成反馈系统，让平台避免黑箱化和失控。后面章节虽然会展开很多具体技术，但这组三分法可以作为定位工具：当前主题到底是在补执行骨架、智能放大器，还是反馈系统？Runtime、Registry、Planner、Memory、RAG / Knowledge、Observability、Eval 与 Policy 分别承担执行骨架、智能放大器和反馈系统的职责。

图4-2：企业级 Agent 平台八个能力簇。来源：本书自绘。Alt text：八个能力簇分为执行骨架（Runtime、Registry、Policy）、智能放大器（Planner、Memory、RAG/Knowledge）和反馈系统（Observability、Eval）三组，连线表示各簇之间的调用与反馈关系。

4.4 DataAgent 主线：让全栈能力显影

本书不只讲 DataAgent，却把 DataAgent 作为主线场景。原因不在于问数最热门，而在于 DataAgent 几乎天然穿过企业级 Agent 平台的主要层级。一个看似简单的问题，例如“上周华东区毛利率异常的原因是什么”，背后会同时触发多个系统问题：

表4-2：DataAgent 为何在每一架构层都绕不过去。来源：本书整理。

DataAgent 适合作为主线场景。它不是唯一重要的业务场景，却能把企业级 Agent 平台的主要层级都暴露出来。把这个任务拆开看，一家多业务线企业的一次 DataAgent 请求至少要经过七个检查点。任务创建阶段要确认用户身份、租户和问题范围；上下文加载阶段要拿到指标口径、历史分析和可访问数据；路径规划阶段要决定先查什么、后查什么、是否需要跨多个工具；工具执行阶段要约束 SQL、API、Python 等动作；结果解释阶段要区分事实、推断和建议；治理记录阶段要留下 trace、成本、审批和风险证据；结果交付阶段要给出图表、引用、结论和后续动作。如果把 DataAgent 误解成“自然语言转 SQL”，平台建设从第一天就会跑偏。它同时连接数据智能、Agent 执行、AI 原生工作台和企业治理。因此，Part VI 在全书中承担主线地位。它把前面的模型、数据、知识、Agent 能力，以及后面的评估、安全、前端拉到同一个综合场景中，不能把它当成一个孤立案例。一个经营指标异常问题会同时穿过任务运行时、语义层、元数据、RAG、Planner、模型网关、SQL / Python 工具、trace、评估和结果交付。

图4-3：DataAgent 端到端任务链路。来源：本书自绘。Alt text：一条从用户提问出发的横向链路，依次经过意图理解、语义层编译、SQL 生成与执行、结果解释与可视化，每个环节标出所依赖的平台能力簇，末端汇出带证据的业务结论。

4.5 全书组织顺序：按平台依赖关系展开

很多 Agent 书会从聊天界面、提示词或工具调用开始讲。这种顺序容易上手，但一旦进入企业落地，就会遇到一个问题：前端体验跑得很快，底层语义、评估、权限、运行时和审计却都没有准备好。本书的组织顺序，按企业级平台逐步形成的依赖关系安排。先讲模型与推理，因为没有基础推理、结构化输出、模型路由和推理优化，后面的 Agent 决策无从谈起。再讲数据基础设施和知识工程，因为企业 Agent 的差异，往往不来自模型本身，而来自它能否安全地连接正确数据、正确口径和正确知识。接着进入 Agent 基础能力，因为有了模型、数据和知识之后，才有必要讨论 Runtime、Tool Registry、MCP、Planner、Memory、HITL、多 Agent 与框架选型。随后进入 DataAgent 主线，把前面的底座能力放进一个真实业务场景中检验。之后进入观测、评估、成本、部署、前端、安全、合规和组织。这些能力决定平台能否长期运行，避免系统停在一次演示上。

表4-3：全书各部分在依赖链中的位置及如此排序的原因。来源：本书整理。

这个顺序来自工程依赖。读者可以跳读，但要保留对上下游依赖的判断。第四章除了给技术地图，还要给阅读地图。不同角色不需要用完全相同的方式读这本书。平台负责人和 CTO 可以先抓平台边界、年度路线、成本、治理和组织协同，重点看第1章、第2章、第4章以及 Part VII 到 Part X。架构师更适合把四层架构、八个能力簇和章节依赖关系读通，再进入 Runtime、Tool Registry、RAG、评估和部署章节。数据智能工程师应优先关注语义层、RAG、DataAgent、NL2SQL 和评估体系；AI 应用开发者则应从 Runtime、工具接入、任务工作台和结果交付开始。安全与合规负责人不必先读所有实现细节，但要抓住权限边界、审批、trace、评估、Guardrails 和法规控制矩阵。

团队共读 Part I 时，可以先用第1章和第2章统一概念，确认团队说的 Agent、平台、框架、Workflow 是否指同一件事；再用第3章讨论哪些业务系统值得 AI 原生化，哪些场景只需要在旧系统上增加一个对话入口；最后用第4章把这些判断映射到团队路线图。这样的共读结果更接近一套后续建设时可以反复引用的共同语言。共读之后，团队最好把现有项目标到这张地图上。哪些项目只有业务任务和前端入口，缺少运行能力；哪些项目有模型和 RAG，却没有评估和权限；哪些项目已经接入工具，但工具注册、审批和审计还散在各处。把项目放到地图上，能避免“每个团队都觉得自己在做平台”的错觉，也能帮助管理者判断哪些能力应由平台团队统一建设，哪些仍应留在业务应用里。

读者已经有实际项目时，也可以按当前痛点跳读。Agent 效果不稳定时，应优先看 Runtime、Planner、Trace 和 Eval，同时检查 prompt 是否承担了过多系统责任；问数经常答不准时，应回到语义层、Schema Linking、NL2SQL 和 DataAgent 评测；工具越来越多、风险难控时，应先看 Tool Registry、Policy、审批和成本治理；平台路线说不清时，应回到 Part I、成本、安全和组织路线；前端像聊天机器人而不像工作台时，应把第3章的 AI 原生业务系统、第47章的对话 UI 和第48章的 Generative UI 连起来看。这张阅读地图让本书更接近工作手册。读者不必只能从第一页顺序读完，也可以按问题定位章节。

4.6 一年建设路线：从首个试点到平台化复制

如果一家多业务线企业准备用一年时间把企业级 Agent 平台从 0 做到可服务多条业务线，比较合理的节奏是围绕真实场景逐步沉淀共性能力，避免一开始就建设“大而全平台”。表 4-4 按季度拆出技术、治理和组织三条线，用来帮助团队识别每个阶段最该沉淀的公共资产。表中的季度不是固定排期，实际项目应按业务风险、团队能力和已有基础设施调整节奏。

表4-4：一年建设路线各季度的技术、治理与组织重点。来源：本书整理。

这张路线图的重点不在季度数字，而在顺序：先把执行链路站稳，再做规模化和组织化。每个阶段都应该沉淀一种可复用的公共资产。第一季度的资产是统一任务状态模型和工具风险等级：前者决定 Runtime、Trace、审批和恢复能否说同一种语言，后者决定新工具接入时是否能快速判断风险。第二季度要把评测样本模板和上线准入清单固定下来，让后续场景不再从“怎么证明可上线”重新讨论。第三季度的重点是语义层规范、数据权限规范和知识接入规范，因为复制到第二条业务线时，最大的摩擦通常来自指标口径、字段权限、文档边界和责任主体。第四季度再沉淀平台目录、复盘模板、成本与质量运营报表，把平台从项目交付转成持续运营。

这些公共资产看起来不像功能，却决定平台能不能复用。没有任务状态模型，每个 Agent 都会发明自己的“运行中”“等待审批”“失败重试”；没有评测模板，每次上线都只能靠现场演示；没有语义层和权限规范，DataAgent 一旦跨部门就会被口径和授权问题卡住；没有复盘和运营报表，平台团队只能证明自己“做了很多事”，很难证明平台质量是否变好、单位调用成本是否下降、业务线是否真正复用能力。路线图复盘时也要看这些资产有没有被第二个场景使用。第一个场景写出的工具注册规范，如果第二个场景仍然手写工具调用，说明规范没有真正成立；第一个场景沉淀的评测模板，如果第三个场景无法复用，说明样例结构过于定制。平台化的信号是后续场景接入时重复步骤减少，而不是文档数量增加。

这也是全书采用 DataAgent 主线的原因。它提供了一个可反复验证的平台样本：模型层、数据层、知识层、Agent 层、前端层和治理层都会在这个样本里暴露缺口。读者读完任何一部分，都可以回到 DataAgent 问一句：这个能力怎样让一次经营分析更可信、更可控、更容易复盘。很多平台路线图失败，原因不一定是技术目标写错，而是只写技术目标，不写治理目标和组织目标。只有技术目标，平台会建出来却用不好；只有治理目标，平台会规矩很多却缺少采纳；只有组织目标，平台会讨论很多却缺少可运行底座。三者要一起推进。

早期路线图还要克制范围。企业很容易在年度规划里同时写上模型网关、RAG、DataAgent、多 Agent、自动化审批、评估平台和安全治理，最后每一项都只有原型。更稳的做法是选择一条能贯穿全链路的主线场景，把任务状态、工具注册、权限、trace、评估和发布流程先跑通；第二条业务线再验证这些能力是否可复用。平台能力是否成立，要看第二个场景能否少做重复工作，而不只看目录是否完整。

4.7 全书主线的阅读方式

本章的地图不应被读成模块清单，而应被读成一条生产链路。企业 Agent 从用户任务开始，经过模型能力、数据上下文、工具动作、运行状态、评测反馈、安全合规和组织运营，最终变成可持续维护的业务系统。任何一层缺失，系统都会在试点和生产之间断开。读者可以按两种方式使用这张地图。第一种是从上往下读，先建立平台观，再逐层理解模型、数据、工具、运行时和治理能力。第二种是带着项目问题回查：如果当前项目卡在问数准确性，就重点读第33章到第39章；如果卡在工具执行和审批，就重点读第22章到第30章；如果卡在上线稳定性，就回到第38章到第52章。全书后续章节会保留这种写法：先说明场景和边界，再进入架构与工程实现，最后回到运行证据和上线判断。这样安排是为了避免读者把 Agent 平台理解成一组产品功能。真正需要建设的，是一套能把模型输出约束为企业动作、把动作连接到证据、把证据连接到责任的工程体系。

4.8 将现有项目映射到全书地图

很多读者不会从空白状态开始建设平台，而是已经有若干试点：一个知识问答助手、一个指标问答页面、一个审批草稿生成器、一个客服质检脚本，或者一个接了少量工具的聊天机器人。阅读本书时，最有价值的做法，是把这些项目逐一映射到四层架构和八个能力簇上，而非先给它们改名。映射时先写清楚当前项目的用户任务，再标出它依赖的模型、数据、知识、工具、运行状态、评测、安全和前端能力。写完以后，缺口往往会很直观：有些项目只有前端和 Prompt，没有 Runtime；有些项目有 RAG，却没有文档版本和权限过滤；有些项目已经能调用工具，却没有 Registry、Trace 和审批事件；有些项目做了评测，却没有把线上失败样本回流。

项目映射还可以帮助团队决定下一步投入。若多个试点都在重复接模型、写工具适配和做日志，说明平台层应优先沉淀模型网关、Tool Registry 和 Trace。若多个试点都卡在数据口径和字段权限，说明语义层、指标治理和数据访问策略应优先于更多 Agent 框架选型。若业务用户觉得结果难以相信，问题可能来自证据展示、引用、复核入口和失败解释，模型只是其中一个排查对象。映射的目的，是把分散问题整理成平台路线图，而不是给每个项目打分。这样团队不会把一个项目的局部成功误认为平台成熟，也不会因为某个试点失败就否定整条路线。

对管理者来说，这张映射表还能澄清责任。业务团队负责场景目标、验收样本和运营结果；平台团队负责可复用底座、运行证据和发布门禁；数据团队负责口径、权限和质量；安全与法务团队负责策略、审计和复核要求。一个项目如果只有业务 owner 而没有平台 owner，后续会在工具治理和运行责任上失控；如果只有平台 owner 而没有业务 owner，则容易做成没有采纳的通用能力。把现有项目放回全书地图，就是把阅读路径转成组织协作路径。后续章节可以按这个映射结果选择阅读顺序，也可以反过来修正团队的年度建设计划。

4.9 从地图到评审动作

全书地图最终要落到评审动作上。企业团队在讨论一个 Agent 场景时，常见问题是会议里所有人都同意“可以先试点”，但没人把试点和生产之间的差距写清楚。第1章讨论边界，第2章讨论平台，第3章讨论 AI 原生业务系统，本章则要求团队把这些判断变成一组可复查的问题。一个场景进入立项评审时，先写出用户任务链路：用户提出什么目标，系统需要读取哪些数据，可能调用哪些工具，哪些步骤会改变业务状态，结果会被谁使用。任务链路写完后，再把每一步标到四层架构里。若某一步找不到归属，说明团队还没有决定它由业务应用、平台能力、数据底座还是治理机制承担。

评审时还要区分“当前可以演示”和“后续可以运营”。一个知识助手能回答制度问题，说明模型、检索和前端入口已经具备雏形；但如果没有文档版本、权限过滤、引用证据和失败样本回流，它仍然只能算试点。一个 DataAgent 能生成 SQL，说明模型和语义提示有一定能力；但如果没有指标口径、查询资源隔离、字段权限和 SQL 回放，它还不能进入多部门生产。一个审批草稿 Agent 能写出邮件，说明生成能力可用；但如果没有审批对象、发布权限、外发审计和撤回流程，它不能替代正式业务流程。地图的用途，就是让团队把这些差距逐条写出来，避免用一次顺利演示代替生产判断。

把地图用在项目评审时，可以形成三类结论。第一类是准入结论：当前场景适合做原型、受控试点、有限生产，还是可以进入平台目录。第二类是缺口结论：缺的是语义层、Tool Registry、Runtime 状态、评估样本、HITL、Trace、安全策略，还是前端工作台。第三类是责任结论：哪些缺口由业务团队补样本，哪些由数据团队补口径，哪些由平台团队补能力，哪些由安全和合规团队定义门禁。没有这三类结论，路线图很容易只剩“继续优化模型”“继续完善平台”这类宽泛表述，后续复盘也很难判断究竟完成了什么。

一个可执行的评审会不需要很复杂，但要坚持证据优先。业务方要带来真实任务、失败样例和采纳标准；平台方要带来可复用能力和当前限制；数据方要带来指标口径、权限边界和数据质量状态；安全合规方要带来风险分级和审计要求。会议结束时，团队应能把该场景放到全书地图的一组坐标上：它依赖哪些章节能力，哪些能力已经具备，哪些能力需要在下一阶段补齐。这样阅读路径、建设路线和组织分工会合在一起。本书后续章节虽然会进入很多实现细节，但判断标准始终回到这里：一个能力是否让任务链路更清楚，是否让运行证据更完整，是否让责任边界更可执行。

4.10 读者预期与平台边界

这张全书地图承担预期管理作用。企业级 Agent 平台不是单点技巧的集合，而是一套建设和评审框架。刚启动试点时，团队最需要判断任务边界和平台边界；进入第二个场景时，最需要判断哪些能力可以复用，哪些仍然是业务专用实现；进入规模化时，最需要判断运行证据、成本、SLO、安全和组织责任是否跟得上。第四章把这些问题放在同一张地图上，后续章节才有共同坐标。

本书会把企业 Agent 平台的主干能力展开到可评审、可实现、可运行的程度，但不会把每一种行业场景都写成完整案例，也不会把 mini-platform 写成可直接替代商业系统的完整产品。mini-platform 的价值在于给出最小可运行路径，让读者看到 Runtime、Registry、语义层、Trace、Eval、HITL 等能力怎样接在一起；真实生产系统仍需要接入企业自己的身份、权限、数据目录、审批系统、监控系统和发布流程。

读者使用这张地图时，问题不应停在“缺哪个组件”。更有效的提问是：当前业务任务需要哪些证据才能上线，哪些动作会产生副作用，哪些数据口径会引发争议，哪些失败需要被用户看见，哪些责任需要留在人工流程中。一个项目如果能调用模型、检索文档和执行工具，只能说明功能链路初步跑通；若无法回答这些评审问题，它距离企业级平台仍然有差距。

4.11 地图驱动的建设顺序

全书地图可以帮助团队安排建设顺序。模型网关、工具注册、Trace、评测样本和权限边界属于早期底座；Memory、多 Agent、DataAgent、Generative UI 和多模态入口属于在底座稳定后逐步扩展的能力；安全、合规和组织治理需要从第一天介入，但可以先覆盖高风险链路。读者应把章节顺序理解为能力成熟路线，而非项目排期模板。

建设顺序要看依赖关系。没有稳定语义层，DataAgent 很难给出可复核的业务分析；没有 Trace 和 Eval，安全与合规就缺少运行证据；没有工具注册和 HITL，业务 Agent 里的高风险动作就无法解释。地图把这些依赖摆出来，团队就能判断哪类能力应先补齐，哪类能力可以在真实材料更充分时再扩展。

短板治理也要跟着地图走。若某个场景的失败来自指标口径，优先补语义层、数据目录和权限过滤；若失败来自工具误用，优先补 Registry、Runtime 状态和审批事件；若失败来自用户不信任结果，优先补引用证据、Trace、Eval 和前端解释。这样平台建设不会被局部热点牵着走，也不会因为某一类材料丰富就让路线图失衡。

4.12 地图驱动的场景准入

团队把第四章用于项目评审时，可以把它当成一张“缺口定位表”。每个正在做的 Agent 项目，都先写出用户任务、数据来源、工具动作、运行状态、证据记录和责任人，再放回四层架构。若某个项目找不到对应的运行状态，说明 Runtime 或 Trace 还没有接入；若某个项目找不到对应的数据口径，说明语义层和数据目录还没有准备好；若某个项目找不到对应的责任人，说明组织流程仍停在试点阶段。

场景准入可以形成三类结论。第一类是阶段结论：当前场景适合做原型、受控试点、有限生产，还是可以进入平台目录。第二类是缺口结论：缺的是语义层、Tool Registry、Runtime 状态、评估样本、HITL、Trace、安全策略，还是前端工作台。第三类是责任结论：哪些缺口由业务团队补样本，哪些由数据团队补口径，哪些由平台团队补能力，哪些由安全和合规团队定义门禁。

一个可执行的评审会不需要很复杂，但要坚持证据优先。业务方带来真实任务、失败样例和采纳标准；平台方带来可复用能力和当前限制；数据方带来指标口径、权限边界和数据质量状态；安全合规方带来风险分级和审计要求。会议结束时，团队应能把该场景放到全书地图的一组坐标上，并写清下一阶段需要补齐的能力和证据。

4.13 全书地图作为团队协作契约

全书地图还可以被当作团队协作契约使用。企业做 Agent 平台时，产品团队、数据团队、平台团队、安全团队和业务团队往往各自拿着一套语言：产品讲体验，数据讲指标，平台讲运行时，安全讲策略，业务讲交付。若没有共同地图，评审会很容易变成局部观点的叠加。第4章给出的四层架构和八个能力簇，可以把这些语言转成同一组问题：任务入口在哪里，数据证据从哪里来，动作由谁执行，风险如何被拦截，结果如何被评测。

协作契约要落到材料。一次 Agent 场景立项时，产品团队提供用户任务和产物样例，数据团队提供数据契约和质量状态，平台团队提供 Runtime、Registry、Trace 和 Eval 接入方式，安全团队提供权限和审批边界，业务 owner 提供验收样本和责任人。全书地图可以作为评审清单的顺序，但不应变成打勾表。每一项都要回答“如果这里失败，用户看到什么，平台如何恢复，谁负责修正”。

地图还能减少章节之间的割裂。读者读到第6章推理服务时，可以回到地图上看它怎样影响第7章优化、第8章结构化输出和第45章网关；读到第34章 NL2SQL 时，可以顺着地图追到第11章湖仓、第15章语义层、第38章 Trace 和第39章 Eval。这样全书不会像一组独立专题，而会像一套平台工程问题逐层展开。

团队可以把这张地图用于读书会或项目评审。每读完一个 part，就把正在做的项目贴回地图：哪些能力已经接入平台，哪些仍在应用侧，哪些缺少证据，哪些缺少责任人。这个动作比单纯讨论章节内容更有价值，因为它能把阅读内容转成落地对照表，也能暴露当前项目最需要补齐的工程材料。

4.14 全书阅读路径与能力取舍

全书地图的作用是帮助读者识别先后关系，避免把完整平台当成一次性建设目标。模型网关、工具注册、Trace、评测样本和权限边界属于早期底座；Memory、多 Agent、DataAgent、Generative UI 和多模态入口属于在底座稳定后逐步扩展的能力；安全、合规和组织治理需要从第一天介入，但可以先覆盖高风险链路。读者应把章节顺序理解为能力成熟路线，而不是项目排期模板。

阅读取舍要看业务链路。若团队主要做数据分析 Agent，应优先读数据基础设施、语义层、NL2SQL、Trace 和 Eval；若团队主要做办公自动化 Agent，应优先读工具注册、Planner、HITL、Guardrails 和前端事件模型；若团队正在做统一平台，应把部署、网关、成本和组织治理提前纳入。不同路径可以跳读，但不能跳过证据、权限、评测和恢复这四类主题。

本书后续章节会反复回到同一组问题：能力是否可复用，证据是否可追踪，失败是否可恢复，责任是否可确认，成本是否能解释。只要读者用这组问题检查每个章节，就能把具体技术点连接成平台工程，而不是把它们当成独立知识点。

4.15 全书主线的阅读节奏

全书地图进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把章节依赖、平台能力、工程证据、风险边界和读者角色记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和各 Part 的开篇、DataAgent 主线和安全治理章节相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括读者把章节当成孤立专题、先看案例再忽略底座、只关注模型而忽视运行责任。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

读者可按角色选择路径，但应保留 Runtime、Trace、Eval 和治理章节的共同背景。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

4.16 不同读者的取舍路径

全书地图还应给读者一个取舍路径。平台负责人可以先读第1章到第4章，再读 Runtime、Trace、Eval、安全和组织治理，因为这些章节决定平台能否规模化。数据负责人应重点读数据基础设施、知识工程和 DataAgent 主线，因为这些章节决定 Agent 能否拿到可信上下文。应用工程师可以从工具、Planner、HITL 和前端交互进入，但不能跳过 Trace 和发布证据，否则很容易做出能演示、难运营的应用。

取舍路径的意义在于降低第一次阅读的负担。读者不一定按顺序读完 55 章，但需要知道跳读会丢失什么。如果只读模型和 Prompt，会低估工具副作用、数据权限和成本治理；如果只读 DataAgent，会低估 Runtime、评测和合规证据；如果只读案例，会看不到案例背后的平台约束。目录应帮助读者形成这种预期，让后续章节的编号、图表和引用不显得零散。

不同读者可以采用不同路径，但主线必须清楚：模型能力进入平台，平台能力进入业务系统，业务系统再进入治理和运营。读者沿着这条线读，才能理解为什么本书反复写 Trace、Eval、Guardrails、owner 和发布证据。这些内容构成企业级落地的共同语言。

本章小结

第四章给出全书的阅读地图。模型路由对应推理层和成本管理，语义层对应 DataAgent 的数据依赖，Human-in-the-loop 对应企业责任边界，评测、安全和组织机制决定系统能否长期运行。这张地图的用法，是先定位问题发生在哪一层，再判断缺的是执行骨架、智能放大器，还是反馈系统。企业级 Agent 平台应先按四层定位，再看具体组件。八个能力簇提供后续章节的共同坐标。DataAgent 被选为主线，是因为它同时牵动模型、数据、工具、前端、评测和安全；其他业务场景也可以按同一套坐标拆解。后续章节从模型与推理层进入细节。模型并非平台中唯一的重心，但它是许多能力成立的起点，也最容易把早期试点推向真实成本、延迟和质量约束。

参考文献

Bass, L., Clements, P., & Kazman, R. (2021). Software Architecture in Practice. Addison-Wesley.

NIST. (2023). AI RMF 1.0.

OpenTelemetry. (n.d.). Documentation.

Model Context Protocol. (n.d.). Specification and documentation.

Part II 模型与推理层

本部分不再强制套用统一三层章节模板，而是按模型与推理层的实际决策链展开：先回答“选什么模型”，再回答“如何本地服务化”，然后进入“如何优化推理成本和延迟”“如何让模型输出可被系统消费”“如何定制能力与接入企业知识”。各章保留章头导读、关键议题、必要图表和本章小结；接口契约、实现路径、发布准入或接入条件只在章节对象确实需要时出现。

本部分章节

第5章 大模型选型

大模型选型不能停留在一次性产品比较上，它会逐步变成由任务画像、数据边界、SLO、成本和生命周期共同约束的运行时决策。选型的目标是为不同任务匹配合适模型，并让这套匹配能随业务和模型迭代调整，而非选出一个“最强模型”。业务任务、模型矩阵、运行时路由、闭源与开源、大模型与小模型的取舍，共同构成企业模型选型的判断框架。大模型选型一旦进入企业，就不再是模型团队单独挑供应商。业务方关心结果质量，平台团队关心路由和回滚，安全团队关心数据边界，财务团队关心成本。选型评审要同时容纳这些约束：先写清任务画像，再决定候选模型和路由策略，并用企业自己的评测集和运行数据持续校准。

模型选型在企业内部很少以一张排行榜结束。试点阶段，团队通常会选一个能力强、接入快的模型先跑起来；到了生产阶段，同一个模型要同时面对客服高并发、财务问数、合同审阅、代码生成和门店离线查询。每个场景对延迟、成本、上下文长度、结构化输出、数据出域和版本稳定性的要求都不同。若仍把选型理解成“全公司统一用一个模型”，平台会在很短时间内遇到两类问题：低风险任务承担了过高成本，高风险任务又缺少足够的推理和审计能力。

真实评审会通常比模型对比表复杂。业务负责人会追问准确率和上线时间，安全团队会追问数据能否离开内网，平台团队要确认网关、限流、降级和回滚能否支持，财务团队则希望费用能按租户和任务归因。模型团队如果只拿公开 benchmark 说明“这个模型更强”，很难回答这些问题。企业需要的是一套持续运行的模型矩阵：任务先被画像，再进入路由和评测，最后由运行数据反过来校准策略；一次采购结论不足以支撑后续生产。

一个常见失败案例是把复杂 DataAgent 和简单分类任务都路由到同一个强模型。前者需要高质量 SQL、工具调用和解释能力，后者只需要稳定标签和低延迟。统一模型让早期上线看起来简单，账单和排队延迟却会迅速放大；当强模型版本升级导致输出格式变化时，所有业务一起受影响。更稳的做法是把模型视为可治理资源，把能力、成本、合规和生命周期写入平台配置，让不同任务在同一控制面下选择不同模型。

5.1 选型从业务任务开始

5.1.1 多业务线企业的模型矩阵需求

一家多业务线企业启动 Agent 平台时，最先遇到的问题往往是到底用哪个模型，而非 Agent 循环怎么写。客服团队希望低成本处理每天数万条工单；财务团队希望 DataAgent 能生成可执行、可审计的 SQL；法务团队希望合同助手不要编造条款；研发团队希望代码助手能理解内部仓库；门店团队希望在网络不稳定时也能用离线助手查询 SOP。这些需求都叫“大模型能力”，但它们对模型的要求完全不同。如果只按公开排行榜选一个模型，平台很快会撞到现实约束。

• 客服分类任务并不需要最贵的推理模型，但需要稳定 JSON、低延迟和极低单次成本。
• DataAgent 需要强推理、结构化输出、工具调用和 SQL 安全校验，不能按普通对话体验选型。
• 合同审阅需要证据引用、拒答边界和人工确认，不能把“回答流畅”当作“结论可靠”。
• 内部代码助手需要长上下文、仓库检索、补丁生成和沙箱执行，普通聊天模型不一定合适。
• 门店离线助手更关心本地部署、轻量化、中文能力和数据不出现场。

因此，企业模型选型不能停在一次采购，也不能停在“统一用某某模型”这类口号上。更可靠的做法是把它做成持续运行的工程机制：先定义任务画像，再选择候选模型，用企业自己的评测集验证，通过 LLM Gateway 路由到不同模型，并持续监控质量、成本、延迟和版本生命周期。一家多业务线企业需要的是模型矩阵，不是“一个最佳模型”。

表5-1：不同业务场景的首要指标、模型倾向与兜底策略。来源：本书整理。

图5-1：企业模型矩阵与运行时路由。来源：本书自绘。Alt text：左侧是按成本与能力排列的模型池（轻量本地模型、国产托管、全球强模型等），中间是接收任务画像与治理策略的模型网关，右侧是不同业务任务，箭头表示网关按任务把请求路由到合适的模型并保留 fallback。

图 5-1 展示三层关系：左侧是业务任务画像，中间是治理与选择层，右侧是可路由模型池。它承接上面的业务场景表，后续 5.2 会展开中间治理层如何在运行时工作。

表 5-1 指向一个基本事实：模型选型要从业务任务出发，而非从模型品牌出发。不同模型供应商、不同部署形态、不同版本和不同推理参数，都应被平台抽象成可治理的“模型能力资源”。

5.1.2 候选模型的分类轴与能力维度

企业讨论模型选型时，常会把几个维度混在一起：闭源、开源、国产、自托管、云服务、推理模型、长上下文模型。它们并不是同一个分类轴。

表5-2：闭源托管、开放权重等模型类别的定义与选型须问的问题。来源：本书整理。

“国产模型”和“开放权重模型”尤其不能混为一谈。一个国产模型可能是闭源 API，也可能开放权重；一个开放权重模型也可能来自境外团队。企业需要把模型拆成多个属性：供应商、部署区域、License、权重可得性、数据边界、能力、成本、延迟、上下文长度、工具调用、结构化输出和生命周期。模型选型至少要看八个维度。

表5-3：任务能力、成本等候选模型评估维度的关键问题与度量。来源：本书整理。

这八个维度的权重由业务场景决定。客服摘要通常优先考虑成本和延迟，合同审阅要优先考虑证据和风险控制，DataAgent 要优先考虑结构化输出、工具调用和 SQL 校验。选型的第一步是写清楚任务画像，不是先列模型。

5.1.3 任务画像：把需求写成可评测约束

任务画像要把业务需求翻译成可评测约束，而非只写一句“效果要好”。表 5-4 给出的是最小问题集，评审时可以按这些问题补齐输入、输出、风险、延迟和部署边界。

表5-4：把任务需求写成可评测约束的提问清单与示例。来源：本书整理。

写清楚这些约束后，模型选型才会从“技术偏好”变成“工程决策”。评审会也能围绕证据讨论候选模型，而非围绕供应商品牌或个人偏好争论。

5.1.4 选型错误到生产风险的传导

公开 benchmark 可以用于初筛，但榜单第一不等于生产首选。许多榜单关注通用知识、数学、代码或多模态能力，而一家多业务线企业关心的是客服枚举、内部指标口径、SQL 执行成功、合同证据引用和安全拒答。榜单高分模型如果在企业 schema 上频繁输出非法 JSON，也不能直接上线。“一个强模型覆盖所有任务”的策略会带来成本和风险失衡。单一模型最容易管理，但成本和风险都不经济：低风险、高频任务用强模型会浪费预算，高风险任务用普通模型会放大错误。企业平台应让模型矩阵服务不同任务，并通过网关把复杂度挡在业务应用之外。开放权重减少了供应商锁定，也可能降低长期推理成本，但“开放”并不意味着免费。企业要承担 GPU、推理引擎、容量规划、模型安全、License 审查、量化评测和运维人力成本。自托管只是把 API 成本换成基础设施和平台工程成本。

国产模型能降低部分采购、服务和数据出境压力，但模型国别并不能自动完成合规。合规仍取决于部署区域、日志留存、数据分类、合同条款、访问控制、审计和供应商安全承诺。只看模型能力、不看版本生命周期，会让系统在供应商变更中失稳。厂商会发布新模型、下线旧模型、调整上下文窗口、价格、速率限制和 API 参数。企业如果没有模型版本 pinning、灰度和回归评测，就会在一次供应商升级后发现 Agent 行为变了。模型选型需要包含生命周期治理。

5.2 模型矩阵的运行时治理

5.2.1 模型矩阵在调用链路中的三种路由模式

模型选型能力位于业务应用和模型调用之间。它由 LLM Gateway、模型注册表、评测系统、策略引擎和可观测性共同组成，属于运行时决策层，不应停留在离线 Excel 表里。

flowchart TD
    App["业务应用 / Agent Runtime / RAG / DataAgent"] --> Req["任务请求<br/>task / tenant / risk / SLO"]
    Req --> Policy["策略引擎<br/>数据边界 / 权限 / 风险等级"]
    Req --> Selector["模型选择器<br/>能力画像 / 成本 / 延迟 / 版本"]
    Policy --> Selector
    Selector --> Gateway["LLM Gateway<br/>鉴权 / 限流 / 路由 / 审计"]
    Gateway --> Closed["闭源托管 API<br/>OpenAI / Claude / Gemini / Kimi / GLM 等"]
    Gateway --> Cloud["云模型平台<br/>Bedrock / Vertex / Azure / 千帆等"]
    Gateway --> Local["本地推理服务<br/>vLLM / SGLang / LMDeploy / TGI"]
    Local --> OpenWeight["开放权重模型<br/>Qwen / Llama / Mistral / DeepSeek / GLM 等"]
    Eval["评测系统<br/>离线集 / 回放 / 回归"] --> Registry["模型注册表<br/>能力 / 版本 / License / SLO"]
    Registry --> Selector
    Gateway --> Obs["可观测性<br/>质量 / 成本 / 延迟 / 错误"]
    Obs --> Eval
    Obs --> Registry

这条链路里，业务应用不应该直接写死 model="某个厂商最新模型"。应用只声明任务、租户、风险等级、延迟目标、输出格式和数据分类。模型选择器根据注册表和策略选择候选模型，LLM Gateway 负责实际调用、重试、审计和降级。在一家多业务线企业，模型选型层需要支持三种运行模式。

表5-5：显式、规则与自动三种模型路由模式及适用场景。来源：本书整理。

显式模型适合可复现，策略路由适合规模化，多模型仲裁适合高风险。平台需要同时支持三者，否则要么不可控，要么不经济。

5.2.2 模型目录、策略引擎与路由契约

一个生产级模型选型系统至少包含七个组件。表 5-5 说明一次模型路由决策背后需要哪些输入、策略和反馈，不应被理解成组件采购清单。

表5-6：模型目录、策略引擎与路由契约的职责、输入输出与失败模式。来源：本书整理。

模型目录不应该只是模型名称列表。它至少要记录这些字段。

model_id: local-qwen3-32b-instruct
display_name: Qwen3 32B Instruct Local
provider: internal
deployment: self_hosted
endpoint: http://llm-gateway.internal/v1/chat/completions
api_style: openai_compatible
weight_access: open_weight
license_review: approved
data_boundary:
  allowed_data_classes:
    - public
    - internal
    - confidential_aggregate
  region: cn-private
capabilities:
  text: true
  vision: false
  tool_calling: true
  structured_output: true
  reasoning: medium
  code: medium
limits:
  context_tokens: 32768
  max_output_tokens: 4096
slo:
  p95_latency_ms: 12000
  monthly_budget_usd: 5000
eval:
  customer_service_json_validity: 0.985
  dataagent_sql_exec_success: 0.78
  safety_refusal_accuracy: 0.93
release:
  status: production
  pinned_version: "2026-06-01"
  fallback_model: frontier-reasoner

业务侧请求也要避免直接表达厂商细节。下面是一个任务级模型选择请求。

{
  "task": "dataagent_sql_planning",
  "tenant": "retail-analytics",
  "risk_level": "high",
  "data_class": "confidential_aggregate",
  "slo": {
    "p95_latency_ms": 30000,
    "max_cost_usd": 0.30
  },
  "required_capabilities": {
    "structured_output": true,
    "tool_calling": true,
    "reasoning": "high"
  },
  "response_contract": {
    "type": "json_schema",
    "schema_id": "dataagent_query_plan",
    "schema_version": "1.2.0"
  }
}

模型选择器返回的应当是一组带约束的路由决策，而非孤零零一个模型名。最终选中的模型只是结果的一部分，配套的校验、降级和发布规则必须一并返回。

{
  "primary": {
    "model_id": "frontier-reasoner-private",
    "reason": "passed data boundary; highest sql planning score within SLO"
  },
  "fallbacks": [
    {
      "model_id": "local-qwen3-32b-instruct",
      "when": "provider_timeout_or_budget_exceeded"
    }
  ],
  "guards": {
    "pre_check": "pii_redaction_v2",
    "post_check": "sql_policy_validator_v3"
  },
  "release_policy": {
    "pinned": true,
    "canary_percent": 10
  }
}

这类契约的价值，在于把模型选择写成可审计的发布决策。为什么选它、什么时候降级、哪些数据允许进入、输出经过哪些校验，都应该留在 trace 里，而非散落在 Prompt 和运维口头约定中。

5.2.3 生命周期、灰度与回退策略

模型从候选进入生产，最好经过一条清楚的生命周期。这样一来，许可证审查、离线评测、沙箱验证、灰度放量和回滚触发点都能落到固定节点上。

stateDiagram-v2
    [*] --> Discovered
    Discovered --> LicenseReview: candidate selected
    LicenseReview --> Rejected: license or data terms failed
    LicenseReview --> OfflineEval: approved
    OfflineEval --> Rejected: quality gate failed
    OfflineEval --> Sandbox: gate passed
    Sandbox --> Canary: integration passed
    Canary --> Production: stable metrics
    Canary --> Rollback: regression detected
    Production --> Deprecated: provider lifecycle or better replacement
    Production --> Rollback: incident
    Deprecated --> Retired: traffic drained
    Rollback --> OfflineEval: fix and retest
    Rejected --> [*]
    Retired --> [*]

上线前的时序可以这样理解。

sequenceDiagram
    participant O as Owner
    participant C as Model Catalog
    participant P as Policy
    participant E as Eval Harness
    participant G as LLM Gateway
    participant M as Monitor

    O->>C: 登记候选模型、版本、License、价格、区域
    C->>P: 检查数据边界和供应商条款
    P-->>C: allowed / denied
    C->>E: 运行任务评测、安全评测、成本延迟评测
    E-->>C: 评测报告和准入结论
    C->>G: 发布灰度路由规则
    G->>M: 记录质量、成本、延迟、错误、反馈
    M-->>E: 生成回放集和回归样本
    E-->>G: 建议扩大流量、回滚或冻结版本

模型生命周期进入生产后，主要风险会落在路由、版本、价格、配额、结构化输出和数据边界上。表 5-7 将这些风险放回运行时控制点，便于后续把灰度、回滚和审计做成平台能力。

表5-7：模型服务常见失败模式的信号与恢复策略。来源：本书整理。

这些失败模式说明，模型选型不能停在一次性决策。生产中还要能发现模型行为变差、解释为什么路由到了某个模型，并在事故发生时快速回滚。

5.3 从模型选择到治理策略

5.3.1 闭源托管、开放权重与专有云

闭源托管模型适合早期验证和高难任务兜底。它的优势是能力强、接入快、无需维护推理集群；代价是数据边界、版本变化、成本波动和供应商锁定都要被纳入治理。开放权重自托管更适合高频、稳定、敏感的内部任务，尤其是客服分类、内网知识问答和 DataAgent 常规问数；它把数据控制权留在企业内，也把 GPU、推理优化、量化、监控和 License 审查成本交给企业。专有云或私有化托管介于两者之间，适合金融、政企和核心数据场景，但商务周期、部署周期和价格都要单独评估。

mini-platform 不应把三类模型写成单选题。更合理的路径是：早期用托管模型快速验证业务价值；中期把高频、稳定、敏感任务迁到开放权重或专有云；长期保留少量强闭源模型处理复杂推理、多模态和兜底任务。这个组合只有在网关、Policy 和 Eval 都能表达任务风险时才成立，否则它会退化成业务代码里到处写死模型名。

5.3.2 国产模型与全球模型

国产模型和全球模型也不应被写成简单的能力排序。国产托管模型在中文、采购、服务响应、数据驻留和本地生态上更容易落地，适合国内业务、中文客服和政企合规场景；全球托管模型在前沿能力、工具生态和多模态更新速度上仍有优势，但数据出境、采购链路和网络可用性需要 Policy 严格控制。国产开放权重则适合本地部署、边缘节点、内网知识问答和高频 DataAgent 任务，前提是企业愿意承担推理运维与调优成本。国产模型不是一个单独技术等级，它同时涉及供应链、合规、服务和生态维度。企业应把国产模型和全球模型同时纳入评测，用数据边界决定可用范围，用业务评测决定流量比例。对 mini-platform 来说，较稳妥的做法是把国产托管、全球托管和国产开放权重都放进候选池，再由 core/policy/ 和 core/eval/ 决定哪些任务能走哪些模型。

5.3.3 单一强模型与模型矩阵

单一强模型在原型期很有吸引力：接入简单，行为相对一致，排障也容易。但它会把成本、供应商风险和能力瓶颈集中到一个点上。双模型策略更适合早期生产：一个通用模型处理常规任务，一个强模型处理兜底和高难任务，路由规则比较简单，成本也更可控。模型矩阵是规模化后的目标形态，它按任务类型、风险等级、租户、成本和延迟选择模型，但前提是注册表、评测、网关、监控和回滚机制已经具备。一家多业务线企业不应该第一天就维护几十个模型。比较稳的路线是：先建立双模型策略，等评测和网关成熟后，再扩展到客服、DataAgent、代码、合同、多模态、本地离线等模型池。模型数量增加以后，治理压力会从“如何接模型”转为“如何解释一次路由为什么选择这个模型”。这正是模型矩阵需要平台化的原因。

5.3.4 长上下文模型与 RAG / 上下文工程

长上下文能力很有价值，尤其适合临时文档分析、单文档审阅和低频探索。但它不应成为“把所有材料塞进 prompt”的理由。长上下文会带来更高成本、更长 TTFT，也会让无关材料增加幻觉概率。需要引用、权限过滤和知识更新的知识库、政策、手册、指标口径场景，RAG 加重排仍然是默认工程路径。多轮对话、长 Trace 和批量文档则更适合摘要与压缩上下文，把稳定事实保留下来，把可重新读取的大对象转成引用。因此，mini-platform 应把长上下文当成受控能力，而非知识系统的替代品。直接长上下文可以服务少量高价值任务；RAG 负责可引用、可更新、可权限过滤的知识；摘要和压缩负责控制多轮上下文的成本。三者组合后，模型看到的是经过选择的上下文，而非任意堆叠的材料。

5.3.5 质量、成本、延迟的三角关系

企业平台不可能在所有任务上同时追求最高质量、最低成本和最低延迟。模型选型的工作，就是把这个三角关系显式化，并把决策固化到路由策略中。高风险任务通常优先质量，可以使用强模型、多模型复判和更完整的上下文，但要接受更高成本和延迟。高频低风险任务通常优先成本，可以使用轻量模型、缓存、批处理或本地推理，但必须通过评测确认质量没有跌破可用线。交互式任务更看重 TTFT 和 P95 延迟，适合小模型、短上下文、流式输出和区域就近路由。真正可持续的策略通常是分级路由：常规任务先走低成本路径，失败或风险升高时再升级模型。图 5-2 不给出唯一最优点，而是提醒读者把不同任务放进不同策略区间：高风险任务优先质量，高频低风险任务优先成本，交互式任务优先 TTFT 和 P95，再由网关固化路由与回退路径。

图5-2：质量、成本、延迟三角与治理边界。来源：本书自绘。Alt text：一个以质量、成本、延迟为三个顶点的三角形，中心标注"不可三者同时最优"，外圈是 SLO 与预算构成的治理边界，示意选型只能在三者间按任务取舍。

5.4 模型矩阵在运行时的落点

5.4.1 模型矩阵在平台中的落点

当前 mini-platform 还处在 v0.1 骨架阶段，模型选型应先落在网关、评测、策略和观测四个边界上，不应直接实现一个复杂模型平台。在 mini-platform 中，模型矩阵应落在几条清晰边界上。core/gateway/ 负责统一模型调用接口、primary/fallback 选择和供应商差异封装；core/eval/ 保存评测集、运行离线评测并产出准入门槛；core/policy/ 判断租户、数据分类、区域和供应商是否匹配；core/guardrails/ 做输入脱敏、输出检查和敏感任务拦截；core/observability/ 记录 trace、usage、latency、cost 和质量反馈；知识型任务则默认经 core/rag/ 检索，而非把长上下文当作唯一方案。

后续若要把模型矩阵做成更完整的教学实现，可以逐步增加 core/gateway/model_catalog.py、core/gateway/model_selector.py、core/gateway/provider_adapter.py、core/eval/model_selection_eval.py 和 core/policy/model_policy.py。这些文件分别承载模型画像、选择策略、供应商适配、准入评测和数据边界判断。本章不要求现在实现它们，原因是模型平台很容易过早膨胀；早期更重要的是把调用、评测、策略和观测边界写清楚，避免业务代码直接在各处写死模型名。

5.4.2 模型选择器与配置示例

下面示例展示一个极简模型选择器。它不是完整生产实现，但表达了 mini-platform 应有的工程边界：任务画像、模型画像、策略过滤和按分数选择。

# 来源建议：mini-platform/core/gateway/model_selector.py
from __future__ import annotations

from dataclasses import dataclass, field

@dataclass(frozen=True)
class TaskProfile:
    task: str
    tenant: str
    data_class: str
    risk_level: str
    max_latency_ms: int
    max_cost_usd: float
    required_capabilities: set[str] = field(default_factory=set)

@dataclass(frozen=True)
class ModelProfile:
    model_id: str
    provider: str
    deployment: str
    allowed_data_classes: set[str]
    capabilities: set[str]
    p95_latency_ms: int
    cost_per_1k_output_tokens: float
    eval_scores: dict[str, float]
    status: str = "production"

@dataclass(frozen=True)
class ModelRoute:
    primary: str
    fallback: str | None
    reason: str

class ModelSelector:
    def __init__(self, models: list[ModelProfile]) -> None:
        self._models = models

    def select(self, task: TaskProfile) -> ModelRoute:
        candidates = [
            model
            for model in self._models
            if model.status == "production"
            and task.data_class in model.allowed_data_classes
            and task.required_capabilities <= model.capabilities
            and model.p95_latency_ms <= task.max_latency_ms
            and model.cost_per_1k_output_tokens <= task.max_cost_usd
        ]

        if not candidates:
            raise ValueError(f"no model satisfies policy for task={task.task}")

        ranked = sorted(
            candidates,
            key=lambda model: (
                model.eval_scores.get(task.task, 0.0),
                -model.cost_per_1k_output_tokens,
                -model.p95_latency_ms,
            ),
            reverse=True,
        )

        primary = ranked[0]
        fallback = ranked[1].model_id if len(ranked) > 1 else None
        return ModelRoute(
            primary=primary.model_id,
            fallback=fallback,
            reason=(
                f"selected by task score for {task.task}; "
                f"provider={primary.provider}; deployment={primary.deployment}"
            ),
        )

配套配置完全可以先从 YAML 起步，把路由、校验和灰度策略先落成可审阅文本。等版本、租户和发布链路复杂起来之后，再逐步迁到数据库或配置中心也不迟。

models:
  - model_id: frontier-reasoner-private
    provider: commercial-api
    deployment: managed_private
    allowed_data_classes: [public, internal, confidential_aggregate]
    capabilities: [text, reasoning_high, tool_calling, structured_output]
    p95_latency_ms: 25000
    cost_per_1k_output_tokens: 0.08
    eval_scores:
      dataagent_sql_planning: 0.86
      contract_risk_review: 0.90
      customer_service_classification: 0.93

  - model_id: local-qwen3-32b-instruct
    provider: internal
    deployment: self_hosted
    allowed_data_classes: [public, internal, confidential_aggregate, confidential_raw]
    capabilities: [text, reasoning_medium, tool_calling, structured_output]
    p95_latency_ms: 12000
    cost_per_1k_output_tokens: 0.01
    eval_scores:
      dataagent_sql_planning: 0.78
      contract_risk_review: 0.74
      customer_service_classification: 0.91

  - model_id: fast-classifier
    provider: internal
    deployment: self_hosted
    allowed_data_classes: [public, internal]
    capabilities: [text, structured_output]
    p95_latency_ms: 1500
    cost_per_1k_output_tokens: 0.002
    eval_scores:
      customer_service_classification: 0.88

routes:
  customer_service_classification:
    primary: fast-classifier
    fallback: local-qwen3-32b-instruct
    escalation:
      low_confidence: frontier-reasoner-private

  dataagent_sql_planning:
    primary: frontier-reasoner-private
    fallback: local-qwen3-32b-instruct
    guards:
      - pii_redaction_v2
      - sql_policy_validator_v3

模型评测配置也要版本化。不要把“模型能用”写在人的记忆里。

eval_suite: model_selection_gate_v1
datasets:
  - name: customer_service_classification
    path: datasets/eval/customer_service_classification.jsonl
    metrics:
      json_validity_min: 0.98
      category_accuracy_min: 0.88
      p95_latency_ms_max: 3000
  - name: dataagent_sql_planning
    path: datasets/eval/dataagent_sql_planning.jsonl
    metrics:
      schema_validity_min: 0.97
      sql_exec_success_min: 0.75
      forbidden_table_access_max: 0
  - name: safety_regression
    path: datasets/eval/safety_regression.jsonl
    metrics:
      refusal_accuracy_min: 0.95
      sensitive_leakage_max: 0
release_gate:
  require_license_approval: true
  require_cost_owner: true
  require_rollback_model: true

这个配置的核心价值是让模型替换可复现。未来换成 OpenAI、Claude、Gemini、Qwen、DeepSeek、Kimi、GLM、ERNIE、Llama、Mistral 或本地量化模型时，业务应用不需要改代码，只需要模型目录、评测报告和路由策略发生变化。

5.4.3 路由策略的发布证据留存

• 权限：每个模型声明可处理的数据分类、租户范围、区域和供应商边界。
• 审计：每次路由记录任务、模型版本、prompt 模板、schema、数据分类和 fallback 原因。
• 成本：按租户、任务、模型和项目统计 token、缓存命中、GPU 成本和月度预算。
• 性能：监控 TTFT、TPOT、P50/P95/P99、队列长度、429、超时和重试。
• 稳定性：所有生产路由都有 fallback、超时、熔断、灰度和回滚策略。
• 质量：上线前通过企业评测集，线上抽样进入回放和回归评测。
• 结构化输出：机器消费场景需要 schema validate、业务 validate 和重试上限。
• 数据安全：敏感字段在网关前脱敏或阻断，日志留存策略区分调试与审计。
• 许可证：开放权重模型需要完成商用、再分发、训练数据和模型输出条款审查。
• 灾难恢复：供应商不可用、本地 GPU 故障、模型下线时有替代路径和通知机制。

5.4.4 选型判断出错后怎样复盘

失效场景 1：只用一批短 prompt 选模型。短 prompt 测出来的延迟和质量经常过于乐观。RAG、DataAgent 和合同审阅的真实输入可能包含数千到数万 Token，还会带工具 schema、历史 trace 和引用片段。选型评测要覆盖短请求、长上下文、高并发、结构化输出和失败重试。失效场景 2：没有区分“模型失败”和“系统失败”。SQL 错误不一定是模型差，也可能是表结构上下文缺失、语义层口径不清、工具返回错误或权限策略拦截。模型选型评测要保存完整 trace，否则团队会错误地更换模型，却没有修复实际的系统问题。失效场景 3：把供应商 alias 当稳定版本。有些模型名是固定快照，有些是会指向新版本的别名。生产系统如果只写 alias，供应商升级后行为可能变化。关键任务应使用明确版本或内部 pinned alias，并在升级前跑回归评测。

模型选型进入生产后，还会遇到表 5-7 中这类失效场景。低成本模型如果没有设置升级路径，客服分类虽然便宜，却会在低置信度、解析失败、投诉升级、VIP 客户、监管关键词等样本上悄悄处理错。自托管模型如果没有算运维成本，也会低估 GPU 空闲、峰值扩容、模型加载、驱动升级、推理引擎兼容、日志审计和安全补丁带来的团队投入。只有当负载稳定、数据边界重要、平台团队具备推理运维能力时，自托管的长期收益才会兑现。

模型矩阵还要进入发布流程。新增一个候选模型时，平台应明确它能服务哪些任务、评测样本覆盖哪些失败模式、默认 fallback 是什么，以及版本升级后由谁确认结果。若这些信息只停留在选型会议纪要里，网关无法执行，事故复盘也无法说明某次请求为什么落到这个模型上。选型完成后，团队要继续观察线上分布。某个模型在评测集上表现很好，但真实用户问题可能集中在长上下文、口径澄清或工具调用失败上；另一个低成本模型在分类任务上稳定，却可能在节假日促销期间因为输入分布变化而误判。运行日志、人工复核和成本报表会不断改变模型矩阵的权重。因此，模型选型的交付物不应只是“推荐模型清单”。更有用的交付物包括任务画像、候选模型评测结果、路由策略、fallback 策略、成本预算、数据出域说明和版本观察窗口。平台把这些材料固化下来，后续模型替换才不会变成重新争论。

模型选型还要考虑“谁有权改变路由”。生产环境里，临时把某个任务切到强模型、把某个租户切到本地模型、把某个供应商下线，都不是单纯技术动作。它会改变成本、延迟、合规路径和用户体验。平台应把这些变更纳入审批或发布流程，至少保留变更原因、影响范围、回滚条件和观察窗口。否则，模型矩阵很快会变成一组没人敢动的历史配置。评测样本也不能只由模型团队维护。业务团队要提供真实任务和可接受答案，数据团队要说明口径和权限，安全团队要补充拒答和数据出域样本，平台团队要补充超时、限流、结构化输出失败和 fallback 场景。这样选型结果才会覆盖上线后真正会发生的问题。一个模型在通用推理题上领先，并不代表它适合承接企业里的审批建议、指标解释或合同条款抽取。

运行一段时间后，模型矩阵应形成自己的复盘节奏。每月可以查看不同任务的命中模型、失败分布、人工复核比例、单位成本和延迟分布。若某个任务长期被 fallback 接管，说明首选模型或 Prompt 不稳定；若某个低风险任务持续使用强模型，说明路由策略过于保守；若某个模型版本上线后人工驳回增加，说明离线评测没有覆盖真实问题。复盘的目的，是让模型选择继续贴近业务，并为后续调整留下证据，事故追责只是其中一种使用场景。企业还要为模型退出做好准备。供应商价格变化、区域合规要求、服务不可用、模型版本退役，都会迫使平台调整模型池。只要任务画像、评测集、路由策略和回放日志保存完整，替换模型时就能用同一套门禁比较新旧版本；若早期只记住“当时选了某个模型”，迁移就会变成重新建设。模型选型最终会落到一个很务实的问题：当某次回答出错时，平台能否解释为什么选了这个模型。能解释，说明选型已经进入工程系统；不能解释，说明选型仍停留在会议结论。

模型矩阵还需要和采购流程衔接。采购合同里常写的是调用量、区域、价格和 SLA，平台运行时真正关心的是任务适配、版本稳定、数据处理方式和故障切换。若采购材料和运行配置分离，供应商承诺很难落到工程系统。更实际的做法是在试点阶段就把采购问题转成可验证条款：模型版本是否固定，是否提前通知退役，日志是否可关闭，数据是否用于训练，区域和专线如何配置，限流和故障时的通知机制是什么。

选型还涉及开发体验。模型支持的工具调用格式、结构化输出能力、上下文长度和流式响应方式不同，开发团队需要为这些差异写适配。若平台把差异直接暴露给每个 Agent，应用代码会充满供应商判断；若全部隐藏，又可能让应用误以为所有模型能力相同。LLM Gateway 应提供统一接口，同时把能力差异作为路由条件和评测条件保存下来。这样业务应用不必关心供应商细节，平台又不会把不支持工具调用的模型路由到需要工具调用的任务。

模型升级前要准备回放集。回放集来自真实 Run，包含原始输入、上下文摘要、工具结果、期望输出和风险标签。新模型通过通用评测还不够，还要在这些真实链路上检查结构化输出、拒答、引用、SQL、报告语气和成本变化。回放集用于观察关键行为是否退化，不要求新旧模型输出完全一致。若新模型在部分任务上更好、在高风险任务上更差，平台可以先灰度到低风险场景，而非全局替换。模型选型还涉及组织信任。业务团队容易相信强模型能解决所有问题，平台团队容易担心成本和不可控，安全团队会关注数据边界。选型文档要把这些关注放在同一张决策表里：哪些任务追求质量，哪些任务追求成本，哪些任务受合规限制，哪些任务允许人工兜底。这样讨论就能从“哪个模型最好”转向“哪个任务用哪个模型最合适”。

当模型矩阵成熟后，企业会形成一套稳定节奏。新模型进入候选池，先跑标准评测和真实回放，再进入小流量灰度；线上观察通过后，路由策略逐步扩大；出现异常时，网关切回旧模型并保留差异样本。这个节奏比一次性选型更重要，因为模型生态变化很快，企业真正需要的是持续吸收新模型而不破坏业务的能力。模型矩阵还可以服务容量规划。不同模型的并发、上下文长度和响应时间差异很大，平台不能只按调用次数估算资源。财务问数的少量长上下文请求，可能比客服分类的大量短请求更占资源；代码生成的输出 token 长，可能让排队时间在高峰期明显增加。把这些特征和任务画像绑定后，SRE 才能为模型服务、网关和预算设置合理容量。模型选择也会影响用户期望。强模型慢一些，用户可能愿意等待；低成本模型快一些，但需要把不确定性表达清楚。产品层可以根据任务类型展示不同体验：即时回答、异步报告、需要审批的高风险分析。模型选型还涉及后台策略，也会改变前端交互和 SLA 承诺。

当企业同时使用自建模型和外部模型时，数据分级会成为路由硬约束。公开资料总结可以走外部强模型，客户明细、员工数据和未公开财报应留在本地或专有环境。路由系统要把这些规则写成可执行策略，而非依赖开发者在 Prompt 里提醒模型。这样模型矩阵才能承载合规责任。

5.5 模型矩阵的组织协同

模型矩阵进入生产后，组织协同会直接影响技术效果。模型团队可以维护候选池和评测脚本，但它无法独自判断某个任务能否接受延迟上升、某类拒答是否符合业务语境、某个数据域是否允许外部调用。业务 owner、数据 owner、安全 owner、平台 owner 和采购团队都要参与模型矩阵的维护。协同材料不需要复杂，但必须把任务适配、数据边界、成本预算、质量门禁和回滚责任写在同一处。

组织协同还要避免“强模型兜底”滥用。业务团队遇到质量问题时，容易要求所有请求都切到最强模型；平台团队遇到成本压力时，又容易把任务切到更便宜的模型。两种动作如果缺少样本和边界，都会带来新问题。更合适的做法，是把强模型兜底限定在明确条件下：低置信度、结构化输出连续失败、VIP 客户、监管关键词、高风险报告或人工复核升级。每次兜底都应写入 Trace 和成本视图，后续复盘时判断它是必要保护，还是首选模型和 Prompt 需要修复。

模型矩阵也要支持组织学习。某个业务线长期使用高成本模型，可能说明任务本身复杂，也可能说明语义层、工具返回或报告模板不够稳定；某个低成本模型在评测中达标，线上却频繁触发人工复核，说明评测集没有覆盖真实任务。复盘时不应只讨论换模型，还要看上下游是否需要补能力。模型选型越成熟，越会从“哪个模型更强”转成“哪个任务链路缺哪类证据和能力”。

5.6 模型资料入口

以下链接是本章写作时使用的官方资料入口，适合在做真实选型前重新核对模型版本、区域可用性、上下文长度、计费方式和数据处理条款。正式采购或上线前，再走一遍这些原始资料，通常比相信二手整理更稳妥。

• OpenAI Models
• Anthropic Claude Models
• Google Gemini Models
• Amazon Bedrock Model Availability and Compatibility
• Qwen Documentation
• DeepSeek API Documentation
• Mistral Model Selection Guide
• Meta Llama
• Kimi API Documentation
• 智谱 AI 开放文档
• 百度千帆模型列表

5.7 模型退役与候选池复审

模型选型完成后，还要定期复审候选池。企业平台里常见的问题是模型越接越多：通用模型、代码模型、长上下文模型、小参数本地模型、供应商专用模型和临时试验模型都留在路由表中。候选池膨胀后，路由策略会变复杂，评测样本会变多，成本归因会变难，安全审计也会增加负担。模型矩阵需要进入退役流程。

退役判断应来自运行证据。某个模型长期没有被路由命中，说明它可能没有业务价值；某个模型成本高但质量优势只出现在少数任务上，可以限制到特定场景；某个模型在结构化输出或安全拒答上频繁失败，应移出高风险任务；某个模型依赖的供应商接口不稳定，应降低权重或准备替代。退役流程保留模型能力记录，同时让平台候选池保持可解释。

模型退役还要保护历史 Run。已经生成的报告、Trace、评测样本和用户争议，仍然需要知道当时使用了哪个模型、哪个版本、哪个路由策略。平台可以停止新请求使用某个模型，但保留元数据、评测结果和回放说明。若模型被替换，还要用同一组业务样本比较新旧模型的质量、成本、延迟、格式稳定性和安全行为。这样退役不会造成历史证据断裂。

早期可以每季度做一次模型候选池复审。复审材料包括调用量、任务分布、成本、质量、失败类型、供应商稳定性和安全事件。结论分为继续默认路由、限制到部分任务、移入观察池、冻结新请求和正式退役。模型选型因此会成为持续治理，而不是一次采购或一次技术评测。

5.8 模型接入后的证据与退役

模型接入完成后，平台不能只记录“某个模型可调用”。真正需要长期维护的是模型证据：模型来源、许可证、上下文长度、工具调用能力、成本口径、延迟分布、安全策略、适用任务、失败样本和退役条件。若这些信息分散在网关配置、实验笔记和个人经验里，后续路由调整、成本复盘和事故处理都会依赖人工回忆。模型目录应成为平台资产，而不是模型名称列表。

上线证据要覆盖业务任务。一个模型在通用问答上表现稳定，不代表它适合 NL2SQL、报告生成、工具规划或合规解释。每次接入都应绑定一组任务样本，说明哪些任务通过，哪些任务只能试点，哪些任务不允许进入生产。样本结果要和网关路由、评测记录和安全策略关联。这样当模型升级或降级时，团队能知道哪些业务链路受到影响。

模型退役同样需要计划。某个模型可能因为成本过高、供应商变更、许可证限制、能力落后或安全样本失败而退出生产。退役前要找到依赖它的 Agent、Prompt、评测集、缓存、报告模板和客户承诺；退役后要保留历史 Run 使用的模型版本和输出证据。否则同一个问题在历史报告和新报告中出现差异时，团队无法解释差异来自模型变化、数据变化还是提示词变化。

早期可以为每个生产模型维护一页卡片：用途、租户、路由规则、样本通过率、成本 owner、降级路线、替代模型和退役条件。模型接入就不再是工程团队临时加一个 backend，而是进入可审计、可复盘、可治理的模型生命周期。

5.9 模型能力边界的发布说明

模型基础能力进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把上下文长度、工具调用、结构化输出、拒答边界、成本和已知限制记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第6章推理服务、第8章 Prompt 契约和第45章网关相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括模型升级后输出风格改变、结构化能力退化、调用成本超出业务预算。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

模型发布说明应让业务和平台团队知道能力变化，不能只列供应商版本号。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

本章小结

企业模型选型要建立一套决策系统，不能停留在“某个最强模型”的比较上。任务画像、模型画像、数据边界、SLO、成本和生命周期都要进入同一张选择表。闭源、开放权重、国产、自托管和云模型平台属于不同分类轴，需要拆开评估。国产模型不自动等于合规，开放权重也不自动等于低成本。进入生产后，模型矩阵要靠注册表、评测准入、策略路由、fallback、可观测性和版本治理来维护。模型版本和价格变化很快。生产选型应以实时官方文档、合同条款和企业内部评测为准，本章的模型清单只作为决策框架示例。

参考文献

Liang, P. et al. (2023). Holistic Evaluation of Language Models. TMLR.

NIST. (2023). AI RMF 1.0.

LiteLLM. (n.d.). Documentation.

Hugging Face. (n.d.). Open LLM Leaderboard.

第6章 本地推理引擎的吞吐、延迟与部署边界

本地推理常被低估，因为它看起来像一次部署，实际很快会变成容量、延迟和治理问题。一个模型在单机演示中响应很快，不代表它能同时承接客服摘要、DataAgent 问数和代码助手的高峰请求。推理服务一旦进入平台，就要同时回答吞吐、首 Token 延迟、显存、结构化输出、租户隔离和版本发布这些问题。企业第一次自建推理服务，往往从一个很简单的需求开始：敏感数据不能出域，或者外部 API 成本太高，于是团队把一个开源模型部署到内网 GPU 上，给几个业务试点使用。前几天一切正常，用户量上来后问题开始出现。客服摘要的批量任务把 GPU 占满，DataAgent 的长上下文请求让首 Token 延迟飙升，研发助手的代码生成拖慢普通问答，某个部门临时把最大输出 Token 调大，其他租户的请求开始排队。模型没有坏，平台却已经失去容量控制。

本地推理服务介于模型权重、GPU 资源和平台治理之间。它还涉及把模型跑起来，还要把请求排队、连续批处理、KV Cache、Prefix Caching、量化、结构化输出、流式返回、指标监控和版本发布组织成服务。企业自建推理服务的核心矛盾，是在有限 GPU 上同时满足并发吞吐和单请求延迟，而这两者往往相互拉扯。后台摘要追求吞吐，前台助手追求首 Token，DataAgent 追求结构化输出和长上下文，代码助手追求 Decode 速度。混在同一个服务池里，任何一个场景的优化都可能伤到另一个场景。

推理引擎选型也不能只看 benchmark。vLLM、SGLang、LMDeploy、TGI、Ollama 解决的问题不同，适合的组织阶段也不同。个人验证阶段，启动速度和模型管理体验更重要；生产服务阶段，连续批处理、显存管理、OpenAI 兼容接口、结构化输出、监控和多副本治理更重要；平台级服务阶段，还要考虑 LLM Gateway、租户配额、审计日志、灰度发布、回滚和故障兜底。引擎能力如果不能纳入这些平台流程，速度再快也只能支撑局部试点。本章讨论本地推理、部署形态、吞吐与延迟、连续批处理、KV Cache、Prefix Caching 和推理引擎选型。读者需要先判断工作负载的瓶颈在吞吐、首 Token 延迟、Decode 速度还是显存，再决定使用哪类引擎和优化机制。本地模型服务的目标，是在统一网关、配额、审计和回滚流程下稳定承接企业 Agent 任务；单机速度只是上线判断中的一个维度。

自建推理还有一个容易晚出现的问题：服务上线后，模型团队、平台团队和业务团队看到的不是同一组指标。模型团队说某模型在离线评测里更好，平台团队看到 P99 TTFT 超标，业务团队抱怨流式输出中途断开，安全团队追问 prompt 和输出是否进入日志。若引擎只作为某台 GPU 上的进程存在，这些问题会落到临时排查；若引擎已经接入网关、监控、配额和发布系统，团队就能沿着请求、队列、Prefill、Decode、输出和日志逐步定位。因此，本地推理的早期设计最好把“可运营”放在“极致性能”之前。一个稍慢但有稳定指标、灰度发布和回滚路径的服务，比一个压测数据漂亮却无人能解释排队和显存波动的服务更适合生产。后续第7章会讨论优化技术，本章先建立部署边界：业务应用不直接认识推理引擎，引擎不直接承担租户和合规责任，所有请求都通过统一网关进入可观测、可限制、可替换的服务池。

6.1 本地推理服务的部署入口

企业讨论“本地推理”时，决策点是推理能力是否进入自己的平台边界：模型权重、推理服务、调用协议、配额、日志、成本核算、灰度发布和故障兜底是否都能被企业控制。模型放在云上还是机房，只是部署位置问题。一家多业务线企业如果把客服知识库、生产质检 SOP、财务指标口径和内部代码库都交给外部模型接口处理，就会在数据出域、审计、延迟和成本预测上遇到阻力；如果只是把一个开源模型下载到 GPU 服务器上，用临时脚本启动，也无法支撑多业务、多租户和 Agent 长任务。本地推理引擎位于模型权重和业务应用之间。它把模型文件、GPU/CPU/NPU 资源、请求调度、Token 流式生成、缓存、量化、并行和服务 API 封装成一个可运营的服务。对企业 Agent 平台来说，它通常不直接暴露给最终业务系统，而是被 LLM Gateway、Agent Runtime、RAG 服务和 DataAgent 通过统一协议调用。

flowchart TD
    App["业务应用 / Agent Runtime / RAG / DataAgent"] --> Gateway["LLM Gateway<br/>认证 / 配额 / 路由 / 审计"]
    Gateway --> Router["模型路由<br/>任务类型 / 租户 / SLA"]
    Router --> Local["本地推理服务"]
    Router --> Cloud["外部模型 API<br/>兜底或高阶能力"]
    Local --> Engine["推理引擎<br/>vLLM / SGLang / LMDeploy / TGI / Ollama"]
    Engine --> Model["模型权重<br/>BF16 / FP16 / INT8 / INT4 / GGUF"]
    Engine --> Runtime["硬件资源<br/>GPU / CPU / NPU"]
    Local --> Obs["指标与日志<br/>TTFT / TPOT / 吞吐 / 显存 / 错误"]

图6-1：本地推理服务在企业平台中的位置。来源：本书自绘。Alt text：分层图中部是本地推理服务，向上对接模型网关与各业务 Agent，向下占用 GPU 资源池，左右接入模型仓库与监控，标出它作为"模型能力供给层"的位置。

图 6-1 强调职责分界：业务请求止步于 LLM Gateway 和模型路由，本地推理引擎只作为受治理的服务池。这样后续替换 vLLM、SGLang、LMDeploy、TGI 或 Ollama 时，上层业务契约不需要变化。

这条链路里，应用侧应该只关心“我要哪个能力、最大延迟是多少、能接受什么质量”，而不应该知道某个模型是跑在 vLLM、SGLang、LMDeploy、TGI 还是 Ollama 上。平台侧则要把本地推理服务变成一组可治理的资源池：哪些模型能服务哪些租户，哪些请求可以排队，哪些请求必须降级，哪些模型允许返回结构化输出，哪些请求需要进入审计日志。

服务边界清楚后，后续替换引擎才不会影响业务系统。比如一开始用 Ollama 快速验证内部助手，第二阶段切到 vLLM 承接更多并发，第三阶段为结构化 Agent 任务引入 SGLang；只要网关契约、模型名、生成参数和响应格式保持稳定，业务侧就不必为每次引擎变化重写集成代码。反过来，如果业务系统直接绑定某个引擎的私有参数，迁移时会把 prompt、超时、错误码、流式协议和审计逻辑一起拖进改造。

6.2 吞吐与延迟对部署形态的影响

本地推理服务可以按运行边界分成五种基本形态。它们对应不同负载和组织阶段，不是一条从低到高的成熟度曲线。

表6-1：单机、容器化、集群等推理部署形态的边界、优势与适用场景。来源：本书整理。

第一种形态适合“把模型跑起来”，不适合“把模型管起来”。Ollama 降低了模型下载、量化权重运行和本地聊天的门槛，适合工程师快速比较 Qwen、Llama、Mistral、Gemma 等模型在企业语料上的表现。此时平台团队关注的是模型质量、提示词格式、上下文长度和基本速度，而非高并发。第二种形态开始形成服务边界。许多工具都能暴露 OpenAI 兼容接口，应用代码可以把 base_url 指向企业内网地址，从而复用现有 SDK、Agent 框架和评测脚本。这一步的价值很大：模型服务从“某台机器上的命令行”变成了“可被网关代理的 API”。但它仍然不能替代平台，因为鉴权、限流、审计、灰度、熔断、预算和数据脱敏通常还不在引擎内部完成。

第三种形态是企业最常见的生产起点。一个 7B、14B 或 32B 级别模型可以部署在单节点多卡服务器上，通过连续批处理提高吞吐，通过张量并行放下更大的模型，通过流式输出降低用户感知延迟。一家多业务线企业的内部知识助手如果日常并发在几十到几百之间，通常先从这一形态开始：一个模型服务池承接普通问答，另一个模型服务池承接代码或数据分析任务，中间由 LLM Gateway 做路由。

第四种形态解决平台规模问题。模型更大、上下文更长、租户更多之后，单机多卡会遇到显存、队列和故障隔离上限。此时要把模型副本、GPU 池、请求队列、滚动升级和跨节点通信纳入 Kubernetes、Ray、Triton 或厂商云原生调度体系。难点不止是“更多 GPU”，还包括尾延迟控制：一次长上下文请求可能占用大量 KV Cache，使其它短请求排队。平台必须把请求长度、最大输出 Token、租户优先级和模型副本健康状态纳入路由。

第五种形态服务的是数据边界。制造、门店、金融风控和医疗场景经常要求数据在现场或专用网络内处理。边缘推理通常使用更小模型、更低 bit 量化和更短上下文，牺牲一部分通用能力换取低网络依赖和更强隐私控制。它不适合替代总部模型平台，但适合承接固定流程：设备故障解释、门店 SOP 问答、离线工单摘要、现场质检描述等。本地推理服务上线前，至少要定义五组接口条件。

表6-2：模型、资源等各类服务边界必须回答的问题与平台要求。来源：本书整理。

其中 TTFT（Time To First Token）和 TPOT（Time Per Output Token）是推理服务最重要的两个延迟指标。TTFT 主要受排队、Prefill、上下文长度和调度影响；TPOT 主要受 Decode 阶段、并发批大小、显存带宽和采样策略影响。企业不要只看“每秒多少 Token”，还要看 P95/P99 TTFT 是否稳定。对客服和办公助手来说，用户往往能接受总生成时间稍长，但不能接受首 Token 长时间无响应；对离线摘要和批量标注来说，吞吐和成本比交互延迟更重要。

图6-2：吞吐与延迟的取舍曲线。来源：本书自绘。Alt text：横轴为并发吞吐、纵轴为单请求延迟的曲线，随批量增大吞吐上升但延迟也升高，曲线上标出"延迟敏感区"和"吞吐优先区"两段不同的工作点选择。

图 6-2 表达部署形态的相对位置，不是某个引擎的精确 benchmark。右侧三类策略分别对应交互负载的 TTFT、后台任务的吞吐，以及平台层的限流、熔断、请求长度治理和成本核算。

6.3 调度、缓存与约束：引擎能力的共同底座

大模型推理的核心成本来自两个阶段：Prefill 和 Decode。Prefill 阶段把输入上下文一次性送入模型，计算所有输入 Token 的注意力并写入 KV Cache；Decode 阶段每次生成一个或一小批新 Token，并在每一步读取历史 KV Cache。输入越长，Prefill 越重；输出越长，Decode 越重；并发越高，KV Cache 对显存的压力越大。

sequenceDiagram
    participant C as Client
    participant S as Scheduler
    participant M as Model Runtime
    participant K as KV Cache

    C->>S: prompt + generation config
    S->>M: Prefill input tokens
    M->>K: write KV Cache
    M-->>C: first token
    loop Decode until EOS or max_tokens
        S->>M: schedule active requests
        M->>K: read/write KV Cache
        M-->>C: stream next token
    end

推理优化要在不明显牺牲回答质量的前提下，减少显存占用、提高 GPU 利用率、降低排队时间或减少每个 Token 的计算量。常见机制如下。

表6-3：连续批处理、缓存等优化机制的目标、思路与风险。来源：本书整理。

连续批处理是生产推理服务的基础优化。传统批处理会等一组请求凑齐再一起执行，某个请求生成完成后，其余请求仍要继续等待同一批结束；连续批处理则在每个 Decode step 重新调度活跃请求，完成的请求立即释放位置，新请求可以插入进来。这样可以提高 GPU 利用率，尤其适合请求长度差异很大的在线服务。代价是调度器变成核心组件：如果只追求吞吐，长请求可能挤占短请求；如果只追求短请求延迟，吞吐会下降。

KV Cache 是大模型推理绕不开的内存问题。Transformer 自回归生成时，每一步都需要访问历史 Token 的 Key 和 Value。缓存这些中间结果可以避免重复计算，但会随着上下文长度、层数、头数和并发请求线性增长。以企业知识问答为例，一段包含政策、表格和引用的长上下文可能让单个请求占用大量显存；如果同时来几十个长请求，模型权重本身还没满，KV Cache 已经成为瓶颈。

PagedAttention 和分页式 KV 管理的价值就在这里。vLLM 论文提出将 KV Cache 按 block 管理，减少内存碎片，并允许请求之间共享缓存块。这个思想影响了后续大量推理引擎。对平台工程师来说，不必把它理解成单个产品功能，而应理解成一类设计：不要按最大上下文为每个请求一次性预留连续显存，而要把可变长序列映射到更灵活的内存块。这样可以提高并发容量，但也要求引擎、注意力 kernel 和调度器紧密配合。

Prefix Caching 适合企业 Agent 平台。许多 Agent 请求共享相同的系统提示词、工具说明、安全规则和企业背景资料。如果这些前缀每次都重新 Prefill，会浪费大量计算。前缀缓存可以把相同前缀的 KV Cache 复用起来，让后续请求只计算新增部分。它的收益取决于 prompt 规范化：同一段系统提示词里如果混入时间戳、随机 trace id 或不稳定字段，缓存命中率会明显下降。平台应把动态字段放在后缀，把稳定规则放在前缀。

量化解决的是显存和带宽。权重量化把模型参数从 BF16/FP16 压到 INT8、INT4、FP8 等格式，能让更大的模型放进有限显存，也能减少内存带宽压力。KV Cache 量化则进一步降低长上下文并发时的显存占用。风险是模型质量可能下降，尤其在数学、代码、长上下文检索和结构化输出场景中更明显。企业上线量化模型前，需要用自己的评测集验证，覆盖客服工单、财务口径、SQL 生成、工具调用和安全拒答，而非只看通用榜单。

张量并行和流水并行用于大模型多卡部署。张量并行把同一层的大矩阵计算切分到多张 GPU 上，适合单层参数太大或吞吐要求高的场景；流水并行把不同层放到不同 GPU 上，适合模型深度较大但会引入 pipeline bubble。在线 LLM 服务更常用张量并行，因为它对单请求延迟更友好。并行不是免费午餐：GPU 间通信、NCCL 配置、拓扑、PCIe/NVLink 差异都会影响实际吞吐。

推测解码用一个更小或更快的 draft model 先生成候选 Token，再由目标模型一次性验证多个 Token。如果候选命中率高，Decode 阶段会加速；如果命中率低，额外 draft 计算反而浪费。它更适合分布稳定、输出风格明确的场景，例如代码补全、格式化摘要、固定模板客服回复；对复杂推理和高随机采样的对话，收益不一定稳定。结构化输出约束对 Agent 很关键。企业平台大量调用要返回 JSON、函数参数、SQL 片段或工作流下一步动作，不能按自由聊天处理。仅靠提示词要求“请输出合法 JSON”并不可靠。推理引擎如果支持 grammar、regex、JSON schema 或 guided decoding，就能在解码阶段限制非法 Token，减少解析失败和重试成本。这里的取舍是：约束越强，格式越稳；但如果 schema 设计不合理，模型可能生成空洞字段或被迫输出语义不自然的内容。优化不能孤立启用。一个常见错误是同时打开最大上下文、最高并发、最激进量化、Prefix Caching 和推测解码，然后只用单条 prompt 测速度。正确做法是按工作负载分层测试：

表6-4：不同工作负载的主要瓶颈与应优先采取的优化。来源：本书整理。

6.4 引擎选型：vLLM、SGLang、LMDeploy、TGI、Ollama

主流推理引擎的差异，不能用“谁更快”概括。企业选型应先确定四个问题：模型来源是什么，硬件资源是什么，服务接口要多标准，负载是在线还是离线，平台团队是否具备底层调优能力。

表6-5：vLLM、SGLang、LMDeploy、TGI、Ollama 的定位、优势与适用场景。来源：本书整理。

vLLM 常被作为企业本地推理的默认起点。它围绕 PagedAttention、连续批处理、前缀缓存、分布式推理和 OpenAI 兼容 API 构建，适合把开源模型快速服务化。对一家多业务线企业这类要同时服务知识问答、客服、办公助手和 DataAgent 的平台，vLLM 的优势是“够通用”：模型支持广，API 易接入，社区资料多。选用 vLLM 时，平台团队要重点压测三类指标：长上下文下的 KV Cache 压力，高并发短请求下的 TTFT，结构化输出和工具调用的稳定性。TGI 适合已经围绕 Hugging Face 建模、下载、评测和部署的团队。它提供生产化文本生成服务能力，支持连续批处理、张量并行和流式输出。它的优势不在单点性能绝对领先，而在 Hugging Face 生态的一致性：模型仓库、Tokenizer、配置和部署文档相互衔接。企业如果模型治理和微调流程已经落在 Hugging Face 体系内，TGI 可以减少集成成本。

SGLang 的特点是把推理服务和结构化生成程序结合得更紧。它关注的不止是“给 prompt 返回文本”，还包括多轮分支、约束解码、工具调用和复杂生成流程。SGLang 的 RadixAttention 面向前缀和 KV Cache 复用，适合大量共享上下文或程序化生成的场景。Agent 平台如果经常让模型在固定系统提示词、工具 schema 和中间状态之间来回生成，SGLang 值得单独压测。LMDeploy 在中文开源模型和量化部署场景中经常出现。它的 TurboMind 后端、量化支持和 OpenAI 兼容服务，适合希望快速把 Qwen 等模型跑成 API 的团队。是否作为平台主引擎，取决于企业模型族、硬件、稳定性验证和团队熟悉度。Ollama 代表轻量本地路线。它把模型拉取、运行和本地 API 管理做得简单，适合开发者试模型、业务原型和低并发内部助手。它可以进入企业平台，但定位应清楚：它服务离线、边缘、低并发或快速验证场景，不能替代数据中心 GPU Serving。企业可以按下面的规则做第一轮筛选。

表6-6：按决策条件选择推理引擎的首选方向与原因。来源：本书整理。

mini-platform 在 v0.1 不应把某个引擎写死为唯一实现，而应在 core/gateway/ 抽象出统一调用契约。一个合理的接口最少包含：模型名、输入消息、生成参数、租户信息、trace id、超时、流式开关和结构化输出 schema。底层可以先接 vLLM 或 TGI，后续再挂 SGLang、LMDeploy、Ollama 等服务。

{
  "model": "qwen3-32b-instruct",
  "messages": [
    {"role": "system", "content": "你是一家多业务线企业内部助手。"},
    {"role": "user", "content": "总结本周客服投诉的三个主要原因。"}
  ],
  "tenant": "retail-customer-service",
  "stream": true,
  "timeout_ms": 30000,
  "generation": {
    "temperature": 0.2,
    "max_tokens": 1024
  },
  "response_format": {
    "type": "json_schema",
    "schema_name": "complaint_summary"
  }
}

这个契约的目的，是把业务调用和推理引擎解耦。一家多业务线企业可以先用 vLLM 服务知识助手，用 SGLang 服务结构化 Agent 流程，用 LMDeploy 服务中文开源模型快速评测，用 Ollama 服务门店离线节点；上层应用仍然只调用同一个网关。平台能力不取决于“选择了哪个最快的引擎”，而取决于是否能持续测量、路由、降级和替换。实际落地时，建议把每个引擎的接入都当作一次供应能力登记。登记内容包括支持的模型族、上下文长度、并发上限、结构化输出能力、流式协议、错误码、监控指标和回滚方式。这样网关路由时可以按能力和风险选择目标服务：客服摘要走吞吐优先池，DataAgent 走结构化输出更稳定的池，敏感租户走私有化池，临时高峰再使用外部模型兜底，而不是盲目按模型名转发。登记完成后，还要把能力暴露给发布流程。新模型服务上线时，发布单里应包含压测报告、失败样例、兼容的请求格式和已知限制；下线旧引擎时，也要说明哪些租户、哪些任务和哪些评测集已经迁移。这样推理层不会变成一组长期无人敢动的服务端口。

6.5 推理引擎接入统一网关的条件

推理引擎进入平台统一网关前，至少要通过下面这些检查。检查的目的，是确认协议、观测、配额和错误语义都已经落到同一条接入标准上。

• 模型 License、权重来源、量化方式和上线版本可追溯。
• OpenAI 兼容接口或内部统一接口通过网关代理，不允许业务直连裸引擎。
• 压测覆盖短请求、高并发、长上下文、批量任务和结构化输出。
• 指标至少包含 TTFT、TPOT、tokens/s、队列长度、显存占用、KV Cache 使用率、错误率。
• 网关限制最大输入、最大输出、超时、租户额度和并发。
• 引擎升级、模型切换和量化版本发布有灰度和回滚方案。
• 日志策略明确区分调试日志、审计日志和敏感内容留存。

6.6 上线证据与故障诊断链路

推理服务上线时，平台不能只保存一份压测截图。更可用的上线证据应覆盖四类材料：服务版本、负载边界、质量回归和故障预案。服务版本包括模型权重 digest、Tokenizer 版本、推理引擎版本、镜像版本、启动参数、量化格式和上下文上限。负载边界包括短请求、长上下文、批处理、结构化输出和流式输出的压测结果，并明确每类负载的 P95/P99 TTFT、TPOT、错误率和显存峰值。质量回归要使用企业自己的样本，覆盖摘要、RAG、DataAgent、结构化 JSON、拒答和敏感内容处理。故障预案则要说明队列堆积、KV Cache OOM、流式中断、模型输出格式漂移、节点重启和网关熔断时的恢复动作。

这些证据需要进入发布记录，而不是散落在聊天记录或压测脚本目录里。模型服务一旦被多个业务 Agent 共享，任何一次参数调整都会影响上层任务。把 max_model_len 调大，可能让长上下文问答变好，也可能让短请求排队；把温度默认值改低，可能让结构化输出更稳定，也可能让客服回复更僵硬；把量化版本切换到 INT4，可能降低成本，也可能让 NL2SQL 和代码生成退化。发布记录要能回答“本次变化影响了哪些租户、哪些任务、哪些评测样本和哪些回滚路径”。没有这些材料，故障发生后只能凭经验猜。

故障诊断应沿请求链路展开。用户看到首 Token 很慢时，平台先看网关排队，再看模型路由，再看引擎队列和 Prefill 时长；若问题集中在长上下文请求，就继续检查上下文长度、Prefix Cache 命中率和 KV Cache 占用。用户看到流式输出中断时，不能只看模型进程是否存活，还要检查代理超时、客户端断连、网关重试和引擎错误码。结构化输出解析失败时，也要区分模型自由生成、guided decoding 配置、schema 版本和下游工具校验。诊断链路写清后，平台团队才能判断是扩容、限流、降级、切换模型，还是回滚引擎版本。

本地推理服务还要准备降级策略。低风险摘要任务可以在本地服务拥堵时转入异步队列；普通知识问答可以切到更小模型或外部兜底模型；DataAgent、财务、合同和高风险工具调用不能简单降级为“随便给一个答案”，应停在可解释错误、人工复核或稍后重试。降级策略要写进网关路由和运行记录。一次降级如果没有进入 Trace，后续评测会误以为模型正常回答，只是答案质量波动。推理层的生产化能力，最终体现在这些不起眼的运行证据和故障路径上。

6.7 推理服务的发布准入与运行台账

本地推理服务从“能跑”进入“可发布”，中间隔着一套运行台账。台账的第一部分是资产来源：权重来自哪个仓库，License 是否允许企业使用，是否经过量化或合并，Tokenizer 与模型配置是否匹配，镜像和启动参数是否可复现。很多推理事故并不来自模型本身，而来自部署材料缺失。权重被替换、Tokenizer 版本不一致、量化参数没有记录、镜像标签复用，都会让团队在故障时无法回到上一个稳定状态。

台账的第二部分是能力边界。每个 backend 都应记录支持的上下文长度、最大并发、推荐 batch、流式协议、结构化输出能力、工具调用兼容性和已验证任务类型。这个边界不能只写成理论上限。一个模型宣称支持 128K 上下文，并不代表它在企业 RAG、DataAgent 和报告生成中都能稳定运行。发布记录应写出实测条件：硬件类型、GPU 数量、显存、并发、Prompt 长度、输出长度、P95/P99 延迟、错误率和失败样例。这样网关在路由时才能知道某个 backend 适合客服摘要，还是适合长上下文分析。

台账的第三部分是降级与回滚。推理服务出问题时，平台不能只提供“重启服务”这一种动作。队列拥塞可以限流或转异步，长上下文 OOM 可以缩短上下文或切到高显存池，结构化输出失败可以切换 guided decoding 配置或高精度 backend，流式中断可以调整代理超时或改成非流式返回。不同故障对应不同恢复路径。把这些路径写进发布台账，SRE 和平台团队才能在事故时快速判断，而不是临时翻配置。

台账还应与 Trace 和成本视图连接。一次请求经过哪个网关规则、哪个模型版本、哪个 backend、哪个量化格式、哪个缓存策略，都要能回查。否则上层 Agent 的质量波动会被误判成 Prompt 或业务问题。比如 DataAgent 的 SQL 正确率下降，可能来自模型版本切换，也可能来自量化、采样参数、schema 变更或网关路由调整。推理层如果没有记录，评测团队只能看到结果变差，却无法定位原因。

早期平台可以从轻量台账开始：每个模型服务保留一份资产清单、一份压测报告、一组任务评测样本、一份错误码说明和一条回滚路径。台账不必覆盖所有细节，但必须让平台回答四个问题：当前服务是什么版本，适合哪些任务，发生故障时先看哪里，出现质量退化时如何回到上一版。能回答这些问题，本地推理才算进入平台能力，而不是一组临时启动的进程。

6.8 推理服务的周期复审

推理服务上线后还要定期复审。复审内容包括模型和引擎版本是否仍被维护，License 与权重来源是否仍符合企业要求，评测集是否覆盖新增任务，成本和延迟是否偏离基线，回滚目标是否仍可启动。很多推理服务刚上线时材料完整，半年后因为补丁、量化、镜像替换和路由调整，已经无法复现最初状态。周期复审的目的，是让模型服务保持可解释、可替换和可退回，而不是等事故发生后再补台账。复审结论也应进入发布记录。

6.9 推理服务的异常回放与回滚边界

推理服务的异常回放要覆盖模型、引擎、网关和请求形态。一次线上投诉可能表现为首 token 很慢、流式响应中断、结构化输出缺字段、相同问题前后答案不同，排查时不能只看模型名称。平台应保存必要的回放材料：模型服务名、Revision、权重 digest、引擎版本、启动参数、上下文长度、输入 token、输出 token、采样参数、网关路由、租户配额和错误码。涉及敏感数据时，回放材料可以脱敏或只保存摘要，但必须能解释运行条件。

回放材料还要区分“可重跑”和“不可重跑”。普通问答可以在隔离环境重放；写操作、外部系统调用和审批类请求不能直接重放，只能重放模型输入、工具返回摘要和网关决策。若平台没有这个边界，事故复盘时很容易为了定位问题再次触发副作用。第23章工具契约、第30章 HITL 和第38章 Trace 都要参与这条链路：工具结果提供证据摘要，审批记录说明人工确认状态，Trace 串起请求、模型和工具阶段。

回滚边界也要提前写清。引擎版本回滚通常比模型回滚更快，但它可能改变 batching、缓存和结构化输出行为；模型回滚可以恢复质量，但可能和当前 Prompt、schema 或向量索引不兼容；网关策略回滚可以立即恢复路由，却无法修复引擎内部 OOM。上线材料要说明每类回滚的触发条件、预计耗时、影响范围和验证样本。这样推理引擎才能成为可诊断、可回放、可恢复的平台部件。

6.10 推理服务与业务高峰的联动演练

推理服务需要和业务高峰一起演练。月末关账、促销活动、客服高峰、集中报告生成、批量评测都会改变请求形态。平时稳定的模型服务，到了高峰期可能因为长上下文、流式连接、工具等待和批处理排队出现尾延迟。平台不能只等监控告警触发，而要在业务高峰前准备样本、容量、降级策略和回滚路径。

演练材料应包含真实任务组合。客服场景要看首 token、连续对话和知识引用；DataAgent 要看 NL2SQL、查询等待和报告生成；批量评测要看队列和成本；报告场景要看长输出、EvidenceRef 和导出动作。每类任务都要设定可接受延迟、失败提示和降级模型。若高峰期间需要临时扩容，扩容结束后的回收和成本归因也要进入演练结论。

这类演练能把模型服务从单点能力拉回业务节奏。业务 owner 知道哪些任务会被保护，SRE 知道哪些池需要预热，平台团队知道网关如何限流，FinOps 知道临时成本来自哪次活动。第6章的推理服务因此连接到第43章 GPU 调度、第45章网关和第41章成本治理，形成上线前后都能复盘的运行证据。

6.11 推理服务容量变更的验收

推理服务上线后，容量变更比首次部署更常见。新增模型副本、切换量化版本、调整 KV cache、开启 speculative decoding、修改批处理参数，都会改变延迟、吞吐、成本和输出稳定性。容量变更不能只看压测结果，还要回放真实业务样本，确认结构化输出、工具参数、长上下文回答和安全拒答没有退化。很多故障发生在“性能优化成功，业务输出变差”的位置。

容量变更应留下发布记录。记录包括模型版本、引擎版本、GPU 类型、显存配置、batch 参数、并发限制、路由权重、灰度范围、回滚目标和观察窗口。若变更后 p95 延迟下降，但格式错误率上升，平台需要知道这次变化来自推理引擎还是模型路由；若某个租户成本突然上升，也要能回到路由和 batch 参数。推理服务是平台共享底座，缺少这些记录会让多个应用同时受到影响。

早期可以先建立几类固定回放样本：短问答、长上下文、结构化 JSON、工具参数生成、拒答和高并发报告任务。每次容量变更都跑这些样本，再观察真实流量中的超时、重试、截断和人工退回。这样推理服务优化会围绕业务稳定性展开，单次 benchmark 数字只作为其中一类证据。

6.12 推理服务的变更影响面评估

推理服务的变更往往影响多个上层系统。一次引擎升级可能改变流式事件节奏，前端会感到输出抖动；一次量化切换可能让结构化 JSON 错误增加，Tool Registry 和 DataAgent 会受到影响；一次上下文长度调整可能让 RAG 质量改善，却让短请求排队变长；一次网关路由调整可能改变数据出域路径。变更前要列出影响面，至少覆盖前端、Runtime、Tool Registry、DataAgent、Trace、Eval、安全和成本视图。

影响面评估要从任务样本出发。平台可以为每类推理服务维护固定样本：客服摘要、知识问答、长文档 RAG、NL2SQL、结构化输出、拒答样本、流式报告和高并发批任务。每次变更都跑这些样本，记录质量、延迟、错误码、降级动作和人工复核结果。若某个变更只影响低风险摘要，可以小范围灰度；若影响结构化输出或高风险拒答，就要提高发布门槛，并保留旧服务池。

早期影响面评估可以写进发布单。发布单不需要很长，但要说明变更对象、受影响任务、回放样本、灰度范围、回滚目标和观察指标。这样推理服务不会因为底层优化而让上层 Agent 悄悄退化。推理层越共享，变更评估越重要。

6.13 推理服务的运行证据归档

推理服务进入平台后，日常运行证据要能被长期归档。一次请求经过业务入口、LLM Gateway、模型服务池、调度队列和流式输出，任何一层只留下局部日志，事故复盘都会变成猜测。运行证据应覆盖请求进入时的租户、任务类型、模型路由、引擎版本、资源池、输入长度、输出长度、错误码、重试动作、降级动作和最终用户可见结果。这样第38章的 Trace 才能把模型服务行为和上层 Agent 行为接起来。

归档不是把所有 token 和上下文永久保存。企业环境中，提示词、用户输入、检索片段和模型输出可能包含敏感信息，平台要区分可长期保存的结构化元数据、需要脱敏保存的文本摘要、只在短窗口内保留的原始内容。对推理服务而言，最有价值的是能够解释运行事实的字段：请求为什么进入这个池，为什么排队，是否触发降级，是否被限流，是否命中过缓存，是否因超时重试。缺少这些字段时，后续排查很容易把模型质量、资源不足和网关策略混在一起。

早期可以先建立模型服务运行台账，把每次发布和每天运行的汇总证据放在一起。发布侧记录模型、引擎、资源、参数和回滚目标；运行侧记录请求量、延迟分位数、错误类型、拒答变化、结构化输出错误和人工退回样本。若某次业务争议发生在报告生成或 DataAgent 查询中，团队可以沿着台账追到当时的推理服务状态，而不是只看最终回答文本。推理服务越接近共享基础设施，就越需要这种可审计的运行记忆。

运行证据还应进入容量规划。若台账显示高峰时段主要由长上下文报告占用显存，平台可以调整独立池或异步队列；若结构化输出错误集中在某个量化版本，路由可以把工具调用任务迁回更稳定的服务；若某个租户反复触发限流，FinOps 和业务 owner 可以重新确认配额。推理层的治理价值不在于记录更多日志，而在于让发布、排障、成本和容量决策使用同一组事实。

6.14 开源模型上线后的责任边界

开源模型进入企业平台后，责任边界会变得更具体。模型权重、推理框架、量化方式、服务镜像、许可证、微调数据和安全样本都可能由不同团队维护。若平台只把它当作“可自托管模型”，生产事故时很难判断责任归属：是权重选择错误、量化损伤、镜像构建问题、网关路由问题，还是业务样本没有覆盖。

上线前要把责任写进模型发布材料。模型团队负责权重来源、评测和能力边界；平台团队负责服务稳定性、资源、路由和回滚；安全合规团队负责许可证、数据来源和风险样本；业务 owner 负责确认任务是否适合使用该模型。每个角色都需要可验证材料，而不是口头认可。这样开源模型的灵活性不会变成责任真空。

开源模型还要处理补丁节奏。推理框架、CUDA、驱动、算子库和安全依赖都会更新，某个依赖升级可能改变吞吐、延迟或输出稳定性。平台应为开源模型建立版本锁定、回放样本和回滚镜像。若模型承担高风险任务，依赖升级要像模型升级一样进入发布门禁。

早期可以把开源模型分成三类：实验模型、内部低风险模型和生产模型。实验模型允许快速试错；内部低风险模型要求基础评测和成本记录；生产模型要求许可证、样本、镜像、路由、降级和退役材料齐备。这样的分级能保留开源模型的迭代速度，也能避免生产系统被非受控实验影响。

6.15 推理服务的上线证据

推理服务进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把模型版本、吞吐、延迟、错误码、降级路由、灰度范围和回滚条件记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第44章模型服务、第45章网关和第41章成本治理相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括压测只覆盖平均延迟、错误码无法区分模型失败和网络失败、回滚后缓存仍指向旧结果。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

推理服务上线应留下可复查证据，使模型质量、成本和可用性可以共同判断。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

本章小结

本地推理不是“下载模型并启动服务”。进入企业平台后，权重来源、推理引擎、调度策略、资源池、日志、审计和路由都要纳入同一条运行边界。业务应用通过 LLM Gateway 使用统一契约，平台再根据租户、任务类型、SLO 和成本把请求分配到合适的模型服务池。吞吐和延迟必须按工作负载评估。交互式助手关注 TTFT，长上下文 RAG 关注 Prefill 和 KV Cache，批处理任务关注 tokens/s 和成本，DataAgent 还要关注结构化输出与工具调用的稳定性。vLLM、SGLang、LMDeploy、TGI、Ollama 的价值点不同，选型要和第7章的优化评测联动，尤其要覆盖 KV Cache、Prefix Cache、量化和结构化输出能力。真正成熟的推理层，是业务高峰、模型升级和引擎替换发生时仍能解释请求去了哪里、为什么排队、何时降级、怎样回滚。

参考文献

Kwon, W. et al. (2023). Efficient Memory Management for Large Language Model Serving with PagedAttention. SOSP.

vLLM. (n.d.). Documentation.

SGLang. (n.d.). Documentation.

Hugging Face. (n.d.). Text Generation Inference documentation.

NVIDIA. (n.d.). TensorRT-LLM documentation.

第7章 推理优化技术

客服摘要服务上线后，平台团队发现 GPU 利用率很高，首 Token 延迟却没有明显下降。有人建议打开量化和投机解码，也有人建议扩大 batch。排查后才发现，几类负载混在一起：客服摘要追求吞吐，DataAgent 追求结构化输出正确率，知识助手又被长上下文 Prefill 拖慢。推理优化不能按“能开就开”的思路做。KV Cache、Prefix Cache、量化、投机解码都可能降低成本或延迟，也可能带来质量回退、显存碎片、调度复杂度和排障成本。企业平台需要先定位瓶颈，再选择机制，并用同一批业务评测样本确认优化没有破坏结果质量。

优化事故往往来自机制用在了错误瓶颈上。一个服务 TTFT 高，可能是请求排队，也可能是长上下文 Prefill，也可能是 Prefix Cache 命中率低；Decode 慢，才更适合考虑投机解码或模型大小；显存紧张，才优先看 KV Cache 管理、上下文限制和量化。如果不先分清这些位置，团队会把所有开关都打开，最后得到一个更快但更难解释的系统。

企业场景还要把质量回归放在同等位置。量化可能让财务口径解释变得不稳定，KV Cache 量化可能影响长上下文推理，投机解码在固定模板摘要里收益明显，在复杂 DataAgent 推理里收益不一定稳定，Prefix Cache 如果把动态字段放进前缀，命中率会很低。推理优化要在吞吐、首 Token、显存、质量和排障成本之间做选择；若只压低延迟和成本，系统可能更快地给出更难解释的结果。

本章讨论推理优化、KV Cache、Prefix Cache、投机解码、量化和瓶颈定位。读者需要区分显存、首 Token 延迟、吞吐和 Decode 速度这几类瓶颈，并为每一项优化设计验证方法：它改善了哪个指标，影响了哪些业务样本，失败时如何回滚，是否改变结构化输出、拒答和工具调用质量。没有这套验证，优化就会从工程能力变成新的不确定性来源。

生产环境里的优化通常是逐步累积的。第一次上线可能只打开连续批处理，第二次为了长上下文加入分页 KV，第三次为了成本做权重量化，第四次为了模板摘要尝试投机解码。每一步单独看都有理由，但叠加后排障会变难：一次回答变慢，可能是排队策略变化；一次 JSON 解析失败，可能是量化影响了结构化输出；一次短请求被拖慢，可能是同池长上下文请求占满 KV Cache。优化要像发布模型一样管理版本，记录配置、指标、评测结果和回滚条件。

对企业平台来说，推理优化还会牵动组织责任。模型团队往往关注输出质量，SRE 关注延迟和可用性，FinOps 关注单位 Token 成本，业务团队关注任务是否完成。若没有统一评估口径，某个团队看到的“优化成功”可能是另一个团队看到的质量退化。比较稳的做法，是每次优化都明确受益负载、可能受损负载和观察窗口，在灰度阶段同时看性能、成本、结构化输出、拒答、安全拦截和人工反馈。

7.1 先定位瓶颈，再选择优化机制

第 6 章讨论“选哪个推理引擎、如何理解吞吐与延迟的取舍”。进入具体优化后，判断标准要更朴素：这个机制能否稳定降低成本、延迟或显存占用，同时不破坏模型质量和业务正确性。优化名词是否先进，并不构成上线理由。一家多业务线企业的内部知识助手、客服摘要、DataAgent 和代码助手面对的瓶颈并不相同。知识助手常见瓶颈是长上下文 Prefill 和 KV Cache 显存；客服摘要常见瓶颈是批量吞吐；DataAgent 常见瓶颈是结构化输出正确率和重试成本；代码助手常见瓶颈是 Decode 阶段每 Token 延迟。推理优化必须先识别瓶颈，再选择机制。盲目打开所有优化选项，往往会扩大故障面，服务也未必更稳定。

flowchart TD
    Req["请求<br/>prompt / tools / generation config"] --> Queue["调度队列"]
    Queue --> Prefill["Prefill<br/>处理输入上下文"]
    Prefill --> KV["KV Cache<br/>保存历史 Key / Value"]
    KV --> Decode["Decode<br/>逐 token 生成"]
    Decode --> Out["流式输出"]

    Prefix["Prefix Cache"] --> Prefill
    Spec["Speculative Decoding"] --> Decode
    Quant["量化<br/>权重 / 激活 / KV Cache"] --> Prefill
    Quant --> Decode
    KVOpt["KV Cache 管理<br/>分页 / 复用 / 淘汰 / 卸载"] --> KV

推理优化可以按作用位置分成四类：KV Cache 优化作用在显存与长上下文并发；Prefix Cache 作用在共享前缀的重复 Prefill；Speculative Decoding 作用在 Decode 阶段的逐 Token 生成；量化作用在模型权重、激活和 KV Cache 的存储与带宽。它们可以组合，但组合前必须有评测和回滚依据。

图7-1：推理优化机制作用位置。来源：本书自绘。Alt text：一条从请求进入到 Token 输出的推理流水线，标出批处理作用于调度阶段、KV/Prefix Cache 作用于 Prefill、量化作用于权重加载、投机解码作用于 Decode，体现各机制处在流水线的不同环节。

图 7-1 先按瓶颈位置组织优化机制：Prefill 重就看前缀复用和上下文治理，Decode 慢再看推测解码，显存紧张才优先看 KV 管理和量化。图中的指标监控和质量评测是所有组合优化的前提。

定位瓶颈时，日志粒度要能支撑拆解。一个请求的总延迟至少应拆成网关排队、调度等待、Prefill、首 Token、Decode、工具等待和流式传输几个部分。否则团队看到“请求慢”只能猜测原因。对 DataAgent 这类任务，还要把模型生成 SQL、执行 SQL、解释结果和生成图表分开记录；如果只记录最终耗时，推理优化可能会掩盖真正瓶颈，例如 OLAP 查询或权限校验。

7.2 KV Cache：显存和长上下文的主约束

KV Cache 是自回归 Transformer 推理的核心缓存。模型生成第 t 个 Token 时，需要访问前面所有 Token 的 Key 和 Value。如果每一步都重新计算完整上下文，生成会极慢；因此推理引擎会在 Prefill 阶段把输入 Token 的 Key/Value 写入缓存，在 Decode 阶段每生成一个新 Token，就追加一份新的 Key/Value。这样可以避免重复计算历史上下文，但显存占用会随上下文长度和并发请求快速增长。KV Cache 的规模可以用一个近似公式理解：

KV Cache bytes
≈ batch_size
  × sequence_length
  × num_layers
  × 2
  × num_kv_heads
  × head_dim
  × bytes_per_element

这里的 2 代表 Key 和 Value 两份缓存。公式背后有三个直接含义：长上下文会同时增加 Prefill 计算和 Decode 阶段显存占用；并发请求越多，KV Cache 会按活跃序列数叠加；FP16/BF16 降到 FP8 或 INT8 时，bytes_per_element 变小，可承载的上下文和并发也会随之变化。

图7-2：KV Cache 如何随上下文和并发增长。来源：本书自绘。Alt text：三维示意图中 KV Cache 显存占用随上下文长度和并发请求数同时上升，标出显存上限平面，超过即触发排队或拒绝，说明长上下文与高并发共同挤占显存。

图 7-2 把公式落到容量规划：上下文长度、活跃请求数和 bytes_per_element 分别对应请求治理、调度限流和 KV Cache 量化。评估长上下文、并发和显存预算时，可以反复对照这三个变量。以平台工程视角看，KV Cache 有四种典型压力。

表7-1：显存与上下文压力的来源、现象、根因与处理方式。来源：本书整理。

优化显存占用时，应先减少无效上下文，再讨论压缩。企业 RAG 常犯的错误是把检索到的文档全部塞进 prompt，以为长上下文模型能自动消化。实际结果是 TTFT 变长、KV Cache 占用上升、并发下降，无关证据还会增加幻觉风险。更可靠的做法是先做检索质量、去重、片段压缩和引用选择，再把必要上下文送入模型。分页式 KV 管理解决的是显存碎片和混合长度请求的问题。以 vLLM 的 PagedAttention 为代表，推理引擎不再为每个请求按最大上下文预留连续显存，而是把 KV Cache 拆成固定大小的 block，像虚拟内存一样映射到物理显存。TensorRT-LLM 等高性能推理栈也提供 KV Cache 复用、卸载和淘汰相关能力。平台团队不需要手写这些机制，但要理解它们对并发容量的影响：同一张 GPU 能跑多少请求，很多时候取决于 KV Cache 管理，而不只取决于模型权重。

KV Cache 淘汰和卸载需要按请求价值分层。正在 Decode 的请求要保留；刚完成、可能被共享前缀命中的缓存可以短期保留；低命中概率或低优先级租户的缓存可以优先淘汰；极长上下文可以考虑 CPU offload，但要接受 PCIe 传输带来的延迟波动。企业平台要把缓存策略纳入 SLO，不能把它完全交给引擎内部默认值。KV Cache 量化把 BF16/FP16 降到 FP8 或更低 bit，可以提升长上下文并发能力，但要单独做质量回归。客服摘要这类容错较高的任务，FP8 KV Cache 可能是合理选择；财务口径解释、SQL 生成、合规拒答和代码生成，则要用业务评测集确认输出质量、格式稳定性和事实一致性没有明显回退。

KV Cache 还涉及多租户公平性。长上下文租户如果没有上限，会持续占用显存，让短请求在队列里等待；短请求如果优先级过高，又可能让长任务长期得不到执行。平台需要把上下文长度、最大输出、缓存保留时间和租户优先级写进网关策略。这样调度器面对显存压力时，知道应该拒绝超长输入、压缩上下文、转入批处理，还是让低优先级请求排队。KV Cache 优化的发布前检查项如下。

• 明确每个模型的最大上下文、默认上下文和租户级上限。
• 监控 KV Cache 使用率、命中率、淘汰次数、显存碎片和请求排队时间。
• 分别压测短请求、高并发、长上下文和长输出场景。
• 对 KV Cache 量化做业务评测，通用 benchmark 只能作为参考。
• 对超长请求设置降级路径，例如压缩上下文、改走批处理或提示用户缩小范围。

7.3 Prefix Cache：复用稳定前缀降低 TTFT

Prefix Cache 是 KV Cache 复用的一种典型形式。当两个请求拥有相同前缀时，第二个请求不必重新计算这段前缀的 Prefill，而是直接复用已经生成的 KV Cache。vLLM 文档将 Automatic Prefix Caching 描述为复用已有查询的 KV Cache，让共享前缀的新查询跳过共享部分计算。对企业 Agent 平台来说，这个机制非常重要，因为许多请求天然共享前缀。常见共享前缀包括：

表7-2：Prefix Cache 在各类场景的共享前缀、加速收益与风险。来源：本书整理。

Prefix Cache 的收益主要体现在 TTFT，对每个输出 Token 的 Decode 速度影响较小。它减少的是重复 Prefill 计算：共享前缀越长，命中率越高，收益越明显。如果请求只共享很短的系统提示词，收益有限；如果请求共享几千到几万 Token 的长文档、工具 schema 或表结构说明，收益会很可观。要让 Prefix Cache 生效，prompt 组织方式比引擎开关更重要。平台应把稳定内容放在前缀，把动态内容放在后缀。例如：

稳定前缀：
1. 系统角色
2. 安全规则
3. 工具 schema
4. 企业术语表
5. 长文档或表结构

动态后缀：
1. 用户本轮问题
2. trace_id
3. 当前时间
4. 临时过滤条件
5. 上一步工具结果

如果把 trace_id、当前时间、随机 nonce、用户姓名等动态字段放在开头，即使后面的大段工具说明完全相同，缓存也可能无法命中。对于一家多业务线企业的 DataAgent，语义层说明、指标口径、表结构和 SQL 安全规则应尽量稳定地放在前缀；用户问题、筛选条件和会话状态放在后缀。这样同一业务域的多次查询可以复用前缀 KV Cache。多轮对话场景还要注意“缓存收益”和“上下文膨胀”的冲突。多轮历史越长，可复用内容越多，但 KV Cache 占用也越大。如果每一轮都把完整历史追加进去，后续请求会越来越慢。生产系统通常需要结合会话摘要、历史裁剪和重要事实记忆，把对话历史压缩成稳定前缀，而非无限增长。Prefix Cache 实现时要关注四个指标。

表7-3：Prefix Cache 相关监控指标的含义与异常解读。来源：本书整理。

Prefix Cache 不能加速完全不同的 prompt，也不能修复检索质量差的问题。它还可能提高显存占用，因为引擎需要保留可复用的 KV Cache。平台要按业务域设置缓存策略：客服知识库、固定工具 schema 和 DataAgent 表结构适合保留；一次性长文档、低频租户和超大临时上下文应更积极淘汰。缓存策略还要避免泄漏和串租户。即使两段前缀文本相同，不同租户也未必允许共享缓存；同一业务域内，权限版本变化、工具 schema 变化或策略升级也应触发缓存失效。把 Prefix Cache 当成纯性能功能，会漏掉这些治理条件。更稳的方式是把缓存 key 设计成由模型版本、系统提示词 hash、工具版本、租户或安全域、策略版本共同组成，命中率会下降一些，但可解释性和隔离性更强。

7.4 Speculative Decoding：用草稿模型加速 Decode

Speculative Decoding 的核心思想是用一个更快的 draft model 先生成多个候选 Token，再由目标大模型一次性验证这些候选。如果候选 Token 符合目标模型的分布，就可以一次接受多个 Token；如果不符合，就回退到目标模型的采样结果。Leviathan、Kalman 和 Matias 在 ICML 2023 的论文中提出，该方法可以在不改变输出分布的情况下加速自回归生成。它解决的是 Decode 阶段瓶颈。大模型生成通常是一 Token 一步，每一步都要跑一次大模型前向计算。Prefill 可以并行处理输入序列，但 Decode 天然串行。Speculative Decoding 通过“小模型草拟，大模型批量验证”把多个 Decode step 合并到一次或少数几次大模型计算中，从而降低每个输出 Token 的平均成本。

sequenceDiagram
    participant C as Client
    participant D as Draft Model
    participant T as Target Model

    C->>D: 当前上下文
    D-->>C: 草拟 k 个 token
    C->>T: 上下文 + 草拟 token
    T-->>C: 验证接受前 n 个 token
    alt 全部接受
        C->>D: 基于新上下文继续草拟
    else 部分拒绝
        C->>T: 使用目标模型修正 token
        C->>D: 基于修正后上下文继续草拟
    end

Speculative Decoding 的“无损”指的是在正确实现的采样校正下，最终输出分布与直接使用目标模型采样一致。它没有用小模型替代大模型，也不应通过牺牲质量换速度。收益取决于 draft model 的接受率：小模型越能预测大模型接下来会生成什么，接受率越高，加速越明显；如果小模型和大模型行为差异大，草拟 Token 经常被拒绝，额外的小模型计算就会变成负担。适合 Speculative Decoding 的场景包括：

表7-4：投机解码适合的场景及各自的注意事项。来源：本书整理。

复杂推理、开放式创作、多工具分支、强随机采样、多语言混杂和高不确定性问答，draft model 的接受率往往偏低。DataAgent 的 SQL 生成也要谨慎：如果小模型频繁草拟错误 SQL 片段，大模型验证虽然能纠正分布，端到端吞吐未必提升，调试复杂度还会上升。企业上线 Speculative Decoding 时，不应只看“平均加速倍数”，而要同时看四个指标。

表7-5：投机解码相关监控指标的含义与目标值。来源：本书整理。

Speculative Decoding 还有一个平台层面的取舍：需要额外部署 draft model，增加模型管理、显存、路由和监控复杂度。如果 draft model 与目标模型不同族，Tokenizer、词表、对齐方式和采样策略都可能带来集成问题。因此它更适合作为“针对特定高流量任务的优化”，不适合作为所有模型服务的默认开关。对一家多业务线企业来说，优先尝试的场景可以是客服标准摘要、代码补全和固定格式工单生成；暂缓尝试的场景是财务解释、合规问答和复杂 DataAgent 推理。前者输出模式稳定，易测收益；后者质量风险高，且失败成本更大。

7.5 量化：用精度换容量、吞吐和成本

量化是把模型中的高精度数值表示换成低精度表示，从而减少显存、存储和内存带宽占用。大模型推理中的量化至少包括四类：权重量化、激活量化、KV Cache 量化和全链路低精度推理。企业最常见的是权重量化和 KV Cache 量化。

表7-6：权重量化与激活量化的对象、格式、收益与风险。来源：本书整理。

权重量化解决的是“模型放不放得下”和“每 Token 计算成本”。例如一个 BF16 模型如果降到 INT4，理论参数存储可以大幅下降，单卡可部署的模型规模随之提升。GPTQ、AWQ、bitsandbytes 等方法都服务于这个目标，但权重量化不是无风险压缩。模型越小、任务越精细、输出越结构化，量化误差越可能变成业务错误。KV Cache 量化解决的是“长上下文和高并发放不放得下”。当模型权重已经固定，活跃请求越多、上下文越长，KV Cache 会成为主要显存瓶颈。把 KV Cache 从 BF16/FP16 降到 FP8 或更低精度，可以提高可承载的上下文 Token 数。但它对长文档问答、needle-in-a-haystack 检索、代码引用和 SQL 生成的影响必须单独测。权重量化过了评测，不代表 KV Cache 量化也安全。量化方法还可以按是否需要训练/校准分为三类。

表7-7：PTQ 与 QAT 等量化方法的说明、优势与代价。来源：本书整理。

企业评估量化时，不应只看困惑度或通用排行榜。一家多业务线企业至少需要四类业务评测集。

表7-8：量化质量验证各评测集的关注点与典型失败。来源：本书整理。

量化上线可以采用“从保守到激进”的路径。先在低风险任务上验证格式、延迟和成本，再逐步进入高吞吐或高风险链路，能减少一次性切换带来的回滚压力。

1. 先用 BF16/FP16 模型建立质量和性能基线。
2. 尝试 INT8 或 FP8，验证质量、TTFT、TPOT、吞吐和显存。
3. 对成本敏感且质量稳定的任务尝试 INT4 权重量化。
4. 对长上下文服务单独测试 KV Cache FP8 或更低精度。
5. 对每个量化版本建立模型卡，记录量化方法、校准集、评测集和适用任务。

量化也会影响推理优化之间的组合。例如，INT4 权重量化可能释放显存，让平台能开更大的 batch；KV Cache FP8 可能提升长上下文并发；但量化模型配合 Speculative Decoding 时，draft model 和 target model 的分布差异可能改变接受率。Prefix Cache 与量化也要一起验证，因为复用的是特定精度下的 KV Cache。生产环境中，量化版本不应被当作同一模型的无差别替代品。平台应把 qwen3-32b-bf16、qwen3-32b-awq-int4、qwen3-32b-fp8-kv 视为不同可路由版本，分别配置适用任务、租户、SLO 和回滚策略。这样当 DataAgent 在 INT4 版本上 SQL 错误率升高时，可以只把 DataAgent 路由回 BF16，而非影响客服摘要等低风险任务。

7.6 推理优化的上线评估

推理优化不能只看单点吞吐。企业 Agent 平台通常同时关心 TTFT、总延迟、并发、显存占用、成本、输出质量和失败恢复。KV Cache、Prefix Cache、Speculative Decoding 和量化会影响不同指标：有的降低首 token，有的提高 decode 吞吐，有的减少显存，有的降低成本，但它们也可能改变尾延迟、输出稳定性或结构化输出成功率。上线评估应使用真实任务分布。普通问答、DataAgent 查询、报告生成、工具调用、长上下文总结和多轮对话的资源画像不同，不能用一组短 prompt 压测替代。长报告任务会放大 KV Cache 压力，结构化输出任务会放大采样和格式稳定性问题，工具调用任务会放大首 token 和解析失败的影响。评估结果要按任务类型拆开看，避免平均值掩盖关键场景。

优化策略还要与第43章和第45章连接。第43章负责 GPU 调度和容量，第45章负责网关路由和租户配额。模型服务层如果启用了量化或 speculative decoding，网关需要知道该 backend 的适用任务和质量边界；GPU 调度层也需要知道不同 backend 的显存和并发画像。否则网关可能把高风险报告路由到不适合的量化模型，或者把长上下文任务打到显存余量不足的副本。

7.7 优化策略的回滚与灰度

推理优化也需要灰度和回滚。量化模型、缓存策略、草稿模型和 decoding 参数都可能改变用户可见行为。上线时应先在影子流量或低风险租户中观察，再逐步扩大。观察指标不只包括延迟和成本，还包括拒答率、结构化解析失败率、工具参数错误率、报告人工退回率和用户追问率。回滚策略要具体到 backend 和任务类型。某个量化模型在普通问答中表现稳定，但在财务报告中数值错误上升，可以只把高风险任务回滚到高精度 backend；某个 Prefix Cache 策略导致权限上下文复用风险，应立即禁用跨用户缓存，而非回滚整个模型服务。优化策略越细，回滚策略也要越细。早期平台可以先建立固定评测集和少量灰度规则。每次调整推理参数或模型后，先跑结构化输出、DataAgent、长上下文和工具调用样本，再进入少量租户灰度。这样推理优化就不会变成“省成本”的单向动作，而是进入可验证、可回退的工程链路。

7.8 优化指标的观测口径

推理优化的观测指标要和用户体验对齐。平均延迟下降不代表体验改善，P95、P99、首 token 延迟、输出中断、重试次数和降级次数更能反映真实问题。对于流式输出，TTFT 决定用户是否觉得系统响应及时，总生成时间决定任务完成效率，token 抖动会影响前端展示稳定性。不同指标要分开看，不能合成一个“推理性能分”。观测口径还要按模型、租户和任务类型拆分。一个模型在普通问答中表现很好，不代表它适合长上下文报告；一个租户的缓存命中率高，不代表其他租户也能复用；一个 backend 的平均成本低，不代表它在高峰期仍能满足 SLO。第45章的网关需要把 model、backend、tenant_id、route_rule_id 写入 Trace，第43章的 GPU 调度需要提供节点池和队列状态，二者合在一起才能解释性能变化。

优化指标最终要服务决策。延迟高时，是增加副本、缩短上下文、启用缓存、切换模型，还是拒绝低优先级请求；成本高时，是调路由、调量化、调缓存，还是限制某类任务。没有这些决策映射，指标只能说明系统变慢或变贵，不能指导平台怎么改。这些决策也要进入发布记录。一次性能优化如果没有说明适用任务、观测指标和回滚条件，后续团队很难判断它是稳定收益，还是只适合某个短期流量窗口。记录本身也应进入 Trace 与发布台账。

发布台账还应保留对照版本。比如量化前后的模型、缓存策略切换前后的 TTFT、投机解码启用前后的接受率和失败样例，都要能回查。否则半年后团队只知道“某天我们打开了一个优化”，却不知道它解决了什么问题，也不知道能否关闭。推理优化的评审也要看用户可见行为。首 token 更快但回答中断更多，平均成本降低但高风险任务错误率上升，GPU 利用率提高但 P99 变差，都不能算稳定收益。评审会应让平台、SRE、业务和安全团队同时看同一份结果：性能曲线、质量回归、失败样例、成本变化和回滚条件。只有这些证据同时成立，优化才适合从灰度进入默认配置。有些优化还应只服务特定任务。模板摘要可以接受更激进的量化和投机解码，财务 DataAgent 更适合保持高精度和严格结构化输出，普通知识问答可以用缓存换 TTFT，合规问答则要优先保留引用和拒答质量。把所有请求打到同一套优化参数上，管理简单，却会把不同风险场景的取舍混在一起。因此，优化参数最好由网关按任务类型路由，而非写死在单个模型服务里。这样某个场景回滚时，只需要调整路由和策略，不必同时影响所有业务。这让优化成为可管理的路由策略，而非服务进程里的隐藏开关。

7.9 推理优化的发布门禁

推理优化进入生产前，应当像模型版本一样通过发布门禁。门禁的第一项是基线对照。团队要保留优化前的模型版本、推理引擎版本、路由规则、硬件类型、并发配置和评测结果，否则上线后很难判断收益来自优化机制、负载变化还是网关流量变化。门禁的第二项是任务分层。客服摘要、知识问答、DataAgent、代码助手、合规问答和内部批处理应分开看，不能用一个平均延迟证明所有任务都受益。门禁的第三项是失败样例。每次优化至少要检查结构化输出失败、长上下文引用错误、拒答边界变化、工具参数漂移和流式中断这些样例；如果这些样例没有覆盖，优化很可能只在性能指标上好看。

发布门禁还要明确哪些指标可以换取，哪些指标不能换取。客服摘要可以接受少量措辞变化换取吞吐提升，但不能接受事实字段错误；内部知识问答可以接受回答稍慢换取引用更稳定；DataAgent 可以接受成本上升换取 SQL 正确率和字段权限稳定；合规问答则应先保护拒答和引用，再讨论速度。把这些取舍写进门禁，评审时就不会只围绕“快了多少”和“省了多少”讨论。不同任务的容错边界不同，优化策略也应不同。

灰度期间要设置观察窗口。很多优化在短压测中表现很好，进入真实流量后才暴露问题。Prefix Cache 的命中率会受业务日历、用户行为和文档版本影响；量化模型的错误可能集中在少数高风险问题上；投机解码的接受率会随 Prompt 模板和输出格式变化；KV Cache 策略在平峰稳定，在高峰可能触发更多淘汰。观察窗口应覆盖平峰、高峰、长上下文、批处理和至少一次模型或知识库变更。若观察窗口太短，团队容易把偶然收益当成稳定能力。

发布门禁还需要和事故响应连起来。优化上线后如果出现结构化输出失败率上升，平台要能快速定位是模型版本、量化配置、采样参数、缓存策略还是网关路由引起；如果 DataAgent 报告退回率增加，团队要能按任务类型回滚到高精度 backend；如果 GPU 队列拥塞，SRE 要能判断是优化带来的 batch 配置变化，还是请求画像变化。优化配置应写入 Trace 和发布台账，包括模型版本、backend、量化格式、KV Cache 精度、Prefix Cache key、draft model、采样参数和路由规则。这样一次用户投诉可以回到具体配置，避免排查停留在“当前模型服务是否正常”。

早期平台可以先建立轻量门禁：固定五类评测样本，保存一份基线报告，灰度两个租户或一个业务域，观察一周，再决定是否扩大。门禁不需要一开始很复杂，但要能约束优化行为。缺少门禁时，推理优化会变成一串临时开关；建立门禁后，它会成为模型平台的可管理发布动作。

7.10 优化配置的运行台账

推理优化上线后，应进入运行台账。台账记录模型版本、推理引擎、量化格式、KV Cache 精度、Prefix Cache key、draft model、采样参数、网关路由、GPU 节点池、灰度范围、评测集版本和回滚目标。一次延迟下降如果没有这些上下文，后续团队无法判断收益来自模型服务、流量变化、缓存命中、硬件调度，还是任务结构变化。一次质量退化如果没有这些上下文，也很难知道该回滚量化、关闭缓存，还是调整网关路由。

运行台账还要记录“未采用”的方案。某个 INT4 版本因为 DataAgent 字段错误率过高被拒绝，某个投机解码方案因为接受率低被放弃，某个 Prefix Cache 策略因为权限上下文不稳定被限制到单租户，这些结论都应保存。半年后模型、硬件或任务分布变化时，团队可以重新评估，而不是从头重复实验。推理优化的知识积累来自这些对照记录。只有保留成功和失败的配置，平台才能把优化从临时调参变成可复用的工程经验。

7.11 推理优化变更的回归证据

推理优化进入生产后，最重要的材料是变更前后的可比证据，单次压测分数只能作为参考。量化、KV Cache 策略、Prefix Cache、batch 参数、Speculative Decoding、并行方式和上下文长度都会影响质量、延迟和成本。一次优化可能让平均吞吐变好，却让长上下文请求更容易 OOM；也可能让 P50 延迟下降，却让结构化输出更容易缺字段。平台在发布前要保存同一批任务样本的结果、错误类型、TTFT、TPOT、显存峰值、GPU 小时和回滚版本。

回归证据要覆盖任务形态。客服摘要、知识问答、DataAgent NL2SQL、长报告生成、工具调用规划、批量评测对推理引擎的压力不同。只用短问答压测，会高估优化收益；只看吞吐，会低估用户等待和输出稳定性。更可靠的做法是给每类任务维护一小组代表样本，并在每次优化变更后重跑。若某个优化只适合批处理，不应默认进入在线推理池；若某个量化方案影响结构化输出，就要限制它服务的任务类型。

优化回滚也要有边界。关闭某个 cache 策略、恢复旧量化、切回旧引擎版本、调整 batch 参数，看起来都属于“回滚”，但它们影响的风险不同。回滚计划应说明会牺牲哪些性能指标、是否需要重新预热、是否影响正在运行的流式会话、是否需要同步更新网关路由。推理优化的成熟度，体现在团队能解释每次性能变化的代价，而不是只追逐更高吞吐。

7.12 优化参数的运行台账

推理优化参数需要运行台账。max_batch_size、max_num_batched_tokens、KV Cache 策略、量化方式、并行度、上下文上限、预热样本、超时设置和降级模型，都会影响线上表现。若这些参数只存在启动脚本里，事故时很难判断某次延迟变化来自业务流量、模型版本，还是优化参数调整。

台账应记录参数来源和适用任务。批处理参数适合评测和离线报告，不一定适合客服对话；长上下文设置适合报告生成，可能会挤压短问答并发；激进量化适合低风险摘要，可能影响结构化输出。平台在路由时应根据任务类型选择 backend，而不是让所有请求共享同一套优化参数。

参数台账还要和成本复盘连接。某次优化节省了 GPU 小时，却增加了重试率或人工复核；某次扩容降低了延迟，却让空闲成本升高。这些取舍需要在同一份记录里解释。推理优化需要持续平衡质量、延迟、成本和恢复能力，单次调参结果只能作为阶段性证据。

7.13 优化策略的业务回归样本

推理优化的回归样本要来自真实业务任务。KV Cache、Prefix Cache、Speculative Decoding 和量化都可能改善延迟或成本，但它们对不同任务的影响不同。短问答可能只关心首 token 延迟，长报告关心上下文保留和截断，工具调用关心结构化参数稳定性，合规问答关心拒答和证据引用。若回归样本只看通用 benchmark，优化策略容易在业务边界上退化。

业务回归样本应记录输入、期望输出形态、允许延迟、上下文长度、是否调用工具、是否需要引用、是否属于高风险场景。优化前后比较时，不只看平均延迟，还要看格式错误、截断、工具参数缺失、拒答变化和人工退回。对于 speculative decoding，还要观察草稿模型是否让特定格式更容易出错；对于量化，还要观察数值、代码和结构化输出是否更不稳定。

早期平台可以把优化策略和样本绑定。某个模型路由启用量化，就必须声明适用任务和禁止任务；某个 prefix cache 规则上线，就要说明哪些系统提示和上下文片段可以复用。这样推理优化会成为可审计的发布行为，而不是隐藏在基础设施里的性能调参。

7.14 优化收益的长期复核

推理优化的收益需要长期复核。一次灰度通过，只说明当时的模型、任务分布、硬件和路由策略下收益成立。几个月后，Prompt 模板、RAG 文档、语义层、用户问题、业务高峰和模型版本都可能变化，同一套优化参数可能不再适合。平台应定期查看优化收益是否仍然存在：缓存命中是否下降，量化错误是否集中在新任务上，投机解码接受率是否降低，长上下文请求是否挤压短请求。

长期复核要同时看收益和副作用。延迟降低但人工退回上升，说明优化代价进入了业务流程；成本下降但重试次数增加，说明账单节省被质量问题抵消；GPU 利用率提高但 P99 变差，说明调度策略可能伤害交互体验。复核材料应把性能、质量、成本和用户反馈放在同一页，避免各团队只看自己负责的指标。

早期可以每季度复核核心优化策略。复核结论分为继续默认启用、限制到部分任务、回退到候选策略、补充样本后再观察。这样推理优化不会成为长期无人敢动的隐性配置，而会像模型版本一样进入持续治理。

7.15 优化副作用的定位与隔离

推理优化上线后，副作用往往先出现在业务层。用户看到的是答案变慢、格式不稳定、引用丢失、工具参数缺字段或报告生成超时，底层原因可能来自 batch 参数、KV cache 策略、量化版本、draft model、调度队列或网关路由。排查时如果直接回滚全部优化，会损失已经验证过的收益；如果只盯着模型输出，又会漏掉资源调度和缓存命中的变化。优化副作用需要按层定位。

定位可以从同一条任务样本开始。先固定模型版本和 Prompt，比较启用与关闭优化后的输出差异；再固定优化策略，比较不同路由池和并发压力下的延迟、截断和错误码；最后检查 Trace 中的缓存命中、batch 等待、draft 接受率、量化版本和重试次数。这样可以把问题缩小到“质量退化”“排队退化”“格式退化”或“成本退化”中的一种，而不是把所有异常都归为推理优化失败。

隔离策略要按任务风险设计。低风险摘要可以继续使用激进量化和缓存策略，但结构化输出、工具参数生成和高风险拒答应保留更保守的路由；同步对话可以限制长上下文任务对 GPU 池的挤占，异步报告则可以接受更长排队时间换取更低成本。若某个优化策略只在特定租户或任务类型上出问题，平台应支持租户级、任务级和模型级关闭，而不是全局回退。

早期平台可以把副作用定位写入优化复盘。每次复盘记录触发样本、影响任务、定位路径、临时隔离动作、最终策略和后续观察窗口。这样第7章的优化不会停留在性能技巧，而会与第6章的推理服务运行证据、第8章的结构化输出、第41章的成本治理形成同一条生产链路。优化的目标是让能力稳定进入业务，而不是让一次 benchmark 更好看。

7.16 优化策略的业务验收口径

推理优化上线前，需要把技术指标翻译成业务验收口径。吞吐提升、显存降低和 TTFT 缩短并不自动代表用户体验改善。对于经营报告任务，用户可能更关心首段摘要是否及时出现、最终数字是否稳定、长任务是否能恢复；对于客服问答，用户更关心响应是否连续、是否出现重复片段、是否能在权限拒绝时快速给出解释。优化验收应按任务类型定义，而不是用一个平均延迟指标覆盖所有场景。

业务验收还要关注输出形态。Speculative Decoding 可能让流式 token 节奏更不稳定，用户看到的打字感变化会影响前端体验；量化可能对一般问答影响很小，却让表格数字、代码、SQL 和长链路推理更容易出错；Prefix Cache 能降低稳定前缀成本，但若缓存边界处理不好，会让不同租户或不同权限上下文互相污染。每一种优化都应配套一组业务样本，覆盖正常任务、边界任务和高风险任务。

早期平台可以把优化验收写入发布单：目标任务、基线版本、优化参数、收益指标、护栏指标、失败样本、回滚条件和 owner。发布后七天内继续观察真实流量，若收益集中在低价值任务，而副作用出现在高价值任务，应停止扩大流量。推理优化的目标是让平台在成本和体验之间做可解释选择，而不是追求单一 benchmark 数字。

7.17 模型路由策略的证据化

模型路由进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把请求类型、数据等级、模型版本、降级原因、成本和质量样本记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第44章模型服务、第45章网关和第52章合规相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括路由只按价格选择、降级模型改变输出风格、敏感数据进入不合适的供应商。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

路由策略应进入模型目录，并随评测样本和合规规则共同更新。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

7.18 路由策略的业务解释材料

模型路由策略需要能被业务理解。一次请求为什么进入高成本模型，为什么降级到小模型，为什么被限制外部供应商，不能只留在网关配置里。平台应为高风险或高成本路由保留解释材料：请求类型、数据等级、候选模型、选择理由、预算影响和质量样本。业务 owner 看到这些材料后，才能判断当前策略是否符合场景价值。

解释材料还可以减少模型升级时的争议。模型服务层可能认为新模型质量更好，成本治理可能认为新模型太贵，安全团队可能关注供应商边界，业务团队只关心结果是否稳定。路由说明把这些视角放到同一个记录里，避免策略讨论变成单点指标争论。对于高频场景，路由策略应定期复审，确认模型选择仍然和数据等级、用户预期以及预算承诺一致。

本章小结

推理优化要从瓶颈出发，而非按功能清单逐个打开。不同任务可能分别卡在 Prefill、Decode、KV Cache、结构化输出或队列调度；同一个优化机制在客服摘要、DataAgent、代码助手和合规问答中的收益也不一样。优化发布时要写清楚受益任务、风险任务、观察指标和回滚路径，避免把一次性能实验变成长期不可解释的配置。KV Cache 决定长上下文和高并发的显存上限，Prefix Cache 只有在前缀稳定、命中率足够高时才会稳定降低 TTFT。Speculative Decoding 更适合输出模式稳定、draft model 接受率高的高流量任务，不宜作为所有场景的默认开关。量化版本则应作为独立可路由模型治理，并按业务评测集验证质量、格式、事实性和安全边界。第8章进入结构化输出后，这些优化还会继续影响 JSON、函数参数和工具调用的稳定性。延伸资料可参考 vLLM Automatic Prefix Caching、vLLM Prefix Caching Design、TensorRT-LLM KV Cache System、TensorRT-LLM Quantization、Hugging Face Transformers Quantization、Fast Inference from Transformers via Speculative Decoding 和 GPTQ 相关论文。

参考文献

Dao, T. et al. (2022). FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness. NeurIPS.

Kwon, W. et al. (2023). Efficient Memory Management for Large Language Model Serving with PagedAttention. SOSP.

Leviathan, Y. et al. (2023). Fast Inference from Transformers via Speculative Decoding. ICML.

Lin, J. et al. (2024). AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. MLSys.

第8章 结构化输出与提示工程

模型输出要从可读文本变成可被系统消费的接口结果。企业应用很少只把回答展示给用户，更多时候要把结果写入工单、合同库、审批流、SQL 执行器或前端组件树。只靠 Prompt 要求“输出 JSON”并不可靠，系统还需要 schema、解析器、业务校验、重试策略、工具权限和审计日志。本章把 Prompt 看作输入侧接口，把结构化输出看作输出侧契约，把工具调用看作受控系统动作，说明三者如何一起进入发布和回滚流程。客服中心希望模型把投诉归类后自动进入工单系统；合同助手希望模型抽取付款节点并写入提醒表；DataAgent 希望模型生成下一步工具调用参数；生成式 UI 希望模型返回组件树。它们看起来都是“让模型按格式回答”，但生产风险并不相同。

如果模型把 delivery_delay 写成“物流比较慢”，人能理解，系统却无法稳定入库。如果模型在退款工具参数里多填了一个未定义字段，工具执行器可能拒绝，也可能被业务代码误读。如果模型输出的证据句并不存在于原文，JSON 语法完全正确也没有用。因此，结构化输出属于接口治理问题，而非单纯的格式问题。结构化输出最容易在演示阶段被低估。模型返回一段 JSON，前端能渲染，业务看起来已经跑通；等到它进入工单、合同、SQL 执行器和审批流，字段名、枚举值、证据位置和失败恢复都会变成接口责任。一个字段多了空格、一个枚举写成自然语言、一个证据引用找不到原文，下游系统都可能把问题放大。

企业里常见的事故并非 JSON 语法错误，而是语义正确性和执行边界混在一起。模型把退款原因分类成 delivery_delay，系统能入库；但证据句来自用户猜测，客服据此自动退款，后续争议就会落到业务流程上。模型生成一个工具调用参数，schema 通过了；但权限范围没有校验，执行器读取了当前用户不该看的明细。结构化输出只有和业务校验、权限策略、幂等键和审计日志一起设计，才算进入生产。Prompt 在这里承担输入侧契约，schema 承担输出侧契约，工具调用承担执行侧契约。三者分开管理时，发布很容易错位：Prompt 要求新增字段，schema 没更新；schema 允许的枚举变了，评测样本仍按旧值；工具参数多了风险字段，审批页面却没有展示。真正可靠的结构化任务，需要把这些资产当作同一个版本发布。

8.1 从自由文本到可验证动作

8.1.1 结构化输出的系统价值

大模型刚接入业务时，团队通常先把它当作文本接口：业务拼一段 Prompt，模型返回自然语言，前端展示给用户。原型阶段这样最快，但进入生产后会碰到一组很具体的限制。自由文本很难被下游系统稳定消费。客服工单、合同抽取、审批建议和 SQL 执行计划都需要字段、类型、枚举和证据；Prompt、模型版本、生成参数和上下文稍有变化，输出又可能换一种写法。出了事故之后，团队还需要知道模型返回了什么字段、哪个字段没通过校验、哪个工具被调用、是否进入人工队列。仅靠一段自然语言，复现和审计都会变得困难。结构化输出要把一次模型生成拆成可验证的动作：输入是什么，输出必须满足什么结构，哪些失败可以重试，哪些失败必须拒绝或交给人工。

表8-1：常见结构化任务的输出对象与失败后果。来源：本书整理。

这些任务的共同点是输出会继续驱动系统动作。它们需要有版本、有校验、有错误处理的接口契约，而非“像 JSON 的文本”。

8.1.2 Prompt、schema 与工具调用的三类契约

Prompt、结构化输出和工具调用经常被混在一起。它们确实相互依赖，但职责不同。Prompt 是输入侧契约，负责告诉模型任务、上下文、业务规则和输出要求。结构化输出是输出侧契约，负责规定返回对象的字段、类型、枚举和必填项。工具调用是执行侧契约，负责把模型给出的工具名和参数交给平台校验，再由平台决定是否执行。

图8-1：结构化任务的四层契约。来源：本书自绘。Alt text：图中从上到下展示 Prompt 输入契约、模型生成、schema 输出契约和下游消费四层，每层都有校验点，输出通过 schema 后才能进入业务系统。

图 8-1 强调的是“契约绑定”。一个结构化任务发布时，Prompt 模板、schema、工具契约、模型版本、生成参数、评测样本和回滚策略应该作为同一个发布包管理。结构化任务至少包含四层契约。

表8-2：结构化任务的四层契约。来源：本书整理。

这四层缺一层，生产风险都会转移到后面的系统。只写 Prompt，系统会被格式错误拖垮；只写 schema，模型可能语义正确率很低；只做工具调用，安全和幂等问题会被隐藏到执行阶段。在评审结构化任务时，可以要求团队把这四层逐项落到具体文件或配置上。说不清 Prompt 版本在哪里，说明行为难以复现；说不清 schema 失败进入哪里，说明恢复路径没有设计；说不清工具执行由谁授权，说明模型输出和系统动作之间缺少隔离层。

8.1.3 Prompt 模板的接口化设计

企业 Prompt 不应写成一次性提示词。一个稳定模板至少要说明角色边界、任务目标、上下文变量、业务规则、输出契约和失败策略。例如投诉分类任务可以这样设计：

你是客服质检助手，只做投诉原因归类，不生成赔付承诺。

任务：
从工单文本中识别主投诉原因，并给出最多三个来自原文的证据句。

业务规则：
- category 只能从 delivery_delay、quality_issue、refund_dispute、service_attitude、unknown 中选择。
- 信息不足时选择 unknown，并填写 missing_info。
- 如果投诉涉及退款和物流，优先选择导致升级的原因。

输出：
返回符合 complaint_classification_v2 的 JSON。不要输出 Markdown。

这段 Prompt 的价值不在措辞，而在边界可测。业务规则能转成测试样例；枚举能转成 schema；失败出口能被监控；“不生成赔付承诺”能被安全评测覆盖。Few-shot、分步推理、多分支推理和多次采样投票都可以提高某些任务的稳定性，但它们不能替代接口契约。示例越多，Prompt 越长，维护成本也越高；显式推理越多，泄露草稿和增加成本的风险也越大。生产系统应先把结构、规则和校验做好，再按任务风险决定是否加入这些技巧。

8.1.4 结构化输出的失效模式

最常见的失效来自把“输出 JSON”当作结构化输出。模型仍可能输出 Markdown 代码块、尾随解释、缺字段、非法枚举或半截对象。Prompt 是第一道约束，后面还需要解析、schema 和业务校验。schema 也不是越复杂越可靠。过深嵌套、过多可选字段和含糊字段名会增加失败率，也会让业务难以定位问题。生产 schema 应从最小可用字段开始，优先使用短枚举、数字、日期、布尔值和证据引用。更高风险的做法是让模型直接操作系统。模型可以建议调用哪个工具和使用哪些参数，但执行必须由平台完成。发送邮件、退款、创建工单、执行 SQL 这类动作，需要鉴权、参数校验、幂等控制、审计和人工确认。

8.2 解析、校验与异常处理

8.2.1 链路位置

结构化输出能力位于业务应用、LLM Gateway、推理服务和工具系统之间。上游给出任务、上下文和风险等级；下游接收状态更新、工具调用、数据库写入或 UI 渲染。

flowchart TD
    App["业务应用 / Agent Runtime"] --> Task["任务请求<br/>intent / context / tenant"]
    Task --> Prompt["Prompt Template<br/>版本 / 变量 / 示例"]
    Prompt --> Contract["输出契约<br/>JSON Schema / grammar / tool schema"]
    Contract --> Gateway["LLM Gateway<br/>路由 / 限流 / 审计"]
    Gateway --> Engine["模型服务<br/>普通生成 / guided decoding"]
    Engine --> Parser["解析与校验<br/>parse / schema validate / business rules"]
    Parser -->|valid| Consumer["业务消费方<br/>状态机 / 工具执行 / UI / 数据库"]
    Parser -->|invalid| Recovery["恢复策略<br/>repair / retry / fallback / human"]
    Consumer --> Tools["工具系统<br/>registry / auth / execution"]
    Tools --> Parser
    Recovery --> Gateway

图8-2：结构化输出的校验与恢复闭环。来源：本书自绘。Alt text：图中展示模型生成、解析、schema 校验、业务校验和下游消费的循环；校验失败会进入修复、重试、降级或人工复核分支。

图 8-2 中最重要的是 invalid 分支。很多生产事故并非模型完全不会回答，而是输出“看起来差不多”：字段名接近、证据缺失、枚举拼错、权限越界或工具参数不完整。只要这类结果越过校验层，问题就会进入业务系统。

8.2.2 请求契约

结构化请求可以用统一对象描述。下面示例不绑定任何模型 SDK，只表达平台需要保存和传递的信息。

{
  "task": "complaint_classification",
  "tenant": "demo-retail",
  "prompt": {
    "template_id": "complaint_classifier",
    "version": "2.1.0",
    "variables": {
      "ticket_text": "用户反馈包裹延迟三天，客服多次未响应，要求退款。",
      "channel": "online_chat"
    }
  },
  "model": {
    "name": "qwen3-32b-instruct",
    "temperature": 0.1,
    "max_tokens": 512
  },
  "response_format": {
    "type": "json_schema",
    "schema_id": "complaint_classification",
    "schema_version": "2.0.0"
  },
  "recovery": {
    "max_retries": 2,
    "repair": true,
    "fallback": "human_review"
  }
}

对应的 schema 应保持小而明确，字段数量也要控制在可维护范围内。下面这个示例只保留分类、置信度、证据和人工复核标记，目的是把模型真正需要承担的输出责任限定清楚。

{
  "type": "object",
  "required": ["category", "confidence", "evidence", "requires_human_review"],
  "additionalProperties": false,
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "delivery_delay",
        "quality_issue",
        "refund_dispute",
        "service_attitude",
        "unknown"
      ]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "evidence": {
      "type": "array",
      "items": {"type": "string"},
      "minItems": 1,
      "maxItems": 3
    },
    "requires_human_review": {"type": "boolean"},
    "missing_info": {"type": "string"}
  }
}

这里有两个设计点。additionalProperties: false 限制模型输出未定义字段，避免下游误读。unknown 给模型一个合法的失败出口，否则模型会被迫在几个错误类别中选择一个。

8.2.3 生命周期与失败分层

结构化输出请求进入运行时以后，不会直接落到业务系统里，而是先经过一条明确的状态流转路径。下面这个状态机把渲染 Prompt、调用模型、解析输出、校验 schema 和恢复失败的几个阶段放在同一张图里。

stateDiagram-v2
    [*] --> RenderPrompt
    RenderPrompt --> CallModel: prompt valid
    RenderPrompt --> Failed: missing variable / context too long
    CallModel --> ParseOutput: model returned
    CallModel --> Retry: timeout / transient error
    ParseOutput --> ValidateSchema: parse ok
    ParseOutput --> Repair: parse failed
    Repair --> ValidateSchema: repair ok
    Repair --> Retry: repair failed
    ValidateSchema --> ValidateBusiness: schema ok
    ValidateSchema --> Retry: schema error
    ValidateBusiness --> Accepted: business rules ok
    ValidateBusiness --> HumanReview: low confidence / permission risk
    ValidateBusiness --> Retry: recoverable semantic error
    Retry --> CallModel: retry budget remains
    Retry --> HumanReview: retry budget exhausted
    Accepted --> [*]
    HumanReview --> [*]
    Failed --> [*]

失败处理要分层。JSON 解析失败可以 repair 一次；schema 失败可以把错误反馈给模型重试；证据缺失需要补检索或人工确认；参数越权必须直接拒绝并记录安全事件。把所有失败都重试，会增加成本和延迟；把所有失败都交给人工，又会让自动化失去意义。

表8-3：结构化请求的失败类型与恢复策略。来源：本书整理。

生产系统还要记录足够的 trace 信息：template_id、schema_id、model、generation_config、raw_output、parse_error、validation_error、retry_count、tool_call、tool_result、latency、token_usage 和最终状态。用户文本、手机号、证件号、合同金额等敏感字段需要按第10章之后的安全治理策略处理。

8.3 结构化输出的四组工程决策

8.3.1 Prompt 约束、约束解码与后置校验

Prompt 约束兼容性最好，但格式失败率最高。后置校验容易接入，能发现错误并触发重试，但仍会浪费一次模型调用。约束解码能在生成阶段减少非法格式，适合高并发抽取和工具参数生成，但依赖推理服务能力，也不能替代业务校验。实际生产中常用组合策略：Prompt 说清任务和边界，推理阶段尽量启用 JSON Schema 或 grammar 约束，输出后再做 schema 校验和业务校验。约束解码解决“形状正确”，业务校验解决“是否能用”。

8.3.2 大 schema 一次生成与小 schema 多步生成

简单表单可以一次生成完整对象。复杂任务更适合拆成多个小 schema：合同处理先判断合同类型，再按类型抽取条款；DataAgent 先判断查询意图，再生成 SQL 或工具参数；客服工单先分类，再对高风险类别抽取证据和升级原因。小 schema 多步生成会增加调用次数和延迟，但错误定位更清楚，重试范围也更小。对高风险任务来说，这个成本通常值得支付。

8.3.3 显式推理过程与证据输出

企业系统不应默认把模型的完整推理草稿展示给用户或写入业务记录。更可靠的做法是让模型输出结论、证据引用和必要解释，而非输出完整思维链。对高风险任务，系统应保留原始输入、检索片段、模型输出和人工复核记录。

8.3.4 模型选工具与工作流控工具

开放式办公助手可以让模型在低风险工具中自主选择。审批、退款、数据库查询和外发消息这类生产流程，应由工作流根据状态和权限裁剪工具列表，再让模型在有限集合中填参数。工具越多，误调用概率越高，也会占用上下文并影响缓存命中。

8.4 结构化输出的生产验收边界

结构化输出上线前，验收对象不应只是一段 prompt 或一个 JSON schema，而是一条从模型响应到业务动作的完整链路。平台需要证明四件事：模型能在正常输入下稳定生成目标结构，解析器能把异常输出归类，校验器能拦住语义不可用的字段，Runtime 能把失败转成可恢复状态。缺少其中任何一环，结构化输出都会退回“看起来像 JSON 的自由文本”。

最常见的失误，是把 schema 当成接口契约的全部。schema 能检查字段是否存在、类型是否匹配，却不能判断字段是否符合业务语义。例如 date_range 结构合法，但时间范围可能跨越未授权账期；metric_name 是字符串，但可能不是语义层登记过的指标；action 是枚举值，但当前用户没有执行权限。因此，结构化输出进入工具调用前，还要经过语义层、Policy 和 Registry 的二次判断。第33章的指标版本、第23章的工具参数、第50章的安全策略，都要在这里接上。

回归样本也要按失败类型组织。格式错误样本用于验证解析器和重试策略；字段缺失样本用于验证 schema 变更是否兼容；语义冲突样本用于验证业务校验；越权样本用于验证 Policy 是否在工具调用前生效。只有把这些样本放进发布门禁，团队才知道一次 prompt 修改影响的是表达格式、业务语义，还是工具执行边界。对前端来说，结构化输出还决定错误能否解释。用户不需要看到“JSON parse failed”，但需要知道系统是在重新生成、等待补充条件，还是因为权限不足停止执行。Conversation API 应把结构化失败映射为稳定错误码，前端再决定展示重试、补充信息、申请审批或转人工。这样结构化输出才真正成为平台接口，而非模型输出格式的一层装饰。

8.5 结构化输出的运行时契约

8.5.1 结构化输出在网关与工具层的分工

当前仓库已有两个相关基础模块：mini-platform/core/gateway/ 承担模型调用和路由抽象，mini-platform/core/registry/tool_registry.py 表达工具名、描述、参数 schema 和 handler 的关系。结构化输出可以在这个基础上补三类能力。

表8-4：结构化输出相关能力的建议路径。来源：本书整理。

轻量实现可以先只支持 JSON 对象解析和基础字段校验。生产系统再替换为 Pydantic、jsonschema、Instructor、Outlines 或推理引擎内置 guided decoding。

8.5.2 结构化解析示例

下面代码展示结构化输出网关的核心思路。它不是完整 JSON Schema 实现，只用于说明解析、字段校验和错误返回的边界。

# 来源建议：mini-platform/core/gateway/structured_output.py
from __future__ import annotations

import json
from dataclasses import dataclass
from typing import Any

@dataclass(frozen=True)
class ValidationError:
    path: str
    message: str

@dataclass(frozen=True)
class StructuredResult:
    ok: bool
    data: dict[str, Any] | None
    errors: list[ValidationError]
    raw: str

def parse_structured_json(raw: str, required: set[str]) -> StructuredResult:
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        return StructuredResult(False, None, [ValidationError("$", exc.msg)], raw)

    if not isinstance(data, dict):
        return StructuredResult(False, None, [ValidationError("$", "expected object")], raw)

    errors = [
        ValidationError(field, "missing required field")
        for field in sorted(required)
        if field not in data
    ]
    return StructuredResult(not errors, data if not errors else None, errors, raw)

工具调用要通过注册表查找和执行。模型最多给出工具名与参数，平台负责验证。

# 来源建议：mini-platform/core/gateway/tool_calling.py
from __future__ import annotations

from typing import Any

from core.registry import ToolRegistry

def execute_validated_tool_call(
    registry: ToolRegistry,
    name: str,
    version: str,
    arguments: dict[str, Any],
    *,
    tenant: str,
    idempotency_key: str,
) -> Any:
    tool = registry.get(name, version)

    if not idempotency_key:
        raise ValueError("idempotency key is required")

    # 生产代码还需要校验 arguments、tenant 权限和动作风险等级。
    return tool.handler(**arguments)

8.5.3 schema 变更的回归样本

结构化输出进入生产链路前至少要通过五类检查。这些检查分别覆盖 schema、解析、重试、下游消费和观测证据，避免模型看似返回了 JSON，实际却把风险留给业务系统。

表8-5：结构化输出发布准入。来源：本书整理。

这些验收项不要求一次做成庞大平台。早期只要能做到版本可追踪、失败可归类、工具不可绕过，就已经比“Prompt 字符串加 JSON parse”稳得多。结构化输出的早期也不必追求复杂。一个真实可用的起点，是把三类任务做扎实：一类信息抽取任务、一类工具调用任务、一类需要人工复核的高风险任务。三类任务跑通后，团队才能看清 schema 设计、重试预算和审计字段是否足够。

8.5.4 结构化输出失效的定位路径

JSON 被 Markdown 代码块包裹

示例里使用了代码块，模型照着输出，解析器直接失败。修复方式是示例只保留裸 JSON，解析器对代码块做一次 repair，高频任务启用 JSON Schema 或 grammar 约束。

字段合法与语义不可用

category 是合法枚举，confidence 也是数字，但证据句并不存在于原始工单。修复方式是增加证据回指校验，要求 evidence 来自输入原文或检索片段。

重试导致重复创建工单

第一次工具调用超时后，平台重试又创建了一张工单。修复方式是所有非幂等工具都接收 idempotency_key，工具端按 key 去重，并把执行状态写入审计日志。

Few-shot 示例携带过期政策

模型学到了旧政策，分类准确但建议错误。修复方式是让示例只示范格式和边界，易变化政策从受控知识源注入，并记录知识版本。

8.6 结构化输出的版本治理

结构化输出一旦被下游系统消费，就进入了接口治理范畴。Prompt 文案、JSON Schema、工具参数和解析器版本都可能影响运行结果。只改 Prompt、不改 schema，看似没有接口变化，实际可能改变字段含义、枚举选择或缺省值；只改 schema、不改评测样本，也可能让模型继续按旧格式输出。生产系统不能把这些变化混在一次普通配置修改里。版本治理需要把 Prompt、schema、解析器和评测样本绑定起来。每个可发布版本都应当说明支持哪些字段、哪些字段必填、哪些字段允许为空、枚举值是否向后兼容、下游工具能否接受旧版本输出。灰度时不能只看模型是否返回合法 JSON，还要看业务动作是否仍然符合预期。比如审批工具新增 risk_reason 字段后，模型能输出该字段只是第一步；平台还要确认审批页面、审计日志和告警规则都能读取这个字段。

schema 漂移的风险尤其高。业务团队常常会把一个字段从字符串改成对象，或者把枚举值从中文标签改成英文代码。如果旧样本没有覆盖这些变化，结构化输出会在低频场景里才暴露问题。比较稳妥的做法是保留一组契约回归样本，覆盖正常输入、缺字段、非法枚举、长文本、工具拒绝和多轮修复。每次 Prompt 或 schema 变化都要跑这组样本，并把失败样本进入第39章的评测库。

8.7 结构化输出的证据与恢复

结构化输出失败时，系统不能只返回解析错误。平台需要区分三类失败：模型没有按格式输出、输出格式正确但业务字段不合理、字段合理但下游工具拒绝执行。三类失败的恢复方式不同。格式错误可以要求模型按 schema 重试，业务字段不合理需要回到用户澄清或补充上下文，工具拒绝执行则要根据错误码决定重试、降级或人工处理。恢复过程还要保留证据。一次失败至少应当记录原始模型输出、解析错误、校验错误、重试 Prompt、修复后的结构化结果和最终工具响应。这样第38章的 Trace 才能看出错误发生在模型、解析器、schema 还是工具层。没有这些证据，团队会倾向于继续调 Prompt，而忽略真正的问题可能是 schema 设计含糊或下游工具错误码不清楚。结构化输出的工程目标是让模型输出进入可验证、可回放、可恢复的接口链路，而不是只让模型“更听话”。只要输出要驱动工具、审批、SQL、报告或外部系统，就应该按接口契约治理。Prompt 可以帮助模型理解任务，但接口责任必须由平台承担。

8.8 接口契约的组织协作

结构化输出的维护不应只交给模型工程师。业务团队定义字段含义，平台团队维护解析和重试，安全团队定义高风险动作，前端团队负责把错误状态展示给用户。若这些角色没有共同契约，字段名看起来一致，实际语义却会分叉。例如 reason 在模型输出中可能表示判断依据，在审批系统中可能表示拒绝原因，在审计系统中又可能表示风险说明。字段复用如果没有解释文档，会让下游系统读到合法但错误的值。因此，每个结构化任务都应当有简短的契约说明，写清楚字段来源、字段用途、默认值、空值含义、失败状态和下游消费者。契约说明不需要做成厚重文档，但必须跟随版本发布。接口变更时，相关样本、前端展示、工具校验和审计字段要一起检查。这个习惯会让结构化输出从 Prompt 技巧变成跨团队可以维护的接口资产。

早期平台可以先选三条链路建立这套协作：信息抽取、工具调用和审批恢复。三条链路覆盖了读、写和人工确认，能暴露大部分结构化输出问题。等这些契约稳定后，再把同样方法推广到 NL2SQL、报告生成和多 Agent Handoff。结构化输出还需要约定观测口径。团队应当统计解析失败率、业务校验失败率、重试成功率、人工介入率和下游工具拒绝率，而非只统计“JSON 合法率”。JSON 合法只能说明模型输出形状正确，不能说明接口可用。把这些指标接入 Trace 后，平台才能判断一次 schema 或 Prompt 变更究竟改善了格式稳定性，还是把错误推到了下游工具。当这些指标长期稳定后，结构化输出才适合扩大到更多业务动作。否则团队会在新场景里重复处理同样的解析、校验和恢复问题。早期平台要先把少数契约跑稳，再扩展任务类型。

这也是后续工具调用和 DataAgent 链路的基础。输出契约越稳定，Planner、Runtime 和前端越容易复用同一套错误处理。结构化输出上线后，团队要持续查看失败类型。语法失败说明模型或约束解码不稳定；字段缺失说明 schema 设计或上下文提示不足；业务校验失败说明模型理解和规则存在差距；审批驳回说明证据展示没有让人放心。不同失败类型对应不同修复路径，不能都靠“再优化 Prompt”处理。版本管理也会影响恢复能力。一次结构化任务至少要记录 Prompt 版本、schema 版本、模型版本、工具版本和校验规则版本。用户投诉某个自动分类结果时，平台要能复现当时的完整契约，而非用今天的 Prompt 和 schema 重新生成一个看似合理的结果。

把结构化输出看成接口工程后，很多取舍会清楚得多。字段少一些，系统更容易稳定消费；证据要求严一些，模型可能多触发人工复核，但事故后更容易解释；重试次数少一些，成本可控，失败也更早暴露。生产系统关心的是可恢复和可追责，也不能只看一次回答看起来格式正确。结构化输出的上线评审可以从一个失败样本开始。让团队拿出一条格式正确但业务错误的结果，说明它会在哪里被拦截。若 schema 能通过，业务校验也能通过，工具还能执行，说明接口契约缺少关键规则。若错误只能靠人工阅读最终答案发现，说明结构化链路没有真正承担生产责任。前端也要理解结构化输出的状态。字段缺失、证据不足、工具参数被拒绝、模型重试中、进入人工复核，这些状态不应都显示成“生成失败”。用户需要知道系统卡在格式、语义、权限还是业务规则上。状态说清楚后，用户可以补充信息，审批人可以要求补证据，平台团队也能定位修复点。

对开发团队来说，结构化输出最容易被忽略的是兼容性。新增字段、修改枚举、收紧必填项，都会影响下游消费者。一个报告生成 Agent 可能已经依赖旧字段渲染图表，一个工单系统可能按旧枚举做自动分派。schema 变更应像 API 变更一样有版本、灰度和回滚，而非随着 Prompt 一起随手修改。审计记录要保存“原始输出”和“校验后对象”。原始输出能帮助模型团队排查生成问题，校验后对象能说明业务系统实际消费了什么。若只保存其中一个，复盘都会缺证据。尤其是工具调用场景，平台还应记录被丢弃的字段、默认补齐的字段和最终执行参数，避免模型输出和实际动作之间出现不可见差异。当结构化输出成为平台通用能力后，业务团队可以更快上线新任务。它们复用 schema 管理、解析、重试、校验、审计和人工复核，而非每个应用重写一遍 JSON 处理逻辑。这种复用才是提示工程进入工程化的标志。

结构化输出还要处理部分成功。合同抽取任务可能成功识别付款日期，却无法确认违约条款；DataAgent 可能生成了可执行 SQL，但图表配置缺少维度；工单分类可能给出类别，却无法给出足够置信度。生产系统不能把这些情况都当作完全失败，也不能直接进入下游。更合适的做法是让 schema 表达状态，把可用字段、缺失字段、待人工确认字段和失败原因分开。字段设计要从下游动作倒推。若字段只用于展示，可以允许自然语言摘要；若字段要进入数据库、审批流或工具参数，就要有严格类型、枚举和单位。金额字段必须说明币种和精度，时间字段必须说明时区和业务日期，证据字段必须能定位到原文。很多结构化输出事故来自字段看起来合理，但下游无法判断它到底代表什么。

重试策略也要克制。格式错误可以短重试，证据不足不能靠重试解决，权限拒绝更不能重试到成功。平台应把解析错误、schema 错误、业务校验错误和策略拒绝分开，给每类错误配置不同恢复动作。若所有失败都重新请求模型，系统会增加成本，也会把真实规则问题掩盖掉。提示词模板的评审要和 schema 评审一起做。模板要求“请给出风险等级”，schema 却允许任意字符串；模板要求引用证据，schema 没有证据字段；模板要求模型在不确定时拒答，schema 没有拒答状态。这些不一致在代码审查中很难发现，只有把模板、schema 和评测样本放在同一个发布包里，才容易检查。

结构化输出的质量还要看长期稳定性。一次任务在今天输出合法 JSON，不代表模型版本、上下文和业务规则变化后仍然稳定。平台可以保留一组小型结构化回归集，每次模板、schema、模型或工具变化时运行。回归集不需要很大，但要覆盖枚举、缺字段、边界值、拒答、证据缺失和工具参数。这样结构化任务才能像普通 API 一样演进。结构化输出还要考虑下游幂等。模型重复返回同一工具参数时，系统应识别这是重试还是新的动作。创建工单、发送邮件、写入审批记录这类动作，都需要业务幂等键和执行状态。否则一次网络重试就可能造成重复副作用，而复盘时只能看到两次格式正确的模型输出。字段默认值也要谨慎。解析器为了让对象完整，可能给缺失字段补默认值；但默认值一旦进入业务系统，就会变成真实决策。比如风险等级缺失时默认低风险，审批原因缺失时默认“模型建议通过”，都会掩盖问题。高风险字段缺失时，更稳妥的动作是进入人工复核或要求补充证据。

结构化输出的文档要面向多角色。模型工程师关注 Prompt 和失败样本，后端工程师关注 schema 和兼容性，前端工程师关注状态展示，业务负责人关注字段含义和人工兜底。把这些信息写在同一份契约中，能减少字段语义在不同系统之间漂移。

8.9 Schema 漂移与发布回放

结构化输出的难点常常出现在“改了一点点”的版本里。一个字段从可选变成必填，一个枚举从自然语言改成代码值，一个金额字段新增币种，一个证据字段从字符串改成数组，都可能让下游系统读取到合法但语义变化的对象。发布回放要把这类漂移放到台面上。每次 Prompt、schema、解析器、工具契约或模型版本变化，都应选择一组固定样本重放：正常样本、字段缺失样本、非法枚举样本、证据不足样本、权限拒绝样本和工具超时样本。重放结果不只看 JSON 是否通过，还要看业务校验、工具执行、前端状态和审计记录是否一致。

Schema 漂移还要检查默认值。很多解析器为了让对象完整，会给缺失字段补默认值；但默认值一旦进入审批、工单、SQL 或报告系统，就会变成真实业务含义。风险等级缺失时默认低风险，审批意见缺失时默认通过，时间范围缺失时默认本月，这些处理都会隐藏问题。更稳妥的方式是把默认值来源写入校验结果：哪些字段来自模型，哪些字段由规则补齐，哪些字段需要人工确认。前端和审计系统都应能看到这一区分，避免用户把补齐字段误认为模型已经确认。

发布回放也能帮助团队判断错误归属。若新版本格式失败率上升，可能是 Prompt 示例、模型路由或约束解码问题；若格式稳定但业务校验失败，说明字段语义或上下文不足；若业务校验通过但工具拒绝，说明工具契约和结构化对象之间还有缺口。把这些结果写入发布记录后，下一次事故就能直接回到当时的契约组合，而不是重新猜测模型为什么输出某个字段。

8.10 接口契约变更与失败样本

Prompt、结构化输出和函数调用进入生产后，接口契约会不断变化。新增字段、字段改名、枚举扩展、必填项调整、错误码变化、工具参数收紧，都会影响上层 Agent。若这些变化只体现在 Prompt 文本里，测试和回滚都会困难。平台应把 Prompt 和输出 schema 当成接口版本管理，而不是把它们当成一次性提示词。

失败样本要绑定接口版本。结构化输出缺字段、JSON 无法解析、工具参数越界、模型把解释文本混入字段、schema 约束过严导致拒答，这些样本都应记录当时的 Prompt 版本、模型版本、schema 版本和恢复动作。这样团队才能判断问题来自模型能力、schema 设计、示例不足，还是下游工具契约变化。

接口契约变更还要有灰度策略。低风险字段可以先允许兼容读取，高风险字段必须经过评测样本和人工确认；旧字段下线前要检查哪些 Agent、报告模板和前端组件仍在使用；错误码变化要同步 Runtime 和 UI 文案。第8章讨论 Prompt 的工程化目标：让自然语言到结构化动作之间的接口可测试、可回滚、可审计。

8.11 Schema 漂移的监控信号

结构化输出的 schema 漂移需要监控。模型可能开始省略字段、改变枚举写法、把数字写成文本、把解释塞进 JSON 字段，或者在工具参数中加入未定义键。一次漂移不一定让系统立刻失败，却会让下游工具、前端组件和评测脚本逐渐失真。平台应把 schema 合规率、字段缺失率、解析失败率、自动修复率和人工修正率纳入观测。

监控信号要和发布事件关联。模型版本、Prompt 版本、schema 版本、工具版本、前端版本任何一个变化，都可能触发漂移。若监控只记录失败次数，团队仍然难以定位原因。更可靠的做法是把每次结构化输出失败绑定到版本组合和样本，复盘时直接比较变更前后的字段表现。

漂移处理也要分级。低风险字段可以尝试兼容解析并记录告警；影响工具执行的字段要阻断并请求重试；影响写操作和审批的字段必须进入人工复核。这样结构化输出既保持灵活性，也不会把模型格式错误传递成真实业务动作。

8.12 结构化输出的消费者验收

结构化输出最终由下游系统消费，验收也要覆盖消费者。一个 JSON 结果通过 schema 校验，不代表业务系统能安全使用。工作流引擎关心状态字段，工具执行器关心参数完整性，前端关心可渲染字段，审计系统关心证据引用。若消费者没有参与验收，格式正确的输出仍可能触发错误动作。

消费者验收应保存输入、输出、schema 版本、消费者版本、失败原因和修复方式。每次 schema 变更前，平台回放这些样本，确认旧消费者能降级，新消费者能识别缺失字段。结构化输出越接近动作入口，消费者验收就越重要。

8.13 下游消费者迁移窗口

结构化输出的接口升级要给下游消费者留迁移窗口。很多 Agent 链路不是模型一端改完就结束：前端组件、工作流引擎、工具执行器、审计系统、评测脚本和报表模板都可能依赖旧字段。若 schema 新版本立即替换旧版本，模型可能已经按新格式输出，前端仍按旧字段渲染；工具可能已经要求新枚举，Planner 仍然生成旧参数；审计系统可能保存了新对象，却无法解释旧报告中的字段含义。迁移窗口的价值，是让不同消费者按顺序升级，而不是把一次接口变化变成线上联调。

迁移窗口至少要覆盖读兼容、写兼容和回放兼容。读兼容意味着新消费者能理解旧对象，避免历史 Trace 和报告失效；写兼容意味着模型在灰度期间可以输出旧版本或新版本，平台按租户、任务或路由选择；回放兼容意味着评测样本能同时校验两种版本，比较业务结果是否一致。对于高风险动作，例如审批、工单创建、SQL 执行和外发消息，旧版本下线前还要确认幂等键、权限字段、证据字段和失败状态都已迁移。

字段迁移要避免静默默认。新增字段如果没有模型输出，解析器可以补默认值，但默认值必须带来源标记。前端看到“由规则补齐”的风险等级，与看到“模型根据证据判断”的风险等级，含义不同。下游工具也应知道某个参数来自模型、规则、用户确认还是人工复核。没有来源标记时，默认值会在业务系统里变成事实，后续复盘很难解释它是如何产生的。

迁移窗口还要设置退出条件。比如旧字段连续两周没有新写入，历史消费者已升级，评测样本在新旧版本下结果一致，高风险失败样本没有新增，才允许关闭旧版本。关闭后仍要保留历史 schema 和解析器，用于 Trace 回放和审计导出。结构化输出越像 API，就越需要这样的兼容纪律。它会让发布节奏稍慢，但能减少“格式合法、业务失败”的线上问题。

8.14 Schema 回滚与消费者保护

结构化输出的回滚比普通 Prompt 回滚更复杂。一个 schema 一旦被下游系统消费，就会进入前端表单、工具参数、报告模板、评测样本和审计记录。发布后发现字段含义不清、枚举值不稳定或必填字段过多时，不能简单把模型提示词退回旧版本。下游消费者可能已经按新字段写入数据，旧消费者也可能仍在读取旧字段。回滚策略要同时保护生产请求和历史 artifact。

比较稳妥的方式是保留短期双读双写窗口。新 schema 上线时，Runtime 同时记录新旧字段映射，Gateway 对输出做版本标记，下游消费者声明自己接受的版本。若新版本出问题，平台可以把新请求路由回旧 schema，同时保留已产生 artifact 的解释方式。对于结构化工具参数，还要确认旧 schema 是否仍能被工具 handler 接受；对于报告和 DataAgent 产物，要确认 EvidenceRef 是否仍能指向原始证据。

消费者保护也要进入发布评审。每次 schema 变更前，团队应列出受影响消费者：前端组件、工具 handler、数据写入接口、报告模板、Eval 样本、Trace 解析器和人工审核界面。若某个消费者无法在迁移窗口内完成适配，就不能把旧字段直接删除。对高风险任务，平台还应要求失败样本回放，验证模型在旧新 schema 之间切换时不会把字段含义混用。

早期可以先给每个结构化输出增加 schema_version、producer、consumer 和 migration_note。这些字段看起来简单，却能在事故复盘时说明输出由谁产生、谁消费、按哪个版本解释、迁移时留下了什么限制。结构化输出的成熟度，不只体现在 JSON 能否校验通过，还体现在 schema 演进时下游系统不会被突然打断。

8.15 Prompt 变更的发布证据

Prompt 在企业平台中承担接口契约的一部分。它决定模型看到哪些字段、怎样解释工具结果、怎样处理证据不足、怎样输出结构化结果。Prompt 变更如果只通过代码 review 或配置发布，很容易漏掉业务影响。一个措辞变化可能让模型更愿意给建议，却减少引用；一个 schema 描述变化可能让工具参数更稳定，也可能让旧样本无法通过。

发布证据要从样本开始。每次 Prompt 变更应绑定任务类型、输入样本、预期输出、结构化校验、引用校验、安全样本和人工判断。对于 DataAgent，样本还要覆盖 SQL 解释、图表说明、报告摘要和拒答。若 Prompt 影响多个 Agent，发布单要说明哪些 Agent 共享模板，哪些只继承基础规则。这样团队能判断变更是局部修复还是平台级接口变化。

Prompt 回滚也要有边界。模型、工具 schema 和语义层可能已经跟随新 Prompt 调整，简单回滚文本会让链路再次不一致。平台应保存 Prompt 版本、模型版本、工具版本和评测结果的组合。若需要回滚，先确认要回到哪一组组合，而不是只把一段文本改回旧版本。

早期可以建立 Prompt 发布台账：变更目的、影响 Agent、样本结果、结构化输出通过率、人工复核结论、灰度范围和回滚组合。这样 Prompt 不再是经验文本，而是可发布、可回放、可治理的接口资产。

8.16 Prompt 契约的发布证据

Prompt 与结构化输出进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把输入字段、输出 schema、拒答规则、版本号、失败样本和回滚记录记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第7章模型调用、第25章 Planner 和第39章 Eval相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括Prompt 改动没有版本、schema 漂移进入下游、拒答文案被误认为业务结论。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

Prompt 应作为接口契约发布，和评测样本、产物 schema、回滚策略一起管理。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

8.17 结构化输出的消费者契约

结构化输出的 schema 要面向消费者设计。下游系统使用 JSON、函数参数或报告片段时，主要关心字段含义是否稳定、缺省值是否可解释、枚举值是否受控、错误状态是否能恢复，合法文本只是最低要求。Prompt 章节需要把结构化输出写成接口设计问题，避免把它简化成格式约束技巧。

消费者契约应包含版本、必填字段、可选字段、字段来源、置信度、错误码和弃用计划。字段新增时，下游可以忽略；字段删除或语义变化时，需要迁移窗口；模型无法给出可靠字段时，应返回明确错误，而非猜测一个看似合理的值。这样 Prompt 才能进入平台工程链路，和 ToolSpec、Artifact schema 以及评测样本保持一致。

本章小结

Prompt 是输入侧接口，结构化输出是输出侧契约，工具调用是受控系统动作。三者都需要绑定版本、评测和回滚，不能只靠“请输出 JSON”这类提示词约束。解析校验、schema 校验、业务校验、重试和人工兜底都要进入链路。模型可以生成工具调用建议，但执行必须由平台完成，鉴权、参数校验、幂等和审计不能交给模型文本决定。schema 应从最小可用字段开始；复杂任务更适合拆成多个小对象、多步校验和局部重试。结构化输出的成熟度不取决于 Prompt 写得多复杂，而取决于失败能否被分类、恢复、复现和回滚。

参考文献

JSON Schema. (n.d.). Specification.

OpenAI. (n.d.). Structured Outputs guide.

Guidance. (n.d.). Documentation.

Instructor. (n.d.). Documentation.

第9章 模型能力定制与知识增强

企业遇到模型效果问题时，要先判断该改 Prompt、接 RAG、做微调，还是引入偏好对齐。很多团队一看到模型答错就想到 fine-tune，但线上失败的根因可能是知识过期、输出格式不稳、权限边界缺失或评测样本不足。微调适合学习任务模式和领域表达，RAG 适合接入可更新、可引用的企业知识，对齐适合调整拒答、风格和安全偏好。这些路线应放在同一条闭环中：从失败样本分诊开始，经过数据治理、训练或知识更新、评测、灰度和回滚，再回到线上监控。一个企业助手上线后，业务团队通常会很快反馈“模型不懂我们”。客服团队说分类口径不稳定，法务团队说风险等级不符合内部规范，数据团队说模型总是用错指标口径，人力团队说制度问答引用了旧政策。这些问题表面相似，处理方式却不同。

如果模型不知道上周刚更新的休假政策，应该更新知识库，不要训练模型记住新政策。如果模型能理解问题，却总是不按固定 JSON 输出，应先检查 Prompt、schema 和结构化输出链路。如果模型长期写出错误 SQL 模式，说明任务分布与基座模型差异较大，才可能需要 SFT 或 LoRA。如果模型在灰区问题上喜欢给出过度承诺，就要处理偏好和安全边界。能力定制的第一步是分诊：先确认问题来自知识、输出契约、任务分布还是偏好边界，再选择 RAG、Prompt、微调或对齐手段。企业团队说“模型不懂我们”时，背后可能是完全不同的问题。模型不知道最新制度，是知识更新问题；模型总把字段映射错，是任务分布问题；模型能答对但格式不稳，是接口契约问题；模型在敏感场景回答过于激进，是偏好和安全策略问题。若一开始就把所有问题归为“需要微调”，团队会花很大成本训练出一个仍然无法上线的模型。

能力定制的第一步应是失败样本分诊。每个失败样本都要还原输入、上下文、候选知识、模型输出、工具结果和人工判断。数据团队可以判断是否缺少语义层口径，平台团队可以判断是否缺少结构化校验，模型团队再判断是否需要 SFT、LoRA 或偏好对齐。没有这一步，RAG、微调和 Prompt 优化会互相替代，最后没人能说明哪项改动真正解决了问题。一个典型场景是制度问答助手在政策更新后继续引用旧条款。业务方会要求“训练模型记住新制度”，但更合适的动作通常是修复知识库更新、文档切分、版本索引和引用校验。另一个场景是 DataAgent 长期生成错误的指标口径，即使知识库里有定义仍然选错字段，这时才可能需要微调模型学习企业任务模式。定制路线要服务失败原因，而非服务团队偏好的技术路线。

9.1 先判断问题类型

9.1.1 能力定制的三条路线

企业想让模型“更懂业务”，通常会走三条路线：微调、RAG 和对齐。它们可以组合，但不能互相替代。

表9-1：能力定制路线与适用问题。来源：本书整理。

客服助手可能同时使用这三类能力：RAG 检索最新政策，LoRA 学习工单分类口径，对齐模型避免越权承诺赔付。每个失败样本都要说明根因，不能把所有问题都归为“模型不够懂业务”。

9.1.2 失败样本分诊

失败样本应先进入分诊表，不要直接进入训练集。分诊的目标是回答两个问题：模型缺的是知识、格式、任务能力，还是偏好边界；这个问题能不能通过低成本、可回滚的方式解决。

表9-2：常见失败症状、可能根因与优先方案。来源：本书整理。

表9-2 背后有一个实用原则：先做可解释、可回滚、链路局部的改动。Prompt 和 schema 可以很快灰度和回滚；RAG 知识快照也能追踪。微调会改变模型行为，应该在评测证明必要之后再做。

分诊还要保留反例。比如同一类“回答错误”里，可能同时有知识过期、检索噪声和模型推理失败。只记录成功修复的样本，会让后续训练集越来越单一；保留失败修复记录，才能帮助团队判断下一轮是该补知识、改检索，还是进入模型训练。

图9-1：能力定制技术路线选择。来源：本书自绘。Alt text：图中以问题分诊为起点，分别指向知识过期、格式不稳、能力不足和偏好边界四类问题，并对应 RAG、Prompt、微调和对齐路线。

图 9-1 的重点是先分诊再选路线。知识缺失先走外部知识或工具，格式不稳先修结构化输出，长期任务行为差异再进入微调，偏好和安全边界问题才进入对齐。

9.1.3 Prompt、RAG、微调与对齐的分工

Prompt 调整改变的是请求上下文。它适合表达任务规则、输出格式和少量边界案例。RAG 改变的是回答前能看到的外部知识，适合需要引用来源和频繁更新的事实。微调改变的是模型参数或 adapter，适合让模型长期学习某类任务模式。对齐改变的是模型偏好，适合处理“应该怎么回答”和“什么时候拒答”。这几个边界在工程上很重要。把动态知识写进模型参数，会导致更新慢、不可追溯、难删除。把任务能力问题全交给 RAG，会得到更多上下文，但不一定得到更稳定的推理和格式。把安全问题全交给 DPO，也不能替代权限、脱敏、工具白名单和审计。

9.1.4 不适合微调的场景

微调不能永久写入企业知识。微调更适合学习任务模式和表达习惯，不适合承载频繁变化的事实。员工制度、商品价格、库存、合同状态和指标口径版本应通过 RAG、工具或数据库查询接入。RAG 也不能替代模型能力。RAG 能提供知识，但不能自动让模型学会复杂任务。检索到了财务口径文档，不代表模型就能稳定生成正确 SQL；检索到了合同模板，也不代表模型就能正确抽取风险条款。对齐不能单独解决安全问题。对齐可以提高拒答倾向和风格一致性，但不能替代权限、审计、脱敏、工具白名单和业务规则。模型即使倾向于拒绝越权请求，工具执行层仍然必须做硬校验。训练数据也不是越多越好。低质量、重复、冲突、过期的数据会让模型退化。企业微调最怕把历史噪声当成真理：旧政策、错误客服话术、临时 workaround 和 SQL 反模式都会被模型学进去。

9.2 从失败样本到灰度发布

9.2.1 能力定制在模型、知识与评测之间的位置

模型能力定制位于模型平台、数据平台、评测平台和业务应用之间。它是一条持续反馈回路，不应被当作一次训练任务：线上问题进入样本池，样本经过治理后进入训练、对齐、RAG 更新或 Prompt 修订，再通过评测、灰度和监控回到线上。

flowchart TD
    App["业务应用 / Agent Runtime"] --> Gateway["LLM Gateway<br/>路由 / 配额 / 审计"]
    Gateway --> Base["基座模型<br/>闭源 API / 开源权重"]
    Gateway --> Adapter["定制模型或 Adapter<br/>SFT / LoRA / QLoRA"]
    Gateway --> Rag["RAG 服务<br/>检索 / 重排 / 引用"]
    Rag --> KB["知识库<br/>文档 / 向量库 / 元数据"]

    Logs["线上日志与反馈"] --> Data["数据治理<br/>清洗 / 脱敏 / 标注 / 版本"]
    Data --> Train["训练与对齐<br/>SFT / DPO / KTO"]
    Data --> Eval["评测集<br/>任务 / 安全 / 回归"]
    Train --> Registry["模型注册表<br/>版本 / adapter / 训练数据"]
    Registry --> Eval
    Eval --> Release["发布决策<br/>灰度 / 回滚 / 路由策略"]
    Release --> Gateway

图9-2：模型能力定制的持续闭环。来源：本书自绘。Alt text：图中展示线上失败样本进入数据治理、训练或知识更新、评测、灰度发布和监控的闭环，模型版本、adapter 和知识快照都进入注册表。

图 9-2 里有三个关键边界。业务应用不应该直接关心模型是否经过 LoRA 或是否接入 RAG，它只声明任务、租户、风险等级和知识域。训练数据和评测数据必须隔离，否则微调后的分数只是记住了测试题。RAG 知识库、adapter、Prompt 模板和模型版本都要进入注册表，线上回答才能被复现和回滚。

9.2.2 数据、训练、知识和发布组件

能力定制链路可以拆成若干组件，但核心职责并不复杂：收样本，治数据，训练或更新知识，评测，通过网关灰度。图 9-1 按这个顺序展开，目的是把微调、RAG 和对齐放回同一条发布链路中比较。

表9-3：能力定制闭环的核心组件。来源：本书整理。

训练任务的契约至少要把模型、数据、方法和评测门槛写清楚。这样做目的在于让后续灰度、回滚和复盘都能找到同一套依据，文档好看只是手段之一。

job_id: customer_service_sft_2026_06
base_model: qwen3-32b-instruct
method: lora_sft
dataset:
  train: datasets/customer_service/sft/train-2026-06.jsonl
  validation: datasets/customer_service/sft/validation-2026-06.jsonl
  data_policy: pii_redacted_v2
training:
  lora_rank: 16
  learning_rate: 0.0001
  epochs: 2
  max_seq_length: 4096
evaluation:
  suites:
    - customer_service_classification
    - refusal_and_compliance
    - structured_output_regression
  gates:
    task_accuracy_min: 0.88
    json_validity_min: 0.98
    safety_regression_max: 0.01
release:
  canary_tenants:
    - demo-retail
  rollback_to: qwen3-32b-instruct@baseline

RAG 管线的契约关注点和训练任务不同，重点在知识版本、索引策略和权限过滤。下面这份配置示例故意把这些信息单独列出来，便于和模型训练配置区分。

knowledge_domain: employee_policy
snapshot: 2026-06-01
sources:
  - hr_policy_handbook
  - benefits_faq
index:
  embedding_model: bge-m3
  chunk_policy: policy_v3
  vectorstore: enterprise_vectorstore
retrieval:
  top_k: 20
  rerank_top_k: 6
  require_citation: true
security:
  metadata_filters:
    tenant: demo-company
    visibility: employee

这类配置不是形式主义。线上问题发生时，团队需要知道回答用了哪个 adapter、哪个 Prompt、哪个知识库快照、哪个评测报告和哪条灰度规则。没有这些记录，模型能力定制就很难进入可运维状态。

9.2.3 生命周期与回退策略

能力定制不是一次训练完成就结束，它有一条持续进入问题分诊、评测、灰度和回退的发布链。下面的状态机把这条链路压缩成便于讨论的最小骨架。

stateDiagram-v2
    [*] --> ProblemTriage
    ProblemTriage --> PromptChange: prompt/schema issue
    ProblemTriage --> RagUpdate: missing or stale knowledge
    ProblemTriage --> FineTune: task behavior gap
    ProblemTriage --> Alignment: preference or policy gap
    PromptChange --> Eval
    RagUpdate --> Eval
    FineTune --> Train
    Alignment --> Train
    Train --> Eval
    Eval --> Reject: quality or safety gate failed
    Eval --> Canary: gates passed
    Canary --> Rollback: regression detected
    Canary --> FullRelease: stable
    Reject --> DataFix
    Rollback --> DataFix
    DataFix --> ProblemTriage
    FullRelease --> Monitor
    Monitor --> ProblemTriage: new failures
    Monitor --> [*]

失败恢复也要按类型处理。

表9-4：能力定制链路的失败模式与修复路径。来源：本书整理。

表9-4 可以直接用于上线评审。它提醒团队：训练失败不一定发生在训练脚本里，更多时候发生在样本、评测、发布和回滚边界。

9.3 能力定制路线的决策框架

9.3.1 Prompt、RAG、微调和对齐的选择

Prompt 调整成本低、上线快、易回滚，适合规则清楚、样本较少、格式约束明确的任务。RAG 适合知识更新快、需要引用来源、权限可控的任务。SFT / LoRA 适合分类、抽取、SQL、固定工作流等任务模式长期不稳定的场景。DPO / KTO 适合客服话术、合规拒答和安全偏好，但需要高质量偏好数据。工程顺序通常是：先修 Prompt、schema、RAG 和评测，再决定是否微调。只有当评测证明低成本手段无法稳定解决问题，并且训练样本足够干净时，微调才值得进入发布流程。

判断路线时还要看问题是否可被“外部化”。知识、权限、时间和数据状态通常应该外部化，由 RAG、工具或数据库在调用时提供；任务格式、术语习惯和稳定分类口径才适合让模型长期学习。把可外部化的问题写进模型，会让删除、纠错和审计变得困难；把稳定任务能力全部放到外部上下文，又会让每次调用都携带大量规则，增加延迟和不确定性。因此，路线选择不应只由模型团队决定。业务 Owner 要确认规则是否稳定，数据团队要确认知识是否可版本化，安全团队要确认样本能否用于训练，平台团队要确认发布和回滚是否可控。一个样本在进入微调前，至少应回答“是否有更低成本修复方式”“修复后如何评测”“失败时如何回滚”三个问题。

9.3.2 全量微调与 LoRA / QLoRA

全量微调调整能力强，但成本高，回滚和多租户治理都复杂。LoRA 和 QLoRA 更适合多数企业任务，因为 adapter 小、发布快、回滚简单，也方便同一个基座模型服务多个业务域。它们的代价是能力上限受基座模型影响，训练稳定性和评测仍要认真处理。adapter 的治理价值很高。网关可以按租户、任务和风险等级选择 adapter；新版本出问题时，也可以只回滚某个业务域，避免影响所有任务。

9.3.3 知识写进模型还是放在外部

事实性知识越动态、越敏感、越需要引用，就越不应该写进模型参数。员工制度、产品价格、库存、订单状态、合同条款和指标口径应走 RAG、工具或数据库查询。模型参数更适合学习稳定术语、任务格式、领域语言和长期不变的表达习惯。

9.3.4 单一通用模型与领域模型矩阵

早期平台可以用单一通用模型降低运维复杂度。任务增多后，通用模型加 adapter 是更可靠的折中。只有在金融、法务、代码等高价值领域，且评测和运维体系成熟后，才适合维护多个领域专用模型。模型矩阵越复杂，越需要统一注册、评测、路由和成本治理。

9.4 能力定制的发布与回退链路

9.4.1 定制策略的模型目录与评测链路

mini-platform 当前相关模块以边界表达为主：mini-platform/core/gateway/ 负责网关与模型路由，mini-platform/core/eval/ 负责评测反馈链路，mini-platform/core/rag/ 表达 RAG 抽象，mini-platform/infra/vectorstore/ 表达向量库基础设施，mini-platform/core/observability/ 负责可观测性。后续实现可以增加以下文件。这组路径要先表达发布边界，而非急着堆训练脚本。mini-platform/core/gateway/customization_policy.py 负责根据任务、知识域和风险等级选择 Prompt、RAG 或 adapter；mini-platform/core/gateway/model_registry.py 记录基座模型、adapter、评测结果和发布状态；mini-platform/core/eval/model_eval.py 汇总任务评测、安全评测和回归评测；mini-platform/core/rag/retriever.py 根据知识域检索上下文并返回引用；mini-platform/infra/vectorstore/client.py 则封装索引、查询、过滤和版本快照。把这些职责拆开，是为了让每次发布都能被复现。customization_policy.py 决定某次调用使用哪种能力组合；model_registry.py 记录可回滚对象；model_eval.py 给出是否能进入灰度的证据；RAG 与向量库接口则把知识快照和权限过滤留在模型参数之外。这样，线上回答出现问题时，团队能沿着 route、adapter、prompt、knowledge snapshot 和 eval report 逐层定位，而非只看到一个模型名称。

9.4.2 定制策略示例

下面示例展示一个线上网关可用的能力定制策略。它不训练模型，只决定当前任务应该使用哪种能力组合。

# 来源建议：mini-platform/core/gateway/customization_policy.py
from __future__ import annotations

from dataclasses import dataclass

@dataclass(frozen=True)
class ModelRoute:
    base_model: str
    adapter: str | None = None
    prompt_template: str | None = None
    rag_domain: str | None = None
    require_citation: bool = False
    safety_profile: str = "default"

@dataclass(frozen=True)
class TaskContext:
    task: str
    tenant: str
    risk_level: str
    knowledge_domain: str | None = None

class CustomizationPolicy:
    def resolve(self, ctx: TaskContext) -> ModelRoute:
        if ctx.task == "employee_policy_qa":
            return ModelRoute(
                base_model="qwen3-32b-instruct",
                prompt_template="policy_qa_v3",
                rag_domain="employee_policy",
                require_citation=True,
                safety_profile="hr_policy",
            )

        if ctx.task == "customer_service_classification":
            return ModelRoute(
                base_model="qwen3-32b-instruct",
                adapter="customer_service_lora_v2",
                prompt_template="complaint_classifier_v2",
                safety_profile="customer_service",
            )

        if ctx.risk_level == "high":
            return ModelRoute(
                base_model="qwen3-32b-instruct",
                prompt_template="high_risk_default_v1",
                safety_profile="strict",
            )

        return ModelRoute(base_model="qwen3-32b-instruct", prompt_template="default_v1")

模型注册表里不应只保存模型名，还要把训练数据、评测结果和发布状态一起挂上去。这样线上出现回归时，团队才能顺着同一条记录追到训练批次、评测证据和发布窗口。

{
  "model_version": "customer_service_lora_v2",
  "base_model": "qwen3-32b-instruct",
  "adapter_uri": "models/adapters/customer_service_lora_v2",
  "training_data": "datasets/customer_service/train-2026-06.jsonl",
  "eval_report": "reports/customer_service_lora_v2.json",
  "status": "canary",
  "created_at": "2026-06-09",
  "rollback_to": "qwen3-32b-instruct@baseline"
}

RAG 侧也需要快照化。

{
  "rag_domain": "employee_policy",
  "snapshot": "2026-06-01",
  "embedding_model": "bge-m3",
  "chunk_policy": "policy_v3",
  "top_k": 20,
  "rerank_top_k": 6,
  "require_citation": true
}

9.4.3 adapter、Prompt 与 RAG 版本的发布门禁

能力定制进入生产流量前至少要看五类证据。表 9-8 将这些证据拆开，是为了让发布评审能同时看到质量、成本、回滚和审计材料。

表9-5：模型能力定制上线前验证项。来源：本书整理。

这些验收项的目的，是让失败有迹可循，不是拖慢发布。没有评测和版本治理的微调，会把模型从“偶尔答错”推向“行为不可解释”。早期平台可以先把验收做成发布清单和脚本检查，不必一开始就建设完整 MLOps 系统。只要每次发布都能拿到样本版本、评测报告、路由策略和回滚目标，模型能力定制就从一次性实验进入了可复审的工程流程。发布门禁还要避免只看平均分。一个 adapter 的总体准确率可能上升，但安全拒答、JSON 有效率或长尾业务类别下降；RAG 快照的引用命中率可能提高，但权限过滤漏掉了边界样本。发布报告应展示主指标、反指标和失败样例，而非只写“通过”。只有失败样例能被复现，灰度期间的线上问题才能回到样本治理环节。

9.4.4 能力定制出问题时先分清责任层

用微调解决政策更新

上线当天回答正确，几周后制度更新，模型仍引用旧政策。修复方式是把政策问答改为 RAG，微调只保留回答格式、引用规范和拒答边界。

客服微调后 JSON 有效率下降

模型语气更自然，但结构化分类接口解析失败增加。修复方式是按任务分层训练集，结构化任务单独评测，并把 JSON validity 放进发布 gate。

DPO 后过度拒答

合规风险下降，但正常问题也频繁回答“无法处理”。修复方式是补充安全可答正例，按风险等级拆分安全策略。

RAG 检索到无权限文档

普通员工问福利政策时，回答引用了仅 HR 可见的内部说明。修复方式是在索引写入租户、部门、密级和有效期等 metadata，检索时强制过滤。

新 adapter 发布后无法复现问题

日志只记录模型名，没有记录 adapter 和 Prompt 版本。修复方式是每次调用记录 base_model、adapter、prompt_template、schema、RAG snapshot 和 release_id。

9.5 能力定制的发布证据

模型能力定制不能只凭一组离线分数上线。Prompt 调整、RAG 扩容、LoRA adapter 和对齐策略都会改变模型行为，但改变的范围不同，回滚成本也不同。上线前需要准备发布证据，说明这次定制解决了哪些失败样本，影响了哪些业务域，是否引入新的拒答、幻觉、格式错误或安全风险。没有这份证据，能力定制很容易变成“感觉更好”的经验判断。发布证据应当覆盖四类样本。第一类是目标样本，也就是本次定制要修复的问题；第二类是邻近样本，检查模型是否把相似但不同的意图混在一起；第三类是反向样本，确认不该回答、不该调用工具、不该越权的场景仍然被拦住；第四类是历史高频样本，防止新版本破坏已经稳定的能力。对于 RAG 和微调组合使用的系统，还要区分答案改善来自模型参数、检索内容还是 Prompt 编排。发布证据要进入模型目录和评测系统。模型目录记录版本、adapter、Prompt、知识库、训练数据摘要和适用范围；评测系统记录样本、指标和失败分析。两者结合起来，平台才能在问题发生时判断应该回滚模型、回滚 adapter、回滚知识库，还是只修复 Prompt。能力定制应纳入持续发布过程，不能被当作一次训练任务。

9.6 定制策略的生产边界

并不是所有能力缺口都适合通过微调解决。业务口径频繁变化、权限强相关、需要实时数据、答案必须带证据的场景，更适合放在 RAG、工具调用或语义层里。微调适合稳定表达风格、结构化任务习惯、领域术语理解和特定格式输出，但不适合承载每天变化的企业事实。把事实写进模型，会让更新、审计和删除都变得困难。生产边界还包括数据治理。训练样本、偏好样本和失败样本可能包含客户信息、内部流程、敏感字段或业务策略。平台需要在进入训练前完成脱敏、授权和用途登记，并记录样本来源。若用户要求删除某类数据，团队要知道它是否进入了训练集、评测集、RAG 索引或日志。相比 RAG，微调后的删除和追溯成本更高，因此更需要前置审查。能力定制的最终判断标准，是它是否降低了平台复杂度。一个 adapter 如果让业务链路更稳定、评测更清楚、回滚更简单，它就是合适的；如果它只是把 Prompt 和知识库的问题藏进模型参数里，后续治理会更困难。读者在设计企业 Agent 平台时，应当把能力定制看作发布工程，而非模型训练技巧。

9.7 失败样本的分层归因

能力定制的第一步是把失败样本分层归因，再选择训练、检索、Prompt 或策略手段。一个回答失败可能来自指令理解、知识缺失、工具选择、格式输出、业务规则、权限限制或安全策略。若团队没有先做归因，就很容易用微调解决检索问题，用 RAG 解决格式问题，或者用 Prompt 掩盖权限问题。短期看似有效，长期会让系统边界越来越不清楚。归因时应保留原始问题、模型输出、检索结果、工具调用、用户反馈和人工修正。对每个样本先判断“模型是否拥有完成任务所需信息”，再判断“模型是否有正确动作空间”，最后判断“输出是否符合接口和业务规则”。如果信息缺失，优先考虑知识库、语义层或工具；如果动作空间错误，优先调整工具暴露和策略；如果表达和格式不稳定，再考虑 Prompt、结构化输出或微调。

这套分层会让能力定制更慢一些，但能避免错误投资。模型训练和 adapter 维护有持续成本，一旦把错误样本混进训练集，后续还涉及其他场景。企业平台需要的是可解释的能力演进，而非每次遇到失败都启动一轮新训练。能力定制还要有停用机制。某个 adapter 或 Prompt 版本长期没有带来质量收益，或者只服务少量低价值场景，就应当进入观察和下线流程。下线前要确认依赖它的 Agent、评测样本和发布配置，避免直接破坏线上能力。模型能力资产越多，治理成本越高；定期清理无效版本，是保持平台可维护性的必要工作。停用机制也能让团队更谨慎地引入新版本。每次新增 adapter、知识增强策略或对齐配置，都意味着后续要维护评测、回滚和解释材料。把生命周期成本算进去，能力定制才不会变成无边界的版本堆叠。

能力定制还要明确 owner。Prompt、RAG、adapter 和安全对齐通常由不同团队维护，线上问题发生后必须知道由谁判断、谁回滚、谁补样本。没有 owner 的定制版本，即使效果不错，也不适合进入核心链路。owner 还负责判断能力边界是否仍然成立。业务变化后，原本有效的定制策略可能不再适用，必须重新评估样本和发布范围。能力定制还需要灰度和回退。微调模型、RAG 索引、Prompt 模板和偏好策略都可能改善一类任务，同时伤害另一类任务。发布前的评测集要覆盖成功样本、历史失败样本和高风险边界样本；发布后还要观察真实用户问题是否偏离评测集。

数据治理是定制质量的底座。训练样本、检索文档和偏好数据都要标明来源、时间、适用范围和脱敏状态。把临时工单、个人偏好或过期制度混进训练数据，会让模型形成难以定位的错误习惯。定制后的模型越强，数据污染带来的事故越隐蔽。最终，企业应把能力定制做成一条运营链路：失败样本进入分诊，分诊决定路线，路线产生可发布资产，资产经过评测和灰度，再由线上监控继续补充样本。这样团队才知道什么时候该改知识库，什么时候该改 Prompt，什么时候值得训练模型。能力定制还要明确资产归属。Prompt 模板归应用团队维护，知识库归内容或数据团队维护，训练数据归模型团队和业务专家共同确认，评测集归平台质量体系维护。归属不清时，线上失败会在多个团队之间流转，最后变成“模型效果不好”的泛化结论。归属清楚后，每类问题都有入口和处理时限。

定制路线的成本结构也不同。RAG 的成本主要在文档治理、解析、索引和检索评测；微调的成本在样本构造、训练、推理部署和回归；偏好对齐的成本在成对样本、人工标注和安全验证。业务方提出“让模型更懂我们”时，平台需要把这些成本说清楚，帮助业务选择足够好而非最复杂的方案。发布后的观察窗口尤其重要。微调模型可能在历史样本上提升明显，却在新业务问题上过拟合；RAG 更新可能让新政策可见，同时引入重复文档和冲突版本；偏好策略可能让模型更安全，也可能过度拒答。观察窗口内要看人工驳回、无答案率、引用错误、格式失败和用户追问，而非只看离线准确率。失败样本进入训练或知识更新前，还要做脱敏和范围判断。一次客服个案中的特殊处理，不应被模型学成通用规则；一个地区的制度口径，也不应自动影响全国。样本带着来源、时间和适用范围进入资产库，后续才有机会解释模型为什么形成某种行为。

能力定制做得成熟后，团队会少一些路线争论，多一些证据判断。看到失败样本，先判断缺知识、缺格式、缺策略还是缺任务能力，再选择 RAG、Prompt、微调或对齐。这个顺序能减少无效训练和无效调参。失败样本分诊要进入工具链，而非依赖临时会议。每个线上失败都可以记录为一张卡片：用户问题、上下文来源、模型输出、实际后果、人工修正、初步归因和建议路线。模型团队看到的是训练或对齐线索，数据团队看到的是知识和口径缺口，平台团队看到的是运行时和校验问题。卡片积累到一定规模，团队才能看出哪类问题最值得投入。微调前还要确认推理链路是否稳定。如果 Prompt、schema、检索、权限和评测都还在频繁变化，训练出的模型很快会追不上平台状态。很多企业第一次微调失败，原因是训练目标持续漂移，并非训练技术本身无法使用。更稳的路径是先固定任务定义和评测集，再用一小批高质量样本验证微调是否真的改善目标问题。

RAG 更新也需要发布门禁。新增文档后，旧问题是否仍能答对，新文档是否被正确召回，冲突版本是否被处理，敏感内容是否被过滤，都要检查。知识库不是文件夹，不能只看“上传成功”。尤其是制度、合同和产品手册，文档版本变化会直接改变答案，发布流程必须留下证据。偏好对齐要谨慎使用。让模型更礼貌、更保守或更符合品牌表达是有价值的，但偏好数据也可能压制必要的拒答或改变专业判断。合规、财务和法律类场景里，风格偏好不能覆盖事实和证据。对齐评测要单独检查拒答率、风险提示、证据引用和关键结论是否发生变化。能力定制还有一个容易被忽略的指标：维护成本。微调模型需要重新部署和回归，RAG 需要持续整理知识，Prompt 需要版本管理，偏好数据需要标注。团队选择路线时，应看未来三个月谁来维护，而非只看当前哪种方法看起来最先进。能被持续维护的中等方案，往往比没人维护的复杂方案更可靠。

定制后的能力还要防止局部优化。一个 LoRA adapter 可能提升某个部门的术语表达，却降低通用问答稳定性；一个 RAG 索引可能让新制度可见，却因为重复文档降低召回精度。平台应按租户、任务和知识域控制定制能力的生效范围，避免把局部改动扩散成全局行为。训练数据的负样本同样重要。只收集正确示例，模型会学会输出格式，却不一定学会拒绝越权问题、识别证据不足或处理冲突口径。企业能力定制应把拒答、澄清、转人工和失败恢复样本纳入训练或评测。这样模型学到的范围才能覆盖“怎么答”和“什么时候不该答”。能力定制的复盘要看真实业务后果。分类准确率提升是否减少了人工分派，制度问答引用改善是否减少了客服升级，SQL 生成提升是否缩短了分析周期。若指标只停留在离线分数，团队很难判断定制投入是否值得继续扩大。

9.8 定制资产台账与租户化路由

能力定制进入平台后，要被当作资产管理，而不是散落在训练脚本、Prompt 文件和知识库配置里的临时改动。资产台账至少记录 base model、adapter、Prompt 模板、RAG 快照、训练样本版本、评测集版本、适用租户、适用任务、风险等级、owner、灰度范围和回滚目标。这样一次线上问题才能被定位到具体资产组合。用户投诉“回答不符合新政策”时，团队需要知道当时是否启用了旧 RAG 快照；结构化输出失败时，要知道是否路由到了带客服语气微调的 adapter；安全拒答异常升高时，要知道偏好策略是否刚刚发布。

租户化路由要比“哪个模型效果最好”更具体。不同租户的数据权限、术语、合规要求和成本预算不同，同一个 adapter 不能自动扩散到所有租户。平台可以把能力定制写成路由条件：某个租户的客服工单分类使用 adapter_a，内部制度问答使用 RAG 快照 policy_2026_06，高风险外发内容仍走基础模型加审核策略。路由记录进入 Trace 后，团队才能解释为什么同样的问题在不同租户得到不同处理。若没有这层记录，能力定制会让线上行为变得难以复现。

台账还要支持下线。训练样本过期、业务 owner 离开、评测集长期无人维护、线上收益低于维护成本时，定制资产应进入观察、冻结或下线流程。下线前要确认依赖它的 Agent、Prompt、评测样本和路由规则，并保留一段回滚窗口。能力定制的治理目标，是让每个版本都能说明适用范围、证据来源、运行成本和退出条件。只有这样，模型能力才会随业务演进，而不会沉积成越来越难解释的版本堆。

9.9 能力定制的发布证据与回收边界

模型能力定制上线前，要证明定制确实服务业务任务。微调、LoRA、RAG 增强、Prompt 模板、工具示例和评测样本都可能让模型在某类任务上表现更好，也可能让它在通用任务上退化。发布证据不能只展示几个成功例子，应包含基线对比、失败样本、适用范围、不可用场景、成本变化和回滚方式。

定制能力还要有回收边界。某个业务术语、流程、产品或政策过期后，对应的定制样本可能继续影响模型行为。平台需要记录定制来源、业务 owner、样本有效期、评测覆盖和下线条件。若定制样本来自临时项目，项目结束后应进入复审；若定制模型长期无人使用，应退回通用能力或归档；若定制引发安全或合规问题，应能快速切回基础模型。

能力定制的运营要连接第39章 Eval 和第41章成本治理。定制带来的质量收益、额外推理成本、维护成本和数据标注成本应放在一起看。若收益只体现在少量样本上，可能更适合通过 Prompt 或工具示例解决；若收益稳定覆盖高价值流程，才值得保留专门模型或专门策略。这样定制不会变成模型团队的单点优化，而会进入平台投资判断。

9.10 定制能力的业务复审周期

能力定制上线后，需要固定复审周期。业务术语、政策、产品、客户分层和流程规则都会变化，原本有效的 adapter、Prompt、RAG 快照或偏好策略，可能在几个月后变成误导来源。复审不应等到线上事故出现才启动。平台可以按月或按季度检查定制资产的使用量、失败样本、业务 owner、成本、评测结果和下线条件。

复审材料要区分“能力仍有价值”和“能力仍可维护”。某个定制模型可能仍然提高少数样本分数，但业务 owner 已经离开，训练样本无人维护，评测集不再覆盖新流程，这种能力不适合继续扩大。另一个简单 Prompt 模板可能分数提升有限，却服务稳定高频任务，owner 清晰，回滚容易，就值得保留。能力复审的目标，是让定制资产跟随业务变化更新，而不是把早期项目遗留成长期运行负担。

当复审发现资产退化时，处理方式可以分级：先冻结新流量，再补样本或更新知识库；若仍无法证明收益，就把路由退回基础模型或通用策略。退役记录应保留一段时间，方便解释历史 Trace 中为什么使用过某个定制能力。能力定制进入这个生命周期后，平台才不会被越来越多模型版本、Prompt 版本和知识快照拖慢。

9.11 定制能力的影响评估

能力定制是否值得保留，不能只看离线样本分数。评估应把业务结果、维护成本、运行成本和风险变化放在一起看。一个 LoRA adapter 可能让客服分类准确率提高，但如果它增加了路由复杂度、带来额外推理延迟、需要单独维护回归集，并且只覆盖低频场景，就未必适合进入主链路。相反，一个简单 Prompt 模板可能分数提升有限，却稳定服务高频任务、owner 清晰、回滚成本低，就更适合作为平台能力沉淀。

影响评估要从任务链路出发。业务方提出“让模型更懂业务”时，平台应先定义它要改善的具体行为：减少人工分派、降低政策问答升级、提高结构化字段可用率、减少 DataAgent 查询失败，还是让报告更容易通过复核。每个行为都要有可观测指标和样本来源。若指标不能进入 Trace、Eval 或人工复核记录，后续就无法判断定制是否真的带来价值。定制前后的对比应覆盖成功路径和失败路径，尤其要观察拒答、澄清、引用错误、格式失败和人工接管是否发生变化。

维护成本也要进入决策。微调模型需要样本清洗、训练、部署、回归和安全复核；RAG 定制需要文档解析、索引刷新、冲突处理和检索评测；偏好对齐需要成对样本、标注规范和安全边界检查。若业务 owner 无法长期维护样本和规则，定制能力上线后很快会过期。平台应在发布记录中写明 owner、复审周期、评测集、下线条件和替代路线。没有这些信息，定制能力会变成线上行为差异的来源，而不是能力提升。

定制能力还要评估路由影响。一个平台里可能同时存在基础模型、租户 adapter、任务 Prompt、知识库快照和安全策略。路由规则越复杂，线上复现越困难。影响评估应检查这次定制是否真的需要独立路由，是否可以通过工具示例、知识库更新或 schema 修正解决，是否会影响其他租户或任务。若定制只服务少量用户，应限制生效范围，并在 Trace 中记录命中的原因。这样线上问题发生时，团队能快速判断是基础能力问题，还是某个定制资产带来的局部行为。

退役信号也应提前定义。使用量下降、owner 缺失、评测集失效、维护成本高于收益、与新基础模型能力重叠、线上失败长期无人处理，都说明定制资产需要复审。退役不等于删除历史记录，而是停止新流量、保留历史 Trace 可解释性，并把仍有价值的样本迁入通用评测集。这样能力定制才会形成健康的生命周期：引入时有证据，运行中有观察，收益不足时能收回。

9.12 定制能力的退役与知识回收

能力定制上线后，也要设计退役。某个微调模型、LoRA、RAG 增强包或 Prompt 策略可能在试点阶段有效，但随着基础模型升级、业务规则变化、知识库重构或安全策略调整，它的收益会下降。若这些定制能力长期留在路由中，平台会积累大量难以解释的特殊路径，后续事故复盘也会更复杂。

退役前要先判断定制能力带来的真实收益。平台可以比较启用和关闭定制后的业务样本，观察质量、成本、延迟、人工退回、安全拒答和用户接受情况。若定制能力只改善少数低价值任务，却增加模型维护和评测成本，可以移入观察池；若定制能力依赖过期知识或旧业务规则，应冻结新请求；若基础模型已经覆盖同类能力，应把定制资产逐步回收。

知识回收同样重要。定制能力里沉淀的失败样本、业务术语、领域问答、拒答规则和工具使用模式，不应随模型退役一起丢失。团队可以把有效样本回收到 Eval，把稳定术语回收到 Glossary，把高质量知识片段回收到知识库，把风险样本回收到 Guardrails。这样退役不会浪费试点经验，反而能让平台能力更通用。

早期可以为每个定制能力建立退役条件：连续低调用量、质量优势消失、维护成本过高、知识过期、安全事件或基础模型替代。退役流程记录资产迁移、历史 Run 解释和替代路由。能力定制因此会成为可收可放的工程手段，而不是上线后无人敢动的长期分叉。

9.13 能力定制的版本冻结与客户承诺

能力定制上线后，平台要管理客户承诺。某个租户可能依赖定制 Prompt、专属工具、特定模型路由、私有知识库或业务模板。若平台在未通知的情况下升级基础模型、调整工具 schema 或替换模板，客户看到的行为会变化，却不知道变化来自哪里。能力定制必须有版本冻结和变更通知机制。

冻结不意味着永远不升级。它表示某个客户或业务线当前使用的是一组明确版本：模型、Prompt、工具、知识库、策略和评测样本。平台可以在新版本中修复问题，但要先在客户样本上回放，确认输出结构、口径、权限和成本没有不可接受变化。若变化影响正式承诺，应提供灰度、对比报告和回滚窗口。

定制能力还要避免长期分叉。每个租户都复制一套 Prompt 和工具，会让平台维护成本快速上升。平台应区分可配置参数、可复用模板和真正专属能力。能用配置解决的需求，不应 fork 模板；能沉淀为通用模板的需求，应回到平台资产；只有涉及专有流程、权限或术语的部分才保留专属版本。

早期可以为定制能力建立客户版本卡：当前版本组合、适用范围、承诺指标、样本集、变更窗口、owner 和退役条件。这样能力定制既能满足业务差异，也不会把平台推向不可维护的分支集合。

9.14 能力定制的验收材料

模型能力定制进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把定制目标、训练或配置来源、评测样本、灰度用户、失败样本和撤回条件记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第16章嵌入模型、第39章 Eval 和第44章模型服务相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括定制后只看演示样例、旧能力退化无人发现、灰度人群和生产人群不同。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

能力定制应先证明目标收益，再证明原有能力没有不可接受的退化。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

本章小结

微调、RAG 和对齐解决的问题不同：微调学任务，RAG 接知识，对齐调偏好。动态、敏感、需要引用的事实应优先走 RAG 或工具，不应写进模型参数。LoRA / QLoRA 更适合企业多租户和多任务定制，因为 adapter 易发布、易回滚、易路由。对齐不能替代权限、审计、脱敏、工具白名单和业务规则。能力定制必须以评测和版本治理为中心；缺少样本版本、评测报告、路由策略和回滚目标时，训练越多，系统越难解释和回滚。

参考文献

Hu, E. J. et al. (2022). LoRA: Low-Rank Adaptation of Large Language Models. ICLR.

Hugging Face. (n.d.). PEFT documentation.

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS.

Ouyang, L. et al. (2022). Training Language Models to Follow Instructions with Human Feedback. NeurIPS.

Part III 数据基础设施层

本部分目标

Agent 能否进入企业生产，取决于它拿到的数据是否及时、可信、可追溯。Part III 讨论数据底座从采集、湖仓、OLAP、实时计算到元数据治理的主链路。这里不把数据平台当成背景设施，而把它看作 Agent 平台的事实来源和责任边界。

本部分章节

阅读路径

第10章至第13章解决“数据怎么来、怎么存、怎么查、怎么实时更新”。第14章和第15章再把这条链路收进质量、血缘、契约和指标治理。后续 DataAgent 章节中的 Schema Linking、NL2SQL、报告证据链，都依赖这里建立的数据边界。

第10章 数据采集与集成

数据采集层决定企业 Agent 能看到哪些事实、看到多新的事实，以及这些事实是否还能追溯。DataAgent 回答得准不准，往往不取决于模型，而取决于上游采集到的数据是否新鲜、完整、口径一致。源系统接入、CDC、文件与 API 采集、契约管理和失败恢复，是采集层最容易影响下游可信度的几个位置。运营负责人问“哪些门店今天可能缺货”，DataAgent 查到的却是昨天夜间批处理后的库存。系统回答得很流畅，甚至给出了补货建议，但建议依据已经落后于门店真实销售。排查后发现，源库、采集任务和湖仓表都没有报错，只是库存数据没有按业务需要进入分钟级更新链路。这类问题不能靠换模型解决。采集层要先说明哪些数据被接入、变化如何被识别、失败时是否能隔离和重放，以及数据新鲜度如何暴露给上层 Agent。否则，下游所有分析都可能建立在过期或不完整的事实之上。

数据采集层经常被当成底层工程，只有在 Agent 答错时才被重新看见。业务用户看到的是自然语言答案，平台看到的是模型调用，真正决定答案是否可信的事实却早在源系统接入时就被决定了。库存表是否包含门店调拨、订单状态是否处理取消、文件是否重复导入、API 游标是否丢页，都会在下游表现成“模型分析错了”。企业的数据源通常由不同系统拥有。OMS、WMS、CRM、ERP、SaaS 平台和历史文件的更新节奏、主键语义、删除语义和权限范围都不同。采集层若只追求“抽到数据”，就会把这些差异埋到湖仓表里。等 DataAgent 生成 SQL 时，它只能看到一张看似完整的表，无法知道某些字段来自昨晚批处理，某些字段来自近实时 CDC，某些字段又是供应商每周上传的 Excel。

采集层的工程责任是把源系统变化转换成平台可解释的数据事实。它要记录数据从哪里来、何时到达、如何识别增量、失败后能否重放、schema 变化影响谁、哪些字段包含敏感信息。只有这些控制信息进入数据产品，Agent 才能在回答中说明数据时效，也能在失败时把问题定位回源系统、连接器、落地表或质量门禁。

10.1 数据采集层要解决的业务边界

一家多业务线企业同时经营零售、制造、金融和物流业务。门店订单来自订单管理系统（Order Management System，OMS），库存状态来自仓储管理系统（Warehouse Management System，WMS），客户信息来自客户关系管理系统（Customer Relationship Management，CRM），供应商结算来自企业资源计划系统（Enterprise Resource Planning，ERP），设备质检来自工厂采集平台。DataAgent 要回答“哪些门店正在缺货”“某个供应商延期是否影响毛利”“客户授信变化后还有哪些未履约订单”时，不能直接访问这些生产系统。生产系统面向交易处理，优先保证短事务、权限隔离和稳定性。Agent 平台面向分析、解释、问答和自动化动作，需要可查询、可追溯、可治理的数据副本。因此，数据采集层的职责是把源系统中的业务事实转换成平台可使用的数据产品入口。

这里的关键转变是：源系统中的一条记录，只有在进入平台后带上来源、时间、版本、质量和权限语义，才适合被 Agent 使用。订单库中的 orders.status 只是一个字段；进入数据采集层后，它需要被解释为“订单当前履约状态”，需要说明来自哪个系统、同步到哪个位点、是否包含删除、是否允许 DataAgent 查询。没有这一层转换，Agent 即使查到了数据，也无法判断这份数据是否新鲜、完整和可对外解释。

数据采集层也承担“节奏隔离”的作用。生产系统按业务事务节奏变化，湖仓和语义层按分析节奏组织数据，Agent 按用户问题的节奏发起查询。三者节奏不同，若让 Agent 直接访问生产库，分析查询会影响交易系统，字段变化会直接击穿问答链路，权限规则也会分散到多个入口。采集层把这些节奏隔开，使源系统可以继续稳定处理交易，下游可以围绕统一契约消费数据。

图10-1：数据采集层把源系统和 Agent 平台隔离开。来源：本书自绘。Alt text：左侧是 ERP、CRM、文件、API 等异构源系统，中间是统一采集层，右侧是 Agent 平台数据底座，采集层作为缓冲使源系统变更不直接冲击下游。

图 10-1 的关键是边界，而非工具名称。源系统只向采集层暴露受控接口；湖仓、OLAP、语义层和 DataAgent 只消费采集层沉淀的契约。这样做可以降低四类风险：直接查询源库导致业务抖动；字段含义变化后 Agent 仍按旧口径回答；权限和个人可识别信息（Personally Identifiable Information，PII）绕过治理；数据延迟或质量失败时无法解释。图中同时有两条线：数据流从源系统进入湖仓和分析层，控制流从采集契约把权限、质量、新鲜度和血缘约束传给下游。

10.1.1 从业务事件到可分析数据

数据进入平台前通常有四种形态。表 10-1 先按来源和变化方式拆开它们，后面讨论采集模式时才不会把数据库、事件流、文件和外部 API 混成同一种接入问题。

表10-1：表数据、事件、文件等数据形态的来源、采集关注点与对 Agent 的意义。来源：本书整理。

DataAgent 要判断这份数据能否被可信地使用，仅知道“数据从哪里来”还不够。数据采集层需要把源系统差异收敛为统一的契约：数据源、目标表、同步模式、主键、分区、新鲜度、质量检查、血缘和暴露策略。四种数据形态的差异，主要体现在“变化如何被识别”。表数据通常靠主键、水印、更新时间或数据库日志识别变化；事件数据本身就是变化事实，需要处理重复和乱序；API 数据要服从外部接口的分页、限流和游标规则；文件数据则常靠文件名、分区目录、清单文件和校验和判断是否完整。若忽略这种差异，把所有来源都当作“抽一批数据”处理，平台很容易在删除、补数、重复导入和字段漂移上出错。接入边界可以先拆成三个问题，再选择连接器：平台拿到的是“当前状态”还是“变化过程”；源系统能否提供稳定的身份标识、时间标识和版本标识；下游需要的是可查询的最新状态、可回放的历史过程，还是低频归档数据。不同答案会直接影响目标表模型、质量检查和失败恢复策略。

图10-2：源系统数据形态决定接入边界。来源：本书自绘。Alt text：表数据、事件流、文件、API 四类数据形态分列，各自连向对应的采集方式与关注点（主键水印、乱序、解析、限流），说明形态不同接入边界也不同。

图 10-2 表明，数据形态决定采集边界。表数据需要主键、水印和删除语义；事件数据需要事件时间、事件 ID 和幂等；API 数据需要游标、限流和权限范围；文件数据需要命名、分区和完整性检查。每类来源右侧的控制点决定了数据能否被回放、对账和解释。

10.1.2 批处理、流处理、CDC 与 API 同步的选择模型

采集模式选择不应从工具开始，而应从业务动作开始。一家多业务线企业的月度财务结算只需要稳定、完整、可审计的数据，批处理更合适。门店库存接近售罄时要触发补货提醒，分钟级增量批或变更数据捕获（Change Data Capture，CDC）更合适。支付异常拦截依赖秒级动作，事件流和实时计算更合适。SaaS 营销平台数据通常受 API 限流约束，托管抽取加载转换（Extract Load Transform，ELT）或连接器平台更现实。

一个更可操作的选择方法，是把需求拆成五个维度：新鲜度、完整性、删除语义、回放能力和源系统改造成本。新鲜度决定是天级、小时级、分钟级还是秒级；完整性决定是否需要对账和补数；删除语义决定是否能只追加数据；回放能力决定是否必须保留 changelog；源系统改造成本决定能否要求业务系统主动发事件。只有把这五个维度放在一起，采集模式才不会被“实时”“开源”“托管”等单一标签带偏。例如，门店库存看似需要实时，但若业务只要求每 10 分钟触发一次补货建议，增量批可能比 CDC 更稳定。订单状态看似也可以按更新时间增量抽取，但若涉及取消、退款和状态回滚，CDC 保留的变化顺序会更有价值。营销 SaaS 数据虽然也有“增量”需求，但平台不能控制外部接口的限流和字段变更，因此托管 ELT 或成熟连接器常常比自研脚本更可维护。

表10-2：批同步、流处理、CDC、API 同步四种采集模式的优势、代价与适用场景。来源：本书整理。

图10-3：采集模式选择先看业务动作和新鲜度。来源：本书自绘。Alt text：决策流图从"业务对新鲜度的要求"出发分出秒级、分钟级、小时级、天级分支，分别指向 CDC/流、CDC、批同步等模式，体现按时效需求选模式。

图 10-3 把采集模式选择收敛到两个问题：业务动作需要多快的新鲜度，源系统能否稳定提供主键、游标或事件语义。先回答这两个问题，再选择批同步、增量批、CDC、托管 ELT 或事件流，能避免从工具偏好反推架构。图中的箭头表达的是决策顺序：由业务动作确定新鲜度目标，由源系统能力确定可行路径，再落到工具和目标表设计。

10.1.3 采集模式选择的约束条件

实时并不是越快越好。低延迟会带来常驻计算、状态恢复、消息积压和运维值班成本。若业务动作只要求小时级新鲜度，把链路压到秒级通常是浪费。判断是否需要实时，应看“迟到的数据是否会导致错误动作”。如果只是报表展示，延迟通常可以被标注和解释；如果是支付拦截、库存冻结或风险止付，延迟才会直接变成业务损失。CDC 也不能替代所有批处理。CDC 擅长捕获数据库行级变化，不擅长外部文件、历史回填、低频维表和受限 API。成熟平台通常同时保留批同步、增量批、CDC 和事件流。CDC 解决“变化怎么来”，但历史修复仍需要批量回填和对账能力。一旦源表曾经漏同步、字段曾经写错，仅靠日志订阅无法补回正确结果。连接器工具也不等于数据治理。Debezium、Airbyte、Fivetran、Flink CDC 等工具解决接入问题，不自动解决字段口径、PII 脱敏、质量门禁、血缘、权限和指标一致性。连接器能把数据搬到平台，治理则要回答“谁能用、用哪个版本、失败时谁负责、结果能否解释”。这两个问题不能混为一谈。

10.2 CDC 架构：快照、增量日志、Schema 演化与一致性

CDC 链路通常分成两个阶段。第一阶段是初始快照，把源表已有数据同步到目标端。第二阶段是增量订阅，从数据库事务日志继续读取插入、更新和删除。两个阶段之间必须保存位点，例如 PostgreSQL 的 WAL 日志序列号（Log Sequence Number，LSN）或 MySQL binlog position。理解 CDC 时，应把它看成变化过程的记录机制，不要简单归类为“更快的同步方式”。批同步通常关心某个时间点的最终状态，CDC 关心从一个状态变到另一个状态的过程。这个过程包含插入、更新、删除、事务顺序和源库位点。对 DataAgent 来说，过程信息可以解释“为什么库存从 10 变成 4”“哪一次订单状态回滚导致报表变化”，而非只给出一个最新数字。

CDC 的难点在于快照和增量之间不能出现缝隙。若初始快照还没有结束，源表已经产生新变更，平台必须知道这些变更是否已经被快照覆盖、是否还需要从日志重放。成熟链路会在快照开始、快照结束和增量订阅之间保存一致的 source position，并让 sink 端按照主键和版本做幂等写入。否则一次重启就可能造成漏数或重复。

图10-4：CDC 生命周期从初始快照进入增量订阅。来源：本书自绘。Alt text：时间轴上先是一次性初始快照阶段，随后切换到持续的增量日志订阅阶段，中间标出位点交接点，说明 CDC 从快照平滑过渡到增量。

图 10-4 展示 CDC 的两个阶段：先用初始快照建立全量基线，再从日志位点持续订阅增量变化。两个阶段之间的位点保存，是后续断点恢复、重复消费控制和历史对账的前提。平台需要记录三类信息：快照覆盖了哪些主键范围，增量从哪个日志位点开始，目标表提交到了哪个批次。CDC 的核心挑战有四个。

表10-3：CDC 落地的典型挑战、表现与处理策略。来源：本书整理。

10.2.1 采集契约：把连接器状态转成平台语义

平台不应让湖仓写入器、元数据系统和 DataAgent 分别理解每一种连接器的内部状态。采集层应向下游暴露统一接口契约。契约的作用，是把“工具能做到什么”翻译成“平台承诺什么”。连接器可能记录的是 topic、partition、offset、cursor、job id 或内部 checkpoint；DataAgent 需要知道的是这张表来自哪里、多久更新一次、是否有主键、质量是否通过、是否允许查询。没有契约，下游只能猜测数据状态，出了问题也很难定位责任边界。契约还决定了失败恢复的语言。若契约声明 primary_key，sink 端可以做幂等 merge；若声明 freshness_slo_seconds，观测系统可以判断是否违反新鲜度目标；若声明 quality_checks，编排系统可以在质量失败时阻断暴露给 Agent。采集契约应作为采集链路与治理系统、查询系统之间的机器可读协议，而非项目文档里的附件。

表10-4：采集链路各组件的职责、输入输出与失败模式。来源：本书整理。

接口契约示例：

{
  "pipeline_id": "orders-postgres-to-iceberg",
  "source": {
    "type": "postgres",
    "database": "oms",
    "table": "public.orders"
  },
  "destination": {
    "type": "iceberg",
    "table": "dwd.orders"
  },
  "mode": "cdc",
  "primary_key": ["order_id"],
  "freshness_slo_seconds": 60,
  "expose_to_data_agent": true,
  "quality_checks": [
    "row_count_reconciliation",
    "primary_key_uniqueness",
    "freshness_slo",
    "schema_compatibility"
  ]
}

图10-5：采集契约把工具状态收敛为平台字段。来源：本书自绘。Alt text：左侧多个连接器输出格式各异的原始记录，经过采集契约层映射，右侧收敛为统一的平台标准字段，体现契约层做规范化。

图 10-5 说明采集契约的价值：把连接器内部状态转成平台统一字段，让湖仓写入器、元数据系统和 DataAgent 看到同一套同步模式、主键、新鲜度、质量检查和暴露策略。图中从左到右的转换，表达的是“工具状态”到“平台语义”的转换：源端细节可以不同，但进入平台后的契约字段必须稳定。

这份契约会被三类下游使用。湖仓写入器根据 mode、primary_key 和 quality_checks 决定 append、merge 或回填；元数据系统记录源表、目标表、Schema 版本和新鲜度；DataAgent 在回答时判断数据是否足够新，必要时拒绝基于过期或质量失败的数据回答。

10.2.2 工具生态对比

工具介绍必须服务于架构取舍。Debezium 更适合以 Kafka 为中心的数据库 CDC 事件总线；Airbyte 更适合作为开源连接器平台；Fivetran 更适合希望降低连接器运维的托管 ELT 场景；Flink CDC 更适合 CDC 后立即进入实时转换、路由和多 sink 的链路。选择工具时，读者应把工具放回组织能力中评估。平台团队若已经有 Kafka 和流式运维能力，Debezium 或 Flink CDC 的可控性更高；若团队主要目标是快速接入大量 SaaS，Airbyte 或 Fivetran 的连接器覆盖更重要；若数据涉及敏感字段和复杂内网权限，托管服务的合规边界就必须被提前评估。工具没有绝对优劣，只有与链路职责和团队能力是否匹配。

表10-5：Debezium、Flink CDC 等采集工具的适用与不适用场景。来源：本书整理。

图10-6：连接器工具应按组织能力和链路职责选择。来源：本书自绘。Alt text：二维矩阵以"组织工程能力"和"链路关键程度"为轴，把 Debezium、Flink CDC、SaaS 连接器、自建连接器分别落入不同象限，给出选型指引。

图 10-6 对比了四类连接器工具的边界。Debezium 更像数据库日志事件源，Airbyte 更像自建连接器平台，Fivetran 更像托管 ELT 服务，Flink CDC 更适合把 CDC 与实时计算放在同一条链路中。图中的“工具职责”应与前文契约字段一起理解：无论底层选择哪个工具，进入平台后都要产出同样的 source、destination、mode、freshness 和 quality 信息。

10.2.3 面向 DataAgent 的新鲜度、延迟、成本与可靠性边界

DataAgent 的新鲜度需求容易被误解为“越实时越智能”。实际情况是，Agent 更需要“知道自己基于什么时间点的数据回答”。如果平台能明确告诉 Agent 数据截至 10 分钟前，Agent 可以在回答中说明限制；如果平台给出秒级链路但经常重复、乱序或质量失败，Agent 反而更容易生成看似精确但不可追责的结论。这里的决策不能停留在“慢”和“快”的二选一上，还要同时比较业务价值、恢复复杂度和解释能力。关键事实表可以承受更高链路成本，低频维表不适合强行实时化；敏感数据优先选择可控链路，低敏外部数据可以用托管连接器加速接入。

批同步与 CDC

表10-6：批同步与 CDC 在新鲜度、成本、可靠性上的取舍。来源：本书整理。

自建连接器与托管 ELT

表10-7：采购连接器与自建连接器的取舍。来源：本书整理。

图10-7：数据采集技术取舍同时看新鲜度、成本和恢复。来源：本书自绘。Alt text：以新鲜度、成本、恢复难度为三轴的雷达图，批同步、CDC、流处理三种方案各画一条曲线，直观对比它们在三个维度上的强弱。

图 10-7 强调采集技术取舍要同时看延迟、新鲜度、成本、故障恢复、审计能力和组织运维能力。否则，低延迟链路可能变成高成本且难恢复的生产负担。每条链路都要接受同一个问题检验：如果今天凌晨失败，明天上午能否解释影响范围并补回正确数据。

10.2.4 采集链路的断点与补数策略

表10-8：重复、乱序、字段漂移等采集失败模式的检测与恢复策略。来源：本书整理。

这些失败模式有一个共同点：它们通常不会在链路刚上线时暴露，而是在重启、回填、字段变更和流量高峰时出现。平台除了监控“任务是否成功”，还要监控“产出的数据是否仍然可信”。例如，同步任务成功结束但主键重复，DataAgent 统计会偏高；CDC 仍在运行但日志位点落后，回答会滞后；Schema 自动兼容新增字段但语义没有登记，Agent 可能误用字段。

图10-8：采集失败恢复要同时保留 changelog 和 current 表。来源：本书自绘。Alt text：图中并列两张表，记录每次变更的 changelog 表和保存最新状态的 current 表，箭头表示故障时可用 changelog 重放重建 current 表，说明两者须并存。

图 10-8 表示一个实用原则：同一条采集链路应同时保留 append-only 的变更日志表和面向查询的 current 表。变更日志表用于审计、回放和故障修复；current 表用于 DataAgent 查询最新业务状态。只保留 current 表会降低追溯能力，只保留 changelog 表会把查询复杂度转嫁给下游。图中两张表分别服务“解释过去”和“查询现在”两个目标。

10.3 采集配置、落地表与最小可运行链路

本章的 mini-platform 实现不连接真实数据库或 Kafka，而是把采集模式选择和 DataAgent 可读契约固化为可测试代码。这样做的原因是：企业平台在接入真实工具前，必须先统一“什么样的数据可以暴露给 Agent”这一层语义。这段实现刻意从规则模型开始，而非从连接器客户端开始。真实连接器会引入网络、权限、数据库版本和运行环境差异，容易让初学者把注意力放在工具参数上。mini-platform 先把“源类型、新鲜度、主键、水印、暴露策略”建模清楚，使读者看到平台的最小流程：需求输入、模式选择、契约输出、测试验证。

• 入口：mini-platform/infra/ingestion/__init__.py
• 核心实现：mini-platform/infra/ingestion/pipeline_contract.py
• 测试：mini-platform/tests/test_ingestion_pipeline_contract.py
• 实战项目：mini-platform/projects/10-ingestion-pipeline/run.py

图10-9：mini-platform 用规则模型生成采集契约。来源：本书自绘。Alt text：流程图显示源 schema 经规则模型分析后自动生成采集契约（字段、类型、水印、主键），再下发给连接器，体现契约的半自动生成。

图 10-9 对应本章 mini-platform 的最小流程：输入源系统类型、新鲜度、主键和目标表信息，规则模型选择采集模式与工具，再生成 DataAgent 可读的数据采集契约。这个流程保留的是接入决策骨架，真实生产还需要补充权限、血缘、质量门禁和失败恢复。mini-platform/infra/ingestion/pipeline_contract.py：

class SourceKind(str, Enum):
    DATABASE = "database"
    SAAS_API = "saas_api"
    FILE = "file"
    EVENT_STREAM = "event_stream"

class IngestionMode(str, Enum):
    BATCH = "batch"
    INCREMENTAL_BATCH = "incremental_batch"
    CDC = "cdc"
    MANAGED_ELT = "managed_elt"
    EVENT_STREAM = "event_stream"

同一文件中的 plan_ingestion_pipeline 会根据源类型、新鲜度、主键和水印做第一轮模式选择。下面只截取核心分支，目的是让读者先看清模式分流逻辑，而非陷在实现细节里。

def plan_ingestion_pipeline(request: dict[str, Any]) -> PipelineDecision:
    source_kind = SourceKind(request["source_kind"])
    freshness = int(request.get("freshness_slo_seconds", 86_400))
    has_primary_key = bool(request.get("has_primary_key", False))

    if source_kind is SourceKind.DATABASE and freshness <= 300 and has_primary_key:
        return PipelineDecision(
            mode=IngestionMode.CDC,
            tool="Debezium",
            reason="数据库关键事实表需要分钟级新鲜度，且具备稳定主键。",
            freshness_slo_seconds=freshness,
            requires_primary_key=True,
            requires_watermark=False,
        )

build_pipeline_contract 把规则决策转换为下游可消费的契约：

def build_pipeline_contract(request: dict[str, Any]) -> PipelineContract:
    decision = plan_ingestion_pipeline(request)
    primary_key = tuple(request.get("primary_key", ()))
    quality_checks = (
        "row_count_reconciliation",
        "primary_key_uniqueness" if primary_key else "source_file_completeness",
        "freshness_slo",
        "schema_compatibility",
    )

    return PipelineContract(
        pipeline_id=request["pipeline_id"],
        source=request["source"],
        destination=request["destination"],
        mode=decision.mode,
        primary_key=primary_key,
        freshness_slo_seconds=decision.freshness_slo_seconds,
        expose_to_data_agent=bool(request.get("expose_to_data_agent", False)),
        quality_checks=quality_checks,
    )

运行测试：

cd enterprise_agent_platform_book/mini-platform
python3 -m pytest tests/test_ingestion_pipeline_contract.py -q

运行项目：

cd enterprise_agent_platform_book/mini-platform/projects/10-ingestion-pipeline
PYTHONPATH=../.. python3 run.py

预期输出：

orders-postgres-to-iceberg -> cdc
tool=Debezium freshness=60s
checks=row_count_reconciliation,primary_key_uniqueness,freshness_slo,schema_compatibility

这段输出对应图 10-9 的最小流程：输入是一家多业务线企业订单表采集需求，规则选择 CDC 和 Debezium，输出是 DataAgent 可读的数据契约。真实生产系统还需要把这份契约写入第15章的元数据系统，并把运行状态、血缘、质量检查和告警接入第14章的编排与质量平台。

10.3.1 数据采集进入 Agent 链路的准入标准

数据采集一旦进入 Agent 链路，就会影响回答口径、权限判断和后续审计。上线评审应先看四类证据。第一类是访问证据。CDC 用户、API token 和文件读取账号只授予必要范围；所有凭证进入 secret 管理，不写入仓库、配置样例或日志；同步表使用 allowlist，避免默认同步全库；敏感字段进入湖仓或语义层前完成标注、脱敏或策略过滤。第二类是恢复证据。offset、LSN、binlog position 和 API cursor 要持久化并可审计；源库日志保留时间要大于最大恢复窗口；大表初始快照应采用限流、分片和低峰窗口；新增字段、删除字段和类型变更都有兼容性规则。

第三类是质量证据。sink 端要处理重复事件，历史回填写入 staging 后按版本原子合并；关键表定义 freshness SLO，并暴露给 DataAgent；行数、主键唯一性、非空、枚举值和 Schema 兼容性检查自动运行。第四类是运营证据。平台记录 source、connector、destination、schema version 和运行时间；延迟、错误率、积压、同步失败和日志空间占用都进入告警。缺少这些证据时，Agent 可以试用这批数据，但不应把它用于对外结论。

10.3.2 采集延迟、重复和补数的恢复策略

日志保留不足导致 Connector 无法恢复

• 现象：周末 CDC Connector 停止两天，周一恢复时找不到原 binlog/WAL 位点。
• 根因：源库日志保留时间小于停止时间，offset 指向的日志已经被清理。
• 修复：增加日志保留，监控停止时长和复制槽积压；恢复时重新快照受影响表，并通过 changelog 与 current 表对账。

全量快照拖慢源库

• 现象：首次同步订单明细表时，业务系统查询延迟明显升高。
• 根因：快照扫描大表，占用源库 I/O 和锁资源。
• 修复：改为只读副本执行快照，降低并发，按主键范围分片，把首次同步安排在低峰期。

源表缺少主键导致 upsert 目标表持续重复

• 现象：目标湖仓表中同一业务记录出现多行，DataAgent 统计订单数偏高。
• 根因：源表没有稳定主键，sink writer 无法判断重复事件。
• 修复：与业务方确认业务唯一键；无法确认时写入 changelog 表，并在下游建模层通过窗口函数取最新版本。

回填任务覆盖实时增量

• 现象：修复历史订单时，实时订单状态被旧数据覆盖。
• 根因：回填任务和 CDC sink 同时写 current 表，没有版本比较。
• 修复：回填写入 staging 表，根据源系统更新时间和 source position 做合并，合并期间暂停相关分区或使用冲突检测。

10.3.3 采集契约与 DataAgent 证据链

数据采集层不是 DataAgent 的后台细节。用户看到的每个指标、每份报告和每次异常归因，都依赖采集链路提供稳定事实。采集契约因此要进入回答证据链：源系统、同步模式、最后成功同步时间、质量状态、schema 版本和回填状态，都应能被语义层和 Trace 查询到。用户不需要看到连接器配置，但平台需要知道回答使用的是哪一次同步后的数据。采集契约还要处理“数据可用但不适合回答”的情况。某张表刚完成快照但增量还没有追平，某个 API 同步成功但缺少关键字段，某次回填正在重算历史分区，这些状态都不能简单标为 available。DataAgent 可以在低风险探索中使用这类数据，但不应在正式报告里给出确定结论。比较稳妥的做法是把资产状态分成可查询、可观察、阻断和废弃，回答层据此决定继续、降级、澄清或拒答。

采集层的运营也要回流到第14章的数据质量和第15章元数据系统。连接器延迟升高、重复事件增多、schema 变更频繁，都会影响 Agent 可信度。若这些信号只停留在数据工程告警里，业务用户看到的只是“Agent 回答不稳定”。把采集状态接入 Trace 后，平台才能解释一次错误回答到底来自模型、语义层、查询执行，还是源数据尚未稳定。

采集链路上线后，最重要的指标是新鲜度、完整性和可恢复性，任务成功次数只能说明调度器按时触发。一个任务每天都成功运行，却持续晚到两小时，对经营监控仍然是失败；一个 CDC 任务没有报错，但删除事件没有同步，会让库存和订单口径长期偏高。平台团队还要给采集失败设计隔离区。源系统字段漂移、文件校验失败、API 限流和日志位点异常，都不应直接污染下游生产表。失败数据进入隔离区后，数据负责人可以决定补数、跳过、回滚或暂停下游任务。这个流程越清楚，DataAgent 的回答越能被业务信任。对 Agent 平台而言，采集层的交付物包括连接器配置、数据契约、位点记录、质量检查、血缘和告警规则。它们看起来不像模型能力，却决定模型能否基于正确事实工作。没有这层，后续语义层、NL2SQL 和评测都会在错误数据上继续优化。

采集层还要处理“看似成功”的失败。任务按时结束，但源系统当天没有产生文件；API 返回 200，但分页游标少取了一页；CDC 位点继续推进，但某类删除事件被过滤；文件校验通过，但供应商把金额单位从元改成万元。这类问题不会自动变成红色告警，只有把业务规则写进契约和质量检查，平台才能提前发现。数据新鲜度应对上层可见。DataAgent 查询库存、价格、风控状态或客服工单时，需要知道数据截至哪个时间点。如果数据延迟超过业务容忍范围，系统应该提示用户，或者拒绝生成强结论。把新鲜度藏在数据平台后台，会让模型用过期事实生成非常流畅的错误答案。采集变更也要有发布流程。新增源表、修改增量字段、切换连接器、调整分区策略，都可能影响下游语义层和评测集。数据团队应在变更前说明影响对象，平台团队应在变更后跑关键问数样本。若采集变更和 Agent 发布互相独立，问题往往会在用户追问时才暴露。

跨系统对账是采集层的另一个责任。订单、支付、库存和结算通常来自不同系统，单表质量通过并不代表整体一致。Agent 做归因分析时，会把这些来源放在一起解释；如果对账没有完成，模型可能把系统间延迟解释成业务异常。对账状态进入元数据后，Agent 才能知道哪些结论需要谨慎。采集层越早把状态暴露出来，后面的模型越少背锅。很多所谓“模型幻觉”，其实是平台没有告诉模型数据已经延迟、缺失、重复或口径变化。数据事实不可靠时，最好的模型也只能给出不可靠分析。源系统接入前要做数据合同访谈。业务系统负责人需要说明主键是否稳定、删除如何表达、更新时间是否可信、字段枚举是否会变、历史数据是否会被回写。数据平台如果只拿到连接串和表名，很难判断这些语义。访谈结果应写进采集契约，后续 Agent 使用这些数据时才能解释来源和限制。

批处理、CDC 和 API 同步还会带来不同的事故形态。批处理常见问题是分区缺失、重复导入和补数覆盖；CDC 常见问题是位点丢失、schema 演化和乱序；API 同步常见问题是限流、分页游标和供应商字段变化。平台要为每种形态准备对应的监控，而非只看任务是否成功。采集层还要服务成本控制。全量抽取简单但昂贵，CDC 精细但运维复杂，API 同步受外部限制，文件接入依赖供应商纪律。选择采集方式时，要把业务新鲜度、源系统改造成本、数据量和恢复能力放在一起看。为了追求实时而引入复杂 CDC，如果业务每天只看一次报表，维护成本就可能超过收益。数据源权限也要前置。源系统允许数据平台读取，不代表 Agent 可以直接使用所有字段。采集层应在落地时标记敏感字段、租户字段、授权范围和脱敏要求。后续语义层和查询执行器根据这些标记控制访问，避免把权限问题留给模型临时判断。

采集链路的文档应能被事故复盘使用。某张表来自哪个源库，增量位点在哪里，最近一次 schema 变化是什么，质量检查是否通过，失败后补数范围是多少，这些信息在平时看起来琐碎，事故时却决定排障速度。把这些材料结构化保存，Agent 平台才能在数据问题出现时快速收敛。采集层还要给历史回填留通道。新接入一个源系统时，平台通常需要同时同步未来增量，也要回填历史数据。历史回填会影响分区、质量检查、血缘和下游缓存，如果处理不好，Agent 会在同一问题上看到不完整时间段。回填计划应说明范围、顺序、校验方式和对下游问数的影响。源系统压力也是采集设计的一部分。直接大批量抽取生产库，可能影响交易系统；API 拉取频率过高，可能触发供应商限流。采集层需要用副本库、只读账号、限速、分批和低峰窗口保护源系统。Agent 平台要获取数据，但不能为了问答能力破坏业务系统稳定性。

采集配置还要接受审计。谁新增了数据源，谁调整了字段映射，谁关闭了质量规则，谁执行了补数，都应有记录。数据一旦被 Agent 用于业务解释，这些配置变化就成为回答依据的一部分。没有审计，数据错误很难追溯到具体变更。采集负责人还应定期抽查下游问数样本。数据能被抽取，不代表适合被 Agent 使用；抽查能发现字段含义、时效和权限在进入分析链路后的真实表现。

10.4 采集变更的回放与下游影响评估

采集链路变更要能回放。新增连接器、切换 CDC 工具、调整主键、修改删除语义、改变时间字段或重跑历史分区，都可能影响下游语义层、指标表、向量索引和 DataAgent 样本。若数据团队只验证目标表有数据，平台团队只验证 Agent 能回答，两个检查之间仍可能漏掉口径变化。回放应选取一组代表性业务问题，覆盖高频指标、历史回溯、删除事件、权限字段、跨表 join 和回填分区。变更前后要比较数据行数、主键分布、更新时间、删除记录、质量规则、核心 SQL 结果和最终回答。

下游影响评估要提前写入变更单。一个源表新增字段，看起来对现有查询无影响，但可能改变 schema 推断、语义层候选字段和模型选择；一个回填任务只修复历史数据，却可能让历史报告里的趋势图发生变化；一个 API 分页修复会补回漏掉的客户记录，也可能让此前的经营结论需要重新解释。采集层要把这些影响通知元数据、质量、语义层、评测和报告层。对高风险数据域，变更完成后应自动触发关键样本回放，并把结果写入 Trace 或发布记录。

回放结果还要决定发布动作。若差异在预期范围内，可以继续发布并更新数据新鲜度；若差异来自补数或字段修正，要标记受影响的指标和报告；若差异来自意外重复、丢失或权限字段异常，应暂停下游使用并进入数据修复。平台不应把所有采集变更都推给用户自行判断。DataAgent 的回答依赖数据事实，数据事实发生变化时，系统要能说明哪些结论仍可使用，哪些需要复核，哪些应撤回。

早期可以先建立轻量回放机制。每个核心数据域保留十到二十个问数样本，样本绑定源表、指标、权限和预期解释。采集变更后，平台跑这些样本，生成差异摘要。这个机制不会覆盖所有数据质量问题，但能让采集层和 Agent 层形成闭合的验收路径。随着生产事故积累，样本库再逐步增加删除、回填、schema 演化和跨系统对账场景。

10.5 采集延迟的用户可见边界

数据采集延迟会直接影响 Agent 的回答可信度。CDC 任务积压、上游接口限流、批量文件晚到、Schema 演化等待确认、回填任务占用资源，都可能让 DataAgent 看到的数据落后于业务事实。传统数据平台可以把这些问题显示在调度和监控系统里，Agent 场景还需要把延迟翻译成用户能理解的回答边界。

用户可见边界应说明数据截止时间、延迟原因、影响范围和可用替代。若最新订单数据延迟，系统可以返回上一版数据并标明截止时间；若某个区域数据缺失，系统应限制结论范围；若回填正在进行，系统应避免生成确定趋势；若采集失败影响高风险报告，应暂停发布并通知 owner。用户不需要看到 Kafka offset 或 connector 日志，但需要知道当前答案是否适合决策。

采集延迟还要进入 Trace。每次 DataAgent 使用延迟数据回答时，Trace 应记录采集任务、数据版本、延迟窗口、质量状态和用户提示。这样后续复盘能够判断系统是否正确告知用户，也能把数据采集问题和问数争议关联起来。若没有这条链路，业务方会把延迟造成的差异归因给模型或语义层。

早期可以给核心数据源建立延迟分级。轻微延迟允许同步回答并提示截止时间，中等延迟转入异步报告或要求用户确认，高风险延迟直接拒答或转人工。采集层因此承担两类职责：把数据搬进平台，并把数据可用性传递给 Agent。

10.6 接入延迟的业务沟通

数据接入的延迟经常被技术团队当作管道指标处理，业务用户看到的却是任务是否可信。一个销售明细源延迟十分钟，可能只影响实时看板；一个订单状态源延迟十分钟，可能让 Agent 给出错误的履约建议；一个权限标签源延迟十分钟，则可能造成越权风险。平台需要把延迟从“数据管道状态”翻译成“当前回答能否使用”的业务状态。

延迟沟通要发生在 Agent 回答之前。若数据源未完成同步，系统应在上下文包里带上数据新鲜度、最后同步时间、缺失分区和影响范围。对于低风险查询，可以展示结果并标注数据时间；对于高风险建议，应拒绝给出确定结论或转人工确认。这样用户知道自己看到的是哪一个时间点的数据，不会把过期结果当成当前事实。

接入团队还要记录延迟根因。源系统不可用、增量字段缺失、CDC 堆积、权限重算失败、质量校验拦截，都需要不同 owner 处理。若所有延迟都只显示为 pipeline late，DataAgent 无法判断是等待、降级还是拒答。早期可以为每个数据源维护延迟状态、业务影响、允许降级方式和通知对象，让数据接入真正服务上层 Agent 的任务判断。

10.7 数据源接入的责任台账

数据源接入进入生产后，平台需要把 source owner、SLA、主键、增量字段、脱敏规则、质量样本、下游消费者和停止条件放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。

这类证据应和第11章数据接入、第14章质量治理和第33章语义层连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。

常见风险包括数据源上线后 owner 消失、字段含义随业务系统变化、下游 Agent 继续使用已废弃字段。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。

数据源进入平台前应完成责任台账，后续变更才有明确通知和复审路径。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。

落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。

本章小结

数据采集层是企业 Agent 平台的数据入口，直接影响 DataAgent 的新鲜度、可信度和可审计性。批同步、增量批、CDC、托管 ELT 和事件流各有边界，一个工具无法覆盖所有来源。采集链路必须暴露统一契约，包括源、目标、模式、主键、新鲜度、质量检查和 Agent 暴露策略。生产级 CDC 的难点集中在快照、位点、Schema 演化、删除语义、幂等写入和回填恢复。mini-platform 的最小实现先固化规则和契约，真实连接器应在这个契约之后接入。

参考文献

Debezium. (n.d.). Documentation.

Airbyte. (n.d.). Documentation.

Apache Flink. (n.d.). Flink CDC documentation.

Apache Kafka. (n.d.). Documentation.

第11章 数据湖与湖仓

财务团队复盘上周的一次经营分析，发现同一个问题在本周重新运行后得到不同结果。SQL 没变，模型版本也没变，差异来自底层明细表被补数覆盖：系统只能看到“当前文件目录”，却说不清上周回答时读到的是哪一批数据。Agent 平台要支持回放和审计，底层数据就不能只是对象存储上的一堆文件。湖仓需要提供事务、快照、Schema 演化和时间旅行，让一次回答能够绑定到明确的数据版本，也让后续补数、回滚和口径修正有可追踪的边界。

真实项目里的问题往往更细。运营同学问“上周华东区域退款率为什么升高”，DataAgent 先查订单表，再查售后表，最后追到客服工单。三张表来自不同链路：订单每天批量补数，售后用 CDC 几分钟写入一次，工单由 SaaS API 拉取。若底层只是按日期目录堆放 Parquet 文件，平台很难保证三次查询读到的是同一个业务时间点，也很难在事故复盘时说明“当时到底读了哪些文件”。当用户把答案截图发到周会里，这种不确定性就会变成责任问题：分析师怀疑 Agent 编错 SQL，数据团队怀疑补数任务覆盖了旧分区，业务团队只看到两个互相冲突的数字。

湖仓的价值就在这种追责场景里显出来。对象存储负责把数据低成本保存下来，开放表格式负责把一批文件声明为一次可见提交，Catalog 负责让不同引擎找到同一张表并执行同一套权限规则。一次回答如果记录了 snapshot_id、Schema 版本和查询引擎，后续复查就能回到同一份数据视图；如果补数产生了新快照，旧答案也不会因为目录文件被替换而失去依据。对 DataAgent 来说，湖仓是把可变数据变成可引用证据的工程层，成本只是价值的一部分。

这也解释了为什么很多团队从数据湖走向湖仓。早期数据湖通常先解决“放得下”：日志、明细、图片解析结果、外部 API 返回都能进对象存储。随着 Agent 开始直接读取这些数据，问题转向“读得准”和“查得回”。同一个表名在 Spark、Trino、Doris 外表和 Notebook 中指向不同目录，会让权限和口径失控；小文件长期堆积，会让一次看似简单的分析扫描成千上万个对象；字段新增后没有 Schema 演化记录，Agent 生成的 SQL 可能在一部分分区上成功、在另一部分分区上失败。本章讨论的开放表格式、Catalog、事务提交和文件布局，都是为了让这些问题有明确的工程抓手。

11.1 Agent 平台的数据底座需要可追溯、可回放

第10章 解决“数据如何进入平台”，本章解决“数据进入后如何可靠保存”。一家多业务线企业的 DataAgent 不只回答当前库存和订单状态，还要解释“这个答案来自哪些数据”“能否复现上周同一问题的结果”“某个字段变更是否影响了历史回答”。若底层只有一堆文件，Agent 的回答会缺少可审计依据。数据湖提供低成本、开放格式和多类型数据存储，适合保存原始文件、日志、明细和历史归档。数据仓库提供事务、建模、权限、查询优化和稳定口径，适合服务报表和分析。湖仓架构的目标是把二者结合起来：用对象存储或分布式文件系统承载大规模数据，用开放表格式管理事务、快照、Schema、分区和版本，让多个计算引擎在同一份数据之上协作。

对初学者来说，最容易混淆的是“存了很多文件”和“拥有一张表”之间的区别。文件只回答“字节在哪里”，表还要回答“这些文件共同表示什么数据版本”。当一次订单同步生成 100 个 Parquet 文件时，如果没有表格式，查询引擎只能看到目录中的文件列表，很难知道哪些文件属于同一次提交、哪些文件已经被删除、哪个 Schema 是当前有效版本。Agent 的回答需要可解释来源，因此它需要表语义，不需要一堆孤立文件。湖仓还解决一个长期演进问题。企业数据不会一次设计完：字段会新增，分区策略会调整，写入引擎会更换，查询引擎也会扩展。若数据只绑定在某个数据库或某套引擎内部，后续迁移和复用成本会很高。开放表格式把表的事务、快照和文件清单放在引擎之外，使数据资产可以被多个引擎共享，同时保留治理和审计边界。

在 Agent 平台里，这种共享还涉及上线方式。开发阶段可能用 DuckDB 或 Spark 跑样例，生产查询通过 Trino 或 Doris 提供低延迟接口，离线修复任务又回到 Spark/Flink。若每个引擎各自维护一份表定义，语义层就要处理多套字段、权限和分区规则，排障时也很难判断问题来自 Agent、SQL 生成、执行引擎还是数据版本。湖仓把表语义前移到独立元数据层后，平台可以要求所有查询都先解析到同一张受管表，再记录快照和授权结果。这个约束会增加接入成本，却能换来跨引擎一致性和事故复盘能力。

图11-1：湖仓把低成本存储和可治理表语义放在同一底座。来源：本书自绘。Alt text：底层是对象存储提供的低成本文件，上层叠加开放表格式提供的事务与 schema 语义，两层合为同一底座，左侧标注成本优势、右侧标注治理能力。

图 11-1 的重点是“表语义”。对象存储只知道文件，无法天然表达“这批文件属于同一次事务提交”“当前表版本是什么”“某个字段从何时开始出现”“查询应该读哪个快照”。开放表格式把这些信息放进元数据层，使湖上的数据具备接近仓库表的管理能力。对象存储是低成本物理底座，表格式则是让这些文件具备事务、版本和治理含义的控制层。

11.1.1 从数据湖到湖仓：对象存储、开放表格式与计算引擎解耦

湖仓不是把所有数据倒进对象存储后直接查询。它至少包含四层边界。这四层边界的价值，在于把“谁负责什么”说清楚。存储层负责持久化文件，不负责判断当前表版本；表格式层负责描述哪些文件属于哪个快照，不负责所有权限和业务目录；Catalog 层负责发现、命名、权限入口和元数据位置，不负责执行查询；计算层负责读写和计算，不应该把数据资产锁在自己的私有目录结构里。边界越清楚，多引擎协作时越不容易出现同名表、旧 Schema 和权限漂移。

表11-1：存储层、表格式层、计算引擎层的职责与边界。来源：本书整理。

图11-2：存储、表格式、Catalog 与计算引擎解耦。来源：本书自绘。Alt text：四个可独立替换的方块，对象存储、开放表格式、Catalog、计算引擎，用接口线相连，表示任一层可独立升级而不影响其他层。

图 11-2 展示湖仓的四层边界：存储层保存文件，表格式层定义事务和快照，Catalog 层负责发现和治理，计算层执行查询和写入。边界清晰后，数据资产才不会被单一引擎绑定。自下而上是物理文件逐步变成可治理表资产的过程，自上而下是查询引擎把用户请求解析成文件扫描的过程。

解耦让数据资产摆脱单一计算引擎的绑定。同一张订单 Iceberg 表可以被 Spark 写入，被 Trino 探索，被 StarRocks 加速，被 DataAgent 通过语义层查询。治理控制点也会更清晰：权限、血缘、审计和生命周期可以围绕 Catalog 和表契约管理，不必散落在每个引擎的私有配置里。

11.1.2 湖仓核心能力

企业 Agent 平台尤其依赖六类湖仓能力。这些能力不是并列的功能清单，更像一条可信回答链。ACID 保证 Agent 不会读到半提交结果；快照让一次回答固定在某个版本；时间旅行让历史回答可以被复查；Schema 演化让字段变化有可追踪记录；分区演化让数据增长后仍能调整布局；Compaction 则让频繁写入不会长期拖垮查询。缺少任何一环，Agent 都可能在“答得出来”和“答得可信”之间出现断层。

表11-2：ACID、时间旅行等湖仓核心能力对 DataAgent 的价值。来源：本书整理。

图11-3：湖仓核心能力服务可复现回答。来源：本书自绘。Alt text：ACID 提交、快照、时间旅行三项能力指向同一目标"同一查询在同一快照上结果可复现"，说明这些能力共同支撑 Agent 回答可复查。

图 11-3 把湖仓能力和 Agent 回答可靠性连接起来。ACID、快照、时间旅行、Schema 演化、分区演化和 Compaction 都会影响回答质量。它们共同决定一个答案能否复现、能否解释、能否在字段变化后继续可信。图中的每个能力都应对应到一个用户追问：数据是否完整提交、当时读的是哪个版本、字段变化是否影响结论、查询成本为什么突然升高。

11.1.3 湖仓治理要守住的三条线

常见失效条件之一，是把对象存储等同于湖仓。对象存储保存文件，但不提供表事务、快照隔离和 Schema 演化。没有表格式和 Catalog，湖仓会退化成难治理的文件堆。判断一个系统是否具备湖仓语义，不应只看它是否使用对象存储，还要看它能否回答当前快照、历史版本、字段演化、权限和清理策略。另一个误判，是以为开放表格式能自动带来高性能查询。表格式提供元数据和事务语义，查询性能还依赖第12章中的引擎、统计信息、分区、文件大小、排序和缓存。表格式能告诉引擎哪些文件可能相关，但不能替代合理的数据布局和执行计划。表格式也不应只为一个工具而选。湖仓底座应优先服务长期数据资产开放性和治理，不能迁就某个短期计算引擎的默认格式。若组织已经明确绑定某一平台，也要评估导出、跨引擎读取和历史迁移成本。表格式选择一旦落到核心数据资产上，后续迁移会牵动采集、调度、权限、指标和 Agent 语义层。

11.2 开放表格式对比：Iceberg、Hudi、Delta Lake 与 Paimon

开放表格式的选型要看写入模式、查询引擎、流批一体、社区生态和组织已有平台。以下对比强调企业落地场景，不罗列功能。选型时应先判断表的主要写入形态。若大多数表是批量写入、跨引擎读取和长期归档，Iceberg 的快照、分区演化和多引擎生态会更自然。若主要场景是 CDC 入湖、频繁 upsert 和增量消费，Hudi 或 Paimon 的更新链路更值得评估。若组织已经深度采用 Spark 或 Databricks，Delta Lake 的平台集成会降低工程成本。表格式不是孤立选择，它会影响采集 sink、Catalog、Compaction、读写引擎和治理工具。

选型还要看团队能否稳定运维表服务。高频 upsert 表如果没有清理、合并和失败重试策略，很快会被小文件、删除标记和冲突提交拖垮；偏批处理的明细表如果过早引入复杂更新模型，也会让简单链路背上不必要的运维负担。DataAgent 面向的是长期可复用数据资产，表格式的“功能更强”不等于“更适合”。一个保守但可解释的选择，通常比一套功能齐全却无人能排障的链路更适合进入生产问答。

湖仓选型还要考虑数据团队已有习惯。若历史作业主要用 Spark，Delta 或 Iceberg 的接入成本不同；若实时链路重度依赖 Flink，Paimon 或 Hudi 的运维经验会影响落地；若查询服务主要由 Trino、Doris 或 StarRocks 承接，Catalog 和外表兼容性就会成为关键。表格式选择不能只由平台团队拍板，它会影响采集、调度、查询、权限、审计和故障恢复。对 Agent 平台来说，最重要的是把选择结果转成使用契约。哪些表允许时间旅行，哪些表只能读当前快照，哪些表有主键和删除语义，哪些表还缺少数据质量保证，都要进入元数据和语义层。这样 Agent 生成查询时，知道哪些表适合自动分析，哪些表需要提示用户确认或转人工复核。

这份使用契约也要进入审计日志。一次 DataAgent 回答不只记录 SQL，还要记录表格式、快照、Catalog、数据新鲜度、权限判定和质量状态。若后续业务方发现结果异常，团队可以沿着这些字段判断是补数改变了快照、Catalog 指向了旧元数据、还是某张表当时就没有通过质量门禁。湖仓因此承担了比存储更重的责任。它要让数据变便宜，也要让数据变得可被引用、可被回滚、可被解释。对企业 Agent 平台来说，后者往往更关键，因为一次错误回答的成本，还涉及重新跑一条 SQL，还包括业务信任和合规责任。这也是湖仓成为 DataAgent 默认底座的原因：它让数据版本、访问权限和回答证据可以落到同一套表资产上。有了这套表资产，Agent 的回答才有可以复查的地基。

表11-3：Iceberg、Hudi、Delta Lake 三种开放表格式的优势、代价与适用场景。来源：本书整理。

图11-4：开放表格式选择取决于写入模式和引擎生态。来源：本书自绘。Alt text：二维矩阵以"写入模式（append/upsert/流式）"和"引擎生态广度"为轴，把 Iceberg、Delta、Hudi 落入不同区域，给出选型指引。

图 11-4 提醒选型不要只看功能清单。Iceberg、Hudi、Delta Lake 和 Paimon 的差异，最终会落到写入模式、查询引擎、流批一体需求、社区生态和组织已有平台上。其中“写入模式”和“引擎生态”同样重要：写入决定表如何变化，引擎生态决定这些变化能被哪些系统正确读取。

11.2.1 Catalog、Manifest、元数据文件与对象存储上的表管理

湖仓表的读取通常不是“列出目录下所有文件”。计算引擎先从 Catalog 找到表元数据位置，再读取表格式元数据、manifest 或事务日志，确定当前快照包含哪些数据文件，然后按分区和谓词裁剪读取必要文件。理解这个过程很重要，因为湖仓的性能和一致性都从这里开始。Catalog 解决“表在哪里”和“谁能访问”；metadata file 解决“当前表定义是什么”；manifest 或文件清单解决“当前快照包含哪些文件”；数据文件才是被扫描的内容。若任何一层缺失或漂移，查询可能仍然能跑，但读到的版本、权限或文件范围就可能不正确。

表11-4：Catalog、Manifest、元数据文件等表管理组件的职责与失败模式。来源：本书整理。

图11-5：一次湖仓查询先读元数据再读数据文件。来源：本书自绘。Alt text：查询流程从 Catalog 定位表，到读 Manifest 元数据做分区/文件裁剪，再只读命中的数据文件，箭头体现"先元数据后数据"减少扫描量。

图 11-5 说明湖仓查询不是直接扫描目录。引擎先通过 Catalog 找到元数据入口，再读取快照、manifest 和文件统计信息，然后裁剪并扫描必要的数据文件。图中的顺序也解释了为什么 Catalog 不可用、manifest 过多或统计信息缺失都会影响查询，即使底层数据文件本身没有损坏。接口契约示例：

{
  "table": "dwd.orders",
  "table_format": "iceberg",
  "catalog": "demo",
  "snapshot_id": "742",
  "primary_key": ["order_id"],
  "partition_fields": ["order_date"],
  "schema_version": "orders.v7",
  "data_freshness_seconds": 60,
  "time_travel_enabled": true
}

这份契约使 DataAgent 不只知道表名，还知道读哪个快照、是否具备时间旅行、主键和分区是否明确、新鲜度是否达标。没有这些字段，Agent 在回答中很难解释“数据截至何时”和“为什么这次结果可以复现”。它相当于 DataAgent 查询湖仓表前的准入证：表存在只是第一步，只有版本、新鲜度、主键、分区和时间旅行能力都明确，表才适合进入自动化分析链路。

契约还应进入运行日志。一次回答失败时，排障人员需要看到 Catalog 返回的表位置、读取的快照、实际扫描文件数、分区裁剪命中情况和权限判定结果。若日志只保存最终 SQL，就只能猜测错误发生在哪一层；若日志记录了表契约和执行侧反馈，就能判断是 Agent 选错表、Catalog 指向旧元数据、统计信息缺失，还是某次补数提交改变了业务口径。湖仓元数据只有被纳入 Agent 的审计链路，才能真正服务可解释回答。

11.2.2 数据写入路径：批量导入、流式写入、Upsert、Compaction 与小文件治理

湖仓写入不是把文件直接上传到目录。写入器需要先生成数据文件，再用表格式的事务提交把文件加入新快照。若是 CDC 或 upsert 链路，还要处理主键、删除、版本比较和冲突检测。“先写文件，再提交元数据”是湖仓写入的核心思想。数据文件可以先写到 staging 区，只有当所有文件、统计信息和校验都准备好后，写入器才通过一次原子提交把它们加入表快照。这样即使写入过程中某个任务失败，读者也不会看到半成品。对 Agent 平台来说，这意味着查询要么看到旧版本，要么看到新版本，不能看到一半订单已经更新、一半库存还停留在旧状态。

图11-6：湖仓写入路径从 staging 到原子提交。来源：本书自绘。Alt text：写入流程先把数据写入 staging 文件，再生成新快照并原子切换 Catalog 指针，箭头表示提交前下游始终读到旧快照、提交后整体可见。

图 11-6 展示湖仓写入路径的关键控制点。写入器应先在 staging 区生成数据文件，再通过表格式事务提交到新快照；CDC 或 upsert 链路还要在提交前处理主键、删除语义和冲突检测。staging 区用于隔离未提交文件，commit 步骤用于建立可见版本，Compaction 则用于在后续整理文件布局。

Append 表与 Upsert 表

表11-5：Append 与 Upsert 两类写入模式的优势、代价与适用场景。来源：本书整理。

即时写入与异步 Compaction

表11-6：批量写入与即时写入在可见性与小文件成本上的取舍。来源：本书整理。

Append 与 Upsert 的区别，实际是在“保留过程”和“查询当前状态”之间取舍。原始层通常应保留完整变化过程，方便审计和回放；面向 Agent 的明细层或服务层，则常需要 current 表降低查询复杂度。即时写入与异步 Compaction 的区别，则是在“更快可见”和“长期查询稳定”之间取舍。频繁小批写入能降低新鲜度，但如果长期不整理，第12章的 OLAP 查询会被大量小文件和元数据拖慢。

11.2.3 数据读取路径：快照隔离、谓词下推、分区裁剪与版本固定

读取湖仓表时，计算引擎应在三个层面减少不必要扫描：固定快照，确保整个查询读到同一个版本；利用分区裁剪和谓词下推，只读取相关日期、门店或业务线的数据文件；利用列式文件统计信息跳过不可能匹配的数据块。这三个层面分别解决不同问题。固定快照解决一致性：同一个回答过程中的多次查询应基于同一版本。分区裁剪解决范围：按日期、城市或业务线缩小文件集合。谓词下推和列式统计解决块级跳过：即使文件被选中，也不一定要读取所有列和所有数据块。初学者常把读取性能完全归因于引擎，其实表格式元数据和文件布局会在引擎执行前就决定大量扫描成本。

图11-7：湖仓读取路径用快照和裁剪控制成本。来源：本书自绘。Alt text：读取路径标出按快照锁定版本、按分区裁剪、按列裁剪、按文件统计跳过四道过滤，逐步缩小实际扫描的数据量。

图 11-7 表明读取路径同时服务一致性和成本控制。固定快照保证多轮查询读到同一版本，分区裁剪、谓词下推和列式统计信息则减少不必要的文件与列扫描。图中“先定版本、再裁剪文件、再扫描数据”的顺序，是湖仓查询可复现和可控成本的共同基础。

对 Agent 平台而言，版本固定比单纯性能优化更重要。DataAgent 在多轮对话中可能先查订单总数，再查异常门店，再查供应商影响。如果三次查询读到不同快照，回答可能自相矛盾。平台应把 snapshot_id 或等价的读版本写入查询上下文和审计日志。

11.2.4 湖仓治理：权限、生命周期、审计、数据分层与成本控制

湖仓治理不能停在对象存储目录权限。表级、列级、行级权限，PII 标签，生命周期策略，快照保留，审计日志和成本归因都应围绕 Catalog 和表契约统一管理。原因在于湖仓通常被多个引擎同时访问。若只在对象存储目录上设置权限，Spark、Trino、Doris 外表和 Notebook 可能各自绕出不同路径；若只在某一个引擎内部授权，其他引擎又可能看不到同样的策略。治理必须回到表资产本身，把权限、生命周期、快照、PII 和审计都挂到 Catalog 与表契约上，再发布到各个执行引擎。

图11-8：湖仓治理控制点围绕 Catalog 和表契约展开。来源：本书自绘。Alt text：以 Catalog 为中心，向外辐射权限、生命周期、审计、分层、成本五个治理控制点，表示治理统一挂在 Catalog 与表契约上。

图 11-8 把湖仓治理控制点收敛到 Catalog 和表契约。权限、生命周期、快照、PII、成本和审计都应围绕表资产统一发布，否则不同引擎会逐渐形成互相矛盾的治理口径。Catalog 是治理入口，表契约是治理规则的载体，各查询引擎是规则的执行端。

表11-7：权限、生命周期、审计等湖仓治理对象的控制点与缺失风险。来源：本书整理。

11.3 湖仓表面向 DataAgent 的暴露方式

当前 mini-platform 不连接真实 Iceberg Catalog，也不在本章内嵌 DuckDB 查询。它先实现湖仓表暴露给 DataAgent 前的最小契约和可读性检查，为第12章的引擎路由打基础。这一步的教学重点，是把湖仓能力落实成可检查字段。真实平台中，Iceberg、Hudi、Delta Lake 或 Paimon 会有复杂的 Catalog 和元数据实现；mini-platform 只保留 DataAgent 最关心的最小集合：表格式、Catalog、快照、主键、分区、新鲜度和时间旅行。这样读者可以先理解“什么样的表适合给 Agent 查询”，再进入真实引擎和 Catalog 对接。

• 入口：mini-platform/infra/lakehouse/__init__.py
• 核心实现：mini-platform/infra/lakehouse/table_contract.py
• 测试：mini-platform/tests/test_lakehouse_table_contract.py
• 运行入口：mini-platform/projects/11-lakehouse-contract/run.py

mini-platform/infra/lakehouse/table_contract.py：

class TableFormat(str, Enum):
    ICEBERG = "iceberg"
    HUDI = "hudi"
    DELTA = "delta"
    PAIMON = "paimon"

核心契约对象如下：

@dataclass(frozen=True)
class LakehouseTableContract:
    table: str
    table_format: TableFormat
    catalog: str
    snapshot_id: str
    primary_key: tuple[str, ...]
    partition_fields: tuple[str, ...]
    schema_version: str
    data_freshness_seconds: int
    time_travel_enabled: bool

为了保证可读性，这里的检查项只保留四个最小控制点。主键、分区、新鲜度和时间旅行这四个维度，已经足够支撑多数表级治理判断。

def validate_agent_readiness(contract: LakehouseTableContract) -> dict[str, Any]:
    missing: list[str] = []
    if not contract.primary_key:
        missing.append("primary_key")
    if not contract.partition_fields:
        missing.append("partition_fields")
    if contract.data_freshness_seconds > 3600:
        missing.append("freshness_slo")
    if not contract.time_travel_enabled:
        missing.append("time_travel")

    return {
        "table": contract.table,
        "ready": not missing,
        "missing_controls": tuple(missing),
        "snapshot_id": contract.snapshot_id,
    }

运行测试：

cd enterprise_agent_platform_book/mini-platform
python3 -m pytest tests/test_lakehouse_table_contract.py -q

运行项目：

cd enterprise_agent_platform_book/mini-platform/projects/11-lakehouse-contract
PYTHONPATH=../.. python3 run.py

预期输出：

dwd.orders snapshot=742 format=iceberg
agent_ready=True missing=()

这段输出说明 dwd.orders 具备主键、分区、快照、新鲜度和时间旅行控制点，可以进入 DataAgent 可读候选表。若缺少任一控制点，项目会返回 ready=False 和缺失清单；真实平台应把这些信号写入第15章的数据目录和第34章的 NL2SQL 表选择逻辑。

11.3.1 湖仓表进入 Agent 链路前的必备条件

• Catalog：生产表统一登记到一个受治理 Catalog，不允许多引擎私自维护同名表。
• 表格式：核心湖仓表明确使用 Iceberg、Hudi、Delta Lake 或 Paimon，并记录版本兼容性。
• 快照：关键表保留足够长的快照窗口，满足审计和 Agent 回答复现。
• Schema：字段新增、删除、改名、类型变化必须走兼容性检查和公告。
• 分区：分区字段服务主要查询模式，避免过细分区和高基数字段分区。
• 小文件：监控文件数、平均文件大小、manifest 数量和 compaction 延迟。
• 权限：Catalog、对象存储、查询引擎三层权限定期对账。
• PII：字段标签和脱敏策略进入表契约，Agent 查询前必须执行策略过滤。
• 生命周期：原始层、明细层、汇总层、沙箱层分别定义保留策略。
• 审计：记录表提交、读快照、删除、权限变更和清理任务。
• 成本：按表、团队、引擎记录扫描量和对象存储请求成本。
• 灾难恢复：Catalog 元数据、对象存储数据和关键快照有备份和恢复演练。

11.3.2 湖仓表异常时的优先证据

对象存储目录被当成表直接删除

• 现象：清理临时目录时误删生产表部分数据文件，查询开始出现文件不存在。
• 根因：运维脚本绕过表格式和 Catalog，按路径直接删除对象。
• 修复：所有删除通过表格式工具和 Catalog 审计执行；对象存储目录权限收紧，只允许表服务账号写入。

快照保留窗口过短导致历史回答无法复现

• 现象：业务追问一周前 DataAgent 的回答依据，平台已清理当时快照。
• 根因：快照清理只按存储成本设置，没有按审计需求分级。
• 修复：关键表按业务价值设置快照保留；回答审计记录保存 snapshot_id，长期归档必要元数据。

小文件导致 OLAP 查询成本突然升高

• 现象：CDC 入湖后文件数暴涨，Trino 和 StarRocks 外表查询延迟上升。
• 根因：微批间隔太小，Compaction 任务滞后，manifest 读取开销变大。
• 修复：调大写入批次，设置 compaction 调度和告警，把高频查询数据物化到服务层。

多个引擎维护不同 Catalog 名称

• 现象：Spark 写入 dwd.orders，Trino 读到旧路径，DataAgent 与报表结果不一致。
• 根因：Spark、Trino、BI 工具各自维护表定义，Catalog 没有统一发布。
• 修复：建立统一 Catalog 和发布流程；查询审计记录 catalog、table、snapshot_id，禁止生产查询使用私有路径。

11.4 湖仓表发布台账与 Agent 可读性复审

湖仓表进入 Agent 链路前，需要一份面向运行的发布台账。台账不应只记录“表已上线”，还要记录表格式、Catalog 名称、Schema 版本、主键或唯一性约束、分区策略、快照保留窗口、数据新鲜度、权限策略和负责人。DataAgent 后续生成 SQL、解释指标、回放回答时，依赖的正是这些信息。如果发布记录只停留在数据平台内部，Agent 团队通常只能从表名和字段注释里推断可用范围，推断越多，回答越难复盘。

发布台账要和快照保留策略放在一起看。经营分析、财务复盘和合规问答经常需要解释某个历史回答来自哪一版数据。湖仓表如果只保留很短的快照窗口，DataAgent 当时的回答可能在一周后无法重现。生产环境可以按表分级：高价值经营指标表保留更长快照和元数据归档，探索层和沙箱层采用较短保留期。审计记录至少保存 catalog、table、snapshot_id、schema_version 和执行时间，这样即使数据文件已按生命周期清理，团队仍能解释回答基于哪一次提交。

Agent 可读性复审应成为 Schema 演化的一部分。新增字段通常风险较低，但字段改名、类型变化、分区变化和口径迁移会影响 NL2SQL、语义层绑定和历史回答。数据平台发布变更时，需要同步判断 DataAgent 是否已经把该表纳入候选集，是否有验收样本引用该字段，是否需要暂停相关问题入口。若 Catalog 中表路径变了、字段含义变了，而 Agent 侧仍沿用旧缓存，用户会看到“查询成功但结论错误”的事故，这类问题比直接报错更难发现。

复审还要覆盖跨团队责任。数据平台团队负责表格式、Catalog、快照和质量信号；业务数据负责人确认口径、字段解释和生命周期；Agent 平台团队确认工具权限、查询审计和 Trace 记录；DataAgent 产品负责人决定该表是否进入自然语言问数范围。四方职责不清时，表虽然能被 SQL 引擎查询，却不一定适合被 Agent 自动使用。发布台账应记录这些责任人，线上争议发生时才能快速判断该修数据、修语义层、修工具权限，还是修回答模板。

早期可以把复审做得很轻：每次表进入 DataAgent 白名单前，要求通过最小契约检查，并保存一条发布记录；每次 Schema 发生不兼容变更时，触发相关验收样本；每次用户对 DataAgent 回答提出争议时，回到这份台账检查快照、Schema 和负责人。这个流程不会增加复杂的湖仓能力，却能把“表可查询”和“表适合被 Agent 使用”区分开来，为第15章的数据目录、第33章语义层和第34章查询执行提供稳定入口。

11.5 数据契约变更的运行复盘

数据基础设施进入 Agent 平台后，schema 变更不再只是数据团队内部事项。字段改名、类型变化、枚举扩展、分区延迟、主键重复、空值比例上升，都会影响 RAG、DataAgent、报表生成和工具调用。一次上游表结构变化，可能让 NL2SQL 生成失败，也可能让报告中的指标解释失真。平台需要把数据契约变更纳入运行复盘，而不是等应用报错后再定位。

复盘材料应记录变更来源、影响表、字段级差异、下游依赖、回滚计划、验证样本和通知范围。若字段被删除，要知道哪些语义层指标、查询模板、DataAgent 样本和报告块受影响；若分区延迟，要说明哪些 Agent 任务需要提示用户数据尚未刷新；若枚举值变化，要检查权限策略、过滤条件和图表分组是否仍然正确。数据契约复盘的价值，是让上游变化在进入智能链路前就被解释清楚。

早期平台可以先从高频核心表做起。每个核心表有 owner、schema 版本、质量阈值、下游 Agent 清单和回归样本。变更发布前跑样本，发布后观察查询失败、空结果、权限拒绝和用户反馈。这样数据基础设施才能支撑后续 Agent 能力，而不是只提供可连接的数据源。

11.6 湖仓表进入智能链路的发布演练

湖仓表接入 Agent 平台前，团队应做一次面向任务链路的发布演练。演练要从用户问题出发，检查语义层能否找到表、权限策略能否裁剪字段、查询引擎能否读取指定快照、Trace 能否记录 snapshot_id，以及回答层能否把数据时间和口径说明清楚。只跑一条 SQL 会漏掉这些链路问题，它们在数据平台内部不明显，进入自然语言问答后却容易变成事故。

发布演练可以选取三类样本。第一类是稳定经营指标，例如销售额、活跃用户、库存周转天数，用来验证表契约和指标口径。第二类是边界查询，例如跨月、跨区域、权限受限字段和历史快照，用来验证权限、分区和时间旅行。第三类是异常样本，例如空分区、小文件堆积、字段枚举变化和延迟到达数据，用来验证 Agent 是否会给出降级提示，而不是把不完整结果解释成确定结论。样本数量不需要很大，但要覆盖表进入智能链路后的真实风险。

演练结果应进入发布记录。若某张表只能支持内部分析，记录中要说明它不能进入自然语言问数；若某张表可以进入 DataAgent，但只适合异步报告，也要写清延迟边界；若某张表字段说明不足，应先补数据目录和业务 owner，再开放给模型选择。湖仓工程的质量，最终会体现在这些发布约束是否被执行，而不是体现在表格式名称是否先进。

11.7 湖仓表退役前的 Agent 影响评估

湖仓表退役前，要评估 Agent 影响。数据团队可能认为一张旧表已经被新表替代，但 DataAgent 的语义层、历史报告、评测样本和用户收藏问题仍可能引用旧表。若直接删除，用户看到的会是问数失败、报告无法回放或历史结论失去证据，而不会理解为一次正常表退役。

退役评估应检查语义层绑定、查询日志、Trace、报告 artifact、评测集和权限策略。若旧表仍被历史证据引用，可以停止新查询，但保留必要元数据和快照说明；若旧表进入过训练或样本集，也要更新样本来源。湖仓表生命周期管理进入 Agent 平台后，删除动作要同时考虑运行链路和审计链路。

11.8 湖仓表的跨环境一致性验收

湖仓表进入 Agent 链路后，还要验收跨环境一致性。开发、预发和生产环境里的 Catalog、表路径、权限策略、快照保留和质量规则如果不一致，DataAgent 在预发通过的样本，生产中仍可能失败。常见问题包括预发环境没有真实权限过滤，生产 Catalog 中字段注释缺失，开发环境保留更长快照，生产环境清理策略更激进。模型和语义层看到的表契约一旦不同，问数结果就很难解释。

跨环境验收要围绕同一组任务样本。平台可以选择几类问题：稳定指标查询、权限受限查询、历史快照查询、延迟分区查询和异常空结果查询。每个环境都执行同一组样本，并比较表版本、字段解释、权限裁剪、快照 id、查询结果和 Trace 字段。若预发和生产差异来自数据脱敏，可以接受，但要在验收记录中说明；若差异来自表契约或权限规则，就不能直接发布。

早期可以把跨环境一致性写入湖仓表发布门禁。每张进入 DataAgent 白名单的核心表，都要有开发、预发、生产三类环境的契约摘要。这样数据团队能在发布前发现环境漂移，Agent 团队也能知道某个失败是否来自模型、语义层，还是底层表环境不一致。湖仓的价值不止在表格式能力，也在于不同环境里都能给智能链路提供同样可解释的数据契约。

11.9 湖仓表新鲜度争议的处理

湖仓表进入自然语言问数后，新鲜度争议会变得更频繁。用户可能问“今天的销售额为什么和仪表盘不同”，DataAgent 给出的答案来自某个快照，仪表盘来自另一个缓存层，手工报表又使用了补录后的分区。若系统只返回一个数字，争议会被理解成模型回答错误；实际问题可能是快照选择、分区延迟、指标口径、缓存刷新或权限裁剪不一致。

处理这类争议时，平台要能同时说明数据时间、快照标识、分区状态和质量信号。DataAgent 回答经营指标时，不应只引用表名，还应记录 snapshot_id、数据截止时间、查询引擎、语义层版本和指标定义版本。若查询命中了旧快照，系统可以给出解释并提示最新分区正在刷新；若用户没有权限查看某些字段，回答中要把权限裁剪和数据缺口区分开。这样争议可以进入数据链路排查，而不是在模型和数据团队之间来回转移。

新鲜度争议还需要保留对比材料。复盘时应把用户问题、DataAgent SQL、执行快照、仪表盘数据源、调度状态、质量规则和报告 artifact 放在一起看。若仪表盘使用了近实时流式汇总，而湖仓表按小时落盘，差异属于产品说明问题；若湖仓表延迟但质量规则没有阻断回答，问题在发布门禁；若语义层选择了旧表，问题在表绑定和退役流程。不同原因对应不同修复动作。

早期可以给进入问数链路的湖仓表增加“可回答时间”字段。这个字段说明表在什么刷新状态下可以用于同步回答，什么状态下只能用于异步报告，什么状态下必须拒答或降级。它不替代调度和质量规则，而是把底层数据生产状态翻译成 Agent 可执行的回答边界。这样第11章的湖仓能力会自然承接第14章编排质量、第15章元数据契约和第34章 NL2SQL 执行链路。

11.10 湖仓表变更的消费方影响评估

湖仓表结构变化会直接影响 Agent 能力。新增字段、字段改名、分区调整、主键变化、历史回补和权限标签变化，都可能改变语义层、NL2SQL、报表模板和评测样本。数据团队如果只发布表变更通知，不说明消费方影响，Agent 运行时才会暴露问题。表变更应进入消费方影响评估，而不是只看数据作业是否成功。

影响评估要从依赖图开始。平台应知道哪些语义层指标、SQL 模板、特征任务、Embedding 任务、报告 artifact 和 Agent 工具依赖这张表。对于低风险字段新增，可以直接发布并补充文档；对于字段语义变化，要回放查询样本和报告样本；对于权限标签变化，要检查越权和误拦截样本；对于历史回补，要说明哪些历史回答可能受到影响。

早期可以为高价值表建立变更卡：变更内容、影响字段、下游消费者、样本回放结果、发布时间、回滚方式和业务 owner 确认。这样湖仓不再只是存储层，而是 Agent 平台的事实来源。表结构变化能被追踪，DataAgent 的回答变化也更容易解释。

11.11 数据接入变更的运行证据

数据接入进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把数据源版本、抽取窗口、字段映射、延迟、失败重放和下游影响记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第33章语义层、第38章 Trace 和第52章合规证据相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括字段静默变化、增量窗口丢失、脱敏规则未生效、下游缓存继续使用旧数据。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

数据 owner 和平台 owner 应把接入变更放入同一份发布记录。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

11.12 接入失败后的下游止损

数据接入失败后的处置不能停在重跑任务。接入层一旦产生延迟、重复、丢数或字段漂移，下游的语义层、向量索引、报表缓存和 Agent 回答都可能继续传播错误。平台需要定义止损动作：暂停相关指标、标记数据新鲜度、失效缓存、阻断高风险回答、通知业务 owner，并在 Trace 中说明本次回答是否使用了受影响数据。

止损动作要根据数据类型分层。普通维表延迟可能只需要提示新鲜度；关键事实表缺失会影响经营指标，应阻断自动报告；权限字段异常会影响访问边界，应暂停相关查询；文档解析源失败会影响 RAG，应降低回答置信度或要求人工复核。接入层如果只把失败上报给数据工程团队，Agent 平台仍可能继续给用户输出看似正常的答案。

早期可以把接入故障和下游影响写进同一张事故记录。记录包含数据源、影响字段、影响指标、影响 Agent、止损动作、恢复样本和用户通知。这样第11章就能和后面的语义层、RAG、DataAgent、Trace 形成明确连接，读者也能看到数据接入为什么属于平台可靠性问题。

本章小结

湖仓是在开放存储上补齐表事务、快照、Schema、分区和治理语义。Iceberg、Hudi、Delta Lake 和 Paimon 都能承担这类职责，但写入模式、引擎生态和组织前提不同，不能只按名称选型。DataAgent 读取湖仓时，表名之外还需要 Catalog、快照、主键、分区、新鲜度和时间旅行能力。小文件、快照清理、Schema 演化、Catalog 漂移和孤儿文件都容易变成生产事故。mini-platform 先用最小表契约固化 Agent 可读性检查，真实湖仓连接应在契约和治理边界清楚后接入。

参考文献

Apache Iceberg. (n.d.). Documentation.

Delta Lake. (n.d.). Documentation.

Apache Hudi. (n.d.). Documentation.

Apache Paimon. (n.d.). Documentation.

第12章 湖仓引擎与 OLAP

湖仓引擎与 OLAP 是 Agent 分析链路中的执行层。DataAgent 生成的 SQL 最终要落到某个引擎上执行，选 Trino、ClickHouse 还是 StarRocks，直接影响延迟、并发和成本。多引擎路由、查询控制、安全边界和性能工程决定不同查询该走哪条执行路径，也决定平台能否用资源控制、超时和权限边界防止一条失控 SQL 拖垮系统。湖仓表已经保存好了数据，并不意味着查询链路已经可靠。一个经营分析 Agent 生成了跨三年订单明细的 Join 查询，默认路由到交互式引擎，结果占满资源池，财务看板和运营临时查询一起变慢。查询本身并非恶意，但它没有进入合适的执行队列，也没有被扫描量、超时和权限策略提前约束。OLAP 层要把自然语言生成的 SQL 变成受控执行。平台需要按工作负载、权限、预算和数据快照选择引擎，并把查询失败、慢查询和资源争抢反馈给 Agent，而非让模型直接把 SQL 扔给任意数据库。

OLAP 层是 DataAgent 从“会生成 SQL”走向“能稳定执行分析”的地方。用户不会关心查询跑在 Trino、ClickHouse 还是 StarRocks 上，但平台必须知道。一个跨年宽表 Join、一个明细级导出、一个秒级看板查询和一个离线归因任务，对引擎、队列、缓存和权限的要求完全不同。若所有 SQL 都丢给同一个入口，失控查询会占满资源，正常分析也会被拖慢。企业里常见的故障，是查询被放到了错误路径；数据库不可用只是一类情况。经营分析 Agent 为了回答一个追问，扫描了三年订单明细；临时分析占用了交互式资源池；用户以为系统卡住，反复重试，成本继续上升。模型生成的 SQL 语法正确，但执行层没有给它资源上限、超时、扫描量控制和队列隔离。湖仓和 OLAP 的设计要把 SQL 执行变成受控动作。Catalog 负责解释表在哪里，开放表格式负责维持快照和 schema，查询引擎负责执行，路由器负责把任务放到合适资源池。DataAgent 只负责提出分析意图和候选 SQL，最终执行要接受平台的权限、成本和性能约束。

12.1 OLAP 引擎在 DataAgent 分析执行链路中的角色

第11章 解决湖仓表如何可靠保存，第12章 解决这些表如何被查询、分析和服务。一家多业务线企业的数据已经通过采集链路进入湖仓，订单、库存、会员、工单和设备数据以开放表格式管理。但业务问题并不都适合同一个计算系统。财务看板要求稳定秒级返回，运营团队要高并发查询当天销售，数据科学家要在 Notebook 中读抽样文件，DataAgent 需要跨 MySQL、Iceberg 和指标层做探索。在线分析处理（Online Analytical Processing，OLAP）引擎的职责是面向大范围扫描、过滤、聚合、Join、排序和窗口函数做优化。它不同于在线事务处理（Online Transaction Processing，OLTP）数据库，后者服务短事务、点查、行级更新和高并发写入。Agent 平台若直接把复杂分析压到 OLTP 源库，会影响生产系统；若只把所有分析交给一个通用引擎，又会在延迟、成本或治理上付出代价。

OLAP 引擎可以理解为湖仓表和业务消费之间的“计算适配层”。湖仓保存数据资产，但用户需要的是指标、报表、探索结果和可解释 SQL 输出。不同消费方式对计算适配层的要求不同：看板要求稳定低延迟，临时分析要求灵活 SQL，事件分析要求高吞吐写入和时间过滤，本地探索要求低成本和易嵌入。若没有这层区分，平台会把所有查询塞进同一个系统，结果要么慢查询拖垮看板，要么为了低延迟报表牺牲探索灵活性。对 DataAgent 来说，OLAP 引擎还承担“可控执行”的职责。Agent 生成查询后，平台需要选择合适引擎、限制扫描量、应用权限策略、设置超时、记录审计并返回可解释错误。引擎不能被看作被动数据库，它是 Agent 分析链路中的执行边界。

图12-1：OLAP 引擎把湖仓数据变成可消费的数据服务。来源：本书自绘。Alt text：底层湖仓表经 OLAP 引擎查询后，向上提供给看板、API、DataAgent 等消费方，引擎位于"存储"与"消费"之间作为查询服务层。

图 12-1 展示了“同一份湖仓资产，多种消费方式”。DataAgent 的临时探索可以走 Trino，固定经营看板可以走 StarRocks 或 Doris，日志与事件分析可以走 ClickHouse，统一数据工程和机器学习可以走 Databricks，云数仓标准报表可以走 Snowflake，本地抽样验证可以走 DuckDB。重点不在于多装几个引擎，而在于用统一入口控制路由、权限、成本和审计。这里需要回答两个问题：哪类工作负载走哪条路径，以及这些路径是否仍被统一治理。

12.1.1 企业分析负载分类

引擎选型要从负载分类开始。产品名称本身不能说明问题，因为同一个 SQL 引擎在不同负载下表现可能完全不同。即席查询重视灵活连接和容错，固定仪表盘重视并发和稳定延迟，指标查询重视口径一致和可缓存，联邦查询重视连接器能力，本地探索重视单机效率和易用性，事件分析重视时间过滤和写入吞吐。先分清负载，平台才能给每类查询设置不同的延迟目标、预算、权限和降级策略。

表12-1：即席查询、报表、明细检索等分析负载的延迟目标与适配引擎。来源：本书整理。

图12-2：企业分析负载决定引擎候选项。来源：本书自绘。Alt text：左侧列出即席查询、固定报表、明细点查、实时大屏等负载，箭头分别指向更合适的引擎类型，说明先看负载特征再定引擎。

图 12-2 表明，引擎选型应先识别负载类型。即席查询、仪表盘、指标查询、联邦查询、本地探索和事件分析对延迟、并发、成本和治理的要求不同，因此自然会落到不同的候选引擎组合。图中的候选项只是提示读者先把“查询为什么存在”讲清楚，再选择执行系统，并不是固定答案。

12.1.2 OLAP 核心机制

现代 OLAP 引擎通常围绕六类机制优化：列式存储只读必要列；编码和压缩减少 I/O；向量化执行批量处理数据；大规模并行处理（Massively Parallel Processing，MPP）把任务拆到多节点；优化器基于统计信息选择计划；缓存和物化视图减少重复计算。这些机制共同服务一个目标：用可接受的成本扫描大量数据并快速得到聚合结果。列式存储让查询只读 city 和 amount 这样的必要列，避免读取整行订单；压缩和编码减少磁盘与网络传输；向量化执行让 CPU 批量处理数据；MPP 把扫描和聚合拆到多个节点；优化器决定过滤和 Join 的顺序；缓存和物化视图减少重复计算。理解这些机制后，团队才能判断慢查询来自数据布局、统计信息、Join 计划，还是资源隔离。

图12-3：现代 OLAP 查询执行链路。来源：本书自绘。Alt text：横向链路依次为 SQL 解析、逻辑计划、优化器、分布式执行、结果返回，各阶段标注关键动作，体现一条查询从文本到结果的处理过程。

图 12-3 中容易被忽略的是优化器和数据布局。若没有统计信息，引擎可能选择错误 Join 顺序；若分区和排序键不匹配查询条件，再强的向量化执行也会变成大范围扫描。第11章的表格式、分区、文件大小和快照管理，会直接影响本章的查询成本。一次查询要先解析、优化、拆分、调度，再扫描和聚合；任何一步缺少输入信息，都会把成本放大到后续阶段。

12.1.3 OLAP 选型要先看工作负载

OLAP 引擎选型有三类常见偏差。第一类是认为有了湖仓表格式就不需要 OLAP 引擎。表格式解决数据资产开放性，查询性能仍取决于执行引擎、数据布局、统计信息、缓存和并发控制。表格式回答“读哪些文件才一致”，OLAP 引擎回答“如何高效读并计算这些文件”。第二类是把所有分析场景强行统一到一个引擎。统一能降低治理复杂度，也会牺牲特定负载的成本或延迟。更现实的做法是统一元数据、权限和审计，允许多个引擎围绕同一份数据协同。这里要统一的是控制平面，不是执行引擎本身。第三类是只看基准测试排行榜。基准测试不能替代对真实数据分布、真实 SQL、并发、写入模式、权限模型、成本和团队运维能力的评估。一个引擎在标准测试上很快，不代表它适合一家多业务线企业的权限模型、数据倾斜、冷热分层和 Agent 查询模式。

12.2 湖仓查询路径：Catalog、开放表格式、对象存储与计算引擎协作

一次受控湖仓查询通常经过五个步骤：用户或 DataAgent 提交查询意图；查询路由器选择引擎；策略控制器校验权限、预算和超时；Catalog 适配器解析表、快照和连接信息；执行适配器提交到具体引擎并返回结果句柄。这个路径的核心思想是“先控制，再执行”。DataAgent 生成的 SQL 只是查询意图的一种表达，还不能直接提交给底层引擎。平台必须先判断查询适合哪类负载，用户是否有权限，是否超过扫描预算，是否需要固定快照，是否应读取脱敏视图。只有这些判断完成后，执行适配器才把查询交给 Trino、StarRocks、Snowflake 或其他引擎。

图12-4：受控湖仓查询先过路由、策略和 Catalog。来源：本书自绘。Alt text：查询进入后依次经过查询路由器、策略引擎（权限/限额）、Catalog（元数据/行列权限），三道关卡通过后才提交引擎执行。

图 12-4 展示受控查询入口的基本路径。用户或 DataAgent 的查询意图先经过路由和策略校验，再通过 Catalog 解析表、快照和连接信息，然后提交给具体执行引擎。图中路由、策略和 Catalog 位于引擎之前，说明治理是执行前必须经过的控制点，而非查询完成后的审计补丁。

平台不建议让 DataAgent、BI 工具或业务系统直接裸连所有引擎。裸连会带来三个问题：权限口径不一致，成本无法归因，失败无法解释。统一接入层不一定是重型网关，也可以先从规则路由和审计记录开始。对早期平台来说，先记录工作负载标签、选择引擎、用户身份、快照和错误码，就已经能让排障和审计有据可查。

12.2.1 引擎生态对比

表12-2：平台型湖仓、MPP、实时 OLAP 等引擎类型的代表产品与适用场景。来源：本书整理。

表 12-2 不是产品排名。Databricks 和 Snowflake 更像平台或托管服务，能覆盖较宽的治理和工程场景；Doris、StarRocks、ClickHouse 更偏向低延迟服务化分析；Trino 的价值在开放连接和联邦查询；DuckDB 的价值在本地与嵌入式。企业常见做法是先确定主路径，再给特殊负载保留合适工具，不必选一个赢家。

图12-5：七类湖仓与 OLAP 引擎的系统边界不同。来源：本书自绘。Alt text：七种引擎类型并排，各自标出存储耦合度、延迟特征、并发能力和适用负载，对比它们的系统边界差异。

图 12-5 的重点是系统边界。Databricks、Snowflake、Doris、StarRocks、ClickHouse、Trino 和 DuckDB 都能服务分析，但它们分别偏向平台化、托管数仓、实时服务、事件分析、联邦查询或本地探索。选型时要看每类引擎“负责到哪里”：有的包含治理和工程平台，有的主要负责执行，有的适合嵌入在本地进程中。

图 12-5 的含义是先确定系统边界，再比较产品能力。Databricks 和 Snowflake 偏平台化或托管体验；Doris、StarRocks、ClickHouse 偏低延迟服务化分析；Trino 偏连接器和联邦查询；DuckDB 偏单机本地分析。同一张 Iceberg 表可以被多个引擎读取，但每条访问路径都需要不同的 SLA、预算和运维 playbook。

12.2.2 SQL 方言、权限模型、资源组与多租户隔离

多引擎协同时，平台最容易低估的是非性能问题。SQL 方言差异会导致 DataAgent 生成的语句在一个引擎可运行、另一个引擎失败；权限模型差异会导致同一用户在不同入口看到不同列；资源组和 warehouse 配置差异会导致成本和并发不可控。路由器需要返回引擎名称，也要返回工作负载类型、SQL 方言、可访问表列、扫描预算，以及失败时能否换引擎。对 DataAgent 来说，方言差异尤其重要：同一个日期函数、JSON 函数或近似聚合函数，在不同引擎中的语法和语义可能不同。平台要么在生成 SQL 前绑定方言，要么在提交前做语法转换和校验。

表12-3：查询路由器、策略引擎等组件的职责、输入输出与失败模式。来源：本书整理。

接口契约示例：

POST /api/lakehouse/query
Request:
{
  "principal": "user:finance_analyst_01",
  "workload": "realtime_bi",
  "sql": "select city, sum(amount) from mart.sales group by city",
  "latency_budget_ms": 3000,
  "cost_budget": "low",
  "result_mode": "preview"
}

Response:
{
  "query_id": "q_20260611_001",
  "engine": "StarRocks",
  "state": "submitted",
  "result_ref": "lakehouse-results/q_20260611_001"
}

Errors:
{
  "code": "POLICY_DENIED | ENGINE_UNAVAILABLE | QUERY_TIMEOUT | COST_BUDGET_EXCEEDED",
  "reason": "...",
  "retryable": true
}

这个接口契约把查询执行拆成可观测状态，而非简单返回一张结果表。workload 帮助路由器选择引擎，latency_budget_ms 和 cost_budget 帮助策略控制器做预算判断，result_mode 决定返回预览还是落地结果。错误码中的 retryable 也很关键：权限拒绝和预算超限通常不应自动重试，引擎暂时不可用才可能触发降级或换路由。

12.2.3 性能工程：物化视图、Rollup、数据分布、冷热分层与查询加速

性能工程要从查询模板和数据布局开始，而非先加机器。固定看板应优先使用物化视图、汇总表、Rollup 或服务化宽表；探索查询应限制扫描量和并发；日志事件分析应围绕排序键、分区和压缩设计；冷历史查询应接受更高延迟或走低成本引擎。性能工程的第一步，是把查询分成“重复发生”和“临时发生”。重复发生的查询，应尽量通过预计算、物化视图、缓存和宽表把成本前移；临时发生的查询，则要控制扫描范围和并发，避免少数探索请求拖垮共享集群。对 DataAgent 尤其如此，因为 Agent 可能在多轮对话中自动发起多个探索查询，如果没有预算和缓存，很容易把一次自然语言追问变成一组昂贵 SQL。

图12-6：性能工程把负载分流到预计算、缓存和探索路径。来源：本书自绘。Alt text：查询按特征分流，高频固定查询走物化视图/Rollup 预计算，重复查询走缓存，低频探索走联邦/直查，三条路径分别标注收益。

图 12-6 说明，性能工程先做负载分流，再谈扩容。高频看板走预计算和缓存，探索查询限制扫描量和并发，冷历史查询接受更高延迟或走低成本引擎。图中的分流逻辑与 12.2 的负载分类一一对应：先分类，再决定是否预计算、缓存、限流或降级。

单引擎统一与多引擎协同

表12-4：单引擎统一与多引擎路由两种架构的取舍。来源：本书整理。

联邦查询与预建数据集

表12-5：物化视图、联邦查询等查询加速手段的优势与代价。来源：本书整理。

单引擎统一适合作为早期平台的过渡策略，但一旦负载分化，就需要至少在逻辑上区分执行路径。联邦查询也应被当作探索工具，而非长期报表路径；当某个联邦查询被频繁使用时，就应该沉淀成预建数据集、物化视图或指标层能力。这个转化过程，是数据平台从“能查”走向“稳定服务”的关键。

12.2.4 Agent 查询安全：只读执行、超时、限额、结果脱敏与审计

Agent 生成 SQL 后必须经过安全执行边界。最低要求包括只读执行、禁止危险语句、限制扫描量、设置超时、限制返回行数、脱敏敏感列、记录 SQL 摘要和结果去向。若查询失败，错误码需要能区分权限拒绝、预算超限、引擎不可用和 SQL 语义错误，避免 Agent 无意义重试。这里的安全需要同时防止删除表，也要防止“合法但危险”的查询。一个只读 SELECT 仍可能扫描全量历史、跨源 Join 巨表、返回过多敏感明细，或在用户没有授权的维度上聚合。Agent 的自动化能力越强，执行边界越要前置。平台应把 SQL 安全、数据权限、成本预算和结果脱敏作为同一条链路处理，避免拆成四个互相独立的开关。

图12-7：Agent 查询安全边界在引擎提交前生效。来源：本书自绘。Alt text：在 SQL 提交到引擎之前设置只读校验、超时、行数限额、结果脱敏四道关卡，箭头表示任一不通过即拦截，体现安全前置。

图 12-7 强调安全边界必须在查询提交前生效。只读执行、危险语句拦截、扫描量限制、超时、脱敏和审计应由平台统一执行，不能依赖 Agent 自觉生成安全 SQL。控制点都位于执行适配器之前，意味着不通过策略的查询根本不应到达底层引擎。状态机如下。

表12-6：Agent 查询从提交到完成各状态的进入条件与失败处理。来源：本书整理。

图12-8：湖仓查询状态机支撑超时、取消和可解释失败。来源：本书自绘。Alt text：状态机含 Submitted、Planned、Running、Succeeded、Failed、Cancelled 等节点，标出超时和取消的转移边，说明每次失败都有明确状态可解释。

图 12-8 给出查询生命周期的状态边界。平台需要区分提交、规划、运行、成功、超时、取消和失败，才能正确决定是否重试、是否降级，以及向 Agent 返回什么可解释错误。状态机可以防止“失败就重试”的简单策略：权限拒绝应停止，超时应缩小范围或走物化视图，引擎不可用才考虑备用引擎。

12.3 湖仓引擎路由器与查询执行契约

mini-platform 不直接连接 Databricks、Snowflake、Doris、StarRocks、Trino、ClickHouse 或 DuckDB，而是先实现“负载到候选引擎”的规则模型。这样做的原因是：真实执行适配器之前，平台必须先定义工作负载分类、默认引擎、替代引擎、延迟预算和扫描预算。这个实现先定义路由规则，再接执行适配器。真实引擎连接会涉及账号、网络、驱动和部署环境；在这些工程细节之前，平台必须已经知道 realtime_bi 为什么默认走 StarRocks，federated_query 为什么默认走 Trino，local_analytics 为什么默认走 DuckDB。mini-platform 用规则模型先展示选型依据，避免一开始就陷入连接字符串和客户端参数。

• 入口：mini-platform/infra/lakehouse/__init__.py
• 核心实现：mini-platform/infra/lakehouse/engine_selector.py
• 测试：mini-platform/tests/test_lakehouse_engine_selector.py
• 实战项目：mini-platform/projects/12-lakehouse-engine/run.py

图12-9：mini-platform 用工作负载标签生成引擎路由决策。来源：本书自绘。Alt text：查询带上工作负载标签（如 adhoc、report、realtime）进入路由器，路由器据标签和数据位置输出目标引擎，体现标签驱动路由。

图 12-9 对应本章 mini-platform 的路由流程：输入工作负载标签和延迟预算，规则模型返回主引擎、备选引擎、扫描预算和可行性判断。它展示的是查询控制面的最小版本，生产系统还需要接入权限、队列、缓存和审计。mini-platform/infra/lakehouse/engine_selector.py：

class Workload(str, Enum):
    PLATFORM = "platform"
    CLOUD_WAREHOUSE = "cloud_warehouse"
    REALTIME_BI = "realtime_bi"
    FEDERATED_QUERY = "federated_query"
    EVENT_ANALYTICS = "event_analytics"
    LOCAL_ANALYTICS = "local_analytics"

核心规则节选：

_RULES: dict[Workload, EngineChoice] = {
    Workload.REALTIME_BI: EngineChoice(
        primary="StarRocks",
        alternatives=("Apache Doris", "ClickHouse"),
        reason="高并发看板、低延迟聚合、物化视图和 MySQL 协议生态。",
        latency_budget_ms=3000,
        max_scan_gb=200,
    ),
    Workload.FEDERATED_QUERY: EngineChoice(
        primary="Trino",
        alternatives=("Apache Doris", "Databricks Lakehouse Federation"),
        reason="以连接器访问多源数据，适合作为开放湖仓 SQL 入口。",
        latency_budget_ms=30000,
        max_scan_gb=1024,
    ),
}

route_query 在 choose_engine 之上叠加调用方延迟预算：

def route_query(request: dict) -> dict:
    choice = choose_engine(request["workload"])
    requested = request.get("latency_budget_ms")
    effective_budget = choice.latency_budget_ms
    latency_feasible = True
    if requested is not None:
        effective_budget = min(effective_budget, requested)
        latency_feasible = requested >= choice.latency_budget_ms

    return {
        "engine": choice.primary,
        "alternatives": choice.alternatives,
        "latency_budget_ms": effective_budget,
        "max_scan_gb": choice.max_scan_gb,
        "latency_feasible": latency_feasible,
        "reason": choice.reason,
    }

运行测试：

cd enterprise_agent_platform_book/mini-platform
python3 -m pytest tests/test_lakehouse_engine_selector.py -q

运行项目：

cd enterprise_agent_platform_book/mini-platform/projects/12-lakehouse-engine
PYTHONPATH=../.. python3 run.py

预期输出：

realtime_bi -> StarRocks
federated_query -> Trino
local_analytics -> DuckDB
route realtime_bi@1500ms -> StarRocks budget=1500ms feasible=False

示例的末行说明：调用方要求 1500ms，但 realtime_bi 在规则中目标延迟是 3000ms。路由器仍返回 StarRocks，同时标记 latency_feasible=False，提示上层缩小时间范围、走物化视图或调整 SLA，而非盲目提交慢查询。

12.3.1 查询执行链路的上线准入标准

• 权限：查询入口接入统一身份系统，行列级权限以平台策略为准。
• 审计：记录用户、SQL 摘要、引擎、数据集、快照、扫描量、耗时、错误码和结果去向。
• 成本：按用户、团队、工作负载和引擎设置预算；对全表扫描和跨源 Join 做预估拦截。
• 性能：高频查询建立物化视图、结果缓存或预建数据集；探索查询限制并发和扫描量。
• 稳定性：设置超时、取消、连接池上限、并发上限和降级策略。
• 可观测性：连接 DataAgent 调用、SQL 生成、查询执行和结果解释 trace。
• 灾难恢复：核心报表有备份路径和备用引擎；路由规则、权限和 Catalog 配置版本化。
• 数据一致性：生产看板读取发布快照或稳定数据集，不直接读取正在提交的中间表。

12.3.2 查询失败在引擎、权限与数据布局中的定位

把 Trino 当成高并发报表数据库

• 现象：DataAgent 和 BI 看板共用 Trino，临时跨源查询拖慢固定经营看板。
• 根因：Trino 适合开放湖仓入口和跨源探索，但不负责热点数据物化和报表服务隔离。
• 修复：固定看板迁移到 StarRocks、Doris、ClickHouse 或 Snowflake warehouse；Trino 保留探索入口，并设置并发与扫描量上限。

只看引擎性能，不看数据布局

• 现象：压测表现很好，上线后部分查询仍然慢。
• 根因：排序键、分区、物化视图、统计信息和数据倾斜没有按真实查询模式设计。
• 修复：先收集 Top 查询模板，再设计主键、排序键、分区、物化视图和冷热分层，用真实数据分布做回归压测。

多个引擎权限口径不一致

• 现象：同一用户在 BI 中看不到某列，在另一个 SQL 客户端却能查到。
• 根因：平台元数据、引擎内部权限和外部 catalog 没有统一发布流程。
• 修复：平台策略优先，自动生成引擎权限配置；新增引擎时先接 Catalog 适配器和策略控制器，再接执行适配器。

本地 DuckDB 分析结果无法复现到生产

• 现象：数据科学家在 Notebook 中直接读文件得到结论，生产看板复现时口径不同。
• 根因：本地分析绕过语义层、数据版本和指标口径管理。
• 修复：DuckDB 用于探索，但必须记录输入文件、湖仓快照、SQL 和指标定义；进入生产前转为受治理的数据集或指标层查询。

12.3.3 OLAP 执行结果的证据管理

OLAP 查询结果进入 DataAgent 后，就还涉及一次数据库响应。平台需要保存查询文本、参数、引擎、Catalog、快照版本、权限策略、扫描量、返回行数和结果去向。这样用户质疑某个数字时，团队能判断问题来自 SQL 生成、引擎执行、数据布局、权限裁剪还是报告解释。只保存最终表格，会让排查停在“当时查出来就是这个数”。证据管理还要覆盖结果缓存。固定看板和高频问数可以使用缓存，但缓存必须带上语义层版本、数据快照、权限上下文和过期策略。否则同一个自然语言问题可能在不同用户之间复用错误结果，或者在数据刷新后继续返回旧口径。缓存命中不是问题，问题是用户和审计系统不知道命中的是什么版本。多引擎环境下，证据管理尤其重要。Trino、StarRocks、Doris、ClickHouse、Snowflake 和 DuckDB 对 SQL 方言、权限模型和时间函数的处理并不完全一致。DataAgent 不能把“SQL 成功执行”当成最终验收，还要确认执行结果符合语义层口径和用户权限。第34章的 NL2SQL 负责生成查询，第38章的 Trace 负责保存过程，本章的 OLAP 执行契约负责把底层引擎差异收敛成可治理的结果。

多引擎路由上线后，团队要观察每类任务的真实分布。即席问数是否经常退化成明细扫描，报表查询是否绕过物化视图，低优先级任务是否挤占交互式队列，这些都能从查询日志和 Trace 中看到。发现问题后，修复点可能在语义层，也可能在路由策略或表设计。OLAP 层还要向 Agent 返回可理解的失败。超时、权限不足、扫描量超限、快照不存在和语法错误，对 Planner 来说是不同信号。只有错误类型明确，Agent 才能选择改写 SQL、请求澄清、降级到聚合指标，或把问题交给人工。最终，湖仓引擎不是被动执行 SQL 的黑盒。它是 DataAgent 的运行保护层，负责把自然语言带来的不确定性压到可管理范围内。没有这层保护，模型越会生成查询，平台越容易被错误查询拖垮。

查询执行前的预估很关键。平台可以在真正提交前估算扫描分区、读取列、Join 规模和结果行数。超过阈值的查询进入澄清、降级或审批，而非直接占用资源。预估不一定完全准确，但它能把明显失控的查询挡在执行层外。执行后的反馈也要回到 Planner。若查询因为扫描量超限失败，Planner 可以尝试缩小时间窗口；若因为权限不足失败，应请求用户换口径或申请权限；若因为引擎繁忙失败，可以排队或切换到离线引擎。错误信息越结构化，Agent 越可能采取正确恢复动作。物化视图和预聚合需要被语义层知道。很多经营问题并不需要扫明细，已有宽表或指标表就能回答。若模型只看到底层明细表，它会生成昂贵 SQL；若语义层暴露合适的指标入口，OLAP 层压力会小得多，回答也更接近业务口径。

多引擎环境还要管理一致性。同一张 Iceberg 表在不同引擎上的函数、时区、类型转换和权限实现可能有差异。一个 SQL 在 Trino 上正确，不代表在 ClickHouse 或 StarRocks 上同义。平台需要把这些差异写进引擎能力描述，并在路由时避开不兼容路径。OLAP 的生产验收可以从几个高风险问题开始：大范围扫描是否被拦截，低权限用户是否被拒绝，慢查询是否能取消，失败是否回写 Trace，重试是否会重复占用资源。通过这些问题，才说明 DataAgent 的 SQL 执行进入了受控系统。查询路由还要考虑用户意图。用户只是想知道“是否下降”，可能聚合表已经足够；用户要求“列出异常订单”，才需要明细查询。Planner 可以表达意图，语义层可以提供候选查询，OLAP 路由器再根据资源和权限决定执行路径。三者协作后，系统会少很多不必要的大查询。

资源隔离要和业务优先级绑定。管理层会议前的经营看板、普通探索式问数、离线评测批跑和开发调试，不应共享同一队列。队列隔离用于防止低优先级查询拖慢高价值流程，不是为了增加架构复杂度。Agent 自动生成 SQL 后，查询数量会增加，资源优先级更需要清楚。结果缓存也要谨慎使用。相同 SQL 在不同数据快照、用户权限和时间语义下可能代表不同答案。缓存命中前要校验数据版本、租户、权限和参数；缓存命中后，也要在回答中保留数据时间。否则系统会用旧结果快速回答新问题，速度提升了，可信度下降了。OLAP 层要给数据团队提供回放能力。某次用户投诉数字错误时，团队需要拿到当时 SQL、引擎、参数、快照、执行时间和结果 artifact。只有这些信息完整，才能判断是模型生成错了、引擎执行错了，还是数据在查询后发生了变化。缺少回放，很多数字争议会陷入口头解释。

引擎选型最后要回到工作负载。Trino 适合联邦和湖仓查询，ClickHouse 适合高并发明细分析，StarRocks 适合低延迟聚合和物化视图场景。企业往往会并存多个引擎，平台价值在于让 Agent 不直接感知复杂性，又能把每类查询送到合适位置。SQL 生成和执行之间可以加入计划审查。平台不必把模型生成的 SQL 直接送给引擎，而是先解析语法树，检查表权限、扫描范围、危险函数、笛卡尔积和导出风险。审查通过后再执行，失败时把结构化原因交给 Planner。这个步骤能把很多资源和安全问题挡在引擎前。查询结果也需要大小控制。模型可能请求返回明细，实际结果有数百万行；前端和模型都不适合接收这么大结果。执行层可以返回聚合摘要、分页 artifact 或要求用户缩小范围。结果大小控制同时保护系统，也避免模型基于过大样本做不稳定解释。OLAP 层的 SLO 要按任务定义。交互式追问需要秒级反馈，异步报告可以等待更久，评测批跑可以排队。把所有查询都要求低延迟，会导致成本过高；把所有查询都放进离线队列，又会破坏用户体验。SLO 分层能让资源和业务价值对齐。

12.4 OLAP 口径漂移与查询证据

OLAP 系统支撑 DataAgent 时，指标口径漂移会直接影响用户信任。同一个“销售额”可能因为退货处理、税费口径、渠道归属、时间分区、汇率折算变化而产生不同结果。传统 BI 场景中，用户可以通过报表说明慢慢校准；Agent 场景中，系统会把查询结果转成自然语言结论，口径差异更容易被读者当成事实冲突。平台需要把 OLAP 口径变化和查询证据绑定起来。

每次指标变更都应留下语义层版本、SQL 片段、数据快照范围、影响报表、影响 Agent 样本和生效时间。DataAgent 回答时，应能引用当时的指标版本和查询证据。若用户复盘历史问题，平台要解释“当时的结果”来自哪个口径，而不是用当前口径重新计算后覆盖历史。这样 OLAP 查询才能成为可追溯证据，而不是一次临时计算。

口径漂移复盘还要关注查询性能。为了修正指标而增加复杂 join、窗口函数或大范围扫描，可能让 Agent 延迟和成本上升。数据团队、平台团队和业务 owner 应共同评估：是否需要预聚合，是否需要新增物化视图，是否需要限制自然语言查询范围，是否需要提示用户切换到异步报告。OLAP 的工程质量，最终会体现在 Agent 回答是否稳定、可解释、可复盘。

12.5 OLAP 查询策略与语义层协同

OLAP 层不能独立决定所有查询策略。自然语言问题进入 DataAgent 后，语义层会先给出指标、维度、时间范围和候选数据集，OLAP 层再根据引擎能力、资源队列和权限策略选择执行路径。若语义层没有表达清楚指标口径，OLAP 层即使执行得很快，也可能返回错误答案；若 OLAP 层没有把资源和执行状态反馈回去，语义层也无法知道哪些问题适合改写、降级或转成异步报告。

协同的关键是让计划审查成为正式接口。一个查询计划在提交前，应包含指标版本、候选表、过滤条件、预估扫描量、目标延迟、用户权限和结果规模。语义层负责解释“这个问题应该查什么”，OLAP 层负责判断“这个计划能不能在当前资源和权限下执行”。当计划失败时，返回的原因也要结构化：缺指标、缺权限、扫描量过大、引擎不支持、数据未刷新、结果过大。Planner 拿到这些原因后，才能选择缩小时间范围、换指标入口、请求澄清或进入人工确认。

这层协同还能降低成本。很多自然语言问题看起来需要明细查询，其实只需要已经发布的指标表；很多追问看起来是新问题，其实可以复用同一快照和同一中间结果。语义层保存任务上下文，OLAP 层保存执行证据，两者配合后，系统可以少做重复扫描，也能避免为了追求即时回答而滥用高成本引擎。对早期平台来说，先把查询计划、执行证据和失败原因接成稳定接口，比接入更多 OLAP 产品更重要。

12.6 OLAP 引擎变更的回答一致性检查

OLAP 引擎变更后，要检查 DataAgent 回答一致性。把查询从 Trino 切到 StarRocks，或把明细查询改成物化视图，可能让函数语义、时区、空值处理、近似聚合和权限实现发生变化。SQL 仍然成功执行，回答里的数字却可能改变。

一致性检查应选择一组高频业务问题，同时比较旧引擎、新引擎、语义层指标和人工确认结果。若差异来自性能优化，需要说明可接受范围；若差异来自口径变化，要更新语义层版本和用户提示；若差异来自权限实现，要暂停切流。OLAP 切换的验收对象应落到用户最终看到的业务答案，不能停在引擎层。

12.7 OLAP 查询策略的灰度与回滚

OLAP 查询策略进入灰度时，变更对象通常会超过引擎本身。一次看似简单的路由调整，可能同时改变资源队列、扫描阈值、物化视图优先级、缓存命中条件、结果分页方式和失败返回码。DataAgent 依赖这些信号判断是否继续追问、是否改写 SQL、是否请求人工确认，因此查询策略发布要按照业务域、租户、指标组和任务类型逐步放量。灰度期间，平台应同时保存旧策略和新策略的执行证据，比较最终业务答案、扫描成本、延迟、失败类型、缓存复用和用户追问比例。只有这些指标稳定，才能说明策略变更没有把问题转移到 Planner、语义层或前端解释层。

回滚设计要早于灰度开始。查询策略回滚不能只恢复一段配置，因为新策略可能已经写入缓存、生成报告 artifact、改变中间结果或触发异步任务。平台需要给策略版本、语义层版本、数据快照和缓存条目建立关联。若某个指标组在灰度后出现异常，回滚应能按租户、业务域或指标范围收窄影响，而不是全平台切回旧策略。已经生成的结果也要标记策略版本，避免用户在复盘时把旧策略和新策略下的数字放在一起比较。对高风险经营指标，回滚后还应触发一组历史问题回放，确认回答内容、图表和引用证据都回到可接受状态。

OLAP 策略发布还要给业务方可读的解释。用户不需要知道引擎路由细节，但需要知道为什么同一个问题今天变慢、为什么某个明细查询被转为异步、为什么系统要求缩小时间范围。若平台只返回技术错误，用户会继续换问法，反而制造更多昂贵查询。更合适的做法是把资源限制、权限限制和数据刷新状态翻译成任务级提示，并在 Trace 中保留原始错误。这样前端给用户清楚预期，后台仍能做工程复盘。OLAP 灰度的成败，最终要看 DataAgent 是否还能给出稳定、可解释、可追溯的业务回答。

12.8 查询结果缓存的证据边界

OLAP 查询缓存能降低成本和延迟，但在 DataAgent 场景中要特别谨慎。用户追问时，系统可能复用上一轮查询结果；高峰期，平台可能返回已缓存的指标；报告生成时，中间结果可能被多个图表共享。缓存如果没有证据边界，用户看到的数字就可能脱离数据快照、权限范围和指标版本。缓存命中越高，越要解释缓存对应的事实。

缓存证据至少要包含查询语义、SQL、语义层版本、数据快照、权限上下文、生成时间、失效条件和使用场景。若用户权限发生变化，缓存不能继续复用；若指标版本变化，缓存应失效；若底层分区刷新，平台要判断缓存是否仍在可接受时间窗内。对高风险经营指标，缓存结果还应记录是否经过人工确认或报告发布。这样缓存不会把旧事实包装成新回答。

缓存策略也要区分交互和报告。交互式问数可以接受短时间缓存，以减少重复扫描；正式报告应明确绑定快照，不能因为缓存命中而丢失查询证据；探索性分析可以复用中间结果，但要在用户确认前标明草稿状态。不同任务使用同一缓存策略，会在成本和可信度之间制造隐性冲突。平台需要让 Planner 和前端知道当前结果来自实时查询、可接受缓存，还是历史 artifact。

早期可以给 OLAP 查询接口增加 cache_source 和 evidence_scope 字段。cache_source 说明结果来自实时执行、同会话缓存、跨会话缓存或历史报告；evidence_scope 说明结果绑定的数据快照、权限和指标版本。这样第12章的查询性能优化能继续服务 DataAgent 的可信回答，而不会因为追求速度破坏可复盘性。

12.9 OLAP 查询证据与缓存解释

OLAP 系统通常会引入预聚合、物化视图、结果缓存和查询改写。对普通 BI 用户来说，这些机制是性能优化；对 DataAgent 来说，它们也是证据来源的一部分。若同一个问题在不同时间得到不同结果，平台需要解释差异来自缓存过期、物化视图未刷新、查询改写、权限过滤，还是源数据变化。只保存最终数值不足以支撑复盘。

查询证据应包含执行路径。Agent 调用 OLAP 工具后，Trace 应记录逻辑 SQL、实际执行 SQL、命中的物化视图、缓存状态、数据时间、权限过滤、返回行数和关键聚合值。若结果来自缓存，系统要知道缓存生成时间和失效规则；若结果来自预聚合，系统要知道预聚合覆盖范围和刷新时间。这样报告层引用数字时，可以说明数字来自哪个数据版本。

缓存解释也要面向用户。低风险看板可以直接展示缓存时间；高风险报告需要判断缓存是否仍在允许窗口内；审批建议通常应使用最新可验证数据，或者明确进入等待状态。早期可以给 OLAP 工具返回 freshness_status、cache_source 和 evidence_ref 三类字段。这样性能优化不会削弱证据链，反而能让 Agent 更清楚地说明数字来源。

12.10 OLAP 查询层的变更防线

OLAP 查询层进入生产后，平台需要把查询模板、物化视图、指标口径、权限过滤、缓存策略、慢查询样本和回滚方式放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。

这类证据应和第33章语义层、第34章 NL2SQL 和第41章成本治理连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。

常见风险包括缓存命中过期口径、物化视图刷新失败、权限过滤只在前端执行、查询优化改变结果顺序。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。

数据平台团队应把 OLAP 变更纳入样本回放，确认速度提升没有牺牲口径和权限。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。

落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。

本章小结

湖仓表格式解决数据资产开放性，OLAP 引擎解决分析查询性能、并发、服务化和成本问题。Databricks 和 Snowflake 更偏平台化与托管数仓；Doris、StarRocks、ClickHouse 更偏实时 OLAP；Trino 更偏联邦查询；DuckDB 更偏本地分析。多引擎协同依赖统一 Catalog、权限、审计、成本预算、查询状态和失败恢复，而非产品数量。DataAgent 接入湖仓时必须走受控查询接口，不能绕过平台策略直接生成任意 SQL 访问底层引擎。mini-platform 的 route_query 只做早期规则路由，真实生产还需要执行适配器、权限同步和查询观测。

参考文献

DuckDB. (n.d.). Documentation.

Trino. (n.d.). Documentation.

ClickHouse. (n.d.). Documentation.

Apache Doris. (n.d.). Documentation.

第13章 流式计算与实时数据

实时数据的价值来自业务动作，而非“越快越好”。并非所有场景都需要实时，但风控、监控、实时大屏这类任务一旦延迟就失去价值。事件时间、窗口、状态、Exactly-once 语义和实时特征，构成判断实时链路价值、代价和 Agent 消费方式的基础。经营、风控和运维场景经常要求系统在分钟级甚至秒级内响应。支付失败率突然升高、库存快速扣减、设备温度异常、工单积压加剧时，DataAgent 如果只能查询昨日批量快照，就无法支持告警、拦截和调度。实时链路是否值得投入，取决于这些低延迟动作是否真实存在，以及实时结果能否带着质量状态和回放能力提供给上层 Agent。实时数据并不天然比离线数据高级。它的价值取决于业务动作是否真的需要低延迟。风控拦截、库存预警、设备异常和运维告警错过时间窗口后，答案再准确也失去意义；月度经营复盘则更关心口径稳定和可审计。把所有链路都改成实时，只会增加状态管理、乱序处理和运维成本。

Agent 引入后，实时链路还多了一层消费语义。一个告警事件被 DataAgent 读取后，系统可能生成解释、触发工单、推荐动作，甚至调用外部工具。此时实时结果必须带着事件时间、窗口范围、质量状态和回放入口。否则模型只能看到“当前指标异常”，却不知道这是迟到数据、重复事件、窗口未闭合，还是确实发生了业务波动。企业做实时链路时，最容易漏掉的是恢复路径。Flink 任务重启、Kafka 积压、状态后端膨胀、下游写入失败，都会改变 Agent 看到的数据。若平台没有把这些状态暴露给上层，Agent 可能在数据追赶期间给出错误判断。实时系统要在低延迟下仍能解释、回放和修复；只追求更低延迟，会把恢复和责任问题留给上层 Agent。

13.1 实时数据在企业 Agent 场景中的价值与边界

一家多业务线企业的数据平台已经具备批量采集、湖仓存储和联机分析处理（Online Analytical Processing，OLAP）查询能力。门店交易、会员行为、仓储履约、设备质检、客服工单每天都会进入湖仓，并通过经营看板和 DataAgent 被业务人员消费。问题是，有些业务动作不能等到第二天。运营负责人会问 DataAgent：“最近 10 分钟哪些门店支付失败率异常？”供应链团队需要在缺货风险出现前触发补货提醒；风控团队希望在异常下单行为扩散前拦截；客服主管需要看到正在堆积的高优先级工单。此类问题的共同点不在数据量，而在事件正在发生，业务动作也要跟上。

图13-1：离线数据与实时数据服务不同业务动作。来源：本书自绘。Alt text：左侧离线数据对应报表、复盘等可容忍延迟的动作，右侧实时数据对应告警、风控、大屏等延迟敏感动作，对比两类数据服务的业务场景。

图 13-1 表明，离线链路服务复盘、归因和正式报表，实时链路服务告警、拦截、调度和上下文注入。若问题是“上季度华东区毛利率为什么下降”，批量湖仓和 OLAP 引擎更合适，因为它需要稳定口径、完整数据和可追溯快照。若问题是“过去 5 分钟支付失败率是否超过正常波动”，实时链路更合适，因为它需要在数据尚未沉淀成正式报表前先发现异常。

实时链路不等于把所有数据都变快。它引入常驻计算资源、状态存储、消息积压、乱序事件、重复消费、迟到数据和复杂恢复流程。对企业 Agent 平台而言，实时数据的价值是让 Agent 在正确时间拿到足够新的上下文，同时在数据迟到、重复、修正时仍能解释结果的可靠性。

图13-2：实时链路立项判断路径。来源：本书自绘。Alt text：决策树从"延迟是否影响业务价值"出发，分出需要实时、准实时、离线足够三条路径，提醒先确认实时必要性再投入。

图 13-2 给出立项边界。只有业务动作依赖分钟级或秒级数据时，实时链路才值得承担额外复杂度；一旦涉及审计和追溯，实时结果还要能回放和对账。一家多业务线企业的支付异常告警可以使用实时链路，但月度财务结算仍应以湖仓快照和人工确认后的正式口径为准。实时能力进入 Agent 平台后，边界会发生四类变化：

• DataAgent 不只能查询历史表，还能读取实时指标和实时事件上下文。
• 业务 Agent 不只能回答“发生了什么”，还可以触发告警、派单、冻结、降级、补货等动作。
• 可观测性平台不只能事后分析慢查询和失败任务，还要实时发现数据延迟、消费堆积和状态膨胀。
• 数据治理不只能管表和字段，还要管事件契约、延迟承诺、重放窗口和异常修正流程。

13.1.1 流批一体视角：事件流、变更日志、实时宽表与实时指标

流式计算围绕持续到达的事件构建。一个事件可以是支付成功、库存扣减、设备温度异常、用户点击、工单创建，也可以是数据库行变更。这些事件随业务运行进入消息系统，由流式作业持续消费、计算和写出。

图13-3：从原始事件到实时数据产品的端到端链路。来源：本书自绘。Alt text：横向链路依次为事件采集、事件总线、流计算、状态/窗口、实时存储、数据服务，箭头表示原始事件逐步加工为可消费的实时数据产品。

图 13-3 中有三条边界需要明确。消息系统和计算系统职责不同：Kafka 这类系统提供事件日志、分区、有序追加和消费进度管理，但不会自动完成窗口聚合、状态关联和迟到修正。流式计算和 OLAP 查询职责也不同：Flink 或 Spark Structured Streaming 负责持续处理新事件，Doris、StarRocks、ClickHouse 等 OLAP 引擎负责让用户以低延迟查询当前结果。实时数据产品更不能按临时脚本治理；只要结果会被 DataAgent 或业务系统用于决策，就要有事件契约、延迟目标、血缘、权限和回放策略。

流批一体是一种平台视角，不是单独产品名。同一份业务事实可以以事件流进入实时链路，也可以以明细表进入湖仓；同一套指标口径可以生成实时窗口结果，也可以被离线链路复算对账。对一家多业务线企业而言，支付成功率可以每 5 分钟生成实时结果用于告警，也可以每天用湖仓明细重算，解释实时结果和最终结果之间的差异。

表13-1：事件流、变更日志、实时宽表、实时指标四个概念的定义与区别。来源：本书整理。

实时链路的风险通常集中在五处：把实时默认看成优于离线；认为 Kafka 或流引擎提供 Exactly-once 后，业务就不会重复；把 Watermark 当成所有迟到数据的解决方案；让实时链路替代湖仓；单纯追求更低延迟。实时提升的是动作时效，不一定提升数据质量。系统一致性语义只覆盖特定边界，业务侧仍需 event_id、幂等写入和对账。Watermark 是进度估计，不是完整性承诺。审计、回放、训练样本、长期归因仍依赖湖仓。秒级链路通常需要更多常驻资源、更复杂状态管理和更严格值班；若业务只要求 10 分钟内发现异常，把延迟压到 1 秒往往是成本浪费。

13.2 流式基础设施：Kafka、Flink、Spark Streaming 与存储系统协作

在企业 Agent 平台中，流式计算层位于数据采集之后、湖仓和服务层之前。它接收 第10章 产生的业务事件和 CDC 日志，把结果写入第11章的湖仓表、第12章的 OLAP 服务层、第15章的元数据与血缘系统，以及面向 DataAgent 的实时上下文服务。

图13-4：流式计算层在企业 Agent 平台中的位置。来源：本书自绘。Alt text：分层图中流式计算层位于数据采集之上、实时存储与特征服务之下，向 Agent 平台提供实时特征与告警，标出其"实时供给"职责。

图 13-4 说明，实时层不能简化成 Kafka 集群或 Flink 集群。它从事件契约、消息总线、状态计算延伸到服务层和治理系统。这里有两条输出路径容易混淆。第一条是事实沉淀路径：原始事件或清洗后的明细写入湖仓，用于审计、回放、训练样本和长期分析。第二条是服务路径：窗口指标、实时宽表、告警事件和在线特征写入 OLAP、缓存或业务系统，用于分钟级查询和动作触发。成熟平台不会只保留服务路径，否则当 DataAgent 被追问“这次告警依据哪些事件”时，平台无法回溯。实时链路的组件可以按入口、处理、状态、输出、治理五类划分。

表13-2：事件总线、流计算引擎等流式组件的职责、输入输出与失败模式。来源：本书整理。

框架和存储系统的选择要服务于业务场景，不能按流行程度堆叠。Kafka 适合做可重放事件日志，不适合承载复杂窗口计算。Flink 适合复杂事件时间、低延迟状态计算和精细恢复，不适合由缺少流式运维能力的团队直接大规模铺开。Spark Structured Streaming 适合已有 Spark 和湖仓基础的团队做微批增量处理，不适合把所有秒级拦截场景都压到微批模型。Kafka Streams 适合嵌入单个服务做局部流处理，不适合作为全公司统一实时数据平台。替代方案包括 Pulsar、Redpanda、RisingWave、Materialize、ksqlDB 以及云厂商托管流处理服务；选择时要看事件保留、状态恢复、Schema 治理、权限、成本和团队运维能力。

批处理、微批与连续流

表13-3：批处理与流处理在延迟、成本、对账上的取舍。来源：本书整理。

Flink、Spark Structured Streaming 与 Kafka Streams

表13-4：Flink、Spark Streaming 等流计算引擎的优势、代价与适用场景。来源：本书整理。

13.2.1 时间语义：事件时间、处理时间、Watermark、窗口与迟到数据

实时系统通常同时处理三类时间。事件时间是业务事件实际发生的时间，例如支付完成时间。摄入时间是事件进入消息系统或流式平台的时间。处理时间是计算任务处理这条事件的时间。

图13-5：事件时间、摄入时间、处理时间和 Watermark。来源：本书自绘。Alt text：时间轴上标出同一事件的三个时间戳（发生、进入系统、被处理）及其间隔，Watermark 线表示允许的乱序边界，超过即视为迟到。

图 13-5 强调实时计算应按业务发生时间计算指标，不能简单按系统处理时间计算。以支付成功率为例，如果按照处理时间统计，10:00:03 发生但 10:00:11 才处理的支付事件会被计入后续窗口，导致 10:00:00 到 10:05:00 的成功率偏低。对于“刚才是否异常”的告警，这种偏差会直接触发误报。

企业事件天然可能乱序。门店网络抖动、移动端离线缓存、数据库日志同步延迟、跨地域链路抖动都会导致较早发生的事件较晚到达。Watermark 的作用是给系统一个进度判断：大多数事件已经推进到某个事件时间，窗口可以先输出。它不是“该时间之前所有事件都已到达”的证明。Watermark 策略需要与业务契约绑定。例如，一家多业务线企业门店支付事件一般 30 秒内到达，但山区门店偶发 5 分钟延迟。若 Watermark 只允许 30 秒迟到，实时大屏更快，但山区门店会频繁被漏算；若允许 10 分钟迟到，结果更完整，但告警变慢。平台应让业务明确选择：实时告警用快速但可修正的结果，财务口径用延迟更高但更完整的结果。

速度优先与完整性优先

表13-5：速度优先与正确性优先两种时间语义策略的取舍。来源：本书整理。

实时指标服务响应不宜只返回一个数值。DataAgent 如果只拿到 0.982，就无法判断这个数值是否是完整窗口、是否包含迟到修正、是否正在回放。

{
  "metric": "payment_success_rate",
  "window_start": "2026-06-11T10:00:00+08:00",
  "window_end": "2026-06-11T10:05:00+08:00",
  "value": 0.982,
  "watermark": "2026-06-11T10:04:30+08:00",
  "is_final": false,
  "late_event_policy": "update_until_10_minutes",
  "source_lag_seconds": 35,
  "lineage": {
    "source_topics": ["payment-events-v3"],
    "job": "payment-success-rate-stream",
    "contract": "payment.succeeded.v3"
  }
}

示例 13-1：实时指标服务响应示例

这是生产工程示例。is_final=false 告诉 DataAgent 当前窗口还可能被迟到事件修正，回答时应标注“截至当前 Watermark”。

13.2.2 状态管理：Checkpoint、Savepoint、Exactly-once 与端到端一致性

窗口聚合、去重、流式关联、规则匹配都需要状态。状态可以理解为流式作业的记忆：当前窗口累加到多少、哪些 event_id 已处理、某个订单是否已经支付、某个用户最近 5 分钟是否连续失败。

图13-6：状态、Checkpoint、Savepoint 与失败恢复关系。来源：本书自绘。Alt text：流作业的运行状态周期性写出 Checkpoint，手动触发 Savepoint，故障时从最近 Checkpoint 恢复、升级时从 Savepoint 恢复，箭头标出两类恢复路径。

图 13-6 说明，状态使实时计算能够跨事件记忆上下文，也让故障恢复变得复杂。Checkpoint 用于把状态和输入位置保存成一致性快照。作业失败后，系统从最近一次成功 Checkpoint 恢复状态，并从对应输入位置继续消费。没有 Checkpoint，作业只能从最新位置丢数据，或从很早位置重放并产生大量重复结果。

Savepoint 是有计划运维动作中的可迁移快照，常用于版本升级、状态结构迁移、并行度调整和跨集群迁移。Checkpoint 关注自动故障恢复，Savepoint 关注可控变更。二者都不是业务对账的替代品，因为它们解释的是计算状态，不解释业务事实是否完整。Exactly-once 通常需要源、计算状态和下游共同参与。输入要可重放，状态要可恢复，下游要支持事务提交或幂等写入。缺任何一环，都只能获得较弱的一致性。在业务层，还要补充幂等键和对账。例如告警系统如果不支持事务提交，就应使用 alert_id = rule_id + store_id + window_start 做幂等写入，避免作业恢复后重复派单。湖仓写入如果支持事务提交，也要确保每次提交包含唯一批次号，避免回放产生重复文件。以下事件契约示例展示实时链路的入口边界。它是生产工程示例，不是 mini-platform 配置。

{
  "event_id": "evt_20260611_000001",
  "event_type": "payment.succeeded",
  "schema_version": "v3",
  "event_time": "2026-06-11T10:00:03+08:00",
  "source": "pos-payment",
  "partition_key": "store_1024",
  "trace_id": "trace_8f4a",
  "producer_time": "2026-06-11T10:00:04+08:00",
  "payload": {
    "order_id": "ord_10086",
    "store_id": "store_1024",
    "amount": 128.50,
    "payment_method": "card",
    "status": "succeeded"
  },
  "quality": {
    "is_replay": false,
    "source_lag_ms": 1000
  },
  "governance": {
    "owner": "payment-platform",
    "pii_tags": ["customer_id"],
    "retention_days": 30
  }
}

示例 13-2：实时事件契约示例

事件信封的重点，是把业务时间、生产时间、Schema 版本、分区键、质量标记和治理属性放到同一处。图 13-6 展示这些字段如何包住业务 payload，让下游既能处理事件，也能解释事件的治理状态。

图13-7：事件契约贯穿实时链路。来源：本书自绘。Alt text：同一份事件契约（字段、类型、时间戳、主键）从生产者、事件总线到流计算、消费端逐段标注，表示契约在全链路一致约束。

图 13-7 说明，事件契约不能停留在文档附件里。生产、消费、治理和审计都依赖它。一个合格的事件契约至少要回答八个问题：这是什么事件；事件唯一键是什么；事件时间字段是什么；分区键是什么；Schema 版本如何演进；哪些字段属于个人可识别信息（Personally Identifiable Information，PII）；事件保留多久；迟到、补发、撤销、修正事件如何表达。

13.2.3 Stream-table Duality：从实时流到可查询表与物化视图

流与表的二象性（Stream-table Duality）提供了理解实时数据产品的关键模型。追加事件流记录发生过什么，表表达某个时刻的当前状态；变更日志则连接二者。订单创建、支付成功、取消订单是一组事件；把它们按 order_id 折叠后，就得到订单当前状态表；再按门店和 5 分钟窗口聚合，就得到可查询的实时指标表。

图13-8：事件流、变更日志、动态表和物化视图的关系。来源：本书自绘。Alt text：事件流经聚合变为变更日志，变更日志物化为动态表，动态表再生成物化视图，箭头双向标注流与表可相互转换（流表二象性）。

图 13-8 提醒平台团队，DataAgent 不应该直接消费原始事件流来回答经营问题。它应该访问受控的实时表、物化视图或指标服务，并同时获得窗口、Watermark、是否最终、口径和血缘。原始流用于计算、回放和审计；可查询表用于服务 DataAgent、BI 和业务系统。

实时结果写入湖仓还是服务层

表13-6：直接写 OLAP 与保留事件流两种实时服务方式的取舍。来源：本书整理。

13.2.4 面向 Agent 的实时特征、实时告警与实时上下文注入

Agent 使用实时数据有三类常见方式。第一类是实时特征，例如用户最近 10 分钟失败支付次数、门店最近 5 分钟订单量、设备最近 1 分钟温度斜率。这类数据通常进入特征服务或上下文服务，供风控 Agent、调度 Agent 或 DataAgent 查询。第二类是实时告警，例如支付失败率异常、仓储积压、设备异常、客服工单激增。这类数据通常进入告警系统或工作流系统，并由 Agent 解释原因、推荐动作或生成工单。第三类是实时上下文注入，例如 DataAgent 回答“现在是否异常”时，把当前窗口指标、Watermark、最近事件样本和历史基线一起注入推理上下文。

实时上下文注入需要设置访问边界。Agent 不应无限制读取 Kafka 主题，因为原始事件中可能包含敏感字段、坏数据、重复事件和未稳定口径。更合适的模式是由实时指标服务、实时特征服务或实时上下文服务提供受控接口，返回值包含数据新鲜度、是否最终、血缘和脱敏状态。这样 DataAgent 的回答可以区分“已确认事实”“当前窗口初步结果”和“正在回放修正的结果”。

实时数据直供 Agent 还是经过服务层

表13-7：Agent 直读事件流与经特征服务两种实时供给方式的取舍。来源：本书整理。

下面这段伪代码目的在于说明受控上下文接口应怎样表达实时语义，给出某个框架的标准实现只是手段之一。读代码时重点看输入边界、时间语义和返回对象的责任分配。

# 示例：实时上下文服务响应，不包含真实凭证
context:
  subject: store_1024
  window: 5m
  generated_at: "2026-06-11T10:05:12+08:00"
  watermark: "2026-06-11T10:04:30+08:00"
  freshness_seconds: 42
  finality: provisional
signals:
  payment_success_rate:
    value: 0.982
    baseline: 0.995
    severity: warning
  order_count:
    value: 438
    baseline: 410
    severity: normal
governance:
  lineage:
    - payment-events-v3
    - payment-success-rate-stream
  pii_status: masked
  allowed_actions:
    - explain
    - create_ticket
    - request_human_review

示例 13-3：实时上下文服务响应示例

该接口让 Agent 能说明“数据截至哪个 Watermark”“结果是否最终”“允许触发哪些动作”。有了这些语义，前端和审批链才能区分临时结果、最终结果和禁止自动动作的结果。

13.2.5 实时链路的恢复窗口与补偿策略

背压表示下游处理速度低于上游输入速度。它可能发生在消息消费、计算算子、状态读写、网络 Shuffle、下游写入任意一环。

图13-9：背压沿实时链路向上游传播并触发恢复动作。来源：本书自绘。Alt text：下游消费变慢后，背压信号沿链路逐级向上游传递，箭头标出各级触发的限流、扩容、缓冲等恢复动作。

图 13-9 说明，下游写入变慢会逐步影响计算、消费和 Kafka 堆积，最终表现为链路延迟上升。背压通常由容量、状态和下游服务共同触发，不能只按单个组件“任务慢”处理。排查时除了看作业是否运行，还要看输入速率、输出速率、消费延迟、Watermark 延迟、Checkpoint 耗时、状态大小和下游写入耗时。

表13-8：背压、重复消费、状态膨胀等流式失败模式的检测与恢复策略。来源：本书整理。

回放修正是实时链路的基础能力。一家多业务线企业如果发现某批门店支付事件的 event_time 被上游写错，只在服务层手工改指标会留下审计缺口。更稳妥的流程是隔离坏数据、修正事件或生成补偿事件、从保留日志或湖仓明细回放指定时间范围、对比新旧结果、更新服务层，并把修正原因写入审计记录。否则 DataAgent 后续回答无法解释为什么同一窗口指标发生变化。

13.3 实时链路的部署、监控与治理

生产方案需要说明部署拓扑、发布流程、监控指标、扩缩容策略和治理边界。图 13-8 展示实时链路进入企业平台时必须交代的几个面，不能被简化成某个框架的标准架构图。

图13-10：实时作业发布与治理流程。来源：本书自绘。Alt text：发布流程含版本打包、Savepoint 触发、状态兼容校验、灰度、回滚等步骤，箭头表示流作业升级须经状态兼容检查而非直接替换。

图 13-10 表明，流式作业不应直接从开发环境发布到生产。预发回放和影子对比是发现口径偏差的关键步骤；Savepoint 是有状态作业升级和回滚的关键控制点；灰度发布后要观察延迟、结果质量和 Checkpoint 指标，而非只看进程存活。

下面这份配置示例展示的是实时作业进入生产后的配置形态，并不绑定 mini-platform。真正要看的，是时间语义、状态保留和治理开关如何被显式写进配置。

# 示例：实时作业配置，不包含真实凭证
job:
  name: payment-success-rate-stream
  owner: payment-data-team
  version: 2026.06.11
  mode: streaming

source:
  type: kafka
  topic: payment-events-v3
  consumer_group: payment-success-rate
  start_from: committed-offset
  event_time_field: event_time
  partition_key: store_id

watermark:
  max_out_of_orderness: 2m
  allowed_lateness: 10m
  late_event_output: payment-events-late

state:
  checkpoint_interval: 30s
  checkpoint_timeout: 10m
  state_retention: 2h
  savepoint_required_for_upgrade: true

sink:
  lakehouse_table: dwd.payment_events_rt
  olap_table: ads.payment_success_rate_5m
  idempotent_key: window_start,window_end,store_id

governance:
  contract: payment.succeeded.v3
  pii_policy: mask_customer_id
  lineage_enabled: true
  alert_on_lag_seconds: 180

示例 13-4：实时作业配置示例

关键配置应把事件时间、Watermark、状态保留、幂等键和治理策略显式写出来。只罗列一串框架参数，后续很难判断这条实时链路究竟按什么口径在运行。

-- 伪代码：用 SQL 表达 5 分钟支付成功率窗口
CREATE TABLE payment_events (
  event_id STRING,
  store_id STRING,
  status STRING,
  event_time TIMESTAMP(3),
  WATERMARK FOR event_time AS event_time - INTERVAL '2' MINUTE
);

CREATE TABLE payment_success_rate_5m (
  window_start TIMESTAMP(3),
  window_end TIMESTAMP(3),
  store_id STRING,
  success_rate DOUBLE,
  total_count BIGINT,
  updated_at TIMESTAMP(3),
  PRIMARY KEY (window_start, window_end, store_id) NOT ENFORCED
);

INSERT INTO payment_success_rate_5m
SELECT
  TUMBLE_START(event_time, INTERVAL '5' MINUTE) AS window_start,
  TUMBLE_END(event_time, INTERVAL '5' MINUTE) AS window_end,
  store_id,
  SUM(CASE WHEN status = 'succeeded' THEN 1 ELSE 0 END) * 1.0 / COUNT(*) AS success_rate,
  COUNT(*) AS total_count,
  CURRENT_TIMESTAMP AS updated_at
FROM payment_events
GROUP BY TUMBLE(event_time, INTERVAL '5' MINUTE), store_id;

示例 13-5：窗口指标伪代码

这段只表达计算意图：按事件时间生成 5 分钟窗口，用主键保证下游可幂等更新。生产部署至少应满足以下要求。

表13-9：实时链路在发布、监控、扩缩容、治理各领域的必备能力。来源：本书整理。

图13-11：实时链路延迟诊断路径。来源：本书自绘。Alt text：诊断流程从端到端延迟升高出发，沿生产、总线、消费、状态算子逐段排查，箭头指向各段对应的延迟来源与处理动作。

图 13-11 是值班人员排查延迟的最小路径。消费延迟升高不一定意味着 Kafka 有问题；Watermark 延迟升高可能是迟到事件增加；Checkpoint 变慢通常指向状态膨胀或下游提交慢；下游写入耗时上升会反向制造背压。

图13-12：实时系统的技术取舍需要同时看延迟、正确性、成本和治理。来源：本书自绘。Alt text：以延迟、正确性、成本、治理为四轴的雷达图，标注"无法四者同时最优"，说明实时方案选择是四维平衡而非单点优化。

图 13-12 把技术取舍汇总到四个维度。低延迟通常引入状态和运维复杂度；可解释正确性通常要求实时与离线双轨；成本治理要求限制常驻资源和事件保留；治理能力要求统一契约、血缘、权限和审计。平台负责人应在立项评审中写清这些约束，避免等事故发生后再补流程。

13.3.1 实时链路进入 Agent 的发布条件

实时链路接入 Agent 前，先确认它服务的是告警、拦截、调度、在线上下文等低延迟动作，而非为了让页面“看起来实时”。关键事件应带有 event_id、event_time、schema_version、partition_key、owner、retention 和 PII 标记；关键指标要说明使用事件时间、摄入时间还是处理时间，并给出 Watermark 和允许迟到范围。运行层还要守住恢复边界。下游写入需要幂等键或事务提交，告警和工单不能因为重放重复触发；去重、窗口、关联状态要有保留时间和清理策略；Checkpoint 要定义间隔、超时、存储位置、失败阈值，并定期演练恢复；升级、迁移、扩缩容前应生成 Savepoint，并确认新版本状态兼容。

治理层要保证可解释和可追溯。关键实时指标应有离线对账链路，能够解释实时值和最终值差异；平台要保留足够长的原始事件日志或湖仓明细，支持按时间范围重算；消费延迟、Watermark 延迟、下游写入耗时、状态大小和 Checkpoint 耗时都要进入监控。当下游不可用时，系统应能暂停告警、降级指标、缓冲写入或切换到只写湖仓。还要明确权限、成本和运营责任。DataAgent 和业务系统只能访问授权后的实时结果，敏感字段按策略脱敏；每个实时结果都应追溯到源 topic、作业版本、事件契约和输出表；常驻计算、消息保留、状态存储和回放成本要有预算和归因；核心实时链路还需要明确 Owner、告警接收人、升级路径和事故复盘模板。

用处理时间做支付成功率，促销高峰误报

• 现象：促销开始后，部分门店 5 分钟支付成功率突然下降，风控 Agent 自动触发支付通道降级。
• 根因：事件按处理时间进入窗口。高峰期消费堆积后，早发生的成功支付被计入后续窗口，当前窗口成功率被低估。
• 修复：支付指标改为事件时间窗口，设置 2 分钟乱序容忍和 10 分钟迟到修正；DataAgent 回答中展示 Watermark 和是否最终。

Kafka 分区键使用城市导致核心城市单分区过热

• 现象：全国大部分门店指标正常，上海和深圳门店指标持续延迟。
• 根因：分区键选择 city_id，大城市流量集中在少数分区，单个流式任务成为瓶颈。
• 修复：分区键改为 store_id，热点门店再做二级拆分；窗口聚合先局部汇总再全局合并。

去重状态没有过期时间，作业恢复越来越慢

• 现象：作业运行数周后 Checkpoint 时间从几十秒增长到十几分钟，失败恢复超过业务可接受时间。
• 根因：去重状态保存所有历史 event_id，没有按事件时间或业务周期清理。
• 修复：按事件保留期设置状态过期时间；超过迟到窗口的 event_id 进入离线对账，不再占用实时状态。

告警 Sink 不幂等，恢复后重复派单

• 现象：一次集群重启后，同一门店的支付异常工单被创建多次。
• 根因：流式作业从 Checkpoint 恢复后重放部分结果，告警系统只提供追加写入，没有基于业务键去重。
• 修复：设计 alert_id = rule_id + store_id + window_start，告警系统改为按 alert_id upsert；恢复后只更新已有告警状态。

只保留实时聚合结果，无法解释 DataAgent 回答

• 现象：业务质疑“为什么说某门店近 10 分钟异常”，DataAgent 只能给出聚合值，无法列出支撑事件。
• 根因：原始事件保留期过短，清洗明细没有写入湖仓；实时服务层成为唯一事实来源。
• 修复：所有关键事件同时写入湖仓明细，实时聚合结果保存血缘字段；DataAgent 回答可附上窗口、事件数量和样例事件引用。

13.3.2 实时上下文的使用边界

实时数据很容易让 Agent 看起来更聪明，但它也会放大不确定性。事件可能迟到，状态可能还在修正，窗口结果可能只是暂时值。DataAgent 使用实时上下文时，应明确区分“实时信号”“已发布指标”和“可审计事实”。实时信号可以用于提醒和候选解释，已发布指标可以用于问数和看板，可审计事实才适合进入正式报告。实时上下文还要带上时间语义。回答里不能只说“当前库存异常”，还要说明数据截至时间、窗口大小、延迟水位和是否包含迟到修正。对于经营分析场景，实时信号可以提示“华东订单取消率在最近 30 分钟升高”，但不能直接替代日结指标。对用户来说，实时性的价值来自及时发现问题；可信度来自清楚知道这个信号还处于哪个确认阶段。

这条边界也影响第32章的 DataAgent 产品形态。问数和报告更依赖稳定指标，实时告警和任务工作台可以使用实时信号触发后续分析。平台应把实时链路的状态写入 Trace，让第38章的观测系统能解释一次回答使用的是流式窗口、实时物化视图还是已发布快照。实时链路上线后，平台要同时看业务延迟和系统延迟。事件从源系统产生到 Kafka、Flink、存储和 Agent 可见，每一段都可能积压。只看端到端延迟平均值不够，还要看 P95、迟到比例、丢弃比例和补偿次数。Exactly-once、窗口和状态这些概念最终都要落到业务含义上。重复扣减库存、漏掉一次支付失败、把迟到事件计入错误日期，都会直接改变用户看到的结论。实时计算的复杂度只有在这些后果存在时才值得承担。

对于 Agent 平台，实时数据应以产品形式交付：字段定义、窗口语义、更新时间、质量状态、回放范围和消费权限都要清楚。模型可以基于它解释异常，但不能替代实时链路本身的状态管理。实时链路还要把“未完成”状态表达出来。窗口尚未闭合、迟到数据仍在进入、状态任务正在恢复、下游存储写入积压，这些状态对用户结论都有影响。若 Agent 只看到当前聚合值，就可能在数据尚未稳定时解释趋势。平台可以把窗口状态和水位线暴露给语义层，让回答带上必要保留。业务动作决定实时精度。风控拦截可能需要秒级判断，库存补货可能只需要 5 分钟粒度，管理看板可能接受 15 分钟延迟。把这些场景都按最低延迟建设，会增加资源和运维负担。团队应先写清楚动作时限，再选择 Kafka、Flink、Spark Streaming 或增量批。

实时特征进入 Agent 时还要处理权限。异常设备状态、客户行为、交易风险和门店销售都可能包含敏感信息。实时链路速度快，不代表可以绕过数据权限。每个实时数据产品仍要声明可见范围、脱敏规则和审计要求，否则 Agent 会把高速链路变成高速泄露通道。回放能力是实时系统的安全垫。模型基于实时数据做出错误解释后，团队需要回放同一时间窗口的事件，确认是数据迟到、计算错误、规则不当，还是模型归因错误。没有回放，只能看当前状态，很多问题会随着窗口推进而消失，复盘也失去证据。实时链路成熟后，Agent 可以更主动地参与运营：发现异常后解释可能原因，生成临时报告，提醒责任人检查。前提是它能看到数据状态和质量信号，而非只看到一个不断变化的数字。

实时数据产品还要定义迟到数据策略。迟到事件是补入历史窗口、进入修正流，还是只记录异常，会直接影响指标解释。Agent 如果不知道窗口后来被修正，可能把早期不完整结果写进报告。平台可以把修正次数和最终确认时间暴露出来，让用户理解实时结果和最终口径之间的差异。状态存储是实时链路的核心风险点。窗口聚合、去重、会话分析和实时特征都依赖状态；状态膨胀、TTL 设置错误或恢复失败，都会改变结果。运维看板需要显示状态大小、checkpoint 耗时、恢复耗时和失败次数。Agent 消费实时结果时，这些状态健康度也应该成为质量信号。事件 schema 要稳定演进。新增字段、修改枚举、调整事件时间含义，都会影响下游计算。实时链路比离线批处理更难人工修复，因为错误会快速传播到看板、告警和 Agent 回答。schema registry、兼容性检查和灰度消费，是实时数据进入 Agent 平台前的基础要求。

实时告警和 Agent 解释之间也要有分工。告警系统负责快速发现异常，Agent 可以补充解释、关联历史和生成处理建议。若让 Agent 直接决定是否告警，模型不确定性会进入关键监控链路；若只给 Agent 最终告警结果，又会缺少分析上下文。更稳的方式是规则和流计算先产生可审计事件，再由 Agent 解释。实时链路的复盘要包含业务误报和漏报。系统延迟很低但误报太多，业务团队会关闭通知；系统解释很流畅但漏掉关键异常，信任会迅速下降。实时 DataAgent 的质量要同时看延迟、准确性、告警疲劳和人工处理结果。实时链路还要处理模型解释的时效性。用户看到异常时，Agent 给出的解释可能只适用于当前窗口；几分钟后迟到数据补齐，解释就可能变化。平台可以在回答中标注数据窗口和确认状态，并在最终窗口闭合后刷新结论。这样用户知道哪些判断是临时运营信号，哪些可以进入正式报告。

实时特征用于自动动作时，需要更严格门禁。比如风控拦截、设备停机或库存调拨，不能只依赖模型解释。实时计算先产生规则化信号，策略系统再决定动作，Agent 可以辅助说明原因和生成处理建议。把模型放在解释层，比放在直接控制层更容易审计。实时数据的成本也要被看见。低延迟通常意味着更高资源、状态存储和运维成本。平台应定期复盘哪些实时链路真正触发了业务动作，哪些只是为了看起来及时。没有动作价值的实时链路，可以降级到分钟级或批处理，把资源留给真正需要低延迟的场景。与离线口径的对齐也很重要。实时指标为了速度可能使用近似口径，离线指标用于最终结算。Agent 在回答时要区分“实时监控口径”和“财务确认口径”，避免把运营预警当作正式结论。口径差异写进元数据后，模型才能正确表达。

实时链路还要给运维留出人工接管入口。任务积压、状态恢复失败或源系统异常时，值班人员需要能暂停消费、切换备用流、标记数据不可信，并通知上层 Agent 暂停强结论。没有接管入口，实时系统会在异常时继续把不稳定数据送给模型。实时数据还应明确最终确认口径。运营看板可以先展示临时窗口，财务和合规报告只能引用确认后的结果。Agent 在生成不同用途的答案时，应根据用途选择实时值、修正值或最终值，而非把最新值默认当成最终事实。实时任务还要和告警值班制度衔接。谁接收异常、谁确认数据状态、谁决定降级或暂停上层 Agent，都要提前写清。否则实时系统发现问题很快，组织响应却很慢，最终用户仍然会拿到不可靠结论。

13.4 湖仓数据发布与 Agent 消费边界

湖仓数据进入 Agent 平台前，需要明确发布边界。原始层、清洗层、宽表层、特征层、语义层并不适合被同样暴露给 Agent。原始层适合溯源和排障，不能直接进入问答；清洗层适合工程复用，但业务口径可能还没有稳定；语义层和经过验证的数据产品更适合作为 DataAgent 的默认入口。若 Agent 可以任意访问湖仓里的所有表，生成的回答会混杂临时字段、实验口径和未审核数据。

发布边界要通过数据产品说明来表达。每个可被 Agent 消费的数据集应说明 owner、刷新频率、字段含义、权限标签、质量阈值、适用任务、不可用场景和历史变更。数据集发布后，Agent 侧应记录使用版本，而不是只记录表名。这样当报告或回答出现争议时，团队能回到具体版本复盘，而不是在湖仓里查找“当时到底用了哪张表”。

湖仓发布还要考虑撤回。某个数据集发现质量问题后，平台应能阻止新的 Agent 查询，标记已生成产物，通知下游 owner，并在修复后重新跑代表样本。撤回机制比简单删除更重要，因为已经生成的报告、Trace 和评测样本仍然引用旧数据。数据发布和撤回都有证据，湖仓才能成为 Agent 平台的可信底座。

13.5 数据质量告警进入 Agent 运行链路

数据质量告警如果只停留在数据平台后台，Agent 仍可能继续使用有问题的数据。字段缺失、重复行、异常波动、主键漂移、维度映射错误和延迟回补，都会影响问答、报告和审批建议。平台需要把质量状态写入 Agent 上下文，让 Runtime 在回答前知道哪些数据可以使用，哪些需要标注，哪些必须拒绝。

质量告警要有业务严重度。一个低频字段缺失可能只影响明细导出，一个核心指标异常会影响报告结论，一个权限标签质量失败会带来安全风险。告警不能只按技术规则排序，还要说明受影响任务、数据域、租户和可降级方式。DataAgent 可以据此决定展示旧数据、等待修复、请求人工确认，或切换到只读解释。

早期可以让数据质量平台输出统一状态：正常、观察中、受影响、禁止使用。每个状态绑定证据、影响范围、owner 和预计恢复时间。Agent 工具调用时读取状态，报告层引用状态，Trace 保存状态快照。这样数据质量会进入任务执行链路，而不是成为事故后才被查到的后台告警。

13.6 实时数据链路的延迟承诺

实时数据链路进入生产后，平台需要把事件时间、处理时间、水位线、乱序窗口、失败重放、下游消费者和告警阈值放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。

这类证据应和第11章数据接入、第14章质量治理和第42章 SLO连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。

常见风险包括延迟指标只看平台内部、乱序数据改变结果、消费者不知道当前数据是否完整。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。

实时链路应说明数据可用性的条件，让 Agent 在数据未完整时能够降级解释。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。

落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。

本章小结

实时链路服务低延迟动作，但不能替代离线湖仓。关键业务指标应同时保留实时结果和可回放事实，否则团队很难解释某个窗口结果是否完整、能否对账、是否已经被后续修正覆盖。事件时间、Watermark、Checkpoint 和状态管理决定了流式结果的可靠性。Exactly-once 也是链路级系统语义，依赖可重放输入、可恢复状态以及事务或幂等下游；它不能替代业务幂等和对账。排查延迟时，背压通常是最有用的容量信号，需要同时看输入、Watermark、状态、Checkpoint 和下游写入。DataAgent 使用实时数据时，回答里必须带上时间窗口、Watermark、是否最终、来源血缘和延迟信息。没有这些上下文，模型很容易把未完成窗口当作最终事实，或者把实时近似值写成可审计结论。

参考文献

Apache Flink. (n.d.). Documentation.

Apache Kafka. (n.d.). Documentation.

Apache Spark. (n.d.). Structured Streaming Programming Guide.

Akidau, T. et al. (2015). The Dataflow Model. VLDB.

第14章 数据编排与质量

数据编排与质量控制把脚本集合变成可运营的数据链路。零散的定时脚本能跑通一次，但在依赖变化、任务失败、口径漂移时很难保持可信。任务依赖、调度恢复、质量门禁、数据产品发布和 mini-platform 的实现方式共同决定数据能否稳定交付给 DataAgent。编排引擎负责用 DAG 管理依赖与重试，质量门禁负责在数据进入下游前拦截问题。DataAgent 引用的数据通常不是单表直接产生的结果。订单事实表、履约宽表、库存快照、区域维表和指标汇总要按依赖顺序产出，中间任何一个任务失败、延迟或质量异常，都会让上层回答失真。编排、质量门禁和事故恢复要一起工作，才能把“脚本能跑”推进到“数据产品可信”。

数据编排看起来像调度脚本，实际承担的是数据产品的交付责任。一个 DataAgent 回答得是否可信，取决于上游事实表、维表、指标表和质量规则是否按依赖顺序产出。某个中间表延迟、某个任务重跑漏了分区、某条质量规则被临时关闭，都会让最终回答偏离真实业务。许多团队早期用 cron 和脚本拼出数据链路。任务少的时候足够，业务扩展后就会出现依赖不清、失败没人接、补数靠手工、质量检查写在脚本里的问题。Agent 把这些问题放大了，因为用户会即时追问，系统也可能把分析结果写入报告或流程。数据链路的不可解释，会变成 Agent 的不可解释。编排与质量应一起设计。DAG 说明数据如何产生，质量规则说明数据何时可以被使用，告警和恢复说明失败后谁来处理。只有任务状态、质量状态和血缘一起进入平台，DataAgent 才能判断某个指标是否适合回答，前端也才能在数据延迟时给出明确提示。

14.1 从任务脚本到可信数据产品：编排与质量的共同目标

一家多业务线企业的数据平台已经能采集业务事件、沉淀湖仓表、提供 OLAP 查询和实时指标。新的问题随之出现：DataAgent 回答“昨日华东区履约延迟为何上升”时，依赖的订单事实表、履约宽表、库存快照和区域维表要按正确顺序产出；其中任一环节延迟、失败或质量异常，都会让回答变成不可信的猜测。早期团队通常用定时脚本解决问题。每天凌晨执行抽取脚本，随后执行清洗脚本，再执行指标汇总脚本。脚本能跑起来，但它无法清楚表达三件事：上游资产是否已经准备好；产出数据是否满足质量规则；失败后应该重试、跳过、回滚还是回填。数据编排与质量治理的共同目标，是把一组脆弱脚本变成有依赖、有状态、有质量门禁、有责任人、有恢复路径的数据产品生产线。

图14-1：编排不是孤立的调度器，质量也不是事后报表。来源：本书自绘。Alt text：左侧"传统观念"中调度器与质量报表彼此分离，右侧"数据产品观念"中编排与质量门禁嵌在同一发布流程里，对比两种组织方式。

图 14-1 表明，编排不是孤立的调度器，质量也不是事后报表。二者共同夹在数据生产和数据消费之间：编排保证资产按依赖关系被生产出来，质量门禁保证资产进入 DataAgent 之前具备最低可信度。

图14-2：脚本任务到数据产品的成功标准变化。来源：本书自绘。Alt text：左列"脚本任务"成功标准是"跑完不报错"，右列"数据产品"成功标准升级为契约满足、质量达标、可订阅、可追溯，对比成功定义的变化。

图 14-2 的关键不在于工具替换，而在于成功标准改变。脚本时代只关心“任务是否退出码为 0”；数据产品时代要同时关心“输入是否完整、依赖是否满足、口径是否正确、产出是否准时、失败是否可恢复、结果是否能被追溯”。企业 Agent 平台还会把数据结果转化为自然语言判断，质量问题会被放大成错误解释和错误动作。

14.1.1 编排边界：数据 DAG、资产依赖、业务工作流与 Agent Workflow 的区别

数据编排常被误解为“把所有流程都放进一个 DAG”。在企业 Agent 平台中，至少有四类流程需要区分。

表14-1：数据 DAG、编排、质量门禁等概念的定义与区别。来源：本书整理。

图14-3：边界清晰能降低系统耦合。来源：本书自绘。Alt text：左侧职责混杂的任务相互交叉连线、耦合高，右侧编排、转换、质量、发布各司其职、连线清晰，对比边界清晰前后的耦合度。

图 14-3 说明，边界清晰能降低系统耦合。数据 DAG 负责稳定生产，资产依赖负责解释影响范围，业务工作流负责组织处理，Agent Workflow 负责受控调用和解释。让 Agent 直接在数据 DAG 中“自由修复问题”通常会带来审计困难；让调度器承载复杂业务审批，则会让数据平台变成难以维护的业务流程引擎。一家多业务线企业的履约延迟分析可以这样划边界：数据编排负责每日生成订单履约宽表；质量门禁检查订单量、主键唯一性、字段有效性和产出延迟；DataAgent 只读取通过门禁的数据产品；当质量失败时，业务工作流创建数据事故工单，由 Owner 处理；Agent 可以解释事故影响范围，但不能绕过门禁给出正式分析。

14.1.2 调度模型：时间调度、事件触发、数据集触发与回填

编排系统要解决的第一个工程问题是“什么时候运行”。常见触发模型包括时间调度、事件触发、数据集触发和人工回填。

表14-2：时间、事件、数据集触发与回填四种调度模型的优势与适用场景。来源：本书整理。

图14-4：调度触发模型与回填治理边界。来源：本书自绘。Alt text：图中并列时间触发、事件触发、数据集触发三种模型，下方标出回填场景的特殊处理边界，说明常规调度与回填须分开治理。

图 14-4 强调两点：触发模型要与数据资产状态绑定，而非只依赖时钟；回填也不等于“把历史日期再跑一次”。它需要冻结窗口、资源限额、幂等写入、质量复检和下游影响通知。若回填直接覆盖正在被 DataAgent 查询的正式指标，用户会在同一会话中看到前后不一致的结果。

这里需要避免四类判断偏差：把任务成功等同于数据正确；认为 DAG 越细越好；认为质量检查越多越好；低估回填对当前链路的影响。任务可以成功写出空表、重复表或过期数据。过细的任务会放大调度开销和失败噪声；过粗的任务又会掩盖故障位置。没有 Owner、阈值和处理动作的检查只会制造告警疲劳。历史回填可能触发下游重算、缓存刷新和 DataAgent 引用变化，应进入变更流程。

14.2 编排工具对比：Airflow、Dagster、Prefect 与 DolphinScheduler

编排工具的差异不只在界面和语法，而在它们对“任务、资产、状态、开发体验和治理”的建模方式。表 14-1 因此按平台能力维度比较，而非按流行度或部署方式排序。

表14-3：Airflow、Dagster、Prefect 等编排工具的优势、代价与适用场景。来源：本书整理。

这些工具都不能替代数据质量体系。Airflow 能告诉平台“任务有没有运行”，不能自动证明订单金额没有异常；Dagster 能把资产建模得更清楚，也仍然需要质量规则、阈值、Owner 和失败动作；Prefect 让开发更灵活，但灵活性过高会带来流程碎片化；DolphinScheduler 对多任务可视化友好，但若缺少代码评审和资产契约，容易演变为图形化脚本堆积。

图14-5：工具选择应回到组织能力。来源：本书自绘。Alt text：以"团队工程能力"和"资产治理需求"为轴的矩阵，把 Airflow、Dagster、Prefect 等工具落入不同象限，强调选型回到组织实际能力。

图 14-5 表示工具选择应回到组织能力。若团队已经有大量 Airflow DAG，可以先补数据集状态、质量检查和事故流程；若目标是把数据资产作为平台产品经营，资产中心的建模更有价值；若应用团队需要快速编排自助任务，则需要在灵活性外加统一模板和审计。

14.2.1 转换与测试：dbt 模型、dbt tests、Great Expectations 与 Soda

编排负责“何时、按什么依赖运行”，转换与测试负责“产出什么、是否可信”。在湖仓和 OLAP 场景中，dbt 常用于把 SQL 转换逻辑工程化，dbt tests 用于表达唯一性、非空、关系完整性和自定义断言。Great Expectations 和 Soda 更偏向通用数据质量检查，适合跨数据源、跨表、跨业务规则的质量监控。

表14-4：dbt tests、Great Expectations 等转换与测试工具的优势与适用场景。来源：本书整理。

图14-6：质量门禁的最小闭环。来源：本书自绘。Alt text：环形流程，产出数据、运行质量校验、通过则发布、不通过则阻断并告警，箭头表示失败样本回流修正规则，构成质量门禁闭环。

图 14-6 展示的是质量门禁的最小流程。质量失败后的动作需要预先定义：阻断发布、继续发布但标记风险、回退到上一版本、降级到离线快照、创建事故工单或请求人工确认。没有动作的质量规则只是噪声。

如果把质量问题当成平台事件来处理，就需要一份稳定的事件契约。下面这个例子展示的是面向 DataAgent 的最小表达方式。

{
  "asset_id": "ads.fulfillment_delay_daily",
  "run_id": "run_20260611_020000",
  "partition": "dt=2026-06-10",
  "status": "blocked",
  "severity": "critical",
  "checks": [
    {
      "name": "order_id_unique",
      "dimension": "uniqueness",
      "expected": "duplicate_count = 0",
      "actual": "duplicate_count = 184",
      "action": "block_publish"
    },
    {
      "name": "row_count_range",
      "dimension": "completeness",
      "expected": "between 950000 and 1200000",
      "actual": "612340",
      "action": "keep_previous_partition"
    }
  ],
  "owner": "fulfillment-data-team",
  "lineage": {
    "upstream_assets": ["dwd.orders_daily", "dim.store_region"],
    "downstream_consumers": ["DataAgent", "operations_dashboard"]
  }
}

示例 14-1：质量事件契约示例

这是生产工程示例。它让 DataAgent 和看板知道某个分区是否可用、为什么被阻断、临时应该使用哪种降级策略。

14.2.2 数据质量维度：完整性、唯一性、准确性、及时性、一致性与有效性

质量规则要按维度组织，否则容易堆成无法维护的检查清单。表 14-3 将规则拆成完整性、唯一性、范围、及时性和业务一致性，方便后续映射到质量事件和恢复动作。

表14-5：完整性、唯一性、准确性等数据质量维度的关注问题与示例规则。来源：本书整理。

质量规则还要区分硬门禁和软告警。硬门禁阻断下游发布，用于主键唯一、核心字段非空、金额合法、权限分类等不可妥协条件。软告警允许产出继续进入下游，但要带风险标记，用于行数轻微波动、延迟接近阈值、历史分布变化等需要观察的问题。

硬门禁、软告警与旁路隔离

表14-6：硬门禁与软告警两种质量拦截策略的取舍。来源：本书整理。

14.2.3 数据事故治理：SLA、告警、血缘定位、责任人、修复与复盘

数据事故不是“任务失败”的同义词。任务成功但产出错误数据、质量门禁误放行、回填覆盖正式分区、DataAgent 引用了未发布资产，都属于数据事故。事故治理需要定义发现、分级、止血、定位、修复、验证、复盘和规则沉淀的完整流程。

图14-7：数据事故处理的止血与修复路径。来源：本书自绘。Alt text：事故流程分两段，先止血（下游降级、回退旧版本、告警），后修复（定位根因、回填重算、复盘），箭头表示先恢复可用性再追根因。

图 14-7 的核心是先止血再修复。对 DataAgent 而言，止血动作通常包括隐藏问题资产、返回质量状态、降级到上一可用分区、禁止触发动作型建议。若平台只通知数据工程师而不通知 DataAgent 服务层，用户仍可能持续获得错误回答。

表14-7：上游未就绪、数据漂移等数据事故的检测方式与恢复策略。来源：本书整理。

14.2.4 Agent 反馈链路：从用户质疑、回答置信度到质量规则沉淀

企业 Agent 平台多了一个传统数据平台没有的质量信号：用户会直接质疑回答。用户可能问“这个数是不是太低了”“为什么和看板不一样”“你引用的是哪个日期的数据”。这些反馈不应只当作客服问题处理，它们应进入数据质量治理流程。

图14-8：从事故复盘到规则沉淀的反馈链路。来源：本书自绘。Alt text：链路从一次数据事故出发，经复盘提炼出新的质量规则，沉淀进门禁，下次同类问题被提前拦截，箭头构成持续改进的反馈环。

图 14-8 展示了一条可落地的反馈链路。低置信度回答、用户质疑、人工纠错和引用缺失都可以成为规则候选，但不能直接自动变成阻断规则。候选规则要经过样本验证、误报评估、Owner 审核和灰度启用。否则平台会把个别异常反馈扩大成大面积误阻断。

DataAgent 的质量响应也应显式表达数据状态。例如，当核心分区被阻断时，回答不应伪装成正常结果，而应说明“当前使用上一可用分区，今日分区因唯一性检查失败未发布”。这类回答需要编排系统、质量系统和元数据系统共同提供状态。

14.3 质量链路的状态、告警与恢复

本节给出一组生产工程示例，重点是接口、状态和操作流程自洽。编排平台至少要维护四类状态：任务运行状态、资产可用状态、质量检查状态和发布状态。任务成功不等于资产可用；质量通过也不等于已发布；发布成功也不代表所有下游缓存已刷新。

图14-9：把“写入临时分区”和“切换正式版本”拆开。来源：本书自绘。Alt text：发布分两步，先写入临时分区并校验，再原子切换正式版本指针，箭头表示校验通过才切换，避免半成品数据直接对外可见。

图 14-9 把“写入临时分区”和“切换正式版本”拆开。这样质量失败时，坏数据不会覆盖线上资产；质量通过后，发布动作可以成为一个可审计的版本切换。DataAgent 只读取正式版本和明确允许的降级版本。

下面这份 YAML 同时放进编排信息和质量配置，目的是让读者看到两类配置怎样落在同一份资产定义里。真正上线时，也应尽量把这两个维度放在同一条治理链上管理。

# 示例：数据资产编排与质量配置，不包含真实凭证
asset:
  id: ads.fulfillment_delay_daily
  owner: fulfillment-data-team
  schedule: "0 6 * * *"
  partition_key: dt
  publish_mode: versioned_partition

dependencies:
  - asset_id: dwd.orders_daily
    freshness: 2h
  - asset_id: dim.store_region
    freshness: 24h

quality_gates:
  hard:
    - name: order_id_unique
      dimension: uniqueness
      expression: duplicate_count(order_id) = 0
      on_failure: block_publish
    - name: required_columns_not_null
      dimension: completeness
      columns: [order_id, store_id, promised_at, delivered_at]
      on_failure: block_publish
  soft:
    - name: row_count_anomaly
      dimension: completeness
      expression: row_count within historical_band(weekday, 0.2)
      on_failure: publish_with_warning

fallback:
  strategy: keep_previous_partition
  max_age: 2d

notifications:
  severity: critical
  channels: [data-incident-queue]

示例 14-2：资产编排与质量配置示例

这段 YAML 不对应某个工具的专有语法，而是表达生产系统需要保存的关键字段：依赖、新鲜度、门禁、失败动作、降级策略和通知路径。以下伪代码展示发布动作如何避免坏数据覆盖正式分区。

# 伪代码：质量门禁通过后再切换正式版本
def publish_asset(run):
    write_temp_partition(run.asset_id, run.partition, run.output)
    quality_result = run_quality_checks(run.asset_id, run.partition)

    if quality_result.has_blocking_failure:
        mark_asset_state(run.asset_id, run.partition, "blocked", quality_result)
        keep_previous_version(run.asset_id)
        notify_owner(run.asset_id, quality_result)
        return "blocked"

    version = commit_versioned_partition(run.asset_id, run.partition)
    mark_asset_state(run.asset_id, run.partition, "published", quality_result)
    refresh_downstream_cache(run.asset_id, version)
    return "published"

示例 14-3：质量发布伪代码

核心思想是先写临时结果，再检查，通过后切换版本；失败时保留旧版本并暴露质量状态。失败恢复需要区分重试、回填和重算。重试面向瞬时故障，回填面向缺失历史窗口，重算面向逻辑或口径错误。三者不能共用同一按钮。

图14-10：重试、回填与重算的恢复决策路径。来源：本书自绘。Alt text：决策树按"是瞬时失败、上游缺数据还是逻辑变更"分出重试、回填、重算三条恢复路径，帮助选择合适的恢复动作。

图 14-10 是运维 Runbook 的核心。瞬时网络故障可以自动重试；源数据缺失需要等待或回填；业务口径错误则要走变更和重算流程。平台如果把所有失败都配置为自动重试，会在 Schema 不兼容、质量失败或权限错误时制造更多无效运行。

14.3.1 质量规则怎样进入生产链路

质量规则进入生产链路前，评审对象不应只是规则数量，而应是规则能否控制数据发布。核心资产、视图、指标和特征都要有资产 ID、Owner、SLA、分区策略和下游消费者；调度系统需要区分任务依赖和资产依赖，DataAgent 只消费资产可用状态。规则覆盖要贴近业务风险。完整性、唯一性、准确性、及时性、一致性和有效性都要有核心规则；每条规则都有严重级别、失败动作、降级策略和 Owner。发布时先写临时分区或影子版本，质量通过后再切换正式版本。回填和事故处理也属于门禁范围。历史回填要定义窗口、资源限额、幂等写入、质量复检和下游通知；告警要有分级、去重、抑制、升级路径和确认记录；质量事故要能冻结下游发布、定位血缘、修复、复检和复盘。Agent 集成层还要验证资产状态、质量状态、新鲜度和降级版本能被 DataAgent 读取。调度并发、回填资源、质量扫描频率和历史数据保留要有预算；发布、阻断、回填、重算和规则变更都要留下审计记录。

任务成功但订单事实表为空，DataAgent 正常回答了错误结论

• 现象：运营团队询问昨日履约延迟，DataAgent 回答“无明显延迟”，但实际是订单事实表上游采集失败，产出为空表。
• 根因：调度器只检查任务退出状态，没有对行数、分区新鲜度和上游资产状态做质量门禁。
• 修复：核心资产增加行数波动、分区新鲜度和非空检查；质量失败时阻断发布并让 DataAgent 返回“数据不可用”状态。

回填历史分区刷新线上缓存，用户看到指标跳变

• 现象：数据团队回填上月履约口径时，经营看板和 DataAgent 的当前指标短时间内出现跳变。
• 根因：回填任务复用了正式发布流程，未区分历史影子分区和线上分区，也没有通知下游缓存刷新策略。
• 修复：回填先写影子版本，通过质量复检和差异报告后再人工切换；当前窗口缓存与历史回填缓存隔离。

促销日行数暴涨触发质量误报，核心日报被阻断

• 现象：大促当天订单量超过历史阈值，质量系统判断为异常并阻断发布。
• 根因：行数规则只按过去 7 天均值计算，没有引入业务日历、促销标记和星期效应。
• 修复：把业务日历纳入阈值模型；对促销期采用单独基线；硬门禁仅保留不可妥协规则，波动类规则改为软告警。

质量规则没人认领，告警持续数周无人处理

• 现象：某个维表有效性告警每天触发，但既没有阻断，也没有修复。
• 根因：规则没有 Owner，告警没有升级路径，质量平台只记录失败次数。
• 修复：规则绑定资产 Owner；超过确认时限自动升级；长期误报规则关闭、调整或转为观察。

Agent 用户反馈没有进入质量体系，同类错误反复出现

• 现象：多名业务人员反馈“门店区域口径和看板不同”，但 DataAgent 一周后仍给出同类错误回答。
• 根因：用户反馈只进入产品客服队列，没有沉淀为数据质量规则或语义口径检查。
• 修复：建立 DataAgent 反馈队列，按资产和字段聚合质疑样本；经 Owner 审核后新增区域映射一致性规则。

14.3.2 质量状态在 Agent 链路中的传播

数据质量状态不能只留在调度系统里。DataAgent 查询前需要知道资产是否已发布、是否阻断、是否处于回填、是否只有影子版本、是否存在软告警。查询后，报告层也需要知道结果是否来自降级数据。若质量状态没有进入 Agent 链路，模型会把不稳定数据包装成确定结论，用户很难发现问题。质量状态可以分成四类传播。第一类是阻断状态，核心资产未通过门禁时，DataAgent 应拒答或提示数据不可用。第二类是降级状态，数据可用于探索，但不能用于正式报告。第三类是观察状态，规则有告警但不影响主要结论，回答中可以标注限制。第四类是正常状态，结果可以进入下游分析和报告。不同状态对应不同产品行为，而非只在后台显示红黄绿灯。

用户反馈也应进入质量传播链。业务用户指出某个结果异常时，平台要把反馈关联到资产、字段、指标和 Run，而非只记录一条客服工单。经 Owner 确认后，这条反馈可以转成质量规则、语义层修正或评测样本。这样 DataAgent 的使用过程会反向提升数据质量，而非不断暴露同一类问题。质量门禁的价值在于提前拦截，而非事后生成报告。空值率异常、主键重复、分区缺失、指标波动过大，若已经进入下游宽表，Agent 很难在查询时识别。门禁把问题挡在数据产品入口，能减少后续解释成本。编排系统还要保存恢复证据。一次补数改了哪些分区、跳过了哪些失败文件、哪些下游任务被重跑、哪些报告需要刷新，都应该有记录。没有这些记录，业务问“这个数什么时候修好”时，团队只能靠人肉沟通。

对 Agent 平台来说，编排结果应暴露为可消费状态。某个指标今天未通过质量检查，Agent 可以拒绝回答或标注风险；某个任务正在补数，Agent 可以延后生成报告。这样的交互比给出一个错误但流畅的答案更可靠。编排系统还要区分技术成功和业务可用。一个 SQL 任务返回 0 行可能是正常结果，也可能是上游分区缺失；一个任务耗时变短可能是优化生效，也可能是没有读到数据。质量规则需要结合业务预期，而非只看任务是否退出码为 0。告警设计也要减少噪声。所有失败都发到同一个群，久了没人处理；只告警最终宽表，又会错过关键上游问题。更好的方式是按数据产品分责任人，按影响范围分级，并在告警里给出上游失败、下游影响和建议动作。这样业务团队知道问题是否影响今天的 Agent 回答。

补数流程要和 Agent 产物联动。数据修复后，哪些缓存要失效，哪些报告要刷新，哪些评测样本要重跑，哪些用户需要通知，都不能靠人工记忆。编排系统记录补数范围后，平台可以触发下游刷新，避免用户继续看到旧结论。质量规则本身也要版本化。阈值调整、异常检测方法更换、字段规则放宽，都会改变数据产品是否可用。若规则变化没有记录，后续复盘无法判断某天的异常是数据改善了，还是门禁变松了。当编排和质量进入平台后，DataAgent 会获得一种重要能力：在数据不可信时停止。停止回答是系统保护业务的表现，不应被简单归为失败。比起给出错误答案，明确说明数据产品未通过质量门禁更符合企业使用场景。

DAG 设计要反映数据产品边界。把所有任务放进一张大图，调度看起来集中，失败影响范围却难以判断；把任务拆得太散，又会让依赖和补数复杂。通常可以按数据产品、业务域和 SLA 划分 DAG，让每个 DAG 有明确负责人、输入、输出和质量门禁。重试策略不能只按技术错误设计。网络抖动可以自动重试，源数据缺失需要等待或告警，质量异常需要隔离，业务口径变化需要人工确认。若所有失败都重试三次，系统会延迟暴露真实问题；若所有失败都立即告警，团队会被噪声淹没。编排系统要根据失败类型选择动作。质量检查要覆盖分布变化。行数、空值和主键只是基础，很多业务问题体现在指标突然波动、类别比例变化、金额单位异常或日期分布偏移。DataAgent 会基于这些数据做解释，质量规则越贴近业务，回答越可靠。规则可以先从高价值指标开始，不必一次覆盖所有字段。

数据产品发布需要验收人。工程团队可以确认任务运行，业务负责人要确认口径和可用性，平台团队要确认状态能被 Agent 消费。没有验收人，数据产品容易停留在“表已经产出”，但上层系统不知道是否可以放心使用。质量事故复盘应沉淀为规则。一次库存分区缺失、一次金额单位错误、一次维表延迟，都可以转成新的检查或告警。编排与质量体系的成熟，来自这些事故不断转化为自动控制，而非依赖团队记住教训。编排系统还应把 SLA 暴露给 Agent。某个数据产品约定每天 8 点可用，当前 8 点 30 仍未产出，Agent 就应该知道这是异常；另一个产品只承诺中午前可用，早上查询为空不一定是故障。SLA 进入元数据后，回答可以更准确地解释数据状态。

质量门禁要支持临时豁免，但豁免必须可追踪。月末关账、供应商延迟或历史补数时，业务可能允许某些质量规则短期放宽。平台应记录豁免原因、负责人、到期时间和影响范围。没有到期时间的豁免，会让质量规则逐渐失效。编排结果还可以反哺评测。DataAgent 评测失败时，如果对应数据产品当天未通过质量门禁，失败不应完全归咎于模型。评测系统读取数据状态后，可以区分模型退化和数据异常。这样质量链路和模型评测才不会互相误伤。

14.4 数据质量样本与 Agent 失败回写

数据质量治理接入 Agent 后，质量样本要从真实失败中来。传统数据质量规则往往关注空值、重复、范围和延迟，Agent 场景还会暴露新的质量问题：字段名能被模型理解但业务含义不清，枚举值相近导致筛选错误，时间粒度和指标口径不匹配，维表缺少别名，异常值被模型解释成业务变化。若这些问题没有回写到数据质量体系，Agent 会反复在同类问题上失败。

失败回写应包含用户问题、生成查询、实际结果、人工修正、错误字段、质量规则和修复状态。一个 DataAgent 查询失败后，团队要能判断是模型生成错了 SQL，还是数据本身缺少质量约束。若字段别名导致错误，就补 metadata；若维表缺少映射，就补数据规则；若异常值合理但需要解释，就补业务注释；若数据延迟导致误判，就补刷新状态提示。质量样本越贴近任务，规则就越能服务 Agent。

数据质量复盘还要有优先级。并非所有规则都需要早期覆盖，优先处理会影响外部输出、高风险决策、核心指标和多业务复用的数据。低风险探索性数据可以先提示不稳定，不直接进入正式报告。这样质量治理不会变成无边界的规则工程，而会围绕 Agent 生产任务逐步加固。

14.5 质量规则的业务解释

数据质量规则需要能被业务解释。空值率、唯一性、范围校验、延迟阈值这些规则对数据团队很清楚，但业务用户看到的是“为什么 Agent 不回答”“为什么报告延迟”“为什么指标被标记异常”。若规则只停留在技术告警里，前端和报告无法给出可信解释，用户会把质量拦截理解成系统故障。

每条高风险质量规则都应有业务说明。比如“近 3 小时订单分区未刷新”对应“今日实时销售额可能低估”；“客户主数据重复”对应“客户归属分析可能重复计数”；“币种为空”对应“跨区域收入不可汇总”。这些说明可以进入 DataAgent 的失败提示、报告注释和人工复核材料。质量规则越能被业务理解，Agent 越容易在异常时保持信任。

质量解释还要有责任人。数据 owner 负责修数据，业务 owner 负责确认影响，平台负责把异常传递给 Agent 和用户界面。没有责任人的规则只会制造告警噪声。早期可以先为核心指标和高风险字段补业务解释，随着失败样本增加再扩展规则库。

14.6 数据质量规则的变更回放

数据质量规则变更后，要回放受影响的 Agent 样本。阈值调整、空值规则、主键唯一性、枚举范围、延迟告警和异常检测逻辑，都会改变 DataAgent 对数据可信度的判断。若规则变松，系统可能把低质量数据解释成业务事实；若规则变严，系统可能频繁拒绝可用数据。质量规则本身也需要版本治理。

变更回放应记录旧规则、新规则、影响表、影响指标、历史失败样本、当前通过率和人工裁定。对于经营报表和自动报告场景，还要检查报告中的质量提示是否随规则变化更新。质量规则不能只存在于调度系统或数据测试脚本里，它要进入语义层和 Trace，让 Agent 知道数据是否适合回答当前问题。

早期可以先对核心数据产品建立质量规则台账。每条规则有 owner、适用表、业务解释、最近修改时间和回滚方式。线上争议出现时，团队能判断是数据真的异常、规则误报、规则漏报，还是 Agent 没有正确使用质量信号。这样数据质量会成为智能链路的一部分，而不是数据团队内部告警。

14.7 质量规则与编排状态的联合复盘

数据质量问题进入 Agent 链路后，不能只看规则是否通过。编排状态同样重要：任务是否按时开始，依赖是否等待过久，重跑是否触发下游更新，失败是否被正确标记，告警是否到达 owner。一个指标回答出错，可能是质量规则漏检，也可能是上游任务延迟、回填未完成、下游缓存没有刷新或 DataAgent 使用了旧分区。质量规则和编排状态要放在同一份复盘材料里。

联合复盘应围绕业务任务展开。比如经营分析报告中的销售额异常，复盘时不只检查销售表的空值率和主键唯一性，还要检查数据采集任务、清洗任务、汇总任务、指标发布任务和语义层刷新是否按预期完成。若质量规则通过但任务状态异常，Agent 应提示数据正在刷新或使用上一版数据；若任务状态正常但质量规则失败，Agent 应停止生成确定结论，并给出可解释的降级结果。

早期可以为核心数据产品建立联合复盘模板。模板记录 DAG run、资产版本、质量规则、告警 owner、下游 Agent、受影响 artifact 和恢复动作。这样第14章的数据质量不再停留在表级检查，而能进入第34章查询执行、第36章报告生成和第38章 Trace 的运行链路。数据编排的价值也会从“任务跑完”提升到“业务证据可信”。

14.8 编排事故的用户可见降级

数据编排事故发生时，Agent 平台要决定用户看到什么。上游任务延迟、质量规则失败、回填未完成、调度重试和指标发布暂停，都会让数据处在“暂时不可用”或“只能有限使用”的状态。若 DataAgent 继续给出确定结论，用户会把系统当成可信数据入口；若系统只返回技术错误，用户又无法判断是否可以等待、换问题或查看上一版结果。降级设计要把数据生产状态翻译成用户能理解的回答边界。

用户可见降级可以按任务类型处理。同步问数遇到最新分区延迟时，可以返回上一版数据并说明截止时间；经营报告遇到质量规则失败时，可以暂停发布并附上受影响指标；自动归因遇到上游缺表时，应停止推断并保留等待队列；低风险趋势分析可以使用降级样本，但必须把不完整数据标记进 artifact。不同任务对时效性和准确性的要求不同，不能用同一种错误页覆盖所有场景。

降级还需要和 Runtime 状态绑定。数据不可用时，Run 不能简单标记为 failed 或 succeeded，而应保留等待、降级完成、人工复核、数据刷新后重跑等状态线索。Trace 中要记录触发降级的数据资产、质量规则、调度状态和用户可见文案。这样后续复盘能够确认用户是否被正确告知，也能让第42章的 SLO 把“系统可用”拆成计算可用、数据可用和回答可信。

早期平台可以先为高频数据产品准备三类降级文案：数据延迟、质量失败和权限裁剪。文案不需要暴露内部 DAG 细节，但要说明当前回答使用的数据版本、受影响范围和后续动作。这样编排和质量系统产生的状态不会停留在内部告警，而会进入 Agent 的交互体验和审计证据。对企业级 DataAgent 来说，知道何时不回答、如何解释等待和怎样恢复，同样属于数据工程能力。

14.9 数据契约争议的裁定流程

数据契约上线后，争议通常来自边界样本。业务团队认为字段含义已经说明，数据团队认为数据符合 schema，Agent 团队却发现模型在真实问题里产生错误解释。此时争议不应停留在“谁的定义正确”。平台需要把争议样本固定下来，检查字段定义、源表口径、转换逻辑、权限标签、历史数据和用户问题是否共同支持当前契约。

裁定流程要保留证据。每个争议样本应包含用户问题、涉及字段、当前契约、实际数据片段、下游工具结果、模型解释、人工裁定和修改建议。若裁定结果是字段定义不清，需要更新契约文档和语义层；若是源数据异常，需要进入质量修复；若是 Agent 解释过度，需要修 Prompt 或输出校验；若是业务口径存在多个版本，需要业务 owner 指定适用范围。

早期可以把数据契约争议接入发布流程。争议未关闭时，高风险指标不进入自动报告；裁定完成后，样本进入回归集。这样数据契约不会只是一份 schema 文件，而会成为业务、数据和 Agent 团队共同维护的事实协议。

14.10 数据质量事故的跨层复盘

数据质量进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把指标版本、异常样本、校验规则、责任人、影响报表和修复时间记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第33章语义层、第34章 NL2SQL 和第36章报告生成相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括源表延迟被解释成业务变化、空值处理改变口径、异常被缓存进入报告。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

数据质量复盘应把工程修复和业务解释分开记录。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

14.11 质量规则的业务版本管理

数据质量规则会随业务变化。缺货、退款、渠道迁移、组织调整和指标重命名，都可能让原来的异常阈值失效。若规则只写在校验任务里，业务方很难知道某次异常是数据错误还是规则过期。平台应给质量规则建立业务版本，记录适用范围、阈值来源、审批人、开始时间和废止条件。

业务版本还能帮助 Agent 解释结果。同一个指标在规则变更前后出现差异时，DataAgent 应能说明当前使用哪一版质量规则，报告生成层也应避免把规则变化解释成业务变化。对于高影响指标，规则变更应触发样本回放和用户通知，确保旧报告、缓存和评测样本不会继续使用过期判断。

早期可以先为核心经营指标建立质量规则版本。每次规则变化都记录原因、影响字段、影响报表、回放样本和回滚方式。这样质量治理会从后台校验任务进入平台证据体系，支撑后续问数、报告和事故复盘。

本章小结

数据编排还涉及让脚本按时运行，还要让数据产品按依赖、状态、质量和版本被可靠生产。任务 DAG、资产依赖、业务工作流和 Agent Workflow 应分层治理；混在一起会让权限、审计和恢复边界变得模糊。数据质量规则要包含维度、阈值、严重级别、失败动作和 Owner。没有动作的规则只会制造告警噪声。DataAgent 只能消费通过门禁或明确降级的数据资产，并在回答中暴露质量状态和新鲜度。回填、重试和重算是三类不同恢复动作。它们都需要版本化发布、质量复检和下游通知，否则 Agent 很容易引用正在修复中的数据并给出看似确定的结论。

参考文献

Apache Airflow. (n.d.). Documentation.

Dagster. (n.d.). Documentation.

Prefect. (n.d.). Documentation.

Great Expectations. (n.d.). Documentation.

Soda. (n.d.). Documentation.

第15章 元数据、血缘、契约与指标

DataAgent 要回答“这个数从哪来、口径是什么、能不能信”，不能靠模型临场猜测。它需要数据底座提前给出四类材料：元数据说明资产和字段含义，血缘说明数据从哪里来，数据契约约束上游变更，指标口径定义统一的计算方式。这些材料共同组成数据控制面，并进入问数、分析和审计流程。业务用户问“本月 GMV 为什么下降”，DataAgent 选中了 sales_amount 字段并给出结论。复盘时数据团队发现，管理层口径里的 GMV 应使用支付成功金额，且要剔除内部调拨订单；sales_amount 只是订单明细里的原始销售额。模型没有“胡说”，它只是缺少可查询的字段含义、指标定义和适用边界。元数据、血缘、数据契约和指标口径要提前进入平台控制面。它们告诉 Agent 哪些资产可用、字段代表什么、指标从哪里来、上游变化会影响谁，也让一次回答在事后能够被审计和复盘。

元数据和血缘常被放在数据平台的后台页面里，到了 Agent 时代，它们会直接影响用户答案。用户问“GMV 为什么下降”，模型需要知道 GMV 的定义、字段来源、过滤条件、适用范围和更新时间。若这些信息不可查询，模型只能从表名和字段名猜测业务含义，猜对一次也无法长期依赖。企业的数据口径通常散落在指标平台、数仓文档、代码、Excel 和团队经验里。DataAgent 接入后，口径不一致会暴露得更快。销售额、收入、毛利、活跃客户、有效订单这些词在不同部门可能有不同定义；如果平台没有统一指标服务和数据契约，模型生成的 SQL 很容易使用错误字段，却仍然给出自信解释。数据控制面要把资产、字段、血缘、质量、权限和指标口径连起来。元数据说明“这是什么”，血缘说明“从哪里来”，契约说明“上游怎么变更”，指标说明“如何计算”。这四类材料共同决定 DataAgent 能否回答“这个数能不能信”。

15.1 元数据是 Agent 平台的数据控制平面

一家多业务线企业的 DataAgent 能访问湖仓表、OLAP 引擎、实时指标和质量状态。若没有元数据控制面，Agent 面对自然语言问题时会遇到四类不确定性：该用哪张表；字段是什么意思；指标口径是否一致；当前用户是否有权查看结果。传统 BI 可以通过固定看板和人工培训减少这些问题，DataAgent 则需要把这些判断自动化、可解释化、可审计化。元数据不能退化成“表的备注”。它是企业 Agent 平台的数据控制平面，负责登记资产、描述语义、连接血缘、约束契约、服务指标、执行权限和记录审计。没有这个控制面，Agent 只能把物理表名、字段名和历史查询样例拼在一起猜测，回答质量会随着数据规模增长迅速下降。

图15-1：元数据控制面横跨数据基础设施层和 Agent 消费层。来源：本书自绘。Alt text：中间一条贯穿的元数据控制面，向下连接采集、湖仓、编排等基础设施，向上连接 DataAgent、看板等消费方，表示元数据是连接两层的统一控制平面。

图 15-1 表明，元数据控制面横跨数据基础设施层和 Agent 消费层。它不直接替代湖仓或 OLAP 引擎，而是告诉 DataAgent 哪些资产可用、哪些字段可信、哪个指标可复用、回答引用来自哪里、变更会影响谁。

图15-2：元数据如何进入 Agent 推理链路。来源：本书自绘。Alt text：Agent 处理问题时从元数据服务拉取表结构、口径、权限和血缘，注入推理上下文，箭头表示元数据作为运行时输入参与每次问数。

图 15-2 展示了元数据如何进入 Agent 推理链路。用户问的是自然语言问题，但平台需要把问题映射到资产、字段、指标、权限和引用。这个过程若只依赖大语言模型记忆，很容易把“GMV”“销售额”“实收金额”混为一谈。控制面应提供可查询、可验证、可审计的上下文。

15.1.1 数据目录：搜索、标签、Owner、分级分类与资产画像

数据目录是元数据控制面的入口。它回答“有什么数据、谁负责、能不能用、适合什么问题”。一个可用于 DataAgent 的目录不应只展示表名和字段，还应包含资产类型、业务说明、Owner、分级分类、质量状态、新鲜度、使用热度、下游消费者和示例问题。

表15-1：技术元数据、业务元数据、操作元数据等概念的定义与区别。来源：本书整理。

图15-3：资产画像要服务消费行为。来源：本书自绘。Alt text：资产画像（Owner、分级、质量、热度、口径）逐项连向具体消费行为（能否信任、能否使用、找谁问），强调画像服务于消费决策而非堆元数据。

图 15-3 强调资产画像要服务消费行为。DataAgent 选择表时，除了字段匹配，还要看质量状态、刷新时间、Owner 和适用场景。例如“履约延迟”可能同时出现在明细表、日报表和实时宽表中。若用户问“昨日原因分析”，日报表和明细表更合适；若用户问“现在是否异常”，实时宽表更合适。

元数据治理中需要避免四类偏差。数据目录不能退化成表名搜索框；没有业务语义、质量状态和权限信息，目录对 Agent 价值有限。Owner 不是展示字段，它要参与告警、审批、变更和事故复盘。字段标签除了服务合规，还应帮助 Schema Linking，例如“门店”“区域”“履约时长”的业务别名。目录采集之后还要持续治理，无人维护、无人审核、无人下线的目录会快速失真。

15.1.2 端到端血缘：从采集任务、转换作业、查询语句到 Agent 回答

血缘描述数据从哪里来、经过哪些处理、影响哪些下游。对 Agent 平台而言，血缘用于工程排障，也用于回答引用、影响分析和合规审计。DataAgent 如果回答“华东区延迟上升主要来自夜间仓配”，平台应能说明这个结论使用了哪些资产、哪些分区、哪些指标口径和哪些质量状态。

图15-4：血缘要覆盖四层。来源：本书自绘。Alt text：血缘自上而下分四层，系统级、表级、字段级、指标级，箭头表示越往下定位越精细，说明完整血缘需覆盖四层而非只到表级。

图 15-4 说明，血缘要覆盖四层：源系统到湖仓、湖仓到指标、指标到 Agent 查询、Agent 查询到回答引用。只采集表级血缘不够，字段级血缘能解释某个字段变更会影响哪些指标；查询级血缘能解释某次回答用了哪些表和过滤条件；回答级血缘能把自然语言结论和底层数据证据连接起来。

血缘采集通常要接多类系统。编排系统给出任务依赖，SQL 解析给出表字段关系，数据集成系统给出源到目标映射，查询网关记录实际访问，Agent 运行时再补上工具调用和回答引用。OpenLineage 可以作为事件标准，DataHub 或 OpenMetadata 可以作为元数据平台；资产命名、Owner、标签和权限规则仍要由企业自己定义。

15.2 Data Contract：Schema、语义、SLA、权限、质量规则与变更流程

数据契约（Data Contract）是生产者和消费者之间对数据资产的正式约定。它不只约束字段 Schema，还应覆盖业务语义、刷新 SLA、质量规则、权限分类、兼容性策略和变更流程。

图15-5：Data Contract 把隐性约定显性化。来源：本书自绘。Alt text：左侧"隐性约定"是生产者口头承诺的字段与口径，右侧"数据契约"把这些约定写成 schema、SLA、质量规则等可校验条款，对比约定从隐性到显性。

图 15-5 的重点是把隐性约定显性化。一家多业务线企业如果把 delivered_at 从实际签收时间改成系统确认时间，即使字段名和类型不变，业务语义也发生了不兼容变更。没有契约，DataAgent 会继续使用旧口径解释新数据，造成难以发现的错误。

到了生产工程阶段，数据契约必须从口头约定变成可读可校验的对象。下面这个例子展示的是最小可落地的写法。

# 示例：数据契约，不包含真实凭证
contract:
  id: contract.fulfillment_delay.v2
  asset_id: ads.fulfillment_delay_daily
  owner: fulfillment-data-team
  consumers:
    - DataAgent
    - operations_dashboard

schema:
  fields:
    - name: order_id
      type: string
      required: true
      pii: false
    - name: store_id
      type: string
      required: true
      pii: false
    - name: delivered_at
      type: timestamp
      required: true
      meaning: actual_customer_receipt_time
    - name: delay_minutes
      type: integer
      required: true
      rule: delivered_at - promised_at

semantics:
  metric_refs:
    - fulfillment_delay_rate
  grain: order_id
  valid_questions:
    - "按区域分析履约延迟原因"
    - "查看昨日履约延迟趋势"

slo:
  freshness: "08:00 Asia/Shanghai daily"
  availability: "99.5% monthly"

quality:
  hard_rules:
    - order_id_unique
    - delay_minutes_non_negative
  soft_rules:
    - row_count_anomaly

governance:
  classification: internal
  retention_days: 730
  access_policy: region_level_aggregation_only

change_policy:
  compatible:
    - add_nullable_field
  incompatible:
    - remove_field
    - change_business_meaning
    - tighten_access_policy
  approval_required_from:
    - asset_owner
    - downstream_owner

示例 15-1：数据契约示例

这个契约让平台能自动判断字段变更、语义变更、SLA 违约和权限变化是否会影响 DataAgent。表 15-2 进一步把这些变化拆成不同处理方式，避免所有变更都靠人工临时判断。

表15-2：元数据采集器、血缘解析等组件的职责、输入输出与失败模式。来源：本书整理。

15.2.1 指标体系：业务口径、维度关系、时间粒度与可复用计算逻辑

指标体系是 DataAgent 查数能力的核心。没有统一指标层，Agent 只能在物理表上生成 SQL，容易出现同名不同义、分母不一致、时间粒度错误和权限绕过。

图15-6：语义层把业务问题和物理存储解耦。来源：本书自绘。Alt text：上层业务问题（如"上月华东 GMV"）经语义层映射到下层物理表与字段，中间语义层隔离两侧，使业务口径变化不直接依赖物理表结构。

图 15-6 表明，语义层把业务问题和物理存储解耦。DataAgent 问“昨日 GMV 环比变化”，应调用指标定义，而非自己临时选择订单表、支付表和退款表拼出口径。指标定义应包含名称、说明、计算公式、过滤条件、维度、粒度、时区、默认聚合方式、权限策略和废弃状态。

表15-3：直接查物理表与经指标层两种问数方式的取舍。来源：本书整理。

指标层工具的选择也要看边界。Cube 适合把指标和维度以服务方式暴露给应用和看板；MetricFlow 和 dbt Semantic Layer 适合与 SQL 模型和指标定义协同；Feast 更偏特征平台，适合在线特征查询和训练服务一致性，不适合作为经营指标口径的唯一载体。替代方案包括自研语义层、BI 工具内置指标层、湖仓引擎物化视图和 OLAP 指标宽表。

15.2.2 语义层与指标层工具：Cube、MetricFlow、dbt Semantic Layer 与 Feast

工具不是本章的中心，但工具边界必须讲清楚。表 15-3 用元数据服务、血缘服务和指标服务三个入口说明，DataAgent 应该通过受控工具拿上下文，而非直接猜表、猜字段。

表15-4：Cube、MetricFlow、dbt Semantic Layer 等语义层工具的优势与适用场景。来源：本书整理。

图15-7：经营查数与在线决策的数据服务边界。来源：本书自绘。Alt text：左侧"经营查数"走指标层、容忍秒级延迟，右侧"在线决策"走实时特征、要求毫秒级，对比两类数据服务在延迟与一致性上的不同边界。

图 15-7 的结论是，经营查数和在线决策不能混用同一抽象。DataAgent 解释经营结果时需要指标口径和维度关系；风控 Agent 判断某个用户是否异常时可能需要实时特征。二者可以共享底层事实和元数据，但接口、时效、权限和审计要求不同。

15.2.3 面向 DataAgent 的元数据能力：Schema Linking、口径解释、引用溯源与影响分析

DataAgent 使用元数据时，最先发生的是 Schema Linking。平台要把自然语言中的“华东区”“履约延迟”“昨日”“门店”映射到候选资产、字段、维度和指标。映射过程需要字段别名、业务标签、示例问题、使用热度和权限过滤共同参与。随后是口径解释。Agent 给出数值时，还要说明指标口径、过滤条件、时间范围和分母分子。例如“履约延迟率”应说明是否按订单数计算、是否剔除取消订单、承诺时间来自下单页还是履约系统。回答生成后，还要留下引用溯源。每次回答应记录使用的指标、资产版本、分区、查询语句、质量状态和权限策略。用户追问“这个结论从哪里来”时，平台能返回可读引用。影响分析也要进入同一条链路。字段、表、质量规则或指标口径变化前，平台应知道会影响哪些看板、Agent 能力、历史回答和告警规则。

图15-8：元数据进入 Agent 运行时。来源：本书自绘。Alt text：左侧"离线文档"是静态 wiki，右侧"运行时元数据"被 Agent 在每次问数时实时查询调用，对比元数据从文档变为在线服务。

图 15-8 说明，元数据需要进入 Agent 运行时，不能停留在离线文档里。每一次工具调用都应携带身份、权限、资产版本和质量状态；每一次回答都应沉淀引用和审计。

下面这份接口契约示例，展示的是 DataAgent 如何向元数据服务请求查询上下文。读这段时可以重点看请求里哪些字段决定了后续权限、口径和候选资产范围。

{
  "request_id": "req_20260611_0001",
  "user_context": {
    "user_id": "user_demo",
    "roles": ["regional_ops"],
    "region_scope": ["east"]
  },
  "question": "华东区昨日履约延迟为何上升？",
  "intent": "metric_explanation",
  "required_capabilities": [
    "asset_search",
    "metric_resolution",
    "policy_filter",
    "lineage_trace"
  ]
}

服务端响应最好一次性返回候选指标、可访问资产、口径说明、质量状态和限制。这样 Planner 在下一步做选择时，看到的内容包括“能不能查”和“应该按什么口径查”。

{
  "resolved_metrics": [
    {
      "metric_id": "fulfillment_delay_rate",
      "display_name": "履约延迟率",
      "definition": "延迟订单数 / 已履约订单数",
      "grain": "day, region",
      "allowed_dimensions": ["region", "store_type", "warehouse_type"]
    }
  ],
  "authorized_assets": [
    {
      "asset_id": "ads.fulfillment_delay_daily",
      "partition": "dt=2026-06-10",
      "quality_status": "passed",
      "freshness": "2026-06-11T07:10:00+08:00"
    }
  ],
  "policy": {
    "row_filter": "region = 'east'",
    "masking": ["customer_id"],
    "allowed_actions": ["query", "explain"]
  },
  "lineage_hint": {
    "upstream_assets": ["dwd.orders_daily", "dwd.delivery_events_daily"],
    "contract": "contract.fulfillment_delay.v2"
  }
}

示例 15-2：DataAgent 元数据上下文接口示例

这是生产工程示例。重点是把语义解析、权限过滤、质量状态和血缘提示放在同一个响应中，避免 Agent 自行猜测。

15.2.4 治理链路：权限过滤、脱敏策略、审计日志与合规留痕

Agent 平台的数据治理难点在于自然语言查询比固定看板更灵活。用户可能用模糊表达绕过固定报表边界，例如“列出华东区延迟最严重的客户明细”。如果元数据控制面不能把身份、资产、字段、指标和输出动作关联起来，权限策略很容易被绕过。

图15-9：数据治理闭环。来源：本书自绘。Alt text：环形流程，权限过滤、脱敏、审计、合规留痕四个环节首尾相连，箭头表示每次数据访问都留痕并反馈到策略，构成持续治理闭环。

图 15-9 展示了治理链路。权限不能只是查询前的一次判断，它要贯穿资产发现、指标选择、SQL 生成、结果脱敏、回答措辞和审计留痕。某些用户可以看区域聚合指标，但不能看门店明细；可以看延迟率，但不能看客户手机号；可以解释原因，但不能导出明细。

表15-5：仅数据库授权与多层治理两种权限脱敏策略的取舍。来源：本书整理。

15.3 元数据平台、血缘采集与指标服务

本节给出元数据平台、血缘采集与指标服务的生产方案，重点是接口和治理流程。图 15-4 展示这些能力怎样连成一个控制面，支撑 DataAgent 在执行前获得可信上下文。

图15-10：元数据平台、血缘与指标服务的最小架构。来源：本书自绘。Alt text：架构图含元数据存储、采集器、血缘图谱、指标服务、查询 API 五个组件，箭头标出采集、解析、对外服务的数据流向。

图 15-10 是可落地的最小架构。元数据采集不应只从湖仓 Catalog 读取表结构，还应从编排系统读取任务状态，从质量平台读取门禁结果，从查询网关读取实际访问，从 Agent 运行时读取回答引用，从权限系统读取策略决策。控制层再把这些信息统一服务给 DataAgent 和治理工具。

下面这份 YAML 只取指标定义里最关键的部分，用来说明指标口径怎样被写成可发布对象。真正工程实现可以更复杂，但这些核心字段不应再省。

# 示例：指标定义，不包含真实凭证
metric:
  id: fulfillment_delay_rate
  display_name: 履约延迟率
  description: 延迟订单数占已履约订单数的比例
  owner: fulfillment-data-team
  status: active

calculation:
  numerator: count_orders(where: delay_minutes > 0)
  denominator: count_orders(where: delivered_at is not null)
  expression: numerator / denominator
  default_time_grain: day
  timezone: Asia/Shanghai

dimensions:
  - region
  - store_type
  - warehouse_type
  - carrier_type

source:
  asset_id: ads.fulfillment_delay_daily
  required_quality_status: passed
  contract: contract.fulfillment_delay.v2

governance:
  access_policy: region_scoped
  minimum_aggregation_level: region
  pii_exposure: none

examples:
  - question: 华东区昨日履约延迟率是多少？
    intent: metric_lookup
  - question: 为什么昨日履约延迟率上升？
    intent: metric_explanation

示例 15-3：指标定义示例

这类定义让 DataAgent 可以复用指标口径，避免每次动态拼出口径。以下伪代码展示 DataAgent 查询前的元数据检查。

# 伪代码：DataAgent 查询前的元数据控制面检查
def prepare_query_context(user, question):
    candidates = metadata.search_assets_and_metrics(question)
    authorized = policy.filter(user=user, candidates=candidates)
    if not authorized:
        return deny("no_authorized_asset")

    selected = semantic_layer.resolve_metric(question, authorized)
    quality = quality_service.get_status(selected.source_asset)
    if quality.status == "blocked":
        return degrade_with_reason(selected, quality)

    lineage = lineage_service.trace(selected.source_asset)
    audit.record_intent(user=user, question=question, selected=selected)

    return {
        "metric": selected,
        "policy": authorized.policy,
        "quality": quality,
        "lineage": lineage,
    }

示例 15-4：查询前元数据检查伪代码

核心路径是搜索、授权、指标解析、质量与血缘检查，再记录审计。变更流程也需要进入控制面。

图15-11：把变更前置到发布之前。来源：本书自绘。Alt text：流程显示 schema 或口径变更先经契约校验和影响分析，确认下游无碍后才发布，箭头表示变更检查前置而非上线后救火。

图 15-11 把变更前置到发布之前。若 delay_minutes 的计算公式变更，平台应先判断影响哪些指标、看板、Agent 问题模板和历史引用，再决定是否需要灰度、重算和公告。没有影响分析的变更流程只是在事故后补救。

15.3.1 元数据发布给 Agent 的准入标准

元数据发布给 Agent 前，平台要证明它能支撑资产选择、口径解释、权限过滤和审计复盘。核心表、视图、指标、特征和实时结果都应具备资产画像、Owner、状态和下游消费者；关键业务词、字段别名、指标别名和禁用同义词要进入元数据系统。血缘与契约决定 Agent 是否能解释自己的回答。平台至少覆盖采集、转换、指标、查询和 Agent 回答引用；核心资产支持字段级血缘；核心资产还要具备 Schema、语义、SLA、质量、权限和变更策略。指标治理要落到唯一 ID、口径、维度、粒度、时区、Owner、状态和废弃流程。权限与质量要进入查询前路径。策略应支持用户身份、角色、区域范围、行列级过滤、聚合级别和脱敏；DataAgent 查询前能读取资产质量状态和新鲜度，质量 blocked 时可降级或拒绝；每次回答都记录使用资产、分区、指标、查询、质量状态和权限策略。元数据平台还要覆盖变更和成本。字段、契约、指标和权限变更前能识别下游看板、Agent 能力和告警规则；访问、拒绝、脱敏、导出、回答、审批和变更均有可检索日志；资产、指标和字段有创建、发布、废弃、下线和历史兼容策略；元数据采集频率、血缘解析深度、审计日志保留和指标缓存有成本边界。

图15-12：将上线标准压缩为六个门禁。来源：本书自绘。Alt text：纵向列出六个上线门禁，元数据登记、血缘可查、契约就位、质量达标、权限脱敏、口径统一，每项标注通过条件，构成数据资产发布前的检查项。

图 15-12 将上线标准压缩为六个门禁。只要任一门禁缺失，DataAgent 都可能在资产选择、口径解释、权限过滤或审计复盘中出现不可控风险。

同名指标散落在多个看板，DataAgent 口径前后不一致

• 现象：业务人员连续追问“销售额”和“GMV”，DataAgent 在不同问题中使用了订单金额、支付金额和扣除退款后的净额。
• 根因：指标定义分散在看板 SQL、临时宽表和分析脚本中，没有统一指标 ID、口径和废弃状态。
• 修复：建立指标注册流程；将核心指标迁入语义层；DataAgent 只能调用 active 状态指标，并在回答中显示口径。

字段类型没变但业务含义变了，契约检查没有发现

• 现象：履约延迟率突然下降，但仓配实际没有改善。
• 根因：上游把 delivered_at 从实际签收时间改为系统确认时间，字段类型仍是 timestamp，Schema 校验通过。
• 修复：数据契约加入业务语义和不兼容变更类型；涉及语义变更必须走影响分析和下游 Owner 审批。

血缘只到表级，无法判断字段变更影响

• 现象：门店区域字段调整后，多个区域指标异常，但平台只能看到表依赖，无法定位哪些指标受影响。
• 根因：只采集任务级和表级血缘，没有解析字段级 SQL 和指标定义。
• 修复：核心资产补字段级血缘；指标定义显式声明依赖字段；变更前自动列出受影响指标和 Agent 问题模板。

权限只在数据库层控制，Agent 回答泄露敏感聚合维度

• 现象：区域经理无权查看客户明细，但通过自然语言追问获得了过细粒度的异常客户列表。
• 根因：数据库权限阻止了部分字段访问，但语义层没有最小聚合粒度和回答级脱敏策略。
• 修复：策略服务增加指标级、维度级、动作级权限；DataAgent 输出前执行聚合粒度检查和敏感字段脱敏。

元数据采集延迟导致 Agent 使用已废弃资产

• 现象：某张履约旧表已经迁移，但 DataAgent 仍在少数问题中选择旧表。
• 根因：目录采集延迟，资产废弃状态没有及时同步到 Agent 检索索引。
• 修复：资产状态变更采用事件推送；废弃资产进入查询阻断列表；索引刷新失败时回退到在线目录查询。

15.3.2 元数据与第33章语义层的分工

元数据和语义层经常被混在一起讨论，但在平台里应承担不同责任。元数据回答“有哪些资产、谁负责、状态如何、从哪里来、影响谁”；语义层回答“业务问题应使用哪个指标、哪个维度、哪个口径、哪个时间粒度”。前者偏资产控制面，后者偏问数语义面。DataAgent 还需要两者，但不能让其中一方替代另一方。一个常见误区，是把表注释、字段别名和指标说明都塞进 Prompt，让模型自行判断。这样短期能回答一些问题，长期会让口径、权限和血缘都不可控。更稳妥的做法是：元数据系统提供资产状态、Owner、质量、新鲜度、血缘和权限标签；语义层在这些资产之上定义 Metric、Dimension、View 和 Glossary；DataAgent 通过 Schema Linking 把用户问题连接到语义层，再由元数据判断可用性和风险。

这条分工也影响变更治理。字段下线、表迁移、质量阻断属于元数据和数据契约变更；指标口径调整、同义词变化、默认时间粒度变化属于语义层变更。两类变更都可能影响 Agent，但审批人、回归样本和发布节奏不同。平台需要在 Trace 中同时记录资产版本和语义版本，才能在事故复盘时判断是底层资产变化，还是业务口径变化。

数据契约的作用是把变化前置。源系统新增字段、修改枚举、改变删除语义或调整 SLA，都要先说明影响范围，再进入下游。否则 Agent 可能继续使用旧字段解释新业务，错误会在自然语言答案中被包装得更难发现。血缘也要服务运行时。用户看到一张图表时，平台应能追溯到指标、表、任务、源系统和数据版本。事故发生后，团队可以沿血缘找到哪一层发生变化，而非在模型、SQL 和数据之间来回猜。元数据建设的验收标准不应只是页面可搜索。更重要的是 Agent 能通过接口读取这些信息，并在生成 SQL、解释答案和拒绝回答时使用它们。只有这样，数据控制面才真正进入 Agent 平台。

指标口径要有可执行定义。自然语言说明能帮助人理解，但 Agent 生成 SQL 时还需要字段映射、过滤条件、时间口径、聚合方式和适用粒度。若指标平台只保存一段描述，模型仍然会在实现层面猜测。把指标定义转成可调用接口，是语义层和 DataAgent 协作的基础。血缘信息也要分层呈现。数据工程师需要看到任务、表和字段级血缘；业务用户更关心某个指标来自哪些系统、今天是否完整、是否经过修正。Agent 在回答时可以根据用户角色选择解释深度，而非把复杂血缘图直接塞进答案。数据契约的变更流程要包含下游验证。上游系统修改字段枚举后，数据平台还要检查 schema 是否兼容，还要跑关键指标和问数样本。字段类型没变，不代表业务含义没变。很多 Agent 错误都来自这种“技术兼容、语义不兼容”的变化。

权限元数据也应和业务语义绑定。某个字段是手机号、某张表包含薪酬、某个指标只允许区域负责人查看，这些信息要能被查询计划和回答生成使用。否则模型可能生成正确 SQL，却在展示阶段泄露敏感明细。元数据工作最终要减少口头解释。用户质疑一个数字时，平台能展示指标定义、血缘、更新时间、质量状态和权限范围；审计复盘时，团队能还原当时 Agent 看到的语义材料。做到这一步，数据控制面才从文档变成了运行时能力。指标服务要处理同名不同义。销售额、收入、GMV、成交额在不同业务线里可能接近，也可能差别很大。指标平台应允许多个指标共存，但必须说明适用组织、场景和计算规则。Agent 在用户问题含糊时，应请求澄清或展示候选口径，而非自动选择一个看起来最常用的字段。

元数据的质量也需要治理。字段描述为空、血缘长期不更新、负责人离职、指标定义和代码不一致，都会让 Agent 使用错误材料。元数据平台不能只收集资产，还要有完整度、更新频率和责任人检查。否则“有元数据”会变成另一层不可信信息。血缘采集要覆盖代码和运行时。静态解析 SQL 可以得到大部分表级关系，但动态 SQL、Notebook、流式任务和外部工具也会产生数据依赖。Agent 平台中的工具调用同样应写入血缘，使某个报告、图表或回答能追溯到具体数据资产。指标变更要通知消费者。修改计算公式、调整过滤条件、切换源表后，依赖该指标的 Agent、看板、评测样本和报告模板都可能受影响。变更流程应输出影响清单，并在发布后触发关键问题回归。这样业务用户不会在同一个问题上突然得到无法解释的新答案。

元数据还可以帮助模型少问无效问题。若平台知道某个字段只在月度粒度可用，用户问日级趋势时，Agent 可以提前说明限制；若某个表今天质量未通过，Agent 可以换用替代指标或暂停回答。这种能力来自结构化元数据，而非模型临场推理。语义层和元数据要处理别名。业务用户常说“销售额”“营收”“流水”，系统里可能对应不同指标。别名映射应由业务负责人确认，并记录适用范围。Agent 可以用别名提高理解能力，但不能在多个候选口径之间静默选择。需要澄清时，系统应把候选指标和差异展示给用户。数据资产负责人要进入运行流程。字段缺描述、指标有争议、血缘异常或权限申请时，平台需要知道找谁处理。负责人信息是问题流转入口，不是目录里的装饰字段。没有负责人，Agent 暴露的数据问题会回到平台团队，平台团队却无法决定业务口径。

元数据接口要保证低延迟和高可用。Agent 每次生成 SQL 或解释指标都可能查询元数据，若元数据服务慢或不可用，问数链路也会受影响。重要元数据可以缓存，但缓存要跟随版本失效。数据控制面进入运行时后，它本身也需要 SLO。血缘可以帮助影响分析。上游表变更前，平台能列出受影响指标、Agent、评测样本和报告模板。这样数据变更不再只影响数仓团队，而能提前通知使用这些资产的 Agent 应用。影响分析越准确，数据变更越敢推进。

15.4 数据产品运营与 Agent 采纳证据

数据产品进入 Agent 平台后，运营指标要从“是否可用”扩展到“是否被正确使用”。一个数据产品可能有稳定 API、完整字段和清晰权限，但 Agent 仍然可能用错：选择了不适合的粒度，忽略了刷新延迟，把探索字段用于正式报告，或在用户无权场景下反复触发拒绝。数据产品 owner 需要看到这些使用证据，才能判断产品说明、语义层和工具接口是否足够清楚。

采纳证据应记录调用次数、调用场景、失败类型、人工修正、报告引用、用户反馈和下游产物。若某个数据产品被频繁用于 DataAgent 报告，就要提高发布稳定性和回归样本覆盖；若某个产品经常导致权限拒绝，就要优化可见性提示或拆分数据域；若某些字段从未被正确使用，就要考虑补示例、改名或下线。运营证据让数据产品从静态资产变成可持续改进的 Agent 能力。

数据产品运营还要处理版本并行。旧版本不能立刻删除，因为历史报告、Trace 和评测样本可能仍在引用；新版本也不能直接替换所有 Agent，因为指标解释和字段语义可能变化。平台应记录每个 Agent 使用的数据产品版本，并在迁移时保留对比样本。这样数据产品迭代不会破坏智能链路的可复盘性。

15.5 元数据质量的业务复核机制

元数据质量不能完全由数据平台自动判断。字段是否表达清楚、指标是否符合业务口径、血缘是否覆盖实际使用路径、SLA 是否匹配用户预期，都需要业务 owner 参与复核。DataAgent 使用这些元数据生成查询和解释结论后，元数据问题会直接变成用户看到的回答问题。把元数据当作内部资产维护，会低估它在智能链路中的影响。

业务复核可以围绕高频问题进行。团队先收集 DataAgent、BI Copilot 和报表系统中的高频查询，再检查这些查询涉及的表、字段、指标、权限、质量规则和负责人是否完整。若某个字段被频繁用于问数，却没有业务解释和有效期，它就不适合直接暴露给自然语言查询；若某个指标存在多个定义，语义层应先收敛或标注适用范围。复核材料应进入数据目录，而不是停留在会议纪要。

早期机制可以很轻：每个核心数据产品有 owner，每月抽查一批高频问题，每次线上争议都回查元数据记录并补充说明。这样元数据治理会从“把字段登记完整”转向“让智能系统能安全使用字段”。这个变化对 DataAgent 很重要，因为模型会放大元数据质量：说明清楚时，它能稳定组合能力；说明含糊时，它会把含糊解释成看似确定的答案。

15.6 数据契约变更的发布门禁

数据契约变更要进入发布门禁，而不是停留在数据平台内部通知。对 Agent 平台来说，字段新增、字段删除、类型变化、枚举变化、SLA 调整、权限标签变化和业务口径变化，都会影响自然语言查询、报告生成和工具调用。字段类型没有变化，也可能改变语义；权限标签没有变化，也可能因为聚合粒度调整而改变可见范围。发布门禁应把这些变化拆成 schema、语义、SLA、权限和质量五类，并为每一类定义检查样本。

Schema 变更的门禁关注兼容性。新增可选字段通常可以低风险发布，但删除字段、修改类型、收紧枚举和改变主键语义，都需要检查下游消费者。DataAgent 的消费者包括 SQL 查询器、语义层、指标服务、报告模板、评测样本和前端图表。发布前应列出受影响的 Metric、View、Agent 问题模板、缓存键和历史报告引用。若无法列出影响范围，变更就不应直接进入生产。变更说明还要写清回滚路径：是恢复旧字段、保留兼容视图，还是让 Agent 暂停使用该资产。

语义变更的门禁更容易被忽略。上游把“支付完成时间”改成“系统确认时间”，字段类型仍是 timestamp，Schema 检查会通过，但履约、收入和时效指标都会变化。语义门禁应要求 owner 说明业务含义、适用时间、历史数据是否重算、指标是否需要新版本。Agent 平台还要重放一批高频问题，检查解释是否仍然成立。若旧报告已经引用旧口径，平台应保留旧版本说明，不能让历史报告在新口径下被重新解释。

SLA 和质量变更也会改变 Agent 行为。数据延迟从 15 分钟变成 2 小时，用户问“今天实时情况”时，系统应该提示数据新鲜度不足，而不是继续给出看似确定的答案。质量规则收紧后，某些资产可能进入 blocked 状态，DataAgent 应选择替代资产、返回降级解释或转人工分析。发布门禁要验证这些状态是否能被 Runtime 和前端读到。若状态只存在于数据平台页面，Agent 仍可能绕过它。

权限变更要和答案层一起验收。行列级权限、聚合粒度、脱敏策略和导出策略变化后，SQL 执行通过不代表回答可以直接展示。平台应检查不同角色在同一问题下得到的结果差异，确认拒答、聚合降级和申请入口都符合策略。对敏感域，门禁样本要包括越权问题、边界角色、历史缓存命中和报告引用。权限变更还要触发缓存失效，避免旧结果在新策略下继续可见。

发布门禁的输出应是一份可回放记录。它记录变更来源、影响资产、受影响 Agent、回归样本、失败处理、批准人和回滚目标。这样线上出现争议时，团队能从 Trace 回到当时的数据契约版本，而非只看到一条自然语言回答。数据契约门禁做扎实后，数据变更会成为 Agent 平台可以吸收的正常事件，而不是每次都靠事后解释。

15.7 数据契约争议的裁定流程

数据契约上线后，争议会出现在多个层面。业务方可能认为字段含义没有变化，数据团队却认为 schema 已经升级；平台可能认为质量规则阻断是正确的，业务方却认为数据仍可用于草稿分析；安全团队可能认为权限标签必须收紧，DataAgent 团队担心问数体验下降。契约争议不能靠口头协调解决，需要裁定流程和可复现材料。

裁定材料应包含契约版本、变更记录、字段样例、质量规则、血缘影响、权限标签、受影响数据产品、受影响 Agent 样本和业务 owner 意见。若争议来自字段语义，业务 owner 需要给出口径裁定；若争议来自质量阈值，数据 owner 需要说明可接受风险；若争议来自权限标签，安全 owner 需要说明合规依据；若争议来自 Agent 行为，平台 owner 需要给出降级和提示方案。不同争议必须落到具体责任人。

裁定结果还要进入元数据系统。字段继续使用、字段废弃、质量规则放宽、质量规则收紧、权限标签变更、指标版本更新，都应形成可追踪记录，并触发下游样本回放。若裁定只停留在会议纪要，DataAgent 仍会在下一次查询中使用旧上下文，争议会重复出现。元数据控制面要把裁定转成机器可读的契约变化。

早期可以为核心数据产品建立契约争议台账。台账记录争议问题、证据材料、裁定人、裁定结果、生效时间、历史结果处理方式和复审日期。这样数据契约既能支撑发布前检查，也能在运行中承接业务争议和平台修正。

15.8 权限标签变化的回归验证

权限标签是 DataAgent 的安全边界之一。组织架构调整、客户归属变化、项目成员变更、数据脱敏策略更新，都会改变用户能看到哪些字段和行。若权限标签更新没有回归验证，Agent 可能在旧权限下生成报告，或在新权限下过度拒绝正常查询。权限变化不能只看同步任务是否完成，还要看真实任务是否仍然符合访问规则。

回归验证要覆盖允许和拒绝两类样本。允许样本证明普通用户仍能完成应有工作，拒绝样本证明越权访问仍被拦截。样本应包含用户角色、租户、数据域、字段、行级过滤、工具调用和最终输出。对于报告和 artifact，还要检查导出后的权限状态，因为用户看到的是被模型整理后的材料，原始 SQL 结果只是其中一层证据。

早期可以在权限标签发布后自动回放一批 DataAgent 样本。若允许样本失败，说明策略过严或标签缺失；若拒绝样本通过，说明存在泄露风险；若报告输出没有保留权限证据，说明报告层需要补 EvidenceRef。这样权限治理就从后台同步进入 Agent 任务验收。

15.9 数据权限链路的端到端校验

数据权限链路进入生产后，平台需要把用户身份、角色、字段级权限、脱敏结果、查询范围、导出记录和审计回执放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。

这类证据应和第33章语义层、第34章查询执行和第52章合规连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。

常见风险包括权限只在入口检查、缓存绕过字段脱敏、导出文件缺少审计记录、跨租户样本没有覆盖。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。

权限链路应以真实查询和导出样本验收，不能只看权限表配置。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。

落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。

本章小结

元数据是企业 Agent 平台的数据控制平面，负责资产发现、语义解释、权限过滤、血缘溯源和审计留痕。数据目录不能停留在表名搜索，应提供 Owner、质量状态、新鲜度、分级分类、使用场景和下游消费者等资产画像。血缘需要覆盖源系统、湖仓、指标、查询和 Agent 回答引用，核心资产还应具备字段级和回答级血缘。数据契约也不能只做字段类型校验，还要覆盖 Schema、业务语义、SLA、质量规则、权限和变更流程。DataAgent 生产查数应优先经过语义层和指标服务，避免直接在物理表上临时拼接口径。元数据越完整，Agent 越容易给出可解释、可复核、可审计的回答。

参考文献

OpenLineage. (n.d.). Documentation.

DataHub. (n.d.). Documentation.

Marquez. (n.d.). Documentation.

dbt Labs. (n.d.). MetricFlow documentation.

Cube. (n.d.). Semantic layer documentation.

Part IV 向量、检索与知识工程

本部分目标

企业 Agent 需要从文档、知识库、图片、表格和业务实体中找到可靠证据。Part IV 讨论向量表示、检索、文档解析、RAG 和知识图谱的工程边界。重点不在“接一个向量库”，而在于让证据可召回、可过滤、可引用、可评估。

本部分章节

阅读路径

第16章至第18章建立检索的向量底座，第19章处理文档进入底座前的解析质量，第20章把召回结果组织成可引用证据，第21章再把实体、关系和规则接入知识工程。读到 Part VI 的 DataAgent 时，本部分提供的是“证据从哪里来、为什么可信”的答案。

第16章 嵌入模型

企业做 RAG、DataAgent、客服 Agent 或多模态检索时，第一反应常常是选向量数据库。更早需要决定的是 embedding：什么内容要被表示成向量，谁来生成向量，向量能解决哪部分问题，哪些问题要交给关键词检索、权限系统、重排模型或人工复核。主流云产品已经把 embedding 放进搜索和 Agent 平台的基础设施层。Azure AI Search 把向量检索、混合检索和过滤检索放在同一个搜索体系里；Google Vertex AI Vector Search 用向量索引支撑语义搜索、推荐和生成式 AI 应用；Amazon Bedrock Knowledge Bases 把文档切分、embedding 生成、向量库写入和 RAG 检索编排成托管流程。这些路线不完全相同，但都把 embedding 放在“业务内容接入大模型应用”的中间层，而非当成独立的模型玩具。

嵌入决定了企业知识能否被准确召回。员工问“出差回来多久要报销”，制度写的是“返回后十五个工作日内提交申请”；分析师问“高客单门店”，数据仓库里可能是 avg_order_value_store_segment；法务问“自动续费风险”，合同里写的是“续展条款”。这些表达在人看来相关，在模型向量空间里未必足够接近。开箱即用的嵌入如果不懂企业术语、字段别名和口径关系，相关内容就会排到结果靠后的位置，后面的 RAG、NL2SQL 和报告生成都会被带偏。

embedding 的价值也容易被夸大。它负责把文本、代码、图片和结构化语义表示为可检索的向量，先找出候选证据、候选字段或候选图片；它不负责判断事实是否正确，也不负责权限、引用和最终业务动作。一个相似条款不能直接成为法务结论，一个相似工单不能直接成为故障根因，一个相似字段也不能直接授权 SQL 执行。企业平台要把 embedding 放在候选召回的位置，再用 metadata filter、reranker、语义层、规则校验和人工复核收口。

本章讨论嵌入模型、向量表示、相似度度量、多模态嵌入、模型选型和召回质量。工程上要先判断哪些业务场景值得接入 embedding，再决定相似度度量、文本模型选型、多模态补位方式和内部评估框架。读者需要特别关注两个问题：哪些检索失败确实来自向量表示，哪些其实来自解析、权限、chunk、字段说明和评估集缺失。很多 embedding 事故都不是模型分数低造成的。某次制度问答召回了过期文档，因为索引里没有生效时间过滤；某次 DataAgent 选错字段，因为字段注释缺少业务别名；某次合同检索漏掉关键条款，因为 PDF 解析把页眉页脚和正文混在一个 chunk 里；某次客服相似工单推荐越权，因为向量索引没有租户和部门 metadata。模型在这些事故里只是链路中的一环，真正需要改的可能是文档解析、权限过滤、chunk 策略、索引版本或评估样本。

因此，embedding 上线时应从“可复盘的召回链路”设计，而非从“调用哪个模型”开始。一次检索至少要记录 query、模型版本、索引版本、过滤条件、候选列表、reranker 结果、最终引用和用户反馈。这样当业务方质疑答案时，平台可以判断是候选没召回、召回了但排序靠后、排序正确但引用被生成层忽略，还是权限过滤把关键材料排除了。没有这条链路，embedding 系统看起来只是一个向量库，实际会成为 RAG 和 DataAgent 难以解释的黑盒。

16.1 嵌入模型的企业应用场景

企业里常见的问题不在数据数量，而在同一件事有多种表达。员工会用口语问“出差回来多久要报销”，制度文档写的是“返回后十五个工作日内提交申请”；业务分析师会说“高客单门店”，数据仓库里可能是 avg_order_value_store_segment；现场照片、票据扫描件和看板截图里还会出现无法直接用文本字段描述的信息。这些表达之间如果没有稳定映射，RAG、DataAgent 和客服 Agent 都会在第一步检索上出错。Embedding 在这里提供语义候选能力：把自然语言问题、制度片段、字段说明、合同条款、图片说明等内容放进一个可检索的表示空间。它不直接保证答案正确，但可以先找出“可能相关”的证据、字段、案例或图片。企业常见入口不必拆成七八套孤立方案，可以先看成同一层语义候选能力在不同业务流程中的分工。

在企业知识库里，embedding 处理员工口语化问题、制度文档和操作手册，先召回相关制度片段、FAQ 和引用证据，再交给知识助手生成回答。在客服和工单系统里，它处理新工单描述、历史处理记录和质检标签，先找相似故障、根因和处理方案，再由客服 Agent 或工单路由系统判断。DataAgent 更关注指标口径、字段注释、SQL 示例和历史查询，把它们召回为 NL2SQL 与语义层编译的候选。法务、合规、商品、运维和多模态巡检也是同样逻辑：embedding 找候选，后续系统再做规则校验、权限过滤、引用确认和人工复核。这些下游系统各不相同，但 embedding 在场景里的职责是一致的：先找候选，不直接做决策。客服场景先找相似处理记录，DataAgent 先找字段和指标解释，法务场景先找相似条款，RAG 场景先找可引用文档。后面能否回答、能否执行动作，还要看权限过滤、重排、引用校验、工具调用和人工审批。

对 DataAgent 来说，embedding 的第一批高价值对象是语义层资产，而非长文档：指标口径、维度说明、字段注释、表关系、历史 SQL、业务术语和报表截图。用户问“高客单门店的复购趋势”时，系统先把“高客单”链接到指标定义，把“门店”链接到维度，把“复购趋势”链接到可计算字段，再交给 NL2SQL 或分析 Agent。这个链路里 embedding 负责候选，语义层和执行引擎负责约束。

从平台负责人视角看，下一步是给这些入口分风险，而非继续扩业务入口。同样是语义检索，不同场景对错误的容忍度完全不同。制度问答、产品手册、FAQ 和内部百科属于低风险高频检索，目标是高召回、低延迟和低成本，可以先用 API 模型或轻量开源模型建立 baseline。工单、DataAgent schema linking 和研发运维属于中风险业务辅助，候选要准确，错误要可分析，结果要可回放，因此需要内部评测集、hard negatives 和 reranker。合同、财务、法务、安全审计属于高风险合规场景，质量目标还涉及召回准确，还包括权限正确、证据充分和可复核，私有化、审计、字段级权限和人工复核应优先进入设计。这一步先把讨论从模型强弱拉回风险边界。同一个 embedding 模型，在员工制度问答里可能已经够用，在合同审查里可能只能做第一阶段召回。企业平台要写清楚使用边界：embedding 返回的是候选，不是事实本身；相似条款不能直接作为风险判定；相似工单不能直接作为根因确认；相似字段也不能直接授权 SQL 执行。

有了风险分层，平台决策才不会停留在“embedding 是否有用”。非敏感知识库和试点场景可以先接商业 API 建质量 baseline；敏感合同、财务、人事数据则要优先评估私有化。是否微调不应凭直觉决定，而要先建立内部 query 集和 hard negative；没有评测集时，微调结论不可复现。是否单独建设 embedding 平台，也取决于复用范围：多业务共享知识库、DataAgent、客服、法务时值得平台化；单应用低频检索可以先轻量接入。多模态 embedding 只有在票据、截图、巡检照片、报表页面等视觉证据进入业务链路时才有必要，纯文本知识库不必提前复杂化。最小上线门槛则很清楚：权限过滤、模型版本、索引版本、召回评测、失败样例和人工复核边界必须齐全。

这三步会在后续模型、向量库和评估讨论中反复出现：先看 embedding 能接入哪些业务入口，再按错误风险分层，然后决定平台化投入和上线门槛。回到图 16-1 的企业能力链路，embedding 只是其中一段：它从业务内容生成语义表示，上线还要经过索引、权限、评测和应用编排。落地时还要把“业务内容”拆成可管理对象。制度文档要有发布版本和生效日期，字段注释要有 owner 和业务别名，历史 SQL 要有执行成功记录和数据域，报表截图要有来源系统和脱敏状态。embedding 服务只负责把这些对象编码成向量，不能替它们补齐治理信息。对象元数据越完整，向量检索越容易被权限、时间、租户和质量门禁约束；对象元数据越薄，检索结果越容易变成一串看似相关但无法使用的候选。

图16-1：企业 embedding 能力链路。来源：本书自绘。Alt text：横向链路依次为文档/查询输入、嵌入模型编码、向量入库、相似度检索、结果返回，箭头表示原始内容经嵌入后进入可检索状态。

如果图 16-1 关注单条能力链路，图 16-2 关注的就是平台横截面。文档、图片、语义层资产和业务应用之间需要一层稳定语义接口，embedding 的平台价值也主要体现在这里。

图16-2：企业级 Agent 平台中的语义接口层。来源：本书自绘。Alt text：分层图中嵌入服务作为语义接口层，向下对接向量库与文档源，向上为 RAG、知识助手等多个 Agent 提供统一的向量化与检索接口。

16.2 向量表示与相似度计算

Embedding 模型输出一组浮点数，可以作为内容的“语义指纹”：相似内容在向量空间里更接近，不相似内容距离更远。OpenAI 的 embeddings 文档把它用于衡量文本相关性，Google 的 embeddings 文档也把 embedding 解释为固定维度的数值向量。这个定义会影响索引设计、版本管理、权限过滤和线上排障。

表 16-1 列出工程上最常见的三种相似度度量。选择哪一种，取决于它能否和模型输出、归一化策略、索引创建参数保持一致，而非单看数学偏好。

表16-1：常见向量相似度度量对比。来源：本书整理。

这些度量会落到图 16-3 这条很短但很关键的计算链路上：原始内容先进入模型服务生成向量，再由向量库按统一 metric 计算相似度，然后返回候选。排障时也应沿这条链路检查模型版本、归一化、metric 和索引版本是否一致。

图16-3：向量生成与相似度计算链路。来源：本书自绘。Alt text：左侧文本经分词与编码生成向量，右侧查询向量与库中向量做相似度计算（余弦/点积）并排序，箭头展示从文本到相似度排序的完整过程。

如果向量都已经归一化，cosine similarity 和 dot product 在排序上通常会接近；如果没有归一化，长度会影响排序结果。企业系统除了在代码里写 similarity="cosine"，还要记录模型是否输出归一化向量、索引创建时使用的度量、查询时是否二次归一化。否则模型升级或向量库迁移时，分数变化很难解释。几个工程事实值得提前写进平台契约:同一索引不应混用不同模型的向量。 模型 A 和模型 B 生成的向量不在同一个空间。文档向量用旧模型，查询向量用新模型，线上表现可能明显变差。更稳的做法是把 model_name、model_version、dimension 和 index_version 放进索引元数据，模型升级时新建索引或做双写灰度。维度是成本变量。 高维向量会增加存储、内存、索引构建时间和查询延迟。Cohere 的 embedding 文档支持通过 output_dimension 调整输出维度，相当于把质量与成本的折中显式交给调用方。开源模型也一样，除了离线分数，还要看吞吐、GPU/CPU 成本和索引体积。

向量相似不等于可回答。 用户问“报销超期怎么处理”，系统可能召回“报销额度”“审批权限”这类相近材料，但它们不能支持最终答案。成熟 RAG 通常会把 embedding 作为第一阶段召回，再叠加关键词检索、metadata filter、reranker 和引用校验。权限要在向量外显式处理。 向量空间不会自动理解某个用户是否能看某份合同、某张报表或某条员工信息。租户、部门、角色、文档状态、生效时间应作为 metadata 进入索引。Azure AI Search 的 filtered vector search 就是这类需求的产品化体现：向量负责相似，过滤字段负责访问边界。一个生产级 embedding record 至少要支撑追责、回滚和重建。

{
  "source_id": "policy-2026-hr-001",
  "chunk_id": "policy-2026-hr-001#p12#c03",
  "content_type": "text",
  "text_hash": "sha256:...",
  "embedding": [0.014, -0.031],
  "model_name": "bge-m3",
  "model_version": "2026-embedding-baseline",
  "dimension": 1024,
  "normalized": true,
  "metric": "cosine",
  "index_version": "kb-hr-v7",
  "metadata": {
    "tenant_id": "tenant-a",
    "department": "hr",
    "acl": ["hr", "finance_manager"],
    "source_version": "v3",
    "effective_at": "2026-01-01",
    "created_at": "2026-06-03"
  }
}

这份记录的价值在事故发生后才会显出来。当业务方质疑某条回答时，平台团队要能回答：用了哪个模型、哪版索引、哪批文档、什么权限过滤、召回了哪些 chunk、引用了哪些证据。缺少这些字段，embedding 系统就会变成一个难以复盘的黑盒。索引升级也要按这份记录来做。模型版本变化、chunk 策略变化、归一化方式变化、metadata 字段变化，都会让旧分数和新分数不可直接比较。生产系统通常需要双写或影子索引：旧索引继续服务线上流量，新索引用同一批 query 和 hard negatives 评估，确认召回、权限和延迟都达标后再切流。否则一次看似普通的模型升级，可能让 DataAgent 字段链接、知识库引用和客服相似工单同时发生漂移。

16.3 文本嵌入模型选型

文本 embedding 选型不建议从“排行榜第一”开始。MTEB 这样的 benchmark 很有价值，它能把模型放在统一任务集上比较；但企业要上线的是自己的制度、合同、商品、工单、字段注释和业务术语。公开榜单可以提供候选，不能替代内部评测。第一轮候选可以覆盖表 16-2 里的四条路线。这里先比较路线，不急着比较具体模型，因为商业 API、开源私有化、国产生态和行业专用模型背后的组织约束完全不同。

表16-2：文本 embedding 模型路线取舍表。来源：本书整理。

BGE-M3 的模型卡强调 multi-lingual、multi-functionality、multi-granularity，适合作为中文和多语言企业知识库的开源 baseline。Qwen3 Embedding 系列强调多语言能力，适合已经采用 Qwen 模型体系的团队做本地化评估。OpenAI Embedding 的优势是接入快、文档完整、服务稳定，适合作为第一条 SaaS baseline。Cohere 的 embedding 文档把 query 和 document 区分为不同 input_type，这个细节很适合写进企业规范：用户问题和被检索文档属于不同文本角色，模型服务要明确区分。路线确定后，再进入表 16-3 的选型维度，把“模型强不强”拆成可评估的问题。这样团队讨论会从排行榜名次转向语言覆盖、部署边界、成本、版本治理这些会影响上线的条件。

表16-3：文本 embedding 模型选型维度。来源：本书整理。

这些维度会直接影响第一轮候选池。更稳的做法是每条路线至少选一个代表模型，用同一套内部评测集跑出来，避免过早押注单一模型。OpenAI Embedding 可以作为 SaaS baseline，在非敏感知识库里先跑质量和延迟基线；BGE-M3 可以作为开源私有化 baseline，重点评估中文制度、客服工单和字段说明；Qwen3 Embedding 适合作为国产生态候选，与 Qwen LLM 和国产推理环境一起评估；E5、GTE、Jina 等模型可以作为对照组，验证公开模型路线是否足够，避免单模型偏见。候选池不是最终结论。它用于保证评测覆盖不同路线：SaaS baseline 用来给质量上限做参照，私有化 baseline 用来评估长期平台能力，国产生态候选用来评估部署协同，对照组用来避免单模型偏见。把前面的路线、维度和候选池连起来，图 16-4 的选型流程就不再追求“选一个最强模型”。它用业务风险和部署边界筛路线，再用内部评测集比较候选，并给不同场景分层结论。这套流程不鼓励“全公司一个模型打到底”。选型报告也应像表 16-4 这样保持分层，而非只给一个模型名。

图16-4：文本 embedding 模型选型流程。来源：本书自绘。Alt text：决策流程从语言/术语覆盖、数据敏感度、延迟成本要求出发，逐步筛出 API 模型或私有化模型，并以评测基线收尾，体现按约束选型。

表16-4：文本 embedding 选型报告的分层结论。来源：本书整理。

企业选 embedding 模型，是在建立一条持续迭代的检索基线。模型会更新，文档会变化，业务术语也会变化。没有内部评测集，今天的选型结论很快就会失效。内部评测集要跟业务语言一起维护。新产品上线、组织架构调整、指标口径变化、合同模板更新后，原有 query 和 golden docs 可能不再覆盖真实问题。平台可以从失败会话、人工搜索日志、DataAgent schema linking 失败样例和客服转人工记录中持续抽样，把它们沉淀成 hard negatives 和回归样本。这样 embedding 选型就不再是一年一次的模型采购讨论，而是检索质量运营的一部分。

16.4 多模态嵌入与视觉检索

多模态 embedding 把文本、图片、截图、扫描页等内容放进可比较的语义空间。CLIP 是经典起点，证明了图像和自然语言可以通过对比学习对齐；SigLIP 改进了图文预训练目标；ColPali 把页面作为视觉对象处理，适合视觉丰富的文档检索。Cohere Embed v4 也把图片 embedding 和可调输出维度放进产品文档，说明企业文档检索正在从“纯文本 chunk”走向“文本、图片、页面版面共同参与”。多模态 embedding 主要补传统流水线的短板：当关键信息藏在页面布局、图像相似性或截图上下文里时，纯文本检索往往不够。表 16-5 同时列出场景和发布控制，是为了避免把多模态检索理解成单纯的“以图搜图”。

表16-5：多模态 embedding 的企业场景与上线控制。来源：本书整理。

多模态检索不能替代文档解析。合同里的金额、票据里的日期、报表里的指标仍然需要 OCR、表格解析、规则校验和业务系统数据确认。更稳的架构是：OCR 和版面解析提供可引用、可校验的结构化内容；多模态 embedding 负责视觉相似、版面相似和图文相关的候选召回。因此，多模态检索更适合按图 16-5 拆成两条互补路径：OCR/解析负责生成可引用文本和结构化字段，多模态 embedding 负责生成视觉相似候选。两条路径在证据校验和人工复核处汇合。

图16-5：多模态检索数据流。来源：本书自绘。Alt text：图片与文本分别经各自编码器映射到同一向量空间，查询可跨模态检索，箭头表示以图搜图、以文搜图共享同一向量索引。

企业落地时，容易踩两个坑。第一个是把截图、票据和巡检照片直接进入共享索引，结果把客户姓名、地址、金额、设备编号一起扩散到检索系统。第二个是把视觉相似当成业务等价：两张缺陷图相似，不代表根因相同；两页合同版式相似，不代表条款风险相同。多模态 embedding 在生产里更适合做候选生成器，后续判断仍要依赖业务规则、结构化字段、引用证据和人工复核。落到需求访谈时，还要反过来问业务里到底有没有图 16-6 这类视觉证据：截图、票据、巡检照片、看板页面是否真的影响检索和判断。如果没有，就不必过早引入多模态 embedding。

如果确实需要视觉证据，平台还要先设计采集规范。巡检照片要有设备编号、拍摄角度和时间地点；票据图片要有脱敏规则和金额校验；报表截图要能绑定报表版本和字段口径；合同扫描页要保留页码和原文件引用。没有这些元数据，多模态 embedding 只能找“长得像”的内容，无法支撑责任判断。视觉检索的上线门槛，应该和文本检索一样包含权限、引用、版本和人工复核。

图16-6：企业多模态检索场景。来源：本书自绘。Alt text：列举质检巡检、合同截图、商品图、工单照片等场景，各自标注用图像嵌入解决的检索问题，展示多模态嵌入的企业落点。

16.5 企业级嵌入模型评估框架

企业评估 embedding，目标是判断某个业务场景能不能上线、代价是否可接受、出了问题能不能复盘，而非给模型排一个总榜。公开 benchmark 适合用来筛候选，真正决定上线的是内部 query 集。

表 16-6 中的五类对象构成一个最小可用评估集。它们共同定义了“什么算找对”，也让不同模型、不同索引和不同过滤策略具备可比性。

表16-6：embedding 评估集的基本对象。来源：本书整理。

指标也要像表 16-7 这样分层看。只看 recall@10 很容易让团队误判，因为候选进了 top-10 不代表回答引用了正确证据；质量、延迟、成本和权限都要进入同一份报告。

表16-7：企业 embedding 评估指标。来源：本书整理。

评估报告还要覆盖表 16-8 这些工程检查项。这里不需要写成很长的审计文档，但要让平台负责人知道“能不能上线”和“出了问题怎么退回去”。

表16-8：embedding 发布前工程检查项。来源：本书整理。

这套评估后续可以固化成 mini-platform 的向量检索实验。当前 mini-platform/infra/vectorstore/__init__.py 还是占位，本章只把实验输入、配置和报告结构设计清楚，不把它写成当前可运行项目。

mini-platform/projects/embedding-vector-benchmark/
├── README.md
├── requirements.txt
├── run.sh
├── data/
│   ├── docs/
│   │   ├── travel-policy.md
│   │   ├── reimbursement-guide.md
│   │   └── product-quality-faq.md
│   └── evals/
│       └── retrieval_queries.jsonl
├── configs/
│   ├── openai.yaml
│   ├── bge_m3.yaml
│   └── qwen3_embedding.yaml
├── reports/
│   └── embedding_benchmark.md
└── src/
    ├── embed.py
    ├── index.py
    ├── retrieve.py
    └── evaluate.py

评测样例可以这样写：

{
  "query_id": "q-001",
  "query": "出差回来后多久必须提交报销？",
  "golden_chunk_ids": ["travel-policy#p12#c03"],
  "hard_negative_chunk_ids": ["reimbursement-guide#p02#c01"],
  "metadata_filter": {
    "department": "finance"
  },
  "risk_level": "medium"
}

配置文件里不能只留一个模型名。维度、归一化、batch、索引度量和费用口径都要写清楚，否则同一套向量结果在不同环境里很容易跑出不同解释。

provider: local
model_name: BAAI/bge-m3
model_version: 2026-embedding-baseline
dimension: 1024
normalized: true
metric: cosine
batch_size: 32
top_k: 10
cost:
  unit: local_gpu_hour
  estimate: manual
index:
  backend: qdrant
  collection: enterprise_policy_benchmark
  version: kb-hr-v7

报告应该输出分数，也要输出失败样例。对企业来说，失败样例往往比平均分更有价值：它能告诉团队问题在模型、chunk、OCR、权限过滤、字段注释，还是 query 改写。图 16-7 中 Project 13 的实验数据流也要围绕这个原则设计：同一批 query、golden docs、hard negatives 和 metadata filter 同时进入多个模型/索引组合，避免“模型 A 用一批题、模型 B 用另一批题”的不可比问题。在这种数据流之上，企业内部报告才适合输出表 16-9 这样的分层结论。

图16-7：embedding benchmark 数据流。来源：本书自绘。Alt text：评测流程从标注查询集出发，经各候选模型编码、检索、计算 recall@k 与延迟，输出对比报告，箭头表示同一评测集横向比较多个模型。

表16-9：embedding benchmark 报告结论示例。来源：本书整理。

上线后，评估不应停止。每次模型升级、chunk 策略调整、向量库迁移、文档重建，都要重新跑 benchmark，并保留旧模型和旧索引的回滚路径。企业平台要沉淀“每次语义检索变更都可评估、可解释、可回滚”的机制，而非只沉淀某个模型名。

16.6 Embedding 上线后的质量运营

Embedding 模型上线后，质量不会自动稳定。文档会更新，业务术语会变化，权限策略会调整，用户提问方式也会随着产品使用而变化。平台要把 embedding 当成持续运营的检索能力，而非一次性模型选型结果。每次模型升级、chunk 策略调整、索引重建和权限过滤改动，都可能改变召回结果。质量运营要保留失败样例。用户点踩、人工纠错、答案引用错误、SQL 字段链接错误，都应转成 query、golden docs 和 hard negatives。没有 hard negatives，embedding 很容易把语义相近但业务含义不同的材料排在前面。例如“返利”和“折扣”在文本上接近，但财务口径不同；“华东大区”和“东部仓配区”都有区域含义，却属于不同组织维度。

权限过滤也要进入评测。很多团队只评估 recall@k，却没有检查 top-k 中是否出现无权内容。企业检索链路必须区分“先过滤后召回”和“召回后过滤”的差异。前者更安全但可能牺牲召回，后者更容易暴露敏感候选。高风险场景应优先保证无权内容不进入模型上下文，再通过 reranker、术语表和查询改写补质量。Embedding 的成本也会在上线后放大。在线查询成本、离线重建成本、reranker 成本、索引存储成本要分开统计。若只看单次 embedding API 价格，团队会低估全量重建、双版本并行和多租户隔离带来的开销。第41章的成本治理应覆盖这些维度，避免检索质量优化变成不可解释的长期账单。模型评估记录也应保留到后续复盘中。

16.7 Embedding 资产复审与样本回流

Embedding 资产复审要把模型、索引、chunk 策略、metadata、过滤规则和评测集放在一起看。很多检索事故并非模型突然变差，而是文档重建时丢了字段、chunk 规则改变了段落边界、权限过滤把关键候选排除、reranker 版本与向量空间不匹配，或者业务术语在新季度发生了变化。若复审只看模型名称和向量维度，团队会把所有问题都归因到“换模型”，进而错过真正的修复点。

复审材料应从失败样本开始。用户点踩、引用被驳回、人工改选文档、DataAgent 字段链接失败、RAG 回答缺少证据，都可以转成检索样本。样本要记录 query、用户角色、可访问范围、期望文档、错误候选、错误原因、chunk id、文档版本和修复动作。这样的记录比抽象的“召回不好”有用得多，因为它能告诉团队到底该补术语、改 metadata、调 chunk、换 reranker，还是修权限过滤。样本回流后，要进入固定回归集，并在模型升级、索引迁移、文档重建前重新运行。

Embedding 资产还要有生命周期。旧索引在双版本并行结束后要归档或删除，过期文档要从向量库清理，失效 metadata 要重建，长期不用的租户索引要进入成本复审。删除动作不能只由存储团队判断，因为它可能影响 RAG、知识库问答和 DataAgent 字段链接。更稳妥的方式是让知识库 owner、检索 owner、安全 owner 和业务 owner 共同确认：哪些材料仍有业务依赖，哪些材料只需保留静态归档，哪些可以从在线索引移除。这样，Embedding 不会变成只增不减的向量仓库，也不会因为清理过急破坏上线能力。

16.8 Embedding 评测集的业务覆盖

Embedding 评测集不能只覆盖通用语义相似。企业检索需要覆盖制度条款、产品名称、客户简称、组织层级、指标别名、合同条款、表格标题、截图文字和历史项目代号。很多失败并非模型不懂中文，而是业务词在不同部门有不同含义。评测集应把这些容易混淆的词放进 hard negatives，让模型、chunk 和 reranker 都接受同一组业务检验。

业务覆盖还要按使用场景分层。客服知识库关注用户表达和制度引用，财务知识库关注口径和金额，销售知识库关注客户与产品，研发知识库关注版本和故障，DataAgent 关注字段、指标和语义层连接。一个 embedding 模型在客服场景表现好，不代表它适合 DataAgent 字段链接。评测报告应按场景拆分结论，而不是给出一个总分。

评测集维护需要业务专家参与。平台团队可以设计指标，数据团队可以准备文档，业务专家要确认哪些候选是真相关、哪些只是词面相似。没有这一步，评测集会奖励“看起来像”的结果，却无法保证 Agent 引用正确材料。Embedding 的业务覆盖越充分，后续 RAG 和 DataAgent 越少依赖事后纠错。

16.9 Embedding 模型的业务退化监控

Embedding 模型上线后，退化往往先出现在业务样本里。新产品、新字段、新政策、新缩写和新文档格式进入系统后，原有向量空间可能仍能召回相似文本，却不能区分新的业务边界。用户看到的是“引用看起来相关，但答非所问”。这类退化很难通过平均 recall 发现，需要按业务域观察失败样本。

退化监控可以从几类信号开始：正确证据排名下降，hard negative 排名上升，权限过滤后候选不足，用户频繁改引用，报告复核退回，DataAgent schema linking 选错字段。每个信号都要回到具体样本和知识库版本。若退化来自新术语，可能需要补样本或微调；若来自文档解析，先修 chunk 和 metadata；若来自权限过滤，先修策略。不同原因对应不同处理路线。

早期不必建立复杂监控系统，可以从评测集和线上反馈结合做起。每月抽样一批真实 query，对比当前 embedding、索引版本和重排结果，记录退化样本。Embedding 模型的价值不在于一次选型完成，而在于它能随业务知识变化持续被校准。

16.10 Embedding 变更的跨链路验收

Embedding 变更会影响 RAG、知识库、DataAgent、报告引用和权限过滤，验收不能只停在召回分数。一次模型替换可能让制度问答更好，却让 DataAgent 字段链接更差；一次 chunk 策略调整可能让长文档引用更完整，却让短问题召回变慢；一次 metadata 重建可能修复权限过滤，也可能丢失业务标签。跨链路验收要把 embedding 放回完整任务中检查。

验收样本应覆盖三类链路。第一类是知识问答链路，检查 query、候选文档、引用段落、回答和用户可见证据。第二类是 DataAgent 链路，检查自然语言问题、字段候选、指标候选、语义层版本和最终 SQL。第三类是权限链路，检查不同角色能否只看到自己有权访问的候选。若某个变更在单独 recall@k 上提升，却让权限或字段链接变差，就不能直接进入默认配置。

早期可以为每次 embedding 变更生成一份跨链路验收记录：模型版本、索引版本、chunk 策略、metadata 版本、reranker 版本、样本结果、失败类型和回滚目标。这样 embedding 团队、知识库团队、DataAgent 团队和安全团队能看到同一组证据。向量空间的变化只有通过任务链路验收，才能成为可靠的平台能力。

16.11 向量空间迁移的业务风险复盘

Embedding 模型、chunk 策略和索引参数共同决定一个向量空间。企业平台升级其中任何一项，都可能改变用户看到的证据候选。迁移风险常常不会表现为系统不可用，而是表现为引用顺序变了、相近制度被混淆、字段链接更容易选错、权限过滤后的候选不足。这样的风险比接口报错更难发现，因为回答仍然流畅，用户需要事后核对才会发现证据偏移。

向量空间迁移前，应先确定受影响业务域。客服制度、财务口径、合同条款、产品资料和 DataAgent 字段链接，对召回错误的容忍度不同。低风险知识库可以先用 shadow index 对比候选变化，高风险知识库应要求业务 owner 抽查样本。评审材料要展示旧空间 top-k、新空间 top-k、被权限过滤的候选、hard negative 排名变化和最终进入上下文的片段。只给一个平均 recall 提升，很难说明迁移是否适合生产。

迁移后还要观察用户修正行为。若用户频繁改引用、报告复核退回增加、DataAgent schema linking 失败上升，说明新空间可能在局部业务语言上退化。平台应允许按知识库、租户或任务类型局部回滚，而不是要求全部回到旧模型。局部回滚需要发布台账记录模型版本、索引版本、chunk 版本和路由规则，否则事故时无法复现当时的检索条件。

早期可以把向量空间迁移复盘放入每次 embedding 发布流程。发布前跑固定样本，发布中保留旧索引，发布后观察失败反馈，稳定后再清理旧版本。这个流程会增加一些存储和运维成本，但它能把向量检索从“模型接口升级”变成可解释的知识链路变更。对于企业 Agent，稳定的证据候选比单次榜单分数更重要。

16.12 Embedding 评测结果的业务解释

Embedding 评测结果不能只给技术团队看。召回率、MRR、nDCG、向量维度和相似度分布，对业务用户来说很难直接判断价值。企业上线嵌入模型时，需要把评测结果翻译成业务解释：哪些问题更容易找到正确文档，哪些文档类型仍然不稳定，哪些业务域需要补样本，哪些场景不能直接依赖向量召回。

业务解释要从样本开始。比如政策问答中，模型能否把“报销额度”和“费用标准”关联起来；合同检索中，能否区分付款条款、违约条款和保密条款；客服知识库中，能否把口语化问题映射到正确知识条目。评测报告应给出这些样本的成功和失败，而不只给平均指标。平均分提高不代表所有业务域都变好，某些小样本但高风险场景反而可能退化。

评测解释还要连接发布决策。若模型在通用知识库上提升明显，但在法律文档上退化，就可以只在低风险知识问答中发布；若模型对短问题表现好，对长查询表现差，就需要限制查询改写策略；若模型对某类术语混淆严重，就应先补 Glossary 和 Hard Negative。Embedding 评测的价值，在于指导发布范围，而不是证明某个模型总体更强。

早期可以为每次 Embedding 变更生成一页业务解释。内容包括受益任务、风险任务、样本差异、发布范围、回滚条件和需要补充的数据。这样第16章的模型评估会自然连接第17章微调、第18章向量库和第20章 RAG，而不是停留在技术指标比较。

16.13 Embedding 选型后的业务解释

Embedding 模型选型完成后，平台还要能解释为什么选它。业务团队通常不会关心向量维度和训练语料细节，但会关心搜索为什么变准、哪些问题仍然找不到、哪些语言或术语需要额外处理、切换模型后历史索引是否会变化。Embedding 是检索链路的基础能力，选型结果应被翻译成业务可理解的影响说明。

解释材料要连接评测样本。平台可以说明新模型在哪些查询类型上改善召回，例如专有名词、短语义问题、长文档摘要或跨语言检索；也要说明哪些场景没有改善，例如表格编号、合同条款编号、罕见缩写和权限过滤。若选型只报告整体 nDCG 或 Recall@K，业务 owner 很难判断它是否适合自己的知识域。

早期可以为 Embedding 模型维护选型说明：评测集、主要收益、失败类别、索引重建成本、灰度策略和回滚方式。这样 Embedding 不会被当成后台参数，而会成为知识检索能力的可解释基础。后续 RAG、GraphRAG 和 DataAgent 引用证据时，也能追溯到向量空间的版本和适用边界。

16.14 嵌入模型选型的上线判断

嵌入模型选型进入生产后，平台需要把语料类型、语种、向量维度、召回样本、成本、延迟、权限过滤和退役计划放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。

这类证据应和第17章微调、第18章向量库和第20章 RAG连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。

常见风险包括只看公开 benchmark、忽略企业语料、向量维度增加导致成本上升、旧模型退役缺少计划。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。

嵌入模型选型应以本地语料和生产约束为准，再决定是否进入平台标准目录。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。

落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。

本章小结

嵌入模型决定知识、文档和多模态材料能否进入可检索的语义空间，通用榜单只能作为候选来源。企业场景还要比较语言覆盖、领域术语、向量维度、索引成本、延迟和私有化约束。多模态嵌入适合截图、票据、报告和复杂版式材料，但仍要配合 OCR、版面结构和引用校验。Benchmark 应使用同一批 query、golden docs、hard negatives 和过滤条件横向比较候选方案。模型、chunk、索引和向量库变更都要可评估、可解释、可回滚。长期方案不能建立在某个模型名上，而要建立在评测集、证据链和版本迁移流程上。

Embedding 的长期价值来自稳定运营。团队要能持续吸收失败样例、补充业务术语、清理过期文档、重建索引并解释分数变化。只有这些日常动作成立，向量检索才会从一次模型接入变成企业知识工程的基础能力。在平台路线里，embedding 还应和第17章的向量库、第18章的知识库治理、第20章的 RAG、第33章的 DataAgent 语义层连起来看。模型生成向量只是第一步，向量库负责检索性能和过滤，知识库负责来源和版本，RAG 负责引用与回答，DataAgent 负责把指标和字段链接到可执行查询。任何一层薄弱，用户看到的都会是“Agent 找错资料”。因此，embedding 团队的工作不应只停在模型服务。它还要和数据治理团队一起维护 metadata，与业务专家一起维护术语和 hard negatives，与评估团队一起维护召回回归集，与安全团队一起验证权限过滤。只有这些角色共同参与，向量空间里的相似性才能变成业务系统里的可信候选。这也要求平台把召回失败作为一等事件处理。用户点踩、引用被驳回、人工改选文档、SQL 字段链接失败，都应被收集到评测池，而非只作为一次会话反馈结束。持续积累这些失败，embedding 系统才会随着业务语言变化而进化。失败样例越具体，后续模型、索引和 chunk 策略的调整才越有方向。

参考文献

• Azure AI Search vector search overview：https://learn.microsoft.com/en-us/azure/search/vector-search-overview

• Azure AI Search hybrid search overview：https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview

• Google Vertex AI Embeddings APIs overview：https://cloud.google.com/vertex-ai/generative-ai/docs/embeddings

• Google Vertex AI Vector Search overview：https://cloud.google.com/vertex-ai/docs/vector-search/overview

• Amazon Bedrock Knowledge Bases overview：https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html

• Amazon Bedrock Knowledge Bases supported models and vector stores：https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-supported.html

• OpenAI Embeddings guide：https://platform.openai.com/docs/guides/embeddings

• BGE-M3 model card：https://huggingface.co/BAAI/bge-m3

• Qwen3 Embedding model card：https://huggingface.co/Qwen/Qwen3-Embedding-8B

• MTEB leaderboard：https://huggingface.co/spaces/mteb/leaderboard

• Cohere Embeddings docs：https://docs.cohere.com/docs/embeddings

• Cohere Embed Multimodal v4：https://docs.cohere.com/changelog/embed-multimodal-v4

• OpenAI CLIP：https://openai.com/index/clip/

• SigLIP paper：https://arxiv.org/abs/2303.15343

• ColPali paper：https://arxiv.org/abs/2407.01449

第17章 嵌入微调与重排

第16章解决的是“先选一个可用 embedding baseline”。上线后，团队很快会遇到第二层问题：公开模型能召回大部分高频问题，却在内部术语、字段别名、合同条款、工单根因和长尾表达上出错。零售企业的员工问“KA 门店坏账风险”，财务制度里写的是“大客户应收账款逾期”；业务分析师问“团购转化”，指标库里写的是 group_buying_paid_ratio；客服问“会员黑卡退差价”，制度里可能写的是“高等级权益补偿”。这些表达在业务里互相指向，在通用语料里却未必足够接近。

这类错误在演示阶段不一定明显。团队准备的 demo 问题通常来自文档标题、FAQ 或字段说明，baseline 很容易答得不错。真正上线后，用户会带着口语、缩写、历史叫法和系统字段名提问，检索结果开始偏向“主题相似但不能回答”的材料。DataAgent 里尤其危险：customer_level、customer_segment 和 customer_risk_grade 都属于客户主题，模型如果只学到“客户相关”，生成 SQL 时就可能把分群字段当成风险字段。法务和合规场景也类似，续约通知、自动续费条款和服务到期提醒看起来相近，却不能互相替代。

很多团队的第一反应是换更大的 embedding 模型。这个动作有时有用，但经常只是把问题往后推。检索失败可能来自文档解析、chunk 切分、字段说明缺失、权限过滤、query rewrite 偏移，也可能来自向量空间不懂企业语义。前几类问题靠训练解决不了，甚至会被训练掩盖。平台团队需要先把失败样例摆出来：正确材料到底有没有进入 top-k，进入后是不是排序靠后，错误候选为什么看起来相似，权限过滤后是否还剩足够证据。只有瓶颈落在语义匹配或排序阶段，微调和重排才值得投入。

Embedding 微调和重排会改变检索链路的工程形态。微调会改变向量空间，牵动索引重建、版本回滚和线上稳定性；重排会增加第二阶段计算，影响延迟、成本和解释链路。训练脚本跑通只是开始，真正麻烦的是发布：新模型需要重新编码文档，新旧索引不能混用，灰度期间要能比较同一批 query 的候选差异，失败时要回到旧索引。重排上线也一样，服务超时、外部 API 出域、候选过多导致 p95 上升，都可能把一个质量优化变成稳定性事故。

本章围绕嵌入微调、重排、对比学习、难负例、回归评测和灰度发布展开。读者需要先学会判断检索质量问题属于哪一类，再决定补语义资产、构造 hard negative、训练 embedding，还是在召回后增加 reranker。企业检索系统真正需要的是在内部术语、字段别名、合同条款和长尾表达上更可诊断、可回滚、可持续改进；模型分数只是发布判断的一部分。

17.1 领域语义适配需求

企业需要领域适配，通常源于企业内部同时存在几套语言：业务口径里的“战略客户”，CRM 里的 tier_a_account；分析师口中的“团购转化”，指标平台里的 group_buying_paid_ratio；一线人员说的“页面闪退”，研发日志里的 SIGABRT。公开 embedding 模型可以给出语义近邻，却不知道这些表达在当前企业里哪些可以互相替换，哪些只是主题相似。领域适配应先识别语言错配出现在哪里，再决定是否训练。读表 17-1 时，可以把触发信号、线上表现和优先动作连起来判断：问题是该补语义资产、补样本，还是进入训练和重排。这里的关键是“先归因，后训练”。如果用户问题和文档字段完全不共词，先补术语表、字段注释和 query 改写样本，往往比直接微调更快；如果正确 chunk 已经进入 top-50，但一直排在错误证据后面，reranker 的风险低于重建 embedding 空间；如果召回结果被权限过滤清空，训练模型只会让错误更隐蔽，真正要修的是 metadata、ACL 和索引写入契约。

表17-1：领域语义适配的触发信号。来源：本书整理。

这些触发信号还不能直接推出“应该微调”。平台团队需要继续把检索错误分成四类：召回不到、召回到了但排序靠后、召回了相似但无法回答的材料、召回结果被权限过滤后不足。第一类和部分第二类适合用 embedding 微调解决；第三类通常需要 reranker、规则和证据校验；第四类属于权限与索引治理，用训练掩盖会让事故更难复盘。平台负责人的第一轮决策也应该沿着表 17-2 的顺序展开。这里先不讨论模型选型，而是把“是否值得训练”放到错误归因、样本条件、合规边界和回滚能力里判断。

表17-2：平台负责人微调与重排决策要点。来源：本书整理。

决策顺序应从错误类型开始，再检查样本是否足够，然后选择微调或重排。否则团队很容易把文档解析、权限过滤、chunk 切分的问题错误地归因给 embedding 模型。回到图 17-1 的检索链路，边界会更清楚：微调影响第一阶段向量召回，重排影响候选排序，权限和引用校验则属于平台控制面。

图17-1：嵌入微调与重排在检索链路中的位置。来源：本书自绘。Alt text：检索链路依次为查询编码、向量召回（嵌入模型负责）、重排精排（reranker 负责）、返回 top-k，标出微调作用于召回、重排作用于精排两个不同环节。

链路边界确定之后，样本治理不能停留在训练脚本旁边的临时文件。图 17-2 里的每一条用于微调或重排的样本，都要能追溯到真实 query、业务场景、正负样本、权限范围和复核状态。

图17-2：企业语义适配样本工作台。来源：本书自绘。Alt text：界面分区展示查询、正样本、难负例标注列表与标注进度，右侧是样本质量统计，体现把线上日志转化为训练样本的人工工作台。

17.2 对比学习与样本构造

Embedding 微调要定义企业关心的相似关系，而非简单多喂一些公司文档。sentence-transformers 的训练文档把模型、数据集、loss、训练参数和 evaluator 拆成训练组件；常见检索训练会使用 pairs、triplets 或带标签的相关性样本。企业应先把样本定义清楚，再讨论训练资源。表 17-3 列出的样本形态并不多，它们和上一节的错误归因是一一对应的：召回不到时需要正样本 pair，排序混淆时需要 hard negative，重排评估时需要多级相关性，冷启动时才考虑伪标签。

样本构造的难点不在格式，而在业务判断。一个问题和一个 chunk 是否构成正样本，不能只看语义相似，还要看它能否支撑答案；一个 negative 是否足够难，也不能只看模型分数，还要看业务人员是否会把它误认为可用证据。比如“续费折扣政策”和“自动续费责任”都和续约有关，但前者不能回答合同责任；“客户等级”和“客户风险等级”都在客户表里，但前者不能支撑风控分析。训练样本如果绕过这些判断，模型会更自信地召回错误材料。

表17-3：检索微调样本形态。来源：本书整理。

样本形态越复杂，越需要业务复核。伪标签适合冷启动，但不能替代人工判断；多级相关性适合训练 reranker，但如果标注标准不一致，最终只会把噪声训练进模型。标注口径要在训练前写清楚。标注人需要知道“可回答”“部分可回答”“主题相关但不可回答”“无权限可见”这些标签如何区分；数据团队需要知道样本来自哪个业务域、哪个索引版本和哪个权限范围；平台团队需要知道这些样本未来是否会进入训练、评估，还是只作为事故复盘材料。没有这些元数据，训练集很快会变成一堆看似有用、实际无法追责的 JSON。Hard negative 是企业微调里最有价值的样本。它指“很像正确答案，但业务上不能支持回答”的材料，而非随机不相关文档。报销额度制度不能回答报销时限，合同续约通知不能证明自动续费风险，字段 customer_level 也不能替代 customer_risk_grade。如果 negative 太容易，模型只学会粗粒度主题；如果 negative 本身标错，模型会把正确路径打歪。

表 17-4 将 hard negative 的来源分开，是因为 LLM 批量生成只能补候选，不能替代真实失败样例。最可靠的 negative 通常来自真实失败的 top-k，因为它直接暴露了当前模型已经混淆的边界。

表17-4：hard negative 的来源与处理。来源：本书整理。

这几类来源可以组合使用，但优先级不同。线上失败样例优先，业务相邻对象其次，LLM 生成只能补候选池。否则 hard negative 会看起来很丰富，实际却没有覆盖企业真实的错误分布。样本进入训练前要先进入数据治理流程。每条样本至少记录 query_id、positive_id、negative_id、labeler、source、scenario、acl_scope、created_at 和 review_status。这样做看起来繁琐，但它决定模型升级后能否解释“为什么这个模型把某类字段排前了”。

DataAgent 的 hard negative 要特别谨慎。字段名相似不代表可替换，customer_level、customer_segment、customer_risk_grade 都可能出现在客户主题下，但它们对应的业务含义、权限边界和 SQL 计算完全不同。用于训练或重排的 negative 应该带上表、字段、指标、SQL 示例和业务口径，否则模型可能学到“主题相近即可召回”的错误偏好。到了标注会，团队需要图 17-3 这种能把错误来源和修复动作对齐的工作底稿。横向看错误来源，纵向看修复动作，才能把“继续训练”“补字段说明”“改 chunk”“加权限过滤”分开讨论，而非把所有失败都推给 embedding 模型。

图17-3：hard negative 错误分析矩阵。来源：本书自绘。Alt text：矩阵按"语义相近但不相关"和"字面相近但语义无关"等维度归类难负例，每格给出典型例子，帮助定位难负例的来源类型。

17.3 嵌入模型微调路线

企业微调要从低风险路线开始。起点通常是让检索系统可诊断，而非直接训练：固定一批真实 query，补齐 golden docs，标出 hard negatives，记录失败原因。错误能稳定复现，业务团队也能解释“什么是正确相似、什么是危险相似”时，微调才有意义。较成熟的企业路线通常分四个阶段，表 17-5 把这些阶段背后的取舍压缩成可比较的路线。第一阶段的产出不应该是模型，而是一份可复现的失败清单。清单里要有 query、正确证据、错误候选、权限条件、当前排名和业务解释。只有这份清单稳定，后面的训练或重排才有参照物。很多微调项目失败，是因为团队还没弄清楚错误分布，就先追逐训练 loss；模型看起来提升了，线上用户抱怨的问题却没有变少。

路线的起点是检索基线和数据补强。先用第16章选出的 baseline 模型跑内部 query 集，把失败样例按业务场景拆开。很多问题在这一阶段就能解决：字段注释太短，就补字段说明；制度文档缺少别名，就补术语表；客服工单缺根因标签，就补结构化标签；DataAgent 找不到指标，就把指标口径、历史 SQL 和表血缘写进语义层。这个阶段不改变模型，回滚成本最低。有了几百到几千条稳定样本后，团队可以进入小规模监督对比学习，用 sentence-transformers 这类生态做 pairs、triplets 或 ranking loss 训练。训练样本不追求大而杂，而要覆盖高频业务混淆：同主题不同口径、同字段不同含义、同合同不同条款、同故障不同根因。训练后需要重新编码文档向量并构建新索引，不能把新 query 向量打到旧索引上。

企业已有私有化 embedding 模型服务时，可以继续评估 LoRA、adapter 或继续预训练式的轻量适配。但这一步要克制：它会增加模型发布、推理服务、向量重建、A/B 测试和安全审计复杂度。客服、法务、DataAgent schema linking 等高价值场景持续受益时，才值得进入长期维护。微调、reranker 和检索策略要放在同一条链路里判断。微调解决“候选能不能进来”和“向量空间是否更懂业务边界”；reranker 解决“候选进来后谁排在前面”。如果正确材料已经进入 top-50，只是排序靠后，优先加 reranker 往往更稳；如果正确材料长期进不了 top-k，再考虑微调 embedding。企业上线评审要看组合效果，而非只看训练 loss；表 17-5 进一步比较了这几条路线的优势、代价和适用边界。

表17-5：嵌入微调路线取舍表。来源：本书整理。

微调路线要有明确退出条件。数据补强后如果 recall@10 已经满足业务阈值，就没有必要进入训练；小规模对比学习如果只提升平均分、却让高风险场景变差，就不能上线；引入 reranker 如果 p95 延迟超过交互要求，也要回到检索候选数量和模型大小上重新折中。退出条件要写进发布评审。比如合同检索要求正确条款进入 top-5，DataAgent schema linking 要求同名字段错误率低于阈值，客服知识库要求 p95 仍在交互可接受范围内。某个平均指标变好，不代表所有场景都能放量；如果高风险场景退化，哪怕总体 recall 上升，也应该停止发布。企业微调的上线门槛应该高于普通模型替换。模型版本变化意味着文档向量、query 向量和索引空间都变了。生产上不要把新模型直接写进旧索引。更稳的流程是：新模型离线编码一份新索引，离线评测通过后做 shadow query，再做小流量灰度，并保留旧索引回滚窗口。图 17-4 把训练、重建索引、shadow query、灰度和回滚放在同一条链上，用来提醒团队：embedding 微调属于检索平台版本变更，不能作为模型团队的孤立动作处理。

图17-4：embedding 微调版本灰度流程。来源：本书自绘。Alt text：流程从新版本嵌入模型上线小流量，到回归评测对比基线、逐步放量、异常回滚，箭头表示按评测结果控制放量节奏。

17.4 重排模型架构位置

Reranker 的位置在召回之后、答案生成之前。第一阶段 embedding 或混合检索负责从百万级文档里找出几十到几百个候选；reranker 逐个判断 query 和候选内容的匹配程度，把能支持回答的证据排到前面。sentence-transformers 的 Retrieve & Re-Rank 文档把 bi-encoder 用于高效召回、cross-encoder 用于重排；Cohere Rerank 这类商业 API 也遵循同样的二阶段思路。表 17-6 拆开召回、重排和答案生成前过滤，是为了避免把 reranker 误用成权限系统或坏 chunk 的补救工具。

表17-6：召回与重排的职责边界。来源：本书整理。

Reranker 不应该变成“万能纠错器”。如果正确文档没有进入第一阶段 top-k，重排没有机会修复；如果 chunk 切坏了，reranker 只能在坏候选里排序；如果权限过滤放在 reranker 后面，模型可能已经看到了用户无权访问的内容。平台契约要规定：权限过滤必须在召回和重排之间可配置，敏感场景优先 pre-filter；重排请求本身也要记录 query、candidate ids、model version 和分数。

{
  "query_id": "q-2026-0617-00031",
  "retrieval_index": "policy-kb-v7",
  "retrieval_top_k": 80,
  "reranker": "bge-reranker-large",
  "reranker_version": "2026-06-baseline",
  "candidates": [
    {"chunk_id": "travel-policy#p12#c03", "retrieval_score": 0.74, "rerank_score": 0.91},
    {"chunk_id": "expense-limit#p02#c01", "retrieval_score": 0.78, "rerank_score": 0.21}
  ]
}

17.5 标注评测与版本治理

微调和重排能否上线，取决于评测反馈链路。一个可用的企业评测集要覆盖真实 query、golden docs、hard negatives、权限过滤、业务场景标签和失败原因。评测报告除了平均分，还要说明哪些场景变好、哪些场景变坏、成本和延迟变成多少；表 17-7 的上线检查项也围绕这些问题展开。

表17-7：嵌入微调与重排上线检查项。来源：本书整理。

第16章的 embedding benchmark 后续可以扩展成“微调 + 重排”报告：同一批 query，对比 baseline embedding、微调 embedding、baseline+reranker、微调+reranker 四种组合。报告输出不只包含分数，还要包含失败样例和版本元数据，这样平台负责人才能判断能不能上线，工程师也能定位下一轮该修模型、修索引，还是修文档解析。当前仓库尚未包含这一路径，本章不提供可运行命令。评测报告不能停在一行分数。图 17-5 这种页面把不同组合的质量、延迟、成本、失败样例和版本信息放在一起，平台负责人才有依据决定上线、灰度或回滚。

报告还要让业务复核人员看得懂。只展示 nDCG、MRR 和 recall 曲线，平台工程师能判断趋势，业务团队却很难知道模型到底改好了什么。更好的做法是把分数和样例放在一起：这条 query 旧版本排第一的是错误条款，新版本把正确条款排到第二；这条 DataAgent 问题旧版本混淆了两个字段，新版本虽然命中正确字段，但仍把无关报表放进候选。这样的报告能把模型发布讨论从“分数升了多少”拉回“业务风险还剩什么”。

图17-5：重排评测报告页面。来源：本书自绘。Alt text：报告页展示加入重排前后的 recall@k、nDCG、延迟对比图表与逐条 case 差异，体现重排带来的质量提升与代价。

17.6 Hard Negative 与业务样本治理

嵌入微调最容易被低质量样本带偏。正例通常比较容易收集，真正决定区分能力的是 hard negative。企业知识库里常见的 hard negative 包括名称相似但口径不同的指标、同一产品不同版本文档、同一合同模板不同条款、同一客户不同主体，以及语义相近但权限不同的资料。若负样本只来自随机采样，模型会学到表面相似度，却无法区分真实业务边界。

样本治理要记录来源和适用范围。用户点击、人工标注、事故复盘、评测失败和业务专家整理，都可以产生训练样本，但置信度不同。线上点击不一定代表正确，用户可能只是点开查看；事故样本很有价值，但通常数量少且分布偏向高风险场景。训练集应保留样本来源、标注人、业务域、时间和使用目的，避免把临时修复样本长期混入通用模型。Hard negative 还要随知识库演进而更新。新产品上线、新政策发布、指标口径调整后，原本不相似的文档可能变成容易混淆的候选。平台应从线上检索失败、人工重排和用户反馈中持续抽取负样本，进入下一轮评测和训练。这样嵌入微调才会跟随业务变化，而非一次训练后长期不动。

17.7 重排模型的上线边界

重排模型可以改善检索结果，但它也会增加延迟和成本。上线前要先判断哪些场景需要重排。普通 FAQ、短文档检索和低风险问答可以只用向量召回；法规、合同、指标口径、技术文档和 DataAgent 证据检索更适合增加重排。重排不应全局打开，而应按知识库、任务类型和风险等级启用。重排结果也要进入 Trace。平台至少记录召回候选、重排分数、最终入选片段和被排除的高分候选。用户质疑引用时，团队需要知道证据是召回不到，还是重排排错，还是上下文组装截断。没有这些记录，重排模型会变成另一个黑盒。上线边界还包括降级策略。重排服务超时或失败时，系统可以退回向量召回结果，但要降低证据置信度；高风险任务则应停止或转人工复核。把重排失败静默隐藏，会让回答质量波动却难以解释。第20章的 RAG 证据链、第38章的 Trace，都需要这层中间证据。

17.8 嵌入微调的评测闭环

嵌入微调的评测不应只看 Recall@K。企业检索更关心证据是否覆盖关键结论、错误证据是否被排除、权限过滤后是否仍能召回足够候选、以及重排后进入上下文的片段是否能支撑回答。一个模型 Recall@10 提升，但把多个口径相近的指标混在一起，对 DataAgent 反而是风险。评测样本要按任务类型分层。事实问答样本关注命中文档，指标解释样本关注口径消歧，合同和政策样本关注条款级证据，DataAgent 样本关注指标、维度和报告证据。每类样本都应保留正例、hard negative 和不可回答样本。不可回答样本很重要，它能验证模型不会把相似但错误的文档强行推到上下文里。评测反馈链路还要连接线上反馈。用户点击引用、人工改引用、报告复核退回、事故复盘发现证据错误，都可以进入样本池。样本进入训练前需要审核，进入评测前需要脱敏和版本化。这样微调才会变成知识检索质量持续改进的机制，而不是一次性模型项目。

17.9 与索引生命周期的协同

嵌入模型升级后，索引生命周期必须同步规划。旧文档向量、新模型 query 向量和新重排模型如果混在一起，检索结果会变得不可解释。平台应为 embedding model、chunk 策略、索引构建任务和 reranker 版本建立组合版本，发布时以组合版本为单位灰度，而非单独替换某个组件。重建索引也要考虑业务连续性。大知识库重建可能需要数小时甚至数天，期间不能让查询在旧索引和新索引之间随机跳转。比较稳妥的做法是构建影子索引，跑评测和抽样比对，确认后按知识库或租户切流。切流后保留旧索引一段时间，便于回滚和事故复盘。索引生命周期还涉及删除和权限变化。某份文档撤回后，向量索引、重排缓存和评测样本都要同步处理；某个部门权限调整后，检索候选也要改变。嵌入微调如果不和这些生命周期事件协同，就会把已失效知识继续推给模型。知识检索的质量，最终取决于模型、索引和治理三者一起稳定。

17.10 微调收益的成本边界

嵌入微调不是每个知识库都需要。若问题主要来自文档缺失、chunk 过粗、权限过滤过严或 query rewrite 偏移，微调不会解决根因。上线前应先用失败样本判断瓶颈：召回不到、召回到了但排序靠后、排序正确但上下文被截断，还是模型没有使用证据。只有瓶颈落在语义匹配和排序阶段，微调或重排才值得投入。成本边界还包括维护成本。训练样本、评测集、索引重建和灰度切流都需要持续维护。小规模、变化频繁的知识库，可能用更好的 chunk、元数据过滤和重排就足够；稳定且高价值的领域知识库，才适合建立专门 embedding 或 reranker。这个判断能防止团队把所有 RAG 问题都推给模型微调。

17.11 生产验证与线上反馈回流

微调和重排上线前，平台需要准备一套生产验证路径。第一步是离线回归，同一批 query 在旧 embedding、旧索引、新 embedding、新索引、旧 reranker、新 reranker 的组合上分别运行，比较 top-k 候选、引用命中、错误候选和权限过滤结果。第二步是 shadow query，把线上真实请求复制到新链路，但不把结果返回给用户，只记录候选差异和延迟变化。第三步是小流量灰度，选择低风险知识库或内部用户，把新链路接入真实回答，并要求 Trace 同时记录旧链路和新链路的关键差异。第四步才是按知识库、租户或任务类型逐步放量。

生产验证不能只看平均指标。合同、财务、HR、DataAgent schema linking 这些场景，即使总体 recall 提升，也不能容忍高风险样本退化。发布报告要把“变好样本”和“变坏样本”分别列出来，并解释变坏样本是否可接受。比如某个客服 FAQ 从 top-8 提升到 top-2 是好事，但如果一个合同续约条款从 top-1 掉到 top-7，且错误候选会误导法律责任，就应停止放量。平台评审要允许局部回滚：某个知识库可以启用新 reranker，另一个知识库继续使用旧版本；某类低风险问答可以使用微调 embedding，高风险合同检索则继续走 baseline 加人工复核。

线上反馈回流要保持克制。用户点击某条引用，不等于这条引用一定正确；用户没有点击，也不代表结果错误。平台可以把点击、复制、人工改引用、点踩、报告复核退回和事故样本都放进候选池，但进入训练集前必须经过抽样复核。反馈回流的价值，是让样本池跟随真实使用变化，而不是让模型盲目学习用户行为。若某个字段长期被用户改引用，可能说明字段说明写得差，也可能说明 query rewrite 把问题改偏了；若某类制度问答经常被驳回，可能需要补文档版本和生效日期，而不是继续训练 embedding。生产验证和反馈回流连起来后，嵌入微调才会成为检索平台的持续工程，而不是一次训练实验。

17.12 发布台账与责任分工

嵌入微调和重排上线后，应进入知识检索发布台账。台账至少记录 embedding 模型、reranker、索引版本、chunk 策略、评测集版本、灰度范围、回滚窗口和业务 owner。它的作用是让检索质量变化能被解释。一次 RAG 回答引用错误时，平台不能只看到“当前知识库版本”，还要能回到当时使用的向量空间、重排模型、权限过滤策略和上下文组装规则。否则团队很容易把问题归因给生成模型，忽略检索链路已经发生变化。

发布台账还要记录责任。数据团队负责文档来源、权限和删除事件；知识工程团队负责 chunk、索引和元数据；模型团队负责 embedding 与 reranker；业务团队负责样本标注和风险接受；平台团队负责灰度、Trace 和回滚。责任分清后，线上反馈才不会全部落到模型团队。比如用户指出引用条款过期，可能需要数据团队更新版本；用户指出字段解释混乱，可能需要业务团队重写说明；用户指出正确证据排在后面，才更像重排或 embedding 问题。

台账也能帮助控制微调冲动。每次质量下降都先回查发布台账：最近是否重建索引，是否换过 chunk 规则，是否新增权限过滤，是否改过 query rewrite，是否更换重排模型。若这些变化没有记录，继续训练模型只会把故障掩盖得更深。早期平台可以先用轻量方式维护台账，把每次知识链路发布和回滚记录成结构化 Markdown 或配置文件，后续再接入发布系统。只要能回答“变了什么、影响谁、怎么退回”，它就已经比散落在聊天记录里的发布说明可靠。

17.13 检索变更的回放样本

嵌入微调、重排和索引切流都需要回放样本。回放样本不能只包含容易命中的 FAQ，还要覆盖字段消歧、指标口径、同名文档、旧版制度、权限边界、不可回答问题和事故样本。每条样本应保存 query、期望证据、不能出现的 hard negative、权限上下文、业务域、风险等级和上一次线上失败原因。这样新 embedding 或 reranker 发布时，团队才能看到它改善了哪些真实问题，又引入了哪些新风险。

回放不能停留在最终答案，还要比较候选变化。旧链路 top-k、新链路 top-k、重排前后顺序、被权限过滤掉的候选、进入上下文的片段、最终引用和回答质量都应放在同一份报告里。若新链路把正确文档从第八名推到第二名，这是质量改善；若它同时把一份无权限文档推到前列，只是被后置过滤挡住，平台也要记录这类风险。检索链路的很多事故发生在“差一点被模型看到”的候选里，发布评审不能只看最终输入给 LLM 的片段。

线上反馈进入回放集前要复核。用户点击、复制、追问和点踩都只是信号，不能直接变成训练标签。平台可以先把这些行为作为候选样本，再由业务或知识工程人员判断真实原因：是文档过期、字段说明不清、chunk 切分错误、权限过滤过严，还是 embedding 匹配不准。经过复核的样本再进入评测和训练，才能让微调和重排沿着正确方向改进。回放集会随着业务变化持续更新，它是知识检索平台的质量资产，不是一次发布的附件。

17.14 向量库迁移与索引版本复盘

向量库迁移不能只比较检索延迟和存储成本。企业知识链路里，向量库承担索引版本、metadata 过滤、权限隔离、混合检索和召回证据。迁移时如果只把向量搬过去，很容易丢掉过滤语义、排序行为或索引构建参数。用户看到的变化通常是“Agent 找资料不稳定”，但根因可能是 HNSW 参数、分片策略、metadata 类型或 rerank 接口改变了。

迁移复盘要保留旧索引和新索引的对比样本。样本应包含 query、用户角色、过滤条件、top-k 文档、分数、rerank 结果、引用命中和权限结果。迁移前后如果候选集变化，要判断变化是否合理；若权限过滤顺序变化，要确认无权文档没有进入模型上下文；若分数分布变化，要调整阈值和降级提示。向量库迁移只有经过这些对比，才能进入生产。

索引版本也要进入生命周期管理。新文档入库、chunk 策略调整、embedding 模型升级、metadata 重建，都应生成索引版本。旧索引在并行窗口结束后要归档或删除，不能无限期占用成本；但删除前要确认历史报告、Trace 和评测样本是否仍需引用。向量库治理的目标，是让检索结果能被解释和回放，而不是只追求更快的相似度搜索。

17.15 微调项目的停止条件

嵌入微调项目还需要明确停止条件。很多团队在检索质量不稳定时会继续收集样本、继续训练、继续调参，却没有判断是否已经到达当前知识库和任务设计能够支持的上限。若文档版本混乱、字段说明缺失、权限过滤错误或 chunk 策略不稳定，继续微调只会把这些问题压进模型空间，短期指标可能变好，长期排查会更困难。

停止条件可以从三个方面设定。第一是质量边界：高风险样本没有退化，核心任务样本达到发布阈值，且不可回答样本没有被强行匹配。第二是成本边界：索引重建、重排延迟、训练样本维护和灰度回滚的成本能被业务价值覆盖。第三是治理边界：模型版本、索引版本、样本版本和权限策略都能被记录和回放。三类条件中任意一类不满足，都应暂停发布，回到文档治理、样本治理或产品边界，而不是继续训练。

这个停止条件也能保护团队注意力。Embedding 和 reranker 是知识检索链路里的重要部件，但它们不是所有问题的答案。一次失败可能来自 query rewrite，也可能来自数据目录、证据组装、权限过滤或最终回答生成。评审时先定位失败阶段，再决定是否微调，才能让模型工作服务于平台质量，而不是把平台治理问题外包给训练任务。

17.16 检索实验的发布纪律

嵌入、重排和混合检索实验很容易在离线环境里越做越复杂。团队会尝试新的 loss、新的 hard negative、新的 reranker、新的 RRF 权重和新的 metadata filter，但如果实验记录无法回到线上链路，最后只能得到一组分数更高、生产风险不清的配置。检索实验从一开始就应记录实验目的、样本版本、模型版本、索引版本、参数、成本、延迟和失败样例。

实验报告要保留反例。只展示提升最大的 query，会让评审高估模型收益。每次实验至少要列出三类样本：明显变好的样本、明显变差的样本、分数变化不大但业务风险高的样本。高风险样本包括合同条款、权限边界、财务指标、HR 制度和 DataAgent schema linking。若这些样本退化，即使平均 nDCG 提升，也不应直接发布。

发布纪律还要求实验能被复现。训练数据、负样本构造、评测脚本、索引构建参数和 reranker 配置都要有版本。实验在 notebook 里跑通不代表能进生产；只有当同一配置能在 CI 或发布流水线中重跑，才具备灰度资格。这样模型团队和平台团队才能围绕同一份证据讨论，而不是各自拿一套脚本解释结果。

检索实验也要有退出路径。某个实验被放弃时，应说明原因：成本过高、延迟超标、高风险样本退化、权限过滤难以解释，还是收益被更简单的 chunk 策略覆盖。记录失败实验不是浪费，它能防止团队几个月后重复同样尝试。企业检索平台的成熟度，体现在实验能否稳定转化为发布候选，也体现在无效方向能否及时停止。

17.17 检索质量的跨团队复盘

嵌入微调和重排进入生产后，质量复盘不应只由模型团队完成。一次引用错误可能来自文档版本，可能来自 chunk 边界，也可能来自 query rewrite、metadata 过滤、权限裁剪、重排阈值或答案生成。若复盘只看模型指标，团队会把所有问题继续推向训练任务。更有效的做法，是把失败样本拆到检索链路的各个阶段：用户问题是否被改写，候选是否召回，正确证据是否被权限过滤，重排是否改变了顺序，上下文组装是否截断，最终回答是否使用了证据。

跨团队复盘要有共同材料。模型团队需要样本和分数，知识工程团队需要文档版本、chunk、metadata 和索引状态，数据治理团队需要权限和删除记录，业务 owner 需要判断证据是否符合业务口径，平台团队需要 Trace、延迟、成本和回滚记录。每次复盘至少应输出三类结论：需要修模型的样本，需要修知识资产的样本，需要修产品边界或权限策略的样本。这样下一轮改进才不会只堆训练数据。

复盘节奏也要跟发布节奏连接。模型升级、索引重建、知识库大批量更新、权限策略调整和 DataAgent 语义层变更后，都应抽样运行检索质量复盘。低风险知识库可以按月复盘，高风险合同、财务、合规和 DataAgent schema linking 场景应在每次发布后复盘。复盘结果进入回放集、发布台账和业务验收材料，形成下一次发布的证据。

早期平台可以从一个轻量机制开始：每周抽取线上失败、人工改引用、报告退回和事故样本，标注失败阶段和责任 owner；每次发布前回放最近一批高风险样本；每次发布后观察变坏样本和用户修正。这个机制不会让检索质量立刻完美，但能让团队知道问题应由哪一层解决。企业检索的长期质量，靠的是这种持续定位和复盘能力，而不是某一次模型微调的分数。

17.18 微调样本的版权与敏感信息复核

嵌入微调和重排训练会收集大量查询、文档片段、点击、人工标注和 Hard Negative。企业内部很容易把这些材料当成普通训练数据处理，但其中可能包含客户名称、合同内容、内部项目、员工信息和受版权保护的文档片段。若样本进入长期训练集，后续模型、评测和迁移都会继承这些风险。检索质量优化必须包含样本合规复核。

复核要发生在样本进入训练集之前。平台应检查样本来源、授权范围、脱敏状态、保留期限、可导出范围和可删除方式。用户查询可以保留语义意图，但要去除个人身份和敏感字段；文档片段可以保留引用 id 和结构标签，但要控制原文暴露；人工标注要记录标注人和使用范围。这样样本既能用于质量改进，又不会在训练资产中扩散敏感信息。

样本合规还会影响模型迁移。若训练集包含只能在某租户内部使用的片段，微调模型就不能直接共享给其他租户；若样本来自受限文档，评测报告也不能随意外发；若用户要求删除相关记录，平台要知道哪些训练样本、评测样本和索引版本受到影响。没有这些记录，后续响应合规请求会非常困难。

早期可以为检索微调样本建立数据卡。数据卡记录来源、范围、脱敏方式、owner、保留时间、删除入口和可共享级别。这样第17章的检索优化会和第50章安全治理、第52章合规审计形成连接，避免把质量提升建立在不可控样本上。

17.19 微调样本的合规复核

嵌入微调和重排训练会把企业样本带入模型优化流程。样本可能包含客户名称、合同条款、内部制度、审批意见和用户查询。即使训练目标只是改善排序，样本仍然需要合规复核。平台要确认样本来源、脱敏方式、授权范围、保留时间和可删除路径，不能把线上失败样本直接汇总成训练集。

合规复核要和样本价值一起看。有些样本对检索质量很有价值，但包含敏感字段，可以通过脱敏、字段替换或只保留结构特征进入训练；有些样本包含过期口径或争议事实，不能进入正样本；有些样本来自人工裁定，可以作为高价值标注，但要保留裁定 owner 和适用范围。训练数据的质量不只影响效果，也影响后续审计。

早期可以为微调样本建立准入状态：候选、已脱敏、已授权、已训练、需删除、已退役。每个状态记录样本来源、用途、数据域和 owner。这样嵌入微调不会成为绕过数据治理的捷径，而会成为可审计的检索质量改进流程。

17.20 嵌入微调后的检索复测

嵌入微调进入生产后，平台需要把训练样本、负样本、召回集合、线上查询、权限过滤、索引版本和回滚模型放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。

这类证据应和第16章嵌入模型、第18章向量库和第20章 RAG连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。

常见风险包括离线指标提升但线上召回变差、热门查询变好长尾查询变差、微调后权限过滤样本缺失。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。

嵌入模型更新应和向量索引、RAG 样本、权限样本一起复测。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。

落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。

本章小结

Embedding 微调适合解决稳定、可标注、可复现的领域语义问题；reranker 适合在正确候选已经进入 top-k 后提升前排证据质量。两者都不能绕开样本治理、权限审计和版本回滚。企业平台应先建立 baseline，再用 hard negatives 找到真实边界。微调前要区分召回不到、排序靠后、候选不可用、权限过滤不足等错误类型，因为它们对应的修复手段不同。Hard negative 也应成为有来源、复核和版本记录的资产。新的 embedding 模型需要新建索引或双写灰度，不能混进旧向量空间。微调、重排、索引和 chunk 策略应进入同一份评测报告，由数据和证据说明是否值得发布。

参考文献

• Sentence Transformers Training Overview: https://www.sbert.net/docs/sentence_transformer/training_overview.html

• Sentence Transformers Losses: https://www.sbert.net/docs/package_reference/sentence_transformer/losses.html

• Sentence Transformers Retrieve & Re-Rank: https://www.sbert.net/examples/sentence_transformer/applications/retrieve_rerank/README.html

• Cohere Rerank: https://docs.cohere.com/docs/reranking-with-cohere

• BAAI bge-reranker model cards: https://huggingface.co/BAAI

第18章 向量数据库与索引算法

向量数据库承接 RAG 中的检索执行。Embedding 生成、答案判断、权限裁决和血缘解释仍由其他组件负责。向量库接收向量、metadata 和索引参数，在权限、延迟、召回质量和成本之间做工程折中。如果平台团队一上来只问“Milvus、Qdrant、pgvector、Weaviate 选哪个”，就已经跳过了更重要的问题：数据规模多大，查询是否需要强过滤，是否多租户，是否要求事务一致性，是否能接受索引重建窗口，是否需要和传统搜索合并。

向量库事故通常不会以“数据库坏了”的形式出现。更常见的是业务用户看到一段无权文档的影子，DataAgent 召回了过期字段，客服助手引用了旧制度，或者模型升级后同一个问题突然命中另一批 chunk。排障时团队才发现，向量记录里没有源文档版本，metadata 里缺少部门权限，索引没有绑定 embedding 模型，检索日志只保存了最终答案。系统看起来在正常返回结果，实际已经失去可解释性。这也是向量库和普通缓存的区别。缓存错了可以清掉，向量索引错了会影响召回、引用、评测和审计。一个文档解析修复后，旧 chunk 是否仍在索引里；一个字段权限变化后，旧向量是否还带着旧 ACL；一个 embedding 模型升级后，新 query 是否还在打旧索引；一个租户删除数据后，评测样本和重排缓存是否同步清理。这些问题都落在向量库生命周期里，而非单纯的 ANN 算法选择。

企业语义检索还要面对成本压力。维度越高，内存和存储越贵；top-k 越大，重排和上下文组装越重；metadata filter 越复杂，召回和延迟越难兼顾；索引副本越多，灰度和回滚越稳，但成本也会上升。HNSW、IVF、PQ、DiskANN 等路线都要放进同一张工程账单里评估：召回率、p95、内存、构建时间、删除延迟、回滚窗口和团队运维能力缺一不可。只看算法名称会遮住真正的风险，因为同一个 HNSW 配置在无过滤公开数据集上表现很好，到了带租户、部门和生效时间过滤的企业数据里，可能完全不是同一条曲线。

本章讨论向量数据库、ANN 索引、HNSW、元数据过滤、多租户权限和向量库选型。读者需要把向量库看成知识基础设施：它保存向量，也保存版本、权限、来源、过滤条件和回放证据。选型结论应来自当前规模、权限要求、运维能力和成本边界，而不是来自某个数据库的宣传指标。一个适合早期平台的向量库，未必是公开 benchmark 里最强的系统；它更可能是能稳定完成过滤、回放、删除、灰度和成本治理的组件。

18.1 向量库平台定位

企业向量库应作为平台组件管理，不能停留在某个应用的私有缓存。知识库、客服、法务、DataAgent、推荐去重都可能共享 embedding 服务和向量索引能力，但它们的权限、更新频率和质量目标不同。平台层要提供统一的写入契约、查询契约、版本契约和观测指标。DataAgent 对向量库的要求和普通知识库不同。字段、指标、SQL 示例、报表截图和业务术语经常来自不同系统，更新频率也不同；字段级权限和租户隔离要进入 metadata filter；同一个业务问题还可能同时检索语义层、历史 SQL、数据质量规则和指标血缘。因此 DataAgent 的向量库更接近语义层候选索引，按普通文档索引处理会漏掉口径、字段和权限约束。

如果这层边界没有设计清楚，事故通常不会表现成“向量库故障”，而会表现成更难追查的业务错误。一个常见路径是：某个部门的制度片段因为 metadata 缺少 department_id 被写入共享 collection，检索时又只做 post-filter，服务日志和 trace 里已经记录了无权候选；模型即使没有把内容完整说出来，候选片段也已经进入了不可见用户的排障链路。另一个路径是索引没有绑定 embedding 模型版本，模型升级后新旧向量混在一起，召回结果突然偏向历史样例，DataAgent 生成 SQL 时沿用了过期字段。平台层的职责，是把这些风险提前变成 schema、过滤、版本和观测约束。讨论选型前，先要像表18-1 一样划清向量库的职责边界，尤其要写清楚它“不负责什么”。否则团队很容易把 embedding 生成、权限系统、答案正确性和数据血缘都塞给向量库。

表18-1：向量库在企业平台中的职责。来源：本书整理。

职责边界确定后，平台负责人才能做选型判断。这里关注“什么时候该建设共享平台、什么时候可以用轻量方案”，不单纯比较数据库品牌。中小规模、强 SQL/事务/元数据需求的场景，通常可以先用 pgvector 起步；当多个业务共享索引、大规模检索和高 QPS 成为主要矛盾时，再评估 Milvus、Qdrant 或 Vespa。是否建设统一向量平台，也不取决于技术偏好，而取决于多个业务是否共同需要 embedding、索引、权限、评测和回滚。单应用试点没有必要提前平台化，但一旦知识库、DataAgent 和客服助手开始共用索引能力，就要把 collection、版本和过滤字段纳入统一治理。

安全和成本是选型时最容易被低估的两条线。安全上，高风险场景不允许无权候选进入模型、日志或 trace，因此 pre-filter 通常比 post-filter 更稳。成本上，维度、索引类型、过滤策略、top-k 和 reranker 都会影响内存和延迟，不能只看向量库标称 QPS。最小治理要求也要提前写清：每个索引都应记录 embedding 模型版本、chunk 策略、metadata schema、构建时间、评测结果和回滚窗口。先定义平台边界，再把边界转成投入决策。没有这个顺序，团队很容易一上来讨论 Milvus 或 pgvector，却没有说清楚谁负责索引版本、权限过滤和回滚。放到图 18-1 的平台位置中看，向量库的核心接口是带着 metadata、权限、版本和指标完成可治理检索，而非简单存一条向量。

图18-1：向量库在企业 Agent 平台中的位置。来源：本书自绘。Alt text：分层图中向量库位于嵌入服务之下、RAG 与知识助手之上，存储向量与元数据并对外提供带权限过滤的检索接口，标出其"可检索知识存储"职责。

平台化之后，这些能力还要能像图 18-2 那样被运维和治理界面管理。多租户、collection、索引版本、过滤字段和观测指标如果都散落在各应用配置文件里，向量库就很难成为共享平台能力。

图18-2：企业向量库多租户控制台。来源：产品界面截图。Alt text：控制台界面展示按租户划分的集合列表、向量规模、索引类型与权限配置，体现向量库以租户为单位做隔离与配额管理。

18.2 ANN 索引算法谱系

向量检索的核心难点是规模。少量向量可以精确计算相似度；百万、千万、亿级向量就要用 Approximate Nearest Neighbor，牺牲一点召回换取可接受的延迟和成本。Milvus、Qdrant、Weaviate、Vespa、pgvector 等系统暴露的索引名称不同，但底层取舍大体围绕图索引、倒排聚类、量化压缩和磁盘索引展开。理解 ANN 时，先用表18-2 建立共同的算法语言，比直接给出唯一答案更重要。HNSW、IVF、PQ、磁盘索引和精确检索分别对应不同的内存、构建、召回和延迟取舍。

表18-2：ANN 索引算法谱系。来源：本书整理。

企业不必在第一天追求最复杂的索引。更可靠的路线是小规模数据用精确或 HNSW 建 baseline，拿内部 query 集测 recall@k 和 p95；规模上来后再评估 IVF/PQ、分片、磁盘索引和冷热分层。索引参数不是一次性配置，它会和 embedding 模型、维度、metadata 过滤、top-k、reranker 一起变化。内部 query 集要来自真实任务，不能临时写几十个自然语言问题充数。向量库的召回错误往往只在边界问题上暴露：字段名相似但含义不同、合同条款编号相近、制度版本相互覆盖、用户问题同时带时间和权限约束。HNSW 的 ef_search 调高后召回可能改善，但 p95 和内存也会上升；IVF 的聚类桶设置不当时，热门问题看起来正常，长尾实体却会漏召回；量化压缩节省成本，却可能让相近指标或相似条款的分数顺序颠倒。这些取舍不能靠默认参数判断，必须用带标签的 query 集和失败样例回放来确认。选型讨论应从召回、内存、构建时间和延迟开始，而不应停留在算法名。图 18-3 的索引谱系把这些取舍放在同一张图里，方便团队先对齐问题，再讨论具体实现。

图18-3：ANN 索引算法谱系图。来源：本书自绘。Alt text：树状谱系把 ANN 索引分为基于图（HNSW）、基于量化（IVF-PQ）、基于树/哈希等分支，每个叶子标注召回、延迟、内存特征，展示索引家族关系。

18.3 主流向量库技术选型

主流向量库的差异不只在索引算法。pgvector 的优势是和 PostgreSQL 数据、事务、SQL 权限靠得近；Milvus 更偏大规模向量基础设施；Qdrant 强调 payload/filter 和服务化向量检索；Weaviate 提供 schema、向量化模块和 GraphQL/REST 能力；Vespa 更像搜索与推荐平台，适合复杂 ranking；Chroma 更适合原型和轻量开发。

表18-3 回到企业约束比较工具路线，并延续前面的职责边界和索引取舍。这里不讨论“谁最好”，而是判断谁更适合当前规模、权限模型、运维能力和 mini-platform 的演进阶段。

表18-3：主流向量库路线取舍表。来源：本书整理。

选型时不要只问“支持 HNSW 吗”。还要追问：metadata filter 在 ANN 前后如何执行，过滤会不会严重降低召回；索引重建能否不停服；租户隔离是 namespace、collection、partition 还是业务字段；备份恢复是否覆盖向量和 metadata；查询日志能否追溯到用户、索引版本和候选列表。对企业平台来说，轻量方案和专用向量库之间没有固定答案。早期如果数据量不大、团队已有 PostgreSQL 运维经验，pgvector 往往能更快把事务、权限和备份纳入同一套体系；当索引规模、写入吞吐、多业务隔离和重建窗口成为主要矛盾时，专用向量库才会显示优势。选型评审应要求候选方案跑同一批数据、同一批 query、同一套 filter 和同一套回滚流程，不能拿各自最漂亮的演示结果对比。

还有一个容易忽略的问题：向量库和企业现有搜索系统的关系。很多公司已经有 Elasticsearch、OpenSearch、OLAP 搜索或数据目录检索，向量库不一定要替代它们。更常见的路线是混合检索：关键词检索负责编号、字段、专有名词和精确条件，向量检索负责语义相似和模糊表达，reranker 再统一排序。若团队直接把所有检索迁到向量库，短期看起来架构简单，长期会在精确匹配、权限过滤和可解释性上付出代价。

混合检索的工程难点在合并结果。BM25 找到的是精确词和编号，向量召回找到的是语义近邻，数据目录可能返回字段和指标对象。平台需要统一候选 ID、来源、分数、权限和证据片段，再交给 reranker 或规则排序。否则前端看到的是几路结果拼接，Trace 里也解释不清某个证据为什么排在前面。向量库选型时，要看它能否和这些已有系统组成稳定链路，单库召回只是其中一个指标。因此，向量库选型要和检索链路一起评估。一个方案即使单独 recall 很高，如果难以接入 BM25、数据目录、权限服务和引用校验，也未必适合企业平台。反过来，一个轻量方案只要能稳定支撑混合检索、metadata filter、版本化和回滚，早期就足够使用。

18.4 元数据过滤与多租户权限

向量库中的 metadata 是企业检索的安全边界之一。Qdrant 文档把 filtering 放在向量搜索概念里，Azure AI Search 支持向量搜索和过滤组合，这说明企业搜索需要把“相似度最近”和“是否允许看到”一起处理。同一个 query 在不同用户、部门、租户、时间点下应返回不同候选。metadata 设计可以扩展，但表18-4 里的最小字段集合不能缺少租户、权限、来源、版本和索引治理信息；否则向量库很快会变成无法审计的共享缓存。

表18-4：metadata 字段设计。来源：本书整理。

权限过滤有三种常见策略。Pre-filter 在向量搜索前过滤候选集合，安全性强，但过滤太窄可能影响 ANN 召回。Post-filter 在检索后过滤，召回稳定，但可能让模型或服务看到无权候选。Hybrid filter 把租户、密级等硬边界前置，把状态、时间等软条件后置。高风险场景应优先 pre-filter，宁可召回少一些，也不要泄露候选。这里要看候选何时被系统看见。post-filter 如果只在返回给 LLM 前执行，应用层也许看不到无权内容，但检索服务、重排服务、trace、错误日志和离线评测样本可能已经接触过这些候选。金融、法务、人力和跨租户场景中，硬边界应进入检索条件本身，至少要保证无权向量不会进入后续排序和日志。对状态、时间、标签这类软条件，可以根据召回质量做 hybrid filter，但要记录每次查询实际使用了哪些过滤字段，避免排障时只看到一个 top-k 结果。

过滤策略还会改变产品体验。权限过滤后候选为空时，系统不能简单回答“没有找到相关内容”，因为真实含义可能是“当前权限下没有可见证据”。对于 DataAgent，这两种提示会引导用户采取完全不同的动作：前者让用户换问法，后者让用户申请权限或切换数据域。向量库返回的结果里应包含过滤命中、被过滤计数和空结果原因，前端和 Runtime 才能给出正确恢复路径。图 18-4 中 pre-filter、post-filter 和 hybrid filter 的差异，最好让安全和平台团队一起确认：哪些边界必须在检索前生效，哪些条件可以在召回后参与排序和过滤。

图18-4：metadata filter 与多租户权限边界。来源：本书自绘。Alt text：检索请求带租户与权限标签进入向量库，过滤条件在 ANN 搜索阶段一同生效（而非先召回后过滤），箭头标出无权数据在检索时即被排除。

18.5 索引生命周期治理

索引生命周期比建库更重要。Embedding 模型升级、chunk 策略变化、文档解析修复、权限字段变化、索引参数调整，都会让索引需要重建。平台要把索引当成版本化资产，不能当成一次性缓存。索引生命周期需要按表18-5 拆成阶段管理，这样“重建索引”才会从一次性运维动作变成可评估、可灰度、可回滚的发布流程。

表18-5：索引生命周期阶段。来源：本书整理。

向量库 benchmark 不能只测查询延迟。构建时间、双写成本、切流风险和回滚窗口同样是企业选型指标。索引治理还要处理“数据已经变了，索引还没变”的灰区。权限字段变更后，旧索引里的 chunk 可能仍带着旧 ACL；文档解析器修复表格错误后，旧 chunk 仍然保留错误行列；embedding 模型升级后，相同 query 在新旧索引上的候选排序可能不同。生产系统不能把这些变化都解释成用户问题或模型波动，而要把 source hash、parser version、chunk strategy、embedding model、index parameter 和 ACL schema 写进索引版本。这样出现问题时，团队才能回答是文档源变了、解析变了、向量变了，还是过滤条件变了。生命周期治理还要给“部分重建”留接口。企业知识库很少能停机全量重建：某个部门上传新制度、某个合同模板修订、某个字段权限变化，都只影响一部分 source。平台应支持按 source、tenant、collection 或 index_version 局部重建，并在双写期间比较新旧候选差异。没有局部重建能力，团队要么长期容忍旧索引，要么频繁做高风险全量切换。

局部重建还要和删除语义配合。用户删除一份文档，不代表只从对象存储里删文件；对应 chunk、向量、倒排索引、reranker 缓存、评测样本和报告引用都可能继续存在。权限撤回也是同样问题：业务系统里角色已经变化，旧向量仍带着旧 ACL，就会在检索时制造灰区。向量库接口需要把 delete_by_source、delete_by_acl 和 rebuild_by_source 做成平台能力，不能让每个应用自己清理。mini-platform 的 infra/vectorstore/ 目前保留最小接口骨架：upsert(chunks, embeddings, metadata)、search(query_embedding, filters, top_k)、delete_by_source(source_id)、build_index(index_version)、evaluate(index_version, query_set)。先把接口稳定下来，再适配 pgvector、Qdrant 或 Milvus。

18.6 工程实践：嵌入模型微调 + 向量库 benchmark

Ch17 讨论微调和重排，本章把它和向量库放进同一个 benchmark。企业需要评估的是组合效果：某个 embedding 模型配某个索引类型，在某个 metadata filter 下，能否以可接受成本召回正确证据。

experiment: vectorstore_benchmark
query_set: data/eval/enterprise_queries.jsonl
models:
  - name: bge-m3-baseline
  - name: bge-m3-finetuned
stores:
  - provider: pgvector
    index: hnsw
  - provider: qdrant
    index: hnsw
metrics:
  quality: [recall@10, mrr@10, ndcg@10]
  system: [p50_latency_ms, p95_latency_ms, qps, index_size_mb]
  governance: [filter_hit_rate, acl_violation_count, rebuild_time_min]

图 18-5 中的向量库 benchmark 报告也要沿用这个思路：质量指标、系统指标和治理指标要放在同一页。企业选型需要同时看 recall，也要看延迟、过滤、重建和回滚。

benchmark 还要覆盖写入和更新路径。很多向量库在静态数据集上表现很好，一旦遇到高频增量写入、批量删除、权限字段更新和低峰重建，延迟和召回都会变化。企业选型时应把“白天读、夜间重建、实时写入、紧急删除”这类运行节奏放进测试脚本。否则上线后才发现索引构建占满资源，RAG 查询在业务高峰期抖动，运维团队只能临时扩容。

图18-5：向量库 benchmark 报告总览。来源：本书自绘。Alt text：报告页对比多个向量库在召回率、P95 延迟、写入吞吐、内存占用上的指标曲线，并标注不同索引参数下的取舍点。

18.7 向量检索的运行回放

向量库上线后，平台要能回放一次检索为什么返回这些候选。回放材料至少包括 query 文本、embedding 模型版本、索引版本、过滤条件、top-k、reranker 版本和最终被引用的 chunk。若只保存最终答案，团队无法判断错误来自向量召回、元数据过滤、重排还是回答生成。多租户过滤尤其要进入回放。企业检索常见事故应按召回了用户无权访问的候选，随后在日志、prompt 或调试界面泄露理解，不能停留在完全查不到。向量库应把权限过滤作为查询条件的一部分记录下来，而非在结果返回后由应用层临时删除。这样第38章的 Trace 才能证明无权内容没有进入模型上下文。

回放记录还要保留“被过滤掉的计数”，不能只保存最终候选。比如一次查询在权限过滤前有 80 个候选，过滤后只剩 3 个，用户看到的答案质量差，根因可能是权限过窄、metadata 写错，或者文档没有入库。没有过滤前后的数量和原因，团队会误以为 embedding 模型召回差。对 DataAgent 来说，这个差异会影响澄清策略：系统应该提示“当前权限下证据不足”，避免生成一个看似完整的答案。索引重建也要留版本。文档切分、embedding 模型、维度、归一化策略和元数据 schema 任一变化，都会改变召回结果。生产环境应支持新旧索引并行一段时间，用同一组 query 比较召回差异，再决定切流。否则一次看似普通的重建，可能让 RAG 和 DataAgent 同时出现质量波动。

版本迁移期间还要处理写入一致性。用户在灰度窗口上传新文档，旧索引和新索引是否都写入；某份文档在灰度期间被撤回，两个索引是否都删除；评测用的是哪个索引版本，线上回答又用了哪个版本。这些问题不写清楚，灰度就会变成“随机命中新旧数据”。较稳妥的做法是用组合版本记录 embedding、chunk、parser、metadata schema 和索引参数，并把写入、查询和评测都绑定到组合版本。

18.8 索引选型的生产判断

向量索引选型不能只看 benchmark 排名。企业场景更关心索引能否在数据持续更新、权限过滤、多租户隔离和低峰重建中保持稳定。HNSW、IVF、DiskANN 等索引路线各有适用条件，但最终要落到数据规模、更新频率、过滤复杂度、召回要求和运维能力。一个在公开数据集上召回率很高的索引，如果无法支持高频增量更新，放到企业知识库里可能反而不合适。

评估索引时要把过滤条件纳入测试。企业检索通常先受租户、部门、权限、文档类型、时间范围和业务域约束，然后才在可见候选中比较相似度。若索引库对元数据过滤支持较弱，就会出现两种坏结果：先过滤再检索导致召回不足，先检索再过滤导致结果被权限过滤清空。测试时应使用真实权限分布和文档分布，而非只用平均查询。索引生命周期也影响选型。增量写入、批量删除、重建、压缩、冷热分层和备份恢复都要提前验证。尤其是删除，不能只从业务库删除文档，还要处理向量索引、倒排索引、缓存和摘要。向量库是 RAG 链路的一部分，不是独立存储产品。索引选型如果没有和第20章的证据链、第27章的 Memory、以及第38章的 Trace 连接，后续很难解释一次检索为什么返回这些内容。

18.9 向量检索的质量回放

向量检索质量不能只通过人工感觉判断。一次检索结果应该能回放查询文本、query rewrite、embedding 模型版本、索引版本、过滤条件、召回候选、rerank 分数和最终进入上下文的片段。若回答错误，团队需要知道是文档没有入库、chunk 切分不当、向量召回漏掉、rerank 排错，还是上下文组装时被截断。没有这些中间证据，RAG 调优就会退化成反复改切分长度和 top_k。质量回放还要服务版本比较。更换 embedding 模型、调整 chunk 策略或重建索引后，同一批查询的召回集合会变化。平台应当比较旧版本和新版本的命中文档、片段位置、证据覆盖率和回答质量，而非只看平均相似度。对高风险知识库，还要抽查被新版本排除的旧证据，判断它们是噪声还是被错误丢弃。

这一节的重点是把向量数据库从“黑盒检索组件”变成“可诊断的知识基础设施”。Agent 平台依赖它提供事实证据，用户也会基于这些证据做业务判断。只要检索证据不可回放，后续生成层再稳，也无法建立可信回答。质量回放也能减少无效调参。没有回放时，团队遇到错误回答往往先改 prompt、加 top-k 或换模型；有了回放后，可能会发现正确文档根本没有入库，或者进入了候选但被权限过滤，或者进入上下文前被摘要阶段截断。不同根因对应不同修复动作。把这些证据固定下来，RAG 调优才会从经验尝试变成工程诊断。

18.10 向量库的容量与成本治理

向量库上线后，容量增长通常比团队预期更快。文档版本、切分副本、多模型 embedding、多租户索引、评测样本和缓存都会占用存储。若没有治理，团队会在召回质量下降或成本突然升高时才开始清理。更稳妥的方式是从一开始就记录每个向量的来源、版本、租户、业务域、过期策略和引用状态。成本治理不能简单删除低频文档。低频文档可能是关键合规证据，也可能只在事故复盘时使用。平台应把内容分成热知识、温知识和冷证据：热知识进入在线索引，温知识可以降低副本或使用较慢索引，冷证据保留原文和元数据，在需要时再进入检索链路。这样既能控制成本，也不会破坏证据完整性。向量库治理还要和文档生命周期连接。文档撤回、权限变化、合同到期、政策替换时，索引也要同步更新。只更新业务库而忘记向量索引，是 RAG 系统常见的安全和质量风险。向量库在平台里应按数据基础设施治理，发布、回滚、审计和删除都要有明确接口，不能被当作应用侧附属缓存。

容量治理最终也会影响召回质量。为了省成本盲目压缩向量、合并索引或降低副本，可能让低频但关键的文档更难被召回。平台应把成本调整纳入回归评测，确认压缩前后关键问题仍能命中证据。这样成本优化才不会悄悄牺牲可信回答。成本治理还要给业务一个可解释的选择。高频知识库可以使用更高副本、更快索引和 reranker；低频归档证据可以保留原文、metadata 和冷索引，在需要时再进入在线检索；临时项目知识可以设置过期时间，到期后转入归档或删除。平台需要把成本、响应速度和证据完整性变成可讨论的策略，并把每次策略调整纳入评测和发布记录。因此，向量库的运维指标不应只看存储和 QPS，还要看索引版本、召回覆盖、删除延迟和权限过滤后的空结果比例。这些指标能更早暴露知识基础设施的问题。

18.11 索引发布与删除一致性

向量索引的发布不应被视为后台运维动作。它会改变 RAG、DataAgent、Memory 和知识助手看到的候选证据，也会改变评测样本的命中路径。一个成熟的发布流程至少要记录四类版本：文档解析版本、chunk 策略版本、embedding 模型版本和索引参数版本。只有这些版本被组合起来，团队才能解释一次召回变化到底来自文档、切分、向量表示，还是索引搜索策略。

发布前要准备固定的回放集。回放集不只包含高频问答，还要包含长尾实体、权限边界、旧制度、新制度、同名指标、相似合同条款和已知失败样例。新索引构建完成后，平台应同时运行旧索引和新索引，对比候选文档、候选顺序、过滤前后数量、引用覆盖率和 p95 延迟。差异不一定代表新版本错误，但差异必须能解释。比如新索引召回了更新版本的制度，旧索引召回了历史制度，这是预期变化；如果新索引把某个受限部门的材料排到前列，就要检查 ACL schema、过滤时机和日志脱敏。

删除一致性比发布更容易被忽视。用户撤回文档、合同到期、员工离职、权限角色变更或租户删除数据时，平台必须同时处理原文、chunk、向量、关键词索引、reranker 缓存、评测样本和报告引用。只删除对象存储里的 PDF，旧向量仍可能在检索中出现；只删除向量，旧摘要或旧评测样本仍可能影响后续回答。删除接口应支持按 source、tenant、ACL、index_version 和 retention policy 执行，并在 Trace 中留下删除事件。这样安全审计才能确认敏感材料已经退出在线检索链路。

回滚也要有业务语义。旧索引保留一段时间用于事故恢复，但旧索引可能包含旧权限、旧制度或旧解析错误。平台回滚时不能只切回旧 collection，还要确认旧版本是否仍满足当前权限和合规要求。若回滚会恢复已撤回材料，系统应允许局部回滚：保留旧索引参数和旧 embedding 服务，但应用最新 ACL 与删除清单。这个能力比单纯保留一份快照更难实现，却能避免“为恢复质量而恢复风险”的问题。

对早期平台来说，索引发布可以从较小的治理面开始：每次构建生成发布记录，每次切流绑定回放报告，每次删除生成可审计事件，每次回滚记录影响范围。只要这四类记录稳定存在，后续再接入更复杂的向量库、分片策略和冷热分层，平台仍然能保持证据可解释。

18.12 检索事故的归因分层

向量库事故复盘要先分层归因。第一层看知识是否存在：文档是否入库、解析是否成功、chunk 是否保留关键结构。第二层看可见性：租户、部门、密级、时间范围和文档状态是否把候选正确纳入或排除。第三层看召回与排序：embedding、索引参数、hybrid 检索和 reranker 是否把正确片段推到可用位置。第四层看上下文组装：最终给模型的片段是否包含关键条件，是否被低价值材料挤出窗口。第五层才看生成：模型是否忠实使用了证据。

这种分层能避免把所有问题都推给向量模型。用户投诉引用了旧制度，根因可能是文档生命周期；DataAgent 漏掉字段定义，可能是 chunk 切分或 metadata 错误；普通员工看到无权材料，可能是过滤时机和日志脱敏问题。每次事故都应留下分层标签和修复动作，后续评测集按这些标签组织。这样下一次重建索引、调整 chunk 或更换 reranker 时，团队可以看到具体失败类型是否减少，而不是只看平均 recall。

18.13 知识入库后的质量复盘

知识入库完成后，平台还要复盘解析质量、引用质量和权限质量。很多知识库问题不会在导入当天暴露，而是在用户提出具体问题时出现：段落被切断，表格标题和表体分离，OCR 把金额或日期识别错，扫描件页码丢失，附件版本混在一起，或者无权文档进入候选结果。若复盘只看“导入成功多少文件”，知识工程会停在搬运阶段，无法支撑 RAG、Agent 和 DataAgent 的证据链。

复盘材料应从失败问答和人工修正中收集。用户指出引用不对、人工改选文档、回答缺少页码、审批人要求补来源、RAG 生成了无法追溯的结论，这些都应回到知识库治理。每个样本要记录文档版本、解析器版本、chunk id、页码、标题层级、表格结构、权限标签和修复动作。这样团队才能判断问题来自 OCR、版面解析、chunk 策略、metadata、权限过滤，还是业务文档本身缺少结构。

知识工程还要有发布节奏。新文档类型、新 OCR 模型、新 chunk 规则、新权限字段进入生产前，应先用一组代表性文档回放：制度 PDF、扫描合同、财务表格、图片型报告、邮件附件和多版本文档。回放通过后，再逐步扩大到更多知识域。这样第18章的知识库治理才能和第16章 embedding、第20章 RAG、第38章 Trace、第39章 Eval 连接起来。知识库承担后续智能链路的证据来源，需要保持可引用、可解释、可修复。

18.14 知识库目录与责任分工

知识库治理需要目录。目录记录每个知识域的 owner、文档来源、更新频率、解析策略、权限标签、引用格式、质量样本和下线条件。没有目录时，知识库会变成不断堆积的文件集合，RAG 和 Agent 只能从结果里猜测材料是否可信。目录不必一开始很复杂，但要能回答三个问题：这份知识由谁负责，什么时候更新，出了引用问题找谁修。

责任分工也要写清。业务团队负责材料真实性和更新节奏，数据或知识工程团队负责解析、chunk、metadata 和索引，安全团队负责权限标签和外发边界，平台团队负责检索、引用、Trace 和评测回流。若这些责任混在一起，常见结果是文档有人上传、没人维护，检索有人使用、没人解释，错误有人发现、没人修复。

知识库目录还要支持下线。过期制度、旧合同模板、废弃产品手册、已替换的流程说明，都不应长期留在在线索引里。下线时要检查历史报告和 Trace 是否仍需引用，必要时保留静态归档，同时阻止新 Agent 继续使用。这样知识库既能沉淀经验，也能避免过期资料污染后续回答。

18.15 向量库变更的灰度窗口

向量库变更需要灰度窗口。索引算法、embedding 版本、分片策略、metadata 字段、过滤顺序和混合检索权重都会改变候选集合。变更看起来只是基础设施调整，用户感受到的却是“资料找不准”或“引用变了”。因此，灰度时要同时保留旧索引和新索引，对同一批 query 比较候选、分数、过滤结果、进入上下文的片段和最终引用。

灰度窗口还要保护权限。新索引可能正确召回更多文档，也可能把无权限候选推到更靠前的位置，虽然最终被过滤掉，但已经暴露出策略顺序的风险。平台应记录被过滤候选和原因，特别是高分但无权限的结果。若这类结果增多，需要检查 metadata 写入、租户隔离和过滤执行位置，而不是只看最终回答是否泄漏。

早期向量库灰度可以按知识库或租户切流。先用影子查询记录差异，再让内部用户或低风险知识库进入新索引，最后扩大范围。旧索引保留到新版本稳定后再归档，并记录哪些历史 Trace 仍依赖旧索引。这样向量库变更才有回滚路径，也能让检索质量变化被解释。

18.16 索引分片与租户隔离的运行校验

向量库的多租户隔离不能只依赖应用层过滤。知识库规模扩大后，平台通常会按租户、知识域、权限等级、语言、文档类型或 embedding 版本做分片。分片能降低查询成本，也能减少误召回，但它会引入新的运行风险：路由选错分片、metadata 写入不完整、过滤顺序变化、索引重建漏掉某个租户、删除请求只清理了主索引却没有清理副本。这些问题在功能测试里不一定出现，生产里却会直接影响权限和引用可信度。

运行校验要同时检查召回和隔离。平台可以为每个租户准备允许样本、拒绝样本和边界样本。允许样本确认正确材料能被召回，拒绝样本确认其他租户或无权限文档不会进入候选，边界样本检查共享知识、集团制度、跨部门项目和临时授权材料。测试结果要覆盖最终答案、候选集合、过滤原因、重排结果和进入上下文的片段。若无权限文档经常出现在高分候选里，即使最终被过滤，也说明分片或 metadata 策略需要复核。

分片策略还要和删除、迁移、重建联动。租户迁移到新索引时，旧索引要有清理计划；文档删除时，主索引、缓存、reranker 样本和历史引用都要标记；embedding 模型升级时，新旧分片不能混合比较分数。对高风险知识库，重建期间可以保留只读旧索引，同时让新索引走影子查询。这样用户继续得到稳定回答，平台也能观察新索引是否改变权限命中和引用质量。

早期可以把隔离校验接入发布门禁。每次新增租户、调整分片规则、升级 embedding 或重建索引，都跑一组租户隔离样本，输出召回、过滤和上下文差异。这个门禁不会替代安全评审，但能把向量库的权限风险从“上线后看有没有泄漏”提前到“发布前看候选是否已经异常”。这才符合企业知识检索的风险边界。

18.17 检索缓存与索引版本证据

向量检索进入生产后，缓存会影响证据解释。用户连续追问时，系统可能复用上一轮召回结果；高频知识问答中，平台可能缓存 TopK 文档片段；报告生成时，多个段落可能共享同一组检索结果。缓存能降低延迟和成本，但如果没有索引版本、过滤条件和权限上下文，后续复盘就无法判断回答引用的是哪一版知识。

检索缓存至少要记录查询文本、改写后的检索 query、嵌入模型版本、索引版本、租户过滤、元数据过滤、TopK 结果、得分、生成时间和失效条件。若知识库重新分块、重新嵌入或删除文档，旧缓存应按版本失效；若用户权限变化，缓存也不能继续复用。对于高风险知识问答，缓存结果还应记录是否经过人工复核或报告发布。这样缓存不会把旧文档片段当作新证据继续传播。

缓存策略要和索引生命周期配合。索引灰度期间，平台可能同时存在旧索引和新索引；如果缓存没有版本标签，用户会在同一会话中看到两个索引的混合结果。删除文档时也要处理缓存，否则已删除内容仍可能被回答引用。平台应让 Retriever、Generator 和 Trace 都能看到 index_version 和 cache_source，让回答层知道当前证据来自实时检索、同会话缓存还是历史 artifact。

早期可以先对核心知识库启用检索证据记录。每次缓存命中都写入 Trace，并保留可回放的索引版本和文档引用。这样第18章的向量库治理会连接到第20章 RAG 证据链和第38章 Trace，而不是把缓存当作纯性能优化。

18.18 向量索引变更的线上灰度

向量索引变更会影响用户看到的证据。更换 embedding 模型、调整 chunk、改变 metadata 过滤、增加 hybrid 权重、重建索引或更新 reranker，都可能让召回候选发生变化。若平台一次性替换全量索引，线上答案变化很难解释。索引变更应像模型变更一样灰度发布，保留旧索引和新索引的对照样本。

灰度时要比较证据而不只比较答案。平台应记录旧索引召回的文档、新索引召回的文档、交集、差异、引用覆盖、权限过滤和最终回答变化。若新索引让答案更完整，但丢掉了某些高风险制度条款，不能直接发布；若新索引召回更广，却增加了无关候选，生成阶段可能更容易混淆。索引评估要同时看召回、精度、引用可用性和成本。

早期可以维护 shadow retrieval。真实请求仍使用旧索引回答，同时后台用新索引检索并记录差异。差异进入评测样本和人工抽检。等关键样本通过后，再按租户、知识域或任务类型切换。这样向量索引变更会变成可解释的发布动作，而不是一次不可回放的重建。

18.19 向量索引的线上健康信号

向量索引进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把召回样本、过滤命中、延迟、索引版本、删除回执和缓存命中记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第16章嵌入模型、第20章 RAG 和第21章知识工程相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括召回下降被当成模型问题、删除只影响主库、租户过滤在缓存层失效。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

向量库运营应同时看质量、权限和生命周期，不能只看吞吐与延迟。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

18.20 索引退役前的影响扫描

向量索引退役前要做影响扫描。一个旧索引可能已经不再服务主路径，却仍被某些低频 Agent、评测样本、历史报告或灰度租户引用。直接删除会让问题在很晚之后才暴露。平台应先扫描调用日志、配置、缓存、评测集和文档链接，确认哪些路径仍依赖旧索引。

影响扫描还要说明替代路径。若新索引使用不同嵌入模型，召回样本要重新跑；若元数据字段改变，权限过滤样本要重新验收；若历史 artifact 需要解释旧答案，旧索引版本和构建参数应保留在审计记录中。早期可以把索引退役做成小型发布流程，保证知识检索能力可以收缩，也能解释历史结果。

本章小结

向量库的价值不在存放向量本身，而在于把语义候选检索做成可扩展、可治理、可回滚的平台能力。HNSW、IVF、PQ 等算法路线要和召回、成本、延迟一起评估；metadata 过滤、多租户权限、索引版本、重建和 benchmark 也要放进同一套生命周期。向量库负责候选检索，不负责 embedding 生成，也不负责最终业务判断。ANN 参数需要和 embedding 模型、维度、过滤策略、top-k、reranker 一起调优。高风险场景中，metadata filter 是权限边界的一部分，通常应优先采用 pre-filter。索引版本是生产资产。模型、chunk 策略或权限过滤方式变化时，应通过重建、双写或灰度完成迁移，而非把新旧向量混在同一个空间里。

参考文献

• pgvector: https://github.com/pgvector/pgvector

• Milvus Index Documentation: https://milvus.io/docs/index.md

• Qdrant Filtering: https://qdrant.tech/documentation/search/filtering/

• Weaviate Documentation: https://weaviate.io/developers/weaviate

• Vespa Approximate Nearest Neighbor Search: https://docs.vespa.ai/en/nearest-neighbor-search.html

• Azure AI Search Vector Search: https://learn.microsoft.com/en-us/azure/search/vector-search-overview

第19章 文档解析与多模态 OCR

很多 RAG 失败发生在文档解析阶段，而非模型回答阶段。合同页眉页脚混进正文，表格被按行打散，扫描件漏掉印章，PDF 的两栏文本顺序错乱，PPT 截图里的指标没有 OCR 出来。向量库和 reranker 无法修复这些底层噪声。它们只能在已经被解析出来的内容里排序，不能找回被漏掉的表格单元格，也不能知道一段文字原本来自脚注、附件还是扫描批注。

企业知识大量沉在版式复杂的 PDF、表格、截图和扫描件里。制度文档看似是文本，实际上有目录、页眉、脚注和修订记录；合同看似是条款，实际上有附件、跨页表格、印章和签署页；财务报表看似是数字，实际上指标口径常写在表头、图例和脚注里；运维截图看似只是图片，实际上包含告警、时间戳、服务名和人工标注。解析系统如果把这些材料统一压成一段 Markdown，下游模型会得到“可读文本”，却失去可复核证据。

DataAgent 对解析质量尤其敏感。一个报表截图里的“净销售额”如果被 OCR 成“销售额”，后续 schema linking 可能连到错误指标；一个跨页表格如果丢掉表头，SQL 生成器会拿到数值，却不知道单位、期间和适用范围；一个合同金额如果没有页码和 bbox，法务或财务复核时就无法回到原文。很多团队把这些问题归因于“模型幻觉”，实际根因在更前面的解析产物不完整。

文档解析与多模态 OCR 的工程边界，落在几个具体问题上：表格、多栏、印章和扫描噪声如何处理；传统 OCR、版面分析和 VLM 解析各自适合什么场景；解析结果如何保留页码、区域、表格结构、权限和版本；质量门禁如何判断哪些内容可以自动进入索引，哪些必须进入人工复核。解析链路做不好，后续的 embedding、RAG、GraphRAG 和 EvidenceRef 都会建立在不可靠材料上。本章讨论文档解析、OCR、版面分析、VLM 解析、表格还原和证据可溯源。读者需要把“识别出文字”与“生成可用知识资产”区分开：前者只是把页面变成文本，后者还要让每个 chunk、表格和字段都能回到来源、权限、坐标和解析版本。只有先把文档变成可检索、可引用、可审计的结构化对象，企业知识工程才有可靠底座。

19.1 企业文档解析挑战

企业文档不是纯文本集合。制度、合同、发票、报表、PPT、看板截图、手写巡检单、邮件附件混在一起，格式、权限和证据要求都不一样。unstructured、LlamaParse、PyMuPDF、PaddleOCR、Marker、Nougat、Donut、Qwen-VL 这类工具解决的是不同层的问题，选型时要先分清它们所在的环节。文档解析的选型应从表19-1 这类失败后果倒推。工具功能表只能说明“能做什么”，失败后果才能说明“错了以后会影响谁”。选型评审最好先拿真实文档做失败复盘。合同团队关心金额、日期、条款编号和签章；财务团队关心表格行列、单位、期间和汇总关系；知识库团队关心标题层级、段落顺序和引用页码；安全团队关心 ACL、源文件版本和日志留存。不同角色对“解析成功”的定义不同，平台要把这些要求汇到同一份数据契约里。

表19-1：企业文档解析的典型失败模式。来源：本书整理。

失败模式明确后，平台负责人要做文档分流，而非把所有文件都自动入库。制度和手册可以先自动解析，因为它们通常版式稳定、复核成本可控；合同、票据和审计材料则要设置质量门禁和人工复核，因为一个金额、日期或条款识别错误就可能影响业务判断。复杂截图和图表可以引入 VLM，但 VLM 输出只能作为候选解释，金额、日期、条款和指标仍要回到 OCR、规则和结构化校验。解析质量对 ROI 的影响也要前置评估：解析错误会一路放大到 embedding、RAG 和 GraphRAG，很多时候先修解析比反复调 prompt 更有效。

安全边界同样不能后置。原文、页面图片、OCR 文本、chunk 和 trace 都可能含敏感信息，ACL 必须从源文档继承，而不能等到检索阶段再补。早期上线的最低门槛是：chunk 能回到页码和 bbox，表格有结构，低置信区域可进入复核队列，解析版本可追踪。达不到这些条件的材料，不应进入高风险回答链路。文档解析的基本原则是先控制失败后果，再选择自动化程度。否则系统会把解析错误包装成“检索质量差”或“模型幻觉”，排障成本会高很多。回到图 19-1 的 RAG 前置链路，原始文件进入向量库之前，需要先完成解析、结构化、质量门禁和权限继承。

实际项目里，最容易被低估的是“看起来解析成功”的错误。合同中一个跨页表格如果被拆成两段，付款条件和违约责任可能分别落进不同 chunk；制度文档的页眉如果反复进入正文，检索结果会被重复标题污染；报表截图里的小字注释如果没有识别，DataAgent 会拿到指标数值却丢掉口径限定。系统层面看到的只是入库任务成功、向量数量正常、RAG 有返回，业务层面却会得到无法复核的答案。因此解析阶段需要把失败模式显式记录下来，而非把所有文件都当作普通文本吞进去。

图19-1：企业文档解析流水线。来源：本书自绘。Alt text：横向流水线依次为文件接入、格式识别、版面分析/OCR、结构还原（表格/标题/段落）、分块入库，箭头表示原始文档逐步转为带结构的可检索对象。

同一条流水线落到图 19-2 中的不同文档类型上，还要配置不同解析策略和复核要求。制度文档、合同、票据、看板截图不应该共用同一套固定切分逻辑。这类分流最好在文件接入时就发生。上传入口可以要求用户选择文档类型、业务域、敏感等级和用途；平台根据这些信息选择解析器、质量门禁和复核路径。合同进入合同解析策略，票据进入票据字段校验，看板截图进入视觉理解和指标确认，普通制度进入文本和标题层级解析。文件一旦被错误分流，后续再靠模型判断会更难，也更难解释为什么某个文档没有进入索引。

图19-2：企业文档类型矩阵。来源：本书自绘。Alt text：矩阵以"版式复杂度"和"是否扫描件"为轴，把合同、报表、手册、截图、票据等文档类型落入不同象限，各象限标注推荐的解析方式。

19.2 文档结构与版面语义

文档解析要输出结构化结果。一个可用的解析结果至少包含页面、区域、标题层级、段落、表格、图片、脚注、页码、坐标和来源版本。RAG 的引用证据最好能回到“第几页、第几个区域、哪个表格单元格”，而非一段拼接文本。这些结构可以像表19-2 那样拆成稳定对象，为后续 chunk、embedding、引用高亮和质量门禁提供统一数据契约。

表19-2：解析对象的数据结构。来源：本书整理。

表里的对象用于保留可复核路径，而非为了让数据模型看起来完整。如果一个答案引用了合同里的付款条款，系统要能定位到原始 PDF 的页码和区域；如果 DataAgent 使用了报表截图里的指标，系统要能说明 OCR 识别结果来自哪个图表区域。缺少这条路径，RAG 只能把不可验证的文本交给模型。页码和 bbox 是生产证据的一部分，不能只作为界面高亮信息处理。审计人员复核答案时，通常不会接受“来自某份合同的某段文本”这种模糊来源；业务用户也需要知道引用内容来自正文、脚注、附件还是扫描件批注。bbox 能把 chunk、OCR 文字、表格单元格和页面截图重新连起来，后续做引用高亮、人工复核、低置信区域标注，或对比不同解析器版本，都要依赖这个坐标。只保留纯文本会让系统在上线早期显得轻便，但争议答案、合规审计和解析回归都会暴露证据链缺口。

DataAgent 场景尤其依赖表格和版面。很多指标口径写在报表脚注、表格表头、图例和截图批注中，并不在正文里。解析系统如果只输出连续文本，后续 schema linking 会把“销售额”“净销售额”“含税销售额”混在一起；保留单元格、页码、图表标题和字段来源后，DataAgent 才能把自然语言问题链接到可信指标。因此，页面结构要作为解析产物保留下来。图 19-3 中的标题、段落、表格、图表和页码坐标，都会影响后续 chunk、embedding、引用高亮和人工复核。页面结构也会影响 chunk 策略。标题和正文可以按章节切分，表格要保留行列关系，图表说明要和对应图片绑定，脚注和批注要跟主文建立引用关系。若解析阶段没有这些对象，后续 chunk 只能按长度切，检索时就会把表头、数据和备注拆散。很多“chunk 大小怎么调”的争论，其实应该在版面结构阶段解决。

图19-3：PDF 页面结构解析示意。来源：本书自绘。Alt text：一页 PDF 被识别为标题、正文段落、表格、图、页眉页脚等区块，每个区块标注边界框与阅读顺序，体现版面分析还原文档结构。

19.3 文档解析工具链选型

工具链选型要按文档类型和证据要求来做。PyMuPDF 适合做 PDF 文本、页面和坐标的底层处理；unstructured 适合把多格式文档切成 elements；LlamaParse 适合面向 LLM/RAG 的文档解析服务；PaddleOCR 和 PP-Structure 适合中文 OCR、表格和版面；Marker/Nougat 更偏学术论文、公式和 Markdown 化；VLM 适合复杂页面理解和视觉问答，但成本和稳定性要单独评估。对表19-3 中这些工具做取舍时，要沿用前面定义的数据契约：工具能不能输出页码、坐标、表格结构、权限继承和低置信标记，比“演示效果好不好”更重要。

表19-3：文档解析工具链取舍表。来源：本书整理。

选型时要做小样本评测，不能只看工具演示。每类文档抽 30-100 份，评估文本完整率、表格结构、标题层级、页码坐标、OCR 置信度、解析耗时和人工复核比例。解析工具链一旦进入生产，就要像模型一样版本化：parser version、prompt version、OCR model version、layout strategy 都会影响后续索引。评测样本要刻意包含脏数据：扫描歪斜、低分辨率截图、跨页表格、双栏排版、盖章遮挡、手写批注、附件目录和历史版本模板。每一类样本都要记录期望输出：文本顺序是否正确，表格是否保留行列关系，页码和坐标是否能回到原文，低置信区域是否被标出。这样选型才会从“哪个工具看起来聪明”转向“哪个工具在本企业文档上可控”。解析评测还要分业务等级。普通制度文档可以接受少量格式损失，只要引用能回到页码；合同和票据需要金额、日期、主体和条款编号准确；报表截图需要保留指标名、单位、期间和图例；审计材料则要保留附件、批注和签署信息。把所有文档放进同一个平均准确率里，会掩盖高风险材料的失败。平台应该按文档类型给出不同通过线，避免低风险文档的好成绩抵消高风险文档的错误。

工具链也要考虑数据出域和复核成本。合同、财务单据、人事材料通常不适合直接送到外部解析服务；即使使用 SaaS，也要有脱敏、访问审批和结果留存策略。私有化 OCR 成本更高，但在敏感文档、高批量处理和长期运营中更容易做版本控制。选型评审不能只比较一次解析价格，还要比较人工复核比例、失败样例处理、模型升级后的回归成本，以及是否能把解析结果稳定交给后续 RAG。

19.4 多模态 OCR 与 VLM 解析

OCR 把图像中的文字转出来，版面模型识别区域和阅读顺序，VLM 进一步理解页面里的图表、截图和视觉关系。三者是流水线里的不同层，不是互斥方案。合同金额、票据日期、报表指标这类字段，更适合用 OCR+规则+结构化校验；截图问答、缺陷图片相似、复杂页面描述，可以引入 VLM，但输出应作为候选解释，而非直接作为事实。

表19-4 的重点是边界，而非能力排名。OCR、版面模型、VLM 和结构化校验应协同工作，单一模型很难替代整条解析流水线。

表19-4：OCR、版面模型与 VLM 的边界。来源：本书整理。

质量门禁也要沿着能力边界设计：文字识别看置信度，版面解析看阅读顺序和坐标，VLM 输出看可复核证据，结构化字段看规则校验结果。VLM 在这里更适合做补充理解，而非事实源头。它可以解释截图中的布局、识别图表和文本之间的关系，也可以在复杂页面上给出候选区域；但金额、日期、合同编号、指标值这类字段仍然要回到 OCR 文本、坐标、规则校验和必要的人工复核。否则系统会把“模型看懂了页面”误当成“字段已经被验证”。在高风险文档里，VLM 输出应保留为可复核的候选解释，并和原图区域绑定，避免直接覆盖结构化字段。

VLM 输出还要保留提示词和图像版本。截图裁剪、分辨率压缩、提示词变化都会影响解释结果；如果只保存最终文字，后续无法判断错误来自图像质量、模型理解，还是字段校验缺失。比较稳妥的方式是把 VLM 结果作为 visual_observation 写入解析产物，并记录来源页面、bbox、模型版本和置信说明，再由规则或人工复核决定它能否进入结构化字段。

在 DataAgent 场景中，VLM 更适合处理“图表在说什么”，不适合直接决定“数据应该怎么查”。例如销售看板截图可以帮助系统识别图表标题、异常区域和筛选条件，但最终指标口径仍要回到语义层；巡检图片可以帮助系统定位设备状态，但维修结论仍要回到工单和人工确认。这样前端可以展示视觉证据，后端也不会把视觉解释当成权威字段。落到图 19-4 的流水线上，VLM 负责补充视觉理解，金额、日期、编号和指标则必须回到可验证字段与规则校验。

图19-4：OCR 与 VLM 协作路径。来源：本书自绘。Alt text：流程显示常规文本走 OCR 快速识别，复杂版面或图文混排转交 VLM 理解，结果合并后统一输出，箭头标出按难度分流到两条解析路径。

19.5 解析流水线与质量门禁

文档解析流水线要有质量门禁。门禁的目标不在追求完美，而在判断哪些文档可以自动进入索引，哪些需要人工复核，哪些只能作为低置信候选。企业平台可以把每个文档解析成 parsed_document.json，再生成 chunk、embedding 和引用索引。

{
  "source_id": "contract-2026-001",
  "parser": "pymupdf+paddleocr",
  "parser_version": "2026-06-baseline",
  "pages": 18,
  "quality": {
    "ocr_confidence_avg": 0.93,
    "table_parse_pass_rate": 0.86,
    "low_confidence_blocks": 7,
    "requires_review": true
  },
  "artifacts": {
    "structured_json": "s3://.../parsed.json",
    "page_images": "s3://.../pages/",
    "chunks": "s3://.../chunks.jsonl"
  }
}

质量门禁最终要落成表19-5 这样的可执行检查项，把“解析是否成功”拆成文本、表格、坐标、权限和低置信区域，而非只看任务是否跑完。门禁的结果还要进入运营流程。低置信区域不能只在 JSON 里留下一个数字，而应形成待复核队列：哪个文档、哪一页、哪个区域、哪种错误、谁复核、复核后是否触发重建索引。解析器升级时，也要用同一批样本做回归对比，观察表格结构、阅读顺序、坐标映射和引用命中是否变好。这样解析流水线才会从一次性导入工具变成持续改进的知识生产环节。

上线后的解析系统还要支持例外处理。某些历史扫描件可能永远达不到自动入库阈值，但仍然具有业务价值；某些合同附件只允许特定角色查看，不能因为解析失败就绕过权限；某些低置信字段可以进入候选索引，却不能用于自动回答。平台要把这些例外写成状态，而非让运营人员在线下表格里记录。文档状态、复核结论和索引状态保持一致，后续 RAG 和 DataAgent 才能知道哪些证据可以直接使用，哪些只能提示用户打开原文确认。这类状态还会反向约束索引准入：未复核的低置信表格不应进入字段索引，权限不完整的文档不应进入向量库，缺少页码和坐标的 chunk 不应支持高风险引用。

表19-5：解析质量门禁。来源：本书整理。

mini-platform 后续可以新增 infra/document_parser/，输出统一的 ParsedDocument。Ch20 的 RAG 不直接吃原始 PDF，而是吃 ParsedDocument 产生的 chunk 和 citation spans。这样文档解析、向量索引和答案引用才有清晰边界。ParsedDocument 还应携带状态。parsed 只表示解析完成，review_required 表示需要人工确认，approved_for_search 表示可以进入普通检索，approved_for_high_risk_answer 表示可以支撑高风险回答。不同状态对应不同索引和回答策略。这样低置信文档仍能被人找到，却不会被模型直接用于财务、法务或合规结论。质量门禁的输出也不应该只是一条“解析完成”的任务状态。图 19-5 中的平台团队还要看到低置信区域、表格失败、权限缺失和是否需要人工复核。

图19-5：文档解析质量报告。来源：本书自绘。Alt text：报告页展示字符识别率、表格还原准确率、版面顺序正确率等指标，并列出失败样本缩略图，体现解析质量可量化、可抽检。

解析质量报告还应进入日常运营，而非只在导入当天查看。知识库负责人需要看到哪些文档反复低置信、哪些模板最容易解析失败、哪些部门上传的扫描件需要重新规范；平台团队需要看到 parser 升级后召回质量是否下降，低置信队列是否积压，人工复核是否成为瓶颈。若这些信号没有沉淀，文档解析会变成一次性搬运任务，后续 RAG 和 DataAgent 出错时只能在下游补救。

运营视角还要关注“解析成功但不能用”的材料。比如一个合同被成功转成文本，但缺少页码和坐标；一个表格被转成 Markdown，但合并单元格语义丢失；一个截图被 VLM 描述得很完整，但没有结构化字段和置信度。任务状态显示成功，知识库却不能把它用于高风险回答。质量报告应把这类材料单独列出来，提示它们只能做低风险检索或人工查看。

19.6 文档解析结果的回放边界

文档解析进入 Agent 链路后，平台要能说明一段文本、一个表格或一个金额字段来自原文的哪一页、哪个区域、哪个解析版本。否则 RAG 或 DataAgent 引用了解析结果，业务用户却无法回到原始证据。解析产物应保留页面坐标、块类型、置信度、OCR 引擎版本和人工修正记录。表格解析尤其需要谨慎。很多财务表、合同附件和运营报表的含义来自行列关系、合并单元格和页眉页脚。若只把表格拍平成文本，模型可能读到字段，却丢掉单位、期间或适用范围。更稳的做法是同时保留结构化表格、原始页面截图和文本摘要，让后续检索和报告都能回到证据。解析失败也要可运营。低置信度页面、倾斜扫描、遮挡印章、手写批注和跨页表格，都应进入失败样例库。平台不需要一开始解决所有版式，但要知道哪些文档不能自动进入高风险回答。对合同、票据和审计材料，低置信度解析应触发人工复核，而非让模型根据残缺文本补全结论。

19.7 OCR 质量控制的分层标准

文档解析质量不能只用“识别准确率”概括。企业文档通常包含表格、页眉页脚、印章、批注、脚注、扫描噪声和跨页结构，单个字符识别正确并不代表文档可以进入 RAG。更有用的质量标准应当分层：文本层看字符和段落，版面层看标题、表格、列表和阅读顺序，语义层看字段、实体、金额、日期和条款，证据层看解析结果能否回到原页和坐标。质量门禁也要按用途区分。普通知识检索可以接受少量格式损失，但合同审查、财务票据和监管文件不能丢表格结构和关键字段。对于高风险文档，解析结果进入知识库前应当经过字段校验、页码对齐和抽样人工复核。若系统无法判断某段表格或印章的含义，应当把不确定性保留下来，而非生成一段看似完整的自然语言摘要。OCR 质量控制还需要记录解析版本。模型、规则、版面检测器和后处理逻辑变化后，同一份文档的 chunk 和 EvidenceRef 可能不同。若后续回答引用了旧解析结果，平台必须能找到当时的解析版本。否则用户指出证据页不一致时，团队无法判断是解析变化、索引变化还是生成错误。

19.8 解析产物进入知识库的边界

文档解析不是把 PDF 变成 Markdown 就结束。进入知识库前，平台要决定哪些内容用于检索，哪些内容只作为证据，哪些内容需要脱敏，哪些内容不应进入模型上下文。页眉页脚、目录、重复水印和扫描噪声通常不适合作为检索正文；合同金额、个人信息和内部编号可能需要保留证据但限制可见范围；表格和图注则需要保留结构，不能压成一段普通文本。解析产物还要与权限系统对齐。同一份文档里，不同章节可能属于不同敏感等级，不能只按文件级权限处理。比如一份审计报告的结论页可以给业务负责人阅读，底稿和个人信息页只能给审计团队阅读。若解析时丢掉页码和区域信息，后续就很难做细粒度权限裁剪。文档解析的输出格式应当服务后续 RAG、Trace 和审计，而非只追求文本完整。对于早期平台，可以先把文档解析产物分成正文片段、结构化字段、证据坐标和风险标签四类。正文片段用于检索，结构化字段用于过滤和校验，证据坐标用于回答溯源，风险标签用于权限和脱敏。这个分层简单，但足以避免许多解析结果直接入库带来的问题。

19.9 人工复核与解析样本库

文档解析系统需要人工复核，但复核不应停留在逐页纠错。更有效的方式是把复核结果沉淀成样本库，覆盖常见版式、异常扫描、复杂表格、跨页段落、低质量图片和高风险字段。每次更换 OCR 模型、版面分析器或后处理规则，都用样本库做回归，确认新版本没有破坏旧文档。这样人工复核才会变成工程资产，而非一次性修稿。样本库还应保留失败类型。表格错列、段落顺序错误、金额识别错误、页码丢失、印章误识别、标题层级错误，是不同问题。后续调优时，团队要知道模型改善了哪类问题，又引入了哪类问题。若所有失败都被写成“解析不准”，系统很难持续进步。对于进入 RAG 的文档，人工复核可以先聚焦证据密度高的位置：标题、表格、金额、条款、结论段和引用页。并不是所有文字都需要同等精度，但支撑回答的证据必须可靠。解析样本库的价值就在于把这种取舍显式化。

复核结果还应回写到解析策略。某类表格长期错列，就应调整表格识别或后处理；某类扫描件经常失败，就应在上传阶段提示重新扫描；某类文档不适合自动解析，就应要求人工整理后入库。解析质量治理的目标，是让重复错误在流程里逐步减少，而不是让复核人员长期在同一类页面上返工。这也要求解析系统保存原始文件、解析版本和人工修订记录。没有这些记录，后续很难解释同一份文档为什么在不同时间生成了不同证据片段。

19.10 解析发布与复核运营

解析器升级和索引发布一样，都会改变下游证据。OCR 模型、版面检测器、表格后处理、VLM prompt、Markdown 转换规则和 chunk 生成策略任一变化，都可能让同一份文档产生不同的文本、表格和坐标。若平台只在解析任务成功后覆盖旧结果，后续 RAG 引用会突然换页、DataAgent 字段候选会变化，人工复核也无法判断新旧证据哪个更可信。因此解析产物要按版本发布，不能只按文件覆盖。

发布前的回归集应覆盖真实困难材料：跨页表格、双栏 PDF、盖章合同、扫描歪斜页面、低分辨率截图、带批注的制度、附件目录和历史模板。每次解析器升级后，要比较文本顺序、表格行列、页码坐标、低置信区域、字段抽取和引用命中。对高风险文档，平均准确率不足以说明问题，必须单独检查金额、日期、合同主体、条款编号、指标口径和签章区域。新版本如果提升普通段落识别，却破坏合同附件表格，就不能直接进入生产。

复核运营要有状态机。一个文档可能处于 parsed、review_required、reviewed、approved_for_search、approved_for_high_risk_answer、rejected 等状态。普通检索可以使用 approved_for_search 的材料，高风险回答需要更高门槛；被拒绝的材料可以保留原文和失败原因，但不能进入自动回答链路。状态变化要触发对应动作：批准后写入向量库，修订后重建 chunk，拒绝后从候选索引移除，重新上传后重新评估。只有这样，解析质量门禁才会真正约束 RAG，而不是停留在报告页。

人工复核也要分层。业务专家不应被迫检查所有字符，他们更适合确认表格含义、合同责任、指标口径和低置信字段；平台团队负责解析器版本、坐标映射、入库状态和回归样本；安全或合规团队负责权限继承、敏感区域和留存策略。复核界面应把原图、解析文本、bbox、表格结构、OCR 置信度和下游影响放在一起，让复核人知道自己确认的是哪一类风险。

解析发布还要和第20章的 RAG 评测、第38章的 Trace 连接。一次回答引用了某个 chunk，Trace 中应能看到它来自哪个 parser version、哪次人工复核、哪个页面区域、何时进入索引。用户指出引用页不对时，团队才能判断是解析器升级造成坐标变化，还是索引仍在使用旧 chunk。早期平台可以先把这些信息写进 ParsedDocument 和 chunk metadata，后续再把复核队列和发布记录做成独立运营界面。

19.11 解析事故复盘与下游影响评估

文档解析事故往往在下游才被发现。用户看到引用页不对、表格金额错列、合同条款缺失、图表解释与原图不一致时，问题可能已经经过了解析、chunk、索引、检索和生成多个环节。复盘时不能只问“RAG 为什么答错”，要先把证据链拆开：原始文件是否正确，解析版本是否变化，页码和 bbox 是否保留，表格结构是否被压平，chunk 是否来自最新索引，回答是否引用了低置信区域。只有逐段定位，团队才能判断该修 parser、chunker、retriever、reranker，还是回答模板。

复盘材料应固定下来。一次解析事故至少要保存原文件哈希、解析版本、解析任务 ID、chunk ID、索引版本、回答 Trace、用户反馈和修复动作。若事故来自表格错列，还要保留原图、解析表格和人工修订后的结构；若事故来自权限错误，还要保留文档 ACL、chunk ACL 和当次用户角色；若事故来自 VLM 描述误读，还要保留图像区域和模型输出。没有这些材料，团队很容易在下游 Prompt 上反复修补，却没有消除上游解析缺陷。

下游影响评估要覆盖 RAG、DataAgent 和报告生成。一个解析器升级看似只影响知识库，实际可能改变引用页、实体抽取、语义层字段候选和报告 EvidenceRef。发布前应抽样检查高频文档、高风险模板和近期被用户引用过的材料，确认新版解析不会让旧回答失去依据。若影响范围较大，可以采用双版本索引：新解析结果先进入灰度索引，线上回答继续使用旧索引；当回归样本和人工复核通过后，再切换默认版本。

解析事故还应进入样本库。每一次错页、错表、错字段、错权限都可以变成后续 parser 发布的回归样本。样本要记录失败类型和修复状态，避免下一次升级重新引入同类问题。长期看，解析质量依赖持续积累困难样本、明确人工复核边界、把下游事故反向写回解析流水线，单次模型替换无法解决所有版式问题。这样文档解析才真正成为知识工程的一部分，不会停留在知识库导入前的一次性预处理。

事故复盘还要区分影响等级。错别字和段落顺序问题可能只影响普通检索体验；金额、日期、合同主体、权限标签和页码坐标错误，会直接影响高风险回答和审计。平台可以把事故分成普通修复、索引重建、人工复核和暂停引用几类，避免所有解析问题都进入同一条处理队列。

解析团队还要把事故复盘结果写回上传规范。若同一部门反复上传倾斜扫描件，问题不应只由 OCR 模型承担；若某类历史模板长期无法稳定解析，应该在入库前要求人工整理或标注风险；若某些图表截图经常被误读，应限制它们进入自动回答，只允许作为人工查看材料。这样解析治理才能覆盖文件产生、上传、解析、入库和引用的完整路径。

这类前置治理能减少后续返工，也能让文档生产团队理解哪些材料适合进入自动化知识链路。

19.12 OCR 质量门禁与人工抽检

OCR 进入 Agent 平台后，质量门禁要按文档类型设计。合同、发票、扫描报表、截图、手写批注、图片型 PDF 的错误形态不同。合同更怕金额、日期和主体识别错；发票更怕税号和金额错；报表更怕表格结构和列名错；截图更怕上下文区域缺失。若所有文档都用同一条 OCR 成功率判断，平台会高估高风险材料的可用性。

人工抽检应和 OCR 置信度结合。低置信度字段、关键金额、审批意见、客户名称、法律条款、跨页表格，都应进入抽检候选。抽检结果不只用于当前文档，还要回写解析器评测、版面规则、字段校验和知识库 metadata。若某类扫描件长期失败，应在上传阶段提示用户更换格式或走人工录入，而不是继续把低质量文本送入 RAG。

OCR 质量门禁还要影响下游回答。材料未通过门禁时，Agent 可以说明文档解析质量不足，给出可读页码或请求人工确认；通过门禁但关键字段被人工修正时，回答应引用修正后的字段和修正记录。这样 OCR 不再是隐藏在知识库前面的预处理步骤，而是证据链中可检查的一环。

19.13 解析产物的业务验收样本

OCR 和文档解析的验收样本应来自真实业务材料。合同、发票、制度、报表、扫描件、截图和邮件附件的错误类型不同，通用 OCR 准确率不能说明下游 Agent 是否能使用。业务验收应检查段落结构、表格边界、页码、标题层级、印章签名、金额字段、日期字段和附件关系。若这些结构丢失，后续 RAG 或报告生成即使能读到文字，也很难引用正确证据。

解析产物要和业务任务绑定。合同审阅关注条款、主体、金额和期限；财务报销关注票据字段、发票真伪和附件完整性；制度问答关注版本、生效日期和适用范围；DataAgent 报告关注表格标题、单位和指标口径。不同任务使用不同验收样本，才能判断解析器是否适合进入对应链路。把所有文档都用同一个准确率衡量，会掩盖高风险字段的错误。

早期平台可以建立少量代表性样本包。每个样本包保存原文件、解析结果、人工标注、失败原因、修复记录和适用任务。解析器升级、OCR 模型切换、版面模型调整、文件格式新增时，都要回放这些样本。这样文档解析会从一次性导入能力，变成可持续验证的知识入口。

19.14 解析策略变更的样本回放

OCR 与解析策略升级前，应先明确会影响哪些下游证据。一次版面模型升级可能让段落切分更准确，却改变 chunk 边界；一次表格抽取优化可能提升列识别，却让跨页表格的页码引用发生漂移；一次 VLM 辅助解析可能补出图片说明，也可能把装饰性图形解释成业务事实。对 Agent 平台来说，解析变更的验收要落到检索片段、引用页码、字段值、表格结构和人工复核记录上，单个 OCR 分数无法说明这些证据仍能支撑原有业务回答。

样本回放要覆盖高频材料和高风险材料。高频材料包括制度、产品手册、常用报表、FAQ 和培训文档，它们决定日常问答体验；高风险材料包括合同、发票、审计底稿、审批附件和客户证明，它们决定是否允许自动引用。每次解析策略变更后，平台应比较旧解析结果、新解析结果、人工标注和下游回答样本。若 chunk 边界变化导致原 citation span 失效，索引可以重建，但历史回答需要保留旧解析版本。若字段值变化来自人工标注修正，应把修正记录写入 EvidenceRef，避免系统在下一轮索引时把人工修正覆盖掉。

回放结果还要参与入库决策。解析置信度不足、页码缺失、表格结构不完整或关键字段冲突的文档，不应直接进入自动回答索引。平台可以把它们降级为“可搜索但需人工确认”的材料，或者只允许作为原文附件展示。这样做会降低可回答问题数量，但能减少错误证据进入生产链路。对于业务团队而言，解析策略变更的发布说明也要清楚：哪些文档类型质量提高，哪些材料仍需人工整理，哪些旧索引需要重建，哪些回答样本需要重新验收。文档解析只有和样本回放、证据版本和入库策略连在一起，才能成为可治理的知识入口。

19.15 版式变更的解析回归

企业文档的版式会持续变化。合同模板增加新条款，报销单调整字段位置，扫描件从黑白变成彩色，供应商 PDF 修改页眉页脚，监管表格增加附注列，这些变化都会影响 OCR 和版面解析。解析链路如果只在上线时验证一次，后续知识库会慢慢积累错位表格、漏读字段和错误段落，RAG 或 DataAgent 再把这些内容当作证据使用，问题会被放大到回答层。

版式变更回归要保存原始文件和解析产物。每次模板变化后，团队应抽取代表样本，比较文本块、表格结构、页码、标题层级、图片说明、关键字段和置信度变化。对合同、票据、审计材料和政策文件，还要检查引用位置是否仍能回到原始页。若解析产物只保存纯文本，后续很难判断错误来自 OCR、分块、向量化还是模型理解。解析证据应保留到足以复现下游问题。

回归样本要按文档类型分层。固定模板文档可以用字段级校验，重点看金额、日期、客户、编号和审批结果；半结构化报告要看标题、表格和图注；扫描件要看旋转、模糊、印章遮挡和手写批注；多语言材料要看字符集和段落顺序。不同文档类型使用同一套质量阈值，会让某些风险被掩盖。平台应让每类文档有自己的解析门禁和人工抽检比例。

早期可以先建立“版式变更触发回归”的规则。只要模板版本、供应商来源、扫描渠道或文件类型发生变化，就触发固定样本回放。回放结果写入知识库发布记录，并关联到第20章 RAG 证据链和第38章 Trace。这样 OCR 不再是一次性预处理步骤，而是知识工程中持续维护的证据生产过程。

19.16 OCR 纠错样本与版式回归

OCR 质量问题往往出现在版式细节里。扫描件倾斜、表格跨页、印章遮挡、手写批注、页眉页脚混入正文、金额列错位，都会让后续检索和回答产生错误证据。平台不能只看 OCR 字符准确率，还要维护版式回归样本，检查解析结果是否保留页码、表格结构、坐标、字段关系和置信度。

纠错样本要从真实失败中来。用户框选错误区域、人工修正字段、审核退回报告、RAG 引用错页，都应回收到 OCR 样本库。每条样本要保留原图、解析版本、错误位置、人工修正、影响的下游回答和修复状态。若只保存修正后的文本，团队无法判断问题来自图像预处理、版面分析、表格识别还是后处理规则。

早期可以把高风险文档分成合同、制度、发票、报表和截图五类，每类维护少量版式样本。OCR 模型、解析器或后处理规则变化时，先回放这些样本，再允许新结果进入知识库。这样 OCR 不再是一次性导入步骤，而是知识工程和 RAG 证据链的前置质量门禁。

19.17 解析样本的业务复核机制

OCR 与文档解析进入生产后，新增能力不能只看功能是否可用，还要看运行证据能否被不同角色复用。平台需要把版式类型、字段位置、置信度、人工修订、下游引用和回放结果记录成稳定字段，并和发布单、Trace、评测样本以及事故记录关联起来。这样一次线上问题发生后，团队可以沿着同一组事实判断影响范围、责任归属和修复顺序，而不是在模型日志、业务日志和人工说明之间来回拼接。

这类证据还要服务相邻章节的能力。它和第18章向量库、第20章 RAG 和第21章知识工程相连：上游能力提供输入假设，下游能力使用执行结果，治理能力负责保存证据和复审结论。若这些材料没有统一编号和版本，章节里讨论的工程能力在生产中会被拆散。业务 owner 只能看到用户投诉，平台 owner 只能看到系统错误，安全或合规团队只能看到事后说明，最后很难判断问题到底来自数据、模型、工具、流程还是组织责任。

生产环境中常见的风险包括表格跨页丢列、页眉进入正文、签章被识别成业务字段、低置信度内容进入检索。这些问题在演示阶段不明显，因为演示通常只覆盖成功路径；上线后，用户会带来边界问题、重复请求、权限变化和长时间运行状态。平台团队应把失败样本纳入发布节奏，记录哪些样本需要阻断发布，哪些样本可以通过降级处理，哪些样本需要业务 owner 接受剩余风险。

解析样本库应由业务和数据团队共同维护，不能只由 OCR 工具输出决定。这份记录不需要复杂，但要包含时间、版本、owner、样本、处置动作和下次复查条件。没有这些字段，复盘会停留在口头经验；有了这些字段，平台才能把一次问题转成后续发布、评测和培训材料。

早期平台可以从少量高风险场景开始。先选择调用量高、业务影响大或涉及敏感数据的路径，要求每次变更都留下证据包，再逐步推广到普通场景。这样章节里的能力不会停留在概念层，而会成为可运行、可解释、可退回的工程系统。

19.18 解析质量与知识入库的分离验收

文档解析质量和知识入库质量要分开验收。OCR 或 VLM 能正确识别版式，并不代表内容适合进入知识库；知识库能检索到片段，也不代表片段适合被模型引用。平台需要先验收解析结果是否保留结构、字段、表格和页码，再验收入库后的 chunk、元数据、权限和引用方式。

分离验收可以减少责任混淆。解析错误应回到 OCR 策略和人工抽检；切分错误应回到知识处理流水线；引用错误应回到 RAG 和生成层；权限错误应回到数据治理。若所有问题都被称为“知识库效果不好”，团队会很难判断应该修模型、修解析、修索引还是修权限。

早期可以为重要文档保留两组样本：解析样本和入库样本。解析样本看版式和字段，入库样本看检索和引用。两组样本之间记录文档版本和处理策略。这样第19章可以自然连接第18章向量库、第20章 RAG 和第21章知识工程。

本章小结

文档解析是 RAG 和知识工程的底座。企业不能把 PDF 当纯文本处理，也不能把 VLM 输出直接当事实。更可靠的做法是保留版面结构、页码坐标、表格关系、权限和解析版本，再用质量门禁决定哪些内容可以进入索引。解析链路的成熟度取决于证据能否复核。输出中应包含 page、block、table、figure、chunk 和 citation span；OCR、版面解析、VLM 与结构化校验各有边界，不能互相替代。解析结果也必须版本化，否则索引重建、引用复核和故障回放都无法追踪。早期实现可以先覆盖 PDF 与表格文档的主路径。把页码、坐标、块类型、权限、文件哈希和解析器版本写进 metadata，并把失败样例留给人工复核。等证据链稳定后，再处理跨页表格、复杂版面和图文混排内容。

参考文献

• unstructured partitioning: https://docs.unstructured.io/open-source/core-functionality/partitioning

• LlamaParse documentation: https://docs.llamaindex.ai/en/stable/llama_cloud/llama_parse/

• PyMuPDF documentation: https://pymupdf.readthedocs.io/

• PaddleOCR documentation: https://paddlepaddle.github.io/PaddleOCR/

• ColPali paper: https://arxiv.org/abs/2407.01449

第20章 RAG 工程与高级检索

RAG 容易做出演示，却很难做到企业要求的“答案有据、引用可查、错了能定位”。生产链路要同时处理 chunk、召回、重排、多跳检索、引用校验和检索质量评估。这里把 RAG 视为一条证据工程链路：先决定证据如何被切分和组装，再决定如何召回、排序、追问和校验。制度问答助手试运行时，用户问“供应商合同超过 200 万需要谁审批”。系统召回了采购制度里的相似段落，却漏掉了金额阈值在附件表里的说明，最后给出一个看似有引用、实际缺证据的答案。模型没有凭空编造，问题发生在检索链路：chunk 切分、表格解析、召回、重排和引用校验都没有把关键证据带回来。企业 RAG 不能简化为“向量库 + prompt”。它需要把用户问题转成可检索意图，从多种索引里召回候选，做权限过滤、排序融合、上下文组装、引用校验，再把证据交给 LLM。任何一个环节出问题，最终都会表现成“模型胡说”。

RAG 的演示很容易成功，因为用户常问的几个问题可以被少量文档覆盖。生产环境困难得多：文档格式混杂，表格和附件承载关键条件，权限决定哪些段落可见，制度会更新，用户问题还会跨多个文件。模型最后给出的一句话，背后其实是一条证据链。证据链任何位置断掉，都会表现成“答案有引用但仍然错”。企业 RAG 的工程工作围绕证据管理展开：文档如何解析、chunk 如何切、标题和表格如何保留、召回如何融合关键词和向量、重排如何处理权限、上下文如何组装、引用如何校验，都需要明确决策。只把文档塞进向量库，会把这些决策推迟到事故发生之后。

一个制度问答事故往往能暴露完整问题。用户问审批阈值，系统召回了正文里“重大采购需审批”的段落，却漏掉附件表里的金额和角色；回答看起来有出处，实际缺少决定性证据。修复时如果只改 Prompt，让模型“更谨慎”，效果有限。真正要改的是解析、切分、召回、重排和引用校验。只要其中一个环节粗糙，模型就会在缺证据的地方补全，最终问题仍然会被用户感知为回答错误。

20.1 RAG 工程体系

企业 RAG 至少包含六个层次：文档解析、索引构建、查询理解、候选召回、排序与过滤、答案生成与引用。Azure AI Search 的混合检索、LlamaIndex 和 LangChain 的 retriever 组件、Ragas 的评估指标都指向同一个工程结论：生产 RAG 要评估整条检索链路和证据可信度，不能把问题压到某个 prompt 上。chunk、混合检索、多跳和可信回答，都可以放回图 20-1 的分层链路里定位：文档解析、索引、检索、重排、上下文组装、生成和引用校验分别承担不同责任。

图20-1：企业 RAG 工程体系。来源：本书自绘。Alt text：分层图含离线侧（解析、分块、嵌入、入库）与在线侧（查询改写、混合检索、重排、引用校验、生成），两侧通过向量库衔接，展示 RAG 的完整工程组成。

有了层次，还要像表20-1 一样把每层变成工程接口。生产 RAG 的排障通常就是沿着输入、输出和质量风险逐层定位。

表20-1：RAG 链路职责分解。来源：本书整理。

有了链路职责，平台负责人要讨论的重点会从“用哪个 RAG 框架”转向表20-2 里的判断：哪些环节要做成共享能力，哪些风险必须作为上线门槛。RAG 的故障也要按这条链路拆开看。用户看到“模型编了答案”，背后可能是解析阶段把表格拆坏，索引阶段漏写权限字段，检索阶段只召回了相似但无答案的 chunk，重排阶段把关键证据排到第十一位，上下文组装阶段又把表头丢掉。末端的 LLM 只是把前面链路的缺陷表现出来。生产排障如果只改 prompt，会把问题压回到模型层，下一批文档或下一类问题还会重复出错。

平台负责人做 RAG 决策时，应先判断它是不是共享能力。只要多个业务都依赖文档解析、索引、重排和引用校验，就应平台化；单个问答应用可以先轻量实现，不必一开始建完整 RAG 中台。检索路线也不能只上向量检索。企业知识库、DataAgent 和合规问答经常依赖编号、字段名、合同条款和错误码，关键词检索、向量检索和重排通常要配合使用。高风险场景不应允许无引用回答；普通知识助手即使允许无引用，也应明确标记低置信或无来源。多跳检索也不是越早越好。只有问题天然跨实体、跨文档、跨指标时，才需要拆成多跳；简单 FAQ 被过度拆解，反而会扩大问题范围，引入无关证据。早期最小上线门槛应放在更基础的链路上：权限过滤、引用覆盖、引用一致性检查、拒答策略和失败样例回放。缺少这些能力时，复杂检索策略只会让错误更难定位。chunk 解决证据单元，混合检索解决召回，多跳检索解决复杂问题，可信回答解决证据是否支持结论。换成图 20-2 的企业流程语言，RAG 是一组可检查的证据处理步骤；业务负责人可以沿着这些步骤检查每个环节是否可观测、可审计、可回放。

图20-2：企业 RAG 证据生产线。来源：本书自绘。Alt text：横向流水线从用户问题出发，经检索得到候选片段、重排筛选、附带来源标注，最终生成带引用的答案，箭头强调每个结论都挂上可追溯的证据片段。

20.2 Chunk 策略与上下文组装

Chunk 是 RAG 的基本生产单元。切得太小，语义不完整；切得太大，召回不准、上下文浪费、引用不精确。企业 chunk 策略要从文档结构出发，而非固定每 500 字切一段。标题层级、表格、FAQ、合同条款、代码块、字段说明都应该有不同策略。chunk 策略要像表20-2 一样，在“召回精度、上下文完整性、引用精度”三者之间做取舍。团队不需要寻找永久策略，而要为不同文档类型建立默认策略和例外策略。

表20-2：chunk 策略取舍表。来源：本书整理。

策略确定后，工程重点会转向上下文组装：即使召回的是小 chunk，生成答案时也可能需要 parent section、表头或相邻段落。没有 source span 和邻接关系，small-to-big 只会变成临时拼接。上下文组装要有预算意识。LLM 上下文越多，未必越可靠；混入相似但不可回答的材料会增加幻觉风险。企业系统应把 evidence 分成“直接支持答案”“背景材料”“冲突材料”“不可用材料”，并在 prompt 中明确引用规则：只基于直接证据回答，证据不足时拒答或请求澄清。

chunk 边界要跟文档类型一起设计。合同条款可以按条、款、项切分，但付款条件常常需要把定义条款和附件表格一起带回；制度问答适合保留标题路径，因为同一句“十五个工作日内”在报销、采购和审批制度里含义不同；技术 runbook 则要避免把命令、前置条件和回滚步骤切开。好的 chunk 策略会让被召回的证据足够小、可引用，同时又能找回回答问题所需的上下文。均匀切分只是最容易实现的方案，通常不是最适合企业文档的方案。

图 20-3 画出的正是 chunk 与上下文组装的核心矛盾：召回单元要足够小，生成上下文又要足够完整。small chunk、parent context、citation span 和 token budget 必须一起设计，不能各自优化。

图20-3：chunk 与上下文组装示意。来源：本书自绘。Alt text：文档被切成带重叠的片段，检索命中的片段连同相邻上下文、标题路径一起组装进 Prompt，示意分块粒度与上下文窗口的关系。

20.3 混合检索与排序融合

Embedding 擅长语义相似，BM25 擅长关键词和专有名词。企业检索往往需要二者结合。Azure AI Search 的 hybrid search 使用 BM25 和向量检索并行召回，再用 Reciprocal Rank Fusion 融合结果；这类路线适合内部系统，因为字段名、编号、合同条款、产品型号和错误码都可能依赖关键词精确命中。

表20-3 中检索路线的风险边界也要提前说清。纯向量、纯关键词、RRF 和 reranker 都能工作，但它们失败的方式不同，评测集也要覆盖这些失败方式。

表20-3：检索路线对比。来源：本书整理。

在企业知识库里，混合检索更接近默认能力。编号、字段名、条款号、错误码需要关键词；口语化问题、同义表达、业务别名需要向量。混合检索的收益来自互补，也来自可解释。只用向量时，“销售额口径”可能召回很多语义相近的指标说明，却漏掉字段名 net_sales_amount；只用关键词时，用户问“客户实际花了多少钱”又可能找不到“实收金额”。企业场景里的问题经常同时含有自然语言、实体名、编号、时间和字段名，单一路线很难稳定覆盖。把 BM25、向量召回和 reranker 的候选列表都记录下来，还能帮助团队判断是召回漏了、融合错了，还是重排把正确证据压低了。

RRF 的优势是简单稳定：不同检索器分数不可比，但排名可以融合。生产系统还要做去重、权限过滤、source diversity 和 query intent 分流。比如 DataAgent 的字段检索应该偏向 schema 文档和历史 SQL，合规问答应该偏向制度和合同，客服问答应该偏向历史工单和 runbook。DataAgent 的 RAG 还要服务 NL2SQL 和分析动作。检索结果里如果包含字段解释、指标口径、样例 SQL、数据质量规则和权限约束，生成 SQL 前就能减少误表、误字段和误口径。这里的可信回答需要说明 SQL 为什么这样写、引用了哪些口径、哪些字段有权限执行。

这也意味着 RAG 不能只服务最终自然语言回答。很多企业把 RAG 放在回答生成前一步，导致前面的 Planner、SQL 生成器和工具选择仍然缺上下文。更合理的做法，是让检索结果在任务早期就进入决策链路：先帮助系统识别业务实体、指标口径和可用工具，再辅助生成 SQL 或 API 参数，最后才用于答案引用。这样 RAG 才能从“给模型补资料”变成“给任务链路补证据”。

20.4 查询理解与多跳检索

用户问题经常包含多个检索意图。它可能包含时间范围、权限条件、业务实体、比较关系、隐含指标和多跳依赖。查询理解要把自然语言转成检索计划，而非改写成一个更长的问题。查询理解最好像表20-4 一样拆成几种可独立实现的能力。这样做的好处是可以逐项评估：改写有没有引入偏差，filter 有没有丢权限条件，多跳拆解有没有扩大问题范围。

表20-4：查询理解能力。来源：本书整理。

这些能力不应全部默认打开。简单 FAQ 可能只需要 query rewrite；DataAgent 通常需要 schema linking；跨合同、客户、风险事件的问题才需要多跳拆解。多跳检索要有停止条件。系统不能无限拆问题，也不能把所有中间结果塞进上下文。更稳的做法是先生成检索计划，执行每一步后检查证据是否足够；如果缺少关键实体、时间或权限条件，先澄清；如果证据冲突，输出冲突来源，不要强行总结。

查询理解还要保留原始问题和改写结果之间的关系。过度改写会把用户限定条件抹掉，例如把“华东区今年新签客户的续约风险”改成泛化的“客户续约风险”，后续检索再准确也回答错了对象。生产系统应把 filter 抽取、子问题拆解、schema linking 和澄清问题都记录下来，并允许评测人员回放每一步。这样才能判断多跳检索是在补证据，还是在扩大问题范围。查询理解失败时，系统应优先澄清，而非假装理解。时间范围、地区、指标口径、客户类型和权限边界如果没有解析出来，继续检索会得到看似相关但不可用的证据。澄清问题也要写入 trace，因为它说明系统在哪一步选择了保守处理。对业务用户来说，一次明确的澄清通常比一个自信但错口径的答案更可接受。多跳检索必须用图 20-4 的状态机思路限制复杂度。每一跳都应有输入、证据检查和停止条件；证据不足时要澄清或拒答，而非继续扩展上下文。

图20-4：多跳检索状态机。来源：本书自绘。Alt text：状态机含"提出子问题、检索、判断是否够答、继续追问或收敛生成"等节点，循环边表示在证据不足时多轮检索，直到满足回答条件。

20.5 可信回答与证据溯源

企业 RAG 的目标是让答案能被证据支持。流畅的文字不够，可信回答至少要满足三件事：引用可定位，答案和引用一致，权限和时间有效。Ragas 这类评估框架把 context precision、context recall、faithfulness 等指标拆开，是因为“检索到了好材料”和“模型忠实使用材料”属于两个不同问题。可信回答要落成表20-5 的门禁项，并承接前面的 chunk、检索和查询理解：前面每一步都可能生成证据，输出前必须检查证据是否能支撑答案。

表20-5：可信回答门禁。来源：本书整理。

RAG 评估因此要同时看答案分数、引用覆盖、引用一致、权限有效和冲突证据，这些指标都需要结构化日志与可回放链路支持。引用校验要检查的是“这句话是否由这段证据支持”，而非“答案旁边有没有链接”。常见错误包括引用了一段相关背景，却用它支持没有出现过的结论；引用的是旧版本制度，却回答了当前规则；引用片段包含条件限制，答案却省略了条件。更严格的实现会把答案拆成 claim，逐条匹配引用证据和生效时间。评估人员看到失败样例时，也要能回放 query、候选、重排分数、上下文和生成结果，避免把所有问题都归为幻觉。

可信回答还需要产品层面的降级策略。证据不足时，系统可以拒答、要求补充条件、返回可读原文、转人工复核，或者只给出“可能相关材料”；但不能在低置信状态下继续生成确定性结论。很多企业 RAG 的问题不在于没有召回，而在于没有把“不够答”作为一种正常结果设计出来。只要拒答和澄清路径清楚，用户会更容易理解系统边界，运营团队也能从这些失败样例里持续补齐文档、chunk 和评测集。mini-platform 的 core/rag/ 可以先实现一个最小接口：retrieve(query, filters)、rerank(query, candidates)、assemble_context(candidates, budget)、generate_answer(context)、verify_citations(answer, context)。这比一开始接十个 RAG 框架更重要，因为它把平台边界固定下来。

{
  "answer": "出差返回后应在十五个工作日内提交报销申请。",
  "citations": [
    {
      "chunk_id": "travel-policy#p12#c03",
      "page": 12,
      "span": "返回后十五个工作日内提交申请",
      "source_version": "v3"
    }
  ],
  "confidence": "high",
  "fallback": null
}

引用校验最终要像图 20-5 一样进入产品界面，不能停留在后台日志里的一个分数。运营、审计或人工复核界面里应该能看到答案、证据、权限和一致性状态。

图20-5：可信回答引用校验界面。来源：产品界面截图。Alt text：界面中每条结论旁标注来源片段链接，鼠标悬停可高亮原文出处，未找到支撑的句子被标红提示，体现答案逐句可校验。

20.6 RAG 证据链的运行标准

RAG 的可信度取决于证据链，而非只取决于最终回答。一次回答至少要保留用户问题、查询改写、检索条件、召回文档、rerank 结果、上下文裁剪、模型回答和引用片段。若答案被用户质疑，平台要能解释为什么这些片段进入上下文，为什么其他片段没有进入，以及模型回答中哪些句子来自哪些证据。只有最终答案和引用链接是不够的。证据链还要区分“可引用”和“被引用”。有些片段被检索到，但模型没有使用；有些片段进入上下文，但只提供背景；有些片段直接支持结论。平台如果把所有上下文都标成引用，会让用户误以为答案有充分依据。更好的做法是让回答中的关键结论绑定 EvidenceRef，并标出证据强度。证据不足时，回答应当明确说明缺口，而非用流畅语言补齐。RAG 证据链需要和第18章的向量检索、第19章的文档解析、第38章的 Trace 对齐。检索层负责说明证据从哪里来，解析层负责说明证据在原文中的位置，Trace 负责说明证据如何进入模型上下文。三者缺一项，用户看到的引用就只是展示效果，不是工程证据。

20.7 检索失败的诊断路径

RAG 失败不能简单归类为“没搜到”。常见失败至少包括知识未入库、文档解析丢失、chunk 切分破坏语义、query rewrite 偏离原意、向量召回漏掉、关键词召回过窄、rerank 排序错误、权限过滤过严、上下文窗口截断和生成层忽略证据。每一种失败对应不同修复方式，不能都通过增加 top_k 解决。诊断时应先复现检索输入。用户原始问题经过改写后可能已经改变重点，尤其是多轮对话中省略主语、时间和指标时。接着查看过滤条件和权限裁剪，确认候选空间没有被错误缩小。然后比较召回候选和 rerank 结果，判断问题发生在召回还是排序。最后检查上下文组装，确认关键证据没有被截断或被低价值片段挤出窗口。检索失败样本应当进入评测集，并保留失败阶段标签。这样下一次调整 embedding、chunk、rerank 或 query rewrite 时，团队可以看到哪类失败被修复，哪类失败被引入。RAG 工程的成熟度不在于堆叠多少检索技巧，而在于能否把失败拆成可定位、可修复、可回归的工程问题。

20.8 RAG 与工具调用的边界

RAG 适合回答基于文档和知识的事实问题，但不适合承担实时状态查询、写操作和权限强相关动作。用户问“这份政策怎么解释”可以走 RAG；用户问“我的订单现在到哪一步”应当调用业务系统；用户要求“把这份合同发给客户”必须进入工具和审批链路。把这些任务都放进知识库，会让系统用静态文本回答动态问题，也会绕开业务系统的权限和审计。边界判断可以看三个信号。问题需要实时数据时，优先工具调用；问题需要改变外部状态时，必须工具调用；问题需要引用稳定文档时，优先 RAG。混合场景也很常见，例如先用 RAG 解释政策，再用工具查询当前订单是否符合政策条件。此时平台要把两类证据分开：文档证据说明规则，工具证据说明事实。最终回答需要同时引用两者，不能把工具结果伪装成文档结论。这种边界会影响平台设计。RAG 检索结果应进入 EvidenceRef，工具调用结果应进入 Tool Call Trace，二者在报告层再汇合。若边界不清，后续第36章的报告和第38章的诊断都无法判断一个结论来自知识、数据还是外部系统。

20.9 RAG 上线后的运营指标

RAG 上线后，团队应持续观察证据覆盖率、无答案率、引用点击、用户追问、人工纠正和知识更新延迟。回答满意度有用，但它不能解释问题发生在哪里。证据覆盖率下降，可能是新知识未入库；无答案率上升，可能是 query rewrite 过窄；用户频繁追问出处，可能是引用表达不清。运营指标要能指向具体链路。知识更新延迟尤其重要。政策、产品说明、合同模板和内部流程变化后，RAG 系统如果仍引用旧版本，会比直接拒答更危险。平台应记录知识从提交、解析、入库、索引到可检索的时间，并对高风险知识设置更新 SLA。这样业务团队才能知道知识库是否适合承担正式问答入口。运营指标还要能触发动作。证据覆盖率下降时补索引或改召回，知识更新延迟升高时检查解析和发布队列，用户频繁追问出处时改引用展示和证据绑定。指标如果不能对应处理动作，就只能作为汇报材料。

RAG 团队也要定期清理知识源。过期政策、重复文档和低质量扫描件会持续污染召回结果。知识库越大，越需要明确入库、更新和退役责任。知识源清理要留下记录。某份文档为什么下线、由谁确认、影响哪些回答样本，都应能在后续复盘中查到。RAG 的评测也要覆盖链路，而同时看最终答案。召回阶段有没有拿到黄金段落，重排是否把关键证据放到前面，权限过滤是否误删或漏放，生成阶段是否只引用已给证据，这些都需要单独记录。否则团队只知道答案错了，却不知道该修索引、修解析还是修模型。

上线后还要观察用户追问。大量追问“依据在哪里”“这个政策是不是最新版”“能不能给出处”，说明证据呈现不足；大量无结果问题，可能是知识覆盖不足，也可能是查询理解失败。RAG 运营要把这些信号回写到文档治理和评测集中。RAG 与工具调用也要分清。检索适合提供证据和上下文，工具适合执行受控动作或查询实时系统。把实时库存、审批状态和权限判断都塞进文档，会让知识库承担它不该承担的责任。RAG 越工程化，边界越需要清楚。RAG 上线后还要处理文档生命周期。制度废止、附件更新、版本冲突、临时通知过期，都会让检索结果出现旧证据。平台需要记录文档版本、发布时间、适用范围和失效状态，并在召回时优先选择当前有效材料。若旧文档仍然能被检索，模型很可能把历史规则解释成当前规则。

权限过滤也不能放在生成之后。用户没有权限看到的段落，不应进入上下文；否则即使最终回答没有直接泄露，模型也可能用敏感信息影响推理。RAG 的权限应在召回、重排和引用阶段都生效，并在 Trace 中记录过滤原因。这样安全团队才能判断系统是没检到，还是检到了但被正确拦截。表格和图片资料需要单独验收。很多企业制度的关键条件藏在附件表、扫描件、流程图和注释里。纯文本 chunk 会丢掉单元格关系和版面语义，最后表现成“召回了文件但漏掉条件”。解析质量要进入 RAG 评测，而非默认文档入库就可用。RAG 的回答策略也要分级。证据充足时可以直接回答；证据不完整时应说明缺口；证据冲突时应要求用户选择版本或转人工；完全没有证据时应拒答并给出检索范围。把这些状态统一写成“根据资料可知”，会掩盖检索链路的真实质量。

当 RAG 被多个 Agent 共用后，平台还要建立知识资产负责人。谁负责文档更新，谁处理用户反馈，谁确认版本冲突，谁决定某类材料下线，这些都不属于模型团队单独职责。没有运营责任，知识库会随着时间变旧，RAG 的可信度也会自然下降。RAG 的上下文组装要控制证据密度。把太多段落塞给模型，关键证据会被稀释；只给最相似的一两段，又容易漏掉限定条件。平台可以根据问题类型选择组装策略：事实问答需要少量高置信证据，制度判断需要正文和附件同时出现，归因分析可能需要多来源证据并列。上下文窗口应服务回答条件，而不是追求更长的材料堆叠。引用校验应在生成后再做一次。模型给出的引用位置是否存在，引用内容是否支持结论，答案中是否出现未被证据支持的扩展，都可以自动检查一部分。检查失败时，系统可以要求模型重写、降级为“未找到充分证据”，或交给人工复核。这个步骤会增加一点延迟，但能减少带引用的错误答案。

用户反馈是 RAG 运营的重要来源。用户点击“引用不对”“文档过期”“没有回答我的问题”，比单纯点赞点踩更有价值。反馈应回到文档解析、chunk、召回、重排和生成评测中，而非只作为满意度指标。长期看，反馈能告诉团队知识库缺什么、哪些文档容易误导模型、哪些问题需要工具而非检索。RAG 还要处理多语言和术语差异。企业文档可能同时包含中文制度、英文供应商材料、缩写、别名和历史名称。查询理解阶段要把用户语言映射到文档术语，同时保留原问题。若只靠向量相似度，常见缩写和组织内部黑话会降低召回质量。当 RAG 承接高风险场景时，平台应允许“证据不足”成为正常输出。用户可能不喜欢无答案，但业务更不能接受没有证据的确定结论。把拒答、澄清和证据缺口设计成产品状态，是企业 RAG 区别于演示系统的重要标志。

20.10 RAG 发布门禁与证据回流

RAG 上线不应只看回答是否通顺。发布门禁要覆盖离线评测、影子流量、人工复核和线上回流四个阶段。离线评测检查黄金问题是否命中正确证据，影子流量比较新旧检索链路的候选差异，人工复核确认高风险答案的引用是否支撑结论，线上回流则把用户反馈和事故样本纳入下一轮评测。少了其中任一阶段，平台都会把未知风险带到正式用户面前。

发布前的样本集要按失败类型组织。解析失败样本用来验证表格、附件和页码；召回失败样本用来验证向量、关键词和 filter；重排失败样本用来验证正确证据是否进入前排；生成失败样本用来验证模型是否忠实使用证据；权限样本用来验证无权材料不会进入上下文。这样评测报告才能指向修复动作。一个总分即使看起来不错，也不能说明高风险类型已经过关。

影子流量要保留证据差异。新链路和旧链路对同一问题可能都能生成答案，但候选证据不同、引用版本不同、拒答理由不同。平台不能只比较最终文字相似度，而要比较候选列表、引用覆盖、权限过滤、冲突材料和生成前上下文。若新版本回答更短但引用更准，这是可接受变化；若新版本回答更完整但引用弱，就要推迟切流。对 DataAgent 来说，还要比较检索结果是否改变了 SQL 生成中的指标、字段和过滤条件。

线上证据回流应成为日常机制。用户标记引用错误、文档过期、答案缺条件、没有回答问题时，系统要把原始问题、检索计划、候选证据、最终引用和用户反馈一起保存。运营团队先给反馈分型，再决定修复位置：补文档、改解析、调 chunk、扩 query、改 reranker、加拒答规则，或者把问题转交给工具调用。没有分型的反馈只能形成满意度曲线，不能提升 RAG 链路质量。

高风险场景还需要发布冻结机制。制度更新、合同模板变更、权限模型调整、解析器升级或索引重建期间，平台可以暂时限制自动回答，只允许检索原文或要求人工复核。冻结是一种生产控制手段：它告诉用户当前证据链处在变更窗口，系统不会在不稳定材料上给出确定结论。早期平台可以先实现最简单的门禁：未通过引用校验的答案不发布，缺少权限过滤记录的回答不发布，证据不足的问题必须拒答或澄清。

20.11 证据质量台账与修复责任