OmniVoice 维吾尔语 TTS 完整部署指南

OmniVoice 维吾尔语 TTS 完整部署指南

一、前言

有一个本人非常不舒服的地方官方的图像界面有丑有慢，还不如直接命令行跑！

本文档旨在帮助用户在 Windows 10/11 系统上从零开始部署 OmniVoice 维吾尔语 TTS，实现批量语音合成。OmniVoice 是小米 Kaldi 团队开源的超大规模多语言 TTS 模型，支持包括维吾尔语在内的 600 种以上语言。

本文档所有步骤均经过实际验证，按照顺序操作即可成功运行。

二、系统要求

关键限制：

• Python 版本必须为 3.10.x，3.11 及以上版本部分依赖库不兼容
• AMD 显卡不支持 CUDA，只能使用 CPU 运行
• 如需 GPU 加速，须使用 NVIDIA 显卡并安装对应 CUDA 驱动

三、模型文件下载

3.1 下载清单

两个模型文件夹，共计四个核心文件必须下载。

OmniVoice 主模型（约 2.45 GB）：

• model.safetensors（2.45 GB）
• config.json（约 2 KB）
• tokenizer.json（约 11 MB）
• tokenizer_config.json（约 0.5 KB）
• 来源：https://hf-mirror.com/k2-fsa/OmniVoice/tree/main

音频分词器 Higgs（约 806 MB）：

• model.safetensors（806 MB）
• config.json（约 2.5 KB）
• preprocessor_config.json（约 0.2 KB）
• 来源：https://hf-mirror.com/eustlb/higgs-audio-v2-tokenizer/tree/main

3.2 下载操作

1. 打开上述链接
2. 点击 Files and versions 标签
3. 逐个点击文件名进入详情页
4. 点击 Download 按钮保存

Higgs 分词器为门控仓库，需要登录 hf-mirror.com 并点击 Agree and access repository 授权后才能下载。如果跳过授权直接下载会遇到 401 错误。

3.3 最终目录结构

所有文件必须按以下结构存放，路径中不能包含中文或空格。

C:\AI_TTS
├── OmniVoice_model
│ ├── model.safetensors (2.45 GB)
│ ├── config.json
│ ├── tokenizer.json
│ └── tokenizer_config.json
├── higgs-audio-v2-tokenizer
│ ├── model.safetensors (806 MB)
│ ├── config.json
│ └── preprocessor_config.json

四、Python 环境搭建

4.1 安装 Python 3.10.11

1. 下载地址：https://www.python.org/downloads/release/python-31011/
2. 下载 Windows installer (64-bit)
3. 双击安装，务必勾选 Add Python to PATH
4. 一路 Next 完成安装

验证安装：

python --version

应显示 Python 3.10.11

如果不勾选 Add Python to PATH，python 命令将无法使用，需要重装或手动配置环境变量。Python 3.11 及以上版本会导致部分库不兼容，必须使用 3.10.x。

4.2 创建虚拟环境

虚拟环境用于隔离项目依赖，避免不同项目之间的包冲突。

mkdir C:\AI_TTS cd C:\AI_TTS python -m venv venv

激活虚拟环境：

venv\Scripts\activate

命令行出现 (venv) 前缀即表示激活成功。每次操作前必须先激活虚拟环境，否则包会安装到系统 Python 中。

五、安装依赖库

5.1 安装 PyTorch

PyTorch 是 OmniVoice 的深度学习运行框架。根据显卡情况选择对应版本。

首先确认显卡类型：

nvidia-smi

有输出表示有 NVIDIA 显卡，应安装 CUDA 版。报错表示无 NVIDIA 显卡，应安装 CPU 版。

有 NVIDIA 显卡时安装 CUDA 版（约 2.8 GB）：

python -m pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118

无 NVIDIA 显卡时安装 CPU 版（约 200 MB）：

python -m pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu

如果下载超时，换用清华源：

python -m pip install torch torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple/

验证安装：

python -c "import torch; print(torch.cuda.is_available())"

输出 True 表示 CUDA 版成功，输出 False 表示 CPU 版或 CUDA 版未正确安装。

AMD 显卡不支持 CUDA，必须安装 CPU 版。如果装了 CPU 版但想用显卡加速，需要重装 CUDA 版。

5.2 安装 OmniVoice

python -m pip install omnivoice soundfile -i https://pypi.tuna.tsinghua.edu.cn/simple/

验证安装：

python -c "from omnivoice import OmniVoice; print('OK')"

输出 OK 即表示安装成功。

