AReaL megatron-core 依赖升级 API 审计清单upgrade-deps 技能与 API Usage Catalog 实战指南【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaLAReaL 将megatron-core锁定为精确版本当前pyproject.toml与pyproject.vllm.toml均 pin 为megatron-core0.17.0任何版本升级都必须先回答一个问题AReaL 在哪些文件、哪些行调用了哪些megatron.coreAPI新版本的签名变化会不会击穿训练引擎。.agents/skills/upgrade-deps/checklists/megatron-core.md正是为这个问题而生的“API 兼容性审计清单”——它完整记录了 18 个 API 表面函数/类/模块路径在 AReaL 中的真实调用点、导入内容与升级时必须核对的校验项。读完本文你将理解这份清单的结构与每个条目的含义、掌握它在/upgrade-deps工作流中如何驱动自动化审计并能对照 AReaL 源码验证清单中记录的每一次 Megatron 调用。1. 背景upgrade-deps 技能与双清单文件模型这份清单不是孤立文件而是 AReaL 的upgrade-deps技能定义于 .agents/skills/upgrade-deps/SKILL.md中“每个 focused 包一份 API 清单”机制的一部分。技能的工作方式是用户执行/upgrade-deps megatron-core0.17.0或类似命令指定目标版本技能先做Step 0.5 清单结构校验grep 全仓库areal/、tests/、examples/中所有from megatron.core/import megatron.core的导入点与清单的 Affected Files 三层表格比对找出 Missing / Stale / Changed 三类偏差并补全修改 pyproject、uv lock重新锁定Step 6 API 兼容性审计读取清单 frontmatter 中的githubNVIDIA/Megatron-LM与branch_templatecore_r${VERSION}克隆目标版本的上游源码逐条核对 API Usage Catalog 中的每个调用点签名。AReaL 维护两份 pyproject 文件pyproject.tomlSGLang 推理后端锁uv.lock和pyproject.vllm.tomlvLLM 后端锁uv.vllm.lock。megatron-core属于shared作用域——两份文件都要改、两套锁都要重新生成但 Dockerfile 无需变更它通过 Stage 3 的uv pip install自动读取更新后的 pyproject。megatron-core还被划入megatron 升级家族megatron-bridge包裹megatron-core、二者 API 紧耦合升级megatron-core时必须检查megatron-bridge是否需要同步升版否则技能会主动告警。当前 pin 位置可以在此确认pyproject.toml 的[optional-dependencies].megatron中写有megatron-core0.17.0带 Python ≥3.12 / linux / x86_64 的 marker 约束。2. 清单结构YAML frontmatter 与上游锚点megatron-core.md 的 frontmatter 是 Step 6a 克隆上游源码的坐标package: megatron-core github: NVIDIA/Megatron-LM branch_template: core_r${VERSION} upstream_paths: - megatron/core/parallel_state.py - megatron/core/distributed/ - megatron/core/optimizer/ - megatron/core/optimizer_param_scheduler.py - megatron/core/pipeline_parallel/ - megatron/core/transformer/transformer_config.py - megatron/core/transformer/pipeline_parallel_layer_layout.py - megatron/core/dist_checkpointing/ - megatron/core/dist_checkpointing/serialization.py - megatron/core/dist_checkpointing/strategies/fully_parallel.py - megatron/core/fp8_utils.py - megatron/core/models/gpt/ - megatron/core/packed_seq_params.py - megatron/core/models/common/embeddings/rotary_pos_embedding.py - megatron/core/utils.py三个字段各有职责github上游仓库审计时git clone --depth 1 --branch BRANCH的来源branch_templateMegatron-LM 的发布分支命名规则是core_r${VERSION}例如core_r0.17.0而非常见的v${VERSION}tag——这是 Megatron-LM 区别于多数上游项目的特殊约定若写错分支模板克隆会直接失败upstream_paths目标版本下需要逐一打开核对的上游文件路径。注意upstream_paths会在审计后随上游文件移动而更新Step 6e。3. Affected Files三级影响面模型清单把 AReaL 中所有megatron.core使用点分成三层层级决定破坏半径blast radius也决定修复时的优先级顺序engine 层 → model 层 → infra 层 → 测试。Primary引擎层最可能先被击穿文件导入 / 用法areal/engine/megatron_engine.pyparallel_state、tensor_parallel、DDP、finalize_model_grads、OptimizerConfig、get_megatron_optimizer、OptimizerParamScheduler、get_forward_backward_func、TransformerConfig、get_model_configareal/engine/megatron_utils/checkpointer.pydist_checkpointing.save、load、sharded strategies、ShardedObjectareal/engine/megatron_utils/megatron.pyparallel_state、FP8 检测、TransformerConfigareal/engine/megatron_utils/pipeline_parallel.pyTransformerConfig、PipelineParallelLayerLayoutareal/engine/megatron_utils/packed_context_parallel.pyPackedSeqParams、parallel_stateareal/engine/megatron_utils/fp8/tensor_helper.pyfp8_utils.is_float8tensorSecondary模型 / 基础设施层文件导入 / 用法areal/models/mcore/registry.pyGPTModel、DDP、TransformerConfig、parallel_state、AutoConfigareal/models/mcore/bailing_moe.pyMLATransformerConfig、LayerType、ModuleSpec、SelfAttention、AttnMaskType、TransformerLayer、TransformerLayerSubmodules、TransformerBlockSubmodules、apply_rotary_pos_emb、rope_utilsareal/models/mcore/tree_attn/module_megatron.pyTransformerConfig、SelfAttention、AttnMaskType、layer specsareal/models/mcore/lightning_attention.pyparallel_state、apply_rotary_pos_emb、MegatronModule、ModuleSpec、build_moduleareal/models/mcore/bailing_moe_bridge.pyMLATransformerConfig、AttnBackendareal/models/mcore/common.pyTransformerConfigareal/models/mcore/qwen3.pygpt_layer_specs、TransformerConfigTertiary测试与外围文件导入 / 用法areal/infra/workflow_executor.py条件式parallel_stateDP world sizetests/test_estimate_num_params.pyparallel_state、tensor_paralleltests/fp8/engine_utils.pyparallel_statetests/fp8/model_hooks.pyparallel_statetests/fp8/test_fp8_rmsnorm.pyfp8_utils、get_model_configtests/torchrun/run_megatron_engine_distributed.pyparallel_state分层规则定义在 CHECKLIST_MAINTENANCE.md §3.3areal/engine/、areal/experimental/engine/归 Primaryareal/models/、areal/infra/、areal/api/等归 Secondarytests/、examples/、工具脚本归 Tertiary。跨关注点的文件按目录位置而非内容归类。4. API Usage Catalog18 条审计条目逐项拆解Catalog 是清单的核心每个条目记录一个独立 API 表面的上游源路径、AReaL 真实调用点代码、以及升级时必须核对什么。审计时只关注五类破坏模式新增必填参数、删除旧参数、参数改名、返回类型/方法签名变化、模块移动或改名。下面按功能域分组完整继承这 18 个条目。4.1 parallel_state进程组拓扑的入口条目 1–3条目 1megatron.core.parallel_state.initialize_model_parallel—— 这是整个清单中被标记为“最关键”的调用签名一旦变化所有 Megatron 训练全部被阻断。AReaL 在 areal/engine/megatron_engine.py 的create_process_group()中调用清单中记录的行号会随代码演进而刷新以当前源码为准mpu.initialize_model_parallel( tensor_model_parallel_sizeself.parallel_strategy.tensor_parallel_size, pipeline_model_parallel_sizeself.parallel_strategy.pipeline_parallel_size, virtual_pipeline_model_parallel_sizevpp_size if vpp_size 1 else None, use_sharpFalse, ordertp-cp-ep-dp-pp, context_parallel_sizeself.parallel_strategy.context_parallel_size, expert_model_parallel_sizeself.parallel_strategy.expert_parallel_size, expert_tensor_parallel_sizeself.parallel_strategy.expert_tensor_parallel_size, distributed_timeout_minutesint(DIST_GROUP_DEFAULT_TIMEOUT.seconds / 60), )核对要点所有关键字参数是否仍被接受——尤其是较新加入的expert_tensor_parallel_size与distributed_timeout_minutes以及order字符串格式tp-cp-ep-dp-pp是否仍合法。条目 2parallel_stategetter 函数族——get_data_parallel_rank/world_size/group、get_tensor_model_parallel_rank/world_size/group、get_pipeline_model_parallel_rank/world_size/group、get_context_parallel_rank/world_size/group、get_expert_model_parallel_rank/world_size、is_pipeline_last_stage、is_pipeline_first_stage、model_parallel_is_initialized、destroy_model_parallel全部为无参签名。这些函数在areal/engine/megatron_engine.py与areal/models/mcore/*.py中被调用数十次例如 checkpointer.py 的 RNG 状态收集就依赖get_pipeline_model_parallel_rank/world_size与get_tensor_model_parallel_rank/world_size任何删除或改名都是立即致命的。条目 3parallel_state工具函数—— AReaL 在 megatron_engine.py 中手工构造了一个上下文模型并行组TP/CP/PP 联合通信组依赖四个 APIrank_generator mpu.RankGenerator( tpself.parallel_strategy.tensor_parallel_size, ep1, dpself.parallel_strategy.data_parallel_size, ppself.parallel_strategy.pipeline_parallel_size, cpself.parallel_strategy.context_parallel_size, ordertp-cp-ep-dp-pp, rank_offset0, ) context_and_model_parallel_ranks rank_generator.get_ranks(tp-cp-pp) group mpu.create_group( ranks, timeoutDIST_GROUP_DEFAULT_TIMEOUT, pg_optionsmpu.get_nccl_options(tp-cp-pp, {}), group_descCONTEXT_AND_MODEL_PARALLEL_GROUP, )核对要点RankGenerator.__init__的rank_offset与order关键字参数、get_ranks(group_str)方法、create_group的timeout/pg_options/group_desc关键字、以及get_nccl_options(group_name, config_dict)签名。4.2 分布式并行与梯度条目 4–5条目 4megatron.core.distributed.DistributedDataParallel—— 模型构建后在 areal/models/mcore/registry.py 中用 DDP 包装from megatron.core.distributed import DistributedDataParallel as DDP from megatron.core.distributed import DistributedDataParallelConfig as MCoreDDPConfig ddp_config MCoreDDPConfig(**dataclasses.asdict(mcore_config.ddp)) wrapped DDP( configtf_config, ddp_configddp_config, modulemodel, disable_bucketingFalse, )核对要点config、ddp_config、module、disable_bucketing是否仍被接受AReaL不传data_parallel_group/expert_data_parallel_group需确认它们保持可选且默认值合理同时核对MCoreDDPConfigdataclass 的字段集它由 AReaL 的mcore_config.ddp展开构造字段改名会导致**asdict展开直接 TypeError。条目 5finalize_model_grads—— AReaL 不直接调用它而是把它挂到TransformerConfig.finalize_model_grads_func上由 Megatron 的 pipeline parallel 前后向函数在需要时回调model_config.finalize_model_grads_func finalize_model_grads核对要点函数签名是否仍与finalize_model_grads_func的回调约定兼容接收model_chunks或带num_tokens关键字的变体。4.3 优化器与学习率调度条目 6–8条目 6megatron.core.optimizer.OptimizerConfig—— 在 megatron_engine.py 处构造约 13 个关键字参数mcore_opt_config MCoreOptimizerConfig( optimizerself.optimizer_config.type, lrself.optimizer_config.lr, min_lrself.optimizer_config.min_lr_ratio * self.optimizer_config.lr, weight_decayself.optimizer_config.weight_decay, bf16self.dtype is torch.bfloat16, fp16self.dtype is torch.float16, adam_beta1self.optimizer_config.beta1, adam_beta2self.optimizer_config.beta2, adam_epsself.optimizer_config.eps, use_distributed_optimizeruse_distributed_optimizer, params_dtypeself.dtype, clip_gradself.optimizer_config.gradient_clipping, fp8_recipe(self.fp8_config.recipe if self.enable_fp8 else None), ) # Post-init field assignments: mcore_opt_config.overlap_param_gather_with_optimizer_step ... mcore_opt_config.use_precision_aware_optimizer ... mcore_opt_config.main_grads_dtype getattr(torch, ...) mcore_opt_config.main_params_dtype getattr(torch, ...) mcore_opt_config.exp_avg_dtype getattr(torch, ...) mcore_opt_config.exp_avg_sq_dtype getattr(torch, ...)核对要点构造函数约 13 个关键字尤其fp8_recipe与fp16是否仍被接受构造后直接赋值的 6 个后置字段overlap_param_gather_with_optimizer_step、use_precision_aware_optimizer、main_grads_dtype、main_params_dtype、exp_avg_dtype、exp_avg_sq_dtype是否仍存在于 dataclass 上——后置赋值对字段改名零容忍。条目 7get_megatron_optimizer—— megatron_engine.py 处的两参调用self.optimizer get_megatron_optimizer(mcore_opt_config, self.model)核对要点(config, model_chunks)两参形式是否仍有效model_chunks是否仍接受 DDP 包装模块的列表是否新增了必填参数例如no_weight_decay_cond、scale_lr_cond——AReaL 不传这些需确认它们保持可选。条目 8OptimizerParamScheduler—— megatron_engine.py 处构造学习率/权重衰减调度器lr_scheduler OptimizerParamScheduler( self.optimizer, init_lr0.0 if warmup_steps_proportion 0 else self.optimizer_config.lr, max_lrself.optimizer_config.lr, min_lrself.optimizer_config.min_lr_ratio * self.optimizer_config.lr, lr_warmup_stepswarmup_steps, lr_decay_stepsft_spec.total_train_steps - warmup_steps, lr_decay_styleself.optimizer_config.lr_scheduler_type, start_wdself.optimizer_config.weight_decay, end_wdself.optimizer_config.weight_decay, wd_incr_stepsft_spec.total_train_steps, wd_incr_styleconstant, )核对要点全部关键字参数是否仍被接受——重点是权重衰减调度参数start_wd、end_wd、wd_incr_steps、wd_incr_stylelr_decay_style的合法取值集如cosine、linear、WSD是否变化。4.4 Pipeline parallel 与层布局条目 9、12条目 9get_forward_backward_func—— 位于训练热循环megatron_engine.py 中每步调用任何破坏都会停止所有 PP 训练forward_backward_func get_forward_backward_func() forward_backward_func( forward_step_funcforward_step, data_iteratordata_iterator, modelself.model if len(self.model) 1 else self.model[0], num_microbatcheslen(mb_list), seq_lengthmb_list.max_seqlen, micro_batch_size1, forward_onlyforward_only, )核对要点返回的 callable 是否仍接受这套签名seq_length与micro_batch_size关键字上游注释中标记为“设置了 input_shapes 后不再使用”是否仍被接受。条目 12PipelineParallelLayerLayout—— areal/engine/megatron_utils/pipeline_parallel.py 顶部导入from megatron.core.transformer.pipeline_parallel_layer_layout import ( PipelineParallelLayerLayout, )核对要点导入路径必须仍是megatron.core.transformer.pipeline_parallel_layer_layout不能只是transformer_config.py里的再导出构造函数关键字参数以及get_num_layers_to_build()与get_transformer_layer_offset()是否仍可访问。4.5 模型配置与模型本体条目 10、14、16条目 10TransformerConfig—— 贯穿 megatron_engine.py、pipeline_parallel.py、registry.py、common.py、qwen3.py 的中心配置 dataclasstransformer_config TransformerConfig( num_layersnum_layers, hidden_sizehidden_size, num_attention_headsnum_heads, num_key_value_headsnum_kv_heads, # ... many more fields )核对要点这是中心配置——任何字段被删除或改名都是破坏性的新增带默认值的可选字段无害同时检查子类MLATransformerConfigbailing_moe.py与bailing_moe_bridge.py使用的兼容性。条目 14GPTModel—— registry.py 中构建标准 GPT 模型model GPTModel( configtransformer_config, transformer_layer_speclayer_spec, vocab_sizevocab_size, max_sequence_lengthmax_seq_len, pre_processpre_process, post_processpost_process, )核对要点构造函数关键字参数get_gpt_decoder_block_spec()是否仍返回有效的 layer spec是否出现新的必填参数。条目 16Transformer 层 spec 与模块构建器—— bailing_moe.py、lightning_attention.py、module_megatron.py 三处自定义模型都依赖这组底层构件from megatron.core.transformer import ModuleSpec, build_module from megatron.core.transformer.enums import AttnMaskType, LayerType from megatron.core.transformer.transformer_layer import ( TransformerLayer, TransformerLayerSubmodules, ) from megatron.core.transformer.transformer_block import TransformerBlockSubmodules from megatron.core.transformer.attention import SelfAttention from megatron.core.transformer.custom_layers.transformer_engine import ( # TE norm modules )核对要点AttnMaskType与LayerType的枚举值ModuleSpec与build_module签名SelfAttention.__init__是否新增必填参数Transformer Engine 集成模块路径是否被重构。4.6 分布式检查点条目 11条目 11dist_checkpointingsave/load—— checkpointer.py 的导入与 save/load_dist_checkpointing 中的调用from megatron.core import dist_checkpointing from megatron.core.dist_checkpointing.mapping import ShardedObject from megatron.core.dist_checkpointing.serialization import ( get_default_save_sharded_strategy, get_default_load_sharded_strategy, ) from megatron.core.dist_checkpointing.strategies.fully_parallel import ( FullyParallelLoadStrategyWrapper, FullyParallelSaveStrategyWrapper, ) # Save save_strategy get_default_save_sharded_strategy(torch_dist) save_strategy FullyParallelSaveStrategyWrapper(save_strategy, dp_group) dist_checkpointing.save( sharded_state_dict, ckpt_path, sharded_strategysave_strategy, async_sharded_saveasync_save, validate_access_integrityvalidate_sharding_integrity, ) # Load load_strategy get_default_load_sharded_strategy(ckpt_dir) load_strategy FullyParallelLoadStrategyWrapper(load_strategy, dp_group) state_dict dist_checkpointing.load( sharded_state_dict, ckpt_dir, sharded_strategyload_strategy )核对要点save的关键字参数——尤其async_sharded_save与validate_access_integrityget_default_save_sharded_strategy是否仍接受torch_dist字符串get_default_load_sharded_strategy是否仍接受ckpt_dir路径参数三条导入路径serialization的策略工厂、strategies.fully_parallel的包装器、mapping的ShardedObject。检查点格式兼容性是重中之重——必须确认上游没有做 checkpoint 格式版本升级否则旧训练无法恢复。源码里还有一个清单之外但同源的版本契约值得注意checkpointer.py 的注释明确记录了“megatron-core v0.14 removed flattened_range supportMegatron-LM PR #2126”因此optimizer.sharded_state_dict显式传metadata{distrib_optim_sharding_type: dp_reshardable}并在is_loadingTrue时预分配exp_avg/exp_avg_sq否则 DCP 在 resume 时会静默丢弃动量状态。这正是“上游一个内部契约变化 → AReaL 必须显式适配”的典型案例升级审计时应对照新版本的sharded_state_dict默认行为重新验证这段逻辑。4.7 FP8、张量并行、Packed 序列与 RoPE条目 13、15、17、18条目 13fp8_utils.is_float8tensor—— tensor_helper.pyfrom megatron.core.fp8_utils import is_float8tensor if is_float8tensor(param): ...核对要点函数是否仍在该路径是否仍接受单个 tensor 参数FP8 支持是否被重构例如移到megatron.core.extensions.transformer_engine。条目 15tensor_parallel工具函数—— megatron_engine.py 与 lightning_attention.pytensor_parallel.model_parallel_cuda_manual_seed(seed) tensor_parallel.gather_from_sequence_parallel_region(output) tensor_parallel.get_cuda_rng_tracker()核对要点三个函数是否仍存在且签名不变。model_parallel_cuda_manual_seed在初始化时调用一次megatron_engine.py L438gather_from_sequence_parallel_region位于热路径get_cuda_rng_tracker还被 checkpointer.py 用于 RNG 状态的保存与恢复。条目 17PackedSeqParams—— packed_context_parallel.pyfrom megatron.core.packed_seq_params import PackedSeqParams packed_seq_params PackedSeqParams( cu_seqlens_qcu_seqlens_q, cu_seqlens_kvcu_seqlens_kv, max_seqlen_qmax_seqlen_q, max_seqlen_kvmax_seqlen_kv, qkv_formatthd, )核对要点构造函数关键字参数与导入路径清单标注了“或megatron.core/transformer/”的备选位置升级时两处都要查qkv_format的合法取值集。条目 18RoPE 工具—— bailing_moe.py 与 lightning_attention.pyfrom megatron.core.models.common.embeddings.rotary_pos_embedding import apply_rotary_pos_emb # Also various rope_utils for extended RoPE (YaRN, etc.)核对要点apply_rotary_pos_emb的(t, freqs)签名。该函数在bailing_moe.py中被大量 patch——必须确认基础实现没有以破坏这些 patch 的方式变化。5. Version-Guarded Code版本守卫与特殊注意点清单的末节记录“版本守卫代码”——AReaL 中针对旧版本写的条件分支升级后需要清理死代码。对megatron-core的结论是AReaL 中没有已知的版本守卫代码。但bailing_moe.py与bailing_moe_bridge.py使用的MLATransformerConfig是上游较新的新增——必须确认目标版本中存在该类。从源码结构看仓库中确实存在针对megatron-core内部契约的防御性适配而非版本分支前述 checkpointer.py 的_UnsupportedMCoreAsyncLayout异常与_inspect_retained_payload函数会在调度异步保存前校验 MCore 内部AsyncRequest的 payload 布局async_fn_args三元组、write_buckets、(bytes_data, tensor_data)元组布局不符时拒绝调度——注释中也留了TODO(agent): Revalidate this internal contract when MCores async checkpoint request or write-bucket layout changes。这意味着虽然清单层面没有显式版本守卫但异步检查点对 MCore 内部布局的隐式依赖是每次升级都必须重新验证的隐藏审计项。6. 升级审计的完整执行路径对照 Step 6把清单代入/upgrade-deps的 Step 6实际执行路径是6a 克隆上游按 frontmatter 执行git clone --depth 1 --branch core_rVERSION NVIDIA/Megatron-LMVERSION 需通过^[a-zA-Z0-9._/-]$校验防命令注入6b 逐条核对打开upstream_paths列出的 15 个上游文件/目录对 18 个 Catalog 条目逐一比对签名标记“删除的参数/改名/新增必填/返回类型变化/模块移动/方法签名变化”六类问题6c 检查版本守卫确认MLATransformerConfig存在性6d 按优先级修调用点engine 层 → model 层 → infra 层 → 测试文件且不做大面积重构遇到无法自动解决的破坏时停下询问用户6e 回写清单上游签名变了就更新 Catalog 条目AReaL 调用点改了就替换代码片段与行号文件移动了就更新upstream_paths6f 清理克隆目录随后pre-commit run --all-files并生成upgrade-summary.md升级摘要含 API 兼容性审计的逐条结论。7. 如何维护这份清单CHECKLIST_MAINTENANCE.md 定义了两种互补的维护活动二者共享同一份清单格式模板见 checklists/_TEMPLATE.md结构校验Step 0.5升级前用from megatron.core/import megatron.core两个 grep 模式扫描areal/、tests/、examples/排除注释、docstring 与无关子串误报产出 MISSING / STALE / CHANGED 三张清单。MISSING 文件按目录规则补进对应层级CHANGED 文件若引入了 Catalog 之外的新函数或“显著不同”的调用不同关键字参数、不同的返回值消费方式、可独立破坏的代码路径则新增 Catalog 条目并整体重新编号。不确定的删除用!-- TODO: verify removal --注释代替硬删。内容更新Step 6e升级后同步 API 签名、调用点代码片段与行号、版本守卫条目、frontmatterupstream_paths最后更新 SKILL.md 底部的Checklist File Status表。SKILL.md 的状态表当前记录megatron-core清单含18 条 API 条目parallel_state、DDP、optimizer、pipeline、checkpointing、transformer config、FP8、GPTModel、tensor_parallel、layer specs、RoPE与本文第 4 节逐项对应。撰写 Catalog 条目的准则§6也值得参考一条目一 API 表面同一 API 多处调用只列主调用点并附引用Check 指令必须具体可执行好例子“确认bias仍接受字符串none”坏例子“检查是否有变化”拿不准时宁可加条目——略嫌冗余的清单远好于导致漏检 breaking change 的缺口。8. 小结.agents/skills/upgrade-deps/checklists/megatron-core.md是 AReaL 依赖升级工程化流程的“契约文档”frontmatter 锚定上游坐标NVIDIA/Megatron-LM分支模板core_r${VERSION}三层 Affected Files 界定影响面18 条 API Usage Catalog 把每一次megatron.core调用变成可机器核对的审计单元。结合 SKILL.md 的工作流与 CHECKLIST_MAINTENANCE.md 的维护规程它保证了从megatron-core0.17.0升级到任何目标版本时破坏点要么被静态审计提前捕获要么被清单本身的缺漏暴露出来——而不是在生产训练中炸开。若要亲手验证本文内容最直接的切入点是 areal/engine/megatron_engine.py 中的create_process_group并行组初始化与 areal/engine/megatron_utils/checkpointer.py 中的save_dist_checkpointing/load_dist_checkpointing检查点契约这两处正是清单中标注“最可能先被击穿”的核心调用链。【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 8:20:06 · 阅读 1.2k AReaL megatron-core 依赖升级 API 审计清单：upgrade-deps 技能与 API Usage Catalog 实战指南
AReaL megatron-core 依赖升级 API 审计清单upgrade-deps 技能与 API Usage Catalog 实战指南【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaLAReaL 将megatron-core锁定为精确版本当前pyproject.toml与pyproject.vllm.toml均 pin 为megatron-core0.17.0任何版本升级都必须先回答一个问题AReaL 在哪些文件、哪些行调用了哪些megatron.coreAPI新版本的签名变化会不会击穿训练引擎。.agents/skills/upgrade-deps/checklists/megatron-core.md正是为这个问题而生的“API 兼容性审计清单”——它完整记录了 18 个 API 表面函数/类/模块路径在 AReaL 中的真实调用点、导入内容与升级时必须核对的校验项。读完本文你将理解这份清单的结构与每个条目的含义、掌握它在/upgrade-deps工作流中如何驱动自动化审计并能对照 AReaL 源码验证清单中记录的每一次 Megatron 调用。1. 背景upgrade-deps 技能与双清单文件模型这份清单不是孤立文件而是 AReaL 的upgrade-deps技能定义于 .agents/skills/upgrade-deps/SKILL.md中“每个 focused 包一份 API 清单”机制的一部分。技能的工作方式是用户执行/upgrade-deps megatron-core0.17.0或类似命令指定目标版本技能先做Step 0.5 清单结构校验grep 全仓库areal/、tests/、examples/中所有from megatron.core/import megatron.core的导入点与清单的 Affected Files 三层表格比对找出 Missing / Stale / Changed 三类偏差并补全修改 pyproject、uv lock重新锁定Step 6 API 兼容性审计读取清单 frontmatter 中的githubNVIDIA/Megatron-LM与branch_templatecore_r${VERSION}克隆目标版本的上游源码逐条核对 API Usage Catalog 中的每个调用点签名。AReaL 维护两份 pyproject 文件pyproject.tomlSGLang 推理后端锁uv.lock和pyproject.vllm.tomlvLLM 后端锁uv.vllm.lock。megatron-core属于shared作用域——两份文件都要改、两套锁都要重新生成但 Dockerfile 无需变更它通过 Stage 3 的uv pip install自动读取更新后的 pyproject。megatron-core还被划入megatron 升级家族megatron-bridge包裹megatron-core、二者 API 紧耦合升级megatron-core时必须检查megatron-bridge是否需要同步升版否则技能会主动告警。当前 pin 位置可以在此确认pyproject.toml 的[optional-dependencies].megatron中写有megatron-core0.17.0带 Python ≥3.12 / linux / x86_64 的 marker 约束。2. 清单结构YAML frontmatter 与上游锚点megatron-core.md 的 frontmatter 是 Step 6a 克隆上游源码的坐标package: megatron-core github: NVIDIA/Megatron-LM branch_template: core_r${VERSION} upstream_paths: - megatron/core/parallel_state.py - megatron/core/distributed/ - megatron/core/optimizer/ - megatron/core/optimizer_param_scheduler.py - megatron/core/pipeline_parallel/ - megatron/core/transformer/transformer_config.py - megatron/core/transformer/pipeline_parallel_layer_layout.py - megatron/core/dist_checkpointing/ - megatron/core/dist_checkpointing/serialization.py - megatron/core/dist_checkpointing/strategies/fully_parallel.py - megatron/core/fp8_utils.py - megatron/core/models/gpt/ - megatron/core/packed_seq_params.py - megatron/core/models/common/embeddings/rotary_pos_embedding.py - megatron/core/utils.py三个字段各有职责github上游仓库审计时git clone --depth 1 --branch BRANCH的来源branch_templateMegatron-LM 的发布分支命名规则是core_r${VERSION}例如core_r0.17.0而非常见的v${VERSION}tag——这是 Megatron-LM 区别于多数上游项目的特殊约定若写错分支模板克隆会直接失败upstream_paths目标版本下需要逐一打开核对的上游文件路径。注意upstream_paths会在审计后随上游文件移动而更新Step 6e。3. Affected Files三级影响面模型清单把 AReaL 中所有megatron.core使用点分成三层层级决定破坏半径blast radius也决定修复时的优先级顺序engine 层 → model 层 → infra 层 → 测试。Primary引擎层最可能先被击穿文件导入 / 用法areal/engine/megatron_engine.pyparallel_state、tensor_parallel、DDP、finalize_model_grads、OptimizerConfig、get_megatron_optimizer、OptimizerParamScheduler、get_forward_backward_func、TransformerConfig、get_model_configareal/engine/megatron_utils/checkpointer.pydist_checkpointing.save、load、sharded strategies、ShardedObjectareal/engine/megatron_utils/megatron.pyparallel_state、FP8 检测、TransformerConfigareal/engine/megatron_utils/pipeline_parallel.pyTransformerConfig、PipelineParallelLayerLayoutareal/engine/megatron_utils/packed_context_parallel.pyPackedSeqParams、parallel_stateareal/engine/megatron_utils/fp8/tensor_helper.pyfp8_utils.is_float8tensorSecondary模型 / 基础设施层文件导入 / 用法areal/models/mcore/registry.pyGPTModel、DDP、TransformerConfig、parallel_state、AutoConfigareal/models/mcore/bailing_moe.pyMLATransformerConfig、LayerType、ModuleSpec、SelfAttention、AttnMaskType、TransformerLayer、TransformerLayerSubmodules、TransformerBlockSubmodules、apply_rotary_pos_emb、rope_utilsareal/models/mcore/tree_attn/module_megatron.pyTransformerConfig、SelfAttention、AttnMaskType、layer specsareal/models/mcore/lightning_attention.pyparallel_state、apply_rotary_pos_emb、MegatronModule、ModuleSpec、build_moduleareal/models/mcore/bailing_moe_bridge.pyMLATransformerConfig、AttnBackendareal/models/mcore/common.pyTransformerConfigareal/models/mcore/qwen3.pygpt_layer_specs、TransformerConfigTertiary测试与外围文件导入 / 用法areal/infra/workflow_executor.py条件式parallel_stateDP world sizetests/test_estimate_num_params.pyparallel_state、tensor_paralleltests/fp8/engine_utils.pyparallel_statetests/fp8/model_hooks.pyparallel_statetests/fp8/test_fp8_rmsnorm.pyfp8_utils、get_model_configtests/torchrun/run_megatron_engine_distributed.pyparallel_state分层规则定义在 CHECKLIST_MAINTENANCE.md §3.3areal/engine/、areal/experimental/engine/归 Primaryareal/models/、areal/infra/、areal/api/等归 Secondarytests/、examples/、工具脚本归 Tertiary。跨关注点的文件按目录位置而非内容归类。4. API Usage Catalog18 条审计条目逐项拆解Catalog 是清单的核心每个条目记录一个独立 API 表面的上游源路径、AReaL 真实调用点代码、以及升级时必须核对什么。审计时只关注五类破坏模式新增必填参数、删除旧参数、参数改名、返回类型/方法签名变化、模块移动或改名。下面按功能域分组完整继承这 18 个条目。4.1 parallel_state进程组拓扑的入口条目 1–3条目 1megatron.core.parallel_state.initialize_model_parallel—— 这是整个清单中被标记为“最关键”的调用签名一旦变化所有 Megatron 训练全部被阻断。AReaL 在 areal/engine/megatron_engine.py 的create_process_group()中调用清单中记录的行号会随代码演进而刷新以当前源码为准mpu.initialize_model_parallel( tensor_model_parallel_sizeself.parallel_strategy.tensor_parallel_size, pipeline_model_parallel_sizeself.parallel_strategy.pipeline_parallel_size, virtual_pipeline_model_parallel_sizevpp_size if vpp_size 1 else None, use_sharpFalse, ordertp-cp-ep-dp-pp, context_parallel_sizeself.parallel_strategy.context_parallel_size, expert_model_parallel_sizeself.parallel_strategy.expert_parallel_size, expert_tensor_parallel_sizeself.parallel_strategy.expert_tensor_parallel_size, distributed_timeout_minutesint(DIST_GROUP_DEFAULT_TIMEOUT.seconds / 60), )核对要点所有关键字参数是否仍被接受——尤其是较新加入的expert_tensor_parallel_size与distributed_timeout_minutes以及order字符串格式tp-cp-ep-dp-pp是否仍合法。条目 2parallel_stategetter 函数族——get_data_parallel_rank/world_size/group、get_tensor_model_parallel_rank/world_size/group、get_pipeline_model_parallel_rank/world_size/group、get_context_parallel_rank/world_size/group、get_expert_model_parallel_rank/world_size、is_pipeline_last_stage、is_pipeline_first_stage、model_parallel_is_initialized、destroy_model_parallel全部为无参签名。这些函数在areal/engine/megatron_engine.py与areal/models/mcore/*.py中被调用数十次例如 checkpointer.py 的 RNG 状态收集就依赖get_pipeline_model_parallel_rank/world_size与get_tensor_model_parallel_rank/world_size任何删除或改名都是立即致命的。条目 3parallel_state工具函数—— AReaL 在 megatron_engine.py 中手工构造了一个上下文模型并行组TP/CP/PP 联合通信组依赖四个 APIrank_generator mpu.RankGenerator( tpself.parallel_strategy.tensor_parallel_size, ep1, dpself.parallel_strategy.data_parallel_size, ppself.parallel_strategy.pipeline_parallel_size, cpself.parallel_strategy.context_parallel_size, ordertp-cp-ep-dp-pp, rank_offset0, ) context_and_model_parallel_ranks rank_generator.get_ranks(tp-cp-pp) group mpu.create_group( ranks, timeoutDIST_GROUP_DEFAULT_TIMEOUT, pg_optionsmpu.get_nccl_options(tp-cp-pp, {}), group_descCONTEXT_AND_MODEL_PARALLEL_GROUP, )核对要点RankGenerator.__init__的rank_offset与order关键字参数、get_ranks(group_str)方法、create_group的timeout/pg_options/group_desc关键字、以及get_nccl_options(group_name, config_dict)签名。4.2 分布式并行与梯度条目 4–5条目 4megatron.core.distributed.DistributedDataParallel—— 模型构建后在 areal/models/mcore/registry.py 中用 DDP 包装from megatron.core.distributed import DistributedDataParallel as DDP from megatron.core.distributed import DistributedDataParallelConfig as MCoreDDPConfig ddp_config MCoreDDPConfig(**dataclasses.asdict(mcore_config.ddp)) wrapped DDP( configtf_config, ddp_configddp_config, modulemodel, disable_bucketingFalse, )核对要点config、ddp_config、module、disable_bucketing是否仍被接受AReaL不传data_parallel_group/expert_data_parallel_group需确认它们保持可选且默认值合理同时核对MCoreDDPConfigdataclass 的字段集它由 AReaL 的mcore_config.ddp展开构造字段改名会导致**asdict展开直接 TypeError。条目 5finalize_model_grads—— AReaL 不直接调用它而是把它挂到TransformerConfig.finalize_model_grads_func上由 Megatron 的 pipeline parallel 前后向函数在需要时回调model_config.finalize_model_grads_func finalize_model_grads核对要点函数签名是否仍与finalize_model_grads_func的回调约定兼容接收model_chunks或带num_tokens关键字的变体。4.3 优化器与学习率调度条目 6–8条目 6megatron.core.optimizer.OptimizerConfig—— 在 megatron_engine.py 处构造约 13 个关键字参数mcore_opt_config MCoreOptimizerConfig( optimizerself.optimizer_config.type, lrself.optimizer_config.lr, min_lrself.optimizer_config.min_lr_ratio * self.optimizer_config.lr, weight_decayself.optimizer_config.weight_decay, bf16self.dtype is torch.bfloat16, fp16self.dtype is torch.float16, adam_beta1self.optimizer_config.beta1, adam_beta2self.optimizer_config.beta2, adam_epsself.optimizer_config.eps, use_distributed_optimizeruse_distributed_optimizer, params_dtypeself.dtype, clip_gradself.optimizer_config.gradient_clipping, fp8_recipe(self.fp8_config.recipe if self.enable_fp8 else None), ) # Post-init field assignments: mcore_opt_config.overlap_param_gather_with_optimizer_step ... mcore_opt_config.use_precision_aware_optimizer ... mcore_opt_config.main_grads_dtype getattr(torch, ...) mcore_opt_config.main_params_dtype getattr(torch, ...) mcore_opt_config.exp_avg_dtype getattr(torch, ...) mcore_opt_config.exp_avg_sq_dtype getattr(torch, ...)核对要点构造函数约 13 个关键字尤其fp8_recipe与fp16是否仍被接受构造后直接赋值的 6 个后置字段overlap_param_gather_with_optimizer_step、use_precision_aware_optimizer、main_grads_dtype、main_params_dtype、exp_avg_dtype、exp_avg_sq_dtype是否仍存在于 dataclass 上——后置赋值对字段改名零容忍。条目 7get_megatron_optimizer—— megatron_engine.py 处的两参调用self.optimizer get_megatron_optimizer(mcore_opt_config, self.model)核对要点(config, model_chunks)两参形式是否仍有效model_chunks是否仍接受 DDP 包装模块的列表是否新增了必填参数例如no_weight_decay_cond、scale_lr_cond——AReaL 不传这些需确认它们保持可选。条目 8OptimizerParamScheduler—— megatron_engine.py 处构造学习率/权重衰减调度器lr_scheduler OptimizerParamScheduler( self.optimizer, init_lr0.0 if warmup_steps_proportion 0 else self.optimizer_config.lr, max_lrself.optimizer_config.lr, min_lrself.optimizer_config.min_lr_ratio * self.optimizer_config.lr, lr_warmup_stepswarmup_steps, lr_decay_stepsft_spec.total_train_steps - warmup_steps, lr_decay_styleself.optimizer_config.lr_scheduler_type, start_wdself.optimizer_config.weight_decay, end_wdself.optimizer_config.weight_decay, wd_incr_stepsft_spec.total_train_steps, wd_incr_styleconstant, )核对要点全部关键字参数是否仍被接受——重点是权重衰减调度参数start_wd、end_wd、wd_incr_steps、wd_incr_stylelr_decay_style的合法取值集如cosine、linear、WSD是否变化。4.4 Pipeline parallel 与层布局条目 9、12条目 9get_forward_backward_func—— 位于训练热循环megatron_engine.py 中每步调用任何破坏都会停止所有 PP 训练forward_backward_func get_forward_backward_func() forward_backward_func( forward_step_funcforward_step, data_iteratordata_iterator, modelself.model if len(self.model) 1 else self.model[0], num_microbatcheslen(mb_list), seq_lengthmb_list.max_seqlen, micro_batch_size1, forward_onlyforward_only, )核对要点返回的 callable 是否仍接受这套签名seq_length与micro_batch_size关键字上游注释中标记为“设置了 input_shapes 后不再使用”是否仍被接受。条目 12PipelineParallelLayerLayout—— areal/engine/megatron_utils/pipeline_parallel.py 顶部导入from megatron.core.transformer.pipeline_parallel_layer_layout import ( PipelineParallelLayerLayout, )核对要点导入路径必须仍是megatron.core.transformer.pipeline_parallel_layer_layout不能只是transformer_config.py里的再导出构造函数关键字参数以及get_num_layers_to_build()与get_transformer_layer_offset()是否仍可访问。4.5 模型配置与模型本体条目 10、14、16条目 10TransformerConfig—— 贯穿 megatron_engine.py、pipeline_parallel.py、registry.py、common.py、qwen3.py 的中心配置 dataclasstransformer_config TransformerConfig( num_layersnum_layers, hidden_sizehidden_size, num_attention_headsnum_heads, num_key_value_headsnum_kv_heads, # ... many more fields )核对要点这是中心配置——任何字段被删除或改名都是破坏性的新增带默认值的可选字段无害同时检查子类MLATransformerConfigbailing_moe.py与bailing_moe_bridge.py使用的兼容性。条目 14GPTModel—— registry.py 中构建标准 GPT 模型model GPTModel( configtransformer_config, transformer_layer_speclayer_spec, vocab_sizevocab_size, max_sequence_lengthmax_seq_len, pre_processpre_process, post_processpost_process, )核对要点构造函数关键字参数get_gpt_decoder_block_spec()是否仍返回有效的 layer spec是否出现新的必填参数。条目 16Transformer 层 spec 与模块构建器—— bailing_moe.py、lightning_attention.py、module_megatron.py 三处自定义模型都依赖这组底层构件from megatron.core.transformer import ModuleSpec, build_module from megatron.core.transformer.enums import AttnMaskType, LayerType from megatron.core.transformer.transformer_layer import ( TransformerLayer, TransformerLayerSubmodules, ) from megatron.core.transformer.transformer_block import TransformerBlockSubmodules from megatron.core.transformer.attention import SelfAttention from megatron.core.transformer.custom_layers.transformer_engine import ( # TE norm modules )核对要点AttnMaskType与LayerType的枚举值ModuleSpec与build_module签名SelfAttention.__init__是否新增必填参数Transformer Engine 集成模块路径是否被重构。4.6 分布式检查点条目 11条目 11dist_checkpointingsave/load—— checkpointer.py 的导入与 save/load_dist_checkpointing 中的调用from megatron.core import dist_checkpointing from megatron.core.dist_checkpointing.mapping import ShardedObject from megatron.core.dist_checkpointing.serialization import ( get_default_save_sharded_strategy, get_default_load_sharded_strategy, ) from megatron.core.dist_checkpointing.strategies.fully_parallel import ( FullyParallelLoadStrategyWrapper, FullyParallelSaveStrategyWrapper, ) # Save save_strategy get_default_save_sharded_strategy(torch_dist) save_strategy FullyParallelSaveStrategyWrapper(save_strategy, dp_group) dist_checkpointing.save( sharded_state_dict, ckpt_path, sharded_strategysave_strategy, async_sharded_saveasync_save, validate_access_integrityvalidate_sharding_integrity, ) # Load load_strategy get_default_load_sharded_strategy(ckpt_dir) load_strategy FullyParallelLoadStrategyWrapper(load_strategy, dp_group) state_dict dist_checkpointing.load( sharded_state_dict, ckpt_dir, sharded_strategyload_strategy )核对要点save的关键字参数——尤其async_sharded_save与validate_access_integrityget_default_save_sharded_strategy是否仍接受torch_dist字符串get_default_load_sharded_strategy是否仍接受ckpt_dir路径参数三条导入路径serialization的策略工厂、strategies.fully_parallel的包装器、mapping的ShardedObject。检查点格式兼容性是重中之重——必须确认上游没有做 checkpoint 格式版本升级否则旧训练无法恢复。源码里还有一个清单之外但同源的版本契约值得注意checkpointer.py 的注释明确记录了“megatron-core v0.14 removed flattened_range supportMegatron-LM PR #2126”因此optimizer.sharded_state_dict显式传metadata{distrib_optim_sharding_type: dp_reshardable}并在is_loadingTrue时预分配exp_avg/exp_avg_sq否则 DCP 在 resume 时会静默丢弃动量状态。这正是“上游一个内部契约变化 → AReaL 必须显式适配”的典型案例升级审计时应对照新版本的sharded_state_dict默认行为重新验证这段逻辑。4.7 FP8、张量并行、Packed 序列与 RoPE条目 13、15、17、18条目 13fp8_utils.is_float8tensor—— tensor_helper.pyfrom megatron.core.fp8_utils import is_float8tensor if is_float8tensor(param): ...核对要点函数是否仍在该路径是否仍接受单个 tensor 参数FP8 支持是否被重构例如移到megatron.core.extensions.transformer_engine。条目 15tensor_parallel工具函数—— megatron_engine.py 与 lightning_attention.pytensor_parallel.model_parallel_cuda_manual_seed(seed) tensor_parallel.gather_from_sequence_parallel_region(output) tensor_parallel.get_cuda_rng_tracker()核对要点三个函数是否仍存在且签名不变。model_parallel_cuda_manual_seed在初始化时调用一次megatron_engine.py L438gather_from_sequence_parallel_region位于热路径get_cuda_rng_tracker还被 checkpointer.py 用于 RNG 状态的保存与恢复。条目 17PackedSeqParams—— packed_context_parallel.pyfrom megatron.core.packed_seq_params import PackedSeqParams packed_seq_params PackedSeqParams( cu_seqlens_qcu_seqlens_q, cu_seqlens_kvcu_seqlens_kv, max_seqlen_qmax_seqlen_q, max_seqlen_kvmax_seqlen_kv, qkv_formatthd, )核对要点构造函数关键字参数与导入路径清单标注了“或megatron.core/transformer/”的备选位置升级时两处都要查qkv_format的合法取值集。条目 18RoPE 工具—— bailing_moe.py 与 lightning_attention.pyfrom megatron.core.models.common.embeddings.rotary_pos_embedding import apply_rotary_pos_emb # Also various rope_utils for extended RoPE (YaRN, etc.)核对要点apply_rotary_pos_emb的(t, freqs)签名。该函数在bailing_moe.py中被大量 patch——必须确认基础实现没有以破坏这些 patch 的方式变化。5. Version-Guarded Code版本守卫与特殊注意点清单的末节记录“版本守卫代码”——AReaL 中针对旧版本写的条件分支升级后需要清理死代码。对megatron-core的结论是AReaL 中没有已知的版本守卫代码。但bailing_moe.py与bailing_moe_bridge.py使用的MLATransformerConfig是上游较新的新增——必须确认目标版本中存在该类。从源码结构看仓库中确实存在针对megatron-core内部契约的防御性适配而非版本分支前述 checkpointer.py 的_UnsupportedMCoreAsyncLayout异常与_inspect_retained_payload函数会在调度异步保存前校验 MCore 内部AsyncRequest的 payload 布局async_fn_args三元组、write_buckets、(bytes_data, tensor_data)元组布局不符时拒绝调度——注释中也留了TODO(agent): Revalidate this internal contract when MCores async checkpoint request or write-bucket layout changes。这意味着虽然清单层面没有显式版本守卫但异步检查点对 MCore 内部布局的隐式依赖是每次升级都必须重新验证的隐藏审计项。6. 升级审计的完整执行路径对照 Step 6把清单代入/upgrade-deps的 Step 6实际执行路径是6a 克隆上游按 frontmatter 执行git clone --depth 1 --branch core_rVERSION NVIDIA/Megatron-LMVERSION 需通过^[a-zA-Z0-9._/-]$校验防命令注入6b 逐条核对打开upstream_paths列出的 15 个上游文件/目录对 18 个 Catalog 条目逐一比对签名标记“删除的参数/改名/新增必填/返回类型变化/模块移动/方法签名变化”六类问题6c 检查版本守卫确认MLATransformerConfig存在性6d 按优先级修调用点engine 层 → model 层 → infra 层 → 测试文件且不做大面积重构遇到无法自动解决的破坏时停下询问用户6e 回写清单上游签名变了就更新 Catalog 条目AReaL 调用点改了就替换代码片段与行号文件移动了就更新upstream_paths6f 清理克隆目录随后pre-commit run --all-files并生成upgrade-summary.md升级摘要含 API 兼容性审计的逐条结论。7. 如何维护这份清单CHECKLIST_MAINTENANCE.md 定义了两种互补的维护活动二者共享同一份清单格式模板见 checklists/_TEMPLATE.md结构校验Step 0.5升级前用from megatron.core/import megatron.core两个 grep 模式扫描areal/、tests/、examples/排除注释、docstring 与无关子串误报产出 MISSING / STALE / CHANGED 三张清单。MISSING 文件按目录规则补进对应层级CHANGED 文件若引入了 Catalog 之外的新函数或“显著不同”的调用不同关键字参数、不同的返回值消费方式、可独立破坏的代码路径则新增 Catalog 条目并整体重新编号。不确定的删除用!-- TODO: verify removal --注释代替硬删。内容更新Step 6e升级后同步 API 签名、调用点代码片段与行号、版本守卫条目、frontmatterupstream_paths最后更新 SKILL.md 底部的Checklist File Status表。SKILL.md 的状态表当前记录megatron-core清单含18 条 API 条目parallel_state、DDP、optimizer、pipeline、checkpointing、transformer config、FP8、GPTModel、tensor_parallel、layer specs、RoPE与本文第 4 节逐项对应。撰写 Catalog 条目的准则§6也值得参考一条目一 API 表面同一 API 多处调用只列主调用点并附引用Check 指令必须具体可执行好例子“确认bias仍接受字符串none”坏例子“检查是否有变化”拿不准时宁可加条目——略嫌冗余的清单远好于导致漏检 breaking change 的缺口。8. 小结.agents/skills/upgrade-deps/checklists/megatron-core.md是 AReaL 依赖升级工程化流程的“契约文档”frontmatter 锚定上游坐标NVIDIA/Megatron-LM分支模板core_r${VERSION}三层 Affected Files 界定影响面18 条 API Usage Catalog 把每一次megatron.core调用变成可机器核对的审计单元。结合 SKILL.md 的工作流与 CHECKLIST_MAINTENANCE.md 的维护规程它保证了从megatron-core0.17.0升级到任何目标版本时破坏点要么被静态审计提前捕获要么被清单本身的缺漏暴露出来——而不是在生产训练中炸开。若要亲手验证本文内容最直接的切入点是 areal/engine/megatron_engine.py 中的create_process_group并行组初始化与 areal/engine/megatron_utils/checkpointer.py 中的save_dist_checkpointing/load_dist_checkpointing检查点契约这两处正是清单中标注“最可能先被击穿”的核心调用链。【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考