安装前必看的检查清单：如何为 dsh-voice-ai-girlfriend 配好环境？显存、CUDA、WSL2 一次装齐-平芜编程栈

【免费下载链接】dsh-voice-ai-girlfriend

语音 AI 女友（Voice AI girlfriend for DeepSeek Harness）：Whisper 语音输入 + Qwen3-TTS 声音克隆 + 句子级流式朗读 + 数字人动画窗。插话/排队双模式，说话即打断。

项目地址：https://gitcode.com/gh_mirrors/ds/dsh-voice-ai-girlfriend

dsh-voice-ai-girlfriend 是一款为 DeepSeek Harness（DSH）打造的语音 AI 女友插件：点一下麦克风，它用 FunASR/Whisper 听懂你说话，再用 OmniVoice/Qwen3-TTS 克隆音色逐句朗读回复，右侧数字人窗口同步开口。安装这类多引擎语音项目，环境没配好是最大的坑。本文给出一份安装前环境检查清单，把显存、CUDA 驱动、WSL2 一次性装齐，装完照着自检表过一遍就能开工。

语音AI女友插件 dsh-voice-ai-girlfriend 女友窗中的数字人形象

一、硬件检查清单：显存、显卡、磁盘先看这里

⚠️ 一句话结论：必须有 NVIDIA 独立显卡（模型推理依赖 CUDA），显存16GB 起步，8GB 不推荐。

检查项	要求	验证命令
系统	Windows 10/11 64 位（推荐 Win11，WSL2 体验更好）	`winver`
显卡	NVIDIA 独显，且驱动正常	`nvidia-smi`（能显示显卡信息即通过）
显存	建议 16GB 或以上	`nvidia-smi`
内存	建议 16GB 以上	—
磁盘	至少 30GB 剩余空间	—

nvidia-smi是最硬核的一条：如果提示「不是内部或外部命令」，说明没有 NVIDIA 显卡或驱动没装好——这种情况装不了本项目，先别往下走。

显存占用速查（运行时实测）

组件	显存占用
OmniVoice TTS（WSL2 + FlashInfer，推荐）	空闲约 5.3GB，推理峰值约 11GB
Qwen3-TTS 1.7B（fp16，备选降级）	约 3.7GB
FunASR Paraformer-large（fp16，语音识别）	约 1GB
DUIX 数字人（视频生成时）	约 4-6GB
全链路峰值（TTS + 数字人同时工作）	约 15GB

💡 小建议：16GB 显存下 OmniVoice 与 DUIX 数字人建议错峰工作（TTS 合成完再生成视频），这也是项目默认的分段流水线思路。

二、软件环境清单：WSL2、CUDA、Docker 一次装齐

以下软件全部为一次性安装，装完各用一条命令验证。

#	软件	用途	验证命令
1	Git	克隆仓库	`git --version`
2	Python（3.10 或更高）	语音桥接 voice_bridge	`python --version`
3	NVIDIA 驱动（最新版）	提供 CUDA 运行环境	`nvidia-smi`
4	Node.js（LTS）+ pnpm	运行 DSH	`node --version`/`pnpm --version`
5	WSL2（Ubuntu 22.04）	OmniVoice TTS 引擎	`wsl -d Ubuntu-22.04 -- hostname -I`
6	Docker Desktop	DUIX 数字人容器	`docker --version`

1. Python：安装时务必勾选 "Add Python to PATH"

这是新手最容易漏的一步。不勾选的话，后面所有python命令都会找不到，官方 Python 安装包下载即可，一路下一步。

2. CUDA：你其实不需要单独装 CUDA Toolkit

✅ 本项目不需要手动安装 CUDA Toolkit——pip安装的 PyTorch 自带 CUDA 运行库，只要 NVIDIA 驱动够新就行。驱动太旧才是 CUDA 报错的常见根源，建议直接更新到最新驱动。

3. WSL2：OmniVoice TTS 的家

