企业官网建设流程全解析

PiD（Pixel Diffusion Decoder）是一个来自 NeurIPS 2026 的高分辨率潜在解码项目，其完整训练流程分为三步：PixelDiT 微调→ PiD 教师训练 → PiD 学生蒸馏。本文是三部曲的第一篇，手把手带你走通 PixelDiT 从 2K 到 4K 分辨率微调的完整训练命令：环境搭建、数据准备、训练启动、调试与结果验证，一条命令一条命令地拆解。

🎯 为什么第一步是微调 PixelDiT？

PiD 的解码器建立在一个像素空间扩散骨干——PixelDiT之上。在训练 PiD 教师模型之前，需要先有一个足够强的像素生成骨干：官方会先对 PixelDiT 做从 2K 到 4K 的多分辨率微调，让它在高分辨率下保持 RoPE 位置编码的合理外推（rope_mode="ntk_aware"）和动态 shift 策略，后续教师与学生模型才能在此基础上稳定工作。

本系列的定位如下：

💡 所有命令都从仓库根目录执行，且需要PYTHONPATH=.。仓库克隆地址：git clone https://gitcode.com/gh_mirrors/pid18/PiD

📦 训练环境搭建：conda 一步到位

PiD 训练环境推荐使用 conda（方便安装 CUDA Toolkit），环境定义在 environment.yml（Python 3.12 + CUDA 12.8）：

conda env create -f environment.yml conda activate pid python -m pip install -e . --group full \ --extra-index-url https://download.pytorch.org/whl/cu128

如果你不想用 conda，也可以参考 docker/README.md 构建训练 Docker 镜像。完成后先跑一个环境自检脚本 verify_env.py：

PYTHONPATH=. python verify_env.py

看到[PASS] Environment OK即可开始训练。

🖼️ 准备 2K–4K 图像数据集

默认使用MultiAspect-4K-1M数据集（约 100 万个多宽高比、最高 4K 的图文对）。整体流程分三步：

1. 下载元数据并解压（在raw_data/下）：

mkdir -p raw_data && cd raw_data wget https://huggingface.co/Owen777/UltraFlux-v1/resolve/main/MultiAspect-4K-1M.tar.gz tar -xzf MultiAspect-4K-1M.tar.gz cd ..

2. 下载图像并转成 WebDataset 格式。先用--max-json-files 10只取 10 个文件做试跑，去掉该参数即下载全量：

python scripts/download_multiaspect_4k_1m.py --max-json-files 10 python scripts/sharding_wds.py --input-dir raw_data/MultiAspect-4K-1M-download \ --output-dir data/image_MultiAspect_4K_1M_webdataset

• 下载脚本：download_multiaspect_4k_1m.py
• WebDataset 分片脚本：sharding_wds.py

3. 加入自己的数据：按照raw_data/MultiAspect-4K-1M-download的目录结构摆放，用sharding_wds.py转换，然后在 data_source_local.py 注册数据源，并纳入 dataset_definition.py。数据的 tar 目录结构详见 docs/webdataset_CN.md。

🚀 核心命令：PixelDiT 微调 2K 到 4K 训练命令

先设置环境变量

输出目录、缓存目录和 WandB key 通过环境变量传入，建议用绝对路径：

mkdir -p imaginaire4/imaginaire4-output imaginaire4/imaginaire4-cache export IMAGINAIRE_OUTPUT_ROOT=$(realpath "./imaginaire4/imaginaire4-output") export IMAGINAIRE_CACHE_DIR=$(realpath "./imaginaire4/imaginaire4-cache") export WANDB_API_KEY=your_wandb_api_key

官方微调命令（两条，按需选择）

# 实验 A：仅 2K 分辨率微调（dataloader 只喂 2K 图像） PYTHONPATH=. torchrun --nproc_per_node=4 --master_port=12341 -m scripts.train \ --config=pid/_src/configs/pid_training/config.py \ -- experiment="pixeldit_text_to_image_finetune_res_2048" # 实验 B：2K 到 4K 多分辨率微调（dataloader 提供 2K~4K 混合分辨率） PYTHONPATH=. torchrun --nproc_per_node=4 --master_port=12341 -m scripts.train \ --config=pid/_src/configs/pid_training/config.py \ -- experiment="pixeldit_text_to_image_finetune_res_2048_to_3840"

两个实验都从官方已微调好的检查点checkpoints/PixelDiT_finetune_2kto4k/model_ema_bf16.pth继续训练，因此必须先用hf download nvidia/PiD拉取checkpoints/目录（见 README.md 的 Download Checkpoints 一节）。

训练命令逐段解读

这条命令其实由三部分组成，理解了结构后你就不会再记错命令：

