模型管理

模型管理决定小匠"用哪个大脑思考"。本章带你登记 LLM、做连通性测试、设默认、改 API key、并看每天调了多少次、出了多少错。仅 super_admin 可见。

5.1 入口与权限

模型管理只对超级管理员开放。普通 admin 看不到这个菜单——因为 API key 是钱、是合规边界，得收口。

1. 用 super_admin 账号登录 admin 后台（普通 admin 账号看不到入口）
2. 左侧菜单「能力配置」分组下点「模型管理」，地址 /admin/models
3. 没看到这个菜单？说明你的账号角色是 admin 不是 super_admin——去「系统 → 管理员」让 super_admin 提权，或直接换号
4. setup 向导第 2 步配的默认 DeepSeek 模型，也是从这里继续维护

注意： API key 等于花钱权限。别把 super_admin 账号给业务用户——一旦 key 泄漏，调用费用全是你的。

5.2 模型列表：按类型分页查看

列表页顶部用 tab 分类切换，每个 tab 后面带数量，能一眼看到当前挂了几个模型、每类各几个。

1. 页面顶部 tab 切换：全部 N / 已启用 N / 对话 N / 推理 N / 嵌入 N（按 code 关键字派生类型：含 embedding=嵌入、含 reasoner/o1/r1=推理、其余=对话）
2. 主区域是模型卡片网格，每张卡上看：code（大字）/ name（副标）/ base_url（描述行）/ 类型 + 密钥状态（meta 行）/ provider（左下角）/ 启禁开关 / 「默认」徽标
3. 顶部搜索框按 code、name 或 provider 模糊过滤，placeholder：「搜索模型 ID、提供商…」
4. 点卡片任意位置打开编辑弹窗；右上角主按钮文本为「添加模型」
5. 卡片右下角三件套：启禁开关 / 测试 API key 图标按钮 / 删除 图标按钮（默认模型的删除按钮禁用）
6. 卡片状态徽标四种：就绪（已启用且密钥可用）/ 停用 / 密钥失效（旧 master key 加密、需重填）/ 未配密钥；默认模型显示紫色「默认」chip 替代状态

5.3 添加模型

添加的核心是填对几个字段，然后用「测试连接」确认通了再保存。流程一致，区别只在 base_url 和 api_key 来源。

1. 右上角点「添加模型」，弹出 540px 宽的「添加模型」弹窗
2. 填 模型代号 (code)（必填，创建后置灰不可改，建议如 deepseek-chat / gpt-4o）
3. 填 显示名（必填，例如 DeepSeek Chat）
4. 选 提供商：DeepSeek / OpenAI / Anthropic / 自定义（前三者会自动把 Base URL 填成各自默认地址）
5. 核对 / 修改 Base URL（必填，例如 https://api.deepseek.com/v1）
6. 填 API Key（创建必填；从厂商控制台复制整段贴入，加密存储于服务端）
7. 勾选 启用（默认勾选）和按需勾选 设为默认（切换后下次会话立即生效）
8. 点表单中「测试连接」（详见 5.5），看到绿色 ✓ 再点底部「保存」

小贴士： code 是系统引用键，创建后不能改。编辑态里 code 输入框置灰，调用日志、提示词模板全靠它串起来；非要改只能删了重建。

5.4 四类 provider 怎么填

provider 下拉固定 4 个选项，前三个选中会自动填默认 Base URL，「自定义」则不动 base_url 留你手填。

提示： 内网部署小匠想用国产模型？启一个 vLLM / Ollama / 兼容 OpenAI 协议的网关，provider 选 自定义 + 手填内网 Base URL 即可。

5.5 测试连接：保存前必做一步

「测试连接」会用你当前表单的 Base URL + API Key 发一个最小请求，确认网络通、key 有效、协议对得上。结果显示在按钮右侧。

1. 添加 / 编辑表单中央有「测试连接」按钮（带插头图标），点击前需先填 Base URL 和模型代号，否则会提示「请先填写 Base URL 和模型代号」
2. 编辑态留空 API Key = 用库里已存的 key 测；填了新值 = 用新值内联测
3. 测试中按钮变 spinner 转圈 + 文字「测试中…」，禁用避免重复点击
4. 成功：右侧绿色 ✓「连通正常 · {ms}ms」（返回延迟）
5. 失败：右侧红色 ✗ 显示错误原文或 失败（HTTP {status_code}）——401 多半是 key 错、超时多半是 Base URL 或网络问题、404 多半是 code 没注册
6. 列表卡片右下角还有一个独立的圆形对勾按钮（hover 显示「测试 API key」），可对已保存模型一键回测，结果以 toast 形式提示

5.6 设默认 / 启禁 / 改 API Key / 删除

日常运维四件事：换默认模型、临时停一个、轮换 API Key、删除冗余项。都在卡片或编辑弹窗里直接操作。

1. 设默认：点卡片打开「编辑模型」弹窗，勾选「设为默认（切换后下次会话立即生效）」保存——同一时间只允许一个默认
2. 启用 / 停用：卡片右下角的开关，立即生效并 toast 提示「{code}：已启用 / 已禁用」
3. 改 API Key：点卡片打开编辑弹窗，原 key 不回显（出于安全考虑），在 API Key 输入框填入新值即覆盖、留空则保留原值；点「测试连接」验证后保存即生效，不用重启 agent
4. 删除：卡片右下角红色垃圾桶按钮 → 弹出二次确认；默认模型的删除按钮被禁用，需要先把默认改到别的模型才能删
5. 改 API Key 后建议立刻去「监控 → 调用日志」看 1-2 条新调用是不是 200，再去厂商控制台禁旧 key

注意： API Key 是密文资产。编辑弹窗任何时候都不会回显原 key——这是反 DOM inspector / network log 泄密的设计。如要轮换，直接输入新值覆盖即可。

5.7 模型调用监控（去专用页面看）

本页只管登记和测试模型。要看「这模型每天用了多少次、错了几次、平均多慢」，去监控相关页面。

1. 整体调用情况看 admin 「监控」分组下的调用统计 / 调用日志页面（参见监控章节）
2. 每一次调用的工具链 / 耗时 / 报错原文，按模型 code 过滤查询
3. 错误率突增？常见两种：① API Key 余额不足或被风控（卡片会标「密钥失效」）② 该模型厂商在故障——临时去编辑弹窗切默认到备用模型先顶上

小贴士： 建议挂两个模型做主备。主用 DeepSeek（便宜稳定），备一个 OpenAI 或 Anthropic；主模型出故障时编辑弹窗里勾另一个为默认，业务不停摆。

提示： 下一步：换默认模型后 → 立刻去调用日志看接下来 1-2 次的对话调用是否 200 OK（避免上线后才发现 api_key 写错）。

相关

• 首次启动：setup 向导
• MCP 外部工具管理
• 业务平台服务器管理
• 监控：调用 · 审计 · 系统日志