vLLM 源码完全拆解（二十）：权重装载——safetensors 分片、TP 切分与量化层的参数清单

线程化装载与算子预取

除「文件级」的读法差异之外，vLLM 还有一个「线程化」选项：model_loader_extra_config={"enable_multithread_load": True, "num_threads": N}。此时 multi_thread_safetensors_weights_iterator / multi_thread_pt_weights_iterator 用线程池并发读多个分片，按文件顺序产出，保证同一文件内的名字顺序不变。它和 prefetch 的区别在于：prefetch 只把数据推进 page cache，真正的解析仍然由主线程按需触发；多线程则是把解析（包括 safetensors 解析和 .pt 反序列化）也放到工作线程，主线程只负责消费。

但线程化装载与 safetensors_load_strategy 有互斥条件：

1
if extra_config.get("enable_multithread_load") and (load_config.safetensors_load_strategy not in (None, "lazy")):
2
    raise ValueError(
3
        "enable_multithread_load does not support "
4
        f"safetensors_load_strategy={load_config.safetensors_load_strategy!r}; the multi-thread "
5
        "loader only implements the default lazy strategy."
6
    )

原因很实在：多线程迭代器只实现了默认的 lazy 读法，如果用户同时要求 eager，静默忽略会比报错更危险——用户以为得到了 eager 的性能特征，实际上得到的是另一个。vLLM 选择显式拒绝。

safetensors_weights_iterator 的签名里还有一个 local_expert_ids 参数，这属于 MoE 专家并行场景的读盘优化：在 _init_ep_weight_filter 里，当模型是 MoE、开启了 EP、且开启了 enable_ep_weight_filter，装载器会提前计算当前 rank 应该持有哪些逻辑专家，然后迭代器在读出张量之前就按名字跳过非本地专家。MoE 模型的权重里专家部分往往占大头，在 EP=64 时每个 rank 只有其中几十分之一需要，如果不跳过，读盘 I/O 会放大一个数量级。

这里有一个必须跳过的情形：开启了 EPLB（专家负载均衡）时，冗余专家槽位可能映射到默认分区里属于其它 rank 的逻辑专家，装载器需要看到所有逻辑专家才能填充冗余槽，所以 enable_eplb 为真时直接放弃权重过滤。

另外，safetensors_weights_iterator 返回之前还有两处过滤逻辑挂在 Source 上：

• is_unused_weight：模型自己声明的「这个 checkpoint 名字用不上」的谓词，用于跳过只包含未使用权重的分片。典型情形是某些 HF checkpoint 里保留的旋转位置编码缓存、旧训练框架写入的多余张量。
• mm_encoder_only_lm_prefixes：多模态模型在 --mm-encoder-only 模式下只需要编码器，纯语言模型部分的分片可以整片跳过。前缀从模型的 _language_model_names 推导，经过 mapper 映射，避免对 Molmo/Phi-4-MM 这类「编码器和语言模型共享 HF 根」的模型误删。

这两个过滤都在读盘之前完成，针对的都是「读了也用不上」的字节。

WeightsMapper：五类映射

WeightsMapper 支持五类规则，按固定顺序应用：

Qwen2 的 hf_to_vllm_mapper 是 stacked 规则最清楚的例子：

1
hf_to_vllm_mapper = WeightsMapper(
2
    orig_to_new_stacked={
3
        ".q_proj": (".qkv_proj", "q"),
4
        ".k_proj": (".qkv_proj", "k"),
5
        ".v_proj": (".qkv_proj", "v"),
6
        ".gate_proj": (".gate_up_proj", 0),
7
        ".up_proj": (".gate_up_proj", 1),
8
    }
9
)

apply() 把 q_proj 改名为 qkv_proj，并在产出的张量对象上挂一个 shard_id="q" 属性。后面 QKVParallelLinear.weight_loader 会读这个属性，决定这个张量应该写进融合参数的 q/k/v 哪一段。gate_proj 和 up_proj 则用整数 0/1 标识 gate_up_proj 的两个逻辑分片。这个设计把「名字映射」和「融合层切片」解耦了：映射器只负责告诉下游「这是第几个逻辑分片」，怎么切由线性层自己决定。

get_rename_mapper() 是同一套映射的「只保留改名」变体：去掉 stacked 规则和映射到 None 的规则。它服务于那些只需要按名字找模块、不需要装权重的消费者，比如 LoRA 名字解析和量化配置里的 quantized_layers 列表。这个细节很关键：量化配置里写的是 HF 名字，get_quant_method(layer, prefix) 收到的是 vLLM 名字，必须用「只改名、不融合」的映射把前者翻译成后者；如果用完整映射，q_proj 会被改写为 qkv_proj，量化配置就找不到原来的层了。

