模型 Provider 配置

Provider 是什么

dsh 自己不带模型。它只负责把「对话、工具、记忆」组织好，真正生成文字的活儿交给大模型厂商。这个「接谁家的模型」的环节，官方叫 Provider（提供方）。

你可以把 Provider 想成电源插座：

• 插头是 LLM 适配器（adapter），它负责把 dsh 的请求翻译成某家厂商的 API 格式；
• 插座孔是 provider route，一个带名字的注册路由，比如 deepseek、anthropic；
• 每个请求都带着 provider + model 两个字段，dsh 按 provider 找到适配器，再把 model 交给它。

这套机制由 ctx.llm 服务统一管理。dsh 内置了两个参考适配器：DeepSeek 官方适配器 llm-deepseek（OpenAI 兼容格式）和 llm-pi-ai（封装 pi-ai LLM 库，API 格式与目录语义都不同）。第三方模型怎么接，本质都是「注册一个 provider 路由 + 填凭据 + 声明模型」；适配器怎么写，第 25 章展开。

配置 DeepSeek 官方模型

DeepSeek 是默认最快上手的路线。前提是你先有 API 密钥，到 platform.deepseek.com 申请。

接入步骤：

1. 启动 dsh：npx @deepseek-ai/dsh web，浏览器打开 http://127.0.0.1:3080。
2. 打开 设置 → 模型。
3. 在 DeepSeek 卡片上找到 API 密钥输入框，粘贴密钥并保存。

模型变更会在下一次请求时生效，不需要重启服务器。

密钥是只写的。保存后页面只会收到脱敏描述符，永远看不到明文。密钥实际存在 $DSH_HOME/.credentials.yaml 里，settings 只保留一个凭据引用（credential reference），不碰密钥本身。这个设计的细节，第 17 章讲凭据管理时再展开。

目录提供方：已收录的厂商

如果你用的是 Anthropic、OpenAI 这类主流厂商，不需要手填端点。

操作：选择添加提供方，从列表里挑一家，输入它的 API 密钥并保存。

已安装目录会自动带来端点、协议和模型列表，你只管填密钥。但要注意：使用原生认证的提供方，只填 API 密钥字段是配不完的。官方文档点名了几家：

提供方	需要的原生凭据
Bedrock	AWS 凭据与区域
Vertex	ADC 项目
Azure	api-version
Codex	OAuth

自定义提供方：接入任意网关

公司网关、自建服务器，或者目录里没有的厂商，走添加自定义提供方。表单要填这些字段：

字段	说明	必填
Provider ID	小写字母，永久标识	是
显示名称	界面里显示的名字	否
基础 URL	端点地址，如 https://gateway.example/v1	是
API 协议	如 openai-completions	是
凭据	API 密钥，或环境变量引用	是
模型	至少一个模型 id	是

Provider ID 是永久的。请求、已保存会话、模型默认值和凭据引用都会用到它。想重命名？没有改名入口——正确做法是新建一个提供方，再删掉旧的。显示名称、基础 URL、协议、凭据和模型则随时可编辑。

填完表单，可以在模型目录里点获取可用模型，让 dsh 查询表单当前的基础 URL 和凭据。这个查询只更新草稿，保存前不会真的存储提供方。

用 settings.yaml 直接配置

表单背后是 $DSH_HOME/settings.yaml。它是用户设置文档，按 namespace 分节；模型路由归 llm-pi-ai 这个 namespace 管。下面是一份完整可复制的自定义提供方配置：

# 文件路径：$DSH_HOME/settings.yaml
llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY   # 凭据引用：从环境变量 GATEWAY_API_KEY 读取
      api: openai-completions      # API 协议
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat          # 纯文本模型，不写 input 即按纯文本对待
        - id: vision-preview       # 视觉模型
          input: [text, image]     # 声明同时接受文本与图片

input 只接受 text 和 image 两个值，且只作用于它所在的模型，所以一条路由可以同时服务文本和视觉两类模型。

还有两个容易混淆的字段：

• defaultInput：路由级回退值，默认为 [text]。只对目录未描述的模型生效，绝不会去掉目录中本就支持图片的模型的能力。
• modelOverrides：目录提供方没有 models 列表可填，收窄某个模型的能力要写在它下面，以模型 id 为键：

llm-pi-ai:
  providers:
    anthropic:
      modelOverrides:
        claude-sonnet-4-5:
          input: [text]    # 把该模型的图片能力去掉

选择模型与默认模型

配好提供方后，模型选择器里就能看到它们。两个行为值得记住：

• 选择某个模型，会同时把它设为新会话的默认值；
• 已发送过请求的会话，会保留自身日志中记录的模型，不受后续切换影响。

有个坑：如果已保存的默认值指向了被删除的提供方，输入框会显示选择模型，并且在选中新模型前阻止输入。遇到这种情况，重新选一个模型即可。

常见排错

官方文档给了五条高频错误，直接对表查：

错误	含义	解决
MISSING_CREDENTIAL	缺少提供方密钥	在模型页存储密钥，或提供被引用的环境变量
UNKNOWN_MODEL	请求的模型没配置	选已配置的模型，或给自定义提供方补上缺失的模型
获取可用模型返回 401	密钥无效，或端点不支持发现	检查密钥；不支持 GET /models 的端点请手动输入模型
图片在发送前被拒绝	模型未声明图片模态	给自定义提供方的模型加 input: [text, image]；DeepSeek 官方路由是纯文本的，无法通过配置改变
提供方拒绝带图片的请求	模型声明了端点没有的能力	从授予图片能力的列表移除 image，然后开启新会话

最后一条要解释一下：附带的图片会留在会话日志里，不换新会话的话，同一个请求会反复失败。

小结

• Provider 是「插座」，适配器是「插头」，请求按 provider 路由。
• DeepSeek 官方：设置 → 模型 → 填密钥，密钥只写、存 $DSH_HOME/.credentials.yaml。
• 目录提供方免填端点；原生认证的厂商要各自的原生凭据。
• 自定义提供方：Provider ID 永久，模型至少一个，视觉模型要声明 input。
• 排错先看错误码：MISSING_CREDENTIAL、UNKNOWN_MODEL、401。