IDM-VTON 是 KAIST 与 OMNIOUS.AI 联合推出的高保真虚拟试衣扩散模型，支持单图 / 多图试衣、细节保留与真实场景适配，适合 AI 试衣、电商可视化等场景。完整本地部署(Linux/Windows)+ 常见问题排查，确保一次跑通。
一、环境准备(必看)
1. 硬件要求
GPU：NVIDIA 显卡，显存≥16GB(12GB 可跑但慢且易 OOM，推荐 24GB+)
系统：Linux(Ubuntu 20.04+/CentOS 7+)/ Windows 10/11(WSL2 或原生)
内存：≥32GB(避免数据加载卡顿)
硬盘：≥50GB(模型 + 依赖 + 缓存)
2. 软件依赖
Python：3.9–3.11(推荐 3.10.兼容性最佳)
CUDA：11.7/11.8/12.1(匹配 PyTorch 版本，避免版本冲突)
工具：Git、Miniconda/Anaconda(环境管理)、pip(包管理)
二、分步安装教程
步骤 1：克隆项目代码
打开终端 / CMD，执行 Git 克隆(国内可替换为 Gitee 镜像)：
bash
运行
# 官方仓库
git clone https://github.com/yisol/IDM-VTON.git
cd IDM-VTON
# 国内镜像(加速)
# git clone https://gitee.com/mirrors/IDM-VTON.git
# cd IDM-VTON
星宇智算官网支持免费部署立马安装！点击下方立即试用!
步骤 2：创建并激活虚拟环境
用 Conda 隔离环境，避免全局包冲突：
bash
运行
# 创建环境(指定Python 3.10)
conda create -n idm-vton python=3.10 -y
# 激活环境
conda activate idm-vton
步骤 3：安装核心依赖
3.1 安装 PyTorch(必选，匹配 CUDA)
bash
运行
# CUDA 11.8(推荐，兼容性最强)
pip3 install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 –index-url https://download.pytorch.org/whl/cu118
# CUDA 12.1
# pip3 install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 –index-url https://download.pytorch.org/whl/cu121
# 验证安装(输出True则成功)
python -c “import torch; print(torch.cuda.is_available())”
3.2 安装项目依赖
bash
运行
# 安装基础依赖
pip install -r requirements.txt
# 补充缺失依赖(部分环境需手动安装)
pip install accelerate==0.25.0 diffusers==0.25.0 transformers==4.36.2 einops==0.7.0 opencv-python gradio==4.24.0 pycocotools basicsr
步骤 4：下载预训练模型(核心)
模型分为专属权重(ckpt 目录)和基础扩散模型(自动下载)，手动下载专属权重避免启动失败：
4.1 模型下载地址
官方 Hugging Face：https://huggingface.co/yisol/IDM-VTON/tree/main
国内镜像(加速)：https://gitcode.com/hf_mirrors/ai-gitcode/IDM-VTON
4.2 目录结构(必须严格对应)
plaintext
IDM-VTON/
└── ckpt/
├── densepose/
│ └── model_final_162be9.pkl
├── humanparsing/
│ ├── parsing_atr.onnx
│ └── parsing_lip.onnx
└── openpose/
└── ckpts/
└── body_pose_model.pth
操作：下载上述文件，按目录放入ckpt对应文件夹(无文件夹则手动创建)
4.3 基础模型自动下载
首次启动app.py时，会自动从 Hugging Face 下载 SD 基础模型(约 28GB)，国内用户可设置代理或手动下载后放入~/.cache/huggingface/hub目录。
步骤 5：启动 Gradio Demo(可视化界面)
bash
运行
# 进入demo目录
cd gradio_demo
# 启动服务
python app.py
启动成功后，终端输出http://127.0.0.1:7860.浏览器打开即可使用
操作：上传人物图 + 服装图，点击生成，等待 10–30 秒(显存越大越快)
三、常见问题 FAQ(高频排查)
Q1：启动报错CUDA out of memory(显存不足)
解决：
降低 batch size：修改app.py中batch_size=1(默认 1.若仍报错则检查其他进程占用 GPU)
开启混合精度：在app.py中添加torch.cuda.amp.autocast()
关闭其他 GPU 程序(如 Chrome、游戏)，释放显存
升级显卡(16GB 以下不推荐本地部署，建议用云 GPU)
Q2：模型下载失败 / 速度慢
解决：
国内用户设置 Hugging Face 镜像：
bash
运行
export HF_ENDPOINT=https://hf-mirror.com
手动下载模型后，修改app.py中模型路径为本地路径
检查网络代理，确保能访问 Hugging Face
Q3：报错ModuleNotFoundError: No module named ‘xxx’
解决：
确认激活idm-vton环境(conda activate idm-vton)
重新安装缺失包：pip install xxx(如pip install pycocotools)
升级 pip：pip install –upgrade pip
Q4：生成结果模糊 / 服装错位
解决：
输入图质量：人物图需正面、无遮挡、分辨率≥512×512;服装图需正面、无褶皱、纯色背景
调整参数：在 Gradio 界面提高num_inference_steps(默认 20.调至 30–50)
更换模型权重：下载最新版 ckpt 文件，替换旧文件
检查人体解析 / 姿态估计模型是否正确放入ckpt目录
Q5：Windows 系统启动报错DLL load failed
解决：
安装 Visual C++ Redistributable(2015–2022)：https://learn.microsoft.com/zh-cn/cpp/windows/latest-supported-vc-redist
用 WSL2 部署(推荐)，避免 Windows 原生环境兼容性问题
重新安装 PyTorch，确保 CUDA 版本与显卡驱动匹配
Q6：启动后无法访问http://127.0.0.1:7860
解决：
检查防火墙：允许 Python / 终端访问网络
更换端口：修改app.py中demo.launch(server_port=7861)
检查是否有其他程序占用 7860 端口(netstat -ano | findstr 7860)
Q7：Linux 系统报错Permission denied
解决：
给项目目录赋权：chmod -R 755 IDM-VTON
避免用 root 用户运行(推荐普通用户 + conda 环境)
检查ckpt目录下模型文件权限，确保可读
Q8：如何批量生成试衣图(非 Gradio 界面)
解决：
参考项目scripts/inference.py，编写批量处理脚本
传入人物图列表、服装图列表，循环调用模型生成
保存结果到指定目录，支持多线程加速(显存充足时)
四、进阶优化(可选)
显存优化：使用bitsandbytes开启 4/8 位量化，减少显存占用(适合 12GB 显存)
bash
运行
pip install bitsandbytes==0.39.0
速度优化：安装xformers加速扩散模型推理
bash
运行
pip install xformers==0.0.23.post1
部署优化：用 FastAPI+Uvicorn 封装 API，支持远程调用
效果优化：微调模型(需数据集 + 算力)，适配特定服装类型(如汉服、西装)
IDM-VTON 部署核心是环境匹配 + 模型路径正确，16GB + 显存 + CUDA 11.8 是最佳组合。遇到问题优先排查显存、依赖、模型路径三大核心点。若本地硬件不足，可租用云 GPU 服务器(如星宇智算)，快速部署并批量生成试衣图，满足电商、AI 创作等场景需求。
