diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 110 |
1 files changed, 87 insertions, 23 deletions
@@ -2,47 +2,77 @@ 将小米 MiMo ASR 语音识别模型接入 Hermes 的语音转文字功能。 +本版本针对 **Windows + Hermes Desktop** 进行了适配，使用纯 Python 实现，不依赖 bash/git-bash 环境。 + +--- + ## 前置条件 -- Hermes Agent 已安装 -- Xiaomi MiMo API Key（https://platform.xiaomimimo.com 获取） -- ffmpeg（用于音频格式转换）：`brew install ffmpeg` +- 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） +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 插件。 +### 为什么用 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 -cp xiaomi-asr.sh ~/.hermes/scripts/xiaomi-asr.sh -chmod +x ~/.hermes/scripts/xiaomi-asr.sh +mkdir -p ~/.hermes/scripts +cp xiaomi-asr.py ~/.hermes/scripts/xiaomi-asr.py ``` ### 2. 配置环境变量 -在 `~/.hermes/.env` 中添加（如果还没有）： +在 `D:\Program Files\Hermes\.env`（或 `$env:HERMES_HOME\.env`，视你的安装位置而定）中添加： -``` -XIAOMI_API_KEY=your_api_key_here +```env +# Xiaomi MiMo ASR +XIAOMI_API_KEY=你的API_Key XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1 ``` -> 如果你的 API Key 绑定的是国际站，用 `https://api.xiaomimimo.com/v1` +> 中国站用户：`https://token-plan-cn.xiaomimimo.com/v1` +> 国际站用户：`https://api.xiaomimimo.com/v1` ### 3. 修改 Hermes 配置 -在 `~/.hermes/config.yaml` 的 `stt` 部分： +编辑 `D:\Program Files\Hermes\config.yaml`（或 `$env:HERMES_HOME\config.yaml`）的 `stt` 部分： ```yaml stt: @@ -51,27 +81,48 @@ stt: providers: xiaomi-asr: type: command - command: ~/.hermes/scripts/xiaomi-asr.sh {input_path} {output_path} mimo-v2.5-asr {language} + 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 / TUI：关闭并重新打开 -- Gateway：运行 `/restart` +- **Desktop**：关闭并重新打开 +- **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 +# 创建 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 ``` +--- + ## 注意事项 | 问题 | 说明 | @@ -80,3 +131,16 @@ cat /tmp/output.txt | 纯音乐 | 无法识别纯音乐内容，会返回空结果 | | 语言 | 主要针对中文优化，其他语言效果较差 | | 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） +``` |