agent-skills/mlops/mimo-capabilities/SKILL.md

name, description, tags

name	description	tags
mimo-capabilities	MiMo 模型原生能力配置指南 - 图像理解、音频理解、视频理解、TTS 语音合成、网络搜索。当主模型为 MiMo 时使用这些方法。	mimo xiaomi vision audio video tts search multimodal

MiMo 模型原生能力配置指南

概述

MiMo 是小米研发的 AI 大模型，支持多种原生能力。当主模型为 MiMo 时，应使用 MiMo 的原生 API 而非第三方工具。

模型感知路由规则

关键原则：根据当前主模型选择对应的方法

功能	MiMo 模型	MiniMax 模型 (mmx-cli)
图像理解	MiMo Vision API	mmx vision describe
音频理解	MiMo Audio API	不支持
视频理解	MiMo Video API	不支持
TTS	MiMo TTS API	mmx speech synthesize
网络搜索	MiMo Web Search API	mmx search query
图像生成	不支持	mmx image generate
视频生成	不支持	mmx video generate
音乐生成	不支持	mmx music generate

1. 图像理解

支持的模型

• mimo-v2.5
• mimo-v2-omni

使用方法

python3 ~/.hermes/scripts/mimo_vision.py "https://example.com/image.jpg" "描述这张图片"
python3 ~/.hermes/scripts/mimo_vision.py /path/to/image.png "这张图片里有什么？"

图片限制

• 格式：JPEG, PNG, GIF, WebP, BMP
• 大小：单张不超过 50MB

2. 音频理解

支持的模型

• mimo-v2.5
• mimo-v2-omni

使用方法

python3 ~/.hermes/scripts/mimo_audio.py "https://example.com/audio.wav" "这段音频说了什么？"
python3 ~/.hermes/scripts/mimo_audio.py /path/to/audio.mp3 "转录这段音频"

音频限制

• 格式：MP3, WAV, FLAC, M4A, OGG
• 大小：URL 不超过 100MB，Base64 不超过 50MB

3. 视频理解

支持的模型

• mimo-v2.5
• mimo-v2-omni

使用方法

python3 ~/.hermes/scripts/mimo_video.py "https://example.com/video.mp4" "描述视频内容"
python3 ~/.hermes/scripts/mimo_video.py /path/to/video.mp4 "视频里发生了什么？" --fps 2

参数说明

• --fps: 每秒提取帧数，范围 0.1-10，默认 2
• --resolution: default（默认）或 max（最高分辨率）

视频限制

• 格式：MP4, MOV, AVI, WMV
• 大小：URL 不超过 300MB，Base64 不超过 50MB

4. TTS 语音合成

支持的模型

模型	功能
mimo-v2.5-tts	内置音色，支持唱歌
mimo-v2.5-tts-voicedesign	音色设计
mimo-v2.5-tts-voiceclone	音色克隆

内置音色列表

• 中文：冰糖（默认）, 茉莉, 苏打, 白桦
• 英文：Mia, Chloe, Milo, Dean

使用方法

# 内置音色
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --voice 冰糖 --output output.wav

# 音色设计（VoiceDesign）
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --design "年轻女性，温柔甜美" --output output.wav

# 音色克隆（VoiceClone）
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --clone voice_sample.mp3 --output output.wav

# 带风格指令
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --voice 冰糖 --style "用欢快活泼的语气" --output output.wav

VoiceDesign 音色设计详解

通过自然语言描述从零生成全新音色，无需参考音频。

描述维度（可自由组合）：

• 性别年龄：年轻女性、中年男性、小女孩、年迈老先生
• 口音语言：标准普通话、带北方口音、说英语
• 音色特征：低沉有磁性、清脆明亮、温柔甜美、略带沙哑
• 发声方式：像纪录片旁白、像新闻主播、声音位置靠后
• 性格气质：沉稳而有感染力、元气满满、饱经风霜

高级特性：

• 对复杂、模糊、甚至相互矛盾的描述也能合理解读
• 不局限于"男/女/青年/老年"粗粒度标签
• 适合游戏NPC、动画角色、虚拟主播、品牌IP、有声剧

示例：

