企业官网建设流程全解析

如何从零训练自己的Pixal3D？三阶段渐进分辨率微调完整教程（含finetune_ckpt链配置）

【免费下载链接】Pixal3D[SIGGRAPH 2026] Pixal3D: Pixel-Aligned 3D Generation from Images项目地址: https://gitcode.com/gh_mirrors/pi/Pixal3D

Pixal3D 是 SIGGRAPH 2026 的单图生成 3D 模型项目，官方开源了完整训练代码与数据工具包。本文带你从零开始，用三阶段渐进分辨率微调（32→64、256→512→1024）训出属于你自己的 Pixal3D 生成器，并重点讲解最容易踩坑的finetune_ckpt检查点链配置。

Pixal3D 三阶段训练流程总览

Pixal3D 不是"一把梭"训练一个大模型，而是像搭积木一样逐级提升分辨率，每个阶段都用像素对齐投影条件（pixel-aligned projection）+视角对齐潜变量（默认 2 个视角）：

💡 核心规则：每一步升分辨率前，都要把上一阶段的 checkpoint 路径填进新配置的finetune_ckpt字段。这条"链"断掉，高分辨率训练就会退化成冷启动，效果大打折扣。

所有配置都在 configs/gen/ 目录，例如 ss_flow_img_dit_1_3B_32_bf16_proj_finetune.json。

训练环境与数据集准备：先跑通 data_toolkit

1️⃣ 克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/pi/Pixal3D cd Pixal3D pip install -r requirements.txt # 按你的 CUDA 架构编译 natten NATTEN_CUDA_ARCH="9.0" NATTEN_N_WORKERS=8 pip install natten==0.21.0 --no-build-isolation

📌 建议先按 TRELLIS.2 的指南搭好基础环境，再安装 Pixal3D 的额外依赖。

2️⃣ 准备视角对齐的 O-Voxel 数据

详细文档见 data_toolkit/README.md，核心步骤 4 步走：

# 初始化环境 . ./data_toolkit/setup.sh # 元数据 → 下载资产 → 导出 Mesh/PBR → 渲染条件图 python data_toolkit/build_metadata.py ObjaverseXL --source sketchfab --root datasets/ObjaverseXL_sketchfab python data_toolkit/download.py ObjaverseXL --root datasets/ObjaverseXL_sketchfab python data_toolkit/dump_mesh.py ObjaverseXL --root datasets/ObjaverseXL_sketchfab python data_toolkit/dump_pbr.py ObjaverseXL --root datasets/ObjaverseXL_sketchfab # 渲染多视角条件图（默认 2 个视角） python data_toolkit/render_cond.py ObjaverseXL --root datasets/ObjaverseXL_sketchfab

下面这张就是渲染出的室内场景条件图，训练时模型会学习"看图对齐 3D"：

3️⃣ 编码视角对齐潜变量

# 形状 / PBR 潜变量（256、512、1024 各跑一轮） python data_toolkit/encode_shape_latent_view.py --root datasets/ObjaverseXL_sketchfab --resolution 512 --view_indices 0-1 python data_toolkit/encode_pbr_latent_view.py --root datasets/ObjaverseXL_sketchfab --resolution 512 --view_indices 0-1 python data_toolkit/build_metadata.py ObjaverseXL --root datasets/ObjaverseXL_sketchfab # 稀疏结构潜变量（阶段 1 专用） python data_toolkit/encode_ss_latent_view.py --root datasets/ObjaverseXL_sketchfab \ --shape_latent_name shape_enc_next_dc_f16c32_fp16_1024_view --resolution 64 --view_indices 0-1

训练入口解析：train.py 的三大关键参数

统一入口是 train.py，每次训练只认 3 个参数：

python train.py \ --config <CONFIG_JSON> \ --output_dir <OUTPUT_DIR> \ --data_dir '<DATA_DIR_JSON>'

--data_dir各阶段必填 key 对照：

✅ 小技巧：第一次运行加--tryrun做干跑，可以快速验证数据路径和模型能否构建成功，不浪费 GPU 时间。

finetune_ckpt 链配置详解：高分辨率微调的关键

打开任意"升档"配置，比如 ss_flow_img_dit_1_3B_32_bf16_proj_finetune_ft64.json，在trainer.args中会看到这样的字段：

"finetune_ckpt": { "denoiser": "<path_to_ss_flow_32_checkpoint>" }

这就是"链"的接点，使用规则如下：

1. 每个阶段的第一个分辨率（32 / 256 / 256）的配置里没有finetune_ckpt，属于冷启动；
2. 升档配置必须替换占位符：把<path_to_xxx_checkpoint>改成上一步--output_dir/ckpts/下的实际 checkpoint 文件路径；
3. 完整的 8 步训练链对应 8 个配置文件，5 个"升档"文件都内置了finetune_ckpt占位符：

