智能时代：AI 与本地模型部署

欢迎来到 Linux 进阶的新领域。本章我们将专注于在本地部署 AI 模型，不再依赖昂贵的云端 API。

1. 为什么选择本地部署？

隐私保护：你的语音数据和文本内容永远不会离开你的设备。
低延迟：局域网内即刻响应，不受外网宽带限制。
无限可能：通过 API 调用，可以将 TTS 集成到你的博客、智能家居或机器人中。

2. 环境前置准备 (Essential)

在安装任何模型前，你需要确保 Linux 系统具备以下基础：

显卡驱动：如果是 NVIDIA 显卡，请参考第 12 章：NVIDIA 显卡排坑。建议 CUDA 版本在 11.8 - 12.8 之间。

依赖工具：安装 ffmpeg, git, 以及高效的 Python 包管理器 uv。

sudo apt install ffmpeg git
curl -LsSf https://astral.sh/uv/install.sh | sh

3. IndexTTS2 安装指南

IndexTTS2 是 Bilibili 开源的情感表达与时长可控的自回归零样本 TTS 系统。它是首个支持精确时长控制与自然时长生成结合的自回归 TTS 模型，同时实现了情感与说话人身份的解耦控制。

3.1 核心特性

精确时长控制：支持显式指定 token 数量以控制语音时长
情感表达控制：独立控制音色和情感，支持多模态情感输入
零样本语音克隆：仅需 3-5 秒参考音频即可复刻音色
多语言支持：中英文混合建模，支持拼音标注
三阶段训练：引入 GPT 潜在表示，提升高情感表达下的语音清晰度

3.2 基础安装

ℹ️ 重要说明

必须使用 uv 包管理器，其他工具（conda/pip）无法保证依赖正确，可能导致偶发 bug、GPU 加速失效等问题。

步骤 1：安装 Git LFS

# 安装 git-lfs
sudo apt install git-lfs
 
# 在仓库中启用 Git-LFS
git lfs install

步骤 2：克隆仓库并下载代码

git clone https://github.com/index-tts/index-tts.git
cd index-tts
 
# 下载大文件
git lfs pull

步骤 3：使用 uv 安装依赖

# 安装 uv（如未安装）
pip install -U uv
 
# 安装所有依赖（推荐）
uv sync --all-extras
 
# 国内用户可使用镜像加速
uv sync --all-extras --default-index "https://mirrors.aliyun.com/pypi/simple"

💡 可选功能

--all-extras：安装全部可选功能（WebUI、DeepSpeed）
--extra webui：仅安装 WebUI 支持
--extra deepspeed：仅安装 DeepSpeed 加速

⚠️ Windows 注意事项

DeepSpeed 在部分 Windows 环境较难安装，可去除 --all-extras。如遇 CUDA 相关报错，请确保已安装 NVIDIA CUDA Toolkit 12.8 及以上。

3.3 下载模型

方式一：Hugging Face 下载

# 安装 Hugging Face CLI
uv tool install "huggingface-hub[cli,hf_xet]"
 
# 下载 IndexTTS-2 模型
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints

方式二：ModelScope 下载（国内推荐）

# 安装 ModelScope CLI
uv tool install "modelscope"
 
# 下载模型
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints

💡 网络加速

如网络访问 HuggingFace 较慢，建议提前设置镜像：

export HF_ENDPOINT="https://hf-mirror.com"

3.4 GPU 加速检测

运行脚本检测是否有 GPU 以及 GPU 版本的 PyTorch：

uv run tools/gpu_check.py

3.5 快速体验

# 启动 WebUI
uv run webui.py
 
# 启用 FP16 推理（降低显存占用）
uv run webui.py --fp16
 
# 查看所有选项
uv run webui.py -h

浏览器访问 http://127.0.0.1:7860。

💡 运行提示

使用 uv run <file.py> 保证程序在 uv 创建的虚拟环境下运行。部分情况需要指定 PYTHONPATH：

PYTHONPATH="$PYTHONPATH:." uv run indextts/infer_v2.py

基础音色克隆：

from indextts.infer_v2 import IndexTTS2
 
tts = IndexTTS2(
    cfg_path="checkpoints/config.yaml",
    model_dir="checkpoints",
    use_fp16=False,
    use_cuda_kernel=False,
    use_deepspeed=False
)
 
