CH 06 · 配置模型与推理档位

全文字数4000 字预估耗时约 15 分钟前置CH 03 已跑通难度可照做

本章目标

把"用哪个模型、思考花多大力气"这两个旋钮配明白：先搞懂调用大模型要带哪三样东西（API Key / Base URL / Model ID），再看懂配置文件、改默认模型、调推理档位，最后学会接第三方大模型。

先搞懂三个概念：API Key / Base URL / Model ID

不管用什么工具调大模型，一次请求都要带三样东西——API Key（你是谁）、Base URL（去哪）、Model ID（用哪个模型）：

一次 LLM 请求的三个要素（示意）

逐个拆开讲：

API Key：一串 sk- 开头的密钥，是你在某个大模型平台的"身份证"。请求带上它，平台才知道你是谁、该给谁扣费。它等于密码，别泄露、别提交到 Git 仓库。顺带一提：sk- 前缀是 OpenAI 兼容生态的通行格式，DeepSeek、以及大量国产平台和自建网关都沿用这套格式。
Base URL：模型的"门牌号"，也就是 API 服务的端点地址。所有请求都发到这个地址上。
Model ID：模型的名字，精确到用哪一款。请求里写 deepseek-v4-flash-vision-exp 就用视觉版，写 deepseek-v4-pro 就用旗舰。

这三个值都来自模型平台本身，不是 dsh 发明的。以 DeepSeek 为例，怎么拿：

API Key：打开 DeepSeek 开放平台，注册登录后进控制台 → API Keys → 创建 API key，命名后点创建，立刻复制保存——密钥只在创建那一刻完整显示一次，之后页面只剩脱敏描述符。
Base URL：DeepSeek 官方文档写得很清楚，OpenAI 兼容接口是 https://api.deepseek.com（用 Anthropic 兼容接口则是 https://api.deepseek.com/anthropic）。
Model ID：在官方 API 文档的模型列表里查，就是你前面在模型选择器里看到的那几个（deepseek-v4-pro / deepseek-v4-flash / deepseek-v4-flash-vision-exp）。

后面接第三方模型时你会发现，同样是这三样东西，只是数值换成别人的。

配置文件在哪：$DSH_HOME/settings.yaml

dsh 的全局配置就一个文件：C:\Users\<你的用户名>\.dsh\settings.yaml。我的机器上长这样：

yaml

ui-onboarding:
  welcomeNoticeVersion: 2026-08-13.1
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash-vision-exp
  reasoningEffort: high

这个文件就是你在 Web UI 里改模型、改推理档位的落点——界面改完，最终都会写到这里。三个字段各管一件事：

字段	作用	我的值
`provider`	用哪个提供方路由	`deepseek-official`（DeepSeek 官方）
`model`	新会话默认用哪个模型	`deepseek-v4-flash-vision-exp`
`reasoningEffort`	默认推理档位	`high`

三个模型怎么选

DeepSeek 官方适配器默认公布三个模型，每个都是 100 万 token 上下文窗口：

模型 ID	定位
`deepseek-v4-pro`	旗舰，复杂、质量关键的任务，能力更强、也更贵
`deepseek-v4-flash`	快速、经济，日常任务用
`deepseek-v4-flash-vision-exp`	视觉版：能读图、看截图，纯文本能力与 flash 持平

一个细节：模型 ID 会原样传到协议，所以官方以后上新模型，你不需要重新注册，直接在配置里填新 ID 就能用。

推理档位：off / low / high / max

推理档位决定模型在动手前"思考"花多大力气。DeepSeek 官方有四个档位。实际在 Web UI 里，点输入框右侧的模型按钮，就能看到并切换这四个档位（本机实测，High 是默认勾选）：

推理档位选择（本机实测）

DeepSeek 推理档位（示意）

档位	行为
`off`	关闭思考（`thinking: disabled`），最快最省
`low`	轻量思考
`high`（默认）	深度推理，Agent 任务合适
`max`	最高思考强度，最难的活才用

官方默认就是 high。档位会直接影响耗时和费用：开思考的档位慢一点、贵一点，但复杂任务更稳；off 不思考，简单问答秒回。挑档位就一个原则——任务越难，档位越高。

怎么改：Web UI 还是手改文件

两种改法，最终都落进 settings.yaml：

Web UI：设置 → 模型，可以存密钥、看已配置模型、加提供方。模型选择器里选的模型会成为新会话的默认；已经发过请求的会话会保留它开始时的模型，不会跟着默认变。

设置 → 模型（本机实测）

手改文件：直接改 agent-default-model 的三个字段，或加 llm-deepseek: 分节覆盖更多字段（后面接自定义提供方时会用到）。

生效规则：改完下一次请求就生效，不用重启服务。

配置第三方大模型

