[Bug] Configuring third-party OpenAI-compatible gateways: STREAM_CLOSED error message is too vague to root-cause

[2233qazwsx0]

环境

• DSH 版本: 最新 npm 全局安装
• 运行环境: Android (proot Ubuntu 24)
• API 网关: 第三方 OpenAI 兼容网关（非 DeepSeek 官方 api.deepseek.com）
• 模型: deepseek-v4-flash

问题

DSH 在配置第三方 OpenAI 兼容 API 网关时存在两个配置陷阱，导致所有请求必然失败并抛出 LlmError("SSE stream ended without [DONE]", "STREAM_CLOSED")，用户体验是「一对话就报错，完全不可用」。

陷阱 1: baseURL 路径不完整时无任何报错提示

现象: 当用户配置 baseURL 为 https://example.com/（缺少 /v1 后缀）时，DSH 的 DeepSeekAdapter.request() 方法会拼接 /chat/completions，最终请求到 https://example.com/chat/completions。

很多第三方 API 网关的正确端点是 https://example.com/v1/chat/completions。缺少 /v1 的请求会被网关返回一个 HTML 首页（200 OK，Content-Type: text/html），而不是 SSE 流。

parseSse() 函数尝试用 EventSourceParserStream 解析这个 HTML 响应，当然不会产生任何合法的 SSE event，循环结束后没有收到 [DONE]，于是抛出 STREAM_CLOSED。

误导性: 这个错误信息 "SSE stream ended without [DONE]" 完全没有提示用户可能是 baseURL 配错了。用户会以为是网络问题、模型问题或者 DSH 本身的 bug，很难定位根因。

建议改进:

1. 在 request() 方法中，检查 HTTP 响应的 Content-Type。如果不是 text/event-stream，应该抛出更明确的错误，例如：

   LlmError("Expected SSE response but got text/html — check your baseURL configuration", "INVALID_CONTENT_TYPE")
   

2. 或者在启动时做一次 baseURL 的健康检查（比如请求 /models 端点），提前发现配置错误。
3. 至少在错误信息中包含实际收到的 Content-Type 和响应 URL，方便用户排查。

陷阱 2: 模型 ID 大小写敏感，配置不匹配时报错信息模糊

现象: 用户在 settings.yaml 中配置模型 ID 为 deepseek-V4-flash（大写 V），但 API 网关上注册的模型 ID 是 deepseek-v4-flash（小写 v）。

DSH 直接把配置的 model ID 原样发送给 API，API 网关返回 model_not_found。然而 DSH 的 retry policy 可能会重试这个请求，最终用户看到的还是 STREAM_CLOSED 或其他模糊错误。

建议改进:

1. 在 DSH 启动时或首次请求前，调用 /v1/models 端点拉取可用模型列表，与用户配置的 models 做交叉校验，对大小写不一致的情况给出 warning。
2. 或者在遇到 model_not_found 错误时，提示用户检查模型 ID 的拼写和大小写，并附带 API 返回的完整错误信息。

根因代码位置

文件: @deepseek-ai/dsh-llm-deepseek/lib/index.js

// 第 150 行 — parseSse 函数
async function* parseSse(stream, onComment) {
    const events = stream.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream({ onComment }));
    for await (const { data } of events) {
        yield data;
        if (data === "[DONE]") return;
    }
    throw new LlmError("SSE stream ended without [DONE]", "STREAM_CLOSED");
}

// 第 588 行 — request 方法
response = await fetch(`${connection.baseURL}/chat/completions`, {
    method: "POST",
    headers,
    body: payload,
    signal
});
// 这里没有检查 response.headers.get("content-type") 是否为 text/event-stream

修复建议

修复 1: 在 request() 方法中增加 Content-Type 校验

在 fetch() 返回后、调用 parseSse() 之前，增加：

const contentType = response.headers.get("content-type") ?? "";
if (!contentType.includes("text/event-stream")) {
    const bodyPreview = await response.text().catch(() => "").then(t => t.slice(0, 200));
    throw new LlmError(
        `Expected SSE response (text/event-stream) from ${connection.baseURL}/chat/completions but got ${contentType}. Response preview: ${bodyPreview}`,
        "INVALID_CONTENT_TYPE"
    );
}

修复 2: 在模型解析阶段增加大小写校验

在 resolveModel() 或首次请求时，可以提示用户检查模型 ID：

// 当 API 返回 model_not_found 时，附带提示
if (providerError?.code === "model_not_found" || providerError?.type === "new_api_error") {
    message = `Model "${body.model}" not found. Please verify the model ID (case-sensitive) matches your API provider's catalog.`;
}

临时解决方案

对于遇到同样问题的用户，手动修改 ~/.dsh/settings.yaml：

llm-deepseek:
  baseURL: https://your-api-gateway.com/v1  # 确保包含 /v1
  models:
    - id: deepseek-v4-flash    # 确保大小写与 API 网关一致
      name: DeepSeek-V4-Flash
      contextWindow: 1000000

可以用 curl 验证：

curl -s https://your-api-gateway.com/v1/models -H "Authorization: Bearer $KEY"

总结

