LLM API 的变迁：OpenAI-compatible 为什么不等于兼容

prompt string  ->  messages  ->  typed items + events + tool loop
一段文本            一段对话       一次持续演化的任务

{
  "model": "gpt-5.6",
  "messages": [
    {"role": "system", "content": "回答要简洁。"},
    {"role": "user", "content": "解释一下幂等。"}
  ]
}

choices[0].message.content

openapi: 3.1.0
info:
  title: 三种 LLM API 的对照 schema
  version: "1.0"
paths:
  /v1/chat/completions:      # OpenAI Chat Completions
    post:
      security: [{ bearerAuth: [] }]     # Authorization: Bearer <OPENAI_API_KEY>
      requestBody:
        content: { application/json: { schema: { $ref: "#/components/schemas/ChatCompletionsRequest" } } }
      responses:
        "200": { content: { application/json: { schema: { $ref: "#/components/schemas/ChatCompletionsResponse" } } } }
  /v1/responses:             # OpenAI Responses
    post:
      security: [{ bearerAuth: [] }]     # Authorization: Bearer <OPENAI_API_KEY>
      requestBody:
        content: { application/json: { schema: { $ref: "#/components/schemas/ResponsesRequest" } } }
      responses:
        "200": { content: { application/json: { schema: { $ref: "#/components/schemas/ResponsesResponse" } } } }
  /v1/messages:              # Anthropic Messages
    post:
      security: [{ apiKeyAuth: [] }]     # x-api-key: <ANTHROPIC_API_KEY> + anthropic-version 头
      requestBody:
        content: { application/json: { schema: { $ref: "#/components/schemas/MessagesRequest" } } }
      responses:
        "200": { content: { application/json: { schema: { $ref: "#/components/schemas/MessagesResponse" } } } }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
    apiKeyAuth: { type: apiKey, in: header, name: x-api-key }

components:
  schemas:

    # ---------- OpenAI Chat Completions ----------
    ChatCompletionsRequest:
      type: object
      required: [model, messages]
      properties:
        model: { type: string, example: "gpt-5.6" }
        messages:                          # system 是 messages 里的一条
          type: array
          items: { $ref: "#/components/schemas/ChatMessage" }
        tools:
          type: array
          items: { $ref: "#/components/schemas/ChatTool" }
        response_format: { type: object }  # 结构化输出入口
        stream: { type: boolean, default: false }
    ChatMessage:
      type: object
      required: [role]
      properties:
        role: { type: string, enum: [system, user, assistant, tool] }
        content: { type: string }          # 经典写法：content 是字符串
        tool_calls:                         # assistant 发起的工具调用挂在这里
          type: array
          items: { $ref: "#/components/schemas/ChatToolCall" }
        tool_call_id: { type: string }      # role=tool 时用来配对
    ChatTool:
      type: object
      properties:
        type: { const: function }
        function:
          type: object
          required: [name, parameters]
          properties:
            name: { type: string }
            description: { type: string }
            parameters: { type: object }    # JSON Schema，工具描述再包一层 function

    # ---------- OpenAI Responses ----------
    ResponsesRequest:
      type: object
      required: [model, input]
      properties:
        model: { type: string, example: "gpt-5.6" }
        input:                              # 可以是字符串，也可以是 Item 列表
          oneOf:
            - type: string
            - type: array
              items: { $ref: "#/components/schemas/InputItem" }
        instructions: { type: string }      # system 语义单独出来，不进 input
        tools:
          type: array
          items: { $ref: "#/components/schemas/ResponsesTool" }
        text: { type: object }              # text.format 是结构化输出入口
        previous_response_id: { type: string }   # 服务端串上下文
        store: { type: boolean }            # 是否让服务端保存这次 response
        stream: { type: boolean, default: false }
    InputItem:                              # 输入也是 typed Item
      oneOf:
        - $ref: "#/components/schemas/EasyMessage"
        - $ref: "#/components/schemas/FunctionCallOutput"
    EasyMessage:
      type: object
      properties:
        role: { type: string, enum: [user, assistant, system, developer] }
        content: { type: string }
    ResponsesTool:                          # 工具描述是平的，没有 function 包装
      type: object
      properties:
        type: { const: function }
        name: { type: string }
        description: { type: string }
        parameters: { type: object }
        strict: { type: boolean }

    # ---------- Anthropic Messages ----------
    MessagesRequest:
      type: object
      required: [model, max_tokens, messages]
      properties:
        model: { type: string, example: "claude-sonnet-4-6" }
        max_tokens: { type: integer, example: 1024 }   # 必填，OpenAI 里是可选
        system: { type: string }            # system 是顶层参数，不进 messages
        messages:
          type: array
          items: { $ref: "#/components/schemas/AnthropicMessage" }
        tools:
          type: array
          items: { $ref: "#/components/schemas/AnthropicTool" }
        stream: { type: boolean, default: false }
    AnthropicMessage:
      type: object
      required: [role, content]
      properties:
        role: { type: string, enum: [user, assistant] }   # 没有 system/tool 角色
        content:                            # content 可以是字符串，也可以是 block 数组
          oneOf:
            - type: string
            - type: array
              items: { $ref: "#/components/schemas/ContentBlock" }
    AnthropicTool:                          # 工具描述又是另一种形状
      type: object
      required: [name, input_schema]
      properties:
        name: { type: string }
        description: { type: string }
        input_schema: { type: object }      # 注意字段名叫 input_schema

