DSH 添加模型：协议、地址、密钥与模型 ID

信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。

1. 核心概念：配一个模型只需要搞清"四件套"

不管是 dsh、Grok Build、Cursor 还是各种客户端，添加模型本质上都在填这四项：

四件套	通俗解释	常见取值
协议	请求和响应的"格式方言"	OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini 原生
Base URL	服务地址	例：`https://api.deepseek.com`
API Key	你的密钥	在各家开放平台申请
Model ID	模型的精确名字（大小写、横杠都要一致）	例：`deepseek-v4-pro`

【有据可查】dsh 的自定义模型表单正好就是这几项：Provider ID、Base URL、API 协议（三选一：openai-completions / openai-responses / anthropic-messages）、凭据、至少一个模型。来源：dsh 模型配置指南

2. 常见对应关系速查表

⚠️ Base URL 与模型 ID 变化很快。下表仅作"去哪里查"的索引，填写前务必打开对应官方文档核对。

厂商	常用协议	Base URL（以官方文档为准）	官方文档	层级
DeepSeek	OpenAI 兼容（另支持 Anthropic 格式，详见官方）	`https://api.deepseek.com`	https://api-docs.deepseek.com/	有据可查
OpenAI	Chat Completions / Responses	`https://api.openai.com/v1`	https://platform.openai.com/docs	有据可查
Anthropic	Messages	`https://api.anthropic.com`	https://platform.claude.com/docs	有据可查
Google Gemini	原生；也有 OpenAI 兼容层	`https://generativelanguage.googleapis.com/v1beta/openai/`（兼容层）	https://ai.google.dev/gemini-api/docs/openai	有据可查
xAI	OpenAI 兼容	`https://api.x.ai/v1`	https://docs.x.ai/	有据可查
月之暗面 Kimi	OpenAI 兼容	`https://api.moonshot.cn/v1`	https://platform.moonshot.cn/docs	有据可查
智谱 GLM	OpenAI 兼容	国内站 `https://open.bigmodel.cn/api/paas/v4`；国际站 `https://api.z.ai/api/paas/v4`；GLM Coding Plan 专用 `https://api.z.ai/api/coding/paas/v4`（Anthropic 兼容 `https://api.z.ai/api/anthropic`）——套餐与普通 API 端点不能混用（2026-10 修订，见ZCode 使用：连接模型、执行模式与目标任务）	https://docs.bigmodel.cn/、https://docs.z.ai/	有据可查
阿里通义（百炼）	OpenAI 兼容模式	`https://dashscope.aliyuncs.com/compatible-mode/v1`	https://help.aliyun.com/zh/model-studio/	有据可查
中转/聚合网关	通常 OpenAI 兼容	由网关提供	见magpie、New API 与 Cockpit Tools：三类工具的区别	视网关而定

2.1 一个时效性的真实例子：DeepSeek 模型名变更

【有据可查（检索于 2026-10-13）】据 DeepSeek 官方文档与更新日志，当前推荐使用 deepseek-flash 与 deepseek-v4-pro；旧名 deepseek-chat、deepseek-reasoner 已于 2026-07-24 退役，deepseek-v4-flash 为已退役的兼容别名。

来源：Models & Pricing、Change Log

这个例子说明：网上旧教程里的模型名可能已经失效。这正是本篇第 3 节"自己查"的意义。

2.2 同一模型在不同工具里的"名字"可能不同【社区共识】

场景	你可能看到的写法
官方 API	`deepseek-v4-pro`
聚合网关	`deepseek/deepseek-v4-pro`、`provider/model` 形式（如 magpie 示例中的 `provider/model`）
客户端内置目录	显示名"DeepSeek V4 Pro"，背后仍是某个 ID

原则：显示名给人看，Model ID 给机器看，填的永远是 ID。

3. 陌生模型：四步自查法

3.1 第①步：官方文档

关键词：<厂商名> API models、<厂商名> pricing、changelog。重点记录：

模型 ID（精确拼写）
上下文窗口、最大输出 token
是否支持图片输入、工具调用、推理（reasoning/thinking）参数
是否有退役计划

3.2 第②步：模型卡