这两个问题本质上都是「配置错误 → 模糊报错 → 用户无法定位」。DSH 作为一个面向开发者的工具，应该在错误提示上做得更好。STREAM_CLOSED 这个错误码太笼统了，它背后可能隐藏着完全不同的根因（HTML 响应、模型不存在、网络中断等），应该被区分开。

[weijiafu14]

两个陷阱都成立，而且陷阱 1 的机制你写得很准。补三件：一个能立刻自查的办法、一个可能更合适的配置路径、以及这个报错属于哪一类。

一、两个陷阱各自最快的自查

陷阱 1（baseURL 少了 /v1）——一条 curl 就能定死：

curl -i -X POST "https://example.com/chat/completions" \
  -H 'content-type: application/json' -H 'authorization: Bearer <key>' \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"stream":true}'

看第一行状态码和 content-type。回 text/html 就坐实了你的判断；把 URL 换成带 /v1 的再跑一次，回 text/event-stream 就说明只差这一段。这比在 DSH 里反复试快得多，而且结果可以直接贴进这个帖子当证据。

陷阱 2（模型 id 大小写）——先看网关自己认什么：

curl -s "https://example.com/v1/models" -H 'authorization: Bearer <key>'

二、如果你想确认 DSH 到底发了什么，有个现成的透传录制器

你的陷阱 2 里有个环节是推测的——"DSH 直接把配置的 model ID 原样发送给 API"。这件事可以直接看到，不用推。

我们仓库里有个独立的小脚本（recording-proxy.mjs），它不是假网关：每个请求真发给你的上游、真实响应原样流回来，它只多做一件事——把请求体存一份到磁盘。

PROXY_UPSTREAM=https://example.com PROXY_PORT=4599 node recording-proxy.mjs
# 然后把 baseURL 指到 http://127.0.0.1:4599/v1，正常跑一轮

然后 requests.jsonl 里就是真正打到线上的那个 body——model 字段是什么大小写一眼可见。凭据走请求自己的 Authorization 头，脚本不读环境变量也不存任何凭据。

（我们做这个是因为自己有条规矩：端到端不许用 mock，假端点回一句固定话就"通过"，证明的只是假端点会说话。但它对排查自建网关同样好用，所以就这么放着了——你不需要装我们任何东西，把那个 .mjs 拷走就能跑。）

三、一个可能更合适的配置路径

你引的根因文件是 @deepseek-ai/dsh-llm-deepseek/lib/index.js。那是 DeepSeek 官方端点的专用适配器（它注册的 provider 就是 deepseek-official）。

DSH 还有另一个官方适配器 llm-pi-ai，那才是为任意 OpenAI 兼容网关准备的那条路：

llm-pi-ai:
  providers:
    my-gateway:
      displayName: My Gateway
      api: openai-completions
      baseURL: https://example.com/v1
      apiKeyEnv: MY_GATEWAY_KEY
      models:
        - id: deepseek-v4-flash
          contextWindow: 131072

走这条的好处：它有一整套面向第三方网关的 compat 开关（supportsDeveloperRole、maxTokensField 等——很多网关正是在这些方言上炸），也有模型发现的 seam。这段是纯 DSH 官方配置，不需要装任何插件。

边界说清：我不知道换到 llm-pi-ai 是否能让 /v1 那个坑变得更好诊断（可能一样糊）。我只是觉得，既然你在配第三方网关，用为第三方网关设计的那个适配器更顺；你这两条改进建议对 llm-deepseek 依然成立且值得提。

四、这个报错属于一个反复出现的类

"SSE stream ended without [DONE]" 的问题不在措辞，在于解析器把"喂错了内容"当成了"什么都没有"。一个 HTML 页面对 SSE 解析器来说是合法输入，只是产生零个事件——所以它不会报"格式错误"，它会安静地跑完然后说"流结束了"。

同样的形状最近在这个社区出现过好几次：

• #3568：工具参数 JSON 解析失败 → 退化成空 {} → server 报"缺少必填参数" → 模型以为自己没传，原样重发，17 步死循环；
• #740：残缺的会话历史被忠实投影，每次请求都带上，永久 INVALID_REQUEST。

共同点：解析/投影环节遇到不该出现的输入时，产出了一个"看起来正常的空值"，而不是一个说得清的错误。 于是错误信息指向了下游的症状（没有 [DONE] / 缺参数 / 请求非法），而根因在上游好几步之外。

你的修复 1 正好是这一类的标准解法——把实际收到的东西（content-type + body 前 200 字节）放进错误里。我建议在提案里把这一点写成通则而不是个案：任何解析器在"零产出"时，都应该把它实际看到的东西报出来，因为零产出恰恰是最没有信息量的失败形态。

边界与利益相关

我们不修 DSH 自家组件——dsh-llm-deepseek、parseSse 都在 DSH 里。上面全是自查办法、配置建议和归类。

利益相关：我维护 pi2dsh（Pi 生态兼容层），第二节那个录制器是它的验收装置之一。这条不推销：那个脚本是独立的一个文件，拷走直接 node 跑；第三节那段 YAML 是纯官方配置。你这两个陷阱是 DSH 自己适配器里的可诊断性问题，装什么插件都不解决。