提供了预构建的镜像可供运行，支持arm/multi-arch架构，并内置了模型。 完整的环境变量列表可在core/config.py文件中找到。

# 可以使用`latest`标签，但可能会包含一些影响稳定性的额外功能。
建议在常规使用中固定命名版本。
欢迎提供反馈和测试意见。

docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest # CPU，或者：
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest  #NVIDIA GPU

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

     git clone https://github.com/remsky/Kokoro-FastAPI.git
     cd Kokoro-FastAPI
     
     cd docker/gpu  # 对于GPU支持
     # 或cd docker/cpu  # 对于CPU支持
     docker compose up --build
     
     # *注意：对于Apple Silicon（M1/M2）用户：
     # 当前的GPU版本依赖于CUDA，而CUDA并不支持Apple Silicon。  
     # 如果您使用的是M1/M2/M3 Mac，请使用`docker/cpu`设置。  
     # MPS（苹果的GPU加速）支持计划中，但尚未可用。
     
     # 模型会自动下载，但如果需要，您可以手动下载：
     python docker/scripts/download_model.py --output api/src/models/v1_0
     
     # 或者直接通过UV运行：
     ./start-gpu.sh  # 对于GPU支持
     ./start-cpu.sh  # 对于CPU支持
     

1. 安装先决条件（）：

   • 安装astral-uv

   • 如果希望在遇到未知单词或发音时作为备用方案，可在系统中安装espeak-ng。上游库可能会尝试处理这种情况，但效果不一。

   • 克隆仓库：

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

     如果尚未运行过，可执行模型下载脚本。

     直接通过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="不需要"
)

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的Python库
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="不需要")
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 = 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
        "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 # 测试所有可用语音

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

组合语音并生成音频：

import requests
response = requests.get("http://localhost:8880/v1/audio/voices")
voices = response.json()["voices"]

# 示例1：简单语音组合（50%/50%混合）
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "af_bella+af_sky",  # 等权重
        "response_format": "mp3"
    }
)

# 示例2：加权语音组合（67%/33%混合）
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "af_bella(2)+af_sky(1)",  # 2:1比例 = 67%/33%
        "response_format": "mp3"
    }
)

# 示例3：将组合语音下载为 .pt 文件
response = requests.post(
    "http://localhost:8880/v1/audio/voices/combine",
    json="af_bella(2)+af_sky(1)"  # 2:1比例 = 67%/33%
)

# 保存 .pt 文件
with open("combined_voice.pt", "wb") as f:
    f.write(response.content)

# 使用下载的语音文件
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "combined_voice",  # 使用保存的语音文件
        "response_format": "mp3"
    }
)

• mp3
• wav
• opus
• flac
• m4a
• pcm

# 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

关键流式传输指标：

• 首个 token 延迟 @ 数据块大小
  • ~300ms (GPU) @ 400
  • ~3500ms (CPU) @ 200 (较旧的 i7)
  • ~<1s (CPU) @ 200 (M3 Pro)
• 可调整的分块设置，适用于实时播放

注：音调方面可能会因分块过小而出现瑕疵

基准测试是在本地 API 上进行的，文本长度最长可达长篇小说级别（约1.5小时的输出），测量了处理时间和实时因子。测试环境如下：

• Windows 11 家庭版，搭载 WSL2
• NVIDIA 4060Ti 16GB 显卡，CUDA 12.1
• 第11代 i7-11700，2.5GHz
• 64GB 内存
• WAV 原生输出
• H.G. Wells 的《时间机器》（全文）

关键性能指标：

• 实时速度：介于35倍至100倍之间（生成时间与音频输出长度之比）
• 平均处理速率：137.67 tokens/秒（cl100k_base）

# GPU：需要支持 CUDA 12.8 的 NVIDIA 显卡（实时速度约为35倍至100倍）
cd docker/gpu
docker compose up --build

# CPU：PyTorch CPU 推理
cd docker/cpu
docker compose up --build

注：为了支持流式传输而进行的结构调整可能导致整体速度有所下降。正在进一步调查中。

• 自动在句子边界处分割和拼接
• 有助于减少伪影，并支持长文本处理，因为基础模型目前仅配置为生成约30秒的输出。

该模型一次最多可处理510个音素化标记的片段，但这样往往会导致语速过快或其他伪影。因此，服务器端额外增加了一层切块逻辑，根据 TARGET_MIN_TOKENS、TARGET_MAX_TOKENS 和 ABSOLUTE_MAX_TOKENS 参数动态生成灵活的片段，这些参数可通过环境变量配置，默认值分别为175、250和450。

不使用流式传输生成带单词级时间戳的音频：

import requests
import base64
import json

response = requests.post(
    "http://localhost:8880/dev/captioned_speech",
    json={
        "model": "kokoro",
        "input": "你好，世界！",
        "voice": "af_bella",
        "speed": 1.0,
        "response_format": "mp3",
        "stream": False,
    },
    stream=False
)

with open("output.mp3","wb") as f:

    audio_json=json.loads(response.content)
    
    # 将Base64编码的音频流解码为字节
    chunk_audio=base64.b64decode(audio_json["audio"].encode("utf-8"))
    
    # 处理流式传输的音频块
    f.write(chunk_audio)
    
    # 打印单词级时间戳
    print(audio_json["timestamps"])

使用流式传输生成带单词级时间戳的音频：

import requests
import base64
import json

response = requests.post(
    "http://localhost:8880/dev/captioned_speech",
    json={
        "model": "kokoro",
        "input": "你好，世界！",
        "voice": "af_bella",
        "speed": 1.0,
        "response_format": "mp3",
        "stream": True,
    },
    stream=True
)

f=open("output.mp3","wb")
for chunk in response.iter_lines(decode_unicode=True):
    if chunk:
        chunk_json=json.loads(chunk)
        
        # 将Base64编码的音频流解码为字节
        chunk_audio=base64.b64decode(chunk_json["audio"].encode("utf-8"))
        
        # 处理流式传输的音频块
        f.write(chunk_audio)
        
        # 打印单词级时间戳
        print(chunk_json["timestamps"])

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

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 = "你好，世界！"
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。

通过以下端点监控系统状态和资源使用情况：

• /debug/threads - 获取线程信息和堆栈跟踪
• /debug/storage - 监控临时文件和输出目录的使用情况
• /debug/system - 获取系统信息（CPU、内存、GPU）
• /debug/session_pools - 查看 ONNX 会话和 CUDA 流的状态

这些端点对于调试资源耗尽或性能问题非常有用。

全局 API 的 loguru 日志级别 可以通过 API_LOG_LEVEL 环境变量设置。默认值为 DEBUG。

Docker

修改相应的 compose yml 文件，或在命令行中追加：

docker run --env 'API_LOG_LEVEL=WARNING' ...

直接通过 UV

Linux 和 macOS

export API_LOG_LEVEL=WARNING
./start-cpu.sh 或 ./start-gpu.sh

Windows

$env:API_LOG_LEVEL = 'WARNING'
.\start-cpu.ps1 或 .\start-gpu.ps1

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:
        # 处理流式传输的块
        pass

分支策略：

• release 分支： 包含最新的稳定版本，推荐用于生产环境。基于该分支构建的 Docker 镜像会打上特定版本标签（例如 v0.3.0）。
• master 分支： 用于活跃开发。该分支可能包含实验性功能、正在进行的更改或尚未进入稳定版的修复。如果您希望使用最新代码，请使用此分支，但请注意其稳定性可能较低。latest Docker 标签通常指向该分支的构建。

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

如果您遇到问题，可能需要回退到 release 标签中的某个版本，或者从源码构建并进行调试，同时提交 PR。

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

部分 Linux 用户在以非 root 用户身份运行时可能会遇到 GPU 权限问题。 我们无法保证解决方案的有效性，但以下是一些常见的解决方法，请务必根据您的安全需求谨慎选择。

选项 1：容器组（可能是最佳选择）

services:
  kokoro-tts:
    # ... 现有配置 ...
    group_add:
      - "video"
      - "render"

选项 2：主机系统组

services:
  kokoro-tts:
    # ... 现有配置 ...
    user: "${UID}:${GID}"
    group_add:
      - "video"

注意：可能需要将主机用户添加到相关组中：sudo usermod -aG docker,video $USER，并重启系统。

选项 3：设备权限（谨慎使用）

services:
  kokoro-tts:
    # ... 现有配置 ...
    devices:
      - /dev/nvidia0:/dev/nvidia0
      - /dev/nvidiactl:/dev/nvidiactl
      - /dev/nvidia-uvm:/dev/nvidia-uvm

⚠️ 警告：会降低系统安全性。仅适用于开发环境。

前提条件：必须正确配置 NVIDIA GPU、驱动程序和容器工具包。

更多详细信息请访问 NVIDIA 容器工具包安装指南。

本 API 使用来自 HuggingFace 的 Kokoro-82M 模型。

访问模型页面可了解更多关于训练、架构和功能的信息。我与他们的工作并无关联，制作此封装是为了方便使用和个人项目。

• Kokoro 模型权重采用 Apache 2.0 许可证（详见 模型页面）
• 本仓库中的 FastAPI 封装代码也采用 Apache 2.0 许可证，以保持一致
• 基于 StyleTTS2 改编的推理代码则采用 MIT 许可证

完整的 Apache 2.0 许可证文本可在以下网址找到：https://www.apache.org/licenses/LICENSE-2.0