LXFLGH/dsh-deepseek-relay

· English · 日本語

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）。但：

1. Web UI 的表单没有 reasoningEfforts 字段，手写模型没有推理元数据，UI 里根本不出现推理等级选项；
2. 即使声明了，发往中转站的思考参数格式也不一定对——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）。点击本仓库链接即视为已知晓并同意上述条款。