dsh-deepseek-relay

August 26, 2026 · View on GitHub

dsh-deepseek-relay — DeepSeek 中转站思考强度适配插件

让 deepseek-harness（dsh）里通过中转站（第三方 OpenAI 兼容网关，如 OneAPI / new-api / one-hub 或各种「API 转发」服务）接入的 DeepSeek 模型，也能像官方 API 一样在 Web UI 里设置推理等级（思考强度）：Off / Low / High / Max 四档，并把思考参数按中转站认识的格式发出去。

⚠️ 升级须知（v0.1.1，重要）

如果你是从旧版升级的老板，只有一处需要你手动确认：

唯一需要你手动改的地方

如果你的老配置里有个模型实际能识图（比如 deepseek-v4-flash-vision-exp），但之前只写了 id、没写任何能力字段——升级后它默认变为「不支持识图」。想让它能收图，需要手动补一行：
- id: deepseek-v4-flash-vision-exp
  supportsVision: true   # ← 升级后想用识图，这行要自己加
其余模型（纯文本）无需改动，保持原样即可；supportsVision 缺省按 false 处理，这是设计使然——让 harness 在误传图片时给出友好的「该模型不支持图片」提示，而不是把请求发出去再报错。

特性

✅ 在 Web UI 暴露 Off / Low / High / Max 四档推理等级（与官方 llm-deepseek 完全一致）
✅ 自动按中转站方言（openai / deepseek）序列化思考参数
✅ 支持按模型覆盖 wire 值，应对网关要求 ultra 之类自定义取值
✅ 支持按模型声明识图能力（supportsVision），收图时给友好拦截
✅ 一个插件实例可挂多条中转站路由
✅ 纯插件即可生效，无需改动 harness 本体

问题

官方 API 走内置 llm-deepseek 适配器，resolveModel 会返回 reasoning.efforts = [Off, Low, High, Max]，所以 UI 有推理等级选项。

中转站通常走 llm-pi-ai 的「自定义提供方」（openai-completions）。但：

Web UI 的表单没有 reasoningEfforts 字段，手写模型没有推理元数据，UI 里根本不出现推理等级选项；
即使声明了，发往中转站的思考参数格式也不一定对——DeepSeek 官方格式（thinking: {type: "enabled"} + reasoning_effort）和 OpenAI 格式（只有 reasoning_effort）在中转站上不通用。

解决方式

本插件注册独立的 OpenAI 兼容适配器路由（每条中转站一条路由），并且：

始终向 UI 暴露 Off / Low / High / Max 四档推理等级（与官方 llm-deepseek 完全一致，见 src/adapter.ts 的 REASONING_EFFORTS）；
按 thinkingFormat 把思考参数写成中转站认识的方言（见 src/serialize.ts）：

档位	`openai`（默认）	`deepseek`
off	不发送任何思考字段（网关默认）	`thinking: {type:"disabled"}`
low	`reasoning_effort: "low"`	`thinking:{type:"enabled"}` + `reasoning_effort:"low"`
high	`reasoning_effort: "high"`	`thinking:{type:"enabled"}` + `reasoning_effort:"high"`
max	`reasoning_effort: "max"`	`thinking:{type:"enabled"}` + `reasoning_effort:"max"`

thinkingFormat: auto 时按 baseURL 域名猜：含 deepseek.com/ai/cn 用 deepseek，其余默认 openai（多数中转站）。
支持按模型覆盖 wire 值（reasoningEfforts），应对「网关要求 ultra 之类自定义取值」的场景。

使用

两种方式都符合官方插件规范（见下文「官方规范符合性」）：

方式 A：从源码运行，`--patch` 本地加载（开发 / 自用）

在 deepseek-harness 仓库根目录（已 pnpm install 过）：

pnpm dsh web --patch ./dsh-deepseek-relay/cordis.yml

启动前先编辑 cordis.yml，把 providers.relay 换成你的中转站信息：