components:
  schemas:

    # ---------- Chat Completions 响应 ----------
    ChatCompletionsResponse:
      type: object
      properties:
        choices:                            # 经典读取路径 choices[0].message.content
          type: array
          items:
            type: object
            properties:
              message:
                type: object
                properties:
                  role: { const: assistant }
                  content: { type: [string, "null"] }
                  tool_calls:
                    type: array
                    items: { $ref: "#/components/schemas/ChatToolCall" }
              finish_reason:                # stop / length / tool_calls / content_filter
                type: string
        usage: { $ref: "#/components/schemas/Usage" }
    ChatToolCall:
      type: object
      properties:
        id: { type: string }                # 用来和后续 role=tool 消息配对
        type: { const: function }
        function:
          type: object
          properties:
            name: { type: string }
            arguments: { type: string }     # 注意是 JSON 字符串，不是对象

    # ---------- Responses 响应 ----------
    ResponsesResponse:
      type: object
      properties:
        id: { type: string }                # 这就是可用于 previous_response_id 的值
        output:                             # 一组 typed Item，不是单个 message
          type: array
          items: { $ref: "#/components/schemas/OutputItem" }
        output_text: { type: string }       # SDK 便利视图，生产代码别硬依赖
        usage: { $ref: "#/components/schemas/Usage" }
    OutputItem:                             # 可能是 reasoning / function_call / message
      oneOf:
        - $ref: "#/components/schemas/ReasoningItem"
        - $ref: "#/components/schemas/FunctionCallItem"
        - $ref: "#/components/schemas/OutputMessageItem"
    FunctionCallItem:
      type: object
      properties:
        type: { const: function_call }
        call_id: { type: string }           # 用 call_id 配对（不是 id/tool_use_id）
        name: { type: string }
        arguments: { type: string }
    FunctionCallOutput:                     # 回传工具结果：独立 Item
      type: object
      properties:
        type: { const: function_call_output }
        call_id: { type: string }
        output: { type: string }

    # ---------- Anthropic Messages 响应 ----------
    MessagesResponse:
      type: object
      properties:
        role: { const: assistant }
        content:                            # content 永远是 block 数组
          type: array
          items: { $ref: "#/components/schemas/ContentBlock" }
        stop_reason:                        # end_turn / max_tokens / tool_use / stop_sequence
          type: string
        usage: { $ref: "#/components/schemas/Usage" }
    ContentBlock:
      oneOf:
        - type: object                      # 文本块
          properties: { type: { const: text }, text: { type: string } }
        - type: object                      # 模型发起的工具调用
          properties:
            type: { const: tool_use }
            id: { type: string }            # 用 id
            name: { type: string }
            input: { type: object }         # 注意是对象，不是 JSON 字符串
        - type: object                      # 回传工具结果：塞进 user 的 content block
          properties:
            type: { const: tool_result }
            tool_use_id: { type: string }   # 用 tool_use_id 配对
            content: { type: string }

    Usage:                                  # 三家字段名各不相同，这里只给形状
      type: object
      description: >
        Chat/Responses 用 prompt_tokens/completion_tokens（Responses 叫 input/output_tokens），
        Anthropic 用 input_tokens/output_tokens，还有 cache_creation/cache_read 相关字段。