⚠️ 注意区分两个概念：finetune_ckpt是跨分辨率热启动（只加载权重、不带优化器状态）；而同步中断后想断点续训，靠的是--load_dir+--ckpt latest（默认值），它会自动找ckpts/misc_*.pt里 step 最大的存档。

阶段 1：训练稀疏结构模型（32→64）

以 ObjaverseXL 为例，输入是一张简单的单图资产，模型要学会先"打草稿"：

# 分辨率 32（冷启动） python train.py \ --config configs/gen/ss_flow_img_dit_1_3B_32_bf16_proj_finetune.json \ --output_dir results/ss_32 \ --data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "ss_latent": "datasets/ObjaverseXL_sketchfab/ss_latents/ss_enc_conv3d_16l8_fp16_64_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}' # 分辨率 64（先把 32 的 ckpt 填进 ft64 配置的 finetune_ckpt，再运行） python train.py \ --config configs/gen/ss_flow_img_dit_1_3B_32_bf16_proj_finetune_ft64.json \ --output_dir results/ss_ft64 \ --data_dir '{同上}'

阶段 2：训练形状模型（256→512→1024）

# 256（冷启动，注意 shape_latent 指向 256 目录） python train.py \ --config configs/gen/slat_flow_img2shape_dit_1_3B_256_bf16_proj_finetune.json \ --output_dir results/shape_256 \ --data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_256_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}' # 512（finetune_ckpt ← results/shape_256 的 ckpt） python train.py \ --config configs/gen/slat_flow_img2shape_dit_1_3B_256_bf16_proj_finetune_ft512.json \ --output_dir results/shape_ft512 \ --data_dir '{... shape_latent 换成 _512_view 目录}' # 1024（finetune_ckpt ← results/shape_ft512 的 ckpt） python train.py \ --config configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16_proj_finetune_ft1024.json \ --output_dir results/shape_ft1024 \ --data_dir '{... shape_latent 换成 _1024_view 目录}'

📝 512 与 1024 档内置了 NAF 特征上采样：以输入图为指导，把 DINOv3 的 32×32 特征升到更高分辨率（配置注释中proj_in_channels=2048 = concat(lr 1024, hr 1024)），这正是高分辨率几何保真的关键。

阶段 3：训练纹理模型（256→512→1024）

纹理阶段的--data_dir比形状阶段多一个pbr_latentkey：

# 256（冷启动） python train.py \ --config configs/gen/slat_flow_imgshape2tex_dit_1_3B_256_bf16_proj_finetune.json \ --output_dir results/tex_256 \ --data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": ".../shape_enc_next_dc_f16c32_fp16_256_view", "pbr_latent": ".../tex_enc_next_dc_f16c32_fp16_256_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}' # 512（finetune_ckpt ← results/tex_256 的 ckpt） python train.py \ --config configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16_proj_finetune.json \ --output_dir results/tex_512 \ --data_dir '{... pbr_latent 换成 _512_view，shape_latent 同步 512}' # 1024（finetune_ckpt ← results/tex_512 的 ckpt） python train.py \ --config configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16_proj_finetune_ft1024.json \ --output_dir results/tex_ft1024 \ --data_dir '{... pbr_latent 与 shape_latent 均换成 _1024_view}'

进阶：多卡、断点续训与常用参数

• 多卡/多机：--num_gpus 8 --num_nodes 1（默认自动用满本机 GPU），分布式训练走 pixal3d/utils/dist_utils.py；
• 断点续训：重新运行同一命令即可，默认--ckpt latest会恢复最近存档；指定步数用--ckpt <step>；
• 训练监控：加--use_wandb开启 W&B 日志，配置会自动上传为 artifact；
• 失败自动重试：默认--auto_retry 3，显存波动导致的偶发崩溃不用人工干预。

小结

回顾一下训练自己 Pixal3D 的完整路径：

1. 用 data_toolkit/ 准备视角对齐的 O-Voxel 数据与三类潜变量；
2. 按稀疏结构 → 形状 → 纹理的顺序跑 3 个阶段、共 8 个分辨率档位；
3. 每次升档前，把上一档 checkpoint 填进新配置的finetune_ckpt，保持链条完整；
4. 用--tryrun先干跑验证，再上全量训练。

坚持这条渐进式路线，你就能在自己的数据集上复刻甚至超越官方的单图 3D 生成效果 🚀。

【免费下载链接】Pixal3D[SIGGRAPH 2026] Pixal3D: Pixel-Aligned 3D Generation from Images项目地址: https://gitcode.com/gh_mirrors/pi/Pixal3D