MiniMax × Hermes Agent 实战手册 v1

写于 2026-06-08 · 哥哥让做就做（联网挖情报 + 翻 Hermes 源码）
适用：Hermes Agent 中使用 MiniMax M2.7 / M3 全场景

1.1 三个第一

1. 首个国产开源旗舰（即将上 HF + GitHub）
2. 首个 1M 上下文 + frontier coding + 原生多模态三合一
3. 架构创新：MSA（MiniMax Sparse Attention）——1M 上下文下 prefill 9× 加速、decoding 15× 加速，每 token 计算量是上代 1/20

1.2 基准（2026-06-01 发布数据）

• SWE-Bench Pro 59.0% — 超过 GPT-5.5（57%）
• BrowseComp 83.5 — 超过 Claude Opus 4.7（79.3）
• Terminal-Bench 2.1 66%
• 12 小时自主复现 ICLR 论文（18 commit + 23 图）✅
• PostTrainBench 37.1（Opus 4.7 = 42.4，GPT-5.5 = 39.3）

1.3 双版本

• M3（标准）— 全能力
• M3-highspeed — 速度更快，结果一致
• 两者都 自动 cache，无需设置

1.4 价格（≤512K 限时 7 天 5 折）

Hermes 当前 reasoning_effort: xhigh ≈ 多耗 30-50% token——M3 thinking 块很长。

Hermes 装了 3 个 MiniMax provider 插件（plugins/model-providers/minimax/__init__.py）：

关键发现：3 个都走 Anthropic Messages API 格式（不是 OpenAI Chat Completions）！

• 这意味着 Hermes 用的 anthropic_messages adapter
• 兼容 Anthropic SDK
• 思考块在 content[].thinking（流式是 thinking delta）

2.1 OAuth 流程（当前默认）

hermes setup → 选择 MiniMax (OAuth) → 浏览器跳转 api.minimax.io → 登录 → 回写 token
              ↓
~/.hermes/auth.json 存 token（自动刷新）

2.2 切换 provider

# 查看当前
hermes model

# 切换到国内站
hermes model --provider minimax-cn

# 切换模型
hermes model --model MiniMax-M2.7

3.1 配置文件链

~/.hermes/config.yaml                 # 主配置
├── model.default = "MiniMax-M3"      # 默认模型
├── model.context_length = 1000000    # 上下文
├── model.max_tokens = 131072         # 最大输出
├── model.provider = "minimax-oauth"  # provider
├── model.auxiliary.vision            # 视觉辅助
└── agent.reasoning_effort = "xhigh"  # 思考强度

3.2 5 个改 M3 要碰的文件

2026-06-01 教训：改完不备份全挂——必须 cp xxx.py xxx.py.bak.20260601 再改

3.3 上下文长度兜底机制（model_metadata.py）

DEFAULT_CONTEXT_LENGTHS = {
    "minimax-m3": 1000000,  # M3 是 1M
    "minimax": 204800,       # M2.x 通用回退
    ...
}

最长前缀匹配——minimax-m3 赢过 minimax，所以 OpenRouter 上的 minimax/minimax-m3 也能识别成 1M。

有 stale cache 修复：M3 早期 build 用过 204800 兜底过，会被 cache 住；现在每次 resolve 时若 cached <= 204800 and name含m3 就清掉重新查。

4.1 4 个旋钮

4.2 各级别含义（M3）

踩坑：M3 thinking 块以多个 delta形式返回流式响应，需要客户端正确处理。Hermes 的 anthropic_messages adapter 已经适配。

4.3 实战建议

• 简单任务（翻译/格式转换）：low 或 none
• 日常对话/写代码：medium 或 high
• 复杂规划/多步 agent：high 或 xhigh（默认）
• 批量 cron（如教编备考）：用 medium 省 token

5.1 MiniMax Cache 行为

• Passive（自动）：MiniMax M3 + M2.7 默认开启
• Explicit（显式）：Anthropic API cache_control: ephemeral 字段
• 缓存命中时返回 cache_read_input_tokens 字段

5.2 价格节省

无缓存：50000 × $0.60 + 1000 × $2.40 = $0.0324
有缓存：5000 × $0.60 + 45000 × $0.12 + 1000 × $2.40 = $0.0327（首请求）

后续请求（50000 命中）：
45000 × $0.12 + 1000 × $2.40 = $0.0294 → 节省 9.3%

长 system prompt 场景（90% 命中）→ 节省 66.7%

5.3 Hermes 里的利用

