DeepSeek Harness 自定义模型 Provider ID 为什么不能改:三处在引用它
DeepSeek Harness 自定义模型 API 的 Provider ID 创建后不能改,不是界面限制,而是它被四类东西同时引用:请求、已保存会话、模型默认值和凭据引用。 官方说明:Provider ID 是永久的,因为这些位置都会使用它;显示名称、基础 URL、协议、凭据和模型仍可编辑(来源)。理解这一点,改名、迁移、双协议网关这些事就不会做错顺序。
DeepSeek Harness Provider ID 是永久键,不是显示名
Provider ID 是数据键,显示名称是标签,两者职责不同。 数据键一旦被引用,就不能随便变;标签只影响界面,改多少次都不影响请求。(来源)
很多人第一次配置自定义模型 API 时,会把 Provider ID 当成「名字」随便填,过几天想改成更规范的名字,结果发现改不了。这不是产品故意刁难,而是改名会让已有的请求、会话和凭据引用失去指向。
官方把可编辑与不可编辑的字段分得很清楚:显示名称、基础 URL、协议、凭据和模型可编辑,Provider ID 不可编辑。配置时先把 ID 想清楚,比事后迁移便宜得多。
一个实用建议:Provider ID 用小写、稳定、与端点归属相关的名字,例如公司网关名或服务名,不要用「test」「my-api」这类以后一定会想改的名字。
DeepSeek Harness 四类引用:请求、会话、默认值、凭据
Provider ID 被四类引用同时使用,这是它不能改的根本原因。 官方列出的四类是:请求、已保存会话、模型默认值、凭据引用(来源)。
逐类看它们的后果:
- 请求 — 每次模型请求都要按 Provider ID 找到对应的适配器和配置;ID 变了,旧请求路径就断了。
- 已保存会话 — 会话日志记录了当时使用的模型与提供商;ID 变了,旧会话可能找不到原提供商。
- 模型默认值 — 默认模型引用 Provider ID;ID 变了,默认值就悬空,输入框会被拦住。
- 凭据引用 — 凭据按 Provider ID 关联;ID 变了,原来保存的密钥可能不再被使用。
四类引用意味着改名不是一个字段的事,而是一次跨请求、跨会话、跨凭据的迁移。产品选择「不允许改名」,是用一个限制换四个位置的一致性。
DeepSeek Harness 想改名只能新建再删旧
改名的正确流程是「新建、迁移、删旧」,不是找一个隐藏的编辑按钮。 官方建议:如需重命名提供商,请添加新提供商并删除旧提供商(来源)。
推荐顺序如下:
- 新建提供商 — 用目标 ID 创建,填同样的基础 URL、协议、凭据和模型;
- 迁移默认值 — 把默认模型切到新提供商;
- 迁移会话 — 需要继续的会话改用新提供商的模型,或接受旧会话保留旧引用;
- 验证请求 — 用新提供商发一条最短任务;
- 删除旧提供商 — 确认没有默认值和会话还依赖它,再删除。
顺序不能反。先删旧再建新,会留下悬空默认值和无法继续的会话;先建新但没迁移默认值,输入框仍可能指向旧 ID。验证放在删除之前,是为了给自己留回退空间。
如果旧提供商只在一个测试会话里用过,迁移成本很低;如果它被多个会话和凭据引用,先把引用面列清楚,再动手。
DeepSeek Harness 四种 API 协议怎么选
协议不是「哪个新用哪个」,而是「网关实际说哪种就用哪种」。 官方提供四种:OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini API,配置里分别存为 openai-completions、openai-responses、anthropic-messages、google-generative-ai(来源)。
选择时看三个信号:
- 网关文档写的是什么协议 — 以文档为准,不要凭端点域名猜;
- 请求路径与字段长什么样 — Chat Completions 与 Responses 的字段不同,Anthropic 与 Gemini 也各有自己的格式;
- 网关是否同时提供两种 — 同时提供时,一个提供商只能选一种,另一种要另建提供商。
协议选错的典型症状是「密钥和地址都对,但每个请求都被拒绝」。这时不要反复换密钥,先确认协议是否匹配。不同协议对系统提示词、输出上限、思考字段的写法不同,网关可能只接受其中一种。
把四种协议和常见写法放在一起看:
| 协议 | 配置值 | 典型场景 |
|---|---|---|
| OpenAI Chat Completions | openai-completions | 大多数 OpenAI 兼容网关 |
| OpenAI Responses | openai-responses | 使用 Responses 形状的端点 |
| Anthropic Messages | anthropic-messages | Claude 风格网关 |
| Gemini API | google-generative-ai | Gemini 端点,URL 含版本 |
这张表只用于确认「配置值写哪个」,不用于判断端点支持什么。端点支持哪种,以网关文档和实际请求为准。
DeepSeek Harness 基础 URL 与协议必须配对
基础 URL 不是随便填一个能通的地址,它要和协议配对。 官方特别指出:Gemini API 的基础 URL 包含 API 版本,例如 https://gateway.example/v1beta(来源)。
配对规则可以记成三条:
- 协议决定路径形状 — 同一个网关,不同协议的路径和字段不同;
- Gemini 的 URL 带版本 — 不要只填到域名,版本段是地址的一部分;
- 一个提供商只用一个协议 — 双协议网关要建两个提供商,各自配对各自的 URL。
如果基础 URL 少了版本段、多了多余路径,或者与协议不匹配,表现通常是 404、400 或「每个请求都被拒绝」。这类错误看起来像密钥问题,实际是地址与协议没对上。
模型探测可以帮助确认端点提供哪些模型,但它只是便利手段,不是保证。探测失败或列表为空时,手动填写模型 ID 即可,效果一样(来源)。
DeepSeek Harness 验证:四处是否都指向新 ID
迁移或新建后,用四处核对确认没有旧 ID 残留。 四处正好对应前面说的四类引用(来源):
- 请求 — 用新提供商发一条最短任务,能返回;
- 默认值 — 模型选择器里的默认模型指向新提供商;
- 会话 — 需要继续的会话已切到新模型,旧会话的行为符合预期;
- 凭据 — 新提供商的凭据引用可用,删除旧提供商后请求仍成功。
四处都过,才算迁移完成。只验请求不验默认值,可能下次开新会话又回到旧 ID;只验默认值不验凭据,可能在删除旧提供商后才发现密钥没迁过来。
Provider ID 的规则讲完,模型列表什么时候刷新、换模型后旧会话为什么不变,可以接着看同批的另外两篇。自定义提供商的完整配置见《DeepSeek Harness 模型提供方怎么配》。
常见问题
因为 DeepSeek Harness 把 Provider ID 当作永久键:请求、已保存会话、模型默认值和凭据引用都会使用它。改名会让这些引用找不到原提供商,所以只能新建再删旧。
DeepSeek Harness 里,Provider ID 是永久标识,用于请求与会话引用;显示名称只是界面展示,可以修改。DeepSeek Harness 允许改显示名称、基础 URL、协议、凭据和模型,但不允许改 Provider ID。
DeepSeek Harness 支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini API 四种协议,在配置里分别存为 openai-completions、openai-responses、anthropic-messages 和 google-generative-ai。
DeepSeek Harness 里,要建两个。DeepSeek Harness 的一个提供商只使用一种协议,网关同时提供两种协议时需要分别建立提供商,并让基础 URL 与各自协议匹配。
相关术语
- Provider ID
- Provider ID 是 DeepSeek Harness 自定义模型提供商的永久标识,请求、已保存会话、模型默认值和凭据引用都会使用它,创建后不能改名。— DeepSeek Harness 官方文档 - 配置模型
- API 协议
- API 协议是 DeepSeek Harness 与模型网关通信时使用的请求格式,提供 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini API 四种选项。— DeepSeek Harness 官方文档 - 配置模型
- 基础 URL
- 基础 URL 是 DeepSeek Harness 发送模型请求的端点根地址,必须与所选 API 协议匹配;Gemini API 的地址还需要包含 API 版本。— DeepSeek Harness 官方文档 - 配置模型
- 模型探测
- 模型探测是 DeepSeek Harness 在自定义模型 API 里向端点询问可用模型的便利功能,失败或列表为空时可以手动填写模型 ID。— DeepSeek Harness 官方文档 - 配置模型
来源
- DeepSeek Harness 官方文档 - 配置模型· deepseek-harness
- DeepSeek Harness 官方文档 - 插件配置目录· deepseek-harness