项目默认 TTS 引擎已从 Qwen3-TTS 换成OmniVoice（600+ 语言、声音克隆 + 音色设计双模式），跑在 WSL2 里并用FlashInfer做 CUDA Graph 加速。收益非常直观：

指标	旧（Qwen3-TTS）	新（OmniVoice + FlashInfer）
克隆首轮出音	18.3s	1.6s
热态出音	约 2.2s	约 1.3s
空闲显存	7GB（常驻）	5.3GB

WSL2 内部环境的关键点（装环境时注意）：

用 uv 建虚拟环境：torch 2.13.0+cu130 + flashinfer 0.6.18 + nvcc cu13；
Blackwell 架构（RTX 50 系，sm_120）必须用 cu13 系列，cu129 会报「requires GPUs with sm75」；
WSL2 里若残留旧版 nvcc（如 12.8）会干扰 flashinfer 的版本检测，启动服务前要把CUDA_HOME指向 cu13 的 nvcc 目录。

这些繁琐操作项目已经封装好：双击 bridge/start-omnivoice-wsl.cmd（逻辑见 bridge/start-omnivoice-wsl.ps1），它会自动拉起 WSL2 → 取 IP → 同步桥接配置 → 等:9877就绪。

⚠️WSL2 IP 是动态的：重启后可能变化，Windows 侧必须通过 IP（wsl hostname -I查询）访问http://<WSL2-IP>:9877，localhost 转发在 WSL2 网络模式下不可用。上面的一键脚本会在 IP 变化时自动更新bridge-config.json的omnivoice.base并重启桥接，不用手工改。

4. Docker Desktop：数字人（DUIX）的容器

可选增强项。项目提供了精简适配版 compose（bridge/docker-compose-5060ti.yml），已适配 RTX 50 系列（5060 Ti / 5090 同架构），去掉了原项目的 Fish Speech 与 FunASR，只保留数字人视频生成服务（宿主端口:8383，冷启动 1-3 分钟）。不想出数字人视频可以先跳过，纯语音模式完全可用。

三、硬盘空间预估：预留 30GB 才从容

项目	大小
本项目代码 + 素材	约 8MB
Python 虚拟环境 + 依赖（含 PyTorch）	约 5-8GB
FunASR Paraformer 中文模型（`models/funasr/`）	约 850MB
OmniVoice TTS 环境（WSL2 内，含模型 + torch cu130 + FlashInfer）	约 10GB
deepseek-harness + node_modules	约 2-4GB

依赖清单见 bridge/requirements.txt（pip install -r bridge/requirements.txt会装 PyTorch、transformers、speech-to-speech 等，体积大、耗时长，耐心等待）。

四、装完环境后的 5 步自检

全部通过后，就可以进入正式安装（克隆仓库 → 建 venv → 装模型 → 填 bridge/bridge-config.example.json 复制出的配置）。

[ ] 1. winver —— Windows 10/11 64 位 [ ] 2. nvidia-smi —— 显卡信息正常，显存 ≥ 16GB [ ] 3. python --version —— 3.10+（PATH 生效） [ ] 4. wsl -d Ubuntu-22.04 -- hostname -I —— 有 IP 输出 [ ] 5. docker --version —— Docker Desktop 可正常启动

五、常见问题快查

问题	原因与处理
`nvidia-smi`报「不是内部或外部命令」	没有 NVIDIA 显卡或驱动没装好，先装驱动
pip 装依赖太慢/超时	换清华 PyPI 镜像：`pip install -r bridge/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`
HuggingFace 模型下载慢	设置`set HF_ENDPOINT=https://hf-mirror.com`后重试
flashinfer 报 sm75 架构错误	WSL2 内 torch/flashinfer 必须 cu13 系列，且`CUDA_HOME`指向 cu13 的 nvcc
Windows 连不上`:9877`	WSL2 IP 变了，重跑 bridge/start-omnivoice-wsl.cmd 自动同步
第一次 TTS 很慢（10~60s）	正常现象：模型首次懒加载 + 预热，之后每句约 0.5s 出音