dshseek
English

seek://guides/configure-models

在 DSH 中配置模型与提供方

2026年8月28日Intermediate← 全部教程

TL;DR

DSH 如何决定由哪个模型回答：模型页把 DeepSeek 密钥以只写方式存进凭据库，目录提供方直接继承已安装目录的端点与模型列表，自定义提供方经一个永久 Provider ID 接入任何 OpenAI 兼容网关——外加一行图片输入声明，和一个解决大多数网关兼容问题的 compat 块。

要点

  • 按官方提供方指南，密钥是只写的：保存后页面只收到脱敏描述符，真实密钥存在 $DSH_HOME/.credentials.yaml，settings 只保留凭据引用
  • 目录提供方（添加提供方）的端点、协议与模型列表来自已安装目录；原生认证的提供方（Bedrock、Vertex、Azure、Codex）需要各自的原生凭据——只填 API 密钥无法完成配置
  • 自定义提供方（添加自定义提供方）需要小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型；Provider ID 永久——改名意味着新增一个提供方并删除旧的
  • 手动输入的模型在自己声明之前一律按纯文本对待：在 $DSH_HOME/settings.yaml 里给它加 input: [text, image]，或在路由上设 defaultInput 回退
  • 按官方指南，大多数网关故障来自两处请求形状差异——在路由上设 compat.supportsDeveloperRole: false 与 compat.maxTokensField: max_tokens 即可修复
  • 模型变更在下一次请求时生效，无需重启服务器；已发送过请求的会话保留自身日志中记录的模型
  • 官方指南的排错表把常见故障——MISSING_CREDENTIAL、UNKNOWN_MODEL、模型发现 401、图片拒绝——逐一映射到修法

模型是你配置的第一样东西，也是 DSH 把可替换性做得最彻底的一样：无论密钥属于 DeepSeek、某个目录提供方还是自建网关，会话机制照常工作。本篇导读官方提供方指南（docs/user/guide/providers.md，写作时抓取），并补上每一步背后的原因。

DeepSeek：一个密钥字段

打开设置 → 模型。DeepSeek 卡片只暴露一个 API 密钥字段，输入并保存。官方指南里值得记住两点：

  • **密钥是只写的。**保存后页面收到的是脱敏描述符，永远不是明文。
  • **存储按设计分离。**密钥存在 $DSH_HOME/.credentials.yaml；settings 只保留它的凭据引用。

目录提供方：最快路径

选择添加提供方，从已安装目录里挑——Anthropic、OpenAI 等。目录直接提供端点、协议和模型列表，你只需要输入密钥。官方指南点名的例外：带原生认证的提供方——Bedrock（AWS 凭据 + 区域）、Vertex（ADC 项目）、Azure（api-version）、Codex（OAuth）——需要各自的原生凭据；只填 API 密钥字段无法完成配置。

自定义提供方：任何 OpenAI 兼容网关

公司网关、自建服务器、目录里没有的服务，选添加自定义提供方。表单要小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。

两个表单行为值得注意：

  • Provider ID 永久——请求、已保存会话、模型默认值、凭据引用全都用它。改名 = 新增加旧。
  • 获取可用模型查询的是表单当前的基础 URL 和凭据；选候选项只更新草稿，保存前不会存储任何东西。

图片输入：一行声明

手动输入的模型在自己声明之前一律按纯文本对待——没有任何环节能去询问端点接受哪些模态，所以附图在发送前就会被拒。修法是 $DSH_HOME/settings.yaml 里的一行（表单没有这个字段）：

llm-pi-ai:
  providers:
    my-gateway:
      models:
        - id: vision-preview
          input: [text, image]

input 只作用于该模型。如果路由上所有模型都收图，在路由上设一次 defaultInput: [text, image] 即可——它是回退不是覆盖，不会从目录里本来就有图片能力的模型身上拿走任何东西。

请求兼容性：修好大多数网关的两个开关

一个网关可以密钥可用、地址可达，却拒绝每一个请求。官方指南解释了原因：请求形状由端点 URL 决定，认不出的地址会被当成 OpenAI 本身——而大多数 OpenAI 兼容网关至少拒绝一件 OpenAI 接受的事。两处差异占了绝大多数：

  1. 推理模型的系统提示词以 role: "developer" 发出——很多网关直接拒绝这个角色。
  2. 输出上限以 max_completion_tokens 发出——只认识 max_tokens 的服务器会拒绝。

表单里都没有对应字段，在路由上修正：

llm-pi-ai:
  providers:
    my-gateway:
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens

路由上的 compat 是其模型的默认值；模型自身的 compat 逐字段胜出。这两个字段是对你的端点陈述一个断言，而不是检查它——写下的每个开关都要有值，因为空键会被拒绝而不是被忽略。

模型选择的语义

配置好的提供方出现在模型选择器里；选择一个模型同时会把它设为新会话的默认值。已发送过请求的会话保留自身日志里记录的模型——所以改默认值不会改写历史。如果保存的默认值指向已删除的提供方，输入框会显示选择模型并阻止输入，直到选了别的模型。

排错，一行一条

官方指南的排错表浓缩版：

  • MISSING_CREDENTIAL → 经模型页存密钥，或提供引用的环境变量
  • UNKNOWN_MODEL → 选已配置的模型，或补上缺失模型
  • 模型发现 401 → 查密钥；没有 GET /models 的端点手动输模型
  • 密钥地址都对网关却全拒 → 上面两个 compat 开关
  • 只有推理模型失败 → compat.supportsDeveloperRole: false
  • 图片发送前被拒 → 模型未声明图片模态；加 input: [text, image]
  • 提供方拒绝带图请求 → 声明的图片能力只是断言；移除 image 并开新会话

与站内其他位置的关系

官方参考