DeepInfer 源码完全拆解（十四）：权重装载——覆盖校验、三条加载通道与按 EP rank 物化专家

config.json 校验：先拒绝不支持的架构，再谈加载

load_hf_model_config 对 V4.1 的配置做了两轮“硬性断言”。第一轮针对文本模型：激活函数必须是 silu、注意力不能有 bias、dropout 必须是 0、num_key_value_heads 必须是 1（MLA 的共享 KV 头只有一个）、HF 顶层 dtype 必须是 bfloat16。第二轮针对量化配置：

1
quant = hf["quantization_config"]
2
for key, expected in {
3
    "quant_method": "fp8",
4
    "expert_dtype": "fp4",
5
    "activation_scheme": "dynamic",
6
    "weight_block_size": [32, 32],
7
    "scale_fmt": "ue8m0",
8
}.items():
9
    if quant[key] != expected:
10
        raise ValueError(f"Unsupported HF {key}: {quant[key]!r}; expected {expected!r}")

这些断言不是“多此一举”。load_covered_params 里的 FP8 逻辑假定：权重是 E4M3、缩放粒度是 32 个通道一组、scale 的存储格式是 ue8m0 且能被无损还原成 fp32。如果 checkpoint 是 128×128 方块（比如 DeepSeek-V3 的格式），那么后面的 transform_sf_into_required_layout 和 batched_transpose_weight_sf 的布局都会对不上。在入口处就把不兼容的配置挡掉，比在加载到第 10 个分片时抛一个形状错误要省事得多。

每个 rank 看到的 config 是不同的：finalize_model_config

进入 load_model 后，第一步不是读文件，而是 finalize_model_config(model_cfg)。它把推理时才知道的并行拓扑写进 gpt 配置：

1
ep_group = PG.expert_parallel_group()
2
ep_size = ep_group.size() if ep_group is not None else 1
3

4
model_cfg.gpt.max_num_decoding_tokens = model_cfg.gpt.max_num_seqs * (1 + envs.DEEPINFER_USE_NEXTN_DECODE)
5
model_cfg.gpt.max_num_prefilling_tokens = model_cfg.gpt.max_num_batched_tokens // PG.context_parallel_group().size()
6

7
min_num_extra_experts = envs.DEEPINFER_OVERRIDE_NUM_EXTRA_EXPERTS
8
_configure_moe_redundancy(model_cfg.gpt, min_num_extra_experts, ep_size)

_configure_moe_redundancy 是关键。EPLB 要求“逻辑专家数 + 冗余专家数”能被 ep_size 整除，否则每个 rank 分到的物理槽位数不一样，n_local_routed_experts 就不成立。所以这里把用户给的“最小冗余专家数”（环境变量 DEEPINFER_OVERRIDE_NUM_EXTRA_EXPERTS，示例脚本里默认 32）向上取整到满足整除的值，并把结果写回 gpt.moe.n_redundant_experts 和 DFlash 层的 dflash_cfg.moe.n_redundant_experts。

