VAE/TAE 解码段：分片等价与精确切分

判断“能不能切、切哪个轴、怎么切才逐位精确、切了值不值”。核心纪律只有两条：

1. 先证独立性，再谈切分——切法由“网络里有哪些跨轴耦合算子”唯一决定，不由“我们想切哪根轴”决定；
2. 精确性不是口号，是四道闸的实测结论——CPU 真值对拍 → 端到端产物 md5 → 帧级健康指标 → 交换预算核算。

0. 范围与边界

范围（本技能拥有）

• VAE / TAE 解码（含任意 decoder 形态）：能否沿某个轴切到多张卡、切哪个轴、怎么切才逐位精确、切了值不值；
• VAE encode：范围已含，当前无内容（待补）——编码段有任务时，按本技能同一套判据（独立性审计 → 选轴 → 状态 / halo → 四道闸）补进本技能，不要新开技能、也不要在别处复制这套判据；
• 计算与通信同技能：解码段的计算侧动作（减工作量 / 换实现 / 降精度）与其跨卡搬运（halo 交换、状态交换、all-gather）在本技能内闭环，不再拆成两个技能。

本技能拥有的 VAE 特有判据

潜帧边界切分、状态携带（state = 记忆块输入处末帧激活）、halo 宽度与 MINLEN 这类条件等价、交换预算核算、以及本对象的设备缺陷史。这些判据在别处没有，也不应复制到别处。

与既有技能的分工（只引用，不复制）

