> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型配置

> 配置并在 100+ LLM 模型间切换。

# 模型配置

Myrm 通过 LiteLLM 统一访问 26+ 内置提供商的 100+ 模型，支持三种兼容协议（OpenAI-like、Gemini-like、Anthropic-like）无限扩展自定义提供商。每个内置提供商预填 API URL 并支持国内/国际区域一键切换，真正零配置即用。

## 首次配置引导

首次启动 Myrm 时，引导向导会帮你快速完成模型配置：

* **本地模型自动探测**：自动扫描运行中的 Ollama 或 LM Studio 实例，推荐最佳可用模型，一键激活。
* **云端快速开始**：没有本地 GPU？向导会展示含免费方案的云端提供商——Google Gemini（免费方案）、SiliconFlow（注册送额度）、OpenRouter（免费开源模型）——一键跳转配置页。
* **持续引导**：即使跳过向导，聊天首屏也会显示温和的提示横幅，引导你配置模型提供商后即可开始对话。

三种部署模式（本地 WebUI、Tauri 桌面端、云托管）共享同一配置界面，位于 **设置 > 模型**。

## 添加 API Key

进入 **设置 > 模型** 或设置环境变量：

```env theme={null}
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=...
GOOGLE_API_KEY=...
```

## 智能路由

三维复杂度路由器根据任务需求、隐私敏感度和提供商健康状态自动选择最优模型：

**阶段 1 — 规则引擎（零 LLM 成本）：** 跨 6 类信号进行多维评分——关键词（30+ 中英双语）、代码块、数学/LaTeX 公式、URL/文件路径、图片和消息长度。99% 的请求瞬间完成分类。

**阶段 2 — LLM Judge（仅模糊场景）：** 对边界情况，由轻量级 Judge 模型分类。结果经 SHA-256 缓存（5 分钟 TTL，256 条 LRU 缓存），避免重复调用。

**Session Momentum（会话动量）：** 短消息（如"好"、"是"）继承会话的复杂度层级，不降级为 SIMPLE。基于消息长度的权重衰减确保长消息独立分类。

**PenaltyTracker — 自学习：** 当你标记路由决策为错误时，该层级获得惩罚分（24 小时半衰期）。后续查询需要更强信号才能激活被惩罚的层级，路由准确度随使用持续提升。

**Fast Lane（快速通道）：** 被判定为 SIMPLE 的任务跳过重量级中间件链，直接以最小开销到达模型。日常闲聊、问候、短跟进等高频消息响应延迟降低约 30-50%——你最常发的消息获得最快回复。

## 模型测速

在选定模型之前，可以直接在设置中测试其真实性能。进入 **设置 > 模型服务**，点击右上角的测速按钮。

**测量指标：**

* **TTFT（首 Token 延迟）** — 模型开始响应的速度
* **TPS（每秒 Token 数）** — 持续生成吞吐量
* **总 Token 数** — 测试提示的完整响应长度

**使用方式：**

* 点击 **全部测试** 依次对所有已启用模型进行基准测试
* 点击单个模型旁的重试图标可单独重测
* 结果以颜色编码徽章显示成功/失败状态

测速结果反映你的真实网络条件和 API 密钥配额，而非合成基准。结合智能路由的自动模型选择，帮助你数据驱动地确认最优模型。

## 推理强度控制

对于支持推理能力的模型（Claude 3.7+、o1/o3/o4-mini、Gemini 2.5、DeepSeek R1、Qwen3 等），Myrm 提供精细的"思考深度"控制。

**6 级预设：** 关闭 / 低 / 中 / 高 / 超高 / 最大 — 从快速回答到深度多步推理，覆盖所有场景。

**自定义 Token 预算：** 输入任意数值（如 `16384`），为支持精确 budget 的 Provider（如 Claude 的 `budget_tokens`）设定思考上限。

**按模型记忆偏好：** 推理强度偏好按模型自动保存。在 Claude 和 GPT 间切换时，各自记住上次的设置，无需重新配置。

**自动检测：** 推理强度按钮仅在当前模型支持推理时出现。非推理模型（如 GPT-4o-mini）不显示按钮，零干扰。检测采用双层机制：API 上报的能力优先，正则匹配覆盖 25+ 模型家族作为兜底。

选中的强度通过完整管道传递 — 前端 `model_kwargs` → Server 透传 → Harness `extra_body` → LiteLLM → Provider API — 三层零耦合。

