ChatTTS-ui 本地部署教程：三步跑通语音合成服务，含 API 接入

ChatTTS-ui 本地部署教程：三步跑通语音合成服务，含 API 接入

【免费下载链接】ChatTTS-ui一个简单的本地网页界面，使用ChatTTS将文字合成为语音，同时支持对外提供API接口。A simple native web interface that uses ChatTTS to synthesize text into speech, along with support for external API interfaces.项目地址: https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui

本文带你完成 ChatTTS-ui 的本地部署——这是一个基于 ChatTTS 内核的网页语音合成服务。装好之后你手里有两样东西：一个能用浏览器打开的中英文文字转语音界面，和一个可供自己程序调用的 /tts 合成接口。Linux 上大约 10 分钟能跑通，Windows 与 Mac 的步骤一致，只是个别命令有差别。

三分钟跑通：克隆仓库并激活虚拟环境

最短路径以 Linux 为例，一条命令一行地敲即可：

git clone https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui cd ChatTTS-ui python3 -m venv venv source ./venv/bin/activate

激活后，虚拟环境提示符前会出现(venv)，后续所有安装都发生在其中，不污染系统 Python。

各平台的差异点：

• Windows：需要先装好 Python 3.9–3.11（安装时务必勾选把 Python 加入 PATH 的选项），激活命令换成.\venv\scripts\activate，后面用python代替python3。
• Mac：依赖用 Homebrew 准备，brew install git python@3.10 ffmpeg libsndfile libomp，之后再按上面步骤创建 venv。
• ffmpeg：Mac 和 Linux 装好包管理器里的 ffmpeg 即可；Windows 需要单独下载ffmpeg.exe，放到项目根目录的 ffmpeg/ 文件夹里，下载说明见 ffmpeg/ffmpeg下载.txt。

安装依赖：按 GPU 或 CPU 选择 PyTorch

依赖清单在 requirements.txt：

pip install -r requirements.txt

清单里的torch>=2.7.1默认会装 CPU 版本，能用但推理偏慢。如果你的机器有英伟达显卡（显存 4G 以上）且装了 CUDA 12.8+，先卸载再装 cu128 版本：

pip uninstall -y torch torchaudio pip install torch==2.7.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128 pip install nvidia-cublas-cu11 nvidia-cudnn-cu11

没有独显或不想折腾驱动就直接用默认 CPU 版，功能完全一样，只是慢一些。

启动服务并确认生效

python3 app.py

首次启动会自动联网下载 ChatTTS 模型（存到项目下的models/目录），这一步耗时取决于带宽，请耐心等待。看到控制台打印Start:127.0.0.1:9966并自动弹出浏览器后，服务就在默认地址http://127.0.0.1:9966上运行了。随便输入一段中英文混合文字点合成，能听到声音就说明部署完成。

选择你的部署姿势：按场景给推荐

同一条源码路径，三种玩法，按场景选即可：

• 本机快速体验→ 源码部署（或 Windows 预打包版）：不为任何服务器服务，装完即开浏览器用；Windows 用户也可以从官方 Releases 直接拿压缩好的成品，省去装 Python 的环节。
• 服务器常驻→ 源码部署 + 后台运行：进程直接落在系统里，tail日志、改 .env 都最顺手，适合只给自己内网用的情况。
• 容器化、多人共用→ Docker Compose：环境固化在镜像里，GPU/CPU 两套启动文件都已备好，一条命令拉起，也方便随时重建。

容器化部署：GPU 与 CPU 的 Docker 启动差异

git clone https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui chat-tts-ui cd chat-tts-ui # 有英伟达显卡（主机需装好 NVIDIA 容器运行时） docker compose -f docker-compose.gpu.yaml up -d # 纯 CPU 机器 docker compose -f docker-compose.cpu.yaml up -d # 跟踪初始化日志 docker compose logs -f --no-log-prefix

两份 compose 文件（docker-compose.gpu.yaml / docker-compose.cpu.yaml）的区别在于镜像基础（Dockerfile.gpu基于 GPU 版 PyTorch 镜像）以及是否申请 GPU 设备，端口映射都是9966:9966，且容器内监听0.0.0.0:9966——所以局域网里直接用http://服务器IP:9966访问，无需再改地址配置。

升级流程：

git pull origin main docker compose down docker compose -f docker-compose.gpu.yaml up -d --build docker compose logs -f --no-log-prefix

模型与参数：模型下载、音色配置、.env 速查

模型下载机制与文件位置

启动逻辑在 app.py：优先检测本地models/pzc163/chatTTS/是否已有完整模型，没有则联网补全——默认走 ModelScope 魔塔社区，检测不到国内源时才回落到 Hugging Face。两个注意点：

• 从魔塔下载不能开代理，开了会直接报 ProxyError；
• 想离线使用，就在有网的机器上先完整跑过一次，之后models/目录里就是全部所需文件。

音色配置：speaker 目录与 pt 文件转换