text = "Translate for me, what is a surprise!"
tts.infer(
    spk_audio_prompt='examples/voice_01.wav',
    text=text,
    output_path="gen.wav",
    verbose=True
)

情感控制合成：

from indextts.infer_v2 import IndexTTS2
 
tts = IndexTTS2(
    cfg_path="checkpoints/config.yaml",
    model_dir="checkpoints"
)
 
text = "酒楼丧尽天良，开始借机竞拍房间，哎，一群蠢货。"
 
# 使用情感参考音频
tts.infer(
    spk_audio_prompt='examples/voice_07.wav',
    text=text,
    output_path="gen.wav",
    emo_audio_prompt="examples/emo_sad.wav",  # 情感参考
    emo_alpha=0.9,  # 情感权重 0.0-1.0
    verbose=True
)
 
# 直接指定情感向量 [高兴, 愤怒, 悲伤, 害怕, 厌恶,忧郁, 惊讶, 平静]
tts.infer(
    spk_audio_prompt='examples/voice_10.wav',
    text="哇塞！这个爆率也太高了！欧皇附体了！",
    output_path="gen.wav",
    emo_vector=[0, 0, 0, 0, 0, 0, 0.45, 0],  # 惊讶情感
    use_random=False,
    verbose=True
)
 
# 文本情感控制（自动生成情感向量）
tts.infer(
    spk_audio_prompt='examples/voice_12.wav',
    text="快躲起来！是他要来了！",
    output_path="gen.wav",
    use_emo_text=True,
    emo_text="你吓死我了！你是鬼吗？",  # 情感描述文本
    emo_alpha=0.6,
    verbose=True
)

💡 拼音控制

IndexTTS2 支持中文字符与拼音混合建模，用于精确发音控制：

之前你做DE5很好，所以这一次也DEI3做DE2很好才XING2。

合法拼音参考项目中的 checkpoints/pinyin.vocab 文件。

3.6 模型版本对比

版本	特性	状态
IndexTTS-2	时长控制 + 情感解耦	🔥 最新
IndexTTS-1.5	稳定性提升 + 英文优化	稳定版
IndexTTS-1.0	基础零样本 TTS	已归档

下载旧版本：

# HuggingFace
hf download IndexTeam/IndexTTS-1.5 --local-dir=checkpoints
 
# ModelScope
modelscope download --model IndexTeam/IndexTTS-1.5 --local_dir checkpoints

4. Qwen3-TTS (阿里千问) 部署实践

Qwen3-TTS 支持极其自然的语音克隆和 12Hz 的超高速推理。

4.1 快速使用 (PyPI 安装)

最简单的方式是从 PyPI 安装 qwen-tts 包。推荐使用独立隔离环境避免依赖冲突：

# 创建干净的 Python 3.12 虚拟环境
uv venv --python 3.12
 
# 安装 qwen-tts 及其运行时依赖
uv pip install -U qwen-tts
 
# (可选) 安装 Flash Attention 2 以降低显存占用
# 仅适用于兼容的 GPU（详见官方文档）
uv pip install -U flash-attn --no-build-isolation
 
# 如果内存 < 96GB，限制编译任务数
MAX_JOBS=4 uv pip install -U flash-attn --no-build-isolation

💡 Flash Attention 2 说明

Flash Attention 2 仅在模型以 torch.float16 或 torch.bfloat16 加载时可用。请确保你的 GPU 支持此特性。

4.2 开发模式 (源码可编辑安装)

如果需要修改代码或贡献开发，从源码以可编辑模式安装：

# 克隆仓库
git clone https://github.com/QwenLM/Qwen3-TTS.git
cd Qwen3-TTS
 
# 创建虚拟环境并以可编辑模式安装
uv venv --python 3.12
uv pip install -e .
 
# (可选) 开发环境安装 Flash Attention 2
MAX_JOBS=4 uv pip install -U flash-attn --no-build-isolation

4.3 模型说明与手动下载

Qwen3-TTS 提供了多个模型版本，根据你的需求选择合适的模型：

模型对比