--design "一位年迈的老先生，说带北方口音的普通话，语速缓慢而沉稳，嗓音略带沙哑和沧桑感，仿佛一位饱经风霜的老爷爷在讲故事，充满岁月的智慧。"

VoiceClone 音色克隆详解

只需短至数秒的参考音频，无需训练/标注/微调，直接复刻音色。

保留的特征：

• 原始说话人的音色身份
• 气息、节奏、习惯性停顿等个人特征

复用能力：克隆后的音色可叠加使用全部控制能力（自然语言指令、音频标签、导演剧本）

示例：

# 提供参考音频 + 风格指令
--clone reference.mp3 --style "用尖锐刻薄的嗓音，带着狐假虎威的得意感"

风格控制标签（行内音频标签）

在文本中用括号插入标签，精准控制情绪/状态/风格：

标签类型：

• 基础情感：开心、悲伤、生气、害怕、惊讶、兴奋
• 复杂情感：忧郁、释然、无奈、内疚、嫉妒、疲惫
• 整体语调：温柔、冷淡、活泼、严肃、慵懒、俏皮
• 音色定位：磁性、醇厚、清亮、空灵、天真、甜美
• 方言：东北话、四川话、河南话、粤语
• 唱歌：唱歌（必须放在最开头）

高级用法：

• 支持中英双语标签
• 支持多标签叠加（用 ｜ 分隔）
• 支持开放文本描述

示例：

(调侃) 老张你当时不是说这条航线稳得很吗……
(模仿自信，提高音量) "系统全绿，放心走。"
(突然停顿) ……现在呢？
(爆发，愤怒压不住) 现在整艘船都在报警！
(低声｜情绪塌陷般平静) ……算了。
(轻笑｜带点释然) 也挺好，至少是一起看的。

导演剧本级结构化输入

对于一致性要求高的场景（有声剧、游戏NPC、角色化对话），支持分层描述：

python3 ~/.hermes/scripts/mimo_tts.py \
  --text "你们求我垂怜..." \
  --voice 白桦 \
  --style "CHARACTER: 曾是守护九天的神祇，见证了凡人的无药可救后，决定以灭世来完成最终的净化。
SCENE: 悬浮于崩塌的祭坛之上，俯视下方在火海中哀嚎的信徒。
DIRECTION: 充分打开胸腔共鸣，声音位置靠后，音色如古钟般低沉且带有金属质感的磁性。" \
  --output output.wav

分层说明：

• CHARACTER：人物身份、背景、性格
• SCENE：场景环境、情境
• DIRECTION：详细的发声指导（共鸣、语调、气声、咬字等）

TTS API 要点

1. 合成文本必须放在 assistant 角色的 content 中
2. user 角色消息可选，用于传递风格指令
3. 流式调用时输出格式指定为 pcm16

5. 网络搜索

支持的模型

• mimo-v2.5-pro, mimo-v2.5, mimo-v2-pro, mimo-v2-omni, mimo-v2-flash

前置条件

在 MiMo Console 启用 Web Search 插件。

使用方法

python3 ~/.hermes/scripts/mimo_search.py "武汉明天天气"
python3 ~/.hermes/scripts/mimo_search.py "附近美食" --city 武汉 --region 湖北

参数说明

• --max-keywords: 每轮搜索最大关键词数，默认 3
• --force/--no-force: 是否强制搜索，默认强制
• --limit: 搜索结果数量，默认 1
• --country/--region/--city: 本地化搜索位置

环境变量

XIAOMI_API_KEY=tp-xxxxx
XIAOMI_BASE_URL=https://token-plan-sgp.xiaomimimo.com/v1

注意：环境变量需持久化到 ~/.bashrc，否则新 terminal session 会丢失。

⚠️ 图片输入配置（关键）

MiMo chat API 不支持图片输入。用户发图片时，如果 Hermes 把图片直接塞进 chat completions 请求，会返回 404: No endpoints found that support image input。

必须设置 image_input_mode: tool

hermes config set agent.image_input_mode tool

• auto（默认）= 尝试直接把图片发给主模型 → MiMo 会 404
• tool = 强制图片走 vision 工具 → 正确路由到 MiMo Vision API

Vision API Key 必须显式写入 config

