# 文本对话

使用 Chat Completions API 向支持文本对话的模型发送消息，并获取完整回复或流式输出。完成本页操作后，你将发送一次文本请求，从响应中读取模型回复，并保存请求 ID 以便排查问题。

## 前提条件

- 已从 [获取可用模型](../../getting-started/available-models.md) 获取一个支持文本对话的模型 ID。
- 已准备当前环境的访问令牌。
- 已按[身份认证](../../getting-started/authentication.md)配置 `Authorization: Bearer <ACCESS_TOKEN>`。

## 请求地址

```text
POST <GENESIS_BASE_URL>/chat/completions
```

## 发送文本请求

下面的请求向指定模型发送一条用户消息。将环境变量和 `<MODEL_ID>` 替换为当前环境的值：

```bash
curl -X POST "$GENESIS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {
        "role": "user",
        "content": "用一句话解释数据血缘。"
      }
    ]
  }'
```

请求会产生模型用量。成功后，从 `choices[0].message.content` 读取回复，并保存响应中的 `id`。

## 请求参数

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 要调用的模型 ID。模型必须支持文本对话；使用 `GET /models` 获取当前凭证可用的 ID。 |
| `messages` | array | 是 | 按对话顺序传入的消息列表。继续对话时，将此前的消息按顺序一并传入。 |
| `messages[].role` | string | 是 | 消息角色。`system` 用于设置模型行为，`user` 表示用户输入，`assistant` 用于传入此前的模型回复。 |
| `messages[].content` | string | 是 | 当前消息的文本内容。文本对话请求使用字符串内容。 |
| `temperature` | number | 否 | 控制输出的随机性。取值范围和模型支持情况以当前接口和模型信息为准。 |
| `top_p` | number | 否 | 使用核采样限制候选 Token。需要调整采样策略时，与 `temperature` 二选一进行小范围验证。 |
| `max_tokens` | integer | 否 | 限制本次响应最多生成的 Token 数。输出因长度限制结束时，可在当前模型和接口允许的范围内调整。 |
| `seed` | integer | 否 | 在接口和模型支持时固定采样随机种子。相同值不保证跨模型、模型版本或服务配置得到完全相同的结果。 |
| `stream` | boolean | 否 | 控制返回完整响应还是增量事件。启用后，客户端需要处理 SSE 事件。 |

不要从示例值推断默认值。模型可能支持其他可选参数；仅发送当前模型和接口明确支持的参数。

## 成功响应

```json
{
  "id": "<request-id>",
  "object": "chat.completion",
  "created": 0,
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "数据血缘描述数据从来源到处理和消费环节的关系。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 非流式成功响应返回 | 本次响应的标识。排查调用问题时提供该值。 |
| `model` | string | 非流式成功响应返回 | 实际处理本次请求的模型 ID。 |
| `choices[].message.content` | string | 模型返回文本时 | 模型生成的回复。 |
| `choices[].finish_reason` | string | 非流式成功响应返回 | 生成结束原因。`length` 表示输出达到当前长度限制，不能视为完整回答。 |
| `usage` | object | 当前响应包含时 | 本次请求的 Token 用量信息。只读取实际返回的字段。 |

## 处理流式响应

将 `stream` 设为 `true` 后，服务以 SSE 增量事件返回内容。流式响应不能按完整 JSON 对象一次读取；请按事件顺序合并文本，并在收到结束事件后关闭读取。具体处理方式见[Chat Completions 流式输出](streaming-chat-completions.md)。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 认证失败 | 请求地址、令牌和 `Authorization` Header | 按[身份认证](../../getting-started/authentication.md)重新配置当前环境的凭据。 |
| 模型不可用 | `model` 值和 `GET /models` 的结果 | 从当前凭证可用列表中选择支持文本对话的模型。 |
| 输出因 `length` 结束 | `choices[].finish_reason` | 缩短输入或在允许范围内调整 `max_tokens` 后重试。 |
| 流式读取不完整 | `stream` 设置和客户端事件解析 | 按[Chat Completions 流式输出](streaming-chat-completions.md)处理增量事件和结束事件。 |

## 下一步

- [将文本对话改为流式输出](streaming-chat-completions.md)
- [选择支持多模态输入的模型](../../getting-started/choose-model-capabilities.md)
- [查看当前凭证可用的模型](../../getting-started/available-models.md)