{
  "model": "gpt-5.6",
  "input": "查一下明天上海的天气，再给出骑行建议。",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "查询指定城市和日期的天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "date": {"type": "string"}
        },
        "required": ["city", "date"],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

{
  "type": "function_call_output",
  "call_id": "call_abc123",
  "output": "小雨，12-17°C，东北风4级"
}

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "回答要简洁。",
  "messages": [
    {"role": "user", "content": "解释一下幂等。"}
  ]
}

{
  "role": "assistant",
  "content": [
    {"type": "text", "text": "我需要先查询订单状态。"},
    {
      "type": "tool_use",
      "id": "toolu_01A",
      "name": "get_order",
      "input": {"order_id": "A-1024"}
    }
  ],
  "stop_reason": "tool_use"
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A",
      "content": "订单已发货"
    }
  ]
}

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "reply OK"}],
)
assert response.choices[0].message.content

flowchart LR
    B[业务用例] --> C[内部窄协议]
    C --> R[能力注册表]
    C --> OA[OpenAI Responses Adapter]
    C --> OC[OpenAI Chat Adapter]
    C --> AN[Anthropic Adapter]
    C --> GE[Gemini Adapter]
    OA --> P1[Provider API]
    OC --> P2[Provider API]
    AN --> P3[Provider API]
    GE --> P4[Provider API]
    C -.显式逃生口.-> X[provider_options]
    R -.启动时校验.-> OA
    R -.启动时校验.-> OC
    R -.启动时校验.-> AN
    R -.启动时校验.-> GE

InputPart      = Text | Image | File | ToolResult
OutputEvent    = TextDelta | ToolCallDelta | ToolCallDone | Citation | Usage | Done | Error
FinishReason   = Stop | Length | ToolUse | Refusal | ContentFilter | Error | Unknown(raw)
Capability     = Streaming | Tools | ParallelTools | StrictSchema | Vision | HostedSearch | State

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor #F8F9FA
    RoundCorner 10
    Padding 10
    FontSize 13
  }
  :depth(0) {
    BackgroundColor #1E3A5F
    FontColor white
    FontSize 18
    FontStyle bold
  }
  :depth(1) {
    FontSize 15
    FontStyle bold
  }
  :depth(2) {
    FontSize 13
  }
}
</style>

* LLM API 的变迁\n兼容不是布尔值
** 三代数据模型
*** prompt string\n文本续写
*** messages\n角色化对话
*** typed items/events\nAgent 任务循环
** 四种主要接口
*** Chat Completions\n生态广、最小公分母
*** Responses API\nItems、状态、托管工具
*** Anthropic Messages\ncontent blocks
*** Gemini Native\ncontents / parts
** OpenAPI 对照
*** system 放哪不同
*** 工具参数\n字符串 vs 对象
*** 配对键\ncall_id/tool_use_id
*** 结果回传\n独立消息 vs block
** OpenAI-compatible 四层
*** 传输兼容
*** 结构兼容
*** 行为兼容
*** 能力兼容
** 七种常见误用
*** 只换 base_url
*** 输出压成 text
*** 忽略未知字段
*** 共用 stream parser
*** 盲目重试工具
*** 把供应商状态当数据库
*** 追求完美统一接口
** 正确的适配层
*** 内部窄协议
*** provider adapters
*** capability registry
*** provider escape hatch
** 选型与验证
*** 边缘能力可兼容
*** 核心能力用原生
*** 契约测试证明兼容
*** shadow test 渐进迁移
@endmindmap