• 固定音色以文件形式放在 speaker/ 目录，支持.csv和.pt两种格式，界面里填文件名（不带扩展名）或 API 里传对应值即可，仓库自带了一批 csv 音色可试听。
• 从社区站点下载的.pt音色是旧编码，当前版本需要用 cover-pt.py 转一道：

python cover-pt.py

脚本只处理speaker/下以seed_开头、_emb.pt结尾的文件，转完会生成以-covert.pt结尾的新文件，原文件即可删除。

• 不传任何音色值时，voice传一个纯数字 seed 也能用，服务会按种子随机生成并自动缓存下来。注意官方说明：同一 seed 在不同设备、甚至同设备不同时间，音色都可能不同，要绝对一致就存 csv/pt 文件。

.env 三个关键变量

打开 .env（记事本即可），一共三行：

WEB_ADDRESS=127.0.0.1:9966 # 改成局域网 IP（如 192.168.0.10:9966）可对外访问 compile=false # 报 triton / torch.compile 错误时保持 false device=default # default 自动选 cuda(显存>4G)/mps/cpu，也可手动指定 cpu|mps|cuda

显存低于 4G 时系统会强制走 CPU，这是设计行为而非故障。

接入你的应用：ChatTTS 语音合成 API 最小示例

服务地址固定为http://127.0.0.1:9966（以你实际WEB_ADDRESS为准），合成接口是 POST/tts：

import requests res = requests.post('http://127.0.0.1:9966/tts', data={ "text": "这是由本地 ChatTTS 服务合成的一段语音。", "voice": "3333", "temperature": 0.3, "top_p": 0.7, "top_k": 20, "skip_refine": 0, "custom_voice": 0 }) print(res.json())

成功时返回：

{code: 0, msg: 'ok', audio_files: [{filename: wav绝对路径, url: 可下载的wav网址, inference_time, audio_duration}]}

失败时code为 1，msg写明原因（比如text params lost）。url字段可以直接丢给浏览器或任何 HTTP 客户端下载音频。另外还有一个清理接口：POST/clear_wavs可清空static/wavs/下的历史产物，避免磁盘被占满。

API 参数速查

• text（必填）：要合成的文字，支持换行分句，中英混排会自动分行处理
• voice：音色，默认 2222；可填 speaker 目录里的音色文件名，或任意数字作为随机种子
• custom_voice：正整数，指定取种子的 seed，设置后优先于voice
• prompt：控制符串，如[oral_2][laugh_0][break_6]，可带口吃、笑声、停顿
• temperature/top_p/top_k：采样参数，默认 0.3 / 0.7 / 20，决定声音的"随机感"
• skip_refine：1 表示跳过文本细化阶段，速度更快但个别生僻写法可能读不准
• speed：语速档位，默认 5
• 其余如text_seed、refine_max_new_token等均有服务端默认值，不填即用默认

故障自查：症状 → 原因 → 解决

启动报Dynamo is not supported on Python 3.12→ PyTorch 编译组件不支持 3.12 及以上 → 换 python 3.10，删除 venv 重建。

下载模型时ProxyError: HTTPSConnectionPool(host='www.modelscope.cn'...)→ 魔塔不接受代理流量 → 关闭系统或终端代理，重新执行python app.py。

报Missing spk_stat.pt或找不到path.yaml→ 模型文件不完整 → 补下载缺失文件，spk_stat.pt放入models/pzc163/chatTTS/asset/，path.yaml放入models/pzc163/chatTTS/config/（补全后重启服务）。

Mac 进度条卡在 0%，或报cannot find a working triton installation→ torch.compile 在当前环境不可用 → 确认 .env 里是compile=false（默认值就是 false，检查是否被改过）。

Mac 报libomp.dylib相关错误→ 缺少 OpenMP 运行时 →brew install libomp。

Mac 上pip install soundfile失败→ 缺系统库 →brew install libsndfile后重装。

Windows 有显卡却只跑 CPU 或明显偏慢→ 装的是 CPU 版 torch 或 CUDA 版本过旧 → 执行"安装依赖"一节中的卸载 + 重装 cu128 命令（需 CUDA 12.8+）；若显存低于 4G，则本就会被强制走 CPU，属正常现象。

局域网其他设备打不开页面→WEB_ADDRESS还是127.0.0.1→ 改成局域网 IP 后重启服务；Docker 部署则直接访问服务器IP:9966。

同样 seed 合成出来的声音和上次/别人机器上的不一样→ 这不是故障，音色 embedding 本身带随机性 → 需要稳定音色就把它存成 csv/pt 放进 speaker/。

更多细节可翻仓库内的 faq.md。

项目源码即本文克隆的 ChatTTS-ui 仓库（地址见开头 git clone 命令），遇到这里没覆盖的问题，欢迎到该仓库的 Issues 区反馈。

【免费下载链接】ChatTTS-ui一个简单的本地网页界面，使用ChatTTS将文字合成为语音，同时支持对外提供API接口。A simple native web interface that uses ChatTTS to synthesize text into speech, along with support for external API interfaces.项目地址: https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui