端到端项目模板
定义
端到端项目模板(end-to-end project template)指把模型能力转换为可交付系统的一组固定结构:六层的职责边界、一份可直接复制的仓库布局、一组带类型校验的配置契约、一个带停止条件与预算上限的执行循环、一套离线与在线评估入口,以及部署、观测、回滚的最低要求。
逐个术语给出定义。
| 术语 | 含义 |
|---|---|
| 用户故事 | 以「角色—动作—目的」描述的一项功能,可拆为可测的验收条件 |
| 验收标准 | 判定该项功能通过的客观条件,取值可来自指标阈值或样例通过与否 |
| 失败定义 | 明确列出哪些输出算失败,包括拒答错误、超时、无引用、引用与答案不一致 |
| SLO | 服务级目标,如「95% 的请求在 8 秒内返回」,是发布门槛而非努力方向 |
| trace id | 一次请求的全局标识,贯穿接口层、编排层、模型层、工具层与观测层 |
| 黄金集 | 带标注的离线评测集,用于每次改动后的回归判定 |
| 预算上限 | 单次请求允许消耗的最大金额,达到即终止循环并降级 |
| 回滚 | 把镜像与配置恢复到上一个通过验收的版本,且不依赖数据迁移 |
| 限流 | 按令牌桶或滑动窗口限制单位时间的请求数,保护下游与成本 |
| 人工审批 | 高风险动作执行前必须由人确认的检查点 |
六个层的名称与职责:接口层负责协议、鉴权与限流;编排层负责循环、状态与停止条件;模型层负责模型适配、重试与超时;工具层负责工具注册、参数校验与执行;数据层负责索引、文档版本与检索;观测层负责日志、指标、追踪与告警。
为什么重要
一个能演示的系统与一个能交付的系统之间,差的是可重复、可度量、可回滚这三件事,而不是模型能力。
没有评估就无法判断改动是改进还是退化。提示词改一个字、检索多取两条、温度从 0 调到 0.2,这些改动在少量样例上表现为随机波动,只有固定黄金集与阈值才能给出判定。没有评估时,团队的决策依据是「看起来更好了」,这类判断在小样本上不可靠:3 条用例全部通过时,真实成功率的 95% 置信区间下界约为 0.44(见第 1 节的 Wilson 区间),即完全无法排除「一半以上请求失败」的情形。
没有 trace id 就无法定位单次失败。用户报告「答错了」,日志里只有一条最终回答时,无法判断错在检索没召回、工具参数非法、模型忽略引用还是超时降级。把每次循环的步骤、工具调用、token 数与成本写入结构化日志,并共享同一个 trace id,才能把一次失败还原为一条可复现的调用链。
没有预算上限时,一次循环可能耗尽整月配额。循环的上界是最大步数与单步最大 token 的乘积,若两者都没有约束,一次异常输入可以触发数十次模型调用。预算上限把成本从「事后统计」变成「运行期硬约束」。
没有回滚时,一次坏发布就是事故。回滚的前提是镜像带版本标签、配置独立于镜像、数据层变更向后兼容;三者缺一,回滚时间就从分钟级变成小时级。
在本库中的位置:本篇承接 Agent工作流与编排 的循环语义、MCP协议 的工具契约与 Harness与Loop工程 的执行边界,把 模型推理优化 与 分布式训练与部署 的部署约束落成一份可执行的清单,并用 成本-延迟-质量权衡 的三角关系确定参数取值,用 模型评估矩阵 选定评测维度。它要回答的问题是:一个人或一个小团队,从零开始交付一个 Agent 系统时,哪些结构必须先建、每个结构的验收条件是什么、哪些错误是可以在流程上被消除的。
原理与推导
1 需求与验收:从用户故事到可测指标
用户故事写成一句话:作为 角色,我要 动作,以便 目的。每条故事拆出 2 至 4 条验收条件,每条条件必须是可判定的,即给定一个输入,能输出通过或不通过。
文档问答 Agent 的验收表如下。
| 编号 | 验收条件 | 指标 | 阈值 | 判定方式 |
|---|---|---|---|---|
| A1 | 答案包含正确要点 | 要点命中率 | 不低于 0.90 | 黄金集 200 条,人工标注要点 |
| A2 | 答案给出可核对的引用 | 引用正确率 | 不低于 0.90 | 引用 doc id 属于标注集合 |
| A3 | 无依据时拒答 | 拒答正确率 | 不低于 0.85 | 30 条无答案样本应为拒答 |
| A4 | 端到端延迟 | P95 | 低于 8 秒 | 压测 1000 次请求 |
| A5 | 单次成本 | 均值 | 低于 0.005 美元 | 日志中的成本字段 |
| A6 | 失败可定位 | trace 完整率 | 100% | 抽查 100 条日志,字段齐全 |
失败定义必须显式列出,否则验收会退化为「看起来对」:答案缺少标注要点、引用 id 不在检索结果内、引用与答案矛盾、超过 8 秒、触发预算上限后未降级、返回空字符串、把用户输入原样复述。以上任一项出现即计为失败,从成功率中扣除。
成功率是二项比例,小样本必须给区间。设 条用例中通过 条,,Wilson 区间的中心与半宽为
区间为 , 对应 95% 置信水平。代入两种样本量:
- 、:,区间 。全部通过仍无法排除四成以上的失败率。
- 、:,区间 。半宽约 4 个百分点。
由此得到样本量的下限:要在 个百分点内判断成功率, 需要 150 至 400 条;要分辨 2 个百分点的差异, 需要上千条。黄金集取 200 条是成本与分辨率的折中点。
2 架构分层与依赖方向
分层的作用是把变更隔离开。提示词改动只触及编排层,模型更换只触及模型层,工具新增只触及工具层,索引重建只触及数据层。任何跨层的直接调用都会破坏这一性质。
| 层 | 职责 | 输入 | 输出 | 典型失败 |
|---|---|---|---|---|
| 接口层 | 协议、鉴权、限流、幂等 | HTTP 请求、身份 | 规范化请求、trace id | 重复提交、未限流导致下游过载 |
| 编排层 | 循环、状态机、停止条件、预算 | 规范化请求 | 最终答案或降级结果 | 死循环、超预算、状态丢失 |
| 模型层 | 提供方适配、重试、超时、用量统计 | 消息列表、工具描述 | 文本或工具调用、用量 | 重试风暴、超时未传递 |
| 工具层 | 注册、参数校验、权限、执行 | 工具名、参数 | 结构化结果或错误码 | 参数未校验、异常吞掉 |
| 数据层 | 索引、文档版本、检索 | 查询、过滤条件 | 片段与 doc id | 版本错配、召回为空 |
| 观测层 | 日志、指标、追踪、告警 | 各层事件 | 可检索的记录与告警 | 缺 trace id、采样不全 |
依赖方向单向向下:接口层依赖编排层,编排层依赖模型层与工具层,工具层依赖数据层,观测层被所有层调用但不反向依赖任何业务层。反向依赖的后果是测试困难:若工具层直接读配置并调用接口层,则工具无法在评测脚本中单独实例化。
flowchart TB
subgraph API[接口层]
A1[HTTP 路由] --> A2[鉴权与限流]
end
subgraph ORC[编排层]
B1[agent loop] --> B2[停止条件与预算]
B2 --> B3[提示词组装]
end
subgraph MOD[模型层]
C1[provider 适配] --> C2[重试与超时]
end
subgraph TOOL[工具层]
D1[工具注册表] --> D2[参数校验]
D2 --> D3[search_docs]
D2 --> D4[read_doc]
end
subgraph DATA[数据层]
E1[向量索引] --> E2[文档版本]
end
subgraph OBS[观测层]
F1[结构化日志] --> F2[指标与追踪]
F2 --> F3[告警]
end
A2 --> B1
B1 --> C1
B1 --> D1
D3 --> E1
D4 --> E1
B2 --> F1
C2 --> F1
D2 --> F1
3 仓库布局与配置契约
布局按层切分目录,而不是按文件类型切分。按层切分时,新增一个工具只需要改 tools/,新增一个指标只需要改 obs/;按类型切分(models/、utils/、services/)会把同一条调用链拆散在四个目录里。
配置遵循三层覆盖:configs/default.yaml 提供全部默认值,configs/{env}.yaml 覆盖环境差异,环境变量覆盖密钥与运行期参数。优先级为 环境变量 > 环境配置 > 默认配置。启动时用带类型的 schema 校验,失败即退出,并把非敏感字段打印为摘要写入启动日志。
配置项分四类,取值必须显式声明。
| 类别 | 配置项 | 取值示例 | 说明 |
|---|---|---|---|
| 模型 | model.id、model.temperature、model.max_output_tokens | qwen3-32b-instruct、0.0、800 | 温度取 0 保证可复现 |
| 循环 | agent.max_steps、agent.budget_usd | 6、0.02 | 两者共同构成成本上界 |
| 工具 | tools.timeout_s、tools.allow_write | 3、false | 写操作默认关闭 |
| 观测 | obs.log_level、obs.sample_rate | info、1.0 | 首版全量采样 |
密钥三条规则:不入库、不写进镜像、不打印。代码只从环境变量读取,.env.example 只保留键名与占位值,CI 用 gitleaks 一类工具扫描提交内容。
4 Agent 循环的五条不变量
循环是系统中最容易出错的部分,因为它的状态分布在多轮之间。以下五条不变量必须在实现中显式保证,任一条缺失都会产生难以复现的故障。
- 每轮有唯一标识。
trace_id在一次请求内不变,step从 1 递增。没有 step 时,日志无法排序,也无法判断是否死循环。 - 工具参数先校验后执行。模型产出的参数是待验证的输入,类型、枚举、必填字段、取值范围都要检查;校验失败作为工具结果回填,让模型自行修正。
- 每步累计成本,超预算立即终止。累计值 , 为单位 token 价格。终止后返回降级结果并标记
stop=budget。 - 终止条件完备。至少包含:最终答案、步数上限、预算上限、墙钟超时、不可恢复错误。缺少任一条都可能挂死。
- 工具输出按数据对待。工具返回的文本可能含指令性语句,这些语句不具有指令效力,不得进入系统提示,也不得改变权限判定。
循环的伪代码如下,停止原因的取值是有限的枚举,便于统计。
输入:question, 预算 B, 步数上限 S
trace := 新标识(); messages := [系统提示, 用户消息]; spent := 0
for step in 1..S:
out := 模型层.complete(messages, 工具描述)
spent += 计价(out.用量)
写日志(trace, step, 模型, out.类型, spent)
if spent > B: return 降级("预算耗尽", stop=budget)
if out 是最终答案: return 答案(out, stop=final)
result := 工具层.call(out.名称, out.参数)
写日志(trace, step, 工具, result.是否成功, result.错误码)
messages += 工具消息(result)
return 降级("步数上限", stop=max_steps)
停止原因的分布本身就是指标:budget 与 max_steps 占比上升,说明提示词或工具设计有问题,而不是模型能力不足。
5 工具注册与契约
工具是模型与外部世界的唯一通道,其契约必须包含名称、描述、参数模式、权限与超时。注册表的作用是让契约成为代码的一部分,而不是散落在提示词里。
| 字段 | 要求 | 缺失后果 |
|---|---|---|
name | 全局唯一,动词开头 | 模型无法稳定选择工具 |
description | 说明何时使用、返回什么、失败的返回形态 | 模型误用或重复调用 |
input_schema | 根节点为 object,逐字段声明类型与枚举 | 参数类型错误进入执行阶段 |
timeout_s | 必须小于循环的单步预算 | 单次工具卡死拖垮整个请求 |
allow_write | 写操作默认关闭,需显式开启并进入审批 | 越权修改数据 |
描述文本是模型选择工具的唯一依据,必须写清「什么时候用这个工具」而非「这个工具是什么」。只写「检索文档」时,模型容易在已有答案的情况下重复检索;写成「当需要核对外部事实或用户询问文档内容时调用,返回文档 id 与片段,无结果时返回空列表」,调用行为会明显稳定。
6 数据与提示词版本管理
提示词是代码,必须有版本号、变更记录与回滚能力。实现方式是把提示词放在 prompts/ 下,文件名为 名字.v版本.md,prompts/manifest.json 记录当前生效版本与内容哈希;启动时校验哈希,不匹配则拒绝启动。
版本信息必须进入每条日志与每次评测结果:model_id、prompt_version、dataset_version、config_hash。缺少任一项时,两次评测的差异无法归因,回滚也无法确定回到哪个组合。
数据侧同理:文档入库时记录 doc_id、source_id、updated_at 与内容哈希;索引带版本号,检索结果返回索引版本。文档更新后重建索引时,旧版本保留一个周期,使正在进行的请求不受影响。
7 评估:离线集、在线指标与回归测试
评估分三层,用途不同,不可互相替代。
| 层 | 数据 | 指标 | 频率 | 用途 |
|---|---|---|---|---|
| 离线黄金集 | 200 条带标注 | 要点命中、引用正确、拒答正确 | 每次提交 | 判定改动是否退化 |
| 离线压力 | 1000 条合成请求 | P50、P95、错误率、单请求成本 | 每次发布 | 判定容量与成本 |
| 在线 | 真实流量 | 成功率、兜底率、点踩率、P95 | 持续 | 判定真实表现 |
回归判定用相对阈值而非绝对阈值,因为基线会随模型与数据变化而移动。
| 检查 | 通过条件 | 失败处理 |
|---|---|---|
| 要点命中率 | 不低于基线 −1 个百分点 | 阻止合并 |
| 引用正确率 | 不低于 0.90 | 阻止合并 |
| P95 延迟 | 不高于基线 × 1.15 | 阻止发布 |
| 单请求成本 | 不高于基线 × 1.10 | 阻止发布 |
| 单元测试 | 全部通过,含预算终止与注册表用例 | 阻止合并 |
评测脚本本身也要测试:用一组已知答案的假数据跑通评测入口,确认指标计算正确。评测脚本出错的表现通常是「分数突然变高」,这类错误比模型退化更难发现。
8 部署:容器、健康检查、限流、回滚
部署单元的粒度是镜像加配置。镜像不带密钥、不带数据,配置通过环境变量注入。
健康检查分两个端点。/healthz 只检查进程存活,返回 200 即通过,用于容器重启判定;/readyz 检查依赖可用性(模型端点可达、索引可读),不通过时从负载均衡摘除但不重启容器。两者混用会导致依赖抖动时容器被反复重启。
限流用令牌桶。桶容量 、补充速率 (每秒),当前令牌数
请求到达时若 则扣减并放行,否则返回 429 并带 Retry-After。取值由容量决定:文档问答 Agent 的日均 1 万请求折合平均 0.116 QPS,峰值按 5 倍计为 0.58 QPS,故取 、 留出余量。
灰度与回滚流程固定为三步。
| 阶段 | 流量 | 观察窗口 | 通过条件 | 失败动作 |
|---|---|---|---|---|
| 金丝雀 | 5% | 30 分钟 | 错误率不高于基线 +1pp,P95 不高于 8 秒 | 立即回滚 |
| 分批 | 25% | 2 小时 | 成本不高于预算,兜底率不高于 5%(告警线为 8%,见第 9 节) | 回滚并保留现场 |
| 全量 | 100% | 24 小时 | 全部 SLO 满足 | 回滚 |
回滚操作只允许两个动作:把镜像标签指回上一个版本,把配置版本指回上一个版本。因此数据层变更必须向后兼容至少一个版本,例如新增字段而非改名。
9 观测:日志、追踪、告警
日志是结构化 JSON,一行一个事件,字段固定。
| 字段 | 类型 | 说明 |
|---|---|---|
ts | ISO 8601 | 事件时间,毫秒精度 |
trace_id | 字符串 | 请求级唯一标识 |
step | 整数 | 循环轮次,从 1 开始 |
event | 枚举 | model、tool、stop、error |
tool | 字符串 | 工具名,仅 event=tool 时有值 |
tokens_in、tokens_out | 整数 | 本次调用的用量 |
cost_usd | 浮点 | 累计成本,保留 6 位 |
latency_ms | 整数 | 本次调用的耗时 |
status | 枚举 | ok、invalid_args、timeout、denied |
告警阈值必须能在事故前触发,因此取相对基线与绝对上限的组合。
| 告警 | 条件 | 级别 | 处置 |
|---|---|---|---|
| 错误率上升 | 5 分钟内 5xx 比例超过 5% | P1 | 检查模型端点与索引,必要时回滚 |
| 延迟劣化 | P95 超过 10 秒持续 10 分钟 | P2 | 检查检索延迟与模型排队 |
| 成本异常 | 单请求成本超过 0.5 美元,或日预算消耗超过 80% | P2 | 检查循环步数与输入长度 |
| 兜底率上升 | 人工兜底率超过 8% 持续 1 小时 | P2 | 抽样检查失败样本 |
| 质量下降 | 每日 1% 抽样人工评分低于 3.5/5 | P2 | 复核提示词与索引版本 |
10 安全:权限、输入过滤、人工审批
权限按最小必要授予。工具分只读与可写两类,可写工具默认关闭;模型端点使用独立的密钥与配额,避免与其他服务共享;数据层对文档做来源级权限过滤,检索时在索引侧过滤而非在结果侧过滤,避免越权内容进入上下文。
输入过滤与输出校验分工明确:输入侧限制长度、块数与字符集,识别明显的注入模式;输出侧校验引用必须来自本次检索结果,答案中的数字与日期必须能在引用片段中找到依据。
| 风险 | 控制 | 检查点 |
|---|---|---|
| 越权读取文档 | 索引侧按来源过滤 | 检索返回前 |
| 提示注入 | 工具输出按数据处理,不进入系统提示 | 消息组装时 |
| 越权写操作 | 写工具默认关闭,需审批 | 工具执行前 |
| 密钥泄漏 | 只从环境变量读取,提交扫描 | CI |
| 数据外泄 | 输入中的敏感字段脱敏后再送模型 | 编排层入模前 |
| 成本攻击 | 单请求预算上限与租户级配额 | 每步累加时 |
人工审批适用于三类动作:写外部系统、发送对外内容、金额或权限变更。审批不是把请求阻塞在循环里,而是把动作转为待办并返回中间状态,由人确认后从检查点继续。
11 成本预算与容量
单请求成本由调用次数与 token 数决定。文档问答 Agent 每次请求 3 次模型调用,输入合计约 4200 token、输出合计约 450 token,按输入 0.5 美元/百万 token、输出 1.5 美元/百万 token 计:
按日均 1 万请求、每月 30 天,月成本结构如下。
| 项目 | 用量 | 单价 | 月成本(美元) | 占比 |
|---|---|---|---|---|
| 模型调用 | 30 万次请求 | 0.0028 美元/次 | 833 | 13.4% |
| 人工兜底 | 9000 次(3%) | 0.60 美元/次 | 5400 | 86.6% |
| 索引重建 | 4 次 | 0.30 美元/次 | 1.2 | 0.02% |
| 日志与追踪存储 | 约 2.4 GB | 按量 | 1 | 0.02% |
| 合计 | 6235 | 100% |
这张表改变优化顺序:模型成本只占一成,兜底成本占八成以上,因此降低兜底率是最大的成本杠杆,而不是压缩 token。兜底率从 3% 降到 2% 每月节省 1800 美元,而把输入 token 压缩 30% 只节省 250 美元。同时可加缓存:相同问题命中缓存时直接返回,按 35% 命中率可再省约 291 美元。
容量按峰值而非均值规划。QPS 峰值 0.58 时,单实例(4 并发、单请求 4.2 秒)可承载约 0.95 QPS,故两实例即可满足并留出故障余量。
12 里程碑与交付清单
| 里程碑 | 交付物 | 验收 | 人日 |
|---|---|---|---|
| M0 需求与验收 | 用户故事、验收表、失败定义 | 验收条件全部可判定 | 3 |
| M1 骨架与工具 | 六层目录、注册表、循环、预算 | 单请求 trace 完整,预算可终止 | 5 |
| M2 评估与基线 | 黄金集 200 条、评测脚本、基线记录 | 基线可复现,区间已计算 | 4 |
| M3 部署与观测 | 镜像、健康检查、限流、告警 | 金丝雀通过,告警可触发 | 4 |
| M4 灰度与交付 | 运行手册、回滚演练、交接文档 | 回滚演练在 5 分钟内完成 | 3 |
交付清单:可构建的镜像与版本标签、配置 schema 与样例、黄金集与评测报告、告警规则与运行手册、回滚演练记录、成本预算表、已知限制清单。缺任一项即视为未交付,因为缺项会在事故时暴露为不可操作。
关键直觉
模板的作用是把「一次成功的演示」转换为「可重复的流程」:凡是不能被日志记录、不能被黄金集复现、不能在一分钟内回滚的环节,都不算已交付。这一判断与第 2 节的分层、第 4 节的不变量、第 7 节的回归门槛是同一件事的三个侧面:分层保证变更可隔离,不变量保证运行可终止,回归门槛保证改动可判定。三者的共同前提是同一份结构化日志与同一套版本标识,因此观测层不是附属设施,而是其他五项能力的证据来源。
例子与代码
例 1:可直接复制的仓库布局
docqa-agent/
├── README.md
├── pyproject.toml
├── Makefile # make eval / make serve / make gate
├── Dockerfile
├── .env.example # 只有键名与占位值
├── configs/
│ ├── default.yaml # 全部默认值
│ ├── staging.yaml
│ ├── prod.yaml
│ └── schema.py # 启动时校验,失败即退出
├── prompts/
│ ├── system.v3.md
│ └── manifest.json # 当前版本与内容哈希
├── src/docqa/
│ ├── api.py # 接口层:路由、鉴权、限流、幂等
│ ├── orchestrator.py # 编排层:循环、停止条件、预算
│ ├── models.py # 模型层:适配、重试、超时、用量
│ ├── tools/
│ │ ├── registry.py # 注册表、参数校验、权限
│ │ └── docs.py # search_docs / read_doc / cite
│ ├── data/
│ │ ├── index.py # 向量索引与文档版本
│ │ └── ingest.py # 入库、切分、去重
│ ├── obs/
│ │ ├── logging.py # 结构化日志与 trace id
│ │ └── metrics.py # 指标、告警阈值
│ └── eval/
│ ├── run_eval.py # 离线评测入口
│ ├── gate.py # 与基线比较,输出通过或拒绝
│ ├── goldenset.jsonl # 200 条标注
│ └── judge.py # 要点匹配与引用校验
├── tests/
│ ├── test_registry.py # 参数校验、重复注册
│ ├── test_loop_budget.py # 预算终止、步数终止
│ └── test_eval_metrics.py # 指标计算正确性
└── ops/
├── alerts.yaml
└── runbook.md # 回滚、降级、扩容的具体命令
布局有两条规则:一条调用链上的代码跨不多于两个目录;测试文件与被测模块同名。前一条保证改动范围可预测,后一条保证新增模块时测试位置无需讨论。
例 2:可运行的骨架(工具注册、循环、评测入口)
下面的脚本是上述布局的最小实现,纯 Python、无第三方依赖,直接运行会打印一条完整 trace 与一次离线评测结果。它把注册表、参数校验、循环、预算、日志与评测串成一条链路,替换其中的 ScriptedModel 即为真实模型调用。
# docqa_skeleton.py —— 纯 Python 3.10+,无第三方依赖,直接可运行
# 覆盖:工具注册与参数校验、带 trace id 与预算上限的 agent loop、离线评测入口
from __future__ import annotations
import json
import time
import uuid
from dataclasses import dataclass
from typing import Any, Callable
PRICE_IN, PRICE_OUT = 0.5 / 1e6, 1.5 / 1e6 # 美元/token
MAX_STEPS, BUDGET_USD = 6, 0.02
QUIET = False
DOCS = {
"D1": "退款政策:签收后 7 天内可无理由退货,退货运费由买家承担。",
"D2": "发票:订单完成后 48 小时内可申请电子发票,逾期需走人工补开。",
"D3": "保修:整机保修 12 个月,电池保修 6 个月,人为损坏不在保修范围。",
}
@dataclass
class ToolSpec:
name: str
description: str
schema: dict
fn: Callable[..., Any]
@dataclass
class ToolResult:
ok: bool
content: Any = None
error: str | None = None
class ToolRegistry:
def __init__(self) -> None:
self._tools: dict[str, ToolSpec] = {}
def register(self, spec: ToolSpec) -> None:
if spec.name in self._tools:
raise ValueError(f"工具重复注册: {spec.name}")
self._tools[spec.name] = spec
def describe(self) -> list[dict]:
return [{"name": t.name, "description": t.description,
"input_schema": t.schema} for t in self._tools.values()]
def call(self, name: str, args: dict) -> ToolResult:
spec = self._tools.get(name)
if spec is None:
return ToolResult(False, None, f"未知工具 {name}")
err = validate(spec.schema, args)
if err:
return ToolResult(False, None, err)
try:
return ToolResult(True, spec.fn(**args))
except Exception as exc: # 工具异常必须回填,不得中断循环
return ToolResult(False, None, f"{type(exc).__name__}: {exc}")
def validate(schema: dict, args: dict) -> str | None:
"""最小 JSON Schema 校验:required、type、enum。真实项目用 jsonschema 库。"""
py = {"string": str, "integer": int, "number": (int, float),
"boolean": bool, "array": list, "object": dict}
for key in schema.get("required", []):
if key not in args:
return f"缺少必填字段 {key}"
for key, spec in schema.get("properties", {}).items():
if key not in args:
continue
if spec.get("type") in py and not isinstance(args[key], py[spec["type"]]):
return f"{key} 类型应为 {spec['type']}"
if "enum" in spec and args[key] not in spec["enum"]:
return f"{key} 不在枚举 {spec['enum']} 内"
return None
def search_docs(query: str, top_k: int) -> list[dict]:
"""按字符重合度打分的检索替身;真实项目替换为向量索引。"""
scored = [(sum(ch in text for ch in set(query)), doc_id)
for doc_id, text in DOCS.items()]
scored = [pair for pair in scored if pair[0] > 0]
scored.sort(reverse=True)
return [{"doc_id": doc_id, "snippet": DOCS[doc_id][:24]}
for _, doc_id in scored[:top_k]]
REGISTRY = ToolRegistry()
REGISTRY.register(ToolSpec(
"search_docs", "按关键词检索文档,返回文档 id 与片段",
{"type": "object", "required": ["query", "top_k"],
"properties": {"query": {"type": "string"},
"top_k": {"type": "integer", "enum": [1, 3, 5]}}},
search_docs))
REGISTRY.register(ToolSpec(
"read_doc", "读取指定文档的全文",
{"type": "object", "required": ["doc_id"],
"properties": {"doc_id": {"type": "string"}}},
lambda doc_id: DOCS[doc_id]))
REGISTRY.register(ToolSpec(
"cite", "生成引用标记,只允许引用已读取的文档",
{"type": "object", "required": ["doc_id"],
"properties": {"doc_id": {"type": "string"}}},
lambda doc_id: f"[doc:{doc_id}]"))
class ScriptedModel:
"""离线替身:按固定策略发工具调用,用于在没有 API 时验证循环、预算与日志。"""
def complete(self, messages: list[dict], tools: list[dict]) -> dict:
tool_msgs = [m for m in messages if m["role"] == "tool"]
question = next(m["content"] for m in messages if m["role"] == "user")
if not tool_msgs:
return {"kind": "tool_call", "name": "search_docs",
"arguments": {"query": question, "top_k": 3}, "usage": (520, 36)}
last = tool_msgs[-1]
if last["name"] == "search_docs":
if not last["payload"]:
return {"kind": "final", "text": "检索无结果,无法回答。",
"usage": (700, 20)}
return {"kind": "tool_call", "name": "read_doc",
"arguments": {"doc_id": last["payload"][0]["doc_id"]},
"usage": (640, 30)}
if last["name"] == "read_doc":
return {"kind": "tool_call", "name": "cite",
"arguments": {"doc_id": last["arguments"]["doc_id"]},
"usage": (760, 28)}
text = next(m["payload"] for m in reversed(tool_msgs)
if m["name"] == "read_doc")
return {"kind": "final", "text": f"依据文档:{text} 引用 {last['payload']}",
"usage": (980, 120)}
def cost(usage: tuple[int, int]) -> float:
return usage[0] * PRICE_IN + usage[1] * PRICE_OUT
def log(**fields: Any) -> None:
if not QUIET:
print(json.dumps(fields, ensure_ascii=False))
def run_agent(question: str, model: ScriptedModel, registry: ToolRegistry,
max_steps: int = MAX_STEPS, budget: float = BUDGET_USD) -> dict:
trace_id = uuid.uuid4().hex[:12]
messages = [{"role": "system", "content": "只依据检索结果回答,必须给出引用。"},
{"role": "user", "content": question}]
spent, t0 = 0.0, time.perf_counter()
for step in range(1, max_steps + 1):
out = model.complete(messages, registry.describe())
spent += cost(out["usage"])
log(trace_id=trace_id, step=step, event="model", kind=out["kind"],
tokens=sum(out["usage"]), cost_usd=round(spent, 6))
if spent > budget:
log(trace_id=trace_id, step=step, event="stop", reason="budget_exceeded")
return {"trace_id": trace_id, "answer": "预算已耗尽,转人工。",
"stop": "budget", "cost": spent, "steps": step,
"ms": round((time.perf_counter() - t0) * 1000)}
if out["kind"] == "final":
log(trace_id=trace_id, step=step, event="stop", reason="final")
return {"trace_id": trace_id, "answer": out["text"], "stop": "final",
"cost": spent, "steps": step,
"ms": round((time.perf_counter() - t0) * 1000)}
res = registry.call(out["name"], out["arguments"])
log(trace_id=trace_id, step=step, event="tool", tool=out["name"],
ok=res.ok, error=res.error)
messages.append({"role": "tool", "name": out["name"],
"arguments": out["arguments"],
"payload": res.content if res.ok else res.error})
return {"trace_id": trace_id, "answer": "步数上限,转人工。", "stop": "max_steps",
"cost": spent, "steps": max_steps,
"ms": round((time.perf_counter() - t0) * 1000)}
CASES = [
{"q": "退货的运费由谁承担", "doc": "D1", "must": "买家"},
{"q": "订单完成后多久能申请发票", "doc": "D2", "must": "48"},
{"q": "电池保修多久", "doc": "D3", "must": "6 个月"},
]
def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
p = k / n
d = 1 + z * z / n
c = (p + z * z / (2 * n)) / d
h = z * (p * (1 - p) / n + z * z / (4 * n * n)) ** 0.5 / d
return c - h, c + h
def run_eval(cases: list[dict]) -> None:
global QUIET
QUIET = True # 评测时只看汇总,不打印逐步日志
model, passed, costs = ScriptedModel(), 0, []
for c in cases:
r = run_agent(c["q"], model, REGISTRY)
answer_ok = c["must"] in r["answer"]
cite_ok = f"[doc:{c['doc']}]" in r["answer"]
passed += answer_ok and cite_ok
costs.append(r["cost"])
print(f" 用例 {c['q'][:8]} answer_ok={answer_ok} cite_ok={cite_ok} "
f"stop={r['stop']} cost=${r['cost']:.6f}")
lo, hi = wilson(passed, len(cases))
print(f"\n成功率 {passed}/{len(cases)} = {passed/len(cases):.3f} "
f"95% Wilson 区间 [{lo:.3f}, {hi:.3f}] "
f"单请求均价 ${sum(costs)/len(costs):.5f}")
if __name__ == "__main__":
print("== 单个请求的完整 trace ==")
run_agent("退货的运费由谁承担", ScriptedModel(), REGISTRY)
print("\n== 离线集回归 ==")
run_eval(CASES)
在做什么:ToolRegistry 把工具的名称、描述、参数模式与实现绑在一处,describe() 生成的列表就是要发给模型的工具声明;run_agent 是第 4 节的循环,spent 每步累加并在超预算时立即返回,返回体带 stop 字段;run_eval 遍历黄金集,按「要点命中且引用正确」判定通过,并给出 Wilson 区间。
为什么这样写:把检索、读取、引用拆成三个工具,而不是一个「回答问题」的工具,是为了让每一步都可核验。cite 只能引用 read_doc 读过的文档,把「引用必须来自检索结果」这条规则实现为工具约束,而不是提示词里的要求。
去掉会怎样:删掉参数校验后,模型偶发的 top_k: "3" 会以字符串形式传入,[:top_k] 抛 TypeError,若异常未被捕获则整个请求失败;删掉预算判断后,一个循环异常的样本会连续调用直到步数上限,成本上升约 2.5 倍;删掉 stop 字段后,日志无法区分「正常回答」与「降级回答」,兜底率无法统计。
运行输出如下。
== 单个请求的完整 trace ==
{"trace_id": "722fa1edced8", "step": 1, "event": "model", "kind": "tool_call", "tokens": 556, "cost_usd": 0.000314}
{"trace_id": "722fa1edced8", "step": 1, "event": "tool", "tool": "search_docs", "ok": true, "error": null}
{"trace_id": "722fa1edced8", "step": 2, "event": "model", "kind": "tool_call", "tokens": 670, "cost_usd": 0.000679}
{"trace_id": "722fa1edced8", "step": 2, "event": "tool", "tool": "read_doc", "ok": true, "error": null}
{"trace_id": "722fa1edced8", "step": 3, "event": "model", "kind": "tool_call", "tokens": 788, "cost_usd": 0.001101}
{"trace_id": "722fa1edced8", "step": 3, "event": "tool", "tool": "cite", "ok": true, "error": null}
{"trace_id": "722fa1edced8", "step": 4, "event": "model", "kind": "final", "tokens": 1100, "cost_usd": 0.001771}
{"trace_id": "722fa1edced8", "step": 4, "event": "stop", "reason": "final"}
== 离线集回归 ==
用例 退货的运费由谁承 answer_ok=True cite_ok=True stop=final cost=$0.001771
用例 订单完成后多久能 answer_ok=True cite_ok=True stop=final cost=$0.001771
用例 电池保修多久 answer_ok=True cite_ok=True stop=final cost=$0.001771
成功率 3/3 = 1.000 95% Wilson 区间 [0.438, 1.000] 单请求均价 $0.00177
读法有三条。第一,trace 的 8 行共享同一个 trace_id(该值每次运行随机生成,故与上文示例不同),step 单调递增,cost_usd 为累计值,任何一次失败都能定位到具体步与具体工具。第二,单请求最终成本 0.00177 美元,与第 11 节按 3 次调用估算的量级一致,说明成本模型可用。第三,3 条用例全部通过但区间下界只有 0.438,这正是第 1 节结论的直接证据:样本量不足时「全过」不构成发布依据,这也是第 7 节要求黄金集 200 条的原因。
例 3:配置分层与密钥注入
# configs/default.yaml —— 全部默认值,不含任何密钥
app:
name: docqa
env: dev
model:
provider: openai-compatible
base_url: ${DOCQA_BASE_URL}
id: qwen3-32b-instruct
temperature: 0.0
max_output_tokens: 800
timeout_s: 20
max_retries: 2
agent:
max_steps: 6
budget_usd: 0.02
# configs/prod.yaml —— 只覆盖环境差异
app:
env: prod
agent:
max_steps: 5 # 生产收紧一步,压缩尾延迟
budget_usd: 0.015
obs:
log_level: info
sample_rate: 1.0
# configs/schema.py —— 启动时校验,失败即退出
from pydantic import BaseModel, Field
class AgentCfg(BaseModel):
max_steps: int = Field(ge=1, le=12)
budget_usd: float = Field(gt=0, le=0.2)
class ModelCfg(BaseModel):
id: str
temperature: float = Field(ge=0.0, le=2.0)
timeout_s: int = Field(ge=1, le=120)
class Cfg(BaseModel):
agent: AgentCfg
model: ModelCfg
在做什么:default.yaml 给出可运行的全部默认值,prod.yaml 只写差异,密钥以 ${VAR} 形式引用并由启动时的环境变量替换。
为什么这样做:默认值全量存在时,新增配置项不会导致老环境启动失败;环境文件只写差异时,环境之间的漂移可被 diff 直接看出。
去掉会怎样:把密钥直接写进 prod.yaml 并提交,密钥进入 git 历史,轮换成本高于重写配置;没有 schema.py 时,max_steps: 60 这类笔误不会被发现,单请求成本上限被放大十倍。
例 4:容器与健康检查
FROM python:3.12-slim AS builder
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev
FROM python:3.12-slim AS runtime
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
COPY prompts ./prompts
COPY configs ./configs
ENV PATH="/app/.venv/bin:$PATH"
RUN useradd -m app && chown -R app:app /app
USER app
EXPOSE 8080
HEALTHCHECK --interval=15s --timeout=3s --retries=3 \
CMD python -c "import urllib.request as u; u.urlopen('http://127.0.0.1:8080/readyz', timeout=2)"
CMD ["uvicorn", "docqa.api:app", "--host", "0.0.0.0", "--port", "8080"]
在做什么:两阶段构建把编译依赖留在 builder,运行镜像只带虚拟环境与源码;USER app 去掉 root;HEALTHCHECK 打 /readyz 而非 /healthz。
为什么这样做:镜像不带密钥与数据,回滚时只需换标签;非 root 运行限制容器逃逸后的影响面。
去掉会怎样:单阶段构建把编译器与缓存带进镜像,体积增至三倍,冷启动变慢;用 /healthz 做健康检查时,索引短暂不可读会触发容器重启,形成重启循环。
例 5:CI 中的合并门槛
name: ci
on: [pull_request]
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
- run: uv sync --frozen
- run: uv run ruff check src tests
- run: uv run pytest -q
- run: uv run python -m docqa.eval.run_eval --config configs/default.yaml --out current.json
- run: uv run python -m docqa.eval.gate --baseline baseline.json --current current.json
- run: uv run gitleaks detect --no-git -v
在做什么:依次执行静态检查、单元测试、离线评测、与基线比较、密钥扫描。
为什么这样做:评测与基线比较放在 CI 中,使「退化」在合并前被发现,而不是在发布后由用户报告。
去掉会怎样:没有 gate 步骤时,评测只作为报告存在,退化不影响合并;没有密钥扫描时,本地调试用的密钥容易随提交进入历史。
易错点
以下六条均可在仓库、日志或发布记录中直接检查。
1. 无评估直接上线:改动只经过人工试用。检验方法是在 CI 中查找评测步骤与基线文件,缺一即视为无评估;小样本的「全部通过」不构成证据,3 条用例的 95% 区间下界为 0.438。
2. 密钥入库:密钥写在
configs/*.yaml、.env或 notebook 中并提交。检验方法是对全历史执行密钥扫描;一旦进入历史,必须轮换而非删除。3. 无回滚方案:镜像使用
latest标签,或数据层变更不可逆(字段改名、类型变更)。检验方法是做一次回滚演练,记录耗时;超过 5 分钟即不合格。4. 日志不含 trace id:只有最终答案与总耗时,无法定位失败步骤。检验方法是随机抽 20 条日志,看能否从其中一条还原出完整的工具调用序列。
5. 成本无上限:循环没有最大步数或预算判断,输入长度未截断。检验方法是构造一个会反复调用工具的输入,观察是否在有界步数内终止并返回降级结果。
6. 把 demo 当产品:缺少鉴权、限流、健康检查与告警,异常时无降级路径。检验方法是按第 12 节的交付清单逐项打勾,缺项即未交付。
关联笔记
- 前置 Agent工作流与编排:给出循环、状态与多步编排的语义,本篇把这些语义固化为五条不变量与停止条件枚举。
- 前置 MCP协议:工具描述与调用的协议层规范,本篇的工具契约与之一致,可直接映射为 MCP 的
tools/list与tools/call。 - 对照 成本-延迟-质量权衡:本篇第 11 节的成本表与第 8 节的限流取值,来自该篇的三角权衡方法。
- 对照 模型评估矩阵:本篇第 7 节的离线、在线与回归三层评估,具体指标定义与基准选择参照该篇。
- 后续 Harness与Loop工程:把本篇的循环骨架扩展为可插拔的运行时,处理并发、恢复与上下文预算。
达标检测
- [ ] 写出文档问答 Agent 的六条验收条件与失败定义,说明每条如何判定,并解释为什么失败定义必须显式列出。
- [ ] 用 Wilson 公式计算 与 的 95% 区间,说明黄金集为何取 200 条而不是 20 条。
- [ ] 画出六层架构图并标注依赖方向,指出把数据访问写进接口层会导致哪两类测试无法进行。
- [ ] 运行例 2 的脚本,把
BUDGET_USD改为 0.001 与 0.02 各跑一次,比较stop字段与返回内容,解释降级路径的差异。 - [ ] 在例 2 中新增一个
list_sources工具,要求参数校验覆盖枚举与必填字段,并补一条单测验证非法参数被拒绝。 - [ ] 按第 11 节的成本结构,计算兜底率从 3% 降到 2% 的月度节省,并说明为什么优化顺序应先降兜底率而非压缩 token。
- [ ] 列出回滚演练的五个步骤与每步的预期耗时,给出总耗时不超过 5 分钟的配置前提。
参考来源
- Chip Huyen, Designing Machine Learning Systems, O'Reilly, 2022 —— 对应第 7 节的三层评估、第 9 节的监控指标与第 12 节的交付清单。
- Anthropic, "Building effective agents", 2024 —— 对应第 4 节的循环不变量、第 5 节的工具描述写法,以及「先用最简单方案」的设计取向。
- Model Context Protocol 规范(modelcontextprotocol.io) —— 对应第 5 节的工具声明与调用契约,以及本篇工具表与
tools/list、tools/call的映射。 - Google, "Rules of Machine Learning" —— 对应第 7 节「先建评估再做优化」的顺序,以及第 12 节分阶段交付的节奏。
- Hugging Face Transformers 官方文档(
GenerationConfig中max_new_tokens、temperature等字段的语义) —— 对应例 3 的模型配置项与例 4 中推理服务的启动参数。