绑定词嵌入与别名参数

tied word embedding 让 lm_head.weight 和 model.embed_tokens.weight 指向同一个 nn.Parameter。如果 checkpoint 里两个名字都存在，按名字逐个加载会把同一块存储写两遍；如果只存在一个，另一个名字会找不到宿主。

AutoWeightsLoader 的做法是：初始化时用 _get_tied_embedding_params(module) 找出所有别名关系，得到 aliased_params: alias → canonical。加载时 _filter_skipped 把别名张量直接丢掉，只保留 canonical 名字；加载结束后 _check_skipped_aliases 检查 canonical 名字是否真的 loaded 过，如果没有，说明这个共享权重根本没被初始化，直接报错。这比「静默地留下一个未初始化张量」安全得多。

maybe_retie_word_embeddings 则在装载后的 process_weights_after_loading 里再处理一次：有些 checkpoint 同时存了 lm_head.weight 和 embed_tokens.weight，两者数值相同但占了两份显存；函数会把它们重新绑定，释放重复的那一份。对 7B 级模型，词表 15 万、hidden 4096，一份 BF16 词嵌入就是 1.2GB 左右，能省则省。

模块级 load_weights 与融合层

MergedColumnParallelLinear.load_weights 是一个模块级实现的典型：

1
def load_weights(self, weights):
2
    for name, loaded_weight in weights:
3
        shard_id = getattr(loaded_weight, "shard_id", None)
4
        self.validate_shard_id(shard_id)
5
        ...
6
        param.weight_loader(param, loaded_weight, shard_id)
7
        yield name

它先把 shard_id 从张量属性上取下来并校验合法性（整数必须在 [0, len(output_sizes))，元组必须连续），再把张量和 shard_id 一起交给参数的 weight_loader。QKVParallelLinear 的版本类似，只是 shard_id 是 "q"/"k"/"v"。

这里有一个设计上的取舍：为什么不让 AutoWeightsLoader 直接调用 param.weight_loader(param, tensor)，而要让线性层再包一层？因为融合层的 weight_loader 需要知道「这个张量是第几个逻辑分片」和「这个融合参数在磁盘上是否已经融合」。后者对应 loaded_shard_id is None 的分支：Phi-3 一类模型的 gate_up_proj 在 checkpoint 里已经是融合的，此时不需要拆 shard，直接按整体形状拷贝即可。这个信息只有线性层自己知道，通用的参数加载器无法判断。

列并行：切输出维

ColumnParallelLinear 计算 $Y = XA + b$，其中 $A$ 的形状是 [output_size, input_size]（PyTorch 的 Linear 习惯）。列并行把输出维切开：

rank $r$ 只持有 $A_r$，形状 [output_size / p, input_size]。因此加载时沿 output_dim=0 取第 $r$ 段：

1
shard_size = param_data.shape[output_dim]
2
start_idx = self.tp_rank * shard_size
3
loaded_weight = loaded_weight.narrow(output_dim, start_idx, shard_size)
4
param_data.copy_(loaded_weight)

注意 shard_size 是从参数的形状推出来的，而不是从 checkpoint 张量推出来的。这是一个防御性设计：如果 checkpoint 的实际输出维和模型配置不一致，narrow 会先因为越界报错，而不是悄悄装进错误的位置。

行并行：切输入维

RowParallelLinear 的输入来自上一层的输出，已经按最后一维切分。它沿输入维切权重：

rank $r$ 持有 [output_size, input_size / p]，加载时沿 input_dim=1 取第 $r$ 段。前向结束后需要一次 all-reduce 把各 rank 的部分和加起来；bias 只在 rank 0 加，避免重复。这个「bias 只加一次」的细节在 RowParallelLinear.forward 里写得很直白：

1
bias_ = None if (self.tp_rank > 0 or self.skip_bias_add) else self.bias
2
output_parallel = self.quant_method.apply(self, input_parallel, bias_)
3
if self.reduce_results and self.tp_size > 1:
4
    output = tensor_model_parallel_all_reduce(output_parallel)

融合列并行：按 shard_id 定位逻辑分片

MergedColumnParallelLinear 把多个逻辑矩阵沿输出维拼成一个参数。比如 MLP 的 gate_up_proj 由 gate_proj 和 up_proj 拼接，output_sizes=[intermediate, intermediate]，融合后的参数形状是 [2 * intermediate / p, hidden]。

加载单个逻辑分片时，先算它在未切分融合矩阵里的偏移，再除以 TP：

1
shard_offset = sum(self.output_sizes[:shard_id])
2
shard_size = self.output_sizes[shard_id]
3
shard_offset //= self.tp_size
4
shard_size //= self.tp_size
5
param.load_merged_column_weight(
6
    loaded_weight=loaded_weight,
7
    shard_id=shard_id,
8
    shard_offset=shard_offset,
9
    shard_size=shard_size,
10
)

参数侧的 load_merged_column_weight 在 param.data 上按 shard_offset/shard_size 取出目标段，再把 checkpoint 张量按 tp_rank * shard_size 取对应段，两者形状一致后 copy_。这里的两次 narrow 分别对应「融合矩阵里的逻辑分片位置」和「该逻辑分片在 TP 下的 rank 位置」，是最容易写错的地方之一。

QKV 并行：按 head 切，K/V 可能复制

QKVParallelLinear 是融合列并行的特例，但它的切分单位不是任意行，而是 head。设总 query head 数为 $H$，KV head 数为 $H_{kv}$，head_dim 为 $d$，则融合权重的输出维依次是：

• Q：$H \cdot d$
• K：$H_{kv} \cdot d$
• V：$H_{kv} \cdot d_v$（多数模型 $d_v=d$）

rank $r$ 的偏移分别是：

其中 $n_{rep}$ 是 KV head 的复制倍数。当 $H_{kv} \ge p$ 时，KV head 可以按 rank 整除，$n_{rep}=1$；当 $H_{kv} < p$ 时，一个 KV head 要服务多个 query head 所在的 rank，必须复制，$n_{rep} = p / H_{kv}$。代码里对应：

1
if loaded_shard_id == "q":
2
    shard_rank = self.tp_rank
3
else:
4
    shard_rank = self.tp_rank // self.num_kv_head_replicas
5
start_idx = shard_rank * shard_size

举个具体例子：Qwen2-7B 有 28 个 query head、4 个 KV head，head_dim 128。TP=4 时，每个 rank 分到 7 个 query head；KV head 只有 4 个，正好每个 rank 1 个，$n_{rep}=1$。TP=8 时，query head 每个 rank 3.5 个——不整除，模型根本不允许这种 TP 配置；如果强行配置，构造期的 assert self.total_num_heads % tp_size == 0 会先失败。KV head 4 个、TP=8 时，$n_{rep}=2$，rank 0 和 1 都拿第 0 个 KV head，rank 2 和 3 拿第 1 个，以此类推。这个复制是有意的：每个 rank 上的 query head 需要看到对应的 K/V，复制一份比跨 rank 通信更便宜。

MLA 是另一条路。DeepSeek 的 MLA 把 K/V 压成一个 latent 向量，KV cache 里每个 token 只存一份 latent，不再有「KV head 数」的概念；kv_b_proj 这类上投影仍然按线性层规则切，但 cache 的切分逻辑由注意力后端单独处理。MLA 的低秩压缩和矩阵吸收可参考站内 MLA 完全拆解；TensorRT-LLM 里 MLA 为什么不能照搬普通 TP 切法，可参考 注意力层的张量并行。

参数对象如何记住切法

切分规则不是写在 weight_loader 里的硬编码，而是参数对象上的元数据。BasevLLMParameter 在构造时接收一个 weight_loader 回调，并记录自己的 tp_rank/tp_size。ModelWeightParameter 同时继承 _ColumnvLLMParameter 和 RowvLLMParameter，因此既有 output_dim 又有 input_dim；具体走哪个 loader，由线性层在 create_weights 时传进来的回调决定。

PerTensorScaleParameter 是另一类：它存的是「每个逻辑矩阵一个 scale」，形状是 [num_logical_matrices]。对 QKV 融合层，一个 per-tensor FP8 checkpoint 会给出 q/k/v 三个标量 scale；模型的参数却是一个长度 3 的数组。load_qkv_weight 会把标量写进 shard_id 对应的槽位；如果 checkpoint 已经把 qkv 融合、只给一个 scale，则把同一个值填满三个槽位，保证后续 .max() 之类的归约仍然有正确的形状。

PackedvLLMParameter 处理 4-bit 打包权重。Marlin/AWQ 一类格式把两个 4-bit 值塞进一个字节，参数的实际形状是 [output, input / packed_factor]。切分时偏移和大小都要先除以 packed_factor，还要按 Marlin 的 tile size 对齐：

1
def adjust_shard_indexes_for_packing(self, shard_size, shard_offset):
2
    return (
3
        shard_size // self.packed_factor + self.marlin_tile_size - 1,
4
        shard_offset // self.packed_factor,
5
    )

