最佳实践案例库
单个功能的参数正确，不等于整条业务链路正确。下面的案例从“谁调用、一次工作怎么算、失败后 怎么办、如何验收”出发，给出可以直接用于设计评审和上线验收的组合方式。示例值是起点，生产 阈值应根据真实流量、模型价格、延迟和风险承受能力校准。
能力覆盖矩阵
Section titled “能力覆盖矩阵”| 能力或端点 | 契约成熟度 | 对应案例 |
|---|---|---|
| Project、Gateway Key、Route 与环境隔离 | 运维能力；按部署版本核对 | 案例一、二 |
| Chat Completions、同步 Responses、可移植 Messages | compatible | 案例二、三、七 |
| Project 预算、Token Guard、Run 预算与 Attempt | Run 部分为 v0.7 experimental | 案例三 |
| Work Unit、Run、Outcome 与 Governance Export | v0.7 experimental | 案例四、五、十三 |
| 延迟 Responses | 创建端点 compatible；资源操作 experimental | 案例六 |
| 流式响应 | 按具体端点/Profile 核对 | 案例七 |
| Admin、Metrics、失败捕获、备份与升级 | 运维能力；按部署版本核对 | 案例八 |
| Embeddings 与 Rerank | Embeddings compatible；Rerank 契约为 experimental，但本构建无可创建后端 | 案例九 |
| 原生 Anthropic Messages 与 Token Count | compatible | 案例十 |
| Moderations、Images、Speech 与 Transcriptions | experimental | 案例十一 |
| Files、Batches 与 Async Invocations | experimental；Async 本构建无可创建后端 | 案例十二 |
案例一：SaaS 服务隔离 Project 与 Key
Section titled “案例一：SaaS 服务隔离 Project 与 Key”场景： 一个后台服务同时有开发、预发布和生产环境，生产中还有客服 Agent 与离线分析任务。
推荐把环境先分开，再按确实需要独立预算、路由或审计边界的工作负载拆 Project：
| 对象 | 推荐划分 | 原因 |
|---|---|---|
| Project | support-prod、analytics-prod、support-staging | 分别设置 Route 授权、日预算和并发上限 |
| Gateway Key | 每个调用服务一把；编排方和验收方再分开 | 可以单独吊销、轮换和最小化 Scope |
| Route alias | 生产使用 support-chat-prod，预发布使用 support-chat-staging | Provider/Deployment 调整不进入业务代码 |
运行治理中，客服编排 Key 使用 inference、work_unit:create、run:create、run:attach；独立
验收服务使用 outcome:write。不要给所有服务共用一把全权限 Key，也不要为了每个 HTTP 请求创建
Project——Project 是策略与账务边界，不是请求追踪 ID。
验收： 用预发布 Key 请求生产别名应被拒；吊销一把 Key 不影响其他服务；账单和 Attempt 能按 Project 区分；验收 Key 不能发起模型调用。
案例二：多 Provider 路由与故障转移
Section titled “案例二：多 Provider 路由与故障转移”场景： support-chat-prod 有主、备两个 Deployment，希望主站点短时故障时继续服务。
将 Route 配置为 ordered，为主、备目标设置明确优先级，并尽可能让两者位于不同区域、账号、
凭据和配额故障域。round_robin 用于分流，不构成主备。只把语义能力相当、价格已配置且经过
兼容性验证的目标放进同一 Route。
跨目标回退适用于 OpenAI 兼容 Chat、同步 Responses、可移植 Messages 和 Embeddings，而且还要 同时满足“尚未向客户端发出首个 payload”与“错误被分类为非歧义、可安全重试”。认证/权限错误、 请求字段错误、上游 500/502/504、请求发出后的连接丢失等歧义失败不会自动切换。原生 Anthropic Messages 固定一个目标；延迟 Responses 在提交时固定一个 Deployment；资源类端点在候选目标不唯一 时会以 409 拒绝。
建议按以下顺序上线：
- 上游可枚举时读取真实模型列表；不可枚举时记录原因并使用显式 operator-declared 目标；
- 用管理员明确触发的能力检测验证工具、流式或其他必需字段；
- 为主、备目标分别制造一次可控失败，确认 Attempt 记录了选择和拒绝原因；
- 检查备用模型没有静默降低业务必需能力，再开放生产流量。
模型列表只证明“谁存在”，不证明“它能做什么”；能力证据必须独立建立。
验收： 主目标健康时不发生多余回退；制造一次明确未发送且可重试的失败，确认最多产生配置 允许的 Attempt；制造一次歧义失败，确认没有静默切换；首 payload 后的失败返回中断而不是混合 输出；没有已知价格时按治理规则拒绝。
相关配置见配置参数参考：Gateway、Retry 与 Circuit Breaker。
案例三：同时限制 Project、Run 与重试成本
Section titled “案例三：同时限制 Project、Run 与重试成本”场景： 一个工单 Agent 每次完整执行最多花费 0.50 USD，生产 Project 还要受每日总预算限制。
为 Project 设置日预算，再创建 budget_micros_usd: 500000 的 Run。每次模型调用显式设置合理的
输出上限，并关闭 SDK 自动重试，由应用根据 Halro 错误码决定是否重试。网关在 Provider I/O 前
原子检查 Project 日预算与 Run 的 committed + reserved + pending；Provider retry/fallback 的
成本仍归原 Run。
| 结果 | 处理 |
|---|---|
run_budget_exceeded | Halro 不会自动关闭 Run；应用可改用仍在余额内的请求，或按业务策略 close |
token_guard_blocked | 成本上限触发时调整请求/模型/策略；临时封禁时等待 TTL 或由管理员处置 |
有 Retry-After 的 429 | 按该值退避，并设置应用级最大次数 |
| 结果不明确的网络失败 | 先承认可能已经计费；重发是新的费用事件 |
Token Guard 先用 observe 或 alert 收集基线，再逐步设置单请求 Token、每分钟 Token、成本、并发、
错误率和来源 IP 阈值，确认误报后才启用 temporary_block。固定 RPM、TPM、预算和并发限制仍是
确定性边界；EWMA 只做相对异常检测和告警。
生产环境建议保留 gateway.pricing_unknown_policy: reject。即使全局允许未知价格，附加到 Run 的
请求仍必须有已知价格，否则返回 409 price_unavailable，因为 Run 预算不能对未知金额准入。
验收： 故意把 Run 预算设低，确认 Provider 未被调用；触发一次回退，确认所有 Attempt 仍属于 同一 Run；对结果不明确的失败，报表不能把费用乐观地归零。
Price Version、Project、Token Guard 与 Run 预算的权威操作顺序见 版本化定价与 Project/Token Guard。
案例四：客服工单的运行治理闭环
Section titled “案例四：客服工单的运行治理闭环”场景： Agent 处理工单，人工质检决定 accepted 或 rejected。
- Work Unit：工单
8472，表示最终只统计一次的业务结果； - Run：一次完整 Agent 执行；人工退回后重跑则创建第二个 Run；
- Request/Attempt：Run 内的模型调用及 Provider 尝试；
- Outcome：质检系统按
ticket_result v1上报的结构化结果。
质检系统只发送 Definition ID、值、observed_at 和可选的脱敏证据编号/摘要。例如
evidence_ref: ticket_8472_acceptance_3 可以指向内部证据，但不要发送 Prompt、模型回答、评语
全文、URL 或凭据。Outcome 写入 Key 应独立于 Agent Key。
当 Work Unit 仍开放，或还有 pending/inflight Attempt 时，结果是 provisional。只有 Work Unit
已关闭且没有在途 Attempt，才会在 Summary 中计入 matured_units，再用于成功率与单位成功成本。
成本完整性是 complete/partial，Outcome 完整性是 complete/partial/unknown；都不能把不完整按
零成本或失败处理。
验收： 第一次执行和重跑产生两个 Run，但一个工单只进入分母一次；修订 Outcome 后旧记录仍 可追溯；缺少验收结果时 coverage 下降，而不是把该工单算作 rejected。
完整接口流程见接入运行治理。
案例五：文档抽取使用不可变输入版本
Section titled “案例五：文档抽取使用不可变输入版本”场景： 同一文件会被用户替换，抽取结果需要业务验收。
把“文件 ID + 不可变版本或内容摘要”作为 Work Unit 的业务幂等边界。一次完整抽取流水线是一个 Run，其中 OCR、结构化和校验可以包含多个模型请求。文件内容改变后创建新 Work Unit，不要继续 向旧对象附加 Run；同一版本因执行失败而重跑时，才在原 Work Unit 下创建新 Run。
创建 Work Unit、Run、关闭和 Outcome 写入都使用稳定且各不相同的 Idempotency-Key。请求超时
后用相同 Key 与相同正文重放；不要把随机生成的新 Key 当作重试。
验收： 相同文件版本的重复创建返回同一资源；正文改变而复用 Key 时返回冲突；文件替换后的 费用与结果不会混入旧版本。
案例六：长任务使用延迟 Responses
Section titled “案例六：长任务使用延迟 Responses”场景： 报告生成需要数分钟，HTTP 客户端不应一直保持连接。
在 Project 上明确启用延迟响应，调用 Responses 时设置 background: true。Idempotency-Key 是
可选的，但生产调用应使用稳定值：相同 Key、正文和 X-Halro-Run-ID 归因返回同一记录；其中任一
项改变却复用 Key 都返回 409。
需要费用归属时同时传 X-Halro-Run-ID。提交成功后持久化响应 ID，由任务系统轮询或领取结果。
当前边界必须进入容量设计：请求最大 256 KiB，存储结果最大 1 MiB，结果 TTL 为 24 小时；首次
成功取回后最多再保留 15 分钟，期间仍可重复 GET，之后返回 404。预算在任务出队执行时准入，因此
超预算任务可能先返回 queued，稍后变成 failed，而不是提交请求立即失败。
延迟执行仍受 gateway.route_total_timeout 约束，默认 2 分钟。报告可能生成数分钟时，应按真实
最长生成时间设置该值，并保持 server.shutdown_timeout >= gateway.route_total_timeout；超时任务会
变成 deferred_response_timeout，且可能已经计费。
延迟中的上游调用在 Gateway 重启时不能无缝继续。需要重做时使用新的 Idempotency-Key 创建新的 deferred submission；只有“完整 Agent 执行重新开始”才创建新 Run，输入业务对象未改变时通常仍在 原 Work Unit 下。
验收： 相同 Idempotency-Key 与正文的重复提交不产生第二项任务；Run 预算不足时任务最终失败 且不会到达 Provider；模拟重启后任务不会永久显示进行中；首次成功取回后 15 分钟内可重复 GET， 窗口结束后应用给出明确的过期状态；超过执行总超时后进入明确失败终态。
接口字段见Responses API。
案例七：正确处理流式中断
Section titled “案例七：正确处理流式中断”场景： 聊天界面边生成边展示内容，上游在输出一半时断开。
应用至少区分“尚未显示任何内容”和“已经向用户显示部分内容”。前者可以在受控次数内重新发起
完整请求；后者应标记为中断，让用户选择重试，不能自动把第二次回答接在已显示文本后。Responses
调用还要区分 response.completed、response.incomplete 和 error；incomplete 可能只是达到
输出上限，不等于成功完成。
验收： 在首事件前和首事件后分别制造断流；确认前者可按策略重试，后者保留“部分结果”状态； UI 不把两个 Provider 的文本拼成一条完整回答；每次重发都显示为独立请求和费用。
案例八：生产安全、诊断与升级恢复
Section titled “案例八：生产安全、诊断与升级恢复”场景： Halro 部署在生产内网，需要远程管理、Prometheus 采集和受控失败诊断。
Gateway、Admin 与 Metrics 使用不同监听地址。Admin 经 HTTPS 反向代理访问，配置准确的
admin.external_origin、admin.mfa_policy: required 和网络访问控制。非回环 Metrics 同时要求
独立 credential_file 和完整 mTLS/Client CA；不要复用 Gateway Key。Provider 凭据、Master Key
和数据目录分别管理，备份中单独确认 Master Key 恢复路径。
gateway.failure_capture 默认保持关闭。启用后会保存脱敏后实际发往上游的请求正文和上游失败
响应，仍可能包含 Prompt、工具参数等客户内容。记录按请求和 Project 绑定并用 Master Key 加密，
Admin 读取会写审计；截断和脱敏仍不能消除全部敏感数据风险。启用前完成隐私/DLP 评审，限制单条
大小、每日条数与保留期，并验证到期清理。运行治理 evidence_ref 只保存不透明编号。
升级运行治理版本前停止 Halro 实例，取得数据目录独占锁，再执行 backup create 和
backup verify。verify 只验证归档认证和 manifest；真正的可恢复性还要用隔离 staging 环境做
restore drill。用新二进制执行配置检查，启动后检查 Accounting、Governance readiness、watermark
和一条受控业务闭环。需要回退时恢复升级前备份，不要让旧二进制打开已升级的数据目录。
验收： 非回环明文 Admin 会被配置校验拒绝；准确的 external_origin、MFA 绑定和登录验证是
本文定义的生产门禁，当前 Halro 不会因为 mfa_policy: optional 自动拒绝启动；Metrics 凭据不能
调用模型；诊断数据按期删除；恢复演练能使用独立恢复的原 Master Key 解密账务与治理数据。
案例九：Embedding 索引与 Rerank 规划边界
Section titled “案例九：Embedding 索引与 Rerank 规划边界”场景： 知识库先用 Embeddings 召回候选文档，并评估增加 Rerank 排序。
一个向量索引版本固定模型、维度、归一化方式和文本切分规则；模型或维度改变时创建新索引并重建，
不要在同一索引混用向量空间。Route alias 应体现索引版本，例如 kb-embed-v2。批量输入前按所选
Profile 核对字段限制：部分 Profile 只接受单字符串，维度能力也不同。
/v1/rerank 已有 experimental 契约和实现，但当前构建唯一对应的
bedrock.agent-runtime.rerank.cohere-v3-5.v1 Profile 被 withheld，Admin 写路径不会允许创建该连接，
因此新实例不能实际提供这个端点。当前应先用 Embeddings/关键词召回并接入外部已验收的排序方案；
只有未来构建明确开放该 Profile 后，才按有界候选集、原始文档 ID 映射和真实 Provider 门禁接入 Halro Rerank。
验收： 同一索引版本的向量维度恒定；切换模型前完成离线召回质量对比和全量重建；当前版本
不会把 /v1/rerank 列入可上线能力。未来开放后再验证返回顺序映射、费用和不可用时的降级排序。
接口字段与成熟度见Embeddings和实验性端点一览。
案例十：Anthropic 原生能力与 Token Count
Section titled “案例十：Anthropic 原生能力与 Token Count”场景： 应用需要 Anthropic 特有字段，同时在提交前估算输入 Token。
默认 portable Messages 保留跨 Provider 可移植性。只有业务明确依赖原生字段时，才发送
Halro-Route-Mode: native；它会固定到一个 Anthropic-wire Profile，并关闭跨 Provider fallback。
不要在 native 路径里再设计“自动换一家”的假设。
POST /v1/messages/count_tokens 只走直接 Anthropic 连接，不支持 portable 或流式。它由 Anthropic
返回计数，没有 input/output token 计费跨度；普通按 Token 计价为 0，但 Price Version 若配置了
固定每请求费用仍会计费。它是真实 Provider 调用，会留下 Attempt 并占用请求预算。计数可用于提示
或提前裁剪输入，不能替代 Halro 在真正生成请求上的 TPM、Token Guard 和成本准入。
验收： portable 与 native 使用分别测试；native 目标故障时不出现跨 Provider Attempt； Count Tokens 的模型别名与随后生成的目标一致，否则预估不能代表实际请求。
协议差异见Anthropic Messages和Token 计数。
案例十一：内容安全与媒体生成链
Section titled “案例十一：内容安全与媒体生成链”场景： 用户提交提示词生成图片，并可把结果转语音；上传音频还能转写。
在业务风险模型需要时，先用 /v1/moderations 检查输入，再调用 Images、Speech 或
Transcriptions；对模型生成内容是否再次审核，由产品的安全规则决定。四类端点当前都是
experimental，分别使用声明了对应能力的 Route 和最小权限 Key，且必须唯一解析到一个 eligible
target；不能从 Chat 可用推断媒体能力也可用。
当前可创建的媒体后端来自 openai.media-resources.v1。Bedrock Runtime 的 Titan Image Profile 虽有
实现与 experimental 契约，但在本构建被 withheld，不能据此创建 Deployment。
为每一步保存 Halro request ID、业务对象 ID、策略版本和用户可见状态。媒体结果失败时不要用文本 模型的回答伪装成功；安全拒绝、能力不支持、Provider 失败和客户端取消应是不同业务状态。
验收： 用允许、拒绝和边界样本验证输入/输出策略；确认不支持字段在 Provider I/O 前被拒； 真实 Provider 门禁单独执行，协议 fixture 不能作为媒体质量或安全验收。
字段、偏差和实验成熟度见实验性端点一览。
案例十二：Files、Batches 与 Async 资源生命周期
Section titled “案例十二：Files、Batches 与 Async 资源生命周期”场景： 先上传 JSONL，再创建 Batch；同时评估 Bedrock Async Invocation 的未来接入。
创建 Files 和 Batches 必须使用稳定的 Idempotency-Key，并持久化 Halro 返回的 opaque ID 与所属
Project。资源型 Route 必须唯一解析到一个兼容目标；不要配置多个候选后期待自动回退。File 保留
30 天，Batch 记录保留 7 天，业务清理任务应早于这些边界读取所需结果。
Async 端点和 7 天 TTL 已进入 experimental 契约与实现，但当前唯一对应的
bedrock.runtime.async.nova-reel-v1.v1 Profile 被 withheld，Admin 写路径不会允许创建该连接。因此本
构建不能实际提交、读取或取消 Async Invocation；下面的选路与取消语义是未来开放 Profile 后的契约，
不是当前可上线能力。
资源选择目标的方式不同：创建 File 时用 Halro-Route 指定别名；Batch 继承 input File 已绑定的
目标；未来开放的 Async Invocation 从请求的 model 解析目标。不要把一种资源的选路规则套到另一种。
Anthropic Batch 的输入由 Halro 本地保存并逐行校验；提交前控制文件大小、行数与每行字段。只有在 依赖任务进入终态并保存所需结果后才删除 File，因为删除会同时移除上游对象、metadata 与本地内容。 未来开放后，Async cancel 仍会 fail closed，因为 Bedrock 没有对应取消操作；不能把取消请求当作已经停止。
验收： 重放相同 File/Batch 创建操作不产生第二个资源；跨 Project 读取不可见；轮询有上限和 退避；到期与删除可解释，费用不会因删除而撤销。当前版本应确认 Async 不被列入可上线能力；未来 开放后再验证其 409 取消响应绝不被解释为已经停止。
全部资源端点的状态语义见实验性端点一览。
案例十三：Governance Export 交给 FinOps
Section titled “案例十三：Governance Export 交给 FinOps”场景： 财务平台要把业务成功、模型成本和费用归属放进同一报表。
Halro 不会主动推送外部 FinOps。受控作业必须取得并关联两份数据：Governance Export 提供
Work Unit、Run、Outcome、Definition 和治理 manifest；Usage Export schema 6 提供 Attempt、费用、
work_unit_id 与 run_id。Governance 的 Run 行只有预算，不含实际成本，不能单独用于费用对账。
当前 Governance export 由管理员会话触发并写入服务器本地目录；Usage 由周期导出产生，需要立即
刷新时则停机执行 halro usage compact 和 halro usage verify。分别校验两份 manifest、Usage
reconciliation、文件 SHA-256 和记录数，再按稳定 ID join。SHA-256 只能检查内容完整性，不能认证
传输来源；外送需使用受信通道，或对 manifest 另做签名/MAC。
按 Summary 规则传播 cost_completeness、outcome_completeness 和 unknown Attempt，不要从双
watermark 自行推导 partial，也不要把不完整数据填成 0。对账至少比较 Project、Work Unit、Run、
Attempt 数量与成本总额；不把 Prompt/Response 或凭据送入 FinOps。
Governance 的 accounting watermark 描述完整账本快照，Usage last_sequence 只描述最高已导出
Attempt；Run/Work Unit 在最后一次 Attempt 后关闭时，前者仍会前进。两者不能直接比较来证明完整，
也不能因为数字不同就断言需要等待补数。
验收： 同一双导出重复导入不增加金额；Usage verify 或文件校验失败时整批拒绝；无法停流取得 受控截止点时标记 partial；按相同 Project/时间边界重算后差异可解释。
当前可执行流程见Usage 与 Governance 数据交接 FinOps，运行治理报表 口径见接入运行治理。
上线评审清单
Section titled “上线评审清单”- Project 与 Key 能对应清晰的环境、责任方、预算和最小 Scope；
- 上游可枚举时使用真实列表；不可枚举时记录原因并显式声明，能力证据与存在性独立；
- 客户端重试、Halro Attempt 上限和总超时不会叠加成无界成本；
- Work Unit 表示一次最终业务结果，Run 表示一次完整执行；
- Outcome 由独立权限写入，只含结构化结果和脱敏证据引用；
-
partial、unknown、provisional在报表和业务决策中有明确处理； - 延迟与流式任务对重启、中断、过期和重复提交有状态机；
- 配置校验、备份恢复、权限隔离和受控业务演练均已通过。