「我刚在网关后台看到的新模型,怎么没出现在 DSH 的模型列表里?是不是版本太旧了?」 这个疑问很合理,但它默认了「模型列表就是端点实时返回的清单」。在 DSH 中,这种理解只对了一半:要看你使用的是哪种提供商配置。
先厘清三种配置路径,后面的现象就容易对应起来:DeepSeek 卡片、内置第三方提供商,以及自定义模型 API。
排查时常见的六类误判:
- 把已安装目录当作端点实时探测;
- 把探测成功等同于模型可用;
- 把凭据检测提示当成认证已通过;
- 把本地声明的能力当成上游真实支持;
- 以为修改模型设置和修改代理环境变量是一回事;
- 把新会话的默认值当成旧会话也已切换模型。
先记住这句话:模型列表回答的是「有哪些」,不回答「能不能用」。 站内基础版可参考 配置模型提供商。
一、三个路径,三种信息来源
DeepSeek 卡片
模型配置指南说明,先在设置 → 模型中填写 DeepSeek 卡片。模型修改从下一次请求开始生效,无需重启服务器。这个「不重启」的特性值得记住,后面会和代理配置形成对照。
已保存的密钥在界面中是只写的:页面接收的是脱敏描述符,而不是明文。指南说明,凭据保存在 $DSH_HOME/.credentials.yaml,settings 中只保留凭据引用。因此,「浏览器里看不到密钥」是设计如此,并不表示密钥没有保存。
内置第三方提供商
选择添加模型提供商,再选一个提供商 ID(指南举例 anthropic、openai、moonshotai、zai),并按需保存凭据。端点、协议和模型列表都由已安装目录提供。
这里容易踩坑:凭据指示只表示检测到了凭据,不会验证密钥,也不会测试连接。留空时,在支持的情况下,可能会使用已保存的凭据或环境变量作为后备。
自定义模型 API
公司网关、中转服务、自建服务,或已安装目录中没有的提供商,都可以走这条路径。需要填写:小写 Provider ID、基础 URL、API 协议、凭据,以及至少一个模型。
协议必须与端点匹配。文档列出了 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三种协议。一个提供商只能使用一种协议;如果网关同时提供两种协议,而你都要用,就需要创建两个提供商。
| 配置路径 | 模型信息来源 | 首先核对什么 |
|---|---|---|
| DeepSeek 卡片 | DeepSeek 适配器配置 | 密钥是否已保存、模型是否选对 |
| 内置第三方提供商 | 已安装目录 | 提供商 ID 与凭据来源 |
| 自定义模型 API | 端点探测或手动模型 ID | 基础 URL、协议和端点实际能力 |
还有一点容易忽略:自定义 Provider ID 是永久标识。请求、已保存的会话、默认值和凭据引用都会使用它。要更改名称,正确做法是新建提供商并删除旧的,而不是修改 ID。显示名称和 ID 不能互换。
二、为什么模型列表看起来过时
指南对此说得很直接:内置提供商的模型探测结果来自已安装目录,即使 API 地址指向网关也是如此。
也就是说,把内置提供商的地址改为自己的网关后,模型列表不会自动变成网关的实时清单;列表仍然来自随安装包提供的目录。
社区中确实有相关反馈:讨论 #6307 中有用户报告 OpenRouter 模型缺失;讨论 #7660 则提议更新目录依赖并调整发现逻辑。这两条属于社区反馈与提议,并非官方结论:它们不能证明每个构建的实际情况,也不能证明提议中的补丁已经发布。
因此,要查询网关实际提供的模型,正确做法是使用自定义提供商进行探测,而不是期待内置目录及时更新。
探测能做什么、不能做什么
自定义提供商的获取可用模型功能会使用表单当前填写的地址、协议和密钥请求端点;对于已保存的提供商,则可以使用已保存的密钥。
有两个限制:选中所需项目并添加后,只有保存或创建提供商,信息才会真正存储;探测支持常见响应格式,但并未覆盖所有端点。如果探测失败或列表为空,可根据服务提供方的文档手动填写一个有效的模型 ID。
三、探测成功不等于模型可用
这是本文最想强调的一点。
列表中出现某个模型,或手动输入一个 ID,都不保证端点支持相应的上下文窗口、图片输入或推理行为。指南明确指出,配置中的能力是使用者作出的声明。
换句话说,模型设置中的上下文窗口、最大输出 token、输入类型等字段,影响的是集成侧如何处理模型,而不是上游服务。填入一个数字或勾选图片输入,不会让网关开始接受图片。
因此,修改容量或输入类型前,应先查阅提供方文档;保存后,再用一个小型代表性请求测试实际需要的能力。
模型探测 vs 真实请求
把探测结果当作初步列表,而不是最终验证。使用自定义提供商时,可以按以下顺序操作:
- 先确认地址和协议指向同一个服务;
- 使用当前表单中的值获取模型列表;
- 成功 → 添加目标模型并保存;失败 → 对照端点文档手动填写一个有效 ID;
- 两种情况下,都要选择已保存的模型并发送最小请求。
还有一步很关键:记录错误发生在探测、保存、选择还是生成阶段。 这四个阶段的失败原因各不相同,混在一起排查就无法获得有效信息。
四、凭据和网络要分开查
检测提示不验证凭据
页面提示检测到凭据环境变量时,指南说明,这并不代表凭据已经验证。先确认选对了提供商,再在不公开密钥的前提下确认服务是否接受该密钥。对于自定义端点,还要核对 URL 和协议。
有句话容易踩坑:一家服务的有效凭据,不一定适用于另一家端点。
代理作用在启动环境上
网络代理指南说明,DSH 会在启动时读取标准代理环境变量,用于自身的出站请求;指南还列出了保持直连的例外,例如回环地址、部分模型编写代码的路径等。
这里必须区分两件事:修改启动环境变量需要重启,而保存模型设置会从下一次请求开始生效。 别把「设置已保存」当成「代理已经生效」。
此外,一次出站请求的代理测试成功,不能证明所有进程和目标都经过同一路由。 例外列表正是为此而列出的。
怎样确认测试用的就是目标模型
测试前,记下提供商 ID 和选择器中选定的模型,再确认观察到的结果属于目标会话。
指南说明,已经发送过请求的会话会保留日志中记录的模型。因此,新会话的默认值变了,不代表旧会话也切换到了新模型。用旧会话测试,测到的可能并不是你原本要测的模型。
五、限制与安全边界
代理 URL 中可能包含凭据,而代理指南提醒,DSH 运行的命令会继承这些环境变量。因此,不要把密码写进可能被工具读取或留在命令输出中的代理 URL。
不要通过关闭证书校验走捷径,应按指南配置组织的 CA。
模型设置无需重启即可生效,这在安全上也有影响:发送敏感内容前,先确认当前选中的提供商和模型。
最后还要记住:检测提示不测试凭据,模型列表探测成功也不能证明生成请求或图片输入成功。 排查时,应把凭据、网络、协议、模型 ID 和能力分别验证;分享日志前,先检查其中是否包含敏感信息。
六、术语速查
- 提供商:访问模型服务时使用的路由和认证配置。
- Provider ID:用于请求和保存配置的持久标识。
- 基础 URL:提供商配置中的 API 地址。
- 已安装目录:内置提供商集成随安装提供的模型和协议信息。
- 模型探测:向自定义端点请求模型列表;端点支持情况和响应格式可能有所不同。
相关阅读
本文依据 DeepSeek Harness 模型配置与网络代理指南,以及社区讨论 #6307、#7660 整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/configure-models-providers
插件与文档收录于:https://dsh-plugin.com/zh/blog