remsky/Kokoro-FastAPI

Kokoro-FastAPI – Docker 化的 OpenAI 兼容 TTS 服务

简介 – 一个开箱即用的 FastAPI 服务器，封装了 Kokoro-82M 文字转语音模型（一个 8200 万参数的多语言 TTS 模型）。该服务器模拟了 OpenAI 的 audio/speech 端点，因此现有的 OpenAI 客户端库无需修改即可使用。它以多架构 Docker 镜像（CPU、NVIDIA-CUDA、AMD-ROCm、Apple-Silicon）形式发布，也可以直接使用 uv 启动。

主要功能

• OpenAI 兼容语音 API – POST /v1/audio/speech 接受相同的 JSON 字段（model、voice、input、response_format、speed 等），并返回 mp3、wav、opus、flac、aac 或原始 PCM 格式的音频。
• 流式传输 – OpenAI 客户端和标准 requests 均可逐块接收音频，实现低首字延迟的实时播放（GPU 上约 300 毫秒，现代 M 系列 CPU 上约 1 秒）。
• 多语言语音 – 英语（美式/英式）、西班牙语、法语、印地语、意大利语、日语、巴西葡萄牙语、中文（普通话）。
• 语音混合与别名 – 使用加权比例组合多个语音包（af_bella(2)+af_sky(1)），或为复杂的混合语音定义简短别名。
• 内嵌 SSML 风格标签 – [voice:…]、[pause:1.5s]、[rate:1.5] 以及 IPA 发音标签可直接嵌入文字中。
• 多角色对话 – 使用语音标签或专用的 /dev/dialogue 端点来编写对话脚本，让每一句对话都有各自的语音。
• 自定义语音包生成 – 通过 Inno-Clone-Tuner (/dev/tune)，您可以根据短参考片段微调语音，并选择性地保存生成的 .pt 语音包。
• 带时间戳的字幕 – 提供可选的逐字或逐块时间戳，用于生成字幕。
• Web UI – 内置浏览器 UI (/web)，用于快速测试、语音混合预览及长文本朗读。
• Kubernetes / DigitalOcean 部署 – 提供 Helm chart 和部署文档。

如何运行

1. Docker – 拉取对应的镜像（例如 ghcr.io/remsky/kokoro-fastapi-gpu:latest）并开放 8880 端口。
2. Docker-Compose – 克隆仓库，选择 docker/gpu（或 cpu/rocm）文件夹并运行 docker compose up --build。
3. 直接运行 – 安装 uv 和系统依赖项，然后运行 ./start-gpu.sh 或 ./start-cpu.sh。

所有镜像皆已内置模型；若需手动下载，亦提供辅助脚本。

典型用法 (Python)

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")
resp = client.audio.speech.create(
    model="kokoro",
    voice="af_bella+af_sky",
    input="Hello world!",
    response_format="mp3",
)
resp.stream_to_file("out.mp3")

若偏好原始 HTTP，同样的调用方式也适用于 requests。

为何选择此项目

• 提供一个自托管、与 OpenAI 兼容的 TTS 后端，无需依赖外部付费 API。
• Kokoro-82M 模型体积小巧，足以在消费级 GPU 甚至 CPU 上运行，同时支持多种语言和语音混合功能，这在开源 TTS 堆栈中相当罕见。
• 丰富的 API 接口（流式传输、语音标签、微调、时间戳）使其非常适合构建语音助手、有声书、互动游戏或任何需要快速、可控语音合成的应用程序。

---

链接

• 模型仓库：https://huggingface.co/hexgrad/Kokoro-82M
• Demo Space：https://huggingface.co/spaces/Remsky/FastKoko
• Helm chart：docs/deployment/kubernetes.md
• 集成指南：Home Assistant, SillyTavern, OpenWebUI 等。