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

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

启用流式响应

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

{
  "model": "<MODEL_ID>",
  "messages": ["..."],
  "stream": true
}

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

请求示例

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

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]。

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，避免硬编码敏感信息。

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()  # 换行

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();

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

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

​启用流式响应

​请求示例

​SSE 数据块格式

​delta 字段说明

​代码示例

启用流式响应

请求示例

SSE 数据块格式

delta 字段说明

代码示例