开源/开放权重模型通常在 Hugging Face 有模型卡（https://huggingface.co/），会写明架构、上下文、推荐参数、许可证。注意：模型卡上的名字是"权重仓库名"，不一定等于某个 API 服务商的 Model ID。【社区共识】

3.3 第③步：直接问接口要列表【有据可查】

大多数 OpenAI 兼容服务提供 GET /models：

# DeepSeek 官方示例（https://api-docs.deepseek.com/api/list-models）
curl https://api.deepseek.com/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

返回的 data[].id 就是可用 ID。
dsh 的 Fetch available models 按钮做的就是这件事；官方文档也提醒：并非所有端点都支持，失败时手动填写 ID 一样能用。【有据可查】

3.4 第④步：实在不知道，就问 AI

这是实践建议：不要硬扛，直接问。但要会问：

我想在 <工具名> 里添加模型 <模型名>。
我查到的信息：<粘贴官方文档片段或 /models 返回结果>
请告诉我：
1. 应该选哪种 API 协议？
2. Base URL 和 Model ID 应该填什么？
3. 有哪些常见兼容性坑（如 developer role、max_tokens 字段、推理参数）？
4. 请给出一条最小 curl 测试命令，我自己验证。
请明确标出哪些是你确定的、哪些是你推测的。

⚠️ AI 也会"编"模型名和 URL（幻觉）。问 AI 的结果必须用一次真实请求验证，不要直接写进生产配置。【社区共识】

4. 最小验证：一条 curl 定生死

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODEL_ID>","messages":[{"role":"user","content":"只回复 OK"}]}'

结果	含义
200 + 正常回复	四件套正确
401 / 403	Key 错、无权限或地区/账户受限
404	URL 路径错（常见：多写或少写 `/v1`）
400 + "model not found"	Model ID 拼错或已退役
400 + 参数错误	协议方言不兼容（见下一节）

5. 兼容性坑：明明 Key 和 URL 都对，就是报错

【有据可查】dsh 官方文档总结的两大常见原因：

推理模型的 system prompt 被以 role: "developer" 发送，很多网关不认 → 设 compat.supportsDeveloperRole: false
输出上限字段用了 max_completion_tokens，有的服务只认 max_tokens → 设 compat.maxTokensField: max_tokens
通过 OpenAI 兼容网关使用 DeepSeek V4 这类"默认会思考"的模型时，需 compat.thinkingFormat: deepseek 才能正确关闭思考。

# $DSH_HOME/profiles/web/cordis.patch.yml 片段（官方文档示例改写）
- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY     # 环境变量名，不是 Key 本身
        api: openai-completions
        baseURL: https://gateway.example/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: my-model
          - id: vision-model
            input: [text, image]       # 声明支持图片

【社区共识】这类问题在几乎所有"兼容 OpenAI"的客户端里都会遇到，只是开关名字不同。

6. 本篇无法核实/需谨慎的点

表中各厂商 Base URL 为依据官方文档整理，可能已有区域版、新版本路径（如国际站/国内站不同域名），请以官方为准。
未列出各家具体模型 ID（除 DeepSeek 示例外），因为变化过快。
其它工具（Cursor、Grok Build 等）的自定义模型字段名与 dsh 不同，本文未逐一核对。

小白练习：把本文流程逐项走通

练习目标：把四个配置字段分别填对，并验证一次最小请求。

上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。

先确认手上的凭据属于普通 API、Coding Plan，还是网页登录。只有当前接入方式支持的凭据才能填入相应字段。
打开该凭据所属平台的接口文档，分别抄下协议、Base URL、Model ID。不要从显示名称猜模型 ID。
在 DSH 的模型设置中先选择提供方或新建自定义提供方，再填写 Base URL，然后保存 API Key，最后添加模型 ID。
保存后选择新模型，单独发送只回复 OK 的请求。能返回文字才说明基本连通；继续用一个小文件检查工具调用。
原文 curl 示例是 Bash 语法。Windows PowerShell 用户可先用工具内的连接测试；需要命令行时使用 curl.exe，并按 PowerShell 的引号规则改写。
若请求失败，按 401、404、模型不存在和参数不兼容分别查对应字段。先保留原配置，再一次只调整一个字段。

继续浏览知己录返回顶部 ↑