向上取整是为了覆盖边界 tile：一个 tile 可能横跨两个逻辑分片，不能简单截断。

BlockQuantScaleParameter 则处理块量化（如 FP8 的 128×128 block）。weight 按块切，scale 的张量形状是 [ceil(out/128), ceil(in/128)]；如果输出维切分点不在 128 的边界上，scale 的切片也要包含被切开的那个块。adjust_block_scale_shard(weight_block_size, shard_size, shard_offset) 就是做这件事。FP8 block 量化模型在 TP 下出现 shape mismatch，十有八九是这里没有对齐 block 边界。

v1 与 v2 两套 loader

vLLM 同时保留了两套参数加载路径。老的 weight_loader 直接操作 param.data，用 narrow + copy_；新的 weight_loader_v2 把切分逻辑下沉到 BasevLLMParameter.load_column_parallel_weight / load_row_parallel_weight / load_qkv_weight 等方法里，线性层只负责算偏移和 shard_id。

是否走 v2 由 WEIGHT_LOADER_V2_SUPPORTED 名单决定：

1
weight_loader = (
2
    self.weight_loader_v2
3
    if quant_method.__class__.__name__ in WEIGHT_LOADER_V2_SUPPORTED
4
    else self.weight_loader
5
)

名单里是 UnquantizedLinearMethod、Fp8LinearMethod、AutoAWQLinearMethod、AutoGPTQLinearMethod、CompressedTensorsLinearMethod 等常用方法。v2 的好处是把「怎么切」和「切到哪」分开：线性层只算逻辑分片的偏移，参数类自己知道 packing、block scale、Marlin tile 等细节；代价是两套路径并存，阅读源码时要先确认当前方法走的是哪一套。自定义量化插件如果没注册进名单，会退回 v1，这时参数类上的 packed/block 元数据可能不会被正确处理——这是写第三方量化后端时的一个常见坑。

替换参数后的 TP 状态

process_weights_after_loading 可能用 replace_parameter 换掉一个 Parameter。新参数由 BasevLLMParameter.__init__ 创建时，tp_rank 被盖成全局 rank；但线性层可能设置了 disable_tp=True，此时层内的 tp_rank 是 0、tp_size 是 1。如果之后还要 reload 权重（RL weight refit 或权重热更新），用全局 rank 去切一个复制权重就会越界。

vLLM 的修法是 update_param_tp_status()：在构造末尾和后处理之后各调用一次，把每个 BasevLLMParameter 的 tp_rank/tp_size 重新对齐到层自己的值。这个函数看起来只是两行赋值，但它解决的是「参数被替换后元数据失配」这一整类问题。

为什么量化方法必须参与「建壳」

可以换一个角度理解这条设计。假设装载器先建一个普通的 BF16 模型，装完再量化，会有什么问题？

• 显存峰值翻倍。671B 的 BF16 权重 1.3TB，量化前必须先放下一份 BF16 再转换成 FP8；多卡也一样，每个 rank 都要额外扛一份。
• 很多量化格式的参数字形状和 BF16 不同。4-bit 打包后 shape 减半，Marlin 还有额外的 tile 排布；不可能先按 BF16 形状建好再「改形状」。
• 部分量化方法必须知道「这是第几个逻辑分片」才能决定 scale 的形状。QKV 融合层如果先建了一个大 weight，再拆成三个 scale 槽位，信息已经丢了。

所以量化方法参与 create_weights 是必然的。它让参数清单、参数形状、参数上的 loader 元数据一次性在构造期确定下来；装载期只是把 checkpoint 张量按这些元数据切进去。这个分界点很清晰：构造期决定「我是谁」，装载期决定「我填哪一块」。

在线量化：uses_meta_device

vLLM 还支持「在线量化」：checkpoint 是 BF16（或 FP16），启动时即时量化成 FP8/INT8。这和「离线量化」共享同一套壳和 loader，但有一个特殊标志：

1
class QuantizeMethodBase(ABC):
2
    uses_meta_device: bool = False
3
    """
4
    Whether this method creates weights on meta device for online quantization.
5
    When True, weights are created on meta device and quantized layer-wise
6
    in process_weights_after_loading, reducing peak memory during loading.
7
    """

如果在线量化方法把参数建在 meta 设备上（只有形状元数据、没有真实存储），那么装载阶段就不会真的把 BF16 权重写进显存；量化的实际发生被推迟到后处理阶段，按层进行，峰值显存只有「当前层 BF16 + 当前层 FP8」，而不是「全模型 BF16 + 全模型 FP8」。

BaseModelLoader.load_model 里的这个分支就是为它准备的：

1
if _has_online_quant(model):
2
    finalize_layerwise_processing(model, model_config)

