企业官网建设流程全解析

PiD 是一款可即插即用的像素扩散解码器（Pixel Diffusion Decoder），它直接替换 VAE/RAE 解码器，把 latent 表示在像素空间一次去噪生成超分图像。本文带你拆解 PiD 的核心网络源码：PixDiT 骨干上的ControlNet 式 LQ 门控注入——也就是那个让 PixDiT 从"文生图模型"变身"4 倍超分解码器"的关键模块，涉及 PidNet、LQProjection2D 两个文件。

一、PiD 在做什么：解码 + 上采样合一

传统扩散模型链路是：文本 → latent diffusion → VAE 解码回像素，再靠独立超分模型放大。PiD 把后两步合并：解码器本身就在高分辨率像素空间去噪，一次前向直接输出 2048px 甚至 4K 的超分图像，比 ESRGAN 等基线快 5.9 倍（见上图 Quantitative Results 部分）。

整个项目代码布局可参考 docs/repository_layout.md，网络层集中在 pid/_src/networks/ 目录。

二、PixDiT 骨干：双通路架构

PiD 的底座是 PixDiT_T2I，它由两条通路组成：

关键超参（默认配置 PID_SR4X）：hidden_size=1536、patch_size=16、patch_depth=14、pixel_depth=2、sr_scale=4。

一句话理解：patch 层负责"画骨架"，pixel 层负责"磨细节"，这正是它适合做高分辨率生成的原因。

三、LQ 投影模块：无损对齐到 patch 网格

注入的原料来自 LQProjection2D：把低质量条件（低清图像或其 VAE latent）投影成与 patch 网格逐 token 对齐的特征图。它的亮点是"无损空间对齐"，完全避免双线性插值糊掉信息：

• 图像分支：PixelUnshuffle(patch_size/sr_scale)把 4×4 像素折叠进通道，例如[B,3,256,256] → [B,48,64,64]，再经 Conv + 4 个 ResBlock 提特征；
• Latent 分支：PiD 实际走这条（lq_in_channels=0, lq_latent_channels=16）。当 latent 分辨率低于 patch 网格时用 nearest 上采样，高于时折叠进通道；Flux2 的 patchified latent 还支持unpatchify_factor=2还原回[B,32,H/8,W/8]；
• 输出头：num_outputs个独立 Linear 头，每个 transformer 块配一份注入特征，可选再挂一个 PiT 专用头。

四、Sigma-aware 门控注入公式拆解 🔑

门控逻辑在 lq_projection_2d.py#L48-L116，两种变体：

x_out = x + sigmoid( Linear([x, lq]) − exp(log_alpha)·σ ) · lq

三个设计点值得新手注意：

1. 内容感知：门值由主特征x和 LQ 特征lq拼接后联合计算，网络自己决定"这里该不该信条件图"；
2. 噪声感知（sigma-aware）：可学习参数log_alpha（初始 log 5）把扩散噪声强度σ折进门控偏置——σ≈1（噪声大）时门≈0.05，几乎不注入；σ≈0（接近干净图）时门≈0.88，充分注入。这让超分强度随去噪进程自动渐变；
3. v1 与 v1.5 的区别：v1 用 per-token-per-dim（门值对每个通道独立，表达力强）；v1.5 改用 per-token 标量门（参数更省），见 SigmaAwarePerTokenGate。

五、注入流程：forward 里的 ControlNet 式循环

PidNet 继承 PixDiT_T2I，只新增 LQ 投影与门控，主干前向完全复用。注入发生在 _run_patch_blocks：

for i in patch_blocks: if is_gate_active(i): # 由 lq_interval 控制注入频率 s_main = gate(s_main, lq_feat[i], sigma) s_main, y_emb = patch_blocksi # 原 PixDiT 块

这就是 ControlNet 范式的精髓：旁支卷积提特征 → 主干块前逐块残差注入，而非像传统超分网络那样改主干。带来两个工程红利：

• 零初始化安全启动（zero_init_lq=True）：所有输出头初始为 0，初始输出与预训练 PixDiT 完全一致，训练只学"注入多少"，不破坏原生成能力；
• 冻结主干只训旁支：v1.5 开启train_lq_proj_only=True，PidNet.init里冻结全部主干参数，仅训练 LQ 投影，显存与数据成本大降。

六、PiD v1.5 架构升级清单

v1.5 相对 v1 的改动集中在 net.py#L62-L83，值得逐一了解：

其中lq_interval=2表示每 2 个块注入一次，num_lq_outputs会按patch_depth向上取整（pid_net.py#L147）。

七、快速定位关键源码 📌

想动手改模型，从这几个入口开始：

• 主网络（注入循环、CP 并行切分）：pid/_src/networks/pid_net.py
• LQ 投影与门控：pid/_src/networks/lq_projection_2d.py
• PixDiT 骨干（MMDiT 块 / PiT 块）：pid/_src/networks/pixeldit_official.py
• 网络默认配置（v1 / v1.5 / Flux2 三套）：pid/_src/configs/common/defaults/net.py
• 训练与推理入口说明：docs/repository_layout.md、README.md

总结

PiD 的聪明之处不在"更大的网络"，而在注入方式：用 ControlNet 式旁支 + sigma-aware 门控，把一个现成的像素扩散生成模型（PixDiT）几乎无侵入地改造成 4 倍超分解码器——零初始化保证预训练能力不退化，门控保证条件强度随噪声级别自适应，v1.5 的train_lq_proj_only更进一步把改造成本压缩到只训练一个轻量卷积旁支。如果你也在做"生成模型 + 条件注入"类改造，这套 pid/_src/networks/ 下的实现是很值得借鉴的范式。