IndexTTS-2-LLM部署教程：Ubuntu 20.04环境实操步骤

1. 引言

1.1 学习目标

本文将详细介绍如何在Ubuntu 20.04系统环境下，从零开始部署基于kusururi/IndexTTS-2-LLM模型的智能语音合成服务 ——IndexTTS-2-LLM。通过本教程，您将掌握：

环境依赖配置与常见问题规避
项目源码拉取与本地部署流程
WebUI 交互界面的启动与使用
RESTful API 的调用方式与参数说明
CPU 推理性能优化技巧

最终实现一个支持中英文输入、具备高自然度语音输出的 TTS 服务系统，适用于内容生成、语音播报、AI 助手等场景。

1.2 前置知识

为确保顺利执行本教程，请确认已具备以下基础能力：

熟悉 Linux 命令行操作（文件管理、权限设置、进程查看）
了解 Python 虚拟环境（venv 或 conda）的基本使用
具备基本的 HTTP 请求概念（GET/POST、JSON 数据格式）

推荐运行环境：

操作系统：Ubuntu 20.04 LTS（x86_64）
内存：≥ 8GB（建议 16GB）
存储空间：≥ 20GB（模型缓存占用较大）
Python 版本：3.9 ~ 3.10

2. 环境准备与依赖安装

2.1 系统更新与基础工具安装

首先，确保系统软件包为最新状态，并安装必要的构建工具和库文件：

sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential git python3-pip python3-venv libsndfile1-dev ffmpeg

说明：
libsndfile1-dev是音频处理库，用于支持.wav文件读写。
ffmpeg用于后续音频格式转换与播放兼容性处理。

2.2 创建独立 Python 虚拟环境

避免全局依赖污染，建议创建专用虚拟环境：

mkdir indextts-deploy && cd indextts-deploy python3 -m venv venv source venv/bin/activate

激活后，升级 pip 至最新版本以提升依赖解析效率：

pip install --upgrade pip

3. 项目获取与模型初始化

3.1 克隆项目源码

当前镜像基于开源项目kusururi/IndexTTS-2-LLM构建，可通过 Git 克隆主分支：

git clone https://github.com/kusururi/IndexTTS-2-LLM.git app cd app

进入目录后，建议切换至稳定提交点（如无特殊需求）：

git checkout tags/v1.1.0 -b release-v1.1.0

3.2 安装核心依赖

该项目依赖较多科学计算与深度学习组件，部分需预编译版本以适配 CPU 推理。使用以下命令安装：

pip install torch==1.13.1+cpu torchvision==0.14.1+cpu torchaudio==0.13.1 --extra-index-url https://download.pytorch.org/whl/cpu pip install -r requirements.txt

⚠️ 注意事项：
必须指定+cpu版本的 PyTorch，否则默认会尝试安装 CUDA 支持包导致失败。
若scipy安装报错，可先安装其依赖：pip install numpy cython后重试。

3.3 下载预训练模型权重

项目不包含模型权重，需手动下载并放置于指定路径。执行脚本自动获取：

python scripts/download_model.py --model-type index_tts_2_llm --output-dir ./models/

该脚本将从官方 Hugging Face Hub 拉取以下关键组件：

主声学模型：index-tts-2-llm-large
阿里 Sambert 备用引擎（高可用兜底）
分词器（Tokenizer）与音素映射表

下载完成后，目录结构应如下：

./models/ ├── index-tts-2-llm-large/ │ ├── config.json │ ├── pytorch_model.bin │ └── tokenizer/ └── sambert-hifigan/ ├── generator.pth └── mel_basis.npy

4. 服务部署与启动

4.1 配置服务运行参数

编辑配置文件config.yaml，调整以下关键项：

tts: device: cpu use_sambert_fallback: true cache_dir: ./cache webui: host: 0.0.0.0 port: 7860 debug: false api: enable: true cors_allow_origin: "*"

解释：
device: cpu明确指定推理设备，关闭 GPU 自动探测。
use_sambert_fallback: true开启阿里 Sambert 引擎作为异常降级方案。
cors_allow_origin: "*"允许跨域请求，便于前端集成。

4.2 启动 WebUI 服务

返回项目根目录，启动可视化界面服务：

cd ../ source venv/bin/activate python -m app.webui --config config.yaml

成功启动后，终端将输出：

INFO: Started server process [PID] INFO: Uvicorn running on http://0.0.0.0:7860

此时可通过浏览器访问http://<服务器IP>:7860打开 WebUI 界面。

4.3 启动 RESTful API 服务（可选）

若仅需接口调用，可单独启动 API 服务：

python -m app.api --config config.yaml

API 文档地址：http://<IP>:7860/docs（Swagger UI 自动生成）

5. 使用说明与功能演示

5.1 WebUI 交互界面操作流程

输入文本
在主页面文本框中输入待合成内容，例如：
"欢迎使用 IndexTTS-2-LLM，这是一段由大语言模型驱动的高质量语音合成服务。"
选择发音人与语速
- 发音人选项：female-narrator,male-podcast,child-story等
- 语速调节：支持 0.8x ~ 1.5x 变速，不影响音调
点击“🔊 开始合成”按钮
页面显示加载动画，后台执行以下流程：
- 文本清洗 → 分词与音素转换 → 声学模型推理 → 声码器解码 → 音频封装
在线试听与下载
合成完成后，自动播放生成的.wav音频，支持：
- 播放/暂停控制
- 音量调节
- 下载为本地文件

5.2 API 接口调用示例

请求地址

POST http://<IP>:7860/tts/generate

请求体（JSON）

{ "text": "Hello, this is a test from IndexTTS API.", "speaker": "female-narrator", "speed": 1.1, "format": "wav" }

返回结果

{ "audio_base64": "UklGRigAAABXQVZFZm...", "duration": 3.2, "sample_rate": 24000 }

Python 调用代码

import requests import base64 url = "http://localhost:7860/tts/generate" payload = { "text": "你好，世界！", "speaker": "male-podcast", "speed": 1.0 } response = requests.post(url, json=payload) data = response.json() # 解码音频并保存 audio_data = base64.b64decode(data["audio_base64"]) with open("output.wav", "wb") as f: f.write(audio_data) print(f"音频已保存，时长: {data['duration']} 秒")

6. 性能优化与常见问题

6.1 CPU 推理加速建议

尽管无需 GPU 即可运行，但可通过以下方式提升响应速度：

启用 ONNX Runtime
将 PyTorch 模型导出为 ONNX 格式，并使用onnxruntime-cpu加速推理：
```
pip install onnxruntime python scripts/export_onnx.py --model-path ./models/index-tts-2-llm-large
```
启用 JIT 编译缓存
修改模型加载逻辑，添加torch.jit.script()包裹，首次运行稍慢，后续显著提速。
限制并发请求数
在生产环境中，通过 Nginx 或 Gunicorn 设置最大 worker 数，防止内存溢出。

6.2 常见问题与解决方案

问题现象	可能原因	解决方法
`ImportError: libgfortran.so.5: cannot open shared object file`	scipy 缺少 Fortran 运行库	`sudo apt install libgfortran-10-dev`
合成音频有杂音或断裂	声码器参数不匹配	切换至 Sambert 引擎：`use_sambert_fallback: true`
WebUI 页面无法加载	浏览器缓存旧资源	清除缓存或使用无痕模式访问
中文标点导致分词错误	输入未规范化	添加预处理：替换全角符号、去除多余空格