用 Docker 跑 Kokoro-FastAPI

English · 简体中文

Kokoro-FastAPI 就是插件的本地引擎：一个又小又快的模型，68 个语音，覆盖英语、中文、日语、法语、西班牙语、意大利语、葡萄牙语和印地语，而且是唯一会报词级时间戳的本地引擎——所以朗读能逐词高亮。它整个跑在你自己的机器上；插件在 http://localhost:8880 上跟它说话（设置里 Kokoro-FastAPI 那一节的地址字段）。

官方 Docker 镜像把模型、CUDA 和 espeak-ng 都打包进去了，所以装好 Docker 之后一条命令就够。

前置条件

Docker：Windows 和 macOS 上装 Docker Desktop，Linux 上装 Docker Engine。要用 NVIDIA 显卡，得有较新的驱动——Linux 上还要装 NVIDIA Container Toolkit，Windows 上不用别的。先确认容器能看见显卡：

docker run --rm --gpus all ubuntu:22.04 nvidia-smi -L

国内网络——镜像放在 ghcr.io 上，直连往往很慢甚至超时。两条路：给 Docker 守护进程配代理，或者在镜像名前面加一个镜像站，例如南京大学的 ghcr.nju.edu.cn/remsky/kokoro-fastapi-gpu:latest（镜像站会变，用之前先确认它还在）。注意 Docker Hub 的「镜像加速器」（registry-mirrors）只对 Docker Hub 有效，对 ghcr.io 不起作用。模型已经打包在镜像里，所以拉下来之后不再需要访问 Hugging Face。

Windows / Linux，有 NVIDIA 显卡

GeForce 900 系列到 RTX 40 系列（CUDA 12.6 构建）：

docker run -d --name kokoro --restart unless-stopped --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

RTX 50 系列（Blackwell）需要 CUDA 12.8 的构建：

docker run -d --name kokoro --restart unless-stopped --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest-cu128

没有 NVIDIA 显卡（任何平台）

docker run -d --name kokoro --restart unless-stopped -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

每句话开口会慢一些，但读文章够用——Kokoro 小到 CPU 也扛得住。

macOS

Mac 上的 Docker 用不了 GPU：GPU 镜像只支持 CUDA，而苹果的 Metal 不对 Linux 容器开放。两个选择：

那几个 Docker 参数各是什么意思：-d 后台运行，--restart unless-stopped 让它随 Docker 一起回来，--gpus all 把显卡交给容器，-p 8880:8880 把服务器暴露在 localhost:8880 上。第一次要下几 GB；之后启动只要几秒。

检查一下

在 Zotero 里，设置 → Zotero-TTS → Kokoro-FastAPI，按测试连接；它应该回答 Connected. 68 voices available.，再按启用把这个服务商打开。然后打开朗读，语音模式选本地，挑一个 Kokoro-… 的语音（af_bella 和 af_heart 是不错的英语语音；zf_xiaobei / zm_yunxi 说中文）。要逐词高亮，把设置 → 常规 → 朗读 → 高亮当前设成单词。

日常使用

docker stop kokoro          # 把显卡让出来
docker start kokoro         # 再起来
docker logs --tail 50 kokoro

升级到新镜像：

docker pull ghcr.io/remsky/kokoro-fastapi-gpu:latest
docker rm -f kokoro
docker run -d --name kokoro --restart unless-stopped --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

疑难解答