**智能推理预算（自动生效）：** 所有主流推理模型（Claude 4.6+、DeepSeek R1、OpenAI o 系列、Gemini 2.5+）都将思考 Token 计入 `max_tokens` 预算。如果 `max_tokens` 设置过小，思考阶段会耗尽预算导致回复被截断。Myrm 根据选择的思考强度自动提升 `max_tokens` 到安全下限（低=8K、中=16K、高=32K、超高/最大=65K）。未显式设置时，默认应用 16K 保守下限（因为所有思考模型默认开启推理）。该机制与 stream recovery 形成双层防线 — 事前预防 + 事后恢复。调整完全透明，不增加 API 费用（供应商按实际使用 Token 计费，而非 `max_tokens` 上限）。

## 按模型家族自适应提示词

不同的 AI 模型有不同的行为倾向。Myrm 会自动为每个模型家族调整系统提示词，以获得最佳效果：

* **GPT / Codex / Grok**：工具持久性强制、事实查询必须使用工具、主动执行而非反复询问
* **Claude**：减少免责声明、执行优先
* **Gemini / Gemma**：绝对路径构建、依赖验证
* **DeepSeek / Qwen / GLM**：简洁的中文适配纪律
* **Claude Opus 5+**：针对 Anthropic 官方文档的三大行为偏差自动调优——范围扩展（做超出要求的事）、自我纠正叙述（不必要的"我刚才说错了"）、默认冗长（回复超出需要的长度）

所有提示词适配在 **Agent 初始化时确定并缓存**，对 KV Cache 命中率零影响。无需任何配置——Myrm 从模型名称自动检测模型家族并应用相应的行为指导。

## 对话内模型透明度

每条助手消息的操作栏都有一个 Token 经济学徽章。点击即可查看本次请求使用的模型、路由方式、费用和性能：

* **模型名称 + 路由层级** — 看到实际使用的模型（如 `gpt-4o`、`claude-sonnet-4`）及其路由分类（简单 / 标准 / 推理）
* **提示词缓存命中率** — 缓存 token 百分比、节省金额估算、缓存失效归因分析
* **成本分解** — 单消息成本 + 实际/估算标签，多模型分解、工具级 token 消耗
* **性能基线对比** — TTFT、每秒 token 数、延迟与会话平均值的对比，带色彩偏差指示
* **上下文预算环形图** — 环形进度展示上下文窗口使用率，健康/警告/危险三色阈值
* **隐私级别** — 数据敏感度分类（S1 公开 / S2 内部 / S3 机密）和路由路径（本地 / 云端）

没有黑盒——每个路由决策都在聊天界面中可见且可验证。

## Key 轮换

为同一提供商添加多个 API Key，Myrm 自动轮换并智能故障切换。当有 2 个以上活跃 Key 时，密钥池状态栏会显示**策略选择器**——选择最适合你的轮换模式：

| 策略                    | 适用场景               |
| --------------------- | ------------------ |
| **轮询 (Round Robin)**  | 均匀分配所有 Key 的用量（默认） |
| **优先填充 (Fill First)** | 先用完免费额度，再使用付费 Key  |
| **最少使用 (Least Used)** | 按实际调用次数均衡分配        |
| **随机 (Random)**       | 简单随机选择             |

遇到限流 (429) 时，自动指数退避 + ±15% 抖动并切换到下一个可用 Key，用户完全无感。

## 隐私路由

隐私路由按数据敏感度自动选择云端或本地模型，无需手动切换：

| 敏感度         | 路由             | 数据处理      |
| ----------- | -------------- | --------- |
| **S1** — 公开 | 云端模型           | 直连云端      |
| **S2** — 内部 | 云端（PII 脱敏后）或本地 | 自动脱敏或本地路由 |
| **S3** — 机密 | 仅本地模型          | 数据不离开本机   |

隐私路由在标准接口后包装模型。Agent、中间件与执行循环对路由无感，与普通模型交互。

配合 Ollama、LM Studio 或 vLLM 本地后端，敏感负载可完全气隙运行。

## 本地模型与硬件管家

Myrm 自动探测本地模型服务和硬件能力，实现零配置的本地 AI 体验：

**首次启动 — 自动发现：** 在引导流程中，Myrm 自动探测 Ollama 和 LM Studio。发现后一键激活——自动配置 Provider、选择推荐模型、设为默认模型，一步到位。

**硬件管家：** 设置面板中的硬件管家展示你的电脑配置（CPU、RAM、GPU、VRAM、磁盘空间），并为每个可用本地模型计算 Fit Score。根据 VRAM 或 RAM 评为 perfect / good / fair / poor 四级。磁盘空间不足时下载按钮自动禁用，从根本杜绝下载爆盘导致系统死机。