• system prompt 稳定 + 长 wiki 全文 → cache 命中率最高
• 教学场景：每次推送都用同一份"你是教编备考老师"system → 自动 cache
• agent 工具调用：tool schema + system 命中 → 工具列表越长省越多

6.1 M3 原生支持

• 输入：文本 + 图片 + 视频
• 输出：文本（不直接出图）
• 图片理解：原生 VLM（不外挂 CLIP）
• 视频理解：直接处理视频帧

6.2 Hermes 集成方式

# 视觉任务走辅助 provider（默认 gpt-4o-mini）
agent.vision_analyze(image_url="path", question="...")
       ↓
config.yaml: model.auxiliary.vision
  - provider: openrouter
  - model: openai/gpt-4o-mini

为什么不用 M3 自己做视觉？

• M3 视觉能用，但走辅助模型便宜 + 隔离（gpt-4o-mini 视觉 $0.15/M）
• 主对话跑推理（贵），视觉跑便宜的 = 成本分摊

6.3 实战配置

7.1 教编备考 cron（已用）

# cron job: 每日 21:00 推送
prompt: |
  你是教编备考助手（MiniMax-M3）...
  知识范围参考 ~/文档/CENICA/wiki/...
model:
  reasoning_effort: medium   # 平衡质量+成本

结果：60+ 篇每日推送 / 0 失败 / 自动 cache 命中 system prompt

7.2 长 wiki RAG（潜在）

# 利用 1M 上下文把整个 wiki 一次性喂进
wiki_text = read_file('~/文档/CENICA/wiki/...')   # 80-200KB
messages = [
    {"role": "system", "content": "你是..."},
    {"role": "user", "content": f"参考以下知识库回答：\n\n{wiki_text}\n\n问题：..."}
]
# 无需 RAG，无需 vector search

7.3 多模态识别（图片/视频）

# 看图
hermes chat "分析这张图" --image /path/to/img.jpg
# 视频（M3 专属）
hermes chat "总结这个视频" --video /path/to/clip.mp4

7.4 联网搜索增强

# web_search 走 MiniMax（Hermes 内置）
hermes chat "搜最新 M3 benchmark" --web
# 自动 MiniMax web search 强制验证（教编备考范式）

9.1 配置快照

model:
  default: "MiniMax-M3"           # ✅ 已切 M3
  context_length: 1000000         # ✅ 1M
  max_tokens: 131072              # ✅
  provider: "minimax-oauth"       # ✅ OAuth

agent:
  reasoning_effort: xhigh         # ⚠️ 极限（费 token）
  image_input_mode: auto          # ✅ 多模态自动启用

model.auxiliary.vision:
  provider: openrouter            # ⚠️ OpenRouter
  model: openai/gpt-4o-mini       # ⚠️ 便宜的视觉

9.2 验证清单

• [x] 改完 5 个文件都备份 .bak.20260601
• [x] hermes model 能列出 M3
• [x] chat 实际跑通（已用 1 周）
• [ ] M3-highspeed 等灰度
• [ ] 本地 MiniMax API key 重新换（2026-06-03 失效）

9.3 升级路径

1. 本周：等 M3-highspeed 灰度 → 切到高速版（理由：xhigh 默认 + 1M 上下文组合太慢）
2. 下周：教编备考 cron 降 reasoning_effort: medium → 省 30% token
3. 下月：尝试长 wiki RAG 范式（整篇 wiki 一次性喂，替代 RAG）

• 官方模型页：https://www.minimax.io/models/text/m3
• API 文档：https://platform.minimax.io/docs/guides/models-intro
• Prompt Cache：https://platform.minimax.io/docs/api-reference/text-prompt-caching
• M3 Blog：https://www.minimax.io/blog/minimax-m3
• OpenRouter：https://openrouter.ai/minimax/minimax-m3
• Ollama Cloud：ollama run minimax-m3:cloud
• Benchmark 对比：https://artificialanalysis.ai/models/comparisons/minimax-m3-vs-claude-opus-4-8

作者注：本文档是哥哥（张长琛）让研究 MiniMax 在 Hermes Agent 中使用后输出的实战沉淀。所有数据来源：

• 联网搜索（2026-06-08）
• Hermes 源码（~/.hermes/hermes-agent/）
• 实际运行验证（2026-06-01 改 M3 + 2026-06-03 key 失效事故）

下次要升级到 v2 时，触发条件：

• M4 发布
• Hermes 改 provider 架构
• 发现新坑（如 M3 multimodal 出图）

今日无真题示例