核心原语：七个词汇，所有 API 共用

1请求 = messages + 角色，而且无状态

一次调用，就是把"角色标注过的整段对话"作为输入，换回模型续写的下一段 assistant 内容。

底层机制（比文档深一层）：角色不是被服务端强制校验的字段，而是模型在训练（RLHF / instruct 微调）时学会服从的特殊 token——比如 ChatML 把消息渲染成 <|im_start|>system … <|im_end|> 这样的定界符。正因为如此，服务器本身是无状态的：每次调用你都要把完整历史重发一遍；所谓"会话"完全是客户端维护的，模型那一端什么都不记得。这一条会一路解释后面的成本、缓存、注入问题。

走查：同一个 system + user，三家怎么表达

// OpenAI（Chat Completions 形态）—— system 作为一条 message
{ "model": "gpt-5.5",
  "messages": [
    {"role": "system",    "content": "你是电商客服，只回答订单相关问题。"},
    {"role": "user",      "content": "我上周买的耳机到哪了？"}
  ] }

// Anthropic —— system 是顶层参数，不是 message；max_tokens 必填
{ "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "system": "你是电商客服，只回答订单相关问题。",
  "messages": [
    {"role": "user", "content": "我上周买的耳机到哪了？"}
  ] }

// Google Gemini —— 无 system 角色，用 systemInstruction；assistant 叫 "model"
{ "systemInstruction": {"parts": [{"text": "你是电商客服，只回答订单相关问题。"}]},
  "contents": [
    {"role": "user", "parts": [{"text": "我上周买的耳机到哪了？"}]}
  ] }

共同点三家都是一个有序的、角色标注的消息列表。 差异 1system 放哪：OpenAI 当 message、Claude 顶层 system、Gemini 顶层 systemInstruction——没有一家用 system 这个"角色"。 差异 2助手那一方：OpenAI / Claude 叫 assistant，Gemini 叫 model。

2token：一切的计量单位

token 是模型眼里的最小文本单位（约 0.75 个英文词 / 1–2 个汉字），上下文长度、输出上限、账单全部以它计。

底层机制（比文档深一层）：tokenizer 用 BPE（byte-pair encoding）把文本切成子词。不同模型用不同 tokenizer——GPT-4o 系用 o200k_base，更早的 GPT 用 cl100k_base，Claude / Gemini 各有自己的。所以"同一段中文有多少 token"在不同模型上答案不同；拿错 tokenizer 去估算就会偏。输入 token（prompt）和输出 token（completion）分开计价，输出通常贵 3–5 倍，因为输出要一个个自回归地算。

// 账单就看这里：输入便宜、输出贵
"usage": {
  "prompt_tokens": 38,        // 你发进去的 system+user，按输入价
  "completion_tokens": 142,   // 模型吐出来的，按输出价（约 3-5x）
  "total_tokens": 180
}
// 经验值：1 个英文词 ≈ 1.3 token；1 个汉字 ≈ 1-2 token；
//        "你好，世界" ≈ 3-5 token（取决于 tokenizer），不是 5

3流式（streaming）

不等整段生成完，模型每产出一块就通过 SSE 推给你，首字几百毫秒即到。

底层机制（比文档深一层）：生成本来就是自回归的——一次前向只产一个 token，所以服务器天然能边生成边发。传输用 Server-Sent Events（Content-Type: text/event-stream）：一行行 data: {…} 推过来，每块带一个增量 delta，最后一个 [DONE] 收尾。代价在第 1.1 节的无状态之外又添了一笔：连接要一直挂着；错误只会在 HTTP 200 之后才暴露（藏在某个 chunk 里）；想原子地拿到整个对象时，流式反而碍事。

chunk 事件名各家不同OpenAI 旧形态是 chat.completion.chunk、Responses 是语义事件 response.output_text.delta；Claude 是 content_block_delta；Gemini 是 content.delta。形态不同，但都是"一块块 delta"。

4工具调用（tool calling）——一个闭环

你把工具的 JSON-Schema 描述递给模型；模型不执行工具，只输出一个"调用请求"；你的代码执行，把结果作为新消息喂回；循环直到模型给出文字答复。

底层机制（比文档深一层，本章最重要的一条）：所谓"调用工具"，本质是模型输出了一段结构化的 token（工具名 + JSON 参数）而不是散文。客户端解析这段 token、执行真正的函数、把结果作为 tool 角色的消息追加回历史，再发一次请求。模型自始至终只输出 token，从不自己执行任何东西。这个设计把副作用、密钥、真正的执行全留在你这边——模型连"函数被执行了"都不知道，它只是看到历史里多了一条工具结果。

走查：客服查订单的完整闭环

// ① 请求：带上工具的 schema
{ "model": "claude-opus-4-8", "max_tokens": 1024,
  "messages": [{"role":"user","content":"我上周买的耳机（订单 123）到哪了？"}],
  "tools": [{
    "name": "get_order_status",
    "description": "查询订单的物流状态",
    "input_schema": {"type":"object",
      "properties":{"order_id":{"type":"string"}},
      "required":["order_id"]}
  }] }

