OmniVoice 维吾尔语 TTS 完整部署指南一、前言有一个本人非常不舒服的地方官方的图像界面有丑有慢还不如直接命令行跑本文档旨在帮助用户在 Windows 10/11 系统上从零开始部署 OmniVoice 维吾尔语 TTS实现批量语音合成。OmniVoice 是小米 Kaldi 团队开源的超大规模多语言 TTS 模型支持包括维吾尔语在内的 600 种以上语言。本文档所有步骤均经过实际验证按照顺序操作即可成功运行。二、系统要求项目最低要求推荐配置操作系统Windows 10/11Windows 10/11Python3.10.x3.10.11硬盘空间10 GB20 GB内存4 GB8 GB显卡无要求CPU运行NVIDIA RTX可选GPU加速网络可访问 hf-mirror.com稳定网络关键限制Python 版本必须为 3.10.x3.11 及以上版本部分依赖库不兼容AMD 显卡不支持 CUDA只能使用 CPU 运行如需 GPU 加速须使用 NVIDIA 显卡并安装对应 CUDA 驱动三、模型文件下载3.1 下载清单两个模型文件夹共计四个核心文件必须下载。OmniVoice 主模型约 2.45 GBmodel.safetensors2.45 GBconfig.json约 2 KBtokenizer.json约 11 MBtokenizer_config.json约 0.5 KB来源https://hf-mirror.com/k2-fsa/OmniVoice/tree/main音频分词器 Higgs约 806 MBmodel.safetensors806 MBconfig.json约 2.5 KBpreprocessor_config.json约 0.2 KB来源https://hf-mirror.com/eustlb/higgs-audio-v2-tokenizer/tree/main3.2 下载操作打开上述链接点击 Files and versions 标签逐个点击文件名进入详情页点击 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下载地址https://www.python.org/downloads/release/python-31011/下载 Windows installer (64-bit)双击安装务必勾选 Add Python to PATH一路 Next 完成安装验证安装python --version应显示 Python 3.10.11如果不勾选 Add Python to PATHpython 命令将无法使用需要重装或手动配置环境变量。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 安装 PyTorchPyTorch 是 OmniVoice 的深度学习运行框架。根据显卡情况选择对应版本。首先确认显卡类型nvidia-smi有输出表示有 NVIDIA 显卡应安装 CUDA 版。报错表示无 NVIDIA 显卡应安装 CPU 版。有 NVIDIA 显卡时安装 CUDA 版约 2.8 GBpython -m pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118无 NVIDIA 显卡时安装 CPU 版约 200 MBpython -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 安装 OmniVoicepython -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.pynotepad C:\Users\你的用户名\AppData\Local\Python\pythoncore-3.10-64\lib\site-packages\omnivoice\models\omnivoice.py6.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.pyimport 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( texttext, speedSPEED, instructINSTRUCT, generation_configOmniVoiceGenerationConfig(num_stepNUM_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, encodingutf-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_okTrue) 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, ftask_{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.6INSTRUCT 控制音色格式为 性别, 年龄, 音调NUM_STEP 控制推理步数值越小速度越快推荐值 16八、运行8.1 启动合成cd C:\AI_TTS venv\Scripts\activate python tts_batch.py8.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_1530458.3 终止运行按 CtrlC 可随时终止程序当前正在合成的任务完成后退出已完成文件保留。首次运行需要加载模型约 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 accentNUM_STEP 推理步数16 为最快速度32 为均衡64 为最慢但质量略高。十、推荐配置经过实际测试以下配置在清晰度和自然度上表现最佳参数值SPEED1.6INSTRUCTfemale, young adult, very low pitchNUM_STEP16此配置产生的声音风格为沉稳清晰的女声语速偏快但不急促适合维吾尔语新闻播报、有声书、教育内容等场景。如需调整更柔和温暖的声音用 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 GBC:/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 即可开始合成。