模型	特性	语言支持	流式	指令控制
Qwen3-TTS-12Hz-1.7B-VoiceDesign	基于描述设计语音	中/英/日/韩/德/法/俄/葡/西/意	✅	✅
Qwen3-TTS-12Hz-1.7B-CustomVoice	支持语音克隆 + 9 种预设音色	中/英/日/韩/德/法/俄/葡/西/意	✅	✅
Qwen3-TTS-12Hz-1.7B-Base	3 秒快速语音克隆基础模型	中/英/日/韩/德/法/俄/葡/西/意	✅
Qwen3-TTS-12Hz-0.6B-CustomVoice	轻量级版本 + 9 种预设音色	中/英/日/韩/德/法/俄/葡/西/意	✅
Qwen3-TTS-12Hz-0.6B-Base	轻量级基础模型	中/英/日/韩/德/法/俄/葡/西/意	✅

💡 选择建议

1.7B 系列: 显存充足（12GB+）时的首选，效果最佳
0.6B 系列: 显存受限（6-8GB）时的轻量选择
VoiceDesign: 需要通过文字描述定制语音风格
CustomVoice: 需要克隆特定声音或使用预设音色
Base: 仅需基础功能或用于微调训练

手动下载模型权重

模型权重会在首次运行时自动下载。如果你的网络环境不佳，可以提前手动下载：

# 通过 ModelScope 下载（推荐国内用户）
uv pip install -U modelscope
 
# Tokenizer (必需)
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz --local_dir ./Qwen3-TTS-Tokenizer-12Hz
 
# 1.7B 系列模型
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local_dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-Base --local_dir ./Qwen3-TTS-12Hz-1.7B-Base
 
# 0.6B 系列模型（轻量级）
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-Base --local_dir ./Qwen3-TTS-12Hz-0.6B-Base

或者通过 Hugging Face 下载（海外用户推荐）：

# 安装 Hugging Face CLI
uv pip install -U "huggingface_hub[cli]"
 
# Tokenizer
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz --local-dir ./Qwen3-TTS-Tokenizer-12Hz
 
# 1.7B 系列模型
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir ./Qwen3-TTS-12Hz-1.7B-Base
 
# 0.6B 系列模型
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-Base --local-dir ./Qwen3-TTS-12Hz-0.6B-Base

4.4 启动 Web UI Demo

安装 qwen-tts 包后，可以直接运行 qwen-tts-demo 启动官方 Web UI。

命令参数说明

完整命令格式：qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000

参数解释：

参数	说明
`qwen-tts-demo`	qwen-tts 包提供的 CLI 入口命令
`Qwen/...`	模型路径 - Hugging Face 上的模型标识符
`--ip`	指定 Web UI 绑定的网络接口
`0.0.0.0`	监听所有网卡，允许从局域网内任意设备访问
`--port`	指定 Web UI 监听的端口号
`8000`	端口号，浏览器访问 http://localhost:8000

启动命令

# 查看帮助信息
qwen-tts-demo --help
 
# CustomVoice 模型 - 支持语音克隆
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000
 
# VoiceDesign 模型 - 支持语音设计
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --ip 0.0.0.0 --port 8000
 
# Base 模型 - 基础版本
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base --ip 0.0.0.0 --port 8000

访问 http://localhost:8000 即可在浏览器中使用 Web UI。

💡 模型选择建议

CustomVoice: 需要克隆特定声音时使用
VoiceDesign: 需要设计自定义语音风格时使用
Base: 仅需基础 TTS 功能时使用

2026-02-27 文档初稿完成，涵盖 IndexTTS 与 Qwen-TTS 的本地部署实战。

智能时代：AI 与本地模型部署

1. 为什么选择本地部署？

2. 环境前置准备 (Essential)

3. IndexTTS2 安装指南

3.1 核心特性

3.2 基础安装

步骤 1：安装 Git LFS

步骤 2：克隆仓库并下载代码

步骤 3：使用 uv 安装依赖

3.3 下载模型

方式一：Hugging Face 下载

方式二：ModelScope 下载（国内推荐）

3.4 GPU 加速检测

3.5 快速体验

3.6 模型版本对比

4. Qwen3-TTS (阿里千问) 部署实践

4.1 快速使用 (PyPI 安装)

4.2 开发模式 (源码可编辑安装)

4.3 模型说明与手动下载

模型对比

手动下载模型权重

4.4 启动 Web UI Demo

命令参数说明

启动命令

14. 智能时代：AI 与本地模型部署

On This Page