在Mac上跑 Kokoro TTS经验总结

在Mac上跑 Kokoro TTS经验总结

前言

Mac 开发阶段测试 TTS 音色，不需要买服务器，也不需要开发板。本文记录了从零在 Mac 上跑通 Kokoro TTS 的完整过程，以及踩过的坑。

适合读者：想在 Mac 本地测试 Kokoro TTS 音色的开发者。

---

环境

• Mac mini M4（Apple Silicon）
• macOS（Apple Silicon 架构）
• Python 3.12（通过 homebrew 安装）
• Rust 1.75+

---

Kokoro TTS 的多个实现版本

实现	语言	特点
thewh1teagle/kokoro-onnx	Python	最流行，ONNX 推理，Mac M1+ 可用
artisdom/kokoro-rs	Rust	跨平台，可交叉编译到 iOS/Android
doiito/kokoroi-rs	Rust	fork 自上述，略有不同
pguso/kokoro.git	Rust	英文专用，轻量

推荐 ：Python 选 kokoro-onnx，Rust 选 artisdom/kokoro-rs。

---

方法一：Python kokoro-onnx（推荐）

安装

pip install kokoro-onnx soundfile

下载模型文件

需要两个文件：

• kokoro-v1.0.onnx 或 kokoro-v1.1-zh.onnx --- TTS 模型
• voices-v1.0.bin --- voice embeddings（标准 NPZ 格式）

下载地址：

wget https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx
wget https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin

注意：GitHub 在国内可能访问困难，需要自备代理。

基本使用

from kokoro_onnx import Kokoro
import soundfile as sf

k = Kokoro('kokoro-v1.0.onnx', 'voices-v1.0.bin')

# 列出所有可用 voice
voices = k.get_voices()
print(voices[:5])  # ['af_alloy', 'af_aoede', 'af_bella', ...]

# 合成语音
audio, sr = k.create('Hello, this is a test.', voice='af_sarah')
sf.write('output.wav', audio, sr)

不同 voice 的音质对比

实测了 Kokoro 全部 54 个 voice（v1.0 voices），结论如下：

男声（全部干净，无电音）：

• am_adam、bm_george、hm_omega 等

女声（全部有不同程度的电音）：

• af_sarah、af_bella、af_nova 等
• 程度轻重不一，但没有一个是完全干净的

原因：这是当前 ONNX 模型 + v1.0 voices 组合的已知问题，女声的 voice embedding 值范围过大，vocoder 推理不稳定。

---

方法二：Rust kokoro-rs（Mac 可编译）

如果你想用 Rust 集成到项目里，或者想测试 ONNX 之外的实现。

安装 Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

克隆并编译

git clone https://github.com/artisdom/kokoro-rs.git
cd kokoro-rs
cargo build --release --examples

运行示例

# 英文合成
cargo run --example synth_directly_v10 --release -- \
  -m models/kokoro-v1.0.onnx \
  -d data/voices-v1.0.bin \
  -s af_sarah \
  -t "Hello, this is a test." \
  -o output.wav

# 中文合成（需要 v1.1 模型）
cargo run --example synth_directly_v11 --release -- \
  -m models/kokoro-v1.1-zh.onnx \
  -d data/voices-v1.1-zh.bin \
  -s zm_045 \
  -t "你好，这是测试。" \
  -o output.wav

下载模型文件

artisdom/kokoro-rs 的 README 说模型在这里下载：

https://github.com/mzdk100/kokoro/releases/tag/V1.1

包含 v1.0 和 v1.1 的 ONNX 模型及 voices 文件。

---

方法三：我们的 lensonai 项目自带的 Rust CLI

项目中已编译好 Mac 版本：

cd deps/kokoroi-rs
cargo build --release -p koko

./target/release/koko \
  -t "Hello, this is a test." \
  -m /path/to/kokoro-v1.0.onnx \
  -d /path/to/voices-v1.0.bin \
  -l en \
  -s af_sarah \
  -o output.wav

详细用法：

./target/release/koko --help

---

踩过的坑

坑 1：Python 版本问题

kokoro-onnx 需要 Python 3.10+，但 Mac 系统自带的 python3 可能是 3.9。

# 检查版本
python3 --version  # 可能是 3.9.6

# 用 Homebrew 安装新版
brew install python@3.12
/usr/local/bin/python3.12 -m pip install kokoro-onnx soundfile

坑 2：pip 和 python3 版本不匹配

装了新版 Python 后，pip 可能还是指向旧版：

# 确认 pip 对应正确的 Python
/usr/local/bin/python3.12 -m pip install kokoro-onnx
/usr/local/bin/python3.12 -c "import kokoro_onnx"  # 确认导入成功

坑 3：voice 文件格式混淆

kokoro 有多种 voice 文件格式：

格式	说明	能否用
voices-v1.0.bin（NPZ）	标准 NumPy ZIP，可用 np.load()	✅
voices-v1.1-zh.bin（bincode）	Rust bincode 编码，np.load() 报错	❌ 需特殊处理

v1.1 voices 文件用 Python 的 np.load() 会报错：

ValueError: This file contains pickled (object) data.

这是因为 v1.1 voices 是 Rust bincode 编码的 HashMap，不是 NumPy 格式。详见另文《Kokoro v1.1 voices 文件格式逆向分析》。

坑 4：中文 G2P 问题

kokoro-onnx 的中文 phonemization 用的是 espeak-ng，在 Mac 上可能没装：

# macOS 安装 espeak-ng
brew install espeak-ng

# 或者用项目的 Rust 实现（支持 jieba 中文分词）

如果 espeak-ng 缺失，中文合成会静默失败（生成空音频）。

坑 5：模型文件下载失败

GitHub 在国内访问不稳定。可以试试镜像：

# HuggingFace 镜像
curl -sI https://hf-mirror.com/thewh1teagle/kokoro-onnx/resolve/main/kokoro-v1.0.onnx

或者用代理：

export https_proxy=http://127.0.0.1:7890
wget https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx

---

性能

Mac M4 上实测：

模型	精度	文件大小	实时率
kokoro-v1.0	fp32	310MB	~0.9x（实时）
kokoro-v1.0	int8	88MB	~1.2x（实时）

M4 的 Neural Engine 对 ONNX 推理有加速，但实测比纯 CPU 并没有显著优势。内存占用约 1GB。

---

总结建议

1. 快速试用 ：直接 pip install kokoro-onnx，10 分钟跑通
2. 深度定制：用 Rust 版本，可交叉编译到 iOS/Android
3. 女声电音问题：v1.0 女声目前 Mac 上无法解决，等上游修复或换用 v1.1
4. 中文支持：v1.1 中文模型需要板端测试，Mac 上受 voices 格式限制

---

相关文档

• 《Kokoro v1.1 voices 文件格式逆向分析》--- 详细记录了 v1.1 voices 的 bincode 编码格式
• lensonai 项目：experience/TTS-VOICE-QUALITY.md --- 实际测试记录