注：若本地存在智能体(好点的模型) codex、Claude Code、openClaw、Hermes 直接去看帖子《小米 TTS- OmniVoice 大模型一键部署(AI代理)》
OmniVoice Windows 本地部署教程
本文以个人机器的实际部署状态为参考，适合在 Windows + NVIDIA 显卡环境下部署 OmniVoice 本地文字转语音模型。
1. 当前已验证环境
本机已经验证通过的环境如下：
项目目录: D:\OmniVoice
Python: 3.10.6
PyTorch: 2.8.0+cu128
Torchaudio: 2.8.0+cu128
Transformers: 5.3.0
CUDA: 可用
显卡: NVIDIA GeForce RTX 4060 Laptop GPU 8G显存
模型目录: D:\OmniVoice\models\OmniVoice
模型体积: 约 3.395 GB
模型目录里最关键的文件包括：
D:\OmniVoice\models\OmniVoice\model.safetensors
D:\OmniVoice\models\OmniVoice\tokenizer.json
D:\OmniVoice\models\OmniVoice\config.json
D:\OmniVoice\models\OmniVoice\audio_tokenizer\model.safetensors
如果这些文件不存在，说明代码已经下载了，但模型权重还没有下载完整。
2. 准备环境
先安装这些基础软件：
Python 3.10
Git
NVIDIA 显卡驱动
如果要处理更多音频格式，建议安装 FFmpeg。本机当前没有检测到 FFmpeg，OmniVoice 仍能运行，但 pydub 会提示：
Couldn't find ffmpeg or avconv - defaulting to ffmpeg, but may not work
这不是一定会导致启动失败，但如果后续遇到音频格式转换问题，优先安装 FFmpeg。
3. 下载项目代码
进入你想放项目的目录，然后克隆代码：
cd D:\
git clone https://github.com/k2-fsa/OmniVoice.git
cd D:\OmniVoice
如果已经有 D:\OmniVoice，可以跳过这一步。
4. 创建虚拟环境
在项目根目录执行：
cd D:\OmniVoice
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
如果 PowerShell 不允许激活虚拟环境，可以先执行：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
然后重新运行：
.\.venv\Scripts\activate
5. 安装 PyTorch CUDA 版本
本机使用的是 CUDA 12.8 对应的 PyTorch：
pip install torch==2.8.0+cu128 torchaudio==2.8.0+cu128 --extra-index-url https://download.pytorch.org/whl/cu128
安装完成后，检查 CUDA 是否可用：
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'no cuda')"
成功时应看到类似结果：
2.8.0+cu128
True
NVIDIA GeForce RTX 4060 Laptop GPU
6. 安装 OmniVoice 依赖
在项目根目录执行：
cd D:\OmniVoice
.\.venv\Scripts\activate
pip install -e .
如果安装时网络较慢，可以使用国内 PyPI 镜像：
pip install -e . -i https://mirrors.aliyun.com/pypi/simple
注意：如果 PyTorch 已经按上一步装好了，不要让后续依赖安装把 CUDA 版 PyTorch 替换成 CPU 版。
7. 下载模型权重
OmniVoice 的 GitHub 仓库只包含代码，模型权重在 Hugging Face：
https://huggingface.co/k2-fsa/OmniVoice
推荐把模型放到：
D:\OmniVoice\models\OmniVoice
如果 Hugging Face 下载慢，可以使用镜像并关闭 Xet：
cd D:\OmniVoice
.\.venv\Scripts\activate
$env:HF_ENDPOINT='https://hf-mirror.com'
$env:HF_HUB_DISABLE_XET='1'
python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='k2-fsa/OmniVoice', local_dir='D:/OmniVoice/models/OmniVoice', local_dir_use_symlinks=False)"
下载完成后检查模型体积：
$root='D:\OmniVoice\models\OmniVoice'
$bytes=(Get-ChildItem $root -Recurse -File -Force | Measure-Object Length -Sum).Sum
[math]::Round($bytes/1GB,3)
当前本机完整模型约为：
3.395 GB
如果只有几 KB 或只有 config.json，说明模型权重还没有真正下载下来。
8. 启动 Web UI
启动本地网页界面：
cd D:\OmniVoice
.\.venv\Scripts\activate
$env:HF_ENDPOINT='https://hf-mirror.com'
.\.venv\Scripts\omnivoice-demo.exe --model D:\OmniVoice\models\OmniVoice --device cuda --ip 127.0.0.1 --port 8001
启动成功后，在浏览器打开：
http://127.0.0.1:8001
如果不想让它自动加载 Whisper ASR，可以加 --no-asr：
.\.venv\Scripts\omnivoice-demo.exe --model D:\OmniVoice\models\OmniVoice --device cuda --ip 127.0.0.1 --port 8001 --no-asr
注意：加了 --no-asr 后，参考音频的自动转写不可用。做声音克隆时最好手动填写参考音频对应文字。
9. 在网页里做实验
Web UI 不只是用来验证部署是否成功，也可以直接用来做各种语音实验。启动后打开：
http://127.0.0.1:8001
常见实验方式：
自动音色：只输入要合成的文字，让模型自动选择声音。
音色设计：输入文字，同时填写类似 female, low pitch, british accent 这样的音色描述。
声音克隆：上传一段参考音频，再填写参考音频对应文字，让模型模仿这段声音说新内容。
做声音克隆时，参考音频建议：
时长 3 到 10 秒
人声清晰
背景噪音少
尽量只有一个人在说话
参考音频文字尽量和音频内容一致
如果启动 Web UI 时没有加 --no-asr，模型可以尝试自动识别参考音频文字；如果加了 --no-asr，就需要手动填写参考音频对应文本。
网页实验适合调效果，比如：
测试中文、英文或多语言合成效果
测试不同音色描述
测试同一段文本在不同音色下的区别
测试参考音频对声音克隆效果的影响
测试 speed、duration、num_step 等生成参数
如果网页已经能生成音频，就说明本地模型服务已经在正常工作，不需要再调用豆包、OpenAI 或其他云端 TTS API。
10. 命令行生成语音
自动音色生成：
cd D:\OmniVoice
.\.venv\Scripts\activate
.\.venv\Scripts\omnivoice-infer.exe --model D:\OmniVoice\models\OmniVoice --device cuda --text "你好，这是一次本地文字转语音测试。" --output outputs\hello.wav
指定音色风格生成：
.\.venv\Scripts\omnivoice-infer.exe --model D:\OmniVoice\models\OmniVoice --device cuda --text "Hello, this is a local text to speech test." --instruct "female, low pitch, british accent" --output outputs\hello_design.wav
声音克隆生成：
.\.venv\Scripts\omnivoice-infer.exe --model D:\OmniVoice\models\OmniVoice --device cuda --text "你好，这是根据参考音频克隆出来的声音。" --ref_audio "D:\OmniVoice\audio素材\ref.wav" --ref_text "这里填写参考音频里说的话。" --output outputs\clone.wav
参考音频建议使用 3 到 10 秒的清晰人声片段，背景噪音越少越好。
11. 判断显卡是否在运行
打开一个新的 PowerShell，执行：
nvidia-smi
看这几个位置：
Memory-Usage: 显存占用
GPU-Util: GPU 当前计算占用
Processes: 是否有 python.exe
如果 Processes 里有 python.exe，并且显存占用明显升高，说明模型已经加载到显卡上。
如果显存占着但 GPU-Util 很低，通常表示模型加载好了但暂时空闲。
如果 GPU-Util 很高，表示模型正在推理生成语音。
12. 常见问题
12.1 只有代码，没有模型
现象：
D:\OmniVoice\models\OmniVoice 目录不存在
或模型目录只有几 KB
或只有 config.json
原因：
GitHub 只放项目代码，Hugging Face 才放模型权重。
解决：
$env:HF_ENDPOINT='https://hf-mirror.com'
$env:HF_HUB_DISABLE_XET='1'
python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='k2-fsa/OmniVoice', local_dir='D:/OmniVoice/models/OmniVoice', local_dir_use_symlinks=False)"
12.2 Hugging Face 下载卡住
现象：
出现 .incomplete 文件
文件大小一直不增长
下载长时间没有进度
解决：
$env:HF_ENDPOINT='https://hf-mirror.com'
$env:HF_HUB_DISABLE_XET='1'
然后重新执行模型下载命令。
12.3 CUDA 不可用
现象：
torch.cuda.is_available() 输出 False
可能原因：
安装了 CPU 版 PyTorch
NVIDIA 驱动异常
Python 环境用错了
解决：
.\.venv\Scripts\activate
pip install torch==2.8.0+cu128 torchaudio==2.8.0+cu128 --extra-index-url https://download.pytorch.org/whl/cu128 --force-reinstall
12.4 PowerShell 输出乱码或 pip 报 GBK 编码错误
可以先设置 UTF-8：
$env:PYTHONUTF8='1'
chcp 65001
再重新执行命令。
12.5 缺少 FFmpeg
现象：
Couldn't find ffmpeg or avconv
解决：
安装 FFmpeg，并把 ffmpeg.exe 所在目录加入系统 PATH。
安装后重新打开 PowerShell，执行：
ffmpeg -version
能输出版本号就表示安装成功。
13. 本机已验证结果
当前机器已经成功生成过：
D:\OmniVoice\outputs\hello.wav
当前模型已经下载到：
D:\OmniVoice\models\OmniVoice
Web UI 最近一次日志显示模型已经加载到 CUDA：
Loading model from D:\OmniVoice\models\OmniVoice, device=cuda
Loading weights: 100%
因此这台电脑的本地 OmniVoice 部署已经具备运行条件。