⚠️ 最常见的报错是「override 必须以--开头」——检查--config=...和experiment=...之间是否漏了独立的那个--。它是本项目配置封装用来区分脚本参数与 Hydra 参数的分隔符，不能省略。配置体系细节可阅读 docs/hydra_CN.md。

2K→4K 实验的关键参数（都在实验配置里预设好了）

对照 finetune.py 可以看到 2K→4K 实验在 2K 实验基础上做了这些修改：

如果你想临时改参数，可以直接在命令里追加 Hydra override（优先级最高），例如：

PYTHONPATH=. torchrun --nproc_per_node=4 --master_port=12341 -m scripts.train \ --config=pid/_src/configs/pid_training/config.py \ -- \ experiment=pixeldit_text_to_image_finetune_res_2048_to_3840 \ trainer.max_iter=100000 optimizer.lr=2e-5

🐞 调试模式：先跑通，再上正式训练

实验名加上_debug后缀即可启用调试配置：只跑 25 个迭代、每 5~10 步出图、关闭 WandB 上报，非常适合验证环境、数据路径是否配置正确：

PYTHONPATH=. torchrun --nproc_per_node=4 --master_port=12341 -m scripts.train \ --config=pid/_src/configs/pid_training/config.py \ -- experiment="pixeldit_text_to_image_finetune_res_2048_to_3840_debug"

调试模式通过_build_debug_run()继承正式实验生成（见 finetune.py），所以先_debug后正式跑是官方推荐的顺序。

📂 训练产物输出在哪里

所有产物统一写入IMAGINAIRE_OUTPUT_ROOT/<project>/<group>/<job>，PixelDiT 微调的目录结构如下：

imaginaire4/imaginaire4-output/pid_training/pixeldit_finetune/pixeldit_text_to_image_finetune_res_2048 ├── checkpoints # 每 5000 步保存一次 DCP 分布式检查点 ├── EveryNDrawSample # 每 5000 步的定 prompt 出图对比 ├── config.yaml / job_env.yaml / launch_info.yaml ├── stdout.log └── wandb # 训练曲线

每 5000 步的出图 callback 会在example（小脸）与harder_cases（复杂文本）两组固定 prompt 上各存 128 张采样，方便肉眼追踪 2K→4K 细节与文字渲染的改善。检查点的保存、恢复与转换规则见 docs/checkpointing_CN.md。

🧪 验证微调效果：对 checkpoint 采样出图

训练到一定迭代后，用 pixeldit.py 内部推理入口评估（单卡示例，--load_ema_to_reg加载 EMA 权重）：

EXP=pixeldit_text_to_image_finetune_res_2048_to_3840 CKPT=/path/to/run/checkpoints/iter_XXXXXXXXX PYTHONPATH=. python -m pid._src.inference_internal.pixeldit \ --experiment "$EXP" \ --checkpoint_path "$CKPT" \ --prompt "A majestic snow-capped mountain range at golden hour" \ --image_size 3840 \ --output_dir ./results/training_checkpoints/pixeldit \ --cfg_scale 2.75 --num_steps 50 \ --load_ema_to_reg

注意--experiment必须与训练时完全同名，检查点路径要指向iter_XXXXXXXXX目录本身（完整参数见 docs/inference.md）。PixelDiT 微调后的采样效果示例：

⚠️ 常见问题与省显存技巧

• OOM（显存不足）：2kto4k实验非常吃显存。两个调节旋钮：调小 dataloader 的 batch size（换data_train=pixeldit_MultiAspect_4K_1M_1bs_2048这类选项），或调大model_parallel.context_parallel_size（代价是等效全局 batch 变小）。
• 多节点训练：代码兼容 SLURM 多节点，示例脚本 multinode_slurm.sh 改好后sbatch scripts/multinode_slurm.sh提交。
• 数据集几乎全是 4K 图？这是正常现象。res_2048_to_3840实验假设数据源覆盖 2K~4K，若只有 MultiAspect-4K-1M，dataloader 喂给模型的将主要是 4K 分辨率图像。
• 数据加载报错：确认 WebDataset 的image/与caption/两个目录下同名 tar 的 key 对齐，机制详见 docs/webdataset_CN.md。

📚 小结与系列预告

本文走完了 PiD 训练三部曲的第一步：PixelDiT 微调。核心就三条命令——_debug实验验证环境 → 2K 实验或 2K→4K 实验正式训练 → 用内部推理入口对检查点采样验证。掌握后，下一篇《PiD 教师训练：为 FLUX / FLUX.2 / Qwen-Image 定制像素解码器》将带你完成 callback 资产准备与教师模型训练；第三篇则讲解学生蒸馏，把解码压缩到 4 步出图。

系列关键文档：

• 训练总指南：docs/training.md
• 训练入口脚本：scripts/train.py
• 配置体系中文教程：docs/hydra_CN.md
• 仓库结构总览：docs/repository_layout.md