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

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

本版本针对 **Windows + Hermes Desktop** 进行了适配，使用纯 Python 实现，不依赖 bash/git-bash 环境。

---

## 前置条件

- Hermes Agent 已安装且正常运行
- Xiaomi MiMo API Key（[https://platform.xiaomimimo.com](https://platform.xiaomimimo.com) 获取）
- ffmpeg（用于非 wav/mp3 格式的自动转换）
  - 可在 [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) 下载，或 `winget install Gyan.FFmpeg`
  - 确保 `ffmpeg` 在系统 PATH 中
- Python（Hermes 自带，无需额外安装）

---

## 工作原理

Xiaomi ASR **不使用**标准的 `/v1/audio/transcriptions` 端点，而是通过 `/v1/chat/completions` 接口 + `input_audio` 格式工作。该脚本负责：

- 音频格式检测（wav/mp3 直接发送，其他格式通过 ffmpeg 转为 16kHz 单声道 WAV）
- Base64 编码音频数据
- 构造 chat completions JSON payload
- 解析响应提取转录文本

### 为什么用 Python 而不是 Shell 脚本？

Hermes 在 Windows 上通过 **cmd.exe** 执行 command provider，cmd.exe **不识别**：
- `~` 波浪号（不会展开为用户目录）
- `.sh` 扩展名（不知道用什么程序打开）

Python 脚本（`.py`）可以被 `python` 解释器直接调用，无上述问题。

---

## 安装步骤

### 1. 复制脚本

将 `xiaomi-asr.py` 复制到 Hermes 的脚本目录：

```powershell
# 创建脚本目录（如果不存在）
mkdir $env:USERPROFILE\.hermes\scripts -Force

# 复制脚本
copy .\xiaomi-asr.py $env:USERPROFILE\.hermes\scripts\xiaomi-asr.py
```

或在 bash (git-bash) 中：

```bash
mkdir -p ~/.hermes/scripts
cp xiaomi-asr.py ~/.hermes/scripts/xiaomi-asr.py
```

### 2. 配置环境变量

在 `D:\Program Files\Hermes\.env`（或 `$env:HERMES_HOME\.env`，视你的安装位置而定）中添加：

```env
# Xiaomi MiMo ASR
XIAOMI_API_KEY=你的API_Key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
```

> 中国站用户：`https://token-plan-cn.xiaomimimo.com/v1`
> 国际站用户：`https://api.xiaomimimo.com/v1`

### 3. 修改 Hermes 配置

编辑 `D:\Program Files\Hermes\config.yaml`（或 `$env:HERMES_HOME\config.yaml`）的 `stt` 部分：

```yaml
stt:
  enabled: true
  provider: xiaomi-asr
  providers:
    xiaomi-asr:
      type: command
      command: python C:/Users/<你的用户名>/.hermes/scripts/xiaomi-asr.py {input_path} {output_path} mimo-v2.5-asr {language}
      language: zh
      format: txt
      timeout: 120
```

> **注意**：请将 `<你的用户名>` 替换为实际的 Windows 用户名，并用**正斜杠**（`/`）代替反斜杠。
>
> 也可用 `hermes config set` 来快速配置：
> ```bash
> hermes config set stt.provider xiaomi-asr
> hermes config set stt.providers.xiaomi-asr.type command
> hermes config set stt.providers.xiaomi-asr.command "python C:/Users/<你的用户名>/.hermes/scripts/xiaomi-asr.py {input_path} {output_path} mimo-v2.5-asr {language}"
> hermes config set stt.providers.xiaomi-asr.language zh
> hermes config set stt.providers.xiaomi-asr.format txt
> hermes config set stt.providers.xiaomi-asr.timeout 120
> ```

### 4. 重启 Hermes

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

---

## 验证

创建一个测试音频文件并用脚本手动测试：

```bash
# 创建 3 秒 440Hz 正弦波测试音频
ffmpeg -y -f lavfi -i "sine=frequency=440:duration=3" -ar 16000 -ac 1 test.wav

# 手动测试（确保 XIAOMI_API_KEY 和 XIAOMI_BASE_URL 已导出为环境变量）
python C:/Users/<你的用户名>/.hermes/scripts/xiaomi-asr.py test.wav output.txt mimo-v2.5-asr zh

# 查看结果
cat output.txt
```

---

## 注意事项

| 问题 | 说明 |
|------|------|
| 音频格式 | 只支持 wav 和 mp3，其他格式自动通过 ffmpeg 转换 |
| 纯音乐 | 无法识别纯音乐内容，会返回空结果 |
| 语言 | 主要针对中文优化，其他语言效果较差 |
| ffmpeg | 非 wav/mp3 格式必须安装 ffmpeg |
| Windows 路径 | 建议在配置中使用**正斜杠**（`/`），Python 脚本内部会自动转换反斜杠 |
| 环境变量 | `XIAOMI_API_KEY` 必须在 `.env` 文件中，Hermes 会自动加载到子进程环境 |

---

## 文件清单

```
mimo-asr-for-hermes/
├── INSTALL.md         # 本安装说明
├── xiaomi-asr.py      # STT 适配脚本（Python）
└── xiaomi-asr.sh      # STT 适配脚本（Bash，仅 Linux/macOS）
```