ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.2

为 https://huggingface.co/hexgrad/Kokoro-82M 文本转语音模型提供的Docker化FastAPI封装器。可在几分钟内生成数小时的高质量语音。

• OpenAI兼容的语音端点，多语言支持
• 英语（美国/英国）、西班牙语、法语、印地语、意大利语、日语、巴西葡萄牙语、普通话
• 可选的集成WebUI；跟读式长文本生成
• 内联多说话人生成与语音混合 + 别名加权组合，支持SSML
• 逐词或逐块带时间戳的字幕生成
• 音素端点：从文本生成音素，或从音素生成音频
• 预构建的多平台镜像
• CPU和NVIDIA GPU（CUDA）：linux/amd64 + linux/arm64
• AMD GPU（ROCm，实验性）：仅linux/amd64
• 通过UV直接运行时支持Apple Silicon（MPS）（无镜像）

集成指南

快速开始

最快启动（docker run）

预构建的多架构镜像，内置模型。

:latest 标签可用，但为确保稳定使用，请固定到发布标签。

无GPU（笔记本电脑、纯CPU服务器）

docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

NVIDIA（GTX 900系列至RTX 40系列；内置cu126）

docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

NVIDIA RTX 50系列/Blackwell（内置cu128）

docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest-cu128

NVIDIA arm64（Jetson、GH200；相同标签，内置cu129）

docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

AMD GPU（ROCm，实验性，仅x86_64）

docker run --device=/dev/kfd --device=/dev/dri -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-rocm:latest

Apple Silicon（原生MPS克隆；CPU镜像也可运行）

./start-gpu_mac.sh

gpu:latest 与 gpu:latest-cu126 为同一镜像。通过环境变量进行配置，详见配置指南。

快速启动（docker compose）

1. 安装先决条件，并使用Docker Compose启动服务（完整设置，包括UI）：

• 安装https://www.docker.com/products/docker-desktop/
• 克隆仓库：

git clone https://github.com/remsky/Kokoro-FastAPI.git
cd Kokoro-FastAPI

cd docker/gpu # 用于NVIDIA GPU支持
# 或 cd docker/cpu # 用于CPU支持
# 或 cd docker/rocm # 用于AMD GPU（ROCm，实验性，仅amd64）
docker compose up --build

#
> [!NOTE] Apple Silicon（M1/M2/M3）用户注意：
# Docker GPU镜像仅支持CUDA，无法在Apple Silicon上运行。使用Docker时，请使用`docker/cpu`。
# 如需原生MPS（Apple GPU）加速，请通过UV直接运行 `./start-gpu_mac.sh`。

cd ../.. # 返回仓库根目录，以便使用以下路径

# 模型将自动下载，如有需要也可手动下载：
python docker/scripts/download_model.py --output api/src/models/v1_0

配置指南涵盖了镜像与构建、卷挂载以及环境变量的相关内容。

直接运行（通过uv）

1. 安装先决条件：

• 安装astral-uv
• 如需将其作为未知单词/发音的备用方案，请在系统中安装https://github.com/espeak-ng/espeak-ng。上游库可能会尝试处理此问题，但结果参差不齐。
• 克隆仓库：

git clone https://github.com/remsky/Kokoro-FastAPI.git
cd Kokoro-FastAPI

如果尚未运行https://github.com/remsky/Kokoro-FastAPI/blob/master/docker/scripts/download_model.py，请先运行

通过UV直接启动（带热重载）

Linux和macOS

./start-cpu.sh OR
./start-gpu.sh

Windows

.\start-cpu.ps1 OR
.\start-gpu.ps1

启动并运行？

作为OpenAI兼容的语音端点在本地运行

from openai import OpenAI

client = OpenAI(
base_url="http://localhost:8880/v1", api_key="not-needed"
)

with client.audio.speech.with_streaming_response.create(
model="kokoro",
voice="af_sky+af_bella", # 单个或多个语音包组合
input="Hello world!"
) as response:
response.stream_to_file("output.mp3")

• API将在 http://localhost:8880 可用

• API文档：http://localhost:8880/docs

• Web界面：http://localhost:8880/web

功能

核心功能

OpenAI兼容的语音端点

# 使用OpenAI的Python库
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")
response = client.audio.speech.create(
model="kokoro",
voice="af_bella+af_sky", # 详见 /api/src/core/openai_mappings.json 进行自定义
input="Hello world!",
response_format="mp3"
)

response.stream_to_file("output.mp3")

或通过Requests：

import requests

response = requests.get("http://localhost:8880/v1/audio/voices")
voices = [v["id"] for v in response.json()["voices"]]

# 生成音频
response = requests.post(
"http://localhost:8880/v1/audio/speech",
json={
"model": "kokoro",
"input": "Hello world!",
"voice": "af_bella",
"response_format": "mp3", # 支持：mp3, wav, opus, flac, aac, pcm
"speed": 1.0
}
)