**推理速度预览（\~tok/s）：** 每个模型卡片在 VRAM 估算旁同步展示预估推理速度标签，基于你的 GPU 内存带宽和模型参数量（Q4\_K\_M 量化）计算，色彩直观：

* 🟢 ≥ 20 tok/s — 丝滑实时对话
* 🟡 8–19 tok/s — 可用但略有延迟感
* 🔴 \< 8 tok/s — 实时对话明显卡顿

这意味着在下载几 GB 大文件前，你就已经知道这个模型用起来是流畅还是卡顿。速度计算还针对不同厂商（Apple Silicon、Nvidia、AMD、Intel）的实际内存带宽利用率做了效率校正，结果比简单的"带宽÷参数"更接近真实体验。

**100% 离线可用 — 零网络依赖：** 整个推荐流程无需联网即可工作。模型规格作为静态资产随应用打包分发——不调用任何外部 API、没有缓存过期问题、首次启动也不需要网络。硬件检测是本地系统调用，Ollama 探测仅访问 localhost。这意味着在断网环境、飞机上、离线机房中，硬件管家的表现与联网时完全一致。

**一键安装与卸载：** 直接在 UI 中下载模型，SSE 流式进度显示 + 支持取消。安装完成后模型即刻出现在选择器中。卸载后磁盘空间立即回收。

**部署模式感知：** SaaS 模式下本地模型功能自动隐藏，云端用户不会看到多余选项。Local WebUI 和桌面端模式下完整硬件管家可用。

**本地端点超时自适应：** 当 API 地址指向本地（localhost、192.168.x.x、10.x.x.x 或任何私有网络），Myrm 自动放宽内部超时阈值。大参数本地模型（70B+）在长上下文场景下首 token 生成可能需要数分钟——针对云端优化的 60 秒超时会误杀这些请求并触发无效重试循环。Myrm 通过 RFC1918/IPv6 地址分析检测本地端点，将超时延长至 5-30 分钟，确保本地推理顺利完成。远程 API 行为完全不变。无需任何配置——开箱即用。

## 配置自愈

所有模型配置在保存时自动清洗，避免常见的复制粘贴错误导致连接失败：

* **API URL** — 自动移除尾部斜杠和空白字符（防止 404）
* **API Key** — 自动去除首尾空格和换行符（防止鉴权失败）
* **模型名称** — 自动去除多余空格（防止模型找不到）
* **空白值** — 自动转为未设置状态，安全降级而非崩溃
* **旧版 providerType** — 从旧工具导入时若 compat 类型写成 `openai` 而非 `openai-like`，启动时自动迁移并按 provider id 回退路由，不会白屏
* **开发者系统健康** — Context Bundle 面板走 `/context-bundle` 相对路径，避免 `/api/v1/api/...` 双前缀导致 404

这意味着从文档或终端粘贴配置时，即使带有多余的空格、斜杠或换行符，系统也能正常工作。你无需关心格式问题。

## 多设备配置同步

Myrm 在浏览器标签、桌面端与 SaaS 之间保持设置一致——**刷新页面不会反复弹出「配置冲突检测」**。

**你能得到什么：**

* 在手机上改语言、朗读或默认模型——桌面端自动同步
* 多标签或硬刷新——**不会误报配置冲突**
* 离线编辑——变更本地排队，联网后自动同步
* 改坏了？**配置时光机** 可一键回滚任意配置键

**工作机制（面向用户）：**

* **智能合并** — 两台设备改*不同*字段时，两边变更都会保留
* **诚实冲突** — 两台设备改*同一*字段时，由你选择保留哪一版
* **同设备静默** — 本机标签页刷新不会触发冲突弹窗
* **幂等同步** — 内容相同时不会无意义地 bump 版本号

**对比文件型 Agent（OpenClaw、Hermes CLI）**：设置散落在文件中，无合并 UI；多设备只能手动拷贝或面对 git 冲突。Myrm 是唯一同时具备**企业级配置同步**与**完整 GUI** 的 Agent 工作站。

## Vision Fallback（视觉备选）

当**主模型不支持视觉**时，在 **设置 → 模型** 中配置 **Vision Fallback**。Myrm 会自动将图片转为文字描述再交给主模型，聊天区显示实时进度，同会话重复图片会缓存以避免重复调用。

详见 [视觉与图片理解](/zh/guides/vision-interaction) 指南。

## 多模型共识推理 (MoA)

