w wyl123ly 的博客
MD

端到端项目模板

44 KB 2026.10.18 原文件

端到端项目模板

定义

端到端项目模板(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.8530 条无答案样本应为拒答
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_tokensqwen3-32b-instruct、0.0、800温度取 0 保证可复现
循环agent.max_steps、agent.budget_usd6、0.02两者共同构成成本上界
工具tools.timeout_s、tools.allow_write3、false写操作默认关闭
观测obs.log_level、obs.sample_rateinfo、1.0首版全量采样

密钥三条规则:不入库、不写进镜像、不打印。代码只从环境变量读取,.env.example 只保留键名与占位值,CI 用 gitleaks 一类工具扫描提交内容。

4 Agent 循环的五条不变量

循环是系统中最容易出错的部分,因为它的状态分布在多轮之间。以下五条不变量必须在实现中显式保证,任一条缺失都会产生难以复现的故障。

  1. 每轮有唯一标识。trace_id 在一次请求内不变,step 从 1 递增。没有 step 时,日志无法排序,也无法判断是否死循环。
  2. 工具参数先校验后执行。模型产出的参数是待验证的输入,类型、枚举、必填字段、取值范围都要检查;校验失败作为工具结果回填,让模型自行修正。
  3. 每步累计成本,超预算立即终止。累计值 , 为单位 token 价格。终止后返回降级结果并标记 stop=budget。
  4. 终止条件完备。至少包含:最终答案、步数上限、预算上限、墙钟超时、不可恢复错误。缺少任一条都可能挂死。
  5. 工具输出按数据对待。工具返回的文本可能含指令性语句,这些语句不具有指令效力,不得进入系统提示,也不得改变权限判定。

循环的伪代码如下,停止原因的取值是有限的枚举,便于统计。

输入: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,一行一个事件,字段固定。

字段类型说明
tsISO 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/5P2复核提示词与索引版本

10 安全:权限、输入过滤、人工审批

权限按最小必要授予。工具分只读与可写两类,可写工具默认关闭;模型端点使用独立的密钥与配额,避免与其他服务共享;数据层对文档做来源级权限过滤,检索时在索引侧过滤而非在结果侧过滤,避免越权内容进入上下文。

输入过滤与输出校验分工明确:输入侧限制长度、块数与字符集,识别明显的注入模式;输出侧校验引用必须来自本次检索结果,答案中的数字与日期必须能在引用片段中找到依据。

风险控制检查点
越权读取文档索引侧按来源过滤检索返回前
提示注入工具输出按数据处理,不进入系统提示消息组装时
越权写操作写工具默认关闭,需审批工具执行前
密钥泄漏只从环境变量读取,提交扫描CI
数据外泄输入中的敏感字段脱敏后再送模型编排层入模前
成本攻击单请求预算上限与租户级配额每步累加时

人工审批适用于三类动作:写外部系统、发送对外内容、金额或权限变更。审批不是把请求阻塞在循环里,而是把动作转为待办并返回中间状态,由人确认后从检查点继续。

11 成本预算与容量

单请求成本由调用次数与 token 数决定。文档问答 Agent 每次请求 3 次模型调用,输入合计约 4200 token、输出合计约 450 token,按输入 0.5 美元/百万 token、输出 1.5 美元/百万 token 计:

按日均 1 万请求、每月 30 天,月成本结构如下。

项目用量单价月成本(美元)占比
模型调用30 万次请求0.0028 美元/次83313.4%
人工兜底9000 次(3%)0.60 美元/次540086.6%
索引重建4 次0.30 美元/次1.20.02%
日志与追踪存储约 2.4 GB按量10.02%
合计6235100%

这张表改变优化顺序:模型成本只占一成,兜底成本占八成以上,因此降低兜底率是最大的成本杠杆,而不是压缩 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 中推理服务的启动参数。