_has_online_quant 遍历所有模块，只要有一个 quant_method.uses_meta_device 为真就走逐层后处理。log_online_quantization_time 会打印在线量化总耗时，log_online_quantization 会打印被量化的层数和类型。

这个设计在 process_weights_after_loading 里还有配套：device_loading_context(module, target_device) 把 CPU 上的参数临时搬到设备上处理、处理完再搬回并以 pinned memory 保留，用于 CPU offload 场景；而 requires_device_loading=False 的方法（比如只在 CPU 上做 scale 校验的 PLE 量化）跳过这次搬运。

权重装载的严格性检查

DefaultModelLoader.load_weights 末尾有一个可选的 track_weights_loading，用来检查「模型声明了哪些参数、checkpoint 实际给了哪些」，差集不为空就抛异常：

1
weights_not_loaded = weights_to_load - loaded_weights
2
if weights_not_loaded:
3
    raise ValueError("Following weights were not initialized from checkpoint: ...")

默认只在非量化模型上开启：model_config.quantization is None and loaded_weights is not None。原因是量化模型的参数清单里有很多 checkpoint 本来就不带的东西——在线量化 scale、KV cache scale（BaseKVCacheMethod 在后处理阶段给默认值）、对称 GPTQ 的空占位 qzeros、量化配置自己构造的 input_scale_ub。如果对这些参数逐一要求「必须从 checkpoint 加载」，几乎所有量化模型都会失败。

但即使是量化模型，真正的权重参数也不应该被放过。代码的豁免逻辑很细：

1
if (quantized and not has_online_quant
2
        and not isinstance(quant_method, BaseKVCacheMethod)
3
        and param.numel() > 0
4
        and param_name.rsplit(".", 1)[-1] not in _CONFIG_BUILT_PARAMS):
5
    continue

只有「在线量化参数」「KV cache scale」「空占位」「配置构造参数」这四类可以豁免；其它量化参数，包括 weight、weight_scale、qzeros、scales，全部要求被加载过。这是一个务实的严格性：检查能真正抓到「某个 adapter 的 scale 漏了」「某个 expert 的 weight 没读到」这类致命错误，又不至于被格式自带的非权重张量误伤。

可以用 model_loader_extra_config={"enable_weights_track": False} 关掉这项检查，通常用于自定义模型或实验性 checkpoint 调试。

FP8 的后处理：转置、合并、替换

以 Fp8LinearMethod.process_weights_after_loading 为例，它有三条路径。

Marlin 路径。当 GPU 不支持原生 FP8、但支持 Marlin 时，use_marlin=True。非 block 量化的情况下，权重先转置成 (K, N)：

1
if not self.block_quant:
2
    replace_parameter(layer, "weight", layer.weight.t())

然后调用 self.fp8_linear.process_weights_after_loading(layer)，由 Marlin kernel 自己做重排。

非 Marlin、非 block 路径。checkpoint 是 per-tensor FP8 时，融合层有 N 个 scale（N = logical_widths 的长度）。process_fp8_weight_tensor_strategy 会把逻辑分片重新量化成「整个权重一个 scale」：

1
weight, weight_scale, input_scale = process_fp8_weight_tensor_strategy(
2
    weight, weight_scale, layer.logical_widths,
3
    getattr(layer, "input_scale", None),
4
)
5
if self.act_q_static:
6
    input_scale = input_scale.max()
7
replace_parameter(layer, "weight", weight.data)
8
layer.processed_weight_dims = (0, 1)
9
replace_parameter(layer, "weight_scale", weight_scale.data)

这里为什么需要「重新量化」而不是简单取 max？因为不同逻辑分片的 scale 不同，直接拼在一起会让某些分片的数值范围溢出或精度损失。正确做法是把每个分片先反量化成 FP32/BF16，再用一个统一的 scale 重新量化。process_fp8_weight_tensor_strategy 做的就是这件事。代价是启动时多一遍读写，收益是 kernel 只需要一个 scale，访存和指令都更简单。

block FP8 路径。权重和 weight_scale_inv 保持 block 布局，不需要合并 scale；但要做 block 形状校验和可能的 FNUZ 转换。layer.weight_block_size 在 create_weights 时已经设好，后处理只需确认 kernel 能接受这个 block 形状。

replace_parameter 这个动作看起来只是「把 layer.weight 指向新张量」，实际上做了三件事：保留原参数的 weight_loader 和 TP 元数据、用新张量替换 Parameter 对象、把旧张量从模块的 _parameters 里摘掉。如果直接用 layer.weight.data = new_tensor，shape 可能变，Parameter 的元数据会失配；replace_parameter 是更安全的写法。

