> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hhapi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# HHAPI 流式响应（SSE）完整说明：启用 stream 参数与解析 delta.content 增量内容

> 在 POST /v1/chat/completions 请求体中设置 stream: true 启用 SSE 流式输出。服务端逐块推送 data: 前缀的 JSON chunk，通过 delta.content 传递增量文本，以 data: [DONE] 标志流结束。流式调用同样按 Token 消耗账户余额。

HHAPI 支持两种响应模式：**标准模式**（默认）会等待模型生成完整回复后一次性返回；**流式模式**则通过 Server-Sent Events（SSE）协议，在模型生成过程中逐块（chunk）推送增量内容，让用户可以实时看到文字逐步出现，显著降低首字节延迟，适合对话类、文字生成类等交互场景。

## 启用流式响应

在 `POST /v1/chat/completions` 请求体中设置 `"stream": true` 即可启用流式模式：

```json theme={null}
{
  "model": "<MODEL_ID>",
  "messages": ["..."],
  "stream": true
}
```

<Warning>
  流式模式同样会**消耗账户余额**，计费规则与标准模式一致，按实际生成的 Token 数量计算。
</Warning>

## 请求示例

使用 `curl` 调用流式接口时，建议加上 `--no-buffer` 参数以禁用本地缓冲，确保数据块实时输出。以下示例从环境变量读取 API Key 和 Base URL：

```bash theme={null}
curl "$API_BASE_URL/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HHAPI_API_KEY" \
  --no-buffer \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

## SSE 数据块格式

服务端返回的每一行数据均以 `data: ` 为前缀，后接一个 JSON 对象（chunk），每个 chunk 之间以空行分隔。流结束时发送固定终止标志 `data: [DONE]`。

```text theme={null}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1720000000,"model":"<MODEL_ID>","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1720000000,"model":"<MODEL_ID>","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1720000000,"model":"<MODEL_ID>","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1720000000,"model":"<MODEL_ID>","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

## delta 字段说明

流式响应中，每个 chunk 的内容通过 `choices[].delta` 字段传递，而非完整的 `message` 对象：

| chunk 位置 | delta 内容 | 说明 |
| - | - | - |
| 第一个 chunk | `{"role": "assistant", "content": ""}` | 标识回复角色，`content` 通常为空字符串 |
| 中间 chunks | `{"content": "增量文本"}` | 每次推送新生成的文本片段 |
| 最后一个 chunk | `{}` + `finish_reason: "stop"` 或 `"length"` | `delta` 为空对象，`finish_reason` 非 `null` |
| 结束标志 | `[DONE]`（非 JSON） | 表示流已完整结束，客户端应停止读取 |

## 代码示例

以下示例均从环境变量读取 API Key 和 Base URL，避免硬编码敏感信息。

<CodeGroup>
  ```python Python theme={null}
  import os
  import openai

  client = openai.OpenAI(
      api_key=os.environ["HHAPI_API_KEY"],
      base_url=os.environ["API_BASE_URL"] + "/v1",
  )

  stream = client.chat.completions.create(
      model="<MODEL_ID>",
      messages=[{"role": "user", "content": "你好"}],
      stream=True,
  )

  for chunk in stream:
      delta = chunk.choices[0].delta
      if delta.content:
          print(delta.content, end="", flush=True)

  print()  # 换行
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.HHAPI_API_KEY,
    baseURL: process.env.API_BASE_URL + "/v1",
  });

  async function main() {
    const stream = await client.chat.completions.create({
      model: "<MODEL_ID>",
      messages: [{ role: "user", content: "你好" }],
      stream: true,
    });

    for await (const chunk of stream) {
      const content = chunk.choices[0]?.delta?.content ?? "";
      process.stdout.write(content);
    }

    console.log(); // 换行
  }

  main();
  ```
</CodeGroup>

<Note>
  上方代码示例使用 OpenAI 官方 SDK，通过自定义 `base_url` / `baseURL` 指向 HHAPI 端点。**SDK 与 HHAPI 的完整兼容性待确认**，如遇到 SDK 特定行为异常，建议改用原生 HTTP 请求调用。
</Note>

<Note>
  **关于流式模式下的 `usage` 字段**：标准模式响应中包含 `usage`（Token 用量统计）字段，但流式模式下各 chunk 是否返回 `usage` 信息**待确认**。如需统计用量，建议在客户端自行累计 `delta.content` 长度或通过日志系统记录。
</Note>