OpenAI Chat Completions

# OpenAI Chat Completions 调用文档

Chat Completions 接口采用 OpenAI 兼容协议，根据消息列表生成模型回复，支持非流式响应和 SSE 流式响应。

本文示例模型为 `qwen3.7-plus`。

## 接口信息

| 项目 | 内容 |
| --- | --- |
| 基础地址 | `https://aiproxy-api.cloudcare.cn` |
| 请求方法 | `POST` |
| 接口路径 | `/v1/chat/completions` |
| 鉴权 | `Authorization: Bearer <平台 API Key>` |
| 请求类型 | `Content-Type: application/json` |
| 示例模型 | `qwen3.7-plus` |

调用示例使用环境变量 `AIPROXY_API_KEY` 传递平台 API Key。请将 `YOUR_API_KEY` 替换为实际密钥。

```bash
export AIPROXY_API_KEY='YOUR_API_KEY'
```

## 非流式调用

### 请求示例

```bash
curl 'https://aiproxy-api.cloudcare.cn/v1/chat/completions' \
  -H "Authorization: Bearer ${AIPROXY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [
      {"role": "system", "content": "你是一个专业的技术助手，请使用中文回答。"},
      {"role": "user", "content": "简要解释什么是可观测性。"}
    ],
    "stream": false
  }'
```

### 响应示例

以下为响应结构示例，内容及用量数值仅供参考。

```json
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "qwen3.7-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "可观测性是通过日志、指标和链路追踪等信息理解系统内部状态的能力。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 30, "completion_tokens": 40, "total_tokens": 70}
}
```

回复文本位于 `choices[0].message.content`。`finish_reason` 表示本轮生成的结束原因。`stop` 通常表示正常结束，`length` 表示达到长度限制。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 平台模型名称，示例为 `qwen3.7-plus` |
| `messages` | array | 是 | 按时间顺序排列的消息列表 |
| `messages[].role` | string | 是 | 基础对话使用 `system`、`user`、`assistant` |
| `messages[].content` | string / array / null | 视消息类型 | 普通文本使用字符串，多模态使用内容数组；工具调用消息可以为 null |
| `stream` | boolean | 否 | `true` 开启 SSE 流式输出 |
| `stream_options.include_usage` | boolean | 否 | 是否在流式响应中返回用量统计 |
| `temperature` | number | 否 | 采样随机性，支持范围由模型决定 |
| `max_tokens` | integer | 否 | 输出 Token 上限，适用范围由模型决定 |
| `response_format` | object | 否 | 结构化输出设置，需要模型支持 |
| `max_completion_tokens` | integer | 否 | 输出 Token 预算，包含推理 Token；适用范围由模型决定，与 `max_tokens` 二选一 |
| `top_p` | number | 否 | 核采样参数，通常与 `temperature` 二选一调整 |
| `stop` | string / array | 否 | 停止序列，需要模型支持 |
| `tools` | array | 否 | 可调用的工具定义 |
| `tool_choice` | string / object | 否 | 工具选择策略 |
| `parallel_tool_calls` | boolean | 否 | 是否允许一次返回多个工具调用，需要模型支持 |

请求结构遵循 [Chat Completions 协议](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)。

## 流式调用

### 请求示例

```bash
curl -N 'https://aiproxy-api.cloudcare.cn/v1/chat/completions' \
  -H "Authorization: Bearer ${AIPROXY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [{"role": "user", "content": "介绍日志、指标和链路追踪的区别。"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'
```

### 响应示例

以下为 SSE 数据片段，省略部分元数据。

```text
data: {"choices":[{"index":0,"delta":{"role":"assistant","content":"日志"}}]}

data: {"choices":[{"index":0,"delta":{"content":"记录离散事件。"}}]}

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

data: {"choices":[],"usage":{"prompt_tokens":20,"completion_tokens":30,"total_tokens":50}}

data: [DONE]
```

按顺序拼接 `choices[].delta.content`。部分事件只有角色、结束原因或用量，`choices` 可能为空；收到 `[DONE]` 表示流结束。用量是否返回以实际上游响应为准。

## 多轮对话

通过 `messages` 按时间顺序传入历史消息和当前问题。请求体示例：

