对话接口完整教程

Scope & Evidence

仅用于 OpenAI 兼容 Chat 端点

模型必须在实时模型广场显示 openai。若模型只显示 openai-response、anthropic 或 gemini，应改用对应协议。

Authentication

请求头与地址必须同时正确

First Request

先发送没有可选参数的最小请求

从模型广场复制精确模型 ID 替换 MODEL_NAME。首次验证不要同时添加工具、媒体、结构化输出或采样参数，这样更容易定位协议问题。

curl https://api.muxllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [
      {
        "role": "user",
        "content": "只回复：连接成功"
      }
    ]
  }'

验收时应同时检查 HTTP 状态码、响应的 Content-Type、是否存在 choices，以及首个消息文本是否非空。

Request Fields

核心字段与可选字段

Messages

按时间顺序构造消息数组

[
  {
    "role": "system",
    "content": "回答时先给结论，再列出依据。"
  },
  {
    "role": "user",
    "content": "什么是指数退避？"
  },
  {
    "role": "assistant",
    "content": "指数退避是逐步延长重试间隔的策略。"
  },
  {
    "role": "user",
    "content": "给出一个适用于 429 的例子。"
  }
]

文本消息的 content 可以是字符串。视觉等多模态输入通常使用内容块数组，不能假设所有带 openai 标签的模型都支持图片。

Response

读取 choices、停止原因和用量

普通请求通常返回一个 JSON 对象。下面只展示常用结构；具体字段、空值和用量明细可能因模型或上游实现而变化。

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "MODEL_NAME",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "连接成功"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 2,
    "total_tokens": 14
  }
}

Server-Sent Events

逐行解析 SSE，而不是按网络块解析 JSON

加入 "stream": true 后，服务端通常以 text/event-stream 返回多个 data: 事件。一次 TCP 读取可能包含半行或多行，客户端应使用成熟的 SSE/SDK 解析能力。

curl -N https://api.muxllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [
      { "role": "user", "content": "逐步解释缓存击穿。" }
    ],
    "stream": true
  }'

data: {"choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"缓存"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"击穿"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

1. 01检查响应类型

   确认成功响应是事件流；错误响应可能仍然是普通 JSON。

2. 02按事件解析

   去除 data: 前缀后解析 JSON，跳过空行和注释事件。

3. 03拼接增量

   按 index 累积 delta.content，空增量不应渲染为文本。

4. 04识别结束

   处理停止原因与结束标记；网络中断时将结果明确标记为不完整。

Conversation State

Chat 接口不会替你保存全部会话

典型 Chat Completions 请求是无状态的。每次追问时，应用需要按顺序重新提交仍然必要的系统消息、用户消息和助手回复。

Compatibility

逐模型确认可选参数

OpenAI 兼容描述的是请求外形，不表示上游完整实现所有 OpenAI 参数。推理模型、传统聊天模型和不同供应渠道可能接受不同的输出限制、采样或结构化输出字段。

1. 01建立最小基线

   只发送 model 与 messages。

2. 02一次增加一项

   分别验证流式、采样、输出上限、工具或响应格式。

3. 03记录模型与日期

   把验证结果与精确模型 ID、渠道和日期绑定，不泛化到全部模型。

4. 04保留降级路径

   可选参数被拒绝时，应用应能回退到最小请求或切换已验证模型。

Errors & Retry

先修正确定性错误，再处理短暂故障

日志可以记录模型名、端点、状态码、耗时、重试次数和脱敏请求 ID，但不得记录 Authorization 头、完整用户隐私内容或第三方签名 URL。

Official Sources

对照官方字段、流式与错误规则

Acceptance

从最小请求到生产接入

1. 01确认模型与标签

   复制 MODEL_NAME，确认端点标签为 openai。

2. 02执行受控最小请求

   使用专用低额度 Key，验证状态码、JSON 类型和非空文本。

3. 03验证 SSE

   确认增量顺序、结束标记、取消和中断状态都被正确处理。

4. 04验证上下文

   连续追问时保留角色顺序，并在接近上限前裁剪或摘要。

5. 05上线保护

   增加超时、有限重试、并发控制、日志脱敏和成本监控。