Diffusers 模型权重准备
本 Skill 提供两个核心能力：
-
从 HuggingFace 或 ModelScope 下载模型权重
-
基于 Diffusers Pipeline 的 config 文件生成假权重（随机初始化），用于业务验证
快速开始
- 下载模型权重
从 HuggingFace 下载：
pip install -U huggingface_hub
基础用法
hf download Wan-AI/Wan2.2-I2V-A14B-Diffusers
使用代理（国内访问）
export HF_ENDPOINT=https://hf-mirror.com hf download Wan-AI/Wan2.2-I2V-A14B-Diffusers
通过脚本下载（支持 dry-run 测试）
python scripts/download_weights.py hf Wan-AI/Wan2.2-I2V-A14B-Diffusers --proxy https://hf-mirror.com python scripts/download_weights.py hf Wan-AI/Wan2.2-I2V-A14B-Diffusers --dry-run
从 ModelScope 下载：
pip install modelscope
基础用法
modelscope download --model Wan-AI/Wan2.2-T2V-A14B
通过脚本下载
python scripts/download_weights.py modelscope Wan-AI/Wan2.2-T2V-A14B -o ./models python scripts/download_weights.py modelscope Wan-AI/Wan2.2-T2V-A14B --dry-run
- 生成假权重
自动从 HuggingFace 下载元数据（config.json、model_index.json、tokenizer 等，不下载权重文件），然后基于 config 随机初始化每个子模型并保存，生成与原始模型文件结构完全一致的假权重。
从 HuggingFace 直接生成：
生成 Z-Image-Turbo 假权重
python scripts/generate_fake_weights.py from-hub Tongyi-MAI/Z-Image-Turbo -o ./fake_z_image --dtype bfloat16
生成 Qwen-Image-2512 假权重（国内使用镜像）
python scripts/generate_fake_weights.py from-hub Qwen/Qwen-Image-2512 -o ./fake_qwen --proxy https://hf-mirror.com
从已有的本地元数据目录生成：
python scripts/generate_fake_weights.py from-local ./model_metadata_dir -o ./fake_weights --dtype bfloat16
验证假权重可正常加载：
import torch import diffusers
pipe = diffusers.DiffusionPipeline.from_pretrained( "./fake_z_image", torch_dtype=torch.bfloat16, ) print(f"Pipeline: {type(pipe).name}") for name, comp in pipe.components.items(): if hasattr(comp, "parameters"): pc = sum(p.numel() for p in comp.parameters()) print(f" {name}: {type(comp).name} ({pc:,} params)")
环境要求
组件 安装命令 说明
huggingface_hub pip install -U huggingface_hub
HuggingFace 下载 & 假权重元数据下载
modelscope pip install modelscope
ModelScope 下载
torch pip install torch
假权重生成
diffusers pip install diffusers
Pipeline 模型实例化
transformers pip install transformers
text_encoder 实例化
假权重生成原理
生成流程：
-
从 HuggingFace 通过 snapshot_download 下载元数据文件（排除 .safetensors 、.bin ）
-
读取 model_index.json ，解析 Pipeline 的每个组件（scheduler、text_encoder、tokenizer、transformer、vae）
-
对于每个模型组件，使用 from_config() 从 config.json 实例化模型（随机权重）
-
通过 save_pretrained() 保存，自动生成正确格式的 safetensors 文件和 index.json
-
tokenizer 和 scheduler 直接复制配置文件
生成的目录结构与原始模型完全一致，例如 Z-Image-Turbo：
fake_z_image_turbo/ ├── model_index.json ├── scheduler/ │ └── scheduler_config.json ├── text_encoder/ │ ├── config.json │ ├── generation_config.json │ ├── model.safetensors │ └── model.safetensors.index.json ├── tokenizer/ │ ├── merges.txt │ ├── tokenizer_config.json │ ├── tokenizer.json │ └── vocab.json ├── transformer/ │ ├── config.json │ ├── diffusion_pytorch_model-00001-of-00002.safetensors │ ├── diffusion_pytorch_model-00002-of-00002.safetensors │ └── diffusion_pytorch_model.safetensors.index.json └── vae/ ├── config.json └── diffusion_pytorch_model.safetensors
脚本参考
download_weights.py
参数 必需 说明
source
是 下载源：hf 或 modelscope
model_id
是 模型 ID（如 Wan-AI/Wan2.2-I2V-A14B-Diffusers ）
-o, --output-dir
否 输出目录
--proxy
否 HuggingFace 代理 URL（仅 hf 源）
--dry-run
否 测试模式，不实际下载
generate_fake_weights.py
子命令 from-hub ：从 HuggingFace 下载元数据 + 生成假权重
参数 必需 说明
model_id
是 HuggingFace 模型 ID
-o, --output-dir
是 输出目录
--proxy
否 HuggingFace 代理 URL
--dtype
否 数据类型：float32 、float16 、bfloat16 （默认：bfloat16 ）
子命令 from-local ：从本地元数据目录生成假权重
参数 必需 说明
metadata_dir
是 本地元数据目录（需包含 model_index.json）
-o, --output-dir
是 输出目录
--dtype
否 数据类型（默认：bfloat16 ）
已验证模型
模型 Pipeline 类型 组件 验证状态
Qwen/Qwen-Image-2512 QwenImagePipeline vae(127M) + text_encoder(8.3B) + transformer(20.4B) ✅
Tongyi-MAI/Z-Image-Turbo ZImagePipeline vae(84M) + text_encoder(4.0B) + transformer(6.2B) ✅
注意事项
-
假权重为随机初始化，生成的图像无意义，仅用于验证代码流程
-
大模型（>10B 参数）生成假权重可能需要较多内存和时间
-
国内环境建议使用 --proxy https://hf-mirror.com 或设置 HF_ENDPOINT 环境变量
-
如遇 socks 代理冲突，先 unset all_proxy ALL_PROXY 再运行
参考资源
-
HuggingFace Hub 文档
-
ModelScope 文档
-
HuggingFace 镜像站