MoE 的 FP8 后处理

Fp8MoEMethod.process_weights_after_loading 走的是另一套逻辑，因为 MoE 的参数是「按专家堆叠」的：

1
w13 = layer.w13_weight
2
w2 = layer.w2_weight
3
w13_scale = getattr(layer, f"w13_{self.weight_scale_name}")
4
w2_scale = getattr(layer, f"w2_{self.weight_scale_name}")
5
...
6
if current_platform.is_fp8_fnuz():
7
    w13, w13_scale, w13_input_scale = normalize_e4m3fn_to_e4m3fnuz(...)

• w13 是 gate+up 的融合权重，形状 [num_local_experts, 2*intermediate, hidden]；w2 是 down 投影，[num_local_experts, hidden, intermediate]。
• per-tensor kernel 要求每个专家一个 scale，或者整体一个 scale；代码会按 kernel 的要求做 .max() 合并。
• FNUZ 转换只对 AMD 平台生效，把 NVIDIA 的 e4m3fn 数值映射到 AMD 的 e4m3fnuz。这不是简单的 dtype cast：两种格式的指数偏置和 NaN 表示不同，normalize_e4m3fn_to_e4m3fnuz 会同时调整 scale，保证反量化后的数值不变。
• block 量化时，w13_scale/w2_scale 的形状是 [num_local_experts, ceil(...), ceil(...)]，后处理要检查每个专家的 block 形状一致，并可能把 scale 重排成 kernel 期望的 [num_local_experts, ...] 连续布局。

MoE 的后处理还有一个额外约束：专家并行下每个 rank 只有一部分专家，所以后处理只能看到本地专家。scale 的合并、转换都必须按本地专家做，不能假设全局专家数量。这也是为什么 MoE 的 create_weights 接收的是 num_experts（全局）和 intermediate_size_per_partition（本地），而不是一个统一的 output_partition_sizes。

在线量化的逐层处理

在线量化的后处理是另一个量级的工作：它不是「整理已有权重」，而是「把 BF16 权重变成量化权重」。uses_meta_device=True 的方法在 create_weights 时只建形状、不分配真实存储；load_weights 阶段把 BF16 权重写进一个临时的 meta 参数（实际是延迟物化），到 process_weights_after_loading 才逐层量化。

finalize_layerwise_processing(model, model_config) 是这条路径的收尾。它按层遍历，对每一层：

1. 把 BF16 权重物化到 GPU（如果之前在 meta/CPU 上）。
2. 计算 scale（per-tensor 用最大值，per-block 用 block 最大值）。
3. 量化成 FP8/INT8，写入正式的量化参数。
4. 释放 BF16 临时权重。

这样峰值显存大约是「一层 BF16 + 一层量化权重 + 少量临时」，而不是「全模型 BF16 + 全模型量化权重」。对 671B 模型，这个差别是几百 GB 级别的。代价是启动时间变长：每层都要做一遍 reduce/quantize，而且不能像离线量化那样用更复杂的校准算法（在线量化通常只做 min-max 或 percentile，不做 GPTQ/AWQ 那种重构）。

supports_pre_processed_weights 则服务于另一条路径：权重缓存守护进程（vllm preload + --load-format ipc_cache）已经把后处理做完，权重以 CUDA IPC 共享内存的形式交给引擎。此时 is_weights_pre_processed() 为真，量化方法的 process_weights_after_loading 必须跳过所有张量变换，只做 kernel 初始化；如果某个方法没声明支持，驱动会直接报错，而不是让它重复处理一遍。

权重本身占多少

每个参数的字节数由 dtype 决定：

以 DeepSeek-V3/R1 级别的 671B 总参数为例（MoE 激活参数远小于总参数，但装载要装全部专家）：

• BF16：$671 \times 10^9 \times 2 \approx 1.34$ TB
• FP8：约 671 GB
• INT4：约 336 GB，加上 scale/zero point 通常再多 3%–6%

单卡 H100 80GB 显然放不下 FP8 的 671B；TP=8 的 8 卡节点总显存 640GB，仍然小于 671GB，连权重都装不下，更不用说 KV cache 和激活。现实部署要么用 16 卡以上、要么用更激进的量化（FP4/INT4）、要么把专家卸载到 CPU/SSD。这个算术不复杂，但它决定了很多「为什么这个模型必须这么部署」的问题。

每卡的权重字节是总量除以并行度，但不是所有参数都按 TP 切：embedding 和 LM head 可能按词表切，norm 是复制的，MoE 专家按 EP 切。所以「671GB / 16 = 42GB」只是粗略下界，实际每卡还要加复制参数和对齐开销。

