config_converter.py — HF 配置到 mcore 配置的转换

文件路径

verl/models/mcore/config_converter.py

文件概述

将 HuggingFace 的 PretrainedConfig 转换为 Megatron-Core 的 TransformerConfig。不同模型架构（Dense、MoE、MLA）需要不同的转换逻辑，因此提供了多个转换函数。

关键代码讲解

基础配置构建

def _get_base_transformer_config(hf_config, dtype, **override_kwargs):
    base_config = {
        "num_layers": hf_config.num_hidden_layers,
        "hidden_size": hf_config.hidden_size,
        "num_attention_heads": hf_config.num_attention_heads,
        "num_query_groups": hf_config.num_key_value_heads,
        "ffn_hidden_size": hf_config.intermediate_size,
        # 并行配置（从当前进程组获取）
        "tensor_model_parallel_size": mpu.get_tensor_model_parallel_world_size(),
        "pipeline_model_parallel_size": mpu.get_pipeline_model_parallel_world_size(),
        "expert_model_parallel_size": mpu.get_expert_model_parallel_world_size(),
        "context_parallel_size": mpu.get_context_parallel_world_size(),
        "sequence_parallel": mpu.get_tensor_model_parallel_world_size() > 1,
        # 通用设置
        "activation_func": F.silu,
        "normalization": "RMSNorm",
        "gated_linear_unit": True,
    }
    base_config.update(override_kwargs)
    return base_config

关键理解：并行配置不是手动指定的，而是从已初始化的 Megatron 进程组中自动获取。

Dense 模型转换（LLaMA / Qwen2 / Qwen3）

def hf_to_mcore_config_dense(hf_config, dtype, **override_kwargs):
    qkv_bias = True if "Qwen2" in hf_config.architectures[0] else False
    qk_layernorm = True if "Qwen3" in hf_config.architectures[0] else False
    args = _get_base_transformer_config(
        hf_config, dtype,
        add_bias_linear=False,
        add_qkv_bias=qkv_bias,     # Qwen2 QKV 有 bias
        qk_layernorm=qk_layernorm,  # Qwen3 有 QK LayerNorm
    )
    return check_and_construct_configs(args, TransformerConfig)

MoE 模型转换（Qwen2 MoE / Mixtral / Qwen3 MoE）

def hf_to_mcore_config_qwen2moe(hf_config, dtype, **override_kwargs):
    args = _get_base_transformer_config(hf_config, dtype,
        moe_ffn_hidden_size=hf_config.moe_intermediate_size,
        moe_router_topk=hf_config.num_experts_per_tok,
        num_moe_experts=hf_config.num_experts,
        moe_shared_expert_intermediate_size=hf_config.shared_expert_intermediate_size,
        moe_router_load_balancing_type="none",  # RL 训练中关闭 aux loss
        moe_grouped_gemm=True,
    )

注意：moe_router_load_balancing_type="none" -- 在 RL 训练中关闭 MoE 的辅助平衡损失，因为它会影响 PPO 的性能。

MLA 模型转换（DeepSeek-V3）

def hf_to_mcore_config_dpskv3(hf_config, dtype, **override_kwargs):
    from megatron.core.transformer import MLATransformerConfig
    args = _get_mla_transformer_config(hf_config, mla_rope_config, dtype,
        q_lora_rank=hf_config.q_lora_rank,
        kv_lora_rank=hf_config.kv_lora_rank,
        qk_head_dim=hf_config.qk_nope_head_dim,
        qk_pos_emb_head_dim=hf_config.qk_rope_head_dim,
        v_head_dim=hf_config.v_head_dim,
        moe_router_score_function="sigmoid",  # DeepSeek-V3 使用 sigmoid
    )
    return check_and_construct_configs(args, MLATransformerConfig)

版本兼容检查

def check_and_construct_configs(original_config, cls):
    removed_keys = []
    for key in original_config.keys():
        if not hasattr(cls, key):
            removed_keys.append(key)
    # 自动移除当前 mcore 版本不支持的参数
    for key in removed_keys:
        original_config.pop(key)
    return cls(**original_config)

核心函数列表

函数名	适用模型
_get_base_transformer_config()	所有模型的基础配置
hf_to_mcore_config_dense()	LLaMA, Qwen2, Qwen3
hf_to_mcore_config_qwen2moe()	Qwen2 MoE
hf_to_mcore_config_mixtral()	Mixtral
hf_to_mcore_config_qwen3moe()	Qwen3 MoE
hf_to_mcore_config_dpskv3()	DeepSeek-V3 (MLA)
hf_to_mcore_config_qwen2_5_vl()	Qwen2.5-VL

与其他模块的关系

• 被 registry.py 的 hf_to_mcore_config() 调用
• 输出的 TransformerConfig 被 model_initializer.py 用于创建模型

小结

这个文件是 HF 到 mcore 的"翻译层"。不同模型架构的配置差异（如 MoE 参数、MLA 参数、bias 设置等）都在这里处理。它也负责版本兼容性检查，确保新版配置参数在旧版 mcore 上不会报错。