QBuilder 中如何配置大语言模型
在「设置 → 提供商」填写 API Key,在「偏好」中选定默认模型,返回仪表盘输入 hi 完成联通测试。
为什么 QBuilder 需要预先配置 LLM?
QBuilder 采用 LLM 供应商中立 的策略 — 默认既不预置模型,也不代为支付 API 费用。用户需自行选择供应商(DeepSeek、Qwen、Kimi、MiniMax、OpenAI、Anthropic、Gemini、本地 Ollama、自部署网关等),并提供对应的 API Key。
该设计的优势包括:
- 成本可控:可基于定价与性能对比灵活选择供应商。
- 数据合规:支持接入自部署或本地中转,数据可不出网。
- 容灾切换:任一供应商不可用时可快速切换至备用供应商。
整体流程
配置过程分为四段:
- 第 0 步:进入设置页 — 点击左侧最下方的齿轮图标。
- 第 1 步:进入「提供商」页 — 在设置页中间菜单选择「提供商」。
- 第 2 步:填写 API Key — 展开目标供应商条目,填写 API Key 并保存。
- 第 3 步:设置默认模型 — 进入设置页「偏好」,刷新模型列表,选择默认模型,滚动至底部保存。
- 第 4 步:返回仪表盘,输入
hi验证联通。
第 0 步 · 进入设置页
登录后点击左侧最下方的齿轮图标
登录后默认进入 仪表盘(Dashboard),中央展示问候语、五个场景按钮及输入框。在此阶段不宜直接对话 — 未配置 Key 的情况下对话无法发起。
QBuilder 主界面左侧最下方有一 齿轮图标(Settings),为系统配置的入口。点击进入设置页。
第 1 步 · 选择「提供商」菜单
在设置页中间菜单中点击「提供商」
进入设置页后,左侧中间列出 设置的二级导航:
- 对话 / 外观 / 偏好 / 提供商 / 配置 / 扩展 / 系统 / 账户 / Help
点击 提供商,页面右侧将切换至 LLM 供应商列表。
提供商页面展示所有 QBuilder 内置支持的供应商,每个条目均包含:
- 供应商名称(如 DeepSeek、Qwen Cloud、MiniMax、Anthropic、Gemini、OpenAI 等)。
- 若已填写有效的 LLM KEY,会进一步列出 支持模型数(如 5 models、10 models)。
- 当前状态:未配置(尚未填写 Key)或 API 密钥已配置(已填写)。
第 2 步 · 配置单个供应商(以 DeepSeek 为例)
展开 DeepSeek 条目,填写 API Key 并保存
假设拟使用 DeepSeek 模型,且已获取相应 API Key(形如 sk-…)。下面将其接入 QBuilder:
2.1 展开 DeepSeek 条目
在提供商列表中找到 DeepSeek 一行,点击卡片本身(而非右侧的箭头图标),卡片将展开为输入区。
展开后可看到以下元素:
- API 密钥输入框(密码掩码,默认隐藏明文)。
- Show 按钮 — 在明文与掩码之间切换,便于确认输入是否正确。
- 保存 按钮 — 未填写 Key 时置灰,填写后方可点击。
- Models 区域:该供应商支持的全部模型,以标签形式列出(初始为 QBuilder 内置默认列表)。
- Refresh models 按钮 — 从供应商处拉取最新模型清单。
2.2 填写 Key
将 sk-... 密钥字符串粘贴至 API 密钥 输入框。输入框默认以密码掩码呈现,避免明文泄漏。
当右下角的 保存 按钮由灰色变为深黄色时,表明输入合法,可保存。
0 与 O、1 与 l。建议复制粘贴后,点击 Show 显示明文核对一次再保存。
2.3 点击「保存」
点击 保存。保存成功后,卡片右上角的状态由 未配置 变为 API 密钥已配置。此时 Key 已生效,所有依赖 DeepSeek 的对话均可立即使用。
第 2 步(进阶)· 通过 QAgent Custom 接入中转或自部署
LLM 中转站与自部署接口的接入方式
对于具有独立 Base URL 的 LLM 中转站,或 自行部署的 LLM 接口(Ollama、vLLM、OpenAI 兼容网关等),不属于 QBuilder 的标准供应商,但可通过 QAgent Custom 接入。
QAgent Custom 与普通供应商相比,多了一个 Base URL 字段 — 用于指定请求发送的目标地址。
2+.1 字段说明
- API 密钥:中转站或自部署网关的鉴权字符串(本地无鉴权时填任意非空字符串,如
ollama)。 - Base URL:中转站接入地址(如
https://your-proxy.example.com/v1),或自部署网关地址(如http://localhost:11434/v1即 Ollama)。
2+.2 常见场景配置示例
| 场景 | Base URL 示例 | Key 形态 |
|---|---|---|
| 自建 OpenAI 兼容网关 | https://gw.example.com/v1 | 中转站分配的字符串 |
| 本地 Ollama | http://localhost:11434/v1 | 任意非空字符串 |
| 本地 vLLM | http://localhost:8000/v1 | 任意非空字符串 |
| 三方聚合中转 | 中转站提供的 URL | 中转站分配的 sk-... 字符串 |
/v1 后缀 OpenAI 兼容接口的 chat completions 路径通常为 /v1/chat/completions,因此 Base URL 须包含 /v1 一层,QBuilder 将自动拼接后续路径。若仅填写 https://x.com 而不含 /v1,将导致 404 错误。
填写完 API 密钥 与 Base URL 后,分别点击各自右侧的 保存。保存成功同样会使状态由 未配置 变为 API 密钥已配置。
第 3 步 · 在「偏好」中设置默认模型
刷新模型列表、选择默认模型、滚动至底部保存
供应商 Key 配置完成后,对话即可正常使用。然而,每次开启新对话均需手动选择模型,操作繁琐。可在 QBuilder 中设置 默认模型,使新对话自动调用。
3.1 切换至「偏好」菜单
返回设置页中间菜单,选择 偏好(位于「提供商」上一行)。
偏好页顶部第一项即为 默认模型,其右侧有两个小图标:
- 刷新 icon(↻):从所有已配置 Key 的供应商处拉取模型清单,确保下拉框选项为最新。
- 高级选项 icon(齿轮):展开默认模型的温度、最大 token 等细粒度参数。
3.2 触发刷新
首先点击 刷新 icon。完成后页面右上角将出现「模型列表已刷新」提示。下拉框内容将自动重新加载,包含刚配置的供应商的全部模型。
3.3 选择默认模型
点击默认模型下拉框,从中选择目标模型。下拉框按供应商分组,示例:
- DeepSeek:deepseek-v4-flash / deepseek-v4-pro / deepseek-chat-v3-0324 / deepseek-reasoner / deepseek-flash
- Qwen Cloud:Qwen3.6 Plus / Qwen3 Omini Flash / Qwen Plus / Qwen3.7 Plus
- MiniMax (China):Minimax M3 / M2.7 / M2.5 / M2.1 / M2 / M3
点击具体模型,选中状态将回填至下拉框顶部。
3.4 滚动至底部,点击「保存设置」
选择默认模型后,不可直接关闭页面。需将偏好页 滚动至最底部,找到 保存设置 按钮 — 点击后,方才的选择才会真正落盘。
第 4 步 · 返回仪表盘,输入 hi 验证
发送测试消息,验证配置链路
至此配置完成,QBuilder 可正常使用。返回 仪表盘(左侧导航首项,九宫格图标),在中央输入框中发送一句测试消息,例如 hi:
按下发送键(回车),稍等 1–2 秒。若模型正常,将收到一段自然语言的问候回复。此即表示:
- 所选供应商的 API Key 有效,请求未被拒绝。
- 默认模型下拉框内的模型可被正常调用。
- 从「配置 Key → 选择默认模型 → 实际对话」的链路已贯通。
配置过程结束。
常见踩坑
- 配置 Key 后默认模型下拉框未出现:未在偏好页点击 刷新 icon,下拉框仍为缓存旧清单。点击刷新后新模型即可出现。
- 选择默认模型后跳转又被还原:未点击偏好页最底部的 保存设置。可使用顶部横条的「保存」按钮。
- 填写 Key 后持续 401 错误:复制粘贴时多带换行或空格,或遗漏
sk-前缀。点击输入框右侧的 Show 显示明文核对一次。 - QAgent Custom 接中转站出现 404:Base URL 未包含
/v1后缀,或网关地址缺失https://前缀。OpenAI 兼容接口的 chat completions 路径通常为/v1/chat/completions。 - 使用 MiniMax 国际版 Key 配置 MiniMax (China) 节点:国际版与中国版为两套独立账号体系,Key 不可互通。注意设置页右上角「当前提供商配额」显示的区域。