装载时间

理论下界是「总字节 / 有效带宽」：

其中 $\eta$ 是有效带宽利用率。几个参考值：

• 本地 NVMe：顺序读 7 GB/s 左右，671GB 需要约 96 秒；如果走 mmap 随机读，实际可能更慢。
• 25GbE/100GbE 网络存储：25 GB/s 对应约 27 秒；但网络文件系统的元数据操作和随机读会显著拉低 $\eta$。
• PCIe Gen5 x16：理论 64 GB/s，实际 H2D 拷贝常见 20–40 GB/s；671GB 约 17–34 秒。

这些数字只算「搬字节」，没算反序列化、名字映射、TP 切片、后处理。真实启动时间通常是理论值的 1.5–3 倍。这也是为什么 ServerlessLLM 一类工作要专门优化 checkpoint 读取，为什么 prefetch/eager/多线程装载值得做成可配置项。

峰值显存的四个来源

1. 模型壳的空参数。with target_device: 让 torch.empty 直接在 GPU 上分配。对 BF16 模型，这一步就占了全部权重的显存；如果显存不够，会在建壳阶段直接 OOM，而不是等到装载。
2. 单个 checkpoint 张量的临时副本。f.get_tensor(name) 返回一个 CPU 张量（mmap 或拷贝），然后 copy_ 到 GPU 参数。生成器一次只持有一个张量，所以临时峰值大致是「最大的单个张量」，不是整个分片。但注意：如果某个张量特别大（比如 15 万词表的 embedding，BF16 约 1.2GB），它会短暂地同时存在于 CPU 和 GPU。
3. 后处理的临时张量。FP8 转置会创建一个同形状的新张量；process_fp8_weight_tensor_strategy 会先反量化再量化，临时量可能是权重的 2–4 倍（FP32 中间态）。replace_parameter 之后旧张量才会被释放。逐层处理把这份峰值限制在「一层」，但 MoE 的一层可能包含几十个专家，仍然不小。
4. 量化 scale 和 zero point。per-tensor 可以忽略；block 量化在 block 很细时（如 32×32）scale 可能占到权重的 1/32；4-bit 的 group scale 通常每 32/64 个权重一个 FP16 scale，额外 3%–6%。

gc.collect() + torch.accelerator.empty_cache() 在 load_weights 之后和后处理之后各调用一次，目的就是把这四类临时量尽量还给驱动。Python 的引用计数对循环引用无效，gc.collect() 处理的是后者；empty_cache 处理的是 caching allocator 的空闲块。两者都不能解决「真实峰值超过显存」的问题，只能减少「峰值过后仍然占着」的浪费。

在线量化把峰值压到一层

离线量化的峰值是「BF16 全模型 + 量化全模型」；在线量化用 meta device 把 BF16 权重延迟到逐层处理，峰值变成「一层 BF16 + 一层量化 + 临时」。对 671B：

• 离线：1.34TB（BF16）+ 671GB（FP8）= 约 2TB 的瞬时占用，必须分布在足够多的卡上。
• 在线：每层 BF16 权重可能是几十 GB（MoE 层），加上量化副本，单卡峰值可能只有 100GB 量级；16 卡就能跑起来。

代价是启动时间增加，以及量化算法更简单。vLLM 的在线 FP8 通常用 per-tensor 动态/静态 scale，不做 GPTQ 的 Hessian 重构；精度和离线 GPTQ/AWQ 有差距，但胜在「拿到任何 BF16 checkpoint 都能直接跑」。

与逐层流式装载的关系

Progressive Weight Loading 的思路是把「装载」和「推理」重叠：第 0 层装好就能开始处理请求，后续层在后台继续装。vLLM 当前的默认路径是「全部装完再服务」，原因有三：

• 调度器需要知道完整的显存预算才能分配 KV cache；逐层装载会让可用显存动态变化，调度逻辑复杂。
• 量化后处理需要跨层一致性（比如 MLA 的延迟注意力层），逐层加载会打乱顺序。
• 多卡场景下，各 rank 的装载进度必须同步，否则集合通信会死锁。

但 vLLM 已经有一些「部分重叠」的机制：DummyModelLoader 用于 profiling 阶段快速建壳；prefetch 在后台把文件推进 page cache；在线量化把 BF16 权重的生命周期压到一层。这些都是在不改变「服务前必须装完」的前提下，尽量把等待时间藏起来。

「Following weights were not initialized from checkpoint」

这是 track_weights_loading 抛出的差集错误。排查顺序：

