模型作为组件：契约、失效模式与选型

01 · 失效模式：把「模型会出错」拆成七条可检测的性质

七条失效性质，每条可检测——每条对应后面某一层的应对

flowchart LR
    CTX["组装上下文<br/>system·历史·检索·工具"] --> PRE["prefill<br/>读上下文"] --> SAMP["逐 token<br/>采样"] --> OUT["输出<br/>文本/JSON/tool_call"] --> ACT["执行动作"]

七条失效性质挂在哪一步

flowchart LR
    PRE["prefill"] & SAMP["采样"] & ACT["执行"]
    F4["④ 上下文标称 ≠ 有效"] -.-> PRE
    F5["⑤ 知识截止"] -.-> PRE
    F3["③ 指令遵循"] -.-> PRE
    F1["① 非确定性"] -.-> SAMP
    F2["② 幻觉"] -.-> SAMP
    F6["⑥ 供应商变更"] -.-> PRE
    F7["⑦ 越界"] -.-> ACT

    classDef stage fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef fail fill:#fdecea,stroke:#c0392b,color:#222
    class PRE,SAMP,ACT stage
    class F1,F2,F3,F4,F5,F6,F7 fail

要点

每条失效性质都有一个落在纸面上的数

02 · API 契约（一）：四家 API 的共同骨架

块列表进出；工具调用是协议不是功能；结构化输出保证语法不保证语义

%%{init: {"flowchart": {"wrappingWidth": 200}}}%%
flowchart LR
    App["应用"] -->|"req"| API["模型 API"]
    API -->|"asst + tc"| CHK{"校验·权限"}
    CHK -->|"执行"| Tool["工具"]
    Tool -->|"res/err"| App
    App -->|"hist+res"| API
    API -->|"ans"| Done(["结束"])
    CHK -->|"循环到无 tc<br/>或预算尽"| API

要点

同骨架不同实现——字段、状态、缓存顺序各异

03 · API 契约（二）：推理模型加了什么维度

思考按输出价计费且占 TTFT；effort 是倾向不是预算；思考是只搬运的跨轮状态

%%{init: {"flowchart": {"wrappingWidth": 200}}}%%
flowchart TB
    IN["输入：完整历史<br/>（含上轮 thinking）"] --> THINK["思考阶段<br/>thinking 不可见<br/>输出价计费 · 占 TTFT"]
    THINK --> OUT["可见输出<br/>文本 / tool_call"]
    OUT --> STATE["返回状态<br/>thinking block 等"]
    STATE --> NEXT["下轮必须携带<br/>（DeepSeek 例外）"]
    EFF["effort"] -.->|"控制思考量级"| THINK
    NEXT -.-> IN

    classDef stage fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef ctl fill:#eef6ff,stroke:#5b8fd6,color:#222
    class IN,THINK,OUT,STATE,NEXT stage
    class EFF ctl

要点

effort 一档 6 倍账单；历史也受校验约束

常见误区

• 「把模型名从 4.6 改成 5 就迁移完了」——thinking 默认开启、采样参数 400、tokenizer 多 30%、max_tokens 含思考

04 · 成本与延迟的账

输出价是输入的 4–6 倍、缓存读 0.1× 一次回本；TTFT 三段、总时长由输出主导

%%{init: {"flowchart": {"wrappingWidth": 170}}}%%
flowchart TB
    Q["排队"] --> P["prefill<br/>∝ 未缓存输入"]
    P --> T["思考<br/>∝ 思考 token"]
    T --> F(["首个可见 token<br/>（TTFT）"])
    F --> D["decode<br/>每 token 一步"]
    D --> E(["最后 token<br/>（总时长）"])

    classDef seg fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef mark fill:#f0f0f0,stroke:#888,color:#222
    class Q,P,T,D seg
    class F,E mark

要点

输出 4–6×、缓存读 0.1×——输出主导账单

多轮对话的输入账

• 多轮不缓存输入二次增长；开缓存后每轮只付写入部分，长会话总输入约降到 15%

05 · 选型：榜单只缩范围

榜单只缩范围——选型用自己的评测集 30–50 条；级联不漏难题、弃用周期也是维度

%%{init: {"flowchart": {"wrappingWidth": 170}}}%%
flowchart TB
    A["20+ 候选 → 硬约束"] -->|"榜单"| E["短名单"]
    E --> F["自家评测集"]
    F --> G{"过？"}
    G -->|"否"| H["放宽约束"]
    G -->|"是"| I["按每任务成本排"]
    I --> K["选定 + 替代模型"]

    classDef step fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    class A,E,F,I,K,H step
    class G dec

要点

30–50 条自测集选型；弃用通知最短 4 天

常见误区

• 「路由比级联省钱所以用路由」——只省 2–3 个百分点却会漏难题

06 · 客户端工程：调用侧要处理哪些失败

错误只重试「再试可能不同」的四类；超时分四层；幂等责任在工具侧

%%{init: {"flowchart": {"wrappingWidth": 180}}}%%
flowchart TB
    S(["业务层发起调用"]) --> CNT["数 token + 并发槽"]
    CNT --> SEND["发送（四层超时）"]
    SEND --> OK{"成功？"}
    OK -->|"是"| PARSE["解析 · 读 usage"]
    PARSE --> DONE(["返回 + 记 trace"])
    OK -->|"否"| CLS["错误分类<br/>（下图）"]

    classDef step fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef stop fill:#f0f0f0,stroke:#888,color:#222
    class CNT,SEND,PARSE,CLS step
    class OK dec
    class S,DONE stop

失败之后：先分类，再决定退避还是兜底

可重试走「退避 + 预算」，不可重试看有没有 fallback——两条路最终都回到发送或失败

%%{init: {"flowchart": {"wrappingWidth": 180}}}%%
flowchart TB
    CLS{"错误分类"} -->|"可重试"| BACK["退避<br/>指数 + 抖动"]
    BACK -->|"预算未耗尽"| SEND["回到发送"]
    BACK -->|"耗尽"| FB{"有 fallback？"}
    CLS -->|"不可重试"| FB
    FB -->|"换模型 / 降级"| SEND
    FB -->|"无"| FAIL(["失败返回 + 记 trace"])

    classDef step fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef stop fill:#f0f0f0,stroke:#888,color:#222
    class BACK,SEND step
    class CLS,FB dec
    class FAIL stop

要点

重试有预算、超时分四种、取消要传播