LLM 流式接口在返回 HTTP 200 后中途报错或断流

流式接口一旦发送了 HTTP 200 响应头，后续生成过程中若发生后端过载、显存不足或上下文超限，服务端已无法修改 HTTP 状态码，只能往 SSE 流内写入 error 事件。

1. 在消费每个 `data:` JSON 帧时，先判断是否存在 `event.error` 或 `event.type === "error"`。
2. 捕获到流内错误后立即中止拼接，丢弃半截残缺文本并执行带退避策略的重试。

const payload = JSON.parse(rawDataLine);
if (payload.error || payload.type === 'error') {
  throw new Error(`Mid-stream error after HTTP 200: ${payload.error?.message || JSON.stringify(payload)}`);
}

[边界说明]这是 Claude 官方文档与 OpenAI 兼容流式协议明确强调的生产级边界条件。

本地模型处理万字长 Prompt 预填充（Time-to-First-Token）可能耗时 20–90 秒期间无数据帧返回，触发 Nginx 或网关默认 60 秒空闲超时切断。

1. 在 Nginx 或反向代理配置中设置 proxy_buffering off 与 proxy_read_timeout 300s。
2. 客户端侧将首字等待超时（TTFT Timeout）与分块空闲超时区分设置。

# Nginx location block for LLM SSE endpoints
location /v1/ {
    proxy_pass http://127.0.0.1:11434/v1/;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
    chunked_transfer_encoding on;
}

[边界说明]若经由云端代理转发，还需注意云厂商网关默认的 100 秒无字节传输限制。

模型输出达到了 max_tokens（或 num_predict）上限，导致 JSON 字符串在闭合括号前被截断，但流本身正常发送了 [DONE]。

1. 在执行 JSON.parse 前，强制检查最后一个 Chunk 的 finish_reason 是否为 "stop"。
2. 若使用带 <think> 标签的推理模型，需预留至少 2048 max_tokens 并在解析前剥离思考块。

if (lastChunk.choices?.[0]?.finish_reason === 'length') {
  throw new Error('Output truncated by max_tokens limit before JSON closed');
}

[边界说明]即使开启了 json_object 模式，一旦触及 max_tokens 上限依然会产生未闭合的残缺 JSON。