多个模型并行生成答案，聚合模型综合出最可靠结果。适用于关键决策、合同审查、技术方案评审等需要交叉验证的场景。

**使用方式：** 进入 **设置 > 智能体 > 能力 > 多模型共识**，启用后选择参考模型和聚合模型。

**核心参数：**

* **参考温度** — 控制参考模型输出多样性（默认 0.6，越高越多样）
* **聚合温度** — 控制最终综合的精确度（默认 0.4，越低越精确）
* **参考输出上限** — 限制每个参考模型的最大输出 token 数（默认不限制，推荐设为 600-2000 以节省成本）
* **参考推理强度** — 控制参考模型的推理深度（low/medium/high），推荐 low 以节省推理 token 费用
* **聚合推理强度** — 控制聚合模型的推理深度，推荐 high 以保证综合质量
* **最少成功数** — 至少需要几个参考模型成功返回（默认 1）

**智能优化：**

* 仅 1 个参考模型成功时自动跳过聚合步骤，直接返回结果
* 聚合模型输出永不截断——用户看到的答案始终完整
* 兼容推理模型（DeepSeek-R1 等）的特殊输出格式，并支持独立的推理强度控制
* 完整的多轮对话上下文传递

## 成本可视化

完整的 Token 经济学可视化体系，从后端到前端全链路覆盖：

| 层级          | 能力                                                                                              | 关键组件                                                |
| ----------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| 消息级         | 每条消息展示 Token 用量和成本                                                                              | TokenUsageDisplay、缓存节省水滴动画                          |
| 会话级         | 会话诊断六问分析 + 执行 Trace 回放                                                                          | SessionAnalyticsDialog、ExecutionTraceTimeline       |
| Dashboard 级 | 7/30/365 天多维度用量统计                                                                               | UsageStatisticsSection、路由分析面板                       |
| 预算控制        | 4 维预算守卫 (tokens/USD/时间/轮次) + 三级渐进式应对 (WARNING eco 压缩→FINALIZATION 强制输出→EXCEEDED 硬阻止) + SSE 实时推送 | BudgetPolicySection、BudgetBadge、BudgetDialog、渠道预算管理 |
| 企业级         | 组织用量概览 + 审计日志                                                                                   | EnterpriseUsageTab                                  |
| 模型策略        | 组织级模型白名单（限制可用的 LLM 模型）                                                                          | EnterpriseModelPolicyTab                            |

| 指标          | 数值                                                                     |
| ----------- | ---------------------------------------------------------------------- |
| Token 经济学测试 | **355 项通过**                                                            |
| Token 类型追踪  | **7 种**（prompt/completion/cached/reasoning/audio\_in/audio\_out/image） |
| 前端可视化组件     | **18+**                                                                |
| 后端统计 API    | **12 端点**                                                              |

## 工具 Schema 自动规范化

切换模型时（如从 GPT-4o 切到 Gemini 或 Claude），各提供商对工具 schema 的要求各不相同。Myrm 在发送给模型前自动规范化所有工具 schema，无需任何配置。

**自动修正的问题：**

* 孤儿 `required` 条目（引用了不存在的 `properties` 字段）—— Gemini/Vertex AI 会返回 400 错误
* 嵌套 nullable 模式（`anyOf: [{type: X}, {type: null}]`）—— OpenAI strict 模式会报错
* `$ref`/`$defs` 内联定义 —— 大多数提供商不支持 JSON Schema 引用
* 缺失 `type` 注解 —— 严格模式提供商直接拒绝
* Anthropic 不支持的关键字（`minimum`、`maxItems`、`pattern` 等）—— 约束折叠为描述文本

**为什么重要：** MCP 工具来自第三方服务器，schema 质量参差不齐。没有规范化，切换模型时工具调用经常直接失败。Myrm 确保每个工具在每个模型上都能正常工作，对用户完全透明。

## 容错

14 层错误恢复系统自动处理故障：

* 限流（4 策略 Key 轮换 + 凭证池 + ManagedLLM/KeyPool 智能体内故障转移）
* 提供商宕机（熔断器 3 级冷却 + 回退预设）
* 流中断（Token 级精确续传）
* 响应截断（渐进输出预算提升 2x → 3x → 4x）
* 超大图片（自动重编码压缩）
* 模型思考模式错误（自动调整模式并重试）
* 空响应（调参重试）
* 迭代上限（grace-call 摘要 — 用户不见空白回复）

完整 14 层架构见[错误恢复](/zh/core-concepts/error-recovery)。