Skip to content

1.2 多模型与自定义端点 ​

本节目标

除了 DeepSeek,学会接入更多模型提供智能的大模型服务,dsh 负责调度它来思考与生成。Model/ˈmɒdl/提供商,以及把 dsh 接到任意 OpenAI 兼容的服务上,比如本地的模型或者公司内部的网关。

两种接法 ​

0.1.7-alpha.1 起,模型提供智能的大模型服务,dsh 负责调度它来思考与生成。Model/ˈmɒdl/页合并成了一个添加模型提供商按钮,点开一张卡片,顶部用分段开关选模式,两种场景都在这张卡里:

  • 第三方模型提供商:从 dsh 自带的提供商列表里选,填个密钥就能用,最省事
  • 自定义模型 API:手动填一个服务地址,适合本地模型、中转网关、公司内部服务

开关下面有一行说明各自是干嘛的;两个模式各记各的草稿,来回切不会丢已填的内容。

这一节两种都讲。

方式一:从内置列表添加 ​

  1. 打开设置 → 模型

  2. 点添加模型提供商,模式选第三方模型提供商

  3. 在弹出的列表里选择你用的服务。列表以英文标识(Provider ID)列出各家平台,内置有 anthropic(Anthropic)、openai(OpenAI)、moonshotai(Kimi)、zai(GLM/智谱)、qwen(通义千问)、minimax、xiaomi、nvidia、together 等二十多家

  4. 选中后会进入该提供商的配置表单,填上对应的 API 密钥访问模型服务的凭据,通常以 sk- 开头,需妥善保管。API key/ˌeɪpiːˈaɪ kiː/,点保存

  5. 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- 开头,需妥善保管。API key/ˌeɪpiːˈaɪ kiː/该服务的密钥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 官方的模型列表

不确定就选第一个。

模型目录怎么填 ​

表单里有一个模型目录区域,两种填法:

  1. 点获取可用模型,dsh 会自动请求服务把模型列表拉下来。请求使用表单当前的 API 地址、协议和密钥;已保存的提供商则用已存储的密钥。拉取成功后会弹出一个可搜索的选择框,搜索、勾选想要的模型,再点添加所选
  2. 如果服务不支持列举模型,点添加模型手动填:先填模型 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 打头的列表:

yaml
- id: llm-pi-ai
  config:
    providers:
      # 在这里继续写你的 provider

让自定义模型支持图片 ​

如果自定义提供商背后是个多模态模型,dsh 默认把它当纯文本。首选还是界面:打开模型编辑表单的自定义设置,展开该模型的模型选项,勾选输入类型里的图片再保存(下面一段就是这个开关)。要批量配置或临时救急,也可以在 $DSH_HOME/profiles/web/cordis.patch.yml 里给这个模型声明输入模态:

yaml
- 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 里修正路由:

yaml
- 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),想直接编辑文件也可以:

yaml
- 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:

  1. 模型页点添加模型提供商,模式切到自定义模型 API
  2. Provider ID 填 ollama-local
  3. 显示名称填 本地 Ollama
  4. API 地址填 http://localhost:11434/v1
  5. API 协议选 openai-completions
  6. API 密钥随便填一个占位(本地服务通常不校验)
  7. 点获取可用模型,或手动添加模型 ID qwen2.5:7b
  8. 点创建提供商

之后就能在主界面的模型选择器里看到本地 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 在哪个地盘干活。

发现错误?提交反馈 · 欢迎 提 PR 改进本书