在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（推荐）

安装

bash 复制代码

pip install kokoro-onnx soundfile

下载模型文件

需要两个文件：

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

下载地址：

bash 复制代码

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 在国内可能访问困难，需要自备代理。

基本使用

python 复制代码

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

bash 复制代码

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

克隆并编译

bash 复制代码

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

运行示例

bash 复制代码

# 英文合成
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 版本：

bash 复制代码

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

详细用法：

bash 复制代码

./target/release/koko --help

踩过的坑

坑 1：Python 版本问题

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

bash 复制代码

# 检查版本
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 可能还是指向旧版：

bash 复制代码

# 确认 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 上可能没装：

bash 复制代码

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

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

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

坑 5：模型文件下载失败

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

bash 复制代码

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

或者用代理：

bash 复制代码

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。

总结建议

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

在Mac上跑 Kokoro TTS经验总结