这一步看似只是数字调整，但它决定了后面专家物化的核心参数：FusedExperts 用 n_routed_experts = 逻辑专家数 + 冗余专家数 来分配 (n_local, h_out, h_in//2) 打包 FP4 的存储，用 n_local_routed_experts = n_routed_experts // ep_size 来算每个 rank 的槽位数；而 _local_expert_ids 又会用“初始全局物理→逻辑映射”在这段槽位里取出真正属于本 rank 的逻辑专家编号。三者必须基于同一个取整后的冗余数，否则装载出来的专家顺序就乱了。

在 meta 上建壳：V41Builder 与参数容器的职责

build_model_on_meta 把默认设备切到 meta，交给 V41Builder：

1
def build_model_on_meta(model_cfg: AttrDict) -> nn.Module:
2
    with torch.device("meta"):
3
        return V41Builder(model_cfg).build_model()

DeepseekForCausalLM.load_model 在规划阶段直接调用 build_model_on_meta(model_cfg)，所以参数壳从头到尾没有碰过真实数据。V41Builder.build_model 建出来的是一个扁平的 nn.Sequential：

1
stage_modules: list[nn.Module] = [MultimodalEmbedding(gpt_cfg)]
2
stage_modules.extend(self._build_block(gpt_cfg, layer_id, shared_topology) for layer_id in range(gpt_cfg.num_hidden_layers))
3
stage_modules.append(MainPredictHeadHC(gpt_cfg, gpt_cfg.num_hidden_layers))
4
if nextn_predict > 0:
5
    ...
6
    for shift in range(1, nextn_predict + 1):
7
        layer_id = gpt_cfg.num_hidden_layers + shift
8
        stage_modules.append(
9
            DFlashNextPredictHeadHC(gpt_cfg, layer_id,
10
                self._build_block(gpt_cfg, layer_id, shared_topology, block_cfg=dflash_block_cfg),
11
                ...)
12
        )
13
model = HFModelParameters(stage_modules, self.cfg)
14
prepare_meta_fp8(model)

模块编号和 HF 的命名一一对应，这不是巧合，而是 hugging_face/names.py 里那张表在事后能工作的前提。那张表的含义是：

这种“固定编号”的设计在后面的覆盖校验里非常重要：加载器需要在 meta 建好的模型上，按 module.module.{k}.xxx 这样的路径找参数，而不是靠名字模糊匹配。同时，DFlash 层的 MoE 可以通过 dflash_cfg.moe 覆盖主模型的 MoE 配置（更少的专家与激活数），_build_block 在构造时把 block_cfg 换成 DFlash 版本，于是 DFlash 层的 FusedExperts 和主干层的槽位数可以不同——这又给装载器增加了一条“不同层覆盖粒度不同”的分支。

MainPredictHeadHC 的构造里有一个容易忽略的点：lm head 的权重是 shared_head.head.weight。到了运行时 DeepseekForCausalLM.__init__ 阶段，ParallelLMHead 会直接引用 head_module.shared_head.head.weight，而不是拷贝。也就是说，lm head 在“容器阶段”和“运行时阶段”共享同一块存储。这种“先建壳、后包装”的模式贯穿整个 DeepInfer 模型层：容器只负责形状和命名，运行时类负责加 kernel 与并行元数据，两者共享 storage。这正是为什么加载必须分两步——先在容器上填数，再包装成运行时——如果反过来，运行时层会在构造时对权重做 process_moe_weight 之类的重排，而重排后的参数已经不再对应 HF 的形状。

prepare_meta_fp8：形状在 meta 上已经改成了 fp8

prepare_meta_fp8 在模型建好之后遍历所有模块，为 FP8 层声明 weight 与 sf 的 meta 形状：

1
block = get_fp8_casting_granularity()   # 32
2
for name, module in model.named_modules():
3
    if "tok_emb" in name or "head" in name or getattr(module, "mxfp4", False):
4
        continue
5
    if getattr(module, "use_fp8_embedding", False):
6
        weight = module.embedding
7
        sf_shape = (weight.shape[0], weight.shape[1] // block)
8
    elif isinstance(module, nn.Linear) and getattr(module, "use_fp8_gemm", False):
9
        weight = module.weight
10
        sf_shape = tuple((dim + block - 1) // block for dim in weight.shape)
11
    else:
12
        continue
13
    assert weight.is_meta, "HF parameter preparation must not quantize initialized weights"
14
    weight.data = weight.data.to(torch.float8_e4m3fn)
15
    weight.sf = torch.empty(sf_shape, device="meta", dtype=torch.float32)

逐条读这段有两个信息量很大的地方。

第一，sf_shape 用的是上取整的方块划分，即 ceil(dim / 32)。HF 导出时的 scale 也是按 32 的方块对齐的（不够 32 的部分补零后再算 scale，导出时去掉填充），所以两边的方块数一样，validate_hf_shapes 里才能直接比较“HF 张量形状”。一旦运行期某层的输出维度不是 32 的倍数（例如 Engram 融合投影的 hidden_size * (hc_mult + 1)，5120×5 = 25600 是 32 的倍数，这里恰好成立，但这种“恰好”必须靠断言守住），这条路径就要改。

第二，这里跳过 head 与 tok_emb：embedding 和 lm head 是 BF16。这对应 load_covered_params 的普通通道——element_size 为 1 的参数才会去读 .scale；元素大小为 2 或 4 的参数只拷权重。再看 mHC（多路残差主干），它的 hc_attn_fn/hc_ffn_fn 是折叠进了 norm 权重的 FP32 小矩阵，loading.py 里专门校验它们是 F32，就是防止被 dtype 转换顺手降成 BF16。

prepare_hf_coverage 的三重检查

prepare_hf_coverage 在读任何权重之前，先完成三件事：

1
index: dict[str, str] = json.loads(index_path.read_text())["weight_map"]
2
missing_shards = sorted(shard for shard in set(index.values()) if not (hf_dir / shard).is_file())
3
if missing_shards:
4
    raise FileNotFoundError(f"HF checkpoint {hf_dir} is missing shards: {missing_shards}")
5
if norms := sorted(name for name in index if re.search(r"(?:^|\.)hc_(?:attn|ffn|head)_norm\.weight$", name)):
6
    raise ValueError(f"HF requires folded HC weights; separate HC norm tensors are unsupported: {norms[:10]}")
7
if len({name.removeprefix("model.") for name in index}) != len(index):
8
    raise ValueError("HF index contains ambiguous model.-prefixed aliases")

• 分片存在性：索引里有、磁盘上没有的分片直接报错，并列出名字。
• 折叠约束：HC 的 norm 必须已经折叠进 hc_*_fn，不允许出现独立的 hc_attn_norm.weight 这类张量。原因很直接：运行期的 hc_attn_fn 是一个整体矩阵，装载时只做“形状不变”的搬运，不做折叠运算。
• 别名歧义：HF 索引里有 model. 前缀和没有前缀的同名项同时出现时，resolve_hf_name 在“加/去前缀都命中”的情况下会解析失败——这里提前把它变成明确错误，而不是在加载中途遇到 KeyError。这一条看似是防呆，其实对应一个常见现象：不同工具链导出的 checkpoint 有时对 model. 前缀处理不一致。

然后逐个分片打开，safe_open 读 keys，把索引里能解析到的名称加入 available 集合；如果索引里有某些张量在任何分片里都找不到，报错并打印前 10 个名字。

build_coverage：三条通道的覆盖建模

接下来 build_coverage 把 weight_map 整理成三个分组，也就是后面加载时的三条通道：

1
@dataclass(frozen=True)
2
class HFCoverage:
3
    weight_map: dict[str, str]
4
    tensors: dict[str, tuple[str, ...]]       # 普通参数：1 个或 2 个 HF 张量（w1/w3 合并）
5
    expert_tensors: dict[str, tuple[tuple[str, ...], ...]]  # 路由专家：按层聚合
6
    engram_tables: dict[str, str]             # Engram 表：按行区间读取
7
    aliases: dict[str, str]                   # tied 参数：目标 -> 已装载的源

普通参数的扫描规则很朴素：跳过 .scale、跳过 _is_expert、跳过 Engram 表的 embed.weight，剩下的名字走 hf_to_model 得到内部名；如果内部名是 experts.shared_experts.0.linear1.weight，则要求它有 2 个来源（w1 与 w3），否则这组直接丢弃——也就是“缺一半就算没覆盖”，不会被加载器悄悄装成一半。

路由专家不是一个名字对应一个张量，而是一层对应很多张量。这里不能按“单个专家”做覆盖，原因在于运行期参数的形状：FusedExperts 的 linear1 是一个 ParallelRoutedLinear，它的权重形状是 (hidden_dim * 2, hidden_size * n_local_experts)——即所有本地专家沿输入维拼接，而且每个专家内部还按 [w1; w3] 拼成一个 2*hidden_dim 的输出。_scan_expert_coverage 正是按这个聚合粒度来建模的：

1
layers.setdefault(match["prefix"], {}).setdefault(int(match["expert"]), {})[match["which"]] = name
2
...
3
if expert_ids != list(range(len(expert_ids))):
4
    logger.warning(f"{prefix}: expert indices are not contiguous ({len(expert_ids)}), so HF cannot fully cover this layer")
5
    continue
6
if any(set(per) != {"w1", "w2", "w3"} for per in experts.values()):
7
    continue
8
expected = gpt_cfg.moe.n_routed_experts
9
if prefix.startswith("mtp."):
10
    override = gpt_cfg.get("dflash_cfg", {}).get("moe") or {}
11
    expected = override.get("n_routed_experts", expected)
12
if len(experts) != expected:
13
    continue
14
module_prefix = hf_layer_module_prefix(prefix, n_layer=gpt_cfg.num_hidden_layers)
15
expert_tensors[f"{module_prefix}experts.linear1.weight"] = tuple((experts[e]["w1"], experts[e]["w3"]) for e in expert_ids)
16
expert_tensors[f"{module_prefix}experts.linear2.weight"] = tuple((experts[e]["w2"],) for e in expert_ids)

这段代码里有四个约束值得展开。

1. 专家编号连续：从 0 开始，不能有缺号。缺号意味着这个层在 HF 里是“残缺”的，运行时无法在形状上对齐。
2. 每个专家都得有 w1/w2/w3 且带 .scale：缺一个就是整层不完整。
3. 数量必须等于配置：主干层用 gpt.moe.n_routed_experts，DFlash 层（mtp. 前缀）用 dflash_cfg.moe.n_routed_experts。这一点在多篇 V4 系列文章里被反复提到——DFlash 层的专家数是和主干不同的，所以这里必须按层判断。
4. 每个专家的权重和 scale 必须成对出现：if scale_name(name) not in available: continue。FP4 打包权重如果没带 scale，装进去就是一堆无意义的半字节。这个约束在“覆盖”层面就挡住了。

注意 expected 用的是 n_routed_experts（逻辑专家数），不是加上冗余后的物理数。因为 HF checkpoint 里只有一份逻辑专家；冗余专家是运行时按物理槽位复制出来的。这一点正是后面 _local_expert_ids 和“一层一个 3D 打包参数”能够成立的关键。

Engram 表的覆盖最简单：权重与 .scale 必须都在，且通过 hf_to_model 映射到内部名。

映射函数：一次“名字对名字”的翻译，但有 1:2 的合并

hf_to_model 是纯字符串映射，但它做了几件事：

1
_HF_TO_MODEL_SUFFIX = {
2
    "hc_attn_base": "hc_attn",
3
    "attn.attn_sink": "self_attn.attn_sink_params",
4
    "attn.wq_a.weight": "self_attn.Wq.A.weight",
5
    "attn.wq_b.weight": "self_attn.Wq.B.weight",
6
    "attn.wkv.weight": "self_attn.Wkv.A.weight",
7
    "attn.wo_b.weight": "self_attn.out_proj.weight",
8
    "attn.compressor.wkv.weight": "self_attn.PackedWkv.A.weight",
9
    "attn.indexer.wq_b.weight": "self_attn.index_attn.q_B.weight",
10
    "ffn.gate.bias": "experts.gate.e_score_correction_bias",
11
    # linear1 = [w1; w3] concatenated along dim 0.
12
    "ffn.shared_experts.w1.weight": "experts.shared_experts.0.linear1.weight",
13
    "ffn.shared_experts.w3.weight": "experts.shared_experts.0.linear1.weight",
14
    "ffn.shared_experts.w2.weight": "experts.shared_experts.0.linear2.weight",
15
    "engram.q_weight": "engram_embedding.weight_hidden",
16
    ...
17
}

三件事值得注意：

• V4.1 的注意力权重被命名成了 MLA 的形状：wq_a/wq_b 是 q 的低秩投影两段；wkv, wo_a, wo_b 分别是 KV 压缩与输出投影；compress_ratios 中压缩率大于 1 的层还有一个 compressor，对应运行时的 PackedWkv；带索引器的层有 indexer.* 的几项。这些名字的语义在 DeepInfer 源码拆解（十一）：注意力族与压缩 KV 里有完整拆解，这里只需知道：加载器只做名称翻译，不做语义解释。
• attn.attn_sink 映射到 attn_sink_params：sink 在模型里是“参数”而不是“权重”，在 loading.py 里还专门检查其 dtype 必须是 F32——因为它是以有效 logit 的形式存的。
• 共享专家的 w1 与 w3 映射到同一个内部名：这意味着 tensors 通道里这一项会有两个来源，加载时沿 dim 0 cat 起来，对应 linear1 = [w1; w3]。

还有一层前缀映射（由 hf_layer_module_prefix 完成）：layers.{L}. → module.module.{L+1}.，mtp.{i}. → module.module.{n_layer+2+i}.block.，以及 mtp.*.embed.weight / mtp.*.head.weight 返回 None（因为它们是 tied，HF 只存一份）。最后一维的细节是 DFlash 层的 block. 这一级在 HF 里被省掉了——加载器必须在映射时补上，否则在 meta 模型上找不到对应参数。

提前做形状校验：validate_hf_shapes

读权重之前，load_hf_checkpoint 先调用 validate_hf_shapes：

1
def validate_hf_shapes(params, coverage, *, hf_dir) -> None:
2
    todo = {cm: names for cm, names in coverage.tensors.items() if cm in params}
3
    index = coverage.weight_map
4
    names = list({name for sources in todo.values() for name in sources})
5
    ...
6
    for shard, sources in _group_by_shard(index, names).items():
7
        with safe_open(str(hf_dir / shard), framework="pt", device="cpu") as handle:
8
            keys = set(handle.keys())
9
            for name in sources:
10
                view = handle.get_slice(resolve_hf_name(name, keys))
11
                shapes[name] = tuple(view.get_shape())
12
                dtypes[name] = view.get_dtype()
13
    for cm, sources in todo.items():
14
        shape = shapes[sources[0]]
15
        if len(sources) > 1:
16
            if any(shapes[name][1:] != shape[1:] for name in sources):
17
                raise ValueError(f"{cm}: incompatible HF concatenation shapes")
18
            shape = (sum(shapes[name][0] for name in sources), *shape[1:])
19
        if shape != tuple(params[cm].shape):
20
            raise ValueError(f"{cm}: HF shape {shape} != model shape {tuple(params[cm].shape)}")
21
        ...

这段最“省钱”的地方是 get_slice：它只读 safetensors 头部，不读数据。所以对每一个普通参数，加载器在真正搬运数万个小张量之前，就已经知道“HF 形状（含合并）是否等于模型形状”、“dtype 是否等于模型 dtype”，并且对 HC 与 sink 强制要求 F32。对大模型来说，这一步的耗时基本就是读几十个分片的头部。

但它只校验普通通道。专家通道里的“形状”是按层聚合的，而且还有更麻烦的 rank 物化问题——所以在加载专家时，_load_expert_params 会做另一组断言，我们稍后展开。

tied 参数：先装一次，再按需复制

DFlash 层的 embedding 与 lm head 都是 tied 的，HF 里只存储一份（embed.weight 与 head.weight）。但 meta 模型里，DFlash 层可能有独立的 emb.tok_emb.weight 与 shared_head.head.weight 参数壳——这是因为 V41Builder 对每个 DFlash 层都构造了 DFlashNextPredictHeadHC，而它内部确实有一个共享 head 的名称路径。cover_tied_parameters 解决的就是这件事：

1
def cover_tied_parameters(coverage, param_names, *, n_layer) -> HFCoverage:
2
    aliases = dict(coverage.aliases)
3
    sources = {
4
        "emb.tok_emb.weight": "module.module.0.emb.tok_emb.weight",
5
        "shared_head.head.weight": f"module.module.{n_layer + 1}.shared_head.head.weight",
6
    }
7
    for cm in param_names:
8
        parts = cm.split(".", 3)
9
        if len(parts) != 4 or parts[:2] != ["module", "module"] or not parts[2].isdigit() or int(parts[2]) <= n_layer + 1:
10
            continue
11
        source = sources.get(parts[3])
12
        if source in coverage.tensors and source in param_names:
13
            aliases[cm] = source
14
    return replace(coverage, aliases=aliases)

它把所有 module.module.{>n_layer+1}.emb.tok_emb.weight 与 ...shared_head.head.weight 标记成“别名”，其源是 embedding 段与主 lm head。加载器只会真正装一遍 source，然后在物化阶段，把同名的 storage 共享给这些别名参数。这样做有两个好处：显存里只有一份 129280×5120 的 embedding（BF16 约 1.2 GiB），DFlash 层再多也不重复；而且这种共享在参数层面就是同一个 tensor 存储，运行时直接读就行。

覆盖完整性：最后的防线

最后，load_hf_checkpoint 把所有参数名与 coverage 的 model_names() 对一遍：

1
missing = sorted(set(params) - coverage.model_names())
2
if missing:
3
    raise RuntimeError(f"HF checkpoint {hf_dir} 未覆盖 {len(missing)} 个模型参数：{missing}")
4
validate_hf_shapes(params, coverage, hf_dir=hf_dir)
5
with checkpoint_load_watchdog():
6
    load_covered_params(gpt, coverage, hf_dir=hf_dir)
7
logger.info(f"HF 加载完成：全部 {len(params)} 个模型参数来自 {hf_dir}")

这里要理解一个细节：set(params) 是这个 rank 自己的参数全集，但 coverage 是从 HF 索引生成的、全 rank 共享的覆盖表。所以“缺失检查”在 EP 下判断的是“模型里每个参数名在该 rank 对应的覆盖条目里有没有来源”；这一点依赖 cover_tied_parameters 已经把所有 DFlash 别名补进来了。另外，checkpoint_load_watchdog 给了 30 分钟的超时保护：超时就 os.abort()，而不是让 loader 挂死在一个坏分片上——对大规模 checkpoint 来说，这比“永远不完成”更可控。

materialize_hf_parameter：一个函数里装下四种参数布局

1
def materialize_hf_parameter(param: nn.Parameter, *, device: str, packed_fp4: bool = False) -> nn.Parameter:
2
    target = torch.device(device)
3
    if target.type == "cuda" and target.index is None:
4
        target = torch.device("cuda", torch.cuda.current_device())
5

6
    if packed_fp4:
7
        assert param.ndim == 2 and param.dtype == torch.float8_e4m3fn
8
        n_experts = getattr(param, "n_experts", None)
9
        assert isinstance(n_experts, int) and n_experts > 0
10
        k, remainder = divmod(param.shape[0], n_experts)
11
        n = param.shape[1]
12
        sf_dtype = PLATFORM.fp8_sf_type
13
        assert sf_dtype in (torch.int16, torch.int32)
14
        sf_pack_granularity = 32 * sf_dtype.itemsize
15
        assert remainder == 0 and k > 0 and n > 0 and k % sf_pack_granularity == 0 and n % 32 == 0
16
        assert get_fp8_casting_granularity() == 32
17
        assert hasattr(param, "sf") and param.sf.dtype == torch.float32
18
        assert tuple(param.sf.shape) == (n_experts * (k // 32), n // 32)
19
        result = nn.Parameter(torch.empty((n_experts, n, k // 2), dtype=torch.int8, device=target), requires_grad=False)
20
        # Pack UE8M0 bytes in the backend dtype, column-major within each expert.
21
        sf = torch.empty((n_experts, k // sf_pack_granularity, n), dtype=sf_dtype, device=target).mT
22
    else:
23
        ...

先讲 packed_fp4 分支，因为它是 V4.1 最特殊的部分。

param 此时是 meta 上的 ParallelRoutedLinear.weight，形状是 (hidden_dim*2, hidden_size * n_local_experts)（linear1）或 (hidden_size, hidden_dim * n_local_experts)（linear2）。这里把它拆成 n_experts 份，每份 k × n，再分配成一个 3D int8 张量 (n_experts, n, k//2)。k//2 是因为 FP4 两两打包进一个字节——在 matmul 之前，kernel 需要的就是这种“每个专家的权重按输出通道放在第一维”的排布。

下面那组断言才是重点：

• k % sf_pack_granularity == 0：这里的 sf_pack_granularity = 32 * itemsize。若 sf_dtype 是 int32，即 128；k 必须是 128 的倍数。这对应什么呢？对 linear1 来说 k = 2 * moe_intermediate_size = 2 × 2304 = 4608，是 128 的整数倍（36×128）；linear2 的 k = hidden_dim = 2304，是 128 的整数倍（18×128）。这个整除其实也是 TP4/FP4 专家在 SM100 上走 grouped GEMM 的要求：每一组专家的输出维（n）在内存里被 128 个 scale 包在一起。
• n % 32 == 0：输出维按 32 通道一组量化。对 linear1 的 n = hidden_size = 5120（160 组），linear2 的 n = hidden_size = 5120——两者正好满足。
• sf.shape == (n_experts*(k//32), n//32)：HF 导出的打包 scale 就是“每个专家、每个输入方块、每个输出方块一个 ue8m0 字节”。
• scale 的布局是列优先：torch.empty((n_experts, k // 128, n), dtype=sf_dtype, device=target).mT。这个 mT 不是随意加的。HF 导出的时候按“行主序”存储每个权重方块组的 scale，而运行时的 grouped GEMM 需要“每个输出通道的 128 个 scale 连在一起”。mT 做的是 transpose 视图：分配的是 (n_experts, k/128, n) 的连续内存，返回的视图把最后两维转置，于是“每个专家、每个输出通道”在内存里是连续的。后面 _load_expert_params 里用 scale.view(param.sf.dtype) 再把每个专家的 scale 写进这个视图——字节直接搬，没有重新计算。

再看普通 FP8 分支：result 分配成与 meta 同形状、dtype 为 float8_e4m3fn 的参数；sf 是一个“空的”占位——如果 param.sf.is_meta，就再分配一个新的 meta 占位（因为普通 FP8 的 scale 加载时会整体替换，见下面）；如果在 CPU/GPU 上已有存储，就沿用。这个分支和 packed_fp4 的差异在于：普通通道的 scale 是运行时从 ue8m0 还原成 fp32 再打包，因此分配阶段不需要知道“按什么布局”。

第三种布局是 Engram：if getattr(param, "is_engram", False) 时，sf 被分配在 CUDA 上，即使权重表在 CPU——原因是 gather_sf() 使用 CUDA 集合通信（all_gather_into_tensor），如果 sf 留在 CPU 会直接报错。

第四种是 BF16/FP32 的普通参数（embedding、head、norm、sink、HC 的 fn）：它们走上图的 else 分支，形状、dtype 不变，直接分配。这一支看起来最平凡，但 load_hf_checkpoint 对 HC fn 与 attention sink 额外要求 F32，原因是它们存的是折叠后的精确值，降成 BF16 会直接改变残差主干的数值行为。

为什么 n_experts 一定要“是本地物理槽位数”

回到 ParallelRoutedLinear：

1
class ParallelRoutedLinear(nn.Linear):
2
    def __init__(self, h_in: int, h_out: int, n_local_experts: int, *, use_fp8_gemm: bool = False) -> None:
3
        super().__init__(h_out, h_in * n_local_experts, bias=False)
4
        self.use_fp8_gemm = use_fp8_gemm
5
        self.n_local_experts = n_local_experts
6
        self.weight.n_experts = n_local_experts

在 FusedExperts.__init__ 里，n_local_routed_experts = n_routed_experts // ep_size，其中 n_routed_experts 是加上了冗余的物理数。所以一个 (n_local, n, k//2) 的打包参数，第一维是“本 rank 的物理槽位数”。

这就把问题推给了读取端：HF 里是“按逻辑专家编号”的单个张量，怎么把它摆成按“物理槽位”排列的 3D 结构？逻辑专家编号和物理槽位编号不是一一对应的——以示例脚本的 EP=8、384 个路由专家 + 32 个冗余为例（384+32=416，416/8=52）：rank 0 的物理槽位 0..51 对应逻辑专家 0..51；rank 7 的 local_start = 52 × 7 = 364，物理槽位 364..415 对应逻辑专家 364..383（20 个），再加上复制出来的逻辑专家 0..7（32 个）（get_initial_global_physical_to_logical_map 返回 [*range(384), *(i % 384 for i in range(32))]）。也就是说，最后一个 rank 里会同时出现“本地逻辑专家”和“从 rank 0 复制过来的逻辑专家”。加载器必须知道每个物理槽位对应哪个逻辑专家。

_local_expert_ids：和 EPLB 初始布局一致的映射

1
def _local_expert_ids(model, params) -> dict[str, tuple[int, ...]]:
2
    from deepinfer.model_executor.eplb import get_initial_global_physical_to_logical_map
3
    from deepinfer.model_executor.models.v4_modules.moe import FusedExperts
4
    from deepinfer.model_executor.parallel_utils.parallel_state import PG
5

6
    cm_of_param = {id(param): cm for cm, param in params.items()}
7
    ep_rank = PG.expert_parallel_group().rank()
8
    modules = sorted((m for m in model.modules() if isinstance(m, FusedExperts)), key=lambda m: m.layer_id)
9

10
    ids: dict[str, tuple[int, ...]] = {}
11
    for module in modules:
12
        num_routed = module.n_logical_routed_experts
13
        physical_to_logical = get_initial_global_physical_to_logical_map(num_routed, module.n_routed_experts - num_routed)
14
        local_start = module.n_local_routed_experts * ep_rank
15
        local_ids = tuple(int(i) for i in physical_to_logical[local_start : local_start + module.n_local_routed_experts])
16
        for attr in ("linear1", "linear2"):
17
            model_name = cm_of_param.get(id(getattr(module, attr).weight))
18
            if model_name is not None:
19
                ids[model_name] = local_ids
20
    return ids

这段很短，但每一行都有意为之：

• 按 layer_id 排序 FusedExperts：保证遍历顺序与层号一致。虽然这里每个模块各自算映射，排序更多是为了日志与后续调试方便，但它也确保了“同名层”不会被混用。
• num_extra_experts 用的是“本层的物理数 − 本层逻辑数”，而不是全局环境变量。这一点至关重要：DFlash 层的 n_routed_experts 与主干不同，如果直接拿环境变量的冗余数去算，就会在 DFlash 层上得到一个长度不匹配的映射，physical_to_logical[local_start: local_start + n_local] 取出来的内容也会错位。
• 映射表是按层现算的：get_initial_global_physical_to_logical_map 是纯 Python 函数，返回 [0..n-1] + [i % n for i in range(extra)]。它和 ExpertLoadBalancer.__init__ 里初始化时用的函数是同一个。这意味着装载时的“物理槽位→逻辑专家”顺序与运行时 EPLB 的初始 physical_to_logical_map 完全一致。如果 EPLB 启动后第一次重排就 shuffle 权重，它是在这个初始布局上做搬移的；如果装载时顺序错了，那次 shuffle 会把错误的专家搬到新位置。
• cm_of_param 按 id(param) 建立索引：因为这里没有名字路径可用，但 model_params(model) 返回的 cm 与参数对象一一对应。这一步把“模块属性 → 参数名”接上了。

一个容易忽略的边界：physical_to_logical[local_start : local_start + n_local] 的长度必须等于 n_local。如果 n_routed_experts % ep_size != 0，FusedExperts.__init__ 的 assert 会先拦住；如果 _configure_moe_redundancy 取整写回的值和这里不一致，长度可能不足，_load_expert_params 里的 assert param.shape[0] == len(ids) 会兜底。

三条加载通道

物化完成后，load_hf_checkpoint 只做一件事：调用 load_covered_params。它内部依次执行三条通道：

1
def load_covered_params(model, coverage, *, hf_dir) -> dict[str, int]:
2
    started = time.perf_counter()
3
    params = model_params(model)
4
    todo = {cm: names for cm, names in coverage.tensors.items() if cm in params}
5
    index = coverage.weight_map
6
    fp8_params, loaded = [], 0
7
    with _TensorReader(hf_dir, index) as reader:
8
        for model_name, names in sorted(todo.items()):
9
            param = params[model_name]
10
            assert param.data.element_size() in (1, 2, 4)
11
            assert not getattr(param, "is_engram", False) and not getattr(param, "mxfp4", False)
12
            weight = reader.read_concat(names, param.device)
13
            if tuple(weight.shape) != tuple(param.data.shape):
14
                raise ValueError(f"{model_name}: HF shape {tuple(weight.shape)} != model shape {tuple(param.data.shape)}")
15
            param.data.copy_(weight)
16
            if param.data.element_size() == 1:
17
                sf = reader.read_concat((scale_name(name) for name in names), param.device)
18
                param.sf = _ue8m0_to_fp32(sf).contiguous()
19
                fp8_params.append(param)
20
            del weight
21
            loaded += 1
22
    if fp8_params:
23
        set_ue8m0_sf(fp8_params)
24
    ...
25
    stats |= _load_expert_params(model, params, coverage, hf_dir)
26
    stats |= _load_engram_tables(params, coverage, hf_dir)

1
def _load_expert_params(model, params, coverage, hf_dir) -> dict[str, int]:
2
    if not coverage.expert_tensors:
3
        return {"expert_params": 0, "experts": 0, "expert_skipped": 0}
4
    index = coverage.weight_map
5
    ids_by_cm = _local_expert_ids(model, params)
6
    experts_loaded = params_loaded = skipped = 0
7

8
    for model_name, per_expert in sorted(coverage.expert_tensors.items()):
9
        param = params.get(model_name)
10
        ids = ids_by_cm.get(model_name)
11
        if param is None: skipped += 1; continue
12
        if ids is None: raise RuntimeError(f"HF expert parameter has no local expert layout: {model_name}")
13
        assert param.dim() == 3 and param.dtype == torch.int8, f"{model_name}: expected native FP4 3D int8, got {param.shape} {param.dtype}"
14
        assert param.sf.dtype in (torch.int16, torch.int32), f"{model_name}: unsupported packed scale dtype {param.sf.dtype}"
15
        assert param.shape[0] == len(ids), f"{model_name}: local expert count {param.shape[0]} does not match the derived {len(ids)}"
16
        assert max(ids, default=-1) < len(per_expert), f"{model_name}: HF has only {len(per_expert)} experts, yet needs index {max(ids)}"
17

18
        with _TensorReader(hf_dir, index) as reader:
19
            for local, expert in enumerate(ids):
20
                names = per_expert[expert]
21
                weight = reader.read_concat(names, param.device)
22
                scale = reader.read_concat((scale_name(name) for name in names), param.device)
23
                want = tuple(param.data[local].shape)
24
                assert tuple(weight.shape) == want, f"{model_name}[{local}]: HF weight {tuple(weight.shape)} != runtime {want}"
25
                assert scale.dtype == torch.float8_e8m0fnu, f"{model_name}: expected UE8M0 scale, got {scale.dtype}"
26
                packed_sf = scale.view(param.sf.dtype)
27
                want_sf = tuple(param.sf[local].shape)
28
                assert tuple(packed_sf.shape) == want_sf, f"{model_name}[{local}]: incompatible HF scale"
29
                param.data[local].copy_(weight)
30
                param.sf[local].copy_(packed_sf)
31
                experts_loaded += 1
32
        param.mxfp4 = True
33
        params_loaded += 1
34
    return {"expert_params": params_loaded, "experts": experts_loaded, "expert_skipped": skipped}

1
def _load_engram_tables(params, coverage, hf_dir) -> dict[str, int]:
2
    from safetensors import safe_open
3
    ...
4
    row_chunk_bytes = 1 << 28   # 256 MiB
5
    for model_name, weight_name in sorted(coverage.engram_tables.items()):
6
        param = params.get(model_name)
7
        ...
8
        row_start = int(getattr(param, "row_start", 0))
9
        with torch.device("cpu"), safe_open(str(hf_dir / shard), framework="pt", device="cpu") as handle:
10
            keys = set(handle.keys())
11
            weight_view, scale_view = handle.get_slice(weight_key), handle.get_slice(scale_key)
12
            table_shape, scale_shape = weight_view.get_shape(), scale_view.get_shape()
13
            valid_rows = min(param.data.shape[0], int(table_shape[0]) - row_start)
14
            rows_per_chunk = max(1, row_chunk_bytes // int(table_shape[1]))
15
            for start in range(0, valid_rows, rows_per_chunk):
16
                stop = min(start + rows_per_chunk, valid_rows)
17
                source = row_start + start
18
                weight = weight_view[source: source + (stop - start)]
19
                param.data[start:stop].copy_(weight)
20
                sf = _ue8m0_to_fp32(scale_view[source: source + (stop - start)].to(device=param.sf.device))
21
                param.sf.data[start:stop].copy_(sf)
22
            if valid_rows < param.data.shape[0]:
23
                # HF 不存对齐行；空的目标行需要两个值都补上
24
                param.data[valid_rows:].zero_()
25
                param.sf.data[valid_rows:].fill_(1)

专家通道之外：非 FP4 专家怎么走

上面讲的是“打包 FP4 专家”的直接加载通道。如果模型不是 mxfp4（例如 BF16 专家，或 FP8 专家），物化阶段 packed_fp4 为假，ParallelRoutedLinear 的权重就保留 2D 形状，然后：

• 加载时走普通通道：权重是 BF16 的话直接 copy_，是 FP8 的话顺带读 scale、还原、打包。
• 运行时包装时，DeepseekMoE 会调用 process_moe_weight(moe_module.linear1.weight, n_experts=self.num_local_physical_experts)：先把 2D (h_out, h_in*n_experts) reshape 成 (n_experts, h_in, h_out)，再用 mT 转成 (n_experts, h_out, h_in)（这样每个专家的输出维在前，GEMM 时可以直接按专家分组），然后 transform_sf_into_required_layout 或 per_token_cast 转 FP4。FP8 → FP4 的转换还带一个 ((w.view(torch.int32) & 0x03030303) == 0).all() 的断言，只接受“低两位为零”的 FP8 值（即 “FP4-QAT checkpoint”），防止把任意 FP8 量化到 FP4 时静默改变数值。

这个对比说明了一点：只有“natively FP4”的专家在加载时就能直接按运行时布局物化；其他精度走两段式（先按 HF 形状装，再在运行时重排 + 转换）。DeepInfer 对 V4.1 专门走前者，是因为这个 checkpoint 本身就是 FP4 导出的。

_TensorReader：一个类解决“别把整个文件读进内存”

1
class _TensorReader(ExitStack):
2
    def read(self, name: str, device: torch.device) -> torch.Tensor:
3
        shard = _shard_of(self.index, name)
4
        if shard not in self.handles:
5
            handle = self.enter_context((self.hf_dir / shard).open("rb"))
6
            size = os.fstat(handle.fileno()).st_size
7
            prefix = handle.read(8)
8
            header_size = int.from_bytes(prefix, "little")
9
            if len(prefix) != 8 or not 0 < header_size <= min(100_000_000, size - 8):
10
                raise ValueError(f"Invalid safetensors header size: {shard}")
11
            header = json.loads(handle.read(header_size))
12
            self.handles[shard] = handle, header, 8 + header_size, size
13
        handle, header, data_start, size = self.handles[shard]
14
        entry = header[resolve_hf_name(name, header)]
15
        dtype, shape = self._DTYPES[entry["dtype"]], entry["shape"]
16
        start, end = entry["data_offsets"]
17
        if not 0 <= start <= end <= size - data_start or end - start != math.prod(shape) * dtype.itemsize:
18
            raise ValueError(f"Invalid HF tensor byte range: {shard}:{name}")
19
        if end == start:
20
            return torch.empty(shape, dtype=dtype, device=device)
21
        handle.seek(data_start + start)
22
        data = bytearray(end - start)
23
        view = memoryview(data)
24
        filled = 0
25
        while filled < len(data):
26
            n = handle.readinto(view[filled:])
27
            if not n:
28
                raise EOFError(f"Short HF tensor read: {shard}:{name}")
29
            filled += n
30
        with torch.device("cpu"):
31
            tensor = torch.frombuffer(data, dtype=dtype).reshape(shape)
32
        return tensor.to(device=device)

它做的事看起来和 safetensors.torch.safe_open 差不多，但有三处差异：

1. 不走 mmap：直接 open("rb")，seek 到 data_start + start 再 readinto 一段字节。safe_open 背后是 mmap 映射整个分片，读到哪一页才 fault 哪一页；而专家通道与 Engram 通道都是“只取区间里的一小块”，显式 seek + read 让每次读取都成为可预测的连续区间读，对共享文件系统（NFS/Lustre）更友好，也不会让页缓存把大分片整片驻留。
2. 严格的字节区间校验：0 <= start <= end <= size - data_start 加上 end - start == prod(shape) * itemsize——不只是“文件在”，还要求这个张量的区间完整且尺寸吻合。对于截断的上传或写到一半的 checkpoint，这条检查会立刻发现异常，而不是读到后面才出现乱码。
3. 返回时 to(device)：在 CPU 上构造 torch.frombuffer 张量，然后搬到目标设备。注意 torch.frombuffer 的 data 是 bytearray，to(device) 会做一次拷贝；但如果目标设备正好是 CPU，to(device) 其实是空操作，返回的 tensor 仍依赖那个 bytearray 的缓冲。在专家通道中，_TensorReader 会读进最终设备；在普通通道中，每个参数的权重也会立刻拷贝到 GPU，因此 CPU 侧的内存峰值只有“当前参数”的大小。

还有一个细节：header[resolve_hf_name(name, header)]。resolve_hf_name 处理 model. 前缀歧义，而这里传入的 header 是 safetensors 的字典，它的 keys 集合正是同一个函数前面为索引检查时使用的 keys。所以索引与分片两侧的前缀处理是一致的。

和 vLLM 的路径对照

把 DeepInfer 的装载和 vLLM 的 DefaultModelLoader 放在一起，差异可以归结为两句话：

• vLLM 是“先物化、后迭代、由模型自己的 load_weights 决定怎么装”：DefaultModelLoader.get_all_weights 返回 (name, tensor) 的迭代器，模型类（例如 DeepseekV3ForCausalLM）在 load_weights 里按名字匹配到自己的参数，并且负责所有“特殊布局”的处理（重复专家、tie、scale 转换）。loader 层面只做两件额外的事：“EP 权重过滤”和“加载后跟踪”。
• DeepInfer 是“先规划、后按布局物化、再严格三条通道”：它把“名字映射、覆盖、形状、tied 别名、专家物理槽位”全部在物化之前算出来，然后一次性装完。模型类（DeepseekForCausalLM）在加载完成之后才被构造，所以模型层只处理运行时布局，不处理 HF 布局。

vLLM 的 EP 权重过滤有一个非常值得对照的逻辑：

1
# When EPLB is enabled, redundant physical expert slots may map to
2
# logical experts that belong to other ranks in the default partition.
3
# The weight loader needs to see ALL logical expert weights so it can
4
# populate these redundant slots.  Skip the filter entirely.
5
if parallel_config.enable_eplb:
6
    return

vLLM 面对 EPLB 时选择关闭按 rank 过滤，让每个 rank 看到所有逻辑专家的权重，由模型内部按物理槽位去挑。这当然正确，但代价是每个 rank 都要读更多的 tensor。DeepInfer 因为事先算好了 _local_expert_ids，可以按“本地物理槽位”精确地只读需要的那几十个逻辑专家（包括冗余的复制），所以在“每个 rank 读多少”这一项上是更省的。

vLLM 的 safetensors_weights_iterator 还有一个很实用的细节：它根据文件系统类型与内存是否够用，决定是否启用并行预读（prefetch），在 NFS 上默认打开。这个设计在 DeepInfer 里体现为 _TensorReader 的“按区间显式读”和 row_chunk_bytes 的分块，而不是多线程预读。两条路线都在试图解决同一个问题：不要让 loader 成为 GPU 等待的瓶颈。

加载后的“运行时适配”

DeepseekForCausalLM.__init__(model, cfg) 是在 from_model_cfg(gpt, model_cfg.gpt) 里被调用的，发生在装载之后。它做几件事：

• 把 gpt.module.module[: n_layer+1] 与 head_module 交给 DeepseekModel，让运行时层接管“前向 + mHC 主干 + 跨层共享”。
• ParallelLMHead(cfg.vocab_size, hidden_size, weight=head_module.shared_head.head.weight)：直接引用已装载的 lm head 权重。
• DeepseekMoE 在构造时针对每个 FusedExperts 决定“直接复用打包参数”还是“调用 process_moe_weight 重排”，并且把初始的 physical_to_logical_map 交给 ExpertLoadBalancer。
• EngramRuntime 在 load_model 里被预分配（engram_preallocate），然后在 worker 初始化时 initialize()：把 CPU/GPU 上的表写入 DeepEP userbuffer，随后释放原始存储。

这一段的意义在于：装载层的输出不是“最终形态”，而是“运行时可以直接接管的形态”。例如，如果 _load_expert_params 把某个槽位装错了（比如本应是逻辑专家 371，却装了 0），DeepseekForCausalLM 在构造时是发现不了的——它只看形状和 dtype。错误会在第一次 forward 时以“路由到专家 371 但拿到专家 0 的权重”的方式，表现为奇怪的输出质量下降，而不是崩溃。这也是为什么 _local_expert_ids 要与 ExpertLoadBalancer 使用同一个初始映射函数：只有两者一致，正确的顺序才能被保证。