322 lines
12 KiB
Markdown
322 lines
12 KiB
Markdown
---
|
||
name: mimo-capabilities
|
||
description: MiMo 模型原生能力配置指南 - 图像理解、音频理解、视频理解、TTS 语音合成、网络搜索。当主模型为 MiMo 时使用这些方法。
|
||
tags: [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
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
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
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
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
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
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
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
# 内置音色
|
||
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、角色化对话），支持分层描述：
|
||
|
||
```bash
|
||
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 插件。
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
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: 本地化搜索位置
|
||
|
||
## 环境变量
|
||
|
||
```bash
|
||
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`
|
||
|
||
```bash
|
||
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 配置 |
|
||
|
||
```bash
|
||
# 方法：从 .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. **验证方式**：
|
||
```bash
|
||
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：
|
||
```bash
|
||
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 - 网络搜索
|