断网也能做语音合成：ChatTTS-ui 离线部署五问实战教程-平芜编程栈

断网也能做语音合成：ChatTTS-ui 离线部署五问实战教程

【免费下载链接】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 是一个本地网页语音合成工具——你在浏览器里输入文字，它输出自然的中英文语音，还能对外暴露 API 接口。当目标机器处在无网络环境（涉密内网、野外作业、临时断网）时，联网下载模型这条路走不通，怎么办？这篇 ChatTTS-ui 离线部署教程不讲空泛原理，直接回答五个问题：要准备什么、要改什么、怎么跑起来、跑不起来怎么办、跑久了怎么管，跟着做完约 30 分钟即可在断网机器上听到第一句合成语音。

一、离线部署前，你需要备齐哪些东西

这一步在一台能上网的机器上完成，把三样东西打包带走，全程不需要和离线机器联网。

1.1 模型文件：语音合成的"引擎"，必须提前就位

ChatTTS 的全部推理都在本地模型文件上完成，这些文件通常约 1GB。在有网机器上执行：

huggingface-cli download 2Noise/ChatTTS --local-dir chattts-model # 若访问不畅，也可改用 ModelScope：pzc163/chatTTS

把得到的chattts-model目录传到离线机器上，放到项目根目录下的models/pzc163/chatTTS位置。关键文件清单（缺一个都会在启动或合成时报错）：

models/pzc163/chatTTS/ └── asset/ ├── GPT.pt # 语言模型，负责"想词" ├── DVAE_full.pt # 声学模型，负责"发声" ├── Decoder.pt # 解码器 ├── Vocos.pt # 声码器，把声学特征还原成波形 ├── tokenizer.pt # 分词器 └── spk_stat.pt # 随机音色所需的统计参数

💡 前五个是推理必需；spk_stat.pt在生成随机音色时会被读取，一并带上最稳妥。模型路径的默认值定义在主程序与配置模块中，目录名必须与它们保持一致。

1.2 Python 依赖包：离线安装的全部"弹药"

先执行依赖清单里 20 来个包。注意 torch/torchaudio 体积大（CPU 版约 800MB+），别忘了：

pip download -r requirements.txt -d ./offline_packages # 再补一对 torch（纯 CPU 即可，离线部署多数跑在 CPU 上） pip download torch==2.7.1 torchaudio==2.7.1 -d ./offline_packages

offline_packages整个目录连同项目源码一起拷走，离线机上用--no-index安装（下面 2.2 节有完整命令）。

1.3 项目源码与音色库

项目代码：把整个 ChatTTS-ui 目录打包拷贝即可，离线机上无需 git clone。
音色文件：仓库自带的 speaker/ 目录里有一批.csv音色种子，可直接使用；也可以用speaker/2222.csv这类文件名作为 API 里的voice参数。
系统级依赖：Linux 上装好 Python 3.9–3.11；用到音频转码的话，按 ffmpeg/ffmpeg下载.txt 的说明把 ffmpeg 放到ffmpeg/目录。

二、要改什么：让离线语音合成跑通的三处调整

好消息是：你几乎不用动源码。app.py 启动时的逻辑是"先找本地模型，找不到才联网下载"（约 52 行起），所以只要模型放对位置，它就自然进入离线模式。

2.1 唯一必须"改"的地方：把模型放进 models 目录

uilib/cfg.py 会把模型根目录固定为项目根目录下的models/，程序拼接后的完整路径就是models/pzc163/chatTTS。把 1.1 节的模型目录摆到这个位置，就是离线部署里最关键的一步——代码一行不改。

2.2 .env 文件：控制监听地址与推理设备

在项目根目录新建.env（程序启动时自动加载）：

WEB_ADDRESS=0.0.0.0:9966 device=cpu compile=false

WEB_ADDRESS：默认只监听本机，改成0.0.0.0后局域网内其他机器也能访问这个语音合成服务；
device：离线机没有 GPU 就写cpu；
compile：设为false关闭 torch.compile，弱配置 CPU 上启动更快、更省心。

装依赖（离线命令，与在线环境形成鲜明对比的就是--no-index参数）：

pip install --no-index --find-links=./offline_packages torch torchaudio pip install --no-index --find-links=./offline_packages -r requirements.txt

2.3 无需改动但值得知道的一处

随机音色的实现依赖asset/spk_stat.pt，这也是 1.1 节清单里多列它的原因。若你在页面上选了"随机音色"却报文件缺失，先回来检查它。

三、怎么跑起来：无网络环境下启动并验证 ChatTTS-ui

3.1 一条命令启动

python app.py

看到Start:0.0.0.0:9966即服务已起，浏览器打开http://127.0.0.1:9966，输入一段文字，点合成——能听到声音，离线部署就算打通了。

3.2 本地 /tts 接口怎么测

不想开浏览器，直接打接口验证整条链路（文本 → 分词 → 推理 → 音频）：

curl -G 'http://127.0.0.1:9966/tts' \ --data-urlencode 'text=离线语音合成部署成功' \ --data-urlencode 'wav=1' \ --data-urlencode 'voice=2222' \ -o out.wav

wav=1时接口直接返回音频文件；不带它则返回 JSON（含音频 URL 和本次推理耗时）；
常用参数：voice（音色，默认 2222）、temperature（默认 0.3，越低越"板正"）、top_p、top_k、speed、skip_refine（1 表示跳过文本润色阶段，能省时间）。

请求打不通时先看端口是否被占用，再看下一节的排查表。

四、跑不起来怎么办：离线部署三大踩坑实录

现象	多半是	处理办法
启动时卡住、报网络相关错误（`LocalEntryNotFoundError`之后）	本地模型不完整，程序回退去联网下载，而离线机没网	对照 1.1 节清单逐个核对`models/pzc163/chatTTS/asset/`下 6 个文件，缺哪个补哪个
页面能开，合成报音频/转码错误	`ffmpeg/`目录缺少 ffmpeg 可执行文件	按仓库内下载说明补齐，文件名和平台要对应
CPU 上启动特别慢或合成中内存吃紧	`compile=true`的图编译 + 长文本	`.env`中设`compile=false`；把长文本按行拆短；同时只开 1–2 个合成请求

排障时盯两处日志：程序控制台输出（每段音频会打印推理时长与音频时长），以及 tools/logger/log.py 写入logs/目录的滚动日志文件（按日期命名）。出现download、connection字样基本可以断定是"本地模型没就位"，而不是代码问题。

五、跑久了怎么管：离线 TTS 系统的轻量运维

磁盘：每次合成的 wav 都落在static/wavs/，越积越多。定期调一下清理接口即可：curl -X POST http://127.0.0.1:9966/clear_wavs。
性能基线参考：CPU（8 核 16GB）上合成 10 秒左右的音频通常在数秒到十几秒级；换成带 4GB+ 显存的 NVIDIA 卡并装 CUDA 版 torch 后，速度可提升一个量级，适合多人共用。
备份：models/目录是整套系统里唯一"丢了就瘫"的部分，随主机一起备份即可；.env和自定义speaker/音色文件顺手带上。
检查节奏：每月看一眼logs/有无异常堆栈、static/wavs/占用是否失控，就够这个量级的服务用了。