跳到主要内容

使用 Docker 部署 Kokoro-FastAPI

注意

本教程是社区贡献内容，不属于 OPL 数据空间官方支持范围，主要用于演示如何把 Kokoro-FastAPI 接入你的部署。

什么是 Kokoro-FastAPI​

Kokoro-FastAPI 是一个基于 Docker 的 FastAPI 封装，围绕 Kokoro-82M 文本转语音模型构建，并实现了 OpenAI Speech API 兼容端点。

主要特性​

  • OpenAI 兼容的 speech 端点
  • 支持 NVIDIA GPU 加速，也支持 CPU ONNX 推理
  • 支持流式输出与不同 chunk 策略
  • 支持多种音频格式：mp3、wav、opus、flac、aac、pcm
  • 自带 Web 界面（默认 localhost:8880/web）
  • 支持音素转换相关接口

可用声音​

  • af
  • af_bella
  • af_irulan
  • af_nicole
  • af_sarah
  • af_sky
  • am_adam
  • am_michael
  • am_gurney
  • bf_emma
  • bf_isabella
  • bm_george
  • bm_lewis

支持语言​

  • en_us
  • en_uk

前提​

  • 已安装 Docker
  • OPL 数据空间正在运行
  • 若要用 GPU：需要 NVIDIA GPU

快速开始​

GPU 版本​

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

或使用 Docker Compose：

services:
  kokoro-fastapi-gpu:
    ports:
      - 8880:8880
    image: ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.1
    restart: always

CPU 版本​

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

或：

services:
  kokoro-fastapi-cpu:
    ports:
      - 8880:8880
    image: ghcr.io/remsky/kokoro-fastapi-cpu
    restart: always

在 OPL 数据空间中配置​

进入 管理员面板 → 设置 → 语音，设置：

  • Text-to-Speech Engine：OpenAI
  • API Base URL：http://localhost:8880/v1
    • 若 OPL 数据空间在 Docker 中运行，可改用 host.docker.internal
  • API Key：not-needed
  • TTS Voice：例如 af_bella
  • TTS Model：kokoro
信息

默认 API Key 就是 not-needed。如果你不需要额外鉴权，可以直接使用这个值。

自行构建容器​

git clone https://github.com/remsky/Kokoro-FastAPI.git
cd Kokoro-FastAPI
cd docker/cpu # 或 docker/gpu
docker compose up --build

故障排查​

NVIDIA GPU 未被识别​

  1. 安装并配置 NVIDIA Container Toolkit
  2. 用 docker run --rm --gpus all nvidia/cuda:12.2.0-base nvidia-smi 验证 GPU 是否可见

OPL 数据空间连接不到 Kokoro​

  • Docker Desktop 场景使用 host.docker.internal
  • 如果两者在同一 Compose 网络中，可直接使用服务名
  • 通过 curl http://localhost:8880/health 检查服务是否正常

CPU 版本性能​

CPU 版本对一般用途已经够用，但如果你对速度敏感，建议切换到 GPU 版本。

更多问题见 音频排障指南。