Kokoro-82M从安装到配置到使用-平芜编程栈

Kokoro-82M ：从安装到配置到使用

面向中文用户的完整上手指南，覆盖环境准备、模型与音色下载、本地脚本体验、HTTP 服务启动与部署、可调配置项，以及常见问题排查。

概览

项目定位：开源、轻量的 TTS（文本转语音）模型，质量与速度兼顾，适合本地与生产部署。
代码入口：本地脚本示例kkrpy/run_kokoro.py，HTTP 服务kokoro_service.py。
语言与音色：当前示例默认中文（lang_code='z'），可切换到其他语言与音色。

环境与依赖

Python：建议 3.9+，使用虚拟环境管理依赖。
必需库：torch、kokoro>=0.9.2、soundfile。
可选组件：espeak-ng（语音学标注回退，非必须；Linux 下可用apt安装）。

安装示例（Windows/通用）：

python-m venv.venv.venv\Scripts\Activate.ps1 pip install--upgrade pip pip install torch kokoro>=0.9.2 soundfile# 其他依赖pip install ordered-setpip install cn2an pip install pypinyin_dict

Linux 可选安装espeak-ng：

sudoapt-get-yinstallespeak-ng

模型与音色下载

模型和音色下载

export HF_ENDPOINT=https://hf-mirror.com # 引入镜像地址 huggingface-cli download --resume-download hexgrad/Kokoro-82M --local-dir ./ckpts/kokoro-v1.0 huggingface-cli download --resume-download hexgrad/Kokoro-82M-v1.1-zh --local-dir ./ckpts/kokoro-v1.1

kokoro_service.py和脚本示例都从本地./ckpts/kokoro-v1.1加载权重与音色。你可以从 Hugging Face 下载到该目录结构：

./ckpts/kokoro-v1.1/ kokoro-v1_1-zh.pth config.json voices/ zf_001.pt af_maple.pt

使用huggingface_hub进行下载（示例）：

fromhuggingface_hubimporthf_hub_downloadimportos target_dir="./ckpts/kokoro-v1.1"os.makedirs(os.path.join(target_dir,"voices"),exist_ok=True)repo_id="hexgrad/Kokoro-82M-v1.1-zh"hf_hub_download(repo_id=repo_id,filename="kokoro-v1_1-zh.pth",local_dir=target_dir)hf_hub_download(repo_id=repo_id,filename="config.json",local_dir=target_dir)# 示例音色（根据需要可更换/增加）hf_hub_download(repo_id=repo_id,filename="voices/zf_001.pt",local_dir=target_dir)hf_hub_download(repo_id=repo_id,filename="voices/af_maple.pt",local_dir=target_dir)

若你使用其他语言与音色，请在对应仓库下选择合适的voices/*.pt文件，并放入voices/目录。

快速体验（本地脚本）

仓库已提供中文脚本示例kkrpy/run_kokoro.py，直接运行将生成output.wav：

python kkrpy/run_kokoro.py

合成逻辑与路径在kkrpy/run_kokoro.py中配置（加载模型、音色、调用KPipeline完成推理）。

启动 HTTP 服务

服务脚本位于kokoro_service.py，默认监听PORT环境变量（缺省8000）。

$env:PORT="8000"python kokoro_service.py

请求路径：POST /synthesize，请求体为 JSON：{"text": "待合成的中文文本"}。
响应内容：audio/wav数据，响应头包含X-RTF（实时因子，越小越快）。

示例请求（PowerShell）：

Invoke-WebRequest-Uri"http://localhost:8000/synthesize"`-Method POST `-ContentType"application/json"`-Body'{"text":"你好，欢迎使用 Kokoro 中文 TTS 服务。"}'`-OutFile"out.wav"

示例请求（curl）：

curl-s -X POST"http://localhost:8000/synthesize"\-H"Content-Type: application/json"\-d'{"text":"你好，欢迎使用 Kokoro 中文 TTS 服务。"}'\--output out.wav -D -

可调配置项

核心配置在kokoro_service.py：

设备选择：自动cuda或cpu（e:\code\personal\Kokoro-82M\kokoro_service.py:16）。
模型路径：model_path与config_path（e:\code\personal\Kokoro-82M\kokoro_service.py:17-18）。
语言代码：中文为lang_code='z'（e:\code\personal\Kokoro-82M\kokoro_service.py:20）。
默认音色：voice_zf = "zf_001"与voice_af = "af_maple"（e:\code\personal\Kokoro-82M\kokoro_service.py:11,13）。
端口：读取环境变量PORT（e:\code\personal\Kokoro-82M\kokoro_service.py:60）。

如需更换音色，替换音色文件名并确保对应.pt存在于voices/：

voice_zf="zf_001"# 改为你的中文女声/男声音色 IDvoice_af="af_maple"# 英文音色示例，如不需要可移除

更换语言：将KPipeline(lang_code='z')替换为其他语言代码，并使用匹配语言的音色文件与模型/配置。

生产部署（Linux）

项目包含一键安装脚本install_kokoro_service.sh（systemd 服务），支持控制启动/停止：

# 以当前用户创建/启动服务，端口 8000SVC_NAME=kokoroPORT=8000./install_kokoro_service.sh# 控制服务./install_kokoro_service.sh start ./install_kokoro_service.sh status ./install_kokoro_service.sh restart ./install_kokoro_service.sh stop

关键参数：

SVC_NAME：服务名（默认kokoro）。
PORT：监听端口（默认8000）。
SVC_USER：运行服务的用户（默认当前用户）。
PYTHON_BIN：Python 解释器路径（默认优先~/.venvs/kokoro/bin/python，否则python3）。

脚本会写入/etc/systemd/system/${SVC_NAME}.service并执行daemon-reload，随后启用并启动服务。

Windows 暂不使用 systemd，可通过任务计划、NSSM 或以简单命令行前台方式运行。

常见问题

CUDA 不可用：自动回退到 CPU（速度较慢）；检查 GPU 驱动与torchCUDA 版本匹配。
soundfile 错误：安装libsndfile（Windows 通过pip install soundfile一般已打包；Linux 需apt-get install libsndfile1）。
文件未找到：确认./ckpts/kokoro-v1.1目录结构与模型/音色文件命名一致。
端口占用：修改PORT或释放占用端口再启动。
文本为空：服务会返回400（e:\code\personal\Kokoro-82M\kokoro_service.py:37-42）。