# 保存音频
with open("output.mp3", "wb") as f:
f.write(response.content)

快速测试（从另一个终端运行）：

python examples/assorted_checks/test_openai/test_openai_tts.py # 测试OpenAI兼容性
python examples/assorted_checks/test_voices/test_all_voices.py # 测试所有可用语音

流式支持

# OpenAI兼容流式
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8880/v1", api_key="not-needed")

# 流式保存到文件
with client.audio.speech.with_streaming_response.create(
model="kokoro",
voice="af_bella",
input="Hello world!"
) as response:
response.stream_to_file("output.mp3")

# 流式播放（需要PyAudio）
import pyaudio
player = pyaudio.PyAudio().open(
format=pyaudio.paInt16,
channels=1,
rate=24000,
output=True
)

with client.audio.speech.with_streaming_response.create(
model="kokoro",
voice="af_bella",
response_format="pcm",
input="Hello world!"
) as response:
for chunk in response.iter_bytes(chunk_size=1024):
player.write(chunk)

或通过requests：

import requests

response = requests.post(
"http://localhost:8880/v1/audio/speech",
json={
"input": "Hello world!",
"voice": "af_bella",
"response_format": "pcm"
},
stream=True
)

for chunk in response.iter_content(chunk_size=1024):
if chunk:
# 处理流式块
pass

关键流式指标：

• 首令牌延迟 @ 块大小
• ~300ms（GPU）@ 400
• ~3500ms（CPU）@ 200（旧款i7）
• ~

多种输出音频格式

• mp3
• wav
• opus
• flac
• aac
• pcm

语音

语音组合

• 使用比例进行加权语音组合（例如，"af_bella(2)+af_heart(1)" 表示67%/33%混合）
• 比例会自动归一化至总和100%
• 通过在任何端点的语音名称后添加括号内的权重即可使用
• 保存生成的语音包以供将来使用

语音别名

加权混合可能会很快变得冗长。voice_aliases 为每个请求映射一个短名称，适用于 voice 字段和 [voice:...] 标签：

• 别名优先不区分大小写匹配（建议使用小写以避免不一致）。
• 指向不存在语音的别名会返回 400。
• Web UI 的 cast 导出格式相同（例如 {"voice_aliases": {...}}），可与 API 调用互换。

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")

client.audio.speech.create(
model="kokoro",
voice="narrator",
input="[voice:narrator] Once upon a time. [voice:villain] Never!",
extra_body={
"allow_voice_tags": True,
"voice_aliases": {"narrator": "af_bella(2)+af_sky", "villain": "am_michael"},
},
)

或

curl -X POST http://localhost:8880/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{
"model": "kokoro",
"voice": "narrator",
"input": "[voice:narrator] Once upon a time. [voice:villain] Never!",
"allow_voice_tags": true,
"voice_aliases": {"narrator": "af_bella(2)+af_sky", "villain": "am_michael"},
"response_format": "mp3"
}' --output aliased.mp3

音素与令牌路由

将文本转换为音素和/或直接从音素生成音频：

import requests

def get_phonemes(text: str, language: str = "a"):
    """获取输入文本的音素和令牌"""
    response = requests.post(
        "http://localhost:8880/dev/phonemize",
        json={"text": text, "language": language}  # "a" 表示美式英语
    )
    response.raise_for_status()
    result = response.json()
    return result["phonemes"], result["tokens"]

def generate_audio_from_phonemes(phonemes: str, voice: str = "af_bella"):
    """从音素生成音频"""
    response = requests.post(
        "http://localhost:8880/dev/generate_from_phonemes",
        json={"phonemes": phonemes, "voice": voice},
        headers={"Accept": "audio/wav"}
    )
    if response.status_code != 200:
        print(f"错误: {response.text}")
        return None
    return response.content

# 示例用法
text = "Hello world!"
try:
    # 将文本转换为音素
    phonemes, tokens = get_phonemes(text)
    print(f"音素: {phonemes}")  # 例如 ðɪs ɪz ˈoʊnli ɐ tˈɛst
    print(f"令牌: {tokens}")  # 包含起始/结束令牌的令牌 ID

    # 生成并保存音频
    if audio_bytes := generate_audio_from_phonemes(phonemes):
        with open("speech.wav", "wb") as f:
            f.write(audio_bytes)
        print(f"生成了 {len(audio_bytes)} 字节的音频")
except Exception as e:
    print(f"错误: {e}")

有关示例脚本，请参见 examples/phoneme_examples/generate_phonemes.py。

底层为宿主 + CUDA 上下文。可从 examples/ 目录执行 uv run --extra benchmarks assorted_checks/benchmarks/benchmark_model_unload.py 复现。

转录往返测试（WER/CER）

端到端往返测试流程：使用 Kokoro 合成语音，通过 https://github.com/SYSTRAN/faster-whisper 将结果转录回文本，再与源文本对比。相关脚本和数据位于 examples/assorted_checks/test_transcription/ 目录下。