如果报 No module named torch，说明 PyTorch 没装好，返回 5.1 重新安装。如果报 setuptools 相关错误，执行python -m pip install --upgrade pip升级 pip 后重试。

六、修改源码（关键步骤）

6.1 为什么要修改

OmniVoice 加载时会自动联网下载 Higgs 音频分词器。由于国内网络可能无法访问 Hugging Face，或者下载速度极慢，需要强制程序使用本地已下载好的 Higgs 文件夹。

6.2 找到源码文件

python -c "import omnivoice; print(omnivoice.__file__)"

输出示例：
C:\Users\你的用户名\AppData\Local\Python\pythoncore-3.10-64\lib\site-packages\omnivoice_init_.py

用记事本打开 omnivoice\models\omnivoice.py：

notepad C:\Users\你的用户名\AppData\Local\Python\pythoncore-3.10-64\lib\site-packages\omnivoice\models\omnivoice.py

6.3 修改 _resolve_model_path 函数

搜索 def _resolve_model_path，找到原始代码：

def _resolve_model_path(name_or_path: str) -> str: if os.path.isdir(name_or_path): return name_or_path from huggingface_hub import snapshot_download return snapshot_download(name_or_path)

替换为：

def _resolve_model_path(name_or_path: str) -> str: if os.path.isdir(name_or_path): return name_or_path if name_or_path == "eustlb/higgs-audio-v2-tokenizer": return "C:/AI_TTS/higgs-audio-v2-tokenizer" from huggingface_hub import snapshot_download return snapshot_download(name_or_path)

保存文件。

修改后路径必须与实际 Higgs 文件夹位置一致。如果路径不对，程序仍会尝试联网下载。修改后没有保存会导致修改无效。

七、创建任务与脚本

7.1 创建任务文件 tasks.json

在 C:\AI_TTS 目录下创建 tasks.json：

[ { "text": "ABS سىستېمىسى تورمۇز ئۈنۈمىنى قانداق ئەھۋالدا ئەڭ چوڭ چەكلىمىدە تولۇق جارىي قىلدۇرىدۇ .", "filename": "abs_1.wav" }, { "text": "ئاپتوموبىلنى جىددىي تورمۇزلىغاندا ABS سىستېمىسى قانداق رول ئوينايدۇ؟", "filename": "abs_2.wav" }, { "text": "رەسىمدىكى ۋىكليۇچاتېل ئاپتوموبىلنىڭ قايسى ئورنىنى كونترول قىلىدۇ ؟", "filename": "control_1.wav" } ]

JSON 格式必须正确，不能有多余的逗号。文本必须使用 UTF-8 编码保存，否则合成结果会出现乱码。filename 只能使用字母、数字、下划线和点。

7.2 创建批量合成脚本 tts_batch.py

在 C:\AI_TTS 目录下创建 tts_batch.py：

import os import json import signal import sys from datetime import datetime from omnivoice import OmniVoice import soundfile as sf from omnivoice import OmniVoiceGenerationConfig MODEL_PATH = "C:/AI_TTS/OmniVoice_model" TASKS_FILE = "C:/AI_TTS/tasks.json" OUTPUT_BASE = "C:/AI_TTS/output" SPEED = 1.6 INSTRUCT = "female, young adult, very low pitch" NUM_STEP = 16 running = True def signal_handler(sig, frame): global running print("\n收到终止信号，正在完成当前任务后退出...") running = False signal.signal(signal.SIGINT, signal_handler) def load_model(): print("加载模型中...") model = OmniVoice.from_pretrained(MODEL_PATH) print("模型加载完成") return model def generate_audio(model, text, output_path): audio = model.generate( text=text, speed=SPEED, instruct=INSTRUCT, generation_config=OmniVoiceGenerationConfig(num_step=NUM_STEP) ) sf.write(output_path, audio[0], 24000) def main(): global running if not os.path.exists(TASKS_FILE): print(f"任务文件不存在: {TASKS_FILE}") return with open(TASKS_FILE, 'r', encoding='utf-8') as f: tasks = json.load(f) if not tasks: print("任务列表为空") return timestamp = datetime.now().strftime('%Y%m%d_%H%M%S') output_dir = os.path.join(OUTPUT_BASE, timestamp) os.makedirs(output_dir, exist_ok=True) print(f"输出目录: {output_dir}") model = load_model() total = len(tasks) for idx, task in enumerate(tasks, 1): if not running: print("已终止") break text = task.get('text', '').strip() if not text: print(f"跳过第 {idx} 条：文本为空") continue filename = task.get('filename', f'task_{idx:03d}.wav') output_path = os.path.join(output_dir, filename) print(f"[{idx}/{total}] 合成中...") try: generate_audio(model, text, output_path) print(f"[{idx}/{total}] 完成: {filename}") except Exception as e: print(f"[{idx}/{total}] 失败: {e}") print(f"全部完成。文件保存在: {output_dir}") if __name__ == "__main__": main()