XIAOMI_API_KEY 环境变量不会自动传给 Hermes vision 工具。必须手动填入 config。

有两个 vision section 都需要 API key：

路径	用途
auxiliary.vision.api_key	主 vision 工具配置（含 provider/model/base_url）
tools.vision.api_key	工具层 vision 配置

# 方法：从 .bashrc 提取 key 并写入（hermes config set 无法展开未 source 的环境变量）
python3 << 'EOF'
import yaml
key = open('/home/ubuntu/.bashrc').read().split('XIAOMI_API_KEY=')[1].split('\n')[0].strip().strip('"').strip("'")
with open('/home/ubuntu/.hermes/config.yaml') as f:
    config = yaml.safe_load(f)
config['auxiliary']['vision']['api_key'] = key
config['tools']['vision']['api_key'] = key
with open('/home/ubuntu/.hermes/config.yaml', 'w') as f:
    yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
print(f'Done. Key set: {key[:10]}...')
EOF

⚠️ 常见问题排查

401 Unauthorized / Invalid API Key

1. 检查 base URL：脚本默认值可能过时。正确 URL 是 https://token-plan-sgp.xiaomimimo.com/v1，不是 https://api.xiaomimimo.com/v1。
2. 检查 header 格式：MiMo API 使用 Authorization: Bearer <key>，而非 api-key header。
3. 验证方式：

   curl -s https://token-plan-sgp.xiaomimimo.com/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $XIAOMI_API_KEY" \
     -d '{"model":"mimo-v2.5-tts","messages":[{"role":"assistant","content":"你好"}],"audio":{"format":"wav","voice":"冰糖"}}'
   

404: No endpoints found that support image input

MiMo chat API 不支持图片输入。用户发图片时 Hermes 尝试直接塞进请求导致。 修复：hermes config set agent.image_input_mode tool，并确保 vision API key 已配置（见上方"图片输入配置"章节）。

脚本报 "No API key found"

确认环境变量已 export：echo $XIAOMI_API_KEY。如果为空，添加到 ~/.bashrc 并 source ~/.bashrc。

注意：Hermes 的 config.yaml 中可能已配置了 API key（auxiliary.vision.api_key 或 provider 的 api_key），但这个 key 不会自动 export 到 shell 环境变量。脚本依赖 XIAOMI_API_KEY 环境变量，二者是独立的。

快速恢复方法：从 config.yaml 提取 key 并 export：

export XIAOMI_API_KEY=$(python3 -c "import yaml; c=yaml.safe_load(open('/home/ubuntu/.hermes/config.yaml')); print(c.get('auxiliary',{}).get('vision',{}).get('api_key',''))")

网络搜索 400 Bad Request

mimo_search.py 可能因 API 端点变更或参数格式问题返回 400。排查步骤：

1. 先用 curl 直接测试 API 是否可达：curl -s -o /dev/null -w "%{http_code}" https://token-plan-sgp.xiaomimimo.com/v1/models -H "Authorization: Bearer $XIAOMI_API_KEY"
2. 如果网络不通（Network is unreachable），是服务器出站网络问题，不是 API 问题
3. 如果网络通但 400，检查请求体格式是否与最新 API 兼容

mmx search 不可用

mmx search query 需要 MiniMax Token Plan 支持 coding-plan-search 模型。如果报错 "your current token plan not support model, coding-plan-search"，说明当前 plan 不包含搜索能力。替代方案：

• 使用 MiMo 网络搜索（如果可用）
• 使用 Playwright 浏览器抓取
• 使用 curl 直接请求搜索引擎（注意服务器出站网络限制）

References

• references/sensenova-api.md — SenseNova API 配置、模型列表、限流策略、已安装 skills 绑定情况
• references/mimo-v2.5-tts-official-doc.md — MiMo-V2.5-TTS Series 官方文档摘要（VoiceDesign/VoiceClone/导演剧本详解）

脚本位置

所有 MiMo 辅助脚本位于 ~/.hermes/scripts/：

• mimo_vision.py - 图像理解
• mimo_audio.py - 音频理解
• mimo_video.py - 视频理解
• mimo_tts.py - TTS 语音合成
• mimo_search.py - 网络搜索