长文本英文测试（完整书籍《地心游记》，古腾堡计划，语音 af_heart，CUDA float16 上的 base.en Whisper 模型，基准测试基于 cu126 GPU 构建捕获）：

完整回归区间详见 examples/assorted_checks/test_transcription/BASELINE.md。

多语言检查（每种语音一句单句，多语言 Whisper small 模型。拉丁语系使用 WER，日语/中文/印地语使用 CER）：

[!NOTE] 注意：这些测试仅使用单句短文本，并非全面的语言质量基准。它们仅用于确认每种语音能生成目标语言的可转录音频；更深入的语言质量评估仍需开展。

复现方法参见 examples/assorted_checks/test_transcription/README.md。

配置变量

所有设置均为环境变量，或项目根目录下 .env 文件中的一行。完整参考见 配置指南。

调试端点

用于调试资源耗尽或性能问题的系统状态和资源使用情况端点。/debug/* 路由会暴露宿主和进程内部信息，因此默认关闭；需设置 ENABLE_DEBUG_ENDPOINTS=true 启用。

• /debug/threads - 获取线程信息和堆栈跟踪
• /debug/storage - 各挂载分区的磁盘使用情况
• /debug/system - 获取系统信息（CPU、内存、GPU）
• POST /dev/unload - 从 VRAM 释放模型；下次请求时会延迟重新加载。默认关闭；需设置 ALLOW_DEV_UNLOAD=true 启用

稳定性说明：/v1/* OpenAI 兼容路由为稳定 API。/dev/* 和 /debug/* 为运维辅助端点，次要版本间可能变更或需通过标志启用。

日志

可通过 API_LOG_LEVEL 环境变量设置全局 API https://loguru.readthedocs.io/en/stable/api/logger.html#levels。默认值为 DEBUG。各运行方法的日志设置详见 配置指南。

已知问题与故障排除

缺失词语和部分时间戳

API 会对输入文本进行标准化处理，可能错误移除或修改部分短语。可在请求 JSON 中设置 "normalization_options":{"normalize": false} 禁用标准化：

import requests

response = requests.post(
"http://localhost:8880/v1/audio/speech",
json={
"input": "Hello world!",
"voice": "af_heart",
"response_format": "pcm",
"normalization_options":
{
"normalize": False
}
},
stream=True
)

for chunk in response.iter_content(chunk_size=1024):
if chunk:
# 处理流式 chunk
pass

Linux GPU 权限

容器组、宿主组和设备权限选项详见 docs/troubleshooting.md#linux-gpu-permissions。

AMD GPU（ROCm）故障排除

HSA 覆盖、MIOpen 预热、hipBLAS 回退及原生 Linux 宿主要求详见 docs/troubleshooting.md#amd-gpu-rocm。

部分读取器中 WAV 时长显示异常

WAV 响应在头部大小字段使用流式标记（0xFFFFFFFF）。大多数读取器可正常处理：soundfile、pydub/ffmpeg、浏览器、系统播放器。Python 标准库 wave 无法处理，会显示错误时长。如需准确时长，可使用 soundfile.info(path).duration 或 ffprobe。

项目

版本控制与开发

分支策略：

• release 分支： 包含最新稳定构建，推荐生产环境使用。特定版本标签的 Docker 镜像由此分支构建。
• master 分支： 活跃开发分支。包含实验性功能、进行中的变更及未发布修复。用于获取最新代码，稳定性较低。此分支不发布镜像；:latest 标签与其他版本标签一样，均从 release 分支构建。

注意：本项目本质上是一个以开发为核心的项目。

如遇问题，若出现异常情况，你可能需要回退到发布标签中的某个版本，或从源码构建和/或排查问题并提交 PR。

自由开源是社区共同努力的结果，而每个人的时间都是有限的。如果你想支持本项目，欢迎提交 PR、请我喝杯咖啡，或报告使用过程中发现的任何 bug/功能需求等。

如需开发代码，或让 AI 代理处理代码？AGENTS.md 涵盖了仓库布局、命令和约定。

模型

本 API 使用 HuggingFace 上的 https://huggingface.co/hexgrad/Kokoro-82M 模型。

访问模型页面了解训练、架构和功能的更多详情。我与该模型的开发工作无任何关联，开发此封装器仅为方便使用和个人项目。

许可证

本项目采用 Apache License 2.0 许可证 - 详情如下：

• Kokoro 模型权重采用 Apache 2.0 许可证（见 https://huggingface.co/hexgrad/Kokoro-82M）
• 本仓库中的 FastAPI 封装器代码为匹配模型许可证，同样采用 Apache 2.0 许可证
• 改编自 StyleTTS2 的推理代码采用 MIT 许可证

完整的 Apache 2.0 许可证文本见：https://www.apache.org/licenses/LICENSE-2.0

项目结构与变更

贡献者

使用 contrib.rocks 生成。