脚本中的三个核心参数：

• SPEED 控制语速，1.0 为正常，推荐值 1.2 至 1.6
• INSTRUCT 控制音色，格式为 性别, 年龄, 音调
• NUM_STEP 控制推理步数，值越小速度越快，推荐值 16

八、运行

8.1 启动合成

cd C:\AI_TTS venv\Scripts\activate python tts_batch.py

8.2 正常输出示例

输出目录: C:/AI_TTS/output/20260904_153045 加载模型中... 模型加载完成 [1/3] 合成中... [1/3] 完成: abs_1.wav [2/3] 合成中... [2/3] 完成: abs_2.wav [3/3] 合成中... [3/3] 完成: control_1.wav 全部完成。文件保存在: C:/AI_TTS/output/20260904_153045

8.3 终止运行

按 Ctrl+C 可随时终止程序，当前正在合成的任务完成后退出，已完成文件保留。

首次运行需要加载模型，约 1 至 2 分钟，属于正常现象。CPU 运行每条约 30 至 60 秒，这是 CPU 推理的正常速度。

九、核心参数说明

SPEED 语速，1.0 为正常语速，推荐值 1.2 至 1.6，维吾尔语建议 1.4 至 1.6。

INSTRUCT 音色描述，格式为 性别, 年龄, 音调。同一类别只能选一个值，如 high pitch 和 moderate pitch 不能同时使用。

可用的性别值：male, female
可用的年龄值：child, teenager, young adult, middle-aged, elderly
可用的音调值：very low pitch, low pitch, moderate pitch, high pitch, very high pitch
可用的口音值：american accent, british accent, australian accent, indian accent, chinese accent

NUM_STEP 推理步数，16 为最快速度，32 为均衡，64 为最慢但质量略高。

十、推荐配置

经过实际测试，以下配置在清晰度和自然度上表现最佳：

此配置产生的声音风格为沉稳清晰的女声，语速偏快但不急促，适合维吾尔语新闻播报、有声书、教育内容等场景。

如需调整：

• 更柔和温暖的声音：用 moderate pitch 替代 very low pitch
• 更年轻明亮的声音：用 high pitch 替代 very low pitch
• 更慢更稳的语速：SPEED 设为 1.4
• 男声：用 male, young adult, very low pitch

十一、常见错误与解决方案

错误：ModuleNotFoundError: No module named torch
原因：PyTorch 未安装或装错环境
解决：确认虚拟环境已激活，重新安装 PyTorch

错误：ImportError: cannot import name OmniVoice
原因：omnivoice 未安装
解决：pip install omnivoice

错误：OSError: model.safetensors 文件不存在
原因：模型文件未下载或路径错误
解决：确认 C:/AI_TTS/OmniVoice_model/model.safetensors 存在

错误：401 Unauthorized
原因：访问门控仓库未授权
解决：浏览器登录 Hugging Face，点击 Agree and access repository

错误：404 Not Found
原因：镜像站地址错误
解决：确认使用 hf-mirror.com 而非 huggingface.co

错误：No space left on device
原因：硬盘空间不足
解决：至少需要 10 GB 空闲空间

错误：AssertionError: Torch not compiled with CUDA enabled
原因：装了 CPU 版 PyTorch 但指定了 GPU 参数
解决：去掉 --device cuda 参数

错误：合成速度极慢，几分钟一条
原因：CPU 运行且推理步数过高
解决：将 NUM_STEP 改为 16

错误：输出不是维吾尔语，是乱码
原因：模型加载错误或 instruct 参数冲突
解决：确认 MODEL_PATH 正确，检查 instruct 参数是否有冲突项

十二、最终检查清单

运行前逐项确认：

• Python 3.10.11 已安装且 python --version 显示正确
• C:/AI_TTS/OmniVoice_model/model.safetensors 存在，大小约 2.45 GB
• C:/AI_TTS/higgs-audio-v2-tokenizer/model.safetensors 存在，大小约 806 MB
• 虚拟环境已激活，命令行有 (venv) 前缀
• PyTorch 已安装，python -c “import torch” 无报错
• OmniVoice 已安装，python -c “from omnivoice import OmniVoice” 无报错
• 源码已修改，_resolve_model_path 函数已替换
• tasks.json 已创建，至少有一条任务
• tts_batch.py 已创建

全部确认后，运行 python tts_batch.py 即可开始合成。