- insert:
    - id: dsh-deepseek-relay
      name: '/绝对路径/deepseek-harness/dsh-deepseek-relay/src/index.ts'
      config:
        providers:
          my-relay:
            baseURL: https://your-relay.example.com/v1
            apiKeyEnv: RELAY_API_KEY
            thinkingFormat: auto
            models:
              - id: deepseek-v4-flash
              - id: deepseek-v4-flash-vision-exp
                supportsVision: true   # 能识图的模型记得开

API key：设置环境变量 RELAY_API_KEY，或启动后在 Web UI 设置 → 模型 里选中该提供方填入密钥（密钥存 $DSH_HOME/.credentials.yaml）。
模型：models 列表即模型选择器里出现的模型；contextWindow / maxTokens 会作为上下文 / 输出上限信息。
保存后，在模型选择器选到该模型的会话里，输入框旁就会出现 Off / Low / High / Max 推理等级下拉（和官方 API 一样）。

方式 B：作为组合包（bundle）安装（可分发）

# 本地目录 / git / tarball 均可；首次会初始化 profile
dsh plugin --profile demo add ./dsh-deepseek-relay
# 或 dsh plugin --profile demo add github:you/dsh-deepseek-relay

包内 cordis.patch.yml 声明了插件行（name: dsh-deepseek-relay 按包名解析，加载 lib/index.js），prepare 脚本（esbuild）会在安装时自动构建 lib/。安装后插件处于 dormant（空配置可安全装载，不注册任何路由 / 目录，适配器与 configurable-provider 目录两侧都有空数组守卫，见 src/index.ts 的 ensureDirectory / ensureRegistrationFacts），在 profile 的 cordis.patch.yml 或 $DSH_HOME/cordis.patch.yml 里覆盖同 id 行填入中转站配置（参考 cordis.patch.yml 顶部注释），或随后在 Web UI 设置中热更新生效。

配置项

字段	说明	默认
`baseURL`	中转站 OpenAI 兼容地址，`/chat/completions` 自动拼接	必填
`apiKeyEnv`	API key 环境变量名	`RELAY_API_KEY`
`displayName`	模型选择器显示名	路由 key
`thinkingFormat`	`auto` / `openai` / `deepseek`	`auto`
`reasoningEffort`	默认推理等级 `off`/`low`/`high`/`max`	`high`
`maxTokensField`	输出上限字段 `max_tokens`/`max_completion_tokens`	`max_tokens`
`maxTokens`	路由级默认输出上限	256000
`models[].id`	发往网关的模型 id	必填
`models[].name`	选择器显示名	id
`models[].contextWindow`	上下文容量	262144
`models[].maxTokens`	该模型输出上限	路由级值
`models[].reasoningEfforts`	按档位覆盖 wire 值（`null`=支持但不发送）	方言默认
`models[].supportsVision`	模型是否支持识图（Web UI 中是模型行的「支持识图」勾选框）。`true` → `inputModalities:['text','image']`；`false` 或省略 → `['text']`（显式非 undefined，让 harness 在提交图片时给出友好的「模型不支持图片」提示）	`false`

💡 升级用户看这里：老配置里若某个模型实际能识图但只写了 id，升级后它会按 supportsVision: false 处理——想用识图就按上方「升级须知」补一行 supportsVision: true。

官方规范符合性

对照仓库 docs/user/develop/basic/{index,config,publish}.zh.md 与 docs/user/develop/practice/llm-adapter.zh.md：

官方要求	本插件
插件模块导出 `name` + `apply(ctx, config)`	✅ `src/index.ts`
声明 `inject`（本插件依赖 `llm` 服务）	✅ `inject = ['llm']`
导出 `Config` 类型 + 同名 Schemastery schema，默认值写在 schema 中	✅ `src/index.ts`
`--patch` overlay 加载本地插件（源码路径 `.ts`）	✅ `cordis.yml`（方式 A）
组合包 `dsh.bundle` manifest + `cordis.patch.yml`（按包名引用）	✅ `package.json` + `cordis.patch.yml`（方式 B）
git 安装的 TS 包必须自带 `prepare` 构建（产出 `lib/`）	✅ `scripts/build.mjs` + `tsconfig.build.json`
`LlmAdapter` 契约：实现 `stream()`、`resolveModel` 返回 `reasoning` 元数据、`attributionHeaders()`、`LlmError` 稳定 code、透传 `options.signal`	✅ `src/adapter.ts`

