> ## 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 解析异常排查指南

> 排查 HHAPI 流式响应被截断、数据格式错误或输出不完整等问题，包含 curl --no-buffer 使用提示、SSE 逐行解析完整代码示例及代理缓冲常见陷阱说明。

流式响应依赖持久的 HTTP 长连接来持续传输数据，比普通的一次性请求更容易受到代理、防火墙、超时配置和客户端解析逻辑等因素的影响。本文整理了常见的流式异常场景及对应的排查与修复方法。

## 常见问题

<AccordionGroup>
  <Accordion title="流式响应被截断或提前中断">
    ### 可能原因

    * **代理或防火墙缓冲了响应**：中间节点等待响应完成后再转发，破坏了流式推送
    * **客户端超时设置过短**：连接在生成完成前被客户端主动断开
    * **网络不稳定**：长连接在传输过程中意外断开

    ### 处理建议

    * 检查请求链路上是否存在反向代理（Nginx、CDN 等）或企业网络的正向代理，确认其是否支持流式（chunked transfer encoding）
    * 增大客户端超时设置，参考 [请求超时处理建议](/faq/timeout)
    * 在流式读取中实现重连机制，记录已接收内容，断连后从断点续传（若业务允许）
  </Accordion>

  <Accordion title="收到 data: [DONE] 前未接收到完整内容">
    ### 可能原因

    * **`max_tokens` 设置过小**：模型在生成完整回答前达到了 Token 上限，提前停止输出
    * **`finish_reason` 为 `length`**：表示因达到长度限制而截断，而非正常完成

    ### 处理建议

    检查每个数据块中的 `finish_reason` 字段：

    ```json theme={null}
    {
      "choices": [{
        "delta": { "content": "..." },
        "finish_reason": "length"
      }]
    }
    ```

    * `finish_reason: "stop"` — 正常完成
    * `finish_reason: "length"` — 因达到 `max_tokens` 限制而截断，需增大该参数值
    * `finish_reason: null` — 数据块尚未结束，继续读取
  </Accordion>

  <Accordion title="数据格式解析错误">
    ### 可能原因

    * 未按 SSE 规范逐行解析数据，将多行合并处理
    * 未过滤空行（SSE 以空行作为事件分隔符）
    * 未处理注释行（以 `:` 开头的行）
    * 直接对整个响应体执行 `JSON.parse`，而非逐行解析

    ### 处理建议

    参考下方「SSE 正确解析逻辑」章节。
  </Accordion>

  <Accordion title="使用 curl 测试时不实时输出内容">
    ### 原因

    curl 默认会缓冲输出，导致流式数据无法实时显示。

    ### 解决方法

    添加 `--no-buffer` 参数禁用输出缓冲：

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

## SSE 正确解析逻辑

HHAPI 的流式响应遵循 [Server-Sent Events（SSE）](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 格式。每个数据块的格式如下：

```text theme={null}
data: {"id":"...","choices":[{"delta":{"content":"你好"},"finish_reason":null}]}

data: {"id":"...","choices":[{"delta":{"content":"！"},"finish_reason":"stop"}]}

data: [DONE]

```

**解析规则：**

1. 按换行符 `\n` 逐行读取响应体
2. 跳过空行（SSE 事件分隔符）
3. 跳过以 `:` 开头的注释行
4. 对以 `data: ` 开头的行，提取 `data: ` 之后的内容
5. 若提取内容为 `[DONE]`，停止读取
6. 否则将其作为 JSON 字符串解析，提取 `choices[0].delta.content`

**Python 完整示例（使用 openai SDK）：**

```python theme={null}
import os
import openai

client = openai.OpenAI(
    api_key=os.environ.get("HHAPI_API_KEY"),
    base_url="<API_BASE_URL>/v1"
)

# 使用 openai SDK 时，SDK 已处理 SSE 解析，直接迭代即可
with client.chat.completions.stream(
    model="<MODEL_ID>",
    messages=[{"role": "user", "content": "请写一首短诗"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()  # 换行
```

若需手动解析 SSE（不使用 SDK）：

```python theme={null}
import os
import json
import requests

response = requests.post(
    "<API_BASE_URL>/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ.get('HHAPI_API_KEY')}",
        "Content-Type": "application/json",
    },
    json={
        "model": "<MODEL_ID>",
        "messages": [{"role": "user", "content": "你好"}],
        "stream": True,
    },
    stream=True,
)

for raw_line in response.iter_lines():
    if not raw_line:
        continue  # 跳过空行

    line = raw_line.decode("utf-8")

    if line.startswith(":"):
        continue  # 跳过注释行

    if line.startswith("data: "):
        data = line[len("data: "):]

        if data == "[DONE]":
            break  # 流结束

        try:
            chunk = json.loads(data)
            content = chunk["choices"][0]["delta"].get("content", "")
            if content:
                print(content, end="", flush=True)
        except json.JSONDecodeError:
            pass  # 忽略无法解析的行

print()
```

## 代理环境注意事项

<Warning>
  某些**正向代理**（如企业网络中的 HTTP 代理）会将响应完整缓冲后再转发给客户端，导致流式效果完全失效——表现为长时间没有输出，最后一次性接收全部内容。

  如果你处于代理网络环境中，请联系网络管理员确认代理是否支持 chunked transfer encoding 或 SSE 透传，或考虑绕过代理直接访问 HHAPI。
</Warning>

***

**相关资源**

* [流式输出使用指南](/guides/streaming)
* [请求超时处理建议](/faq/timeout)
* [获取技术支持](/support)