这份附录怎么用
附录 A 不是词典，而是评审时的共同语言。
当有人说“这个能力不稳定”“网关应该处理”“降级一下就行”，速查表用来说明：他说的“能力”包含哪些承诺，“网关”负责到哪一层，“降级”之后用户看到什么。
每组术语给四样东西：定义、判断条件、常见误用、对应章节。判断条件尽量写成可观察的事实，而不是形容词。
一、能力（capability）
定义：产品对外承诺的一项可验证行为，例如“生成一段可发送的私信回复”。
判断条件：
| 要素 | 必须回答的问题 |
|---|---|
| 输入 | 接受什么，长度上限多少，哪些字段必填 |
| 输出 | 返回什么结构，允许哪些自由文本 |
| 质量 | 用什么指标验收，谁来评 |
| 延迟 | 首字与完整的预算分别是多少 |
| 成本 | 单次上限与月度上限 |
| 失败 | 不可用时是缺失、变弱还是阻塞 |
常见误用：
- 把模型调用当成能力，没有质量与失败语义。
- 只写“尽量快”“尽量准”，无法验收。
- 一个能力对应多个模型，却没有说明切换规则。
对应章节：1.1、1.2、1.3、13.1。
二、契约（contract）
定义：能力、请求、响应与错误之间的稳定约定，不随模型或供应商变化。
判断条件：业务方只依赖契约，不依赖具体模型 ID；更换模型不需要改业务代码。
常见误用：
- 业务代码直接拼供应商的请求体。
- 错误码直接透传供应商的私有码。
- 契约里包含模型名称，导致无法路由。
对应章节：1.1、3.2、7.1。
三、网关（gateway）
定义：产品与模型之间的稳定层，负责认证、配额、路由、缓存、观测与审计。
判断条件：
| 该放进网关 | 不该放进网关 |
|---|---|
| 密钥管理、租户识别 | 业务规则与领域判断 |
| 配额与限流 | 长事务与多步编排 |
| 路由与重试 | 与具体页面强耦合的逻辑 |
| 统一观测与计量 | 需要人工审核的流程 |
常见误用：
- 把业务语义塞进网关，导致每次产品变更都要改平台。
- 网关保存会话状态，无法水平扩展。
- 网关吞掉错误，只返回空结果。
对应章节：3.1、3.2、3.3、13.2。
四、路由（routing）
定义：把一次请求分配到具体模型的过程。
判断条件：给定请求、模型档案与健康状态，输出确定，且能解释为什么选它、为什么没选其他。
五个维度：
| 维度 | 例子 | 通常在哪判断 |
|---|---|---|
| 任务 | 回复、摘要、审核、重排 | 能力标识 |
| 租户 | 主站、合作方、内部 | 网关 |
| 区域 | 境内、境外 | 网关 |
| 成本 | 经济、标准、前沿 | 网关 + 预算 |
| 健康 | 熔断、限流、延迟 | 网关 |
常见误用：
- 路由只按价格，忽略质量与区域。
- 路由结果不可见，出问题无法复盘。
- 健康检查只看端口，不看真实错误率。
对应章节：4.1、4.2、4.3。
五、流式（streaming）
定义：把生成结果分片发送给用户的传输方式。
判断条件：首帧、增量、计量、结束与错误五类事件都有明确定义；取消后不再发送增量。
常见误用：
- 把供应商的流式协议直接透给客户端。
- 首帧后失败还自动重试，导致重复文本。
- 取消只断开连接，不通知上游停止计费。
对应章节：5.1、5.2、5.3。
六、提示（prompt）
定义：发给模型的指令与上下文，属于可版本化的产物。
判断条件：有模板、变量、版本、所有者与变更记录；能灰度、能回滚。
常见误用：
- 提示写在代码字符串里，改了就覆盖。
- 变量直接拼接，用户内容可以伪造指令。
- 版本与模型版本没有绑定记录。
对应章节：6.1、6.2、6.3。
七、结构化输出（structured output）
定义：要求模型返回符合约定结构的结果，例如 JSON。
判断条件：有 schema、有校验、有失败分类、有修复预算与降级路径。
常见误用：
- 只写“请返回 JSON”，不做校验。
- 校验失败直接抛错，没有修复或兜底。
- 修复无限重试，成本和延迟失控。
对应章节：7.1、7.3。
八、预算（budget）
定义：一次请求或一项能力允许消耗的延迟、token 与金额上限。
判断条件：
| 预算 | 口径 |
|---|---|
| 延迟 | 首字与完整分别设上限，按阶段拆分 |
| token | 输入与输出分别设上限 |
| 成本 | 单次上限与租户月度上限 |
| 重试 | 次数与总预算共享，不单独放宽 |
常见误用：
- 只有总超时，没有阶段预算。
- 重试不消耗预算，实际耗时翻倍。
- 成本只在月底看账单，无法归因。
对应章节：8.1、8.2、8.3、12.2。
九、缓存（cache）
定义：复用之前的结果，减少模型调用。
判断条件：键包含能力、模型、提示版本、租户与权限范围；失效规则明确；语义缓存的误命中可评估。
常见误用：
- 键只有用户输入，租户之间串结果。
- 提示改版后旧缓存继续生效。
- 把个性化结果做成全局缓存。
对应章节：9.1、9.2、9.3。
十、降级（degradation）
定义：模型或依赖不可用时，用较弱但可解释的方式维持产品行为。
判断条件：每个能力有降级等级（可缺、可弱、必须阻塞），有触发条件、用户可见文案与恢复条件。
常见误用：
- 降级成空字符串，用户以为功能坏了。
- 降级链没有预算，越降越慢。
- 开关只增不减，没人知道当前状态。
对应章节：10.1、10.2、10.3。
十一、安全边界（trust boundary）
定义：数据、指令与执行权限在系统之间的分界。
判断条件：
| 边界 | 判断 |
|---|---|
| 密钥 | 不进入客户端，不进入提示，按租户隔离 |
| 数据出域 | 有字段白名单与区域限制 |
| 提示注入 | 用户内容不被当成系统指令 |
| 工具调用 | 模型只提议，执行方校验权限与参数 |
| 输出 | 有审查与拦截，且有申诉路径 |
常见误用：
- 把用户原文直接拼进 system 提示。
- 工具参数不校验，模型可以越权查询。
- 输出拦截没有审计，无法解释误杀。
对应章节：11.1、11.2、11.3。
十二、可观测与计量（observability & metering）
定义：记录一次请求的关键事实，使成本、质量与故障可以归因。
判断条件：一次请求至少包含请求 ID、能力、租户、模型、耗时分解、用量、结果与错误类别；采集端完成脱敏。
常见误用：
- 只记录成功请求，失败无法统计。
- 采样把错误也采掉。
- 计量与账单口径不一致，对账靠猜。
对应章节：12.1、12.2、12.3。
一页纸十二问
评审时逐条问：
- 这项能力的六面契约写全了吗？谁验收？
- 业务方依赖的是契约还是具体模型？
- 哪些职责在网关，哪些在业务？边界写在哪？
- 这次请求为什么落在这个模型上？能解释吗？
- 首帧前后失败分别怎么处理？会重复吗？
- 提示有版本吗？改坏了怎么回滚？
- 结构化输出失败几次后放弃？放弃后给用户什么？
- 延迟、token 与金额预算分别是多少？超了谁负责？
- 缓存键包含什么？什么变更会让它失效？
- 每个能力不可用时是缺失、变弱还是阻塞？
- 密钥、用户数据与工具权限的边界在哪？
- 一次请求的观测字段能回答哪几个问题？
十二个问题答不上来的部分，就是下一轮治理的输入。
术语对照
| 中文 | 英文 | 本文用法 |
|---|---|---|
| 能力 | capability | 产品对外承诺的可验证行为 |
| 契约 | contract | 不随模型变化的稳定约定 |
| 网关 | gateway | 产品与模型之间的稳定层 |
| 路由 | routing | 请求到模型的分配过程 |
| 流式 | streaming | 分片返回生成结果 |
| 提示 | prompt | 可版本化的指令与上下文 |
| 结构化输出 | structured output | 符合约定结构的模型输出 |
| 预算 | budget | 延迟、token 与金额上限 |
| 降级 | degradation | 用较弱方式维持产品行为 |
| 信任边界 | trust boundary | 数据、指令与权限的分界 |
| 计量 | metering | 记录用量与成本 |
| 退出条件 | exit criteria | 临时方案何时删除 |
同一个词在不同团队可能有不同含义。评审前先对齐这张表，比争论定义更省时间。
小结
术语的价值不在于统一叫法，而在于统一判断。两个人说“降级”，如果一个人指隐藏入口、另一个人指换成小模型，讨论一定错位。
这张表可以裁剪，也可以扩展。团队应该补上自己的本地术语：本产品最贵的能力是什么、哪类数据绝对不能出域、哪个开关是历史遗留。本地术语往往比通用术语更早暴露问题。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。