// ② 模型的响应：它没查任何东西，只是 emit 了一个 tool_use 块
{ "stop_reason": "tool_use",
  "content": [{"type":"tool_use","id":"tu_01","name":"get_order_status",
               "input":{"order_id":"123"}}] }

// ③ 你的代码真正执行 get_order_status("123")，得到 {"status":"shipped",...}
//    把结果作为 tool_result 追加，连同全部历史再发一次：
{ "model": "claude-opus-4-8", "max_tokens": 1024,
  "messages": [
    {"role":"user","content":"我上周买的耳机（订单 123）到哪了？"},
    {"role":"assistant","content":[{"type":"tool_use","id":"tu_01",
        "name":"get_order_status","input":{"order_id":"123"}}]},
    {"role":"user","content":[{"type":"tool_result","tool_use_id":"tu_01",
        "content":"{\"status\":\"shipped\",\"eta\":\"2026-06-05\",\"carrier\":\"SF\"}"}]}
  ] }

// ④ 模型这次才给出文字答复："您的耳机已发货，预计 6 月 5 日由顺丰送达。"

5结构化输出（structured output）

让模型的输出严格符合你给的 JSON Schema，而不是自由散文。

底层机制（比文档深一层）：分两个层次，差别很大。JSON mode 只保证输出是语法合法的 JSON（靠偏置 + 后校验），但形状不保证——少字段、字段名拼错、类型不对都在它的能力之外。strict schema 则把你的 schema 编译成一个有限状态机 / 语法，在生成的每一步用一个"logit 处理器"把所有违反当前语法状态的 token 概率压到负无穷再采样——所以它能保证输出形状（下一章拆这个机制）。代价：schema 要编译，递归 / 无界 pattern 等特性未必编得出来。

// OpenAI —— strict json_schema，形状有保证
"text": {"format": {"type":"json_schema","strict":true,
  "schema":{"type":"object",
    "properties":{"status":{"type":"string"},"eta":{"type":"string"},
                  "carrier":{"type":"string"}},
    "required":["status","eta","carrier"],
    "additionalProperties":false}}}

// Anthropic —— 2026-01 起有原生结构化输出（也可用 tool schema 约束）
"output_config": {"format": {"type":"json_schema","schema":{ /* 同上 */ }}}

// Gemini —— responseSchema / responseJsonSchema
"generationConfig": {"responseMimeType":"application/json",
  "responseJsonSchema": { /* 同上 */ }}

6采样参数（sampling）

temperature / top_p 控制模型从"下一个 token 的概率分布"里怎么挑——挑最稳的，还是允许些随机。

底层机制（比文档深一层）：模型每一步输出的是一个 logits 向量，经 softmax 变成"下一个 token 的概率分布"。temperature T 在 softmax 前缩放 logits：T→0 趋近 argmax（永远挑概率最高的那个），T>1 把分布拉平（更随机）。top_p（核采样）只在"累计概率达到 p 的最小 token 集合"里挑；top_k 只看概率前 k 个。这章先记住效果，下一章会讲一个反直觉的事实：temperature=0 也不保证逐字节可复现。

7上下文窗口 + prompt caching

上下文窗口是单次调用能容纳的 token 上限（输入 + 输出共享）；prompt caching 复用重复前缀的计算，省钱又省延迟。

底层机制（比文档深一层）：注意力机制会把每个 token 的 Key/Value 张量缓存下来（KV cache），让第 N 步复用前面算好的 K/V 而不是重算——所以成本和延迟随输入和输出 token 都线性增长，长上下文之所以贵，是因为 KV cache 占满了显存带宽。prompt caching 再进一步：把"前缀的 KV 状态"整段存住，重复请求直接跳过重算——命中时读取价低至 0.1x。但它要求前缀逐字节相同：前面任何一个字符变了（比如 system prompt 顶部塞了个时间戳），后面全部失效。

[system] 你是电商客服…（500 token 的固定规则、话术、FAQ）   ← 适合缓存：逐字节不变
[user]   订单 123 到哪了？                                    ← 每轮变化：放后面
─────────────────────────────────────────────────────────
反例（缓存永不命中）：
[system] 当前时间 2026-06-02 14:03:01。你是电商客服…        ← 顶部塞时间戳
         每秒都变 → 前缀永远不同 → 后面 500 token 每次全价重算

8新成员：reasoning / thinking 模型

新一代模型在给出答复前，先生成一段"思考"token；你用 effort / thinking budget 控制它想多久，思考 token 按输出计费、通常不可见。

底层机制（比文档深一层）：模型先自回归生成一段隐藏的 reasoning token，再生成最终答复。reasoning token 计入输出 token 计费，但通常只返回摘要或完全不返回。控制旋钮各家不同：Anthropic 用 effort（2026-02 起，Opus 4.8 默认 high）+ adaptive thinking（按需才思考）；OpenAI 用 reasoning_effort（minimal/low/medium/high/xhigh）；Gemini 用 thinking levels。代价：更慢更贵（思考也烧 token）；在简单任务上开高 effort 是纯浪费。

这是当前变动最快的一块（见起点的"现状速览"）。把它当成"在前七个原语之上多了一个隐藏的生成阶段"来理解就够了——它没有推翻任何原语，只是在"模型 emit token"这一步前面加了一段你付费但看不见的 token。