# 读取 Chat Completions 流式响应

向 Chat Completions 请求添加 `stream: true`，以服务器发送事件（SSE）持续读取生成增量。此页只说明 Chat Completions 的流式事件；Responses 和 Anthropic Messages 使用各自的事件结构。

```text
POST https://token.moi.matrixorigin.cn/v1/chat/completions
```

## 调用前准备

请求地址为 `https://token.moi.matrixorigin.cn/v1/chat/completions`。准备具有 Genesis 权限的访问凭据，以及支持 Chat Completions 流式输出的模型 ID。

下方示例使用：

- `$GENESIS_ACCESS_TOKEN`：实际访问令牌或服务账号 API Key，通过 `Authorization` Header 传递。
- `$MODEL_ID`：要调用的模型 ID，填入请求体的 `model` 字段。

## 请求头

| 请求头 | 是否必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | 使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。 |
| `Content-Type` | 是 | 设置为 `application/json`。 |
| `Accept` | 否 | 可设置为 `text/event-stream`。 |

## 请求体

请求体包含以下字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Chat Completions 流式输出的模型 ID。 |
| `messages` | array | 是 | 按顺序提交的消息列表。 |
| `stream` | boolean | 是 | 必须设为 `true`。 |

## 请求示例

```bash
curl -N -X POST "https://token.moi.matrixorigin.cn/v1/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [
      {
        "role": "user",
        "content": "用一句话说明主键的作用。"
      }
    ],
    "stream": true
  }'
```

`-N` 使 curl 不缓冲输出，便于逐行读取 SSE 事件。

## 成功响应

成功时响应媒体类型为 `text/event-stream`。每个 `data:` 行包含一个 `chat.completion.chunk`，末尾事件为 `data: [DONE]`：

```text
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"主键"}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"用于唯一标识表中的每一行。"}}]}

data: [DONE]
```

单个 `data:` 行中的 JSON 负载具有以下结构；`delta.content` 缺失时不应追加文本：

```json
{
  "object": "chat.completion.chunk",
  "choices": [
    {
      "delta": {
        "content": "主键"
      }
    }
  ]
}
```

单个 `data:` 行中用于读取增量内容的字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`choices[].delta.content` 表示 `choices` 数组中每一项的 `delta.content` 字段。

| 字段或事件 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 事件对象类型，示例为 `chat.completion.chunk`。 |
| `choices` | array | 当前事件的增量列表。 |
| `choices[].delta` | object | 增量对象。 |
| `choices[].delta.content` | string，可选 | 存在时追加到当前文本。 |
| `[DONE]` | 事件标记 | 正常结束标记。收到该标记后再将结果标记为完成。 |

网络分片可能将一条 SSE 事件拆开。客户端应按事件边界解析，并在收到 `[DONE]` 前保留未完成状态。

## 错误响应

流开始前的错误使用普通 HTTP 状态和 JSON 错误正文处理；流开始后的错误可能表现为事件异常或连接中断。错误对象由兼容的模型服务返回；除 `error.message` 外的字段可能省略。

### 错误对象字段

```json
{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}
```

建立流前的错误正文中可能出现以下字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error.message` | string | 建立流前返回的可读错误信息。 |
| `error.type` | string，可选 | 上游错误类别。 |
| `error.code` | string 或 null，可选 | 上游错误代码。 |

### 常见错误

下表说明建立流前或读取事件时应执行的操作。

```{list-table}
:header-rows: 1
:widths: 20 22 28 30

* - 阶段或 HTTP 状态码
  - 错误代码或现象
  - 常见原因
  - 建议操作
* - 建立流前：`400`
  - —
  - 请求体或 `stream` 参数无效。
  - 修正请求后重新建立连接；不要开始解析 SSE。
* - 建立流前：`401`
  - —
  - 凭据无效或没有模型权限。
  - 修正认证信息和模型访问范围。
* - 建立流前：`403`
  - —
  - 凭据无效或没有模型权限。
  - 修正认证信息和模型访问范围。
* - 建立流前：`429`
  - —
  - 请求受限或服务暂时不可用。
  - 降低请求频率，或稍后建立新连接。
* - 建立流前：`5xx`
  - —
  - 请求受限或服务暂时不可用。
  - 降低请求频率，或稍后建立新连接。
* - 已收到部分事件
  - 连接在 `[DONE]` 前中断。
  - 流未正常结束。
  - 将结果标记为中断，不标记为完成。只有应用可以识别重复内容时才重新请求。
```

## 后续操作

- [Chat Completions](chat-completions.md)