维度	归谁	本技能怎么做
计算动作的手段（pattern/compile 融合、Copy 消减、算子本体开发与调优）	pattern-dev / operator-dev（能力供给）	只引用，不复制写法；本技能只说“这段计算还能不能少、能不能换”
选档（开不开某特性、开哪一档）	DiT 侧参照 dit-perf-opt；特性真源 docs/zh/features/*	只给 VAE 侧特有约束（潜帧边界 / 条件等价 / 交换预算），不复制选档表
通信方法论（并行形态选择、通信掩盖、通信账、差异归因）	dit-parallel-opt	只引用；本技能只声明 VAE 侧特有判据（见上）。两者常同时出现在一个任务里，但判据完全不同：前者看吞吐/带宽，本技能看逐位相等
一致性判据（逐位 / 数值门 / 质量门三级）	accuracy-gate	本技能产出“切分是否等价”的证据（闸①~④），判据口径引用它，不在此重定义等价分层
数字能否入库（同窗 A/B、窗口口径、噪声地板）	perf-gate	收益宣称必须按它的口径出；本技能不定义测量纪律
交付搬运 / 装载预热（mp4 编码、worker→API 通路、落盘、权重加载、编译预热、镜像预热）	host-opt	解码段之外的 host 固定开销不属本技能；本技能只把“解码段占比”作为是否值得切的输入
通用排障流程（CPU 真值 → 指标量化 → 逐层打点找首个分叉 → 算子隔离 → 阈值扫描 → 陈旧内存判定）	accuracy-gate/references/silent-failure-localization.md	只留本对象的判定与规避（references/troubleshooting-cann-upsample.md），通用流程单向引用

第 0 步：先算账，值不值得切

切分只省“解码那段”，不会让 DiT 变快。先量清楚解码在 e2e 里的占比，再决定投入：

同环境实测（15 s / 768P / 4 步；绝对值按数字纪律出库，见 {run_results_dir}/archive/）	量级	占 e2e
视频 TAE 解码（8 卡各自完整解一遍）	亚秒级	个位数百分比
音频 VAE 解码（与视频并行）	亚秒级，明显小于视频解码	远小于视频解码（占比需现场量）
交付开销（mp4 编码 + worker→API 通路）	秒级	个位数百分比，明显高于视频解码（数倍）
DiT 去噪 4 步	十秒级	绝大部分（近九成）

⇒ 解码占比 <5 % 时（占比本身要现场量，别沿用本文的数字），优先去啃 DiT 与 host 固定开销（后者见 host-opt）；只有当解码占比高（大分辨率 / 长视频 / 解码器本身重）时，切分才划算。同时记住：解码若已到屋顶线（同环境视频 TAE 的 cube_utilization 已到接近饱和的量级、aicore_time == Task Duration），kernel 级没有余量，只能靠“减少工作量”——切分（摊到多卡）与降精度是仅有的两条路。

第 1 步：证明独立性（不可跳过，也别信直觉）

把网络里所有可能跨轴耦合的算子列全，逐个判定“它是否把不同切片绑在一起”。判据只有一条：输出元素是否依赖切片边界外的输入。

for op in network.ops:                      # 逐算子
    if op couples(axis):  -> 该轴不可直接切（或需要 halo / 需要状态携带）
    else:                 -> 该轴可自由切

两个真实对照（同一份 latent、同一台机器实测）：

网络	跨轴耦合算子	帧轴切分结论
逐帧 2-D 预览网（Kijai tae-2d，2.45 M 参数）	无：Clamp、3×3 conv、Upsample、逐帧 quantile 归一化全部逐帧独立	精确、无需 halo；实测 12/12 请求产物 md5 与基线一致，video_tae 耗时降到约四分之一（读数见归档 {run_results_dir}/archive/）
时间维 taehv（官方 taehv-temporal，9.87 M 参数）	MemBlock(past)：past 是上一帧在该块输入处的激活，逐块递推	帧轴切分不可能精确（第 t 帧依赖整段前缀），除非每个 rank 重放前缀

否证要点（最容易走错的一步）：stock 实现里的 chunk_latents=5 / trim=3 / 末尾丢 12 是“边界伪影裁剪”，不是独立性证据。看到 chunk 化就以为“天然可切”是错的——必须回到“输出是否依赖切片外输入”这一条判据。同理，“8 个 rank 解出来的结果逐位相同（指纹一致）”只说明当前是冗余计算，不说明可切。

细节与判定表见 references/independence-proof.md（含如何把审计写成可复核的 proof 记录）。

第 2 步：按独立性选轴

所有跨轴算子都不跨 T 轴  -> 帧轴（或 batch 轴）等分；无需 halo
存在 1 帧深度的因果递推  -> 帧轴不可分；改用「状态携带切分」（见第 3 步）
跨轴算子只跨 H/W（空间） -> 空间分块 + halo（halo ≥ 该层感受野），精确
同时跨 T 与 H/W          -> 只能做 (T, H, W) 对齐的块状划分，或退回单卡

• 空间分块：逐帧卷积网（含 3×3 conv 与最近邻上采样）沿 H/W 切，halo 取该点感受野即可精确。注意交换代价（见第 5 步）：按输出张量形状手算字节数（T×H×W×C×dtype），视频输出单卡 fp32 就达数 GB 量级（形状与读数见归档 {run_results_dir}/archive/），直接 all-gather 会把省下的时间全吃掉。
• 帧轴：优先选它——通信量小、halo 无需计算、实现最简单；前提是第 1 步证明通过。

第 3 步：递归网络的正确切法 = 潜帧边界切分 + 携带每块末帧状态

这是实测中最有复用价值的一条。若网络里有“上一帧反馈”的记忆块（MemBlock / past / state 之类）：

1. 非递归层逐帧独立：conv / upsample / 时间上采样（TGrow）都不跨帧 ⇒ 只有记忆块需要状态；
2. 状态定义：state[i] = 上一段末帧在 MemBlock i 输入处的激活（不是输出！）。首段用 zeros pad 复现整段语义（等价于 F.pad(view, ..., 1, 0)[:, :tt]）；
3. 切分点必须落在潜帧边界：本案例 time_upscale=4，潜帧 j ↔ 输出帧 4j，因此每个潜帧边界在所有层都是帧边界（每级时间上采样都是整数倍）。这条不成立时，必须按“最粗那一级”的边界对齐；
4. 段的顺序执行是必须的（第 k 段依赖第 k−1 段末帧状态）——所以它省的是显存与设备缺陷，不是并行度；要并行就得放弃精确性。

可直接抄的骨架：scripts/sliced_state_decode.py（apply_sliced(model, x, patch_size, slices, state=None)）。同环境实测（同一 latent、同一权重）：

环境	整段	2 段	4 段
CPU（等价性真值）	基准	bitwise 等价，max|d| = 0	bitwise 等价，max|d| = 0
NPU 时间/峰值显存	基准	耗时降到约四成、峰值显存约减半	耗时与 2 段基本持平、显存再降一档
NPU 尾段正确性	自某个绝对帧号起塌陷（首坏帧号属会话读数，见归档）	塌陷消失（与 CPU 逐桶一致）	同样干净

语义与推导细节见 references/sliced-state-decode.md。

第 4 步：判定必须与 rank 无关（否则死锁）

进入“要通信”的路径（状态交换、all-gather）的条件只能由 env + shape 推导，绝不能依赖 rank：

# 对：所有 rank 得到同一结论，要么全进集体通信，要么全不进
pieces = shard_pieces_from_env(env)          # 全 rank 一致
ok = pieces >= 2 and world >= 2 and shape_is_divisible(shape)
if ok: ...collective...

反例（实测中踩过）：rank < pieces 的选举式参与，只在“输出 shape 可由算数独立推出”时安全；一旦接收方需要知道别的 rank 的输出形状来分配缓冲，就必须全员参与。

第 5 步：交换预算必须先算（先算再实现）

交换量 = 输出张量字节数 × (pieces-1)/pieces × (1 - 可压缩比)
可接受 ⇔ 交换耗时 < 切分省下的计算时间

同环境判据：按输出张量形状与 dtype 手算（T×H×W×C×4），fp32 视频输出单卡就是数 GB 量级（形状与读数见归档），all-gather 不可接受；改 uint8（解码输出已 clamp 到 [0,1]）降到其约四分之一，或不交换——按 tile 直接写进编码器/落盘。先算这笔账，再决定轴；否则“切完更快”会在通信处翻车。算式细则与逐方案对照见 references/verification-and-budget.md §1。

第 6 步：切分同时是“规避设备缺陷”的手段

切分不只提供并行度与显存收益，也是绕过设备算子缺陷的开关：本对象遇到的是“最近邻上采样在单次调用 batch 过大时少写输出尾部”（读到陈旧显存 ⇒ 成品从某个绝对帧号起塌陷，全程无报错、形状与帧数都正确）。

• 缺陷要自己判定，不能由“切完就好了”反推——否则无法区分“切分治愈了缺陷”与“缺陷本来就不出现”。本对象的判定实验（算子隔离 → 等价写法交叉验 → 规模阈值扫描 → 陈旧内存判定）与判读规则见 references/troubleshooting-cann-upsample.md §2，此处不重复；
• 规避手段：把整段递推切成多段，让该算子单次调用 batch 落到干净区（即第 3 步的状态携带切分）。不要用 repeat_interleave 复制替代空间上采样——数值等价，但额外分配整张输出张量（见下方陷阱清单）；
• 复核与回退：换 CANN / 驱动 / 形状后必须重做判定实验；确认缺陷已修时，“分段”只剩省显存一个理由，需按回退条件重新评估是否保留（references/troubleshooting-cann-upsample.md §4）。

已知陷阱清单（都是静默失败，必须逐条自查）

陷阱	现象	正确做法
all_gather_into_tensor 传 torch.stack(list)	集合通信写到栈副本上，原列表一片未初始化 ⇒ 全错但无报错	先 torch.empty((world, *shape)) 真张量，再 gather，再切片拼接
repeat_interleave 逐轴复制当 upsample 替换	数值等价但多分配整张输出，显存紧张时 OOM	省显存选“切片”，不选“复制”
rank < pieces 选举式参与	部分 rank 不进集体通信 ⇒ 死锁或半张量	见第 4 步：判定与 rank 无关
按“chunk 化”推断可切	相关性/纹理由此而错，静默	回到“输出是否依赖切片外输入”
只看产物 md5 就宣布无损	md5 只证明“优化没改变本链产物”，不证明解码器忠实（基线自己也可能用了劣质解码器）	另做与真值解码器的逐帧对照（实测：官方 TAE 对 stock VAE 的逐帧误差为个位数 /255 量级、相关性接近 1；2-D 预览网误差大一个数量级以上、相关性几乎为 0，且含数十段冻结帧；绝对值见归档）

有损/条件性分片：必须带“精确性前置条件”

分片在某些长度下才逐字节精确时，代码里必须同时给出前置条件、自动修复与回退：

• 同环境音频 VAE 分片：逐字节精确只在片长满足某个下限时成立——该下限由 halo 宽度 / 记忆块几何决定， 须按现场片长重扫（重算与判定方式见 references/verification-and-budget.md §3；具体常数不得沿用历史值）； 短片实测绝大多数样本不逐字节相等（相对偏差极小，读数见归档）。修复：按扫描出的下限设 MINLEN， 短片补零到该帧数后 ndiff = 0；
• 扩到 8 片反而不逐字节精确（同一实现、仅片数变化）⇒ 片数不是越多越好，片数必须由等价性判据决定，不能由“卡多”决定。

验证流程（四道闸，缺一不可）

闸	做法	合格判据
① CPU 等价性	整段 vs 2/4 段在 CPU 上逐元素对拍	max|d| = 0（bitwise）；不为 0 先怀疑状态搬运写错
② 端到端产物	同窗口 4 请求（1 冷 + 3 热），比 md5	4/4 md5 一致；片数/开关的开与关产物一致
③ 帧级健康	桶化高频能量、帧间差、近重复帧段	无“后半段塌陷/平坦段”：同环境坏片后半段各桶 hf 明显低于健康档（修复后回到健康档量级），坏帧 PNG 体积只有健康帧的几十分之一（≈全平）
④ 预算与代价	交换量、耗时、峰值显存	交换耗时 < 省下的计算时间；显存不升（同环境实测反而明显下降，约减半）

工具：scripts/shard_equivalence_check.py（①，CPU 对拍）、scripts/frame_health.py（③，张量或 mp4 的桶化健康指标）。 判据细节与阈值见 references/verification-and-budget.md；三级等价口径与质量门属 accuracy-gate。

分片“到底有没有生效”：先证明切片发生，再谈等价与收益

“看起来生效了但收益测不出 / 结果不对”时，先用状态量（pieces 的实读值、片内 shape、state 是否为 None）证明分片确实发生，再做闸① 逐位对拍。顺序反过来会把静默回退（门控没生效 ⇒ 仍是整段冗余解码）误判成“无损”。探针写法、两侧对照表与逐层收窄的判别量见 references/parallel-scope-effectiveness.md（本节不重复）。

脚本调用时机

脚本	何时调用
scripts/sliced_state_decode.py	网络里有记忆块、要按潜帧边界切分并携带状态时：抄它的 apply_sliced，替换两个 ADAPTER 钩子
scripts/shard_equivalence_check.py	实现完切分后第一件事：CPU 上整段 vs N 段 bitwise 对拍（不通过就不要上卡）
scripts/frame_health.py	② 通过后做 ③：对张量或 mp4 算桶化 hf / 帧间差 / 近重复帧段，定位“从第几帧开始坏”

维护与更新

• 触发：解码器结构 / 权重形态变化、CANN 或 torch_npu 版本升级、交换拓扑变化、本对象出现新的失败形态时，按 dev-workflow 的复盘流程刷新本技能（判据进正文，实测数字按数字纪律出库或带作用域）。
• 新增内容的归属：VAE encode 段一旦有经验，按 §0 的范围用同一套判据补进本技能正文与 references/；计算手段 / 通信方法论 / 等价判据 / 数字口径仍只引用（pattern-dev / operator-dev / dit-perf-opt / dit-parallel-opt / accuracy-gate / perf-gate），不在本技能复制。
• 如何判定记录仍存在（先复核、再套用）：
  • 设备缺陷类：按 references/troubleshooting-cann-upsample.md §2 的三条判定实验（算子隔离 / 等价写法交叉验 / 规模阈值扫描）跑一遍；阈值与首坏索引不再复现 ⇒ 该条已失效，删除或改写为“已被修复”，并按该文件 §4 决定分段是否保留；
  • 可切性 / 独立性类：拿目标网络的算子表重跑 scripts/shard_equivalence_check.py 的逐位对拍；不再为 max|d| = 0 ⇒ 结构或版本已变，重做独立性审计（references/independence-proof.md §1 表）；
  • 条件等价类（MINLEN 一类）：用当前长度 / 形状重算前置条件并重跑闸①；条件不再成立 ⇒ 前置条件与自动修复一并重写，不得沿用旧常数；
  • 占比 / 收益类：按 perf-gate 同窗重测，并写明步数档 + 分辨率 + 卡数口径（同一模型不同步数档的固定开销占比差异极大）。
• 失效信号（出现任一条即视为对应记录过期）：换版本后首坏索引 / 阈值区间变了；同一实现仅改段数就不再逐位相等；同窗对照差异落进噪声地板；解码段占比不再领先（结论退回“先去啃 DiT 与 host 段”）。
• 删除纪律：确认已修复 / 不再复现的条目直接删除，不要留“以防万一”；绕行一律走可一键关闭、可整体删除的开关，不长期分裂代码路径。

结论是动态的：记判据，不记死结论

本技能里出现的每个数字都是某次观测，写进来是为了让你知道“该期待什么量级、该怎么判”，不是让你 照抄。判断随下面这些轴变化——任何一条变了，旧结论就不再成立，必须重测（这也是为什么本技能把 流程与判据放在正文、把数值放在“实例”里）：

会变的轴	为什么会推翻旧结论	重测方式
硬件 / 驱动 / CANN 或框架版本 / kernel 实现	阈值、首坏索引、数值路径都可能随实现改变（同一个算子换版本可能就好了，也可能新坏）	重跑阈值扫描 + 逐层打点
模型 / 形状 / 序列长度 / 分块参数	阈值与首坏索引通常是形状的函数，不能按比例外推	用真实形状重扫
布局 / dtype / 自动混合精度是否真的生效	“autocast 没下转”这类观察是版本相关的	开关对照一次（逐位比对）即可判定
并行拓扑与卡数	参与方式、交换量、状态边界都会变	重做独立性审计与预算核算
窗口 / 邻居负载 / 共享机器	绝对值漂移可能大于收益本身	同窗 A/B（必要时 A/B/A 校正）
权重 / 解码器 / 预处理约定	同一道门禁下语义可能完全不同	与独立真值做忠实度对照
用户裁决（某参数冻结、某档不采用）	这是决策，不是技术结论	记录裁决与其出处，不要写成“更快/更好”

写结论时请带上证据卡三件套，缺一件别人就无法复核、也无法判断它何时过期：

1. 口径：哪台机器、什么形状/步数、哪个时间窗口、哪份权重与解码器；
2. 判据：多大差异算成立、噪声地板是多少、阈值只二分到哪个区间（未定值就写“区间”）；
3. 失效信号：出现什么现象就说明这条结论不再适用（例如“换版本后首坏索引变了”“同窗对照差异接近地板”）。

案例索引（同环境口径下的观测，用于对照形态；数值本身不是普适结论）

每条都绑定“当时的口径与条件”，条件一变就重测（见上「结论是动态的」）。

• 帧轴切分精确：逐帧 2-D 预览网（_decode_2d，按 chunk_latents 对齐切，无 halo）→ 12/12 md5 一致、video_tae 耗时降到约四分之一；代价为数 GB 量级的额外 HBM/卡。
• 帧轴切分否证：官方时间维 taehv 的 MemBlock 前缀依赖 → 改走状态携带切分（否证是结构性的，与版本无关；但换成别的递归网络要重新审计依赖范围）。
• 状态携带切分：CPU bitwise 等价；设备上实测 2 段即消除尾段塌陷（段数以现场阈值扫描为准，别照搬 2 这个数），且明显更快更省（耗时降到约四成、峰值显存约减半）。
• 切分绕过设备缺陷：CANN nn.Upsample 大 batch 少写尾部（缺陷阈值与首坏索引随版本/形状变化，必须现场重扫；判定实验见 references/troubleshooting-cann-upsample.md）。
• 条件性分片：音频 VAE 2 片（按现场重扫出的下限设 MINLEN 修复短片）、8 片不精确的否证（精确性前置条件要按现场长度条件重算）。
• 交换量的口径是：按输出张量形状（T×H×W×C）× dtype 字节数手算，fp32 视频输出单卡达数 GB 量级 ⇒ 改 uint8 可降到约四分之一，或按 tile 落盘（尚未实现，作为待办；换分辨率/时长要按实际张量重算）。