```json
{
  "model": "qwen3.7-plus",
  "messages": [
    {"role": "system", "content": "请用简洁的中文回答。"},
    {"role": "user", "content": "什么是可观测性？"},
    {"role": "assistant", "content": "可观测性是通过系统输出理解其内部状态的能力。"},
    {"role": "user", "content": "给出一个订单服务的应用例子。"}
  ],
  "stream": false
}
```

`session-id` 为可选请求头，用于会话亲和路由。同一会话应保持该值一致，例如 `conversation-001`。历史消息仍通过 `messages` 传入，缓存命中情况以实际用量明细为准。

## 结构化输出

通过 `response_format` 指定输出格式。以下示例使用 JSON Schema 提取告警信息，适用于支持结构化输出的模型。

```json
{
  "model": "qwen3.7-plus",
  "messages": [{"role": "user", "content": "订单服务发生超时，请提取服务名和问题摘要。"}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "alert_summary",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "service": {"type": "string"},
          "summary": {"type": "string"}
        },
        "required": ["service", "summary"],
        "additionalProperties": false
      }
    }
  }
}
```

结构化结果以 JSON 字符串形式返回于 `choices[0].message.content`，由客户端解析。`json_object` 模式只约束 JSON 格式，不等同于 Schema 校验；严格模式需要受支持的 Schema 子集。解析前应检查拒绝信息及输出是否完整。参见 [OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)。

## 工具调用

工具调用通过 Function Calling 完成：模型生成函数名和参数，客户端执行函数后回传结果。以下示例适用于支持工具调用的模型。

### 声明工具

请求体示例：

```json
{
  "model": "qwen3.7-plus",
  "messages": [{"role": "user", "content": "查询订单 A1001 的状态。"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "lookup_order",
      "description": "根据订单编号查询订单状态",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  }],
  "tool_choice": "auto"
}
```

### 返回工具执行结果

收到 `message.tool_calls` 后，解析 `function.arguments` 并执行函数。后续请求保留原始用户消息及完整 `assistant` 工具调用消息，通过 `tool` 消息返回执行结果。调用 ID 应使用实际响应值。

```json
{
  "model": "qwen3.7-plus",
  "messages": [
    {"role": "user", "content": "查询订单 A1001 的状态。"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_order_001",
        "type": "function",
        "function": {"name": "lookup_order", "arguments": "{\"order_id\":\"A1001\"}"}
      }]
    },
    {"role": "tool", "tool_call_id": "call_order_001", "content": "{\"status\":\"shipped\"}"}
  ]
}
```

`tool_call_id` 必须对应原调用。多个工具调用分别回传结果；继续允许模型调用工具时，后续请求也携带工具定义。工具参数是模型生成的输入，执行前需校验参数及业务权限。协议流程参见 [OpenAI Function Calling](https://developers.openai.com/api/docs/guides/function-calling)。

## 图片输入

图片输入使用多模态内容数组，适用于支持图片理解的模型。请求体示例：

```json
{
  "model": "qwen3.7-plus",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "描述这张图片。"},
      {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
    ]
  }]
}
```

将示例地址替换为可访问的真实图片。也可使用 `data:image/jpeg;base64,<图片数据>`；大小、格式和分辨率限制以模型为准。格式参见 [OpenAI Images and Vision](https://developers.openai.com/api/docs/guides/images-vision)。

## 流式解析与结束原因

SSE 事件以空行分隔。客户端应缓存跨网络数据块的内容，组装完整事件后解析 `data:` 字段。

| `finish_reason` | 客户端处理 |
| --- | --- |
| `stop` | 本轮正常结束 |
| `length` | 内容可能截断，检查输出预算和上下文长度 |
| `tool_calls` | 执行工具调用流程 |
| `content_filter` | 内容受到过滤，应检查实际返回结果 |

工具参数流式输出位于 `delta.tool_calls`，应按工具索引累积参数片段，完成后再解析 JSON。开启用量输出时，最后的统计事件可能没有候选文本；连接提前中断也可能收不到该事件。

## 用量统计

`usage.prompt_tokens`、`completion_tokens`、`total_tokens` 分别表示输入、输出和总 Token 用量。缓存明细如有返回，可读取 `usage.prompt_tokens_details.cached_tokens`；Token 数不等于字符数。

## 错误处理

错误码及处理方式请参阅 [错误响应汇总](https://mrdoc.cloudcare.cn/doc/1042/)。