Token、Cost Budget 与 Model Routing

1. 为什么这组知识要一起学

把延迟、Token、成本、并发、缓存、队列和容量视为同一个系统问题，而不是上线后的补丁。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

性能优化要分解端到端时间与成本：模型、tool、retrieval、queue、serialization 各自有独立瓶颈。

Request → Queue → Context/Retrieval → Model TTFT+Generation → Tools → Final; 每段记录 latency/token/cost/in-flight

3. 核心机制

Token Accounting

token 成本按输入/输出/cache/reasoning 等 provider 维度记录；RunBudget 在超阈值时可降模型、停止探索或请求用户确认。

Cost Budget

token 成本按输入/输出/cache/reasoning 等 provider 维度记录；RunBudget 在超阈值时可降模型、停止探索或请求用户确认。

Model Routing

路由应根据 task class、质量阈值、延迟和成本选择模型，并通过 eval 验证。简单按 token 长度路由通常不足以代表任务难度。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

budget = RunBudget(deadline=deadline, max_cost=2.0, max_tokens=100_000)
model = router.select(task, budget)
async with capacity.acquire(model.provider):
    return await model.generate(request)

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

RunBudget 统一 token/cost/deadline；CapacityPolicy 管并发与下游 pool；router/cache 作为可替换策略。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 不要只优化平均 latency
• 并发受下游容量限制
• cache 要考虑 scope/freshness/privacy
• 模型路由需用 eval 证明质量未明显下降

7. Failure Modes

7.1 无限并行反而放大 429

当出现「无限并行反而放大 429」时，拆分 queue/context/model/tool/retrieval 延迟和 token/cost，查看 p95/p99 与 in-flight/429/pool saturation 的关联。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 缓存跨用户串数据

当出现「缓存跨用户串数据」时，拆分 queue/context/model/tool/retrieval 延迟和 token/cost，查看 p95/p99 与 in-flight/429/pool saturation 的关联。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 只看 token 不看 tool/queue latency

当出现「只看 token 不看 tool/queue latency」时，拆分 queue/context/model/tool/retrieval 延迟和 token/cost，查看 p95/p99 与 in-flight/429/pool saturation 的关联。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 成本预算耗尽后仍继续 Agent Loop

当出现「成本预算耗尽后仍继续 Agent Loop」时，拆分 queue/context/model/tool/retrieval 延迟和 token/cost，查看 p95/p99 与 in-flight/429/pool saturation 的关联。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

大模型质量高但贵；小模型/路由降低成本但增加错误模式；并发降低 wall time 但增加峰值资源。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

建立 p50/p95/p99、TTFT、tokens、tool latency、in-flight、success/cost 曲线，逐步提高 concurrency 找拐点。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Token Accounting 最容易被误解的点是什么？

token 成本按输入/输出/cache/reasoning 等 provider 维度记录；RunBudget 在超阈值时可降模型、停止探索或请求用户确认。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Request → Queue → Context/Retrieval → Model TTFT+Generation → Tools → Final; 每段记录 latency/token/cost/in-flight 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• OpenAI Agents SDK — Running agents
• OpenAI Agents SDK — Tracing
• OpenTelemetry — GenAI semantic conventions

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。