Chunk Loss 用于降低大词表语言模型在输出投影和交叉熵阶段的峰值显存。它沿当前 rank 的
本地序列维分块执行 LM Head、FP32 交叉熵和一阶梯度计算,任何时刻都不会生成完整的
[batch, local_sequence, vocabulary] logits。
当前实现包含三层:
components/losses/chunked_cross_entropy.py:与模型无关的分块线性交叉熵;ChunkedCausalLMLoss和 Trainer 接线:负责标签交接、局部归一化与模型绑定;models/qwen3_moe/adapter/chunk_loss.py:Qwen3-MoE 在完整 LM Head 之前的专用适配。
普通 causal-LM 前向先执行:
final hidden [B, S_local, H]
-> lm_head
full logits [B, S_local, V]
-> FP32 cross entropy
loss
如果只在 BaseTrainer.postforward() 中新增一个 loss,模型已经生成了完整 logits,峰值显存已经
发生,事后删除 logits 不能消除该峰值。因此,启用 Chunk Loss 时,Trainer 会先把 loss-only
标签转换为模型输入协议;模型族 adapter 再在 root model 的 forward 内取得 final hidden,直接
调用分块 loss,并跳过原来的完整 lm_head(hidden_states)。
Qwen3-MoE adapter 返回 ChunkedCausalLMOutput(logits=None)。ChunkedCausalLMLoss 会再次检查
logits is None,若模型错误地走回完整 logits 路径会立即报错,而不是静默退化。
通用接口如下:
from hyper_parallel.components.losses import chunked_cross_entropy
loss_sum = chunked_cross_entropy(
hidden_states,
targets,
lm_head.weight,
chunk_size=1024,
ignore_index=-100,
)| 参数 | 形状或类型 | 含义 |
|---|---|---|
hidden_states |
[B, S_local, H], floating |
当前 rank 的 final hidden |
targets |
[B, S_local], torch.long |
已和 hidden 对齐的目标 token |
lm_head.weight |
[V, H], floating |
当前 root forward 中可计算的完整 LM Head 权重 |
chunk_size |
positive int |
单次处理的最大本地序列长度 C |
ignore_index |
int |
不参与交叉熵的目标值 |
接口返回图连接的 FP32 标量 loss_sum,不在内部做 DP、CP、micro-batch 或 token 数归一化。
普通路径的主要输出临时量随 B * S_local * V 增长。Chunk Loss 把这一项限制为
B * C * V,但仍保留训练必须交还上游的 dHidden [B, S_local, H] 和累计的
dWeight [V, H]:
| 项目 | 普通完整 logits | Chunk Loss |
|---|---|---|
| 单次 logits 范围 | [B, S_local, V] |
[B, C, V] |
| 交叉熵主要临时量 | O(B * S_local * V) |
O(B * C * V) |
| outer backward 前保留 | 完整 logits 图及必要激活 | dHidden、累计 dWeight |
| 参数/FSDP 梯度 | 必须存在 | 仍必须存在 |
因此它解决的是大词表输出阶段随序列长度增长的临时峰值,不会把模型参数、优化器状态、 FSDP all-gather 权重或最终参数梯度变成零。
每个本地序列块执行以下过程:
- 取
hidden_chunk [B, C, H]和对应target_chunk [B, C]; - 计算
hidden_chunk @ weight.T,只生成[B, C, V]logits; - logits 转 FP32,执行
reduction="sum"的交叉熵; - 用
torch.func.grad_and_value同时得到该块的 loss、dHidden_chunk和dWeight_chunk; - 把
dHidden_chunk写入完整本地dHidden的对应区间,并把dWeight_chunk加到一个[V, H]accumulator; - 释放该块 logits 和块级梯度后再进入下一块。
自定义 autograd Function 的 outer backward 不会重新生成 logits。它把保存的 dHidden、
dWeight 乘以上游标量,分别交回 decoder graph 与 LM Head 参数。这样支持 Trainer 的 token
加权和梯度累积,同时避免保存完整 logits graph。
该实现保证一阶梯度并显式拒绝二阶梯度。首版面向全参数训练,固定分配 dHidden 和
dWeight 两个 accumulator,不为冻结 decoder 或冻结 LM Head 增加分支。accumulator dtype
跟随输入和权重 dtype,交叉熵数值计算使用 FP32。
在 TrainerConfig 根节点显式配置 loss:
loss_fn:
_target_: hyper_parallel.components.losses.ChunkedCausalLMLoss
chunk_size: 1024
ignore_index: -100BaseTrainer._build_loss() 在模型完成替换、分片、FSDP、加载和 dtype 转换后构建该模块,并调用
它的 bind_model(model, distributed_setup)。Qwen3-MoE 的 provider 通过模型 adapter registry
自动解析,用户不需要在 recipe 中手写 forward patch。
每个 micro-batch 的 Trainer 流程是:
- batch adapter 返回独立的
model_inputs与loss_inputs; ChunkedCausalLMLoss.prepare_model_inputs()从 loss 输入读取预先生成的shift_labels和 loss mask;- 从模型输入移除普通
labels、shift_labels,避免 Qwen 自己计算 eager loss; - 增加显式的
chunk_loss_*参数并调用模型; - Qwen adapter 返回
loss_sum、valid_token_count、可选 MoE aux loss,且logits=None; - loss 模块先形成当前 rank 的有效 token mean;
- 现有
mean_global_loss()再完成 DP/CP 与 micro-batch 的全局 token 加权; - backward 把预计算梯度交回普通 autograd 和 FSDP。
普通 ModelOutputLoss 以及只实现 forward(model_output=..., labels=...) 的自定义 loss 不受影响。
bind_model 和 prepare_model_inputs 是 model-integrated loss 才使用的可选生命周期接口。
通用 chunked_cross_entropy primitive 允许自定义 ignore_index。Trainer 的全局 token 计数目前
遵循数据层统一值 -100,所以 ChunkedCausalLMLoss 会在 bind 阶段拒绝其他值,防止局部 loss
和 DP/CP token 权重统计不同步。
首版只接受 shift_labels。该 tensor 已经表示每个 hidden 位置要预测的下一个 token:
hidden[:, 0:S, :] <-> shift_labels[:, 0:S]
实现保留全部本地 hidden 位置,再用 loss_mask 把无效目标覆盖为 ignore_index。数据路径必须
在 CP 切分前完成 next-token shift,再把 input 和 target 一起切到各 rank;这样 CP=1 与 CP>1
使用同一语义,也不会丢失 rank 边界目标。只提供普通 labels 会直接报错,避免 CP=1 静默
二次 shift 或 CP>1 静默漏算边界 token。
Qwen adapter 只在输入包含 chunk_loss_targets 时启用。普通推理或未配置 Chunk Loss 的训练仍调用
原始 Qwen forward。
Chunk Loss 路径按以下顺序执行:
- 调用
model.model(...)得到last_hidden_state; - 校验 final hidden 与预先 shifted targets 对齐,并应用 loss mask;
- 直接以
model.lm_head.weight调用chunked_cross_entropy; - 若
output_router_logits=true,复用 Transformers 的 load-balancing loss,并保留原router_aux_loss_coef; - 返回
ChunkedCausalLMOutput,明确令logits=None。
训练路径要求 use_cache=false、return_dict=true 和 logits_to_keep=0。LM Head 当前必须是无
bias 的 torch.nn.Linear。adapter 的绑定是幂等的,未收到 Chunk Loss 参数时会回退原 forward。
第一版支持 TP=1、PP=1、loss parallel 关闭时的普通 DP/FSDP、CP 和 EP 组合。以下边界会在首个 forward 之前 fail fast:
- TP>1:词表或 hidden 维分片需要分布式 softmax/交叉熵,不能直接把本地 shard 当完整权重;
- PP>1:最后 stage 的 loss 输入、token 归一化与 stage 输出协议尚未接入;
- loss parallel:会和当前完整词表 Chunk Loss 重复定义 logits/softmax 布局。
FSDP root forward 覆盖 Qwen decoder 和 LM Head;Chunk Loss 在该 forward 返回前使用 unshard 后
的 lm_head.weight。它产生的 dWeight 仍作为该 Parameter 的梯度交给既有 FSDP
reduce-scatter/reshard,不复制参数,也不绕开 FSDP 的梯度管理。
当前还不支持带 bias、LoRA/DoRA/QLoRA 或自定义投影语义的 LM Head,也不承诺
torch.compile(fullgraph=true) 下的图捕获。
较小的 chunk_size 降低块级 logits 峰值,但增加 LM Head、交叉熵和 Python 调度次数;较大的值
通常更快但峰值更高。建议从 1024 开始,再按词表大小、本地序列长度和设备实测选择。