oboroge0/hayamimi · 上手攻略

仓库：oboroge0/hayamimi
链接：https://github.com/oboroge0/hayamimi
分类：语音识别 / 实时转录 / CPU 推理
作者：Tom
更新：2026-08-27

是什么

「早耳」（hayamimi，日语"快耳"之意）是一个纯 CPU 运行的实时多语言语音转文字工具，主打"开口即出字幕"的极低延迟体验。核心设计理念是：不用 GPU、不用云端 API、一台普通电脑 + 2GB 内存就能跑。

它不依赖 Whisper 单一模型打天下，而是通过 sherpa-onnx 调度一个包含 5 条路由的多模型 специалист 体系——每种语言自动路由到该语种最优的 ASR 模型，量化 INT8 ONNX 格式，全部 CPU 多线程运行。

解决什么问题

传统 CPU 实时转录方案的痛点： - 延迟高：Whisper 单模型在 CPU 上延迟通常 3–5 秒以上 - 精度差：非英语语言（尤其是日语、粤语等）WER/CER 远高于英语 - 依赖重：需要 PyTorch + CUDA + 大量显存，普通人用不了

hayamimi 的目标就是在没有独显的办公电脑上，实现接近实时的多语言字幕输出，延迟压到 ~100ms（说话停后 100ms 出最终文本），同时精度比 Whisper Large 还高一倍（实测日语广播 5.8% CER vs Whisper Large 13.8%）。

快速安装

前置条件：Python 3.10+，ffmpeg 在 PATH 环境变量中。

# 1. 克隆仓库
git clone https://github.com/oboroge0/hayamimi
cd hayamimi

# 2. 建立虚拟环境
python -m venv .venv

# 3. 安装依赖（Windows）
.venv\Scripts\pip install -r requirements.txt

# 3. 安装依赖（macOS / Linux）
.venv/bin/pip install -r requirements.txt

# 4. 下载预训练模型（约 3.1GB，全量；或 --minimal 只下日语/英语约 1.1GB）
.venv/bin/python scripts/download_models.py

# 5. 开始实时转录（默认用麦克风）
.venv/bin/python scripts/realtime_transcribe.py

# 6. 带 Dashboard + OBS 叠加层（浏览器打开 http://localhost:8833/dashboard）
.venv/bin/python scripts/realtime_transcribe.py --serve

Docker 方式（如有 docker 环境）：

docker run -it --rm \
  --device /dev/snd:/dev/snd \
  -p 8833:8833 \
  oboroge0/hayamimi
# 浏览器访问 http://localhost:8833/dashboard

⚠️ scripts/download_models.py 会下载约 3.1GB 模型文件到 models/ 目录（git-ignored），确保磁盘空间充足。--minimal 参数可降至 ~1.1GB（仅日语+英语）。

核心用法

麦克风实时转录

# 标准模式（麦克风输入，实时输出 partial + final 字幕）
.venv/bin/python scripts/realtime_transcribe.py

# 关闭 in-progress draft（只看完整句）
.venv/bin/python scripts/realtime_transcribe.py --no-partial

# 自定义线程数（默认 4，建议按 CPU 核心数来）
.venv/bin/python scripts/realtime_transcribe.py --threads 8

# 将字幕追加写入文件
.venv/bin/python scripts/realtime_transcribe.py --transcript output.txt

热词（Hotwords）支持

# 创建热词列表（每行一个词，支持专有名词）
echo "OpenAI" > my_hotwords.txt
echo "GPT-4" >> my_hotwords.txt

# 使用热词（在解码时 bias 向这些词，对日语 tier 目前无效——见坑节）
.venv/bin/python scripts/realtime_transcribe.py --hotwords my_hotwords.txt

⚠️ 当前 --hotwords 对日语 tier（ReazonSpeech）无效，因为 ReazonSpeech 的 byte-level BPE tokenizer 无法 encode 热词，运行时会警告具体失败数量。可改用 --replace 做后处理替换：

# 后处理 find/replace（对所有语言生效）
.venv/bin/python scripts/realtime_transcribe.py --replace "GPT-4:ChatGPT"

双语翻译

# 将日语转录结果实时翻译为英语（通过 FuguMT，质量较高）
.venv/bin/python scripts/realtime_transcribe.py --translate en

# 翻译为中文（通过 M2M-100）
.venv/bin/python scripts/realtime_transcribe.py --translate zh

# 翻译为韩语
.venv/bin/python scripts/realtime_transcribe.py --translate ko

# 翻译为西班牙语
.venv/bin/python scripts/realtime_transcribe.py --translate es

翻译参数支持 M2M-100 模型支持的任意目标语言代码。

OBS 直播叠加层

# 启动服务（本地 HTTP server，端口 8833）
.venv/bin/python scripts/realtime_transcribe.py --serve

