🏆 Qwen3-TTS Blackwell 部署指南

🚨 核心背景

1️⃣ ABI 符号冲突

Blackwell PyTorch (nv26) 移除旧 FP8 符号，torchaudio 启动崩溃

2️⃣ 版本死锁

Transformers 4.57.3 校验 huggingface-hub < 1.0，环境为 1.4+

3️⃣ 架构限制

GB10 统一内存架构，必须强制开启 fp16 发挥性能

📦 第一阶段：宿主机环境准备

1. 目录持久化

⚠️ 重要

模型约 6GB，必须存放在宿主机挂载目录，防止容器删除后数据丢失

mkdir -p /home/nvidia/ComfyUI/models/Qwen3-TTS/

2. Docker 启动配置

docker run -it --name qwen3_blackwell_prod \
  --gpus all --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
  -p 8188:8188 -v /home/nvidia/ComfyUI:/workspace/ComfyUI \
  nvcr.io/nvidia/pytorch:26.02-py3 /bin/bash

🎯 关键参数

--ipc=host: 解决 SHMEM 限制
--ulimit memlock=-1: 提升 Blackwell 响应
-v: 持久化工作目录

🛠️ 第二阶段：依赖注入

❌ 绝对禁忌

严禁执行 pip install -r requirements.txt，会覆盖 Blackwell 优化库

1. 系统级音频后端

apt-get update && apt-get install -y ffmpeg libsndfile1 sox libsox-dev

2. 最小化依赖安装

# 必须使用 --no-deps
pip install modelscope accelerate tqdm librosa scipy onnxruntime --no-deps
pip install transformers==4.57.3 --no-deps
pip install qwen-tts --no-deps

🧪 第三阶段：黑盒补丁

1. Transformers 校验补丁

# 注释第 57 行的 require_version_core
sed -i '57s/require_version_core/# require_version_core/' \
  /usr/local/lib/python3.12/dist-packages/transformers/dependency_versions_check.py

🔍 为什么必须

Transformers 写死了 huggingface-hub < 1.0，环境为 1.4+

2. Torchaudio Mocking

🎭 技术原理

创建全 Python"影子模块"欺骗 Import 机制，触发 Fallback

# 1. 移除冲突库
pip uninstall -y torchaudio

# 2. 注入伪装代码
python3 - <

📥 第四阶段：模型部署

1.7B-CustomVoice

✨ 特点

支持 9 种高质量预设
支持快速克隆
12Hz 采样率优化

下载脚本

python3 -c "from modelscope import snapshot_download; \
snapshot_download('Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice', \
local_dir='/workspace/ComfyUI/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-CustomVoice')"

python3 -c "from modelscope import snapshot_download; \
snapshot_download('Qwen/Qwen3-TTS-Tokenizer-12Hz', \
local_dir='/workspace/ComfyUI/models/Qwen3-TTS/Qwen3-TTS-Tokenizer-12Hz')"

🎯 第五阶段：性能调优

1. 镜像存档

验证通过后（import qwen_tts 不报错），立即存档：

docker commit comfy_qwen3_prod qwen3_tts_blackwell_success_final

2. ComfyUI 启动参数

cd /workspace/ComfyUI
python3 main.py \
  --listen 0.0.0.0 \
  --lowvram \
  --force-fp16 \
  --fp16-vae \
  --fp16-text-enc \
  --use-split-cross-attention \
  --cuda-malloc

⚡ 参数详解

--force-fp16: 激活 Blackwell 半精度加速引擎
--cuda-malloc: 减少显存碎片化
--lowvram: 优化显存使用

🎵 部署成果演示

📊 工作流元数据

模型 Qwen3-TTS-1.7B-CustomVoice

音色 Ryan (预设)

精度 BF16

种子 42

生成文本 Hello Blackwell World!

🎉 部署状态： ✅ 成功

✅ Patch 成功：Transformers 版本校验绕过
✅ Mock 成功：Torchaudio 影子模块正常
✅ 性能正常：Blackwell (GB10) 成功推理
✅ 音色正常：Ryan 预设工作良好

✅ 验证清单

浏览器访问：http://[Your-IP]:8188
节点确认：右键菜单是否出现 Qwen3-TTS 类别
推理测试：运行一个 3s 克隆工作流
性能观察：nvidia-smi，10 秒音频 ≈0.5s 生成

📌 关键记忆点

阶段	关键操作	原因
环境准备	`--ipc=host` + `--ulimit`	解决 SHMEM 限制
依赖注入	`--no-deps` + 手术式安装	避免覆盖优化库
补丁	注释校验 + Mock	绕过 ABI 冲突
性能	`--force-fp16`	激活 Tensor Core

🗓️ 后续待办

创建 ComfyUI 工作流模板
测试 9 种预设效果
验证克隆质量
记录生成时间基准