summaryrefslogtreecommitdiff
path: root/INSTALL.md
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL.md')
-rw-r--r--INSTALL.md176
1 files changed, 92 insertions, 84 deletions
diff --git a/INSTALL.md b/INSTALL.md
index f3bcae0..425c01a 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,68 +1,67 @@
-# Xiaomi MiMo ASR (mimo-v2.5-asr) — Hermes STT 安装说明
+# MiMo V2.5 ASR — 安装说明（给 Agent 看）
-将小米 MiMo ASR 语音识别模型接入 Hermes 的语音转文字功能。
-
-本版本针对 **Windows + Hermes Desktop** 进行了适配，使用纯 Python 实现，不依赖 bash/git-bash 环境。
-
----
+> **提示**：如果你已经安装过其他 MiMo 插件（如 mimo-tts、mimo-websearch）并已配置过 `XIAOMI_API_KEY` 和 `XIAOMI_BASE_URL`，可以直接复用已有的环境变量配置，无需重复询问 API Key 和端点。
## 前置条件
-- Hermes Agent 已安装且正常运行
-- Xiaomi MiMo API Key（[https://platform.xiaomimimo.com](https://platform.xiaomimimo.com) 获取）
+- Hermes Agent 已安装并可运行
+- Xiaomi MiMo API Key（获取地址：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 脚本？
+> **注意**：`setup.sh` 仅供参考，请勿直接运行。请阅读以下步骤，根据用户的环境自行完成安装。
+> 以下命令中的 `~/.hermes` 仅为 Unix 典型路径，**不要硬编码**。安装前请先确认 Hermes 的实际安装目录（如 `$HERMES_HOME`、`$env:HERMES_HOME` 等）。
-Hermes 在 Windows 上通过 **cmd.exe** 执行 command provider，cmd.exe **不识别**：
-- `~` 波浪号（不会展开为用户目录）
-- `.sh` 扩展名（不知道用什么程序打开）
+### 方式一：Plugin 模式（推荐）
-Python 脚本（`.py`）可以被 `python` 解释器直接调用，无上述问题。
+将插件文件复制到 Hermes 插件目录并启用：
----
+```bash
+mkdir -p ~/.hermes/plugins/stt/mimo
+cp plugin.yaml __init__.py provider.py ~/.hermes/plugins/stt/mimo/
+hermes plugins enable stt/mimo
+```
-## 安装步骤
+```powershell
+# Windows (PowerShell)
+mkdir -Force "$env:USERPROFILE\.hermes\plugins\stt\mimo"
+cp plugin.yaml,__init__.py,provider.py "$env:USERPROFILE\.hermes\plugins\stt\mimo\"
+hermes plugins enable stt/mimo
+```
-### 1. 复制脚本
+安装后配置：
-将 `xiaomi-asr.py` 复制到 Hermes 的脚本目录：
+```bash
+hermes config set stt.provider mimo-asr
+hermes config set stt.providers.mimo-asr.type plugin
+# 重启 session 生效（/reset）
+```
-```powershell
-# 创建脚本目录（如果不存在）
-mkdir $env:USERPROFILE\.hermes\scripts -Force
+### 方式二：Command 模式
-# 复制脚本
-copy .\xiaomi-asr.py $env:USERPROFILE\.hermes\scripts\xiaomi-asr.py
-```
+适用于不希望以插件形式加载，或需要自定义脚本路径的场景。
-或在 bash (git-bash) 中：
+#### 1. 复制脚本
```bash
mkdir -p ~/.hermes/scripts
cp xiaomi-asr.py ~/.hermes/scripts/xiaomi-asr.py
+cp xiaomi-asr.sh ~/.hermes/scripts/xiaomi-asr.sh
+chmod +x ~/.hermes/scripts/xiaomi-asr.*
+```
+
+```powershell
+# Windows (PowerShell) — 仅需要 .py 脚本
+mkdir -Force "$env:USERPROFILE\.hermes\scripts"
+cp xiaomi-asr.py "$env:USERPROFILE\.hermes\scripts\xiaomi-asr.py"
```
-### 2. 配置环境变量
+#### 2. 配置环境变量
-在 `D:\Program Files\Hermes\.env`（或 `$env:HERMES_HOME\.env`，视你的安装位置而定）中添加：
+在 Hermes 的 `.env` 文件中添加：
```env
-# Xiaomi MiMo ASR
XIAOMI_API_KEY=你的API_Key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
```
@@ -70,77 +69,86 @@ XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
> 中国站用户：`https://token-plan-cn.xiaomimimo.com/v1`
> 国际站用户：`https://api.xiaomimimo.com/v1`
-### 3. 修改 Hermes 配置
+#### 3. 修改 Hermes 配置
-编辑 `D:\Program Files\Hermes\config.yaml`（或 `$env:HERMES_HOME\config.yaml`）的 `stt` 部分：
+编辑 Hermes 的 `config.yaml` 的 `stt` 部分：
```yaml
stt:
enabled: true
- provider: xiaomi-asr
+ provider: mimo-asr
providers:
- xiaomi-asr:
+ mimo-asr:
type: command
- command: python C:/Users/<你的用户名>/.hermes/scripts/xiaomi-asr.py {input_path} {output_path} mimo-v2.5-asr {language}
+ command: python ~/.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
-> ```
+> **Windows 注意**：命令路径需用正斜杠，如 `python C:/Users/<用户名>/.hermes/scripts/xiaomi-asr.py ...`
-### 4. 重启 Hermes
+或使用 `hermes config set`：
-- **Desktop**：关闭并重新打开
-- **Gateway**：运行 `/restart`
+```bash
+hermes config set stt.provider mimo-asr
+hermes config set stt.providers.mimo-asr.type command
+hermes config set stt.providers.mimo-asr.command "python ~/.hermes/scripts/xiaomi-asr.py {input_path} {output_path} mimo-v2.5-asr {language}"
+hermes config set stt.providers.mimo-asr.language zh
+hermes config set stt.providers.mimo-asr.format txt
+hermes config set stt.providers.mimo-asr.timeout 120
+```
----
+#### 4. 重启 Hermes
-## 验证
+- **Desktop**：关闭并重新打开
+- **Gateway**：运行 `/restart`
-创建一个测试音频文件并用脚本手动测试：
+## 独立使用（不依赖 Hermes）
```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
+export XIAOMI_API_KEY="your-key-here"
+export XIAOMI_BASE_URL="https://token-plan-cn.xiaomimimo.com/v1"
-# 查看结果
+python3 xiaomi-asr.py audio.wav output.txt mimo-v2.5-asr zh
cat output.txt
```
----
+```powershell
+# Windows (PowerShell)
+$env:XIAOMI_API_KEY="your-key-here"
+$env:XIAOMI_BASE_URL="https://token-plan-cn.xiaomimimo.com/v1"
-## 注意事项
+python xiaomi-asr.py audio.wav output.txt mimo-v2.5-asr zh
+type output.txt
+```
-| 问题 | 说明 |
-|------|------|
-| 音频格式 | 只支持 wav 和 mp3，其他格式自动通过 ffmpeg 转换 |
-| 纯音乐 | 无法识别纯音乐内容，会返回空结果 |
-| 语言 | 主要针对中文优化，其他语言效果较差 |
-| ffmpeg | 非 wav/mp3 格式必须安装 ffmpeg |
-| Windows 路径 | 建议在配置中使用**正斜杠**（`/`），Python 脚本内部会自动转换反斜杠 |
-| 环境变量 | `XIAOMI_API_KEY` 必须在 `.env` 文件中，Hermes 会自动加载到子进程环境 |
+## 卸载
----
+```bash
+hermes plugins disable stt/mimo
+rm -rf ~/.hermes/plugins/stt/mimo
+rm -f ~/xiaomi-asr.py ~/xiaomi-asr.sh
+```
-## 文件清单
+```powershell
+# Windows (PowerShell)
+hermes plugins disable stt/mimo
+rm -Recurse -Force "$env:USERPROFILE\.hermes\plugins\stt\mimo"
+rm -Force "$env:USERPROFILE\xiaomi-asr.py","$env:USERPROFILE\xiaomi-asr.sh"
+```
+
+## 验证
+```bash
+ffmpeg -y -f lavfi -i "sine=frequency=440:duration=3" -ar 16000 -ac 1 test.wav
+python3 xiaomi-asr.py test.wav output.txt mimo-v2.5-asr zh
+cat output.txt
```
-mimo-asr-for-hermes/
-├── INSTALL.md # 本安装说明
-├── xiaomi-asr.py # STT 适配脚本（Python）
-└── xiaomi-asr.sh # STT 适配脚本（Bash，仅 Linux/macOS）
+
+```powershell
+# Windows (PowerShell)
+ffmpeg -y -f lavfi -i "sine=frequency=440:duration=3" -ar 16000 -ac 1 test.wav
+python xiaomi-asr.py test.wav output.txt mimo-v2.5-asr zh
+type output.txt
```
generated by cgit v1.3.1 (git 2.54.0) at 2026-07-29 23:39:06 +0000