1. 看列出来的名字。如果全是量化张量（weight_scale、qzeros、input_scale），说明这个 checkpoint 不是该量化方法期望的格式，或者该方法的豁免表没写全。这是 vLLM 侧的问题，通常需要在 track_weights_loading 里补豁免，而不是改 checkpoint。
2. 如果列出来的是 model.layers.N.xxx 形式的权重，说明某层的 load_weights 没有消费这个张量。多半是名字映射漏了一类（比如某个 adapter 用了不同的前缀），或者模型的 load_weights 提前 return 了。
3. 如果是 lm_head.weight 或 embed_tokens.weight，检查 tied embedding 的别名逻辑：canonical 名字是否在 checkpoint 里存在？如果 checkpoint 只有 lm_head.weight，而模型把它当别名丢掉了，就会漏装。

「There is no module or parameter named …」

AutoWeightsLoader._load_module 抛出的路由错误。错误信息会列出当前模块下所有可用的参数名，这是最直接的线索。常见原因：

• checkpoint 是旧版 HF 格式，模块名用了 transformer.h.0 而不是 model.layers.0；需要 orig_to_new_prefix 或 orig_to_new_substr 映射。
• 模型融合了模块（qkv_proj），但 checkpoint 名字没有被 stacked 映射覆盖，导致试图把 q_proj 路由到不存在的子模块。
• 量化配置里声明了某个层要量化，但模型按前缀找不到这个层，于是量化方法返回 None，层被建成了 unquantized，checkpoint 里的量化张量无处可放。这个错误信息有时会误导人，因为真正的根因在前面的 get_quant_method(prefix)。

形状不匹配

assert param_data.shape == loaded_weight.shape 失败。按并行类型分：

• 列并行 / 行并行：多半是 checkpoint 的维度顺序和模型预期相反。HF 的 Linear 权重是 (out, in)，但某些转换脚本会存成 (in, out)。检查 output_dim/input_dim 是否设置正确。
• QKV 并行：KV head 数小于 TP 时，num_kv_head_replicas 的计算和 checkpoint 的 KV head 数要一致；如果模型配置写错了 num_key_value_heads，切片会越界。
• block 量化：TP 切点没有对齐 block 边界。adjust_block_scale_shard 只在 BlockQuantScaleParameter 上生效；如果用的是旧的 weight_loader（v1），block scale 的切片可能没有对齐。确认该方法是否在 WEIGHT_LOADER_V2_SUPPORTED 名单里。
• 4-bit packed：packed_factor 和 checkpoint 的打包方式不一致（有的格式把 8 个 4-bit 打包，有的把 2 个打包）。Marlin 的 tile 对齐也会导致形状看起来差几个元素。

FP8 启动后前向结果不对

装载成功了，但推理输出乱码或精度暴跌。常见原因：

• weight_scale_inv 的语义搞反：有些 checkpoint 存的是 scale（乘以权重），有些存的是 scale_inv（除以权重）。vLLM 在 process_weights_after_loading 里统一成 kernel 期望的约定，但如果自定义 kernel 直接读原始参数，就会差一个倒数。
• 融合层 scale 合并错误：per-tensor FP8 的多分片 scale 如果只取了第一个分片的 scale，其它分片的数值会溢出。
• FNUZ 未转换：在 MI300 上加载 NVIDIA 生成的 FP8 checkpoint，没有走 normalize_e4m3fn_to_e4m3fnuz，数值范围不同会导致大量饱和。

OOM 发生在装载而非推理

如果模型「推理时能跑，启动时 OOM」，说明峰值出现在装载或后处理阶段。对策：

• 用 --load-format dummy 先测「仅建壳 + 推理」的显存需求，确认是装载侧的问题。
• 开在线量化，把 BF16 权重生命周期压到一层。
• 逐层后处理时压力太大，检查 release_device_memory_under_pressure 是否生效；某些平台（UMA，如 Grace Hopper）需要更激进地归还内存。
• 临时关掉 enable_weights_track 排除差集检查本身带来的额外集合开销（很小，但能缩小范围）。

排查工具

• VLLM_LOGGING_LEVEL=DEBUG 会打印每个权重加载的 debug 日志，能看到名字、形状、目标参数。
• VLLM_LOG_MODEL_INSPECTION=1 会在建壳后打印完整模型结构，适合确认模块名和参数名。
• load_weights 里的 logger.info_once("Loading weights took %.2f seconds") 和建壳的 Initializing model took %.6f seconds 把装载分成两段计时；后处理的耗时会出现在在线量化的日志里。
• 对单个层，可以写一个小脚本 model.load_weights([(name, tensor)])，单独复现路由问题，不必启动整个引擎。