Skip to main content

Chatterbox TTS — 声音克隆

警告

本教程为社区贡献，不属于 Open WebUI 官方支持。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

什么是 Chatterbox TTS API？​

Chatterbox TTS API 是一个 API 包装器，支持声音克隆和文本转语音 (TTS)，可作为 OpenAI 语音 API 端点的直接替代方案。

Link to Resemble AI voice samples

核心特性​

  • 零样本声音克隆： 仅需约 10 秒的任何声音样本。
  • 性能卓越： 超越 ElevenLabs。
  • 数字水印： 输出包含水印，确保负责任的声音克隆。
  • 强大架构： 基于 0.5B Llama 骨干网络。
  • 自定义声音库： 集成声音库管理。
  • 流式传输支持： 实现快速生成。
  • 高级内存管理： 具备自动清理功能。
  • 可选前端： 提供易于管理和使用的前端界面。

硬件建议​

  • 内存： 最少 4GB，推荐 8GB+。
  • GPU： 支持 CUDA (Nvidia) 或 Apple M 系列 (MPS)。
  • CPU： 可以运行但速度较慢，生产环境推荐使用 GPU。
提示

Chatterbox 可能会消耗大量内存，其硬件要求可能高于您习惯的其他本地 TTS 解决方案。如果您的硬件难以满足要求，您可能会发现 OpenAI Edge TTS 或 Kokoro-FastAPI 是合适的替代方案。

⚡️ 快速开始​

🐍 使用 Python​

选项 A：使用 uv（推荐 - 速度更快且依赖管理更好）​

# 克隆仓库
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# 如果尚未安装 uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 uv 安装依赖（自动创建虚拟环境）
uv sync

# 复制并自定义环境变量
cp .env.example .env

# 使用 FastAPI 启动 API
uv run uvicorn app.main:app --host 0.0.0.0 --port 4123

# 或者使用主脚本
uv run main.py

💡 为什么选择 uv？ 用户反馈其与 chatterbox-tts 的兼容性更好，安装速度快 25-40%，且依赖解析更优。查看迁移指南 →

选项 B：使用 pip（传统方式）​

# 克隆仓库
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# 设置环境 — 使用 Python 3.11
python -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制并自定义环境变量
cp .env.example .env

# 添加您的声音样本（或使用提供的样本）
# cp your-voice.mp3 voice-sample.mp3

# 使用 FastAPI 启动 API
uvicorn app.main:app --host 0.0.0.0 --port 4123

# 或者使用主脚本
python main.py

遇到问题？请查看 故障排除部分。

🐳 Docker（推荐）​

# 克隆并使用 Docker Compose 启动
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# 使用 Docker 优化的环境变量
cp .env.example.docker .env  # Docker 专用路径，开箱即用

# 或者：cp .env.example .env    # 本地开发路径，需要自定义

# 选择您的部署方式：

# 仅 API (默认)
docker compose -f docker/docker-compose.yml up -d             # 标准版 (基于 pip)
docker compose -f docker/docker-compose.uv.yml up -d          # uv 优化版 (构建更快)
docker compose -f docker/docker-compose.gpu.yml up -d         # 标准 + GPU
docker compose -f docker/docker-compose.uv.gpu.yml up -d      # uv + GPU (推荐 GPU 用户)
docker compose -f docker/docker-compose.cpu.yml up -d         # 仅 CPU

# API + 前端 (在上述任何命令后添加 --profile frontend)
docker compose -f docker/docker-compose.yml --profile frontend up -d             # 标准 + 前端
docker compose -f docker/docker-compose.gpu.yml --profile frontend up -d         # GPU + 前端
docker compose -f docker/docker-compose.uv.gpu.yml --profile frontend up -d      # uv + GPU + 前端

# 查看初始化日志（首次使用 TTS 耗时最长）
docker logs chatterbox-tts-api -f

# 测试 API
curl -X POST http://localhost:4123/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from Chatterbox TTS!"}' \
  --output test.wav
🚀 运行前端界面

本项目包含一个可选的基于 React 的 Web UI。使用 Docker Compose profiles 可以轻松开启或关闭前端：

使用 Docker Compose Profiles​

# 仅 API (默认行为)
docker compose -f docker/docker-compose.yml up -d

# API + 前端 + Web UI (使用 --profile frontend)
docker compose -f docker/docker-compose.yml --profile frontend up -d

# 或者使用便捷的 fullstack 辅助脚本：
python start.py fullstack

# 同样模式适用于所有部署变体：
docker compose -f docker/docker-compose.gpu.yml --profile frontend up -d    # GPU + 前端
docker compose -f docker/docker-compose.uv.yml --profile frontend up -d     # uv + 前端
docker compose -f docker/docker-compose.cpu.yml --profile frontend up -d    # CPU + 前端

本地开发​

对于本地开发，您可以分别运行 API 和前端：

# 首先启动 API（遵循前面的说明）

# 然后运行前端：
cd frontend && npm install && npm run dev

注意： 如果遇到依赖问题，请尝试运行 npm install --force 而不是简单的 npm install。

点击 Vite 提供的链接访问 Web UI。

生产环境构建​

构建前端用于生产部署：

cd frontend && npm install && npm run build

注意： 如果构建因依赖冲突失败，请尝试使用 npm install --force。

然后您可以直接从本地文件系统的 /dist/index.html 访问它。

端口配置​

  • 仅 API： 可在 http://localhost:4123 访问（直接 API 访问）
  • 带前端： Web UI 在 http://localhost:4321，API 请求通过代理路由

前端使用反向代理路由请求，因此在使用 --profile frontend 运行时，Web 界面将在 http://localhost:4321 可用，而 API 在代理后运行。

设置 Open WebUI 使用 Chatterbox TTS API​

我们建议运行前端界面，以便在配置 Open WebUI 设置之前上传您想要使用的声音音频文件。如果启动正确（见上文指南），您可以访问 http://localhost:4321 进入前端。

要将 Chatterbox TTS API 与 Open WebUI 配合使用，请按照以下步骤操作：

  • 打开 管理员面板 并转到 设置 -> 音频
  • 将您的 TTS 设置 配置如下：
    • 文本转语音引擎： OpenAI
    • API 基础 URL： http://localhost:4123/v1 # 或者尝试 http://host.docker.internal:4123/v1
    • API 密钥： none
    • TTS 模型： tts-1 或 tts-1-hd
    • TTS 声音： 您克隆的声音名称（也可以包含在前端定义的别名）
    • 响应拆分： Paragraphs (段落)
提示

默认 API 密钥是字符串 none（无需 API 密钥）。

Open WebUI 音频设置截图，展示了本项目的正确端点配置

请在 GitHub 上关注该项目 以支持开发 ⭐️​

需要帮助？​

Chatterbox 的首次运行可能具有挑战性，如果遇到特定安装选项的问题，您可能需要尝试不同的安装方式。

有关 chatterbox-tts-api 的更多信息，您可以访问 GitHub 仓库。