# Xiaomi MiMo ASR (mimo-v2.5-asr) — Hermes STT 安装说明

将小米 MiMo ASR 语音识别模型接入 Hermes 的语音转文字功能。

## 前置条件

- Hermes Agent 已安装
- Xiaomi MiMo API Key（https://platform.xiaomimimo.com 获取）
- ffmpeg（用于音频格式转换）：`brew install ffmpeg`

## 工作原理

Xiaomi ASR **不使用**标准的 `/v1/audio/transcriptions` 端点，而是通过
`/v1/chat/completions` 接口 + `input_audio` 格式工作。因此需要一个包装脚本来处理：
- 音频格式转换（非 wav/mp3 文件通过 ffmpeg 转为 16kHz 单声道 WAV）
- Base64 编码音频数据
- 构造 chat completions JSON payload
- 解析响应提取转录文本

Hermes 的 **command provider** 机制允许通过 shell 命令接入任意 STT 后端，
无需编写 Python 插件。

## 安装步骤

### 1. 复制脚本

```bash
cp xiaomi-asr.sh ~/.hermes/scripts/xiaomi-asr.sh
chmod +x ~/.hermes/scripts/xiaomi-asr.sh
```

### 2. 配置环境变量

在 `~/.hermes/.env` 中添加（如果还没有）：

```
XIAOMI_API_KEY=your_api_key_here
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
```

> 如果你的 API Key 绑定的是国际站，用 `https://api.xiaomimimo.com/v1`

### 3. 修改 Hermes 配置

在 `~/.hermes/config.yaml` 的 `stt` 部分：

```yaml
stt:
  enabled: true
  provider: xiaomi-asr
  providers:
    xiaomi-asr:
      type: command
      command: ~/.hermes/scripts/xiaomi-asr.sh {input_path} {output_path} mimo-v2.5-asr {language}
      language: zh
      format: txt
      timeout: 120
```

### 4. 重启 Hermes

- Desktop / TUI：关闭并重新打开
- Gateway：运行 `/restart`

## 验证

```bash
# 手动测试脚本
export XIAOMI_API_KEY=your_key
export XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
~/.hermes/scripts/xiaomi-asr.sh /path/to/audio.wav /tmp/output.txt mimo-v2.5-asr zh
cat /tmp/output.txt
```

## 注意事项

| 问题 | 说明 |
|------|------|
| 音频格式 | 只支持 wav 和 mp3，其他格式自动通过 ffmpeg 转换 |
| 纯音乐 | 无法识别纯音乐内容，会返回空结果 |
| 语言 | 主要针对中文优化，其他语言效果较差 |
| ffmpeg | 非 wav/mp3 格式必须安装 ffmpeg |