# OBS 中添加 Browser Source，URL 填写：
#   http://localhost:8833/         # OBS 全功能叠加
#   http://localhost:8833/?show=final    # 只显示已确认文字
#   http://localhost:8833/?show=partial  # 只显示进行中文字
#   http://localhost:8833/transcript     # 纯滚动字幕历史

网络音频输入（手机 / ESP32 推流）

# 在目标机器上启动 hayamimi 监听 WebSocket
.venv/bin/python scripts/realtime_transcribe.py --input ws --serve

# 手机端推送音频（Python 依赖-free 参考客户端）
# ws://<host>:8766/ingest
# 协议：先发 JSON 帧 {"sr": 16000, "format": "pcm_s16le", "channels": 1}
# 然后持续发送 raw PCM 二进制音频帧

静默与语音时长参数

# 静默多久算一句话结束（默认 0.35s，越小截得越碎）
.venv/bin/python scripts/realtime_transcribe.py --min-silence 0.5

# 强制截断超长语音（默认 12s，防止一段话说太久没分割）
.venv/bin/python scripts/realtime_transcribe.py --max-speech 20.0

# 关闭二轮精修（省算力，延迟略增）
.venv/bin/python scripts/realtime_transcribe.py --no-refine

典型适用场景

场景	说明
直播字幕 / OBS 推流	`--serve` 输出浏览器叠加 URL，直接进 OBS Browser Source
会议记录	`--transcript` 写入文件，配合 `--translate` 出双语记录
日语/中文/韩语/粤语实时翻译	`--translate` 实时出译文，不依赖云 API
嵌入式设备推流	`--input ws` 接受手机/ESP32 网络音频，本体在服务器转录
无 GPU 环境	纯 CPU INT8 ONNX，10–50× 实时（在 6 核桌面 CPU 上）
多语言混合会议	5 路由体系自动区分 ja/zh/ko/yue/en+24 种欧盟语言

坑与注意

--hotwords 对日语无效：ReazonSpeech 的 byte-level BPE tokenizer 无法 encode 热词，会在启动时 warn 具体失败数量。临时解法是用 --replace 后处理替换，或者等待上游 ReazonSpeech 支持。
模型下载量大：全量 download_models.py ~3.1GB，--minimal ~1.1GB。下载慢可以手动从各模型 huggingface 页面下载后放到 models/ 目录。
macOS / Linux 尚未 CI 全流程测试：项目在 Windows 11 上开发并 CI 测试；macOS/Linux 理论上可用，但 full pipeline 未被 CI 覆盖，遇到问题欢迎提 issue。
只有一位说话人标签而非完整说话人分离：--speakers 输出的 S1/S2 等标签基于 CAM++ 说话人嵌入，是轮次检测（turn-taking detection），不是完整说话人日志（diarization），多说话人场景下标签会混乱。
二轮精修（Refine）仅支持日语：2s 静默后的 batch re-decode 精度提升目前仅针对日语（CER 15.5% → 12.0%），其他语言关闭 --no-refine 即可跳过此步。
内存上限默认 <2GB：LRU eviction 机制确保多模型不超过 2GB 总内存，但 --max-resident 0 可解除限制。
依赖 ffmpeg 在 PATH：录音和音频处理依赖 ffmpeg，Windows 用户需单独安装并加入 PATH。

与同类对比

方案	延迟	CPU only	多语言路由	翻译	开源	模型大小
hayamimi	~100ms（final）	✅	✅ 5路专业模型	✅（FuguMT/M2M-100）	✅ MIT	~3.1GB
Whisper（本地）	3–5s+	✅	❌ 单模型	❌	✅	1.5–3GB
DeepSpeech	秒级	✅	❌	❌	✅	~200MB
Whisper API（云）	取决于网络	❌	❌	✅	❌	—
开源多语言方案（Coqui等）	秒级	✅	有限	有限	✅	各异

核心差异：hayamimi 不是另一个 Whisper 替代品，而是一个专为多语言实时字幕设计的多模型路由系统。在日语场景下 5.8% CER vs Whisper 13.8% 的优势来自于针对日语优化的 ReazonSpeech 模型，而非模型尺寸更大。

一句话推荐结论

"不需要 GPU、不需要网络、只需要麦克风和 2GB 内存，就能跑出比 Whisper 更准的日语实时字幕 + 20+语言翻译"——适合直播推流、多语言会议记录、无网环境下的语音转写场景。

来源：GitHub README（https://github.com/oboroge0/hayamimi）+ docs/SCORECARD.md（CER 数据）+ docs/TRANSLATE_M2M.md（翻译质量）+ docs/GOALS.md（延迟目标）。CER 数据来自 docs/SCORECARD.md（真实广播日语音频测试集），对比的是 whisper-large-v3-turbo。⚠️ 翻译语言质量标注（zh/ko/es "measured quality"）来自 docs/TRANSLATE_M2M.md，其他 M2M-100 目标语言未做质量测量。