用 Docker 跑 Chatterbox-TTS-Server（NVIDIA 显卡）

English · 简体中文

Chatterbox-TTS-Server 把 Resemble AI 的 Chatterbox 模型包进了一个网页界面和一套 OpenAI 兼容 API。和 Kokoro 比，它的语音自然、有感情得多——Turbo 模型甚至认识 [laugh]、[sigh] 这样的标签——而且你可以拿一小段录音克隆一个语音。代价是：没有词级时间戳（所以朗读只能逐句高亮）、慢（一个长句要好几秒），而且它要一块真显卡。

插件是通过设置里的 OpenAI 那一节来用它的。

只讲显卡

本教程只讲 Docker 里的 NVIDIA 显卡，别的都不讲，这是故意的。CPU 模式和 macOS（Apple Silicon）上的原生构建都「能出声」，但我们测下来，合成一句话比读完这句话还慢，于是每读一句都要卡一下；拿来朗读是不能用的。请按有 6–8 GB 空闲显存的卡来准备。给个参照：在 RTX 3080 Ti 上，短句约 1.7 秒，长句约 8 秒；插件会提前预取几句，把这段等待藏起来。

前置条件

1. 取代码

git clone https://github.com/devnen/Chatterbox-TTS-Server.git
cd Chatterbox-TTS-Server

下面的命令都在这个目录里跑。服务器的数据也存在这里：config.yaml、voices/、reference_audio/、outputs/、logs/。

2. 把占位的 Hugging Face 令牌清空

上游的 docker-compose.yml 里写着 HF_TOKEN=YOUR_TOKEN_HERE。Hugging Face 会把它当成一个真实但无效的令牌，于是拒绝下载模型。这些模型是公开的，令牌留空就行。与其去改上游那个文件（之后 git pull 会跟你打架），不如在它旁边加一个覆盖文件 docker-compose.override.yml：

services:
  chatterbox-tts-server:
    environment:
      HF_TOKEN: ""

Docker Compose 会自动把它合并进去。

国内网络——模型是从 huggingface.co 下的，直连基本不通。在同一个覆盖文件里再加一行 HF_ENDPOINT: "https://hf-mirror.com" 即可走镜像站（huggingface_hub 认这个变量）。另外，构建镜像时要从 Docker Hub 和 PyPI 拉东西，那一步走不动的话，给 Docker 守护进程配代理（Docker Desktop：Settings → Resources → Proxies）比换源省事。

3. 构建并启动

RTX 20/30/40 系列：

docker compose up -d --build

RTX 50 系列（Blackwell）——两个文件都要点名，因为覆盖文件只有挨着默认的 docker-compose.yml 时才会被自动读取：

docker compose -f docker-compose-cu128.yml -f docker-compose.override.yml up -d --build

构建大约十五分钟（CUDA 基础镜像、PyTorch、chatterbox 包）。然后容器启动，第一次启动会下模型。跟着看：

docker compose logs -f

直到出现 Final device selection: cuda——如果写的是 cpu，说明显卡没进到容器里，见疑难解答——再过一两分钟出现 TTS Model loaded successfully on cuda 和 Application startup complete。此后容器会随 Docker 一起启动（restart: unless-stopped），模型缓存在一个 Docker 卷里，所以之后启动只要一分钟。

4. 检查一下

网页界面在 http://localhost:8004，API 文档在 http://localhost:8004/docs。在终端里：

curl -s http://localhost:8004/api/model-info
curl -s http://localhost:8004/v1/audio/voices
curl -s -o test.mp3 -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"Emily.wav","input":"Chatterbox is running on the GPU.","response_format":"mp3"}' \
  http://localhost:8004/v1/audio/speech

第一条应答里有 "device":"cuda"，第二条列出 28 个语音，第三条写出一个能播放的 test.mp3。

5. 把插件指过去

Zotero → 设置 → Zotero-TTS → OpenAI 那一节：

字段 填什么
启用 OpenAI 语音 开
服务器 Chatterbox-TTS-Server——选了它会自动填好地址，并把密钥、模型、语音置灰，因为 Chatterbox 不看这几项
API 地址 http://localhost:8004（预设已填好；用别的机器就改这里）
额外请求头 留空（只有服务器在网关后面才需要，见 Cloudflare 教程）

测试连接会回答 Connected. 28 voices available. Synthesis works.。在朗读的本地语音模式里，这些语音显示为 OpenAI-Emily.wav、OpenAI-Henry.wav 等等。不管高亮当前怎么设，高亮都是逐句的，因为这个服务器不报词级时间戳。

语言

默认引擎 Chatterbox Turbo 只说英语。要别的语言就换成多语种模型（23 种语言，含中文）：在 config.yaml 里写

model:
  repo_id: chatterbox-multilingual
generation_defaults:
  language: zh

然后重启（docker compose restart）；模型会在下次启动时下载。插件发请求时不带语言，所以 generation_defaults.language 就是所有文档被读成的语言——一台服务器一种语言。网页界面也能换引擎，不用重启。

用你自己的声音

把一段干净的、10–30 秒的说话人 WAV 或 MP3 放进 voices/。下一次测试连接就会把它列出来，在朗读里以文件名出现。（放在 reference_audio/ 里的也能用，但不会被列出来；那样就得手动填进语音字段。）

日常使用

docker compose stop       # 把显卡让出来
docker compose start
docker compose logs --tail 50

升级到新版服务器：

git pull
docker compose up -d --build

疑难解答