注：--patch 从源码路径加载 .ts 是官方教程支持的开发方式；正式分发（npm / git / tarball）走方式 B，prepare 构建出 lib/index.js 后与源码运行等价。两种方式共用同一份 src/。

备选：不装插件，直接用官方 llm-pi-ai 手工配置

官方 llm-pi-ai 本身支持同样的能力，只是要手写 $DSH_HOME/settings.yaml。如果不想装插件，可以这样写（等效于 thinkingFormat: deepseek）：

llm-pi-ai:
  providers:
    my-relay:
      apiKeyEnv: RELAY_API_KEY
      api: openai-completions
      baseURL: https://your-relay.example.com/v1
      compat:
        thinkingFormat: deepseek
      models:
        - id: deepseek-v4-flash
          reasoningEfforts:
            off:
            low: low
            high: high
            max: max

注意：reasoningEfforts 里 off: 冒号后留空表示「支持该档、不发送」；其余档必须给 wire 值，否则配置被拒。多数网关（OneAPI 等）应使用 thinkingFormat: openai 而不是 deepseek，除非网关原样转发官方 API。

代码结构

dsh-deepseek-relay/
├── cordis.yml          # --patch 本地加载配置示例（方式 A）
├── cordis.patch.yml    # 组合包配置层（方式 B，dsh.bundle.patch 指向它）
├── package.json        # dsh.bundle manifest + scripts（prepare 构建）
├── scripts/build.mjs   # esbuild 构建单文件 lib/index.js（external @deepseek-ai/*）
├── tsconfig.json       # 类型检查（tsc --noEmit）
└── src/
    ├── index.ts      # 插件入口：Config schema、路由注册、settings 热更新
    ├── adapter.ts    # RelayAdapter：四档推理等级 + fetch/SSE stream
    ├── serialize.ts  # 消息 + 思考参数序列化（openai/deepseek 方言）
    ├── translate.ts  # SSE chunk → harness StreamChunk
    ├── sse.ts        # SSE 解析（eventsource-parser）
    └── types.ts      # wire 类型

验证

tsc --noEmit 完整类型检查：0 错误（对 @deepseek-ai/dsh-llm 等 0.1.1-rc.2 官方 npm 包）。
序列化逻辑测试（resolveThinking / resolveThinkingFormat / serializeRequest，openai/deepseek 方言 × off/low/high/max × 模型级覆盖 × session-title × maxTokensField）：全部通过。
SSE 转换测试（reasoning_content 流、tool_calls 增量拼接、usage 去重、[DONE] 收尾、空响应）：全部通过。
验证依赖通过 npm 平铺安装（C:/Users/29261/Downloads/relay-verify，测试脚本可复用）。

注意事项

中转站若在 /chat/completions 之外还有 /v1 后缀，baseURL 写完整路径，例如 https://relay.example.com（若网关恰好要求不带 /v1）。
插件默认只支持文本输入（与官方 llm-deepseek 一致）；图片输入会以 UNSUPPORTED_CONTENT 拒绝。若某模型已声明 supportsVision: true，但图片传输功能（attachments store 集成）尚未实现，会给出 UNSUPPORTED_CONTENT（「图片传输待实现」），届时再补。
一个插件实例可配多条中转站路由（providers dict 里加即可）。

免责声明

本插件为第三方非官方适配层，与 DeepSeek 官方无隶属关系。使用中转站 / 第三方网关请遵守其服务条款与当地法律法规；本插件按「现状」提供，不保证适配所有网关，也不对安装、使用、升级过程中可能造成的任何数据丢失、配置损坏或账号风险负责。升级前请自行备份 $DSH_HOME（含 settings.yaml 与 .credentials.yaml）。点击本仓库链接即视为已知晓并同意上述条款。