1.2 多模型与自定义端点
本节目标
除了 DeepSeek,学会接入更多模型提供智能的大模型服务,dsh 负责调度它来思考与生成。提供商,以及把 dsh 接到任意 OpenAI 兼容的服务上,比如本地的模型或者公司内部的网关。
两种接法
0.1.7-alpha.1 起,模型提供智能的大模型服务,dsh 负责调度它来思考与生成。页合并成了一个添加模型提供商按钮,点开一张卡片,顶部用分段开关选模式,两种场景都在这张卡里:
- 第三方模型提供商:从 dsh 自带的提供商列表里选,填个密钥就能用,最省事
- 自定义模型 API:手动填一个服务地址,适合本地模型、中转网关、公司内部服务
开关下面有一行说明各自是干嘛的;两个模式各记各的草稿,来回切不会丢已填的内容。
这一节两种都讲。
方式一:从内置列表添加
打开设置 → 模型
点添加模型提供商,模式选第三方模型提供商
在弹出的列表里选择你用的服务。列表以英文标识(Provider ID)列出各家平台,内置有
anthropic(Anthropic)、openai(OpenAI)、moonshotai(Kimi)、zai(GLM/智谱)、qwen(通义千问)、minimax、xiaomi、nvidia、together等二十多家选中后会进入该提供商的配置表单,填上对应的 API 密钥访问模型服务的凭据,通常以 sk- 开头,需妥善保管。,点保存
0.1.6-alpha.1 起,DeepSeek 内置提供商默认走 Anthropic Messages 协议,API 地址默认是
https://api.deepseek.com/anthropic,密钥不用换——新协议复用同一个DEEPSEEK_API_KEY。模型显示名0.2.1-alpha.2 起写作 DeepSeek-V4.1-Flash(本教程旧版里的DeepSeek-V41-Flash、Messages Flash两种叫法都已过时)
更正:DeepSeek 已经不能切回 Chat Completions
本节此前教读者"在 $DSH_HOME/settings.yaml 的 llm-deepseek 段把 protocol 改成 chat-completions"。0.1.7-alpha.1 起这条不成立了:官方 DeepSeek 适配器改成只说 Messages 协议,protocol 不再是可配置字段,配置里留着它会让启动直接失败,报 llm-deepseek: protocol is not configurable; remove it and use a Messages-compatible baseURL。想用 OpenAI 兼容的 DeepSeek 端点(https://api.deepseek.com),走本页下面的自定义模型 API:API 协议选 openai-completions、地址填 https://api.deepseek.com,把它当成一个普通 OpenAI 兼容网关来配。
每个提供商的表单都长得差不多,都是密钥加可选的模型列表,和 1.1 节 DeepSeek 的编辑表单一致。协议下拉里的选项会显示各协议的产品名,没起名字的协议直接显示协议标识。
OAuth 提供商
通过 OAuth 登录的提供商(例如 Codex)暂不支持在表单里直接配置,后续会逐步开放。
拿不到某家的密钥?
各家平台都有自己的开放平台,去对应官网注册申请即可。填完后和 DeepSeek 一样,模型立即可用。
方式二:添加自定义提供商
这个入口是给"标准 OpenAI 兼容接口"准备的。你的服务只要实现了 OpenAI 的接口协议,就能被 dsh 识别。典型的场景有三个:
- 本地跑的模型,比如 Ollama、vLLM、LM Studio
- 第三方中转服务,统一转发到多家大模型
- 公司内部网关,只对员工开放
点添加模型提供商,模式切到自定义模型 API,弹出下面的表单:

逐个字段解释:
| 字段 | 填什么 | 例子 |
|---|---|---|
| Provider ID | 小写字母开头的唯一标识,用于派生凭据名 | my-gateway |
| 显示名称 | 界面上显示的名字 | 我的网关 |
| API 地址 | 服务的完整地址 | https://gateway.example/v1 |
| API 协议 | 接口协议,三种可选 | openai-completions |
| API 密钥访问模型服务的凭据,通常以 sk- 开头,需妥善保管。 | 该服务的密钥 | sk-... |
| 模型目录 | 列出可用的模型 ID | 见下方说明 |
0.1.5-alpha.2 起,API 地址会先校验协议(必须 http:// 或 https://)并自动归一化尾斜杠,填错会立即报错提示,不用等服务返回 404 才知道坏了。
API 协议选哪个
- openai-completions:标准 OpenAI 对话补全协议,绝大多数服务都兼容,默认选这个
- openai-responses:OpenAI 新版 Responses 协议,只有 OpenAI 自家最新服务用
- anthropic-messages:Anthropic(Claude)的消息协议,0.1.2-rc.1 起 dsh 能直接拉取 Claude 官方的模型列表
不确定就选第一个。
模型目录怎么填
表单里有一个模型目录区域,两种填法:
- 点获取可用模型,dsh 会自动请求服务把模型列表拉下来。请求使用表单当前的 API 地址、协议和密钥;已保存的提供商则用已存储的密钥。拉取成功后会弹出一个可搜索的选择框,搜索、勾选想要的模型,再点添加所选
- 如果服务不支持列举模型,点添加模型手动填:先填模型 ID(请求里用的原始 ID,比如
qwen2.5-7b),再填显示名称(界面下拉里看到的)
填完点创建提供商就完成了。
探测模型的局限
探测读取的是常见网关公开的列表格式,但并非每个端点都用这些格式作答,所以它只是便利手段而非保证:探测失败或列表为空时,手动添加模型 ID 即可,效果完全一样。内置提供商一律由已安装目录作答,即使其 API 地址指向网关也是如此;要查看网关实际提供的模型,请通过自定义提供商探测。
哪些协议能自动列举模型
获取可用模型 走 dsh 内部的 model discovery,0.1.2-rc.1 起支持 OpenAI 兼容协议(openai-completions / openai-responses)和 Anthropic Messages 协议两家。Anthropic 用自己的 GET /v1/models 端点配 x-api-key + anthropic-version 请求头,所以官方 Claude 接口、AWS Bedrock 这类 Anthropic 兼容网关点一下就能拉下模型列表。Azure、Codex 等走非 Bearer 认证的协议不在此列,仍需手动填模型 ID。
进阶配置现在写在哪个文件
本节下面几处都要手改配置,先把路径讲清楚。模型字段写在当前 profile 的 cordis.patch.yml 里:用 dsh web 启动就是 $DSH_HOME/profiles/web/cordis.patch.yml,自定义 profile 换对应名字;浏览器和服务器在同一台机器上时,也可以点设置页顶部的打开配置文件直达。这是模型页真正写入的那份文档。$DSH_HOME/settings.yaml 是早期版本留下的偏好文件,启动时只导入一次、写完就改名成 settings.yaml.imported,往里加模型字段不再起作用——本教程旧版三处 YAML 都写的 settings.yaml,这次一起更正。还有一点要记住:Cordis 的配置覆盖按整条替换同名条目的配置,手改时要保留该条目里其他 provider 和字段。统一写法是以插件 id 打头的列表:
- id: llm-pi-ai
config:
providers:
# 在这里继续写你的 provider让自定义模型支持图片
如果自定义提供商背后是个多模态模型,dsh 默认把它当纯文本。首选还是界面:打开模型编辑表单的自定义设置,展开该模型的模型选项,勾选输入类型里的图片再保存(下面一段就是这个开关)。要批量配置或临时救急,也可以在 $DSH_HOME/profiles/web/cordis.patch.yml 里给这个模型声明输入模态:
- id: llm-pi-ai
config:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
models:
- id: vision-preview
input: [text, image]input 只对该模型生效;如果该提供商下所有模型都支持图片,可以写到路由级的 defaultInput: [text, image] 作为兜底。声明了图片模态,你在对话里粘贴图片它才会接收,否则会在发送前拒绝。
0.1.6-alpha.2 起,这件事也可以在设置界面里做:打开模型编辑表单,模型选项下有图片输入一项,三档可选,支持(声明文本 + 图片)、不支持(仅文本)、默认(移除显式声明,回到继承规则:自定义模型继承已安装目录或提供商默认值,DeepSeek 目录里没写模态就当仅文本)。不用再手改 settings.yaml。注意 DeepSeek 模型选了不支持图片后,它名下的图片请求限制字段会被一并清掉,想再开图片得重新配。
网关总拒绝请求?检查兼容性
有些 OpenAI 兼容网关地址通、密钥也对,却每条请求都报错。原因是 dsh 的 pi-ai 适配器会按端点推断请求形态:带推理的模型会把系统提示以 developer 角色发送、输出上限用 max_completion_tokens 字段,而很多网关只认 max_tokens、不认 developer 角色。同样在 profile 的 cordis.patch.yml 里修正路由:
- id: llm-pi-ai
config:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: my-model最常见的两步就是 supportsDeveloperRole: false 加 maxTokensField: max_tokens。开关名都要给值,留空会被拒绝;具体支持哪些开关以配置目录里的 PiAiCompatProfile 为准。
给自定义模型加推理等级
对于声明了推理等级的模型,模型选择器会提供推理等级菜单。内置提供商的模型从已安装目录继承其等级。手动录入的模型不声明任何等级,因此模型菜单里不会出现推理等级项,由端点自身的默认值决定模型是否思考。
0.2.1-alpha.4 起这件事不用改配置文件了,模型页就能配:编辑该提供商 → 展开自定义设置 → 点开那一行模型的模型选项(就在输入类型下面)→ 打开推理等级开关。界面是一张两列表格,列头是档位和API 参数值:
- 打开开关默认给你四行:off、low、medium、high;添加档位补一行,删除档位去掉一行。档位下拉可选
off/minimal/low/medium/high/xhigh/max,同一个档位在一列里只能用一次 - API 参数值默认与档位名相同,只有网关自己另有一套词汇时才改,比如把
max那行填成xhigh off那行的参数值框是禁用的,占位写着关闭思考——对多数端点来说,不思考就是不传这个参数- 校验说得很直:只留 off 会提示「至少添加一个 Off 以外的档位;不需要思考请关闭推理等级。」,漏填值提示「Off 以外的档位都需要填写 API 参数值,且参数值不能为空字符串。」
- 把开关关掉等于删掉这条声明;旁边的 ?(推理等级说明)会提醒「配置中已写入的值会保留并发送」
这个开关只给手工声明的自定义模型 API 路由显示;走内置目录的提供商(包括 DeepSeek)不在这里改,它们的等级由目录提供。
界面保存后写进 profile 的 cordis.patch.yml(providers.<id>.models[].reasoningEfforts),想直接编辑文件也可以:
- id: llm-pi-ai
config:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
reasoning: high
models:
- id: my-reasoner
reasoningEfforts:
off:
high: high
max: max每个键都是菜单提供的一个等级,其值是在协议上以 reasoning_effort 发送的写法,因此 max: xhigh 可以为自有一套词汇的网关重命名某个等级。只有 off 可以留空,因为对多数端点来说,不思考就是不传该参数。路由的 reasoning 是会话尚未选择等级时采用的等级;在选择器中选定某个等级后,它会与模型一起保存为新会话的默认值。
内置提供商的等级仍要写文件
自定义模型能在界面里配等级了,但内置提供商模型的推理等级、请求兼容性开关、请求头、超时和重试策略仍然只能在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 里设——就是模型页写入的同一份文档,可以直接编辑。
DeepSeek 模型不用配
DeepSeek 自身的路由不需要以上任何配置:其模型已经提供 off、low、high 和 max,llm-deepseek.reasoningEffort 设置选择器的起始默认值即可。1.1 节配好的 DeepSeek 提供商开箱即用。
实战:接一个本地 Ollama
拿最常见的本地模型场景举例。假设你装了 Ollama 并跑起了 qwen2.5:7b:
- 模型页点添加模型提供商,模式切到自定义模型 API
- Provider ID 填
ollama-local - 显示名称填
本地 Ollama - API 地址填
http://localhost:11434/v1 - API 协议选
openai-completions - API 密钥随便填一个占位(本地服务通常不校验)
- 点获取可用模型,或手动添加模型 ID
qwen2.5:7b - 点创建提供商
之后就能在主界面的模型选择器里看到本地 Ollama了。
本地服务的地址
本机服务用 localhost 就行。如果 Ollama 跑在另一台机器上,地址要换成那台机器的局域网 IP,并确认服务监听了非本机端口。
常见问题
问:填完自定义提供商,模型选择器里看不到模型?
先确认模型目录里有没有模型。用获取可用模型拉一次,不行就手动添加。另外确认 API 地址和协议没选错,地址末尾的路径(比如 /v1)要和服务要求一致。
问:保存时报"无法连接"?
地址不对或者服务没起来。先在浏览器里直接访问 API 地址试试,能通再回来填。
小结
- 一个添加模型提供商入口管两种接法(0.1.7 起),卡内分段切换第三方与自定义模式,草稿互不丢失
- 内置支持二十多家提供商,选完填密钥即可
- 自定义提供商适合本地模型、中转、公司网关,关键是填对地址 + 协议 + 模型
- 模型目录可以用获取可用模型自动拉取(弹出可搜索选择框),也可以手动添加
- 推理等级(0.2.1-alpha.4 起)和图片模态(0.1.6-alpha.2 起)都能在模型页的自定义设置 → 模型选项里配;网关兼容性、内置提供商等级等进阶字段仍要手改,但文件是 profile 的
cordis.patch.yml,不是$DSH_HOME/settings.yaml
模型配好了,接下来选一个工作区,告诉 dsh 在哪个地盘干活。