前面讲的是 DeepSeek 官方一家。这里正好体现 dsh 的一个鲜明特色：模型随便接，不锁死在自家模型上。官方适配器只是默认带 DeepSeek，你完全可以接 Anthropic、OpenAI、任何 OpenAI 兼容网关、甚至本地模型——相比之下，Codex 这类产品被限制在固定模型集合里，想换一家得等官方放开。在 dsh 里接第三方，就是下面这两条路。

方式一：添加提供方（接现成目录）

设置 → 模型 页面有添加提供方入口，里面是官方预置好的一批"目录"——选 Anthropic、OpenAI 这类现成目录，端点、协议都已经配好。添加后跟着表单三步走：

添加提供方并配置（本机实测）

选提供方：点"提供方"下拉，选中你要接的提供商（比如 minimax-cn）。
填 API 密钥：把这家平台给你的 Key 粘进"API 密钥"框——掩码显示，只写不读。
获取可用模型：点"获取可用模型"，把它的模型目录拉下来，模型列表里就能选它的模型 ID 了。

保存后，这个提供方的模型就出现在模型选择器里，正常选用即可。

方式二：添加自定义提供方（接自己的网关 / 本地模型）

如果 dsh 没预置你用的平台，用添加自定义提供方。要填的东西，正好就是本章开头那三样再加一个：

要填的	对应什么	示例
Provider ID	给这个提供方起个唯一 ID（小写，建好后永久生效）	`my-gateway`
API 地址	就是 Base URL，模型服务的门牌号	`https://你的网关地址`
API 协议	用什么格式对话（OpenAI / Anthropic 兼容等）	`openai-completions`
密钥	就是 API Key，认证凭证	`sk-...`
模型	至少填一个 Model ID	`deepseek-v4-flash`

填完保存，这个自定义提供方就出现在模型列表里，可以正常选用了。几个注意点：

Provider ID 一旦建好就是永久 ID，别随意改，后面配置里都靠它引用。
接本地模型 / 自建网关时，把 API 地址指向你自己的服务、密钥填本地服务的密钥（或按它的要求留占位）即可。
如果自定义的模型是视觉模型（要收图片），光填 Model ID 不够——官方要求额外声明它支持图片输入，在 settings.yaml 里给该提供方加一行 input: [text, image]，否则图片会被当作无效输入拒绝。

密钥与凭据

填 Key 的卡片（CH 03 填过）背后有两个机制：

密钥是只写的：设置 → 模型 里保存后，页面只显示脱敏描述符，明文只落在 C:\Users\<你的用户名>\.dsh\.credentials.yaml，settings.yaml 里只存凭据引用，不存明文。
解析顺序：请求时先走凭据存储，再回退到环境变量（默认 DEEPSEEK_API_KEY）。两个地方都没有就报 MISSING_CREDENTIAL。

排错速查

配置相关的报错就那几个，对号入座：

报错	意思	处理
`MISSING_CREDENTIAL`	没配密钥	去模型页存密钥，或配好环境变量
`INVALID_CREDENTIAL`	密钥格式不对	检查你填的 Key
`UNKNOWN_MODEL`	模型不存在或没配置	选一个已配置的模型
`UNSUPPORTED_REASONING_EFFORT`	推理档位不支持	用 `off` / `low` / `high` / `max` 之一
获取可用模型返回 401	密钥不对	检查密钥；模型发现会调 OpenAI 兼容的 `GET /models` 接口

这一章你学到了什么

能自己完成下面几条，就算过关：

[ ] 能说清 API Key / Base URL / Model ID 三个概念，以及在哪里能拿到这三样东西（以 DeepSeek 为例）
[ ] 能说出 settings.yaml 的位置和 agent-default-model 三个字段的含义
[ ] 能说出 DeepSeek 三个模型 ID 各自的定位
[ ] 能说出推理档位四个值（off / low / high / max）和默认值，以及选档位的原则
[ ] 知道改模型/档位后下一次请求就生效、不用重启
[ ] 知道接第三方模型的两条路：添加提供方（现成目录，填它的 Key、用它的模型 ID）vs 添加自定义提供方（Provider ID / API 地址 / 协议 / 密钥 / 模型）
[ ] 知道密钥存哪、settings 里为什么不存明文
[ ] 能对照排错表定位 MISSING_CREDENTIAL、UNKNOWN_MODEL 这类报错

CH 06 · 配置模型与推理档位 ​

本章目标 ​

先搞懂三个概念：API Key / Base URL / Model ID ​

配置文件在哪：$DSH_HOME/settings.yaml ​

三个模型怎么选 ​

推理档位：off / low / high / max ​

怎么改：Web UI 还是手改文件 ​

配置第三方大模型 ​

方式一：添加提供方（接现成目录） ​

方式二：添加自定义提供方（接自己的网关 / 本地模型） ​

密钥与凭据 ​

排错速查 ​

这一章你学到了什么 ​