AReaL 中 transformers 依赖升级 API 审计清单从受影响文件分层到 12 项高风险接口目录【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL本文基于 AReaL 仓库中 upgrade-deps 技能的 transformers 升级检查清单完整讲解如何把一个大型 RL 训练框架对transformers库的依赖面系统化地“盘点成文档”受影响文件按 Primary/Secondary/Tertiary 三层分级、12 个 API 目录条目逐条记录调用点与审计要点以及其中 flash attention 私有函数 monkey-patch、Qwen VL 内部符号导入等最高风险项。读完本文你可以掌握 AReaL 升级transformers版本时的完整审计方法并能照此清单自查任何一次版本跳跃可能破坏的调用点。1. 背景upgrade-deps 技能与“聚焦包”审计模型AReaL 用一个名为upgrade-deps的 Agent 技能SKILL.md来规范化运行时依赖的升级流程。该流程分为 10 步解析输入并记录基线版本 →结构化校验清单Step 0.5→ 修改 pyproject →uv lock→ 解决依赖冲突 → 更新 Dockerfile → 识别实际发生版本变化的聚焦包 →API 兼容性审计Step 6→ pre-commit → 生成升级摘要。其中transformers是 8 个“聚焦包”focused package之一——它的每一个 API 使用点都被目录化任何一次版本变化都会触发 API 审计。审计的目标是对照目标版本的上游源码确认六类破坏性变化新增的必填参数AReaL 未传会导致失败被删除的旧参数AReaL 仍在传会报 TypeError参数改名、返回类型变化方法签名变化返回对象上的方法模块被移动或重命名import 路径失效。清单文件本身的格式由 checklists/_TEMPLATE.md 定义维护规则如何发现缺失/过期条目、如何补写 API 目录条目统一收敛在 CHECKLIST_MAINTENANCE.md 中。1.1 双 pyproject 与 transformers 的当前版本约束AReaL 维护两套依赖清单因为 SGLang 与 vLLM 钉死了互不兼容的torch/torchao版本文件推理后端锁文件pyproject.tomlSGLang默认uv.lockpyproject.vllm.tomlvLLMuv.vllm.locktransformers属于shared共享作用域的聚焦包它在两个 pyproject 的[project].dependencies中声明且没有 Dockerfile 影响升级后由镜像 Stage 3 的uv pip install自动读取新约束无需改基础镜像。当前仓库中两个变体的约束分别为SGLang 变体transformers5.0.0,5.3.0vLLM 变体transformers5.0并显式排除5.1.*5.5.0的若干小版本。这说明本文清单对应的正是 transformers 5.x 时代uv.lock/uv.vllm.lock中的解析结果是升级时记录基线Step 0与识别传递性版本漂移Step 5的依据锁定动作通过 scripts/uv_lock.sh 执行。2. 清单的 YAML frontmatter审计的“地图入口”清单文件开头是一段机器可读的 frontmatter供 Step 6a 自动克隆上游源码package: transformers github: huggingface/transformers branch_template: v${VERSION} upstream_paths: - src/transformers/models/auto/auto_factory.py - src/transformers/models/auto/configuration_auto.py - src/transformers/configuration_utils.py - src/transformers/tokenization_utils_fast.py - src/transformers/tokenization_utils_base.py - src/transformers/processing_utils.py - src/transformers/optimization.py - src/transformers/modeling_flash_attention_utils.py - src/transformers/integrations/flash_attention.py - src/transformers/models/qwen2_vl/modeling_qwen2_vl.py - src/transformers/models/qwen2_5_vl/ - src/transformers/models/qwen3_vl/modeling_qwen3_vl.py - src/transformers/utils/import_utils.py各字段含义packagepip 包名github上游组织/仓库审计时git clone --depth 1 --branch vVERSIONbranch_template由版本号构造 git tag 的模板v${VERSION}即 transformers 的发布 tag 约定upstream_paths与 AReaL 用法最相关的上游源码路径列表——审计时逐个打开这些文件比对签名。若上游移动了源文件Step 6e 要求同步更新此列表。3. Affected Files三层分级确定“爆炸半径”清单把 AReaL 中所有使用transformers的文件分成三层分级规则与 CHECKLIST_MAINTENANCE.md §3.3 一致按文件位置而非内容归类Primary引擎层最可能坏areal/engine/、areal/experimental/engine/等Secondary模型/基础设施层areal/models/、areal/workflow/、areal/infra/、areal/utils/等其中monkey-patch 类文件被单独标为 HIGH RISKTertiary测试与示例破坏面可控优先级最低。3.1 Primary 层引擎层文件导入 / 用法areal/engine/fsdp_engine.pyAutoConfig、AutoModelForCausalLM、AutoModelForImageTextToText、AutoModelForTokenClassification、PretrainedConfig、PreTrainedTokenizerFast、ProcessorMixin、get_linear_schedule_with_warmup、get_constant_schedule_with_warmupareal/engine/megatron_engine.pyPretrainedConfigareal/engine/fsdp_utils/init.pyPreTrainedModelareal/engine/fsdp_utils/parallel.pyPretrainedConfigareal/experimental/engine/archon_engine.pyAutoConfig、PretrainedConfig、PreTrainedTokenizerFast3.2 Secondary 层HIGH RISKmonkey-patch 集中区文件导入 / 用法areal/models/transformers/ulyssess_patch.py直接导入transformers.modeling_flash_attention_utils._flash_attention_forward对transformers.integrations.flash_attention._flash_attention_forward做 monkey-patch按模块字符串动态导入transformers.models.{qwen2_vl,qwen2_5_vl,qwen3_vl}areal/models/transformers/qwen3_vl.pytransformers.integrations.flash_attention.flash_attention_forwardtransformers.models.qwen3_vl.modeling_qwen3_vl.{apply_rotary_pos_emb, repeat_kv}areal/models/transformers/qwen2_vl.pytransformers.integrations.flash_attention.flash_attention_forwardtransformers.models.qwen2_vl.modeling_qwen2_vl.{apply_multimodal_rotary_pos_emb, repeat_kv}areal/models/transformers/vision_sp_shard.pymonkey-patch Qwen VL 视觉模块内部子模块访问areal/models/tree_attn/module_fsdp.py对transformers.integrations.flash_attention._flash_attention_forward做“保存-替换”式 monkey-patchareal/workflow/rlvr.pyPreTrainedTokenizerFastdecode、apply_chat_template、eos_token_idareal/workflow/vision_rlvr.pyAutoProcessor、PreTrainedTokenizerFastareal/workflow/multi_turn.pyPreTrainedTokenizerFastareal/utils/hf_utils.pyAutoTokenizer.from_pretrained()、AutoProcessor.from_pretrained()areal/utils/seeding.pytransformers.set_seed()areal/infra/platforms/init.pytransformers.utils.import_utils.is_torch_npu_availableareal/infra/rpc/serialization.pyAutoTokenizer、PreTrainedTokenizer、PreTrainedTokenizerFast、AutoProcessor、ProcessorMixinareal/models/mcore/registry.pyAutoConfig、PretrainedConfigareal/models/mcore/bailing_moe.pyPretrainedConfigareal/experimental/models/archon/*/args.py与*/state_dict_adapter.pyPretrainedConfig3.3 Tertiary 层tests/与examples/下共 30 文件全部是AutoTokenizer、AutoConfig、AutoModelForCausalLM、PreTrainedTokenizerFast的标准加载模式不涉及 monkey-patch——因此只在 Affected Files 中登记不单独写 API 目录条目这一取舍符合维护指南 §7“不重复建条目”的原则。4. API Usage Catalog12 个审计条目逐条详解每个条目的固定结构是上游源文件 → AReaL 实际调用点代码 → Check具体要核对什么。下面按清单顺序全部继承并展开。4.1 Auto* 模型与配置类上游源src/transformers/models/auto/auto_factory.py、src/transformers/models/auto/configuration_auto.py。调用点集中在 areal/engine/fsdp_engine.py# 加载 config self.model_config AutoConfig.from_pretrained( pretrained_model_name_or_pathself.config.path, trust_remote_codeTrue, ) # VLM 路径 model AutoModelForImageTextToText.from_pretrained( pretrained_model_name_or_pathself.config.path, trust_remote_codeTrue, dtypedtype, attn_implementationself.config.attn_impl, ) # LLM 路径 —— _create_llm_actor_or_critic model_class AutoModelForTokenClassification if is_critic else AutoModelForCausalLM model_kwargs {num_labels: 1} if is_critic else {} model_kwargs.update({dtype: dtype, attn_implementation: self.config.attn_impl}) # 分支from_configmeta-device省显存或 from_pretrained model model_class.from_config(self.model_config, **model_kwargs) # 或 model model_class.from_pretrained( pretrained_model_name_or_pathself.config.path, trust_remote_codeTrue, **model_kwargs, )同样的加载模式还出现在 areal/utils/hf_utils.py、areal/models/mcore/registry.py、areal/experimental/engine/archon_engine.py 以及areal/experimental/models/archon/*/args.py。Check 要点核对from_pretrained/from_config的关键字参数dtype、attn_implementation、trust_remote_code、num_labels是否仍然存在AutoModelForImageTextToText这个入口名在 transformers 历次大版本中曾被改名不同时期叫AutoModelForVision2Seq等需确认目标版本中它仍存在、未被合并或更名确认from_config仍接受num_labelscritic 路径依赖它查找目标版本是否引入新的必填 kwarg。4.2PretrainedConfig上游源src/transformers/configuration_utils.py。调用分布在 fsdp_engine.py、megatron_engine.py、fsdp_utils/parallel.py、archon_engine.py、registry.py 及各 archon 模型的args.py典型用法# 类型注解 / isinstance 检查 config: PretrainedConfig # 属性访问常见模式 config.model_type config.num_attention_heads config.num_key_value_heads config.text_config.num_attention_heads # VLM 子配置Check 要点确认PretrainedConfig仍位于configuration_utils.py且仍是基类没有被移动VLM 的text_config子配置访问模式是否仍有效__init__是否新增了必填字段。值得一提的是areal/utils/hf_utils.py 中的save_hf_config正是针对PretrainedConfig.to_dict()序列化model_type的行为差异做了防护remote-code config 的model_type可能是实例字段而非类属性save_pretrained()会把它写成空字符串因此该函数保存后会回填并校验model_type、torch_dtype。这类“贴皮肤”的代码对上游序列化行为的细微变化非常敏感是 API 审计时要特别留意的消费点。4.3PreTrainedTokenizerFast与分词器方法上游源src/transformers/tokenization_utils_fast.py、tokenization_utils_base.py。核心调用点在 areal/utils/hf_utils.py 的load_hf_tokenizer当前仓库实际代码def load_hf_tokenizer( model_name_or_path: str, fast_tokenizerTrue, padding_side: str | None None, ) - transformers.PreTrainedTokenizerFast: kwargs {} if padding_side is not None: kwargs[padding_side] padding_side tokenizer transformers.AutoTokenizer.from_pretrained( model_name_or_path, fast_tokenizerfast_tokenizer, trust_remote_codeTrue, force_downloadFalse, **kwargs, ) if tokenizer.pad_token_id is None: tokenizer.pad_token_id tokenizer.eos_token_id return tokenizer同一文件中的load_hf_processor_and_tokenizer带lru_cache(maxsize8)随后用AutoProcessor.from_pretrained(..., trust_remote_codeTrue, force_downloadFalse, use_fastTrue)加载 processor失败时降级为仅 tokenizer 并告警——这是 VLM 训练路径的容错设计。分词器方法还被 areal/workflow/rlvr.py、multi_turn.py、vision_rlvr.py 高频调用tokenizer.decode(token_ids, ...)、tokenizer.apply_chat_template(messages, ...)、tokenizer.eos_token_id。Check 要点确认fast_tokenizer参数是否仍存在——部分历史版本中它叫use_fast需核对目标版本实际接受的参数名本条目是典型的“参数改名”高风险点确认apply_chat_template签名未变尤其tokenize、add_generation_prompt、return_tensors确认force_download仍被接受eos_token_id/pad_token_id仍是普通属性注意load_hf_processor_and_tokenizer带lru_cache——若返回类型发生变化缓存语义必须同步重新验证。这里也暴露了清单维护的一个真实问题清单原文档中的代码快照写的是force_downloadTrue、lru_cache标注在 tokenizer 函数上而当前仓库代码是force_downloadFalse、缓存标注在 processor 函数上。这正是 CHECKLIST_MAINTENANCE.md 要求每次升级前执行 Step 0.5“结构化校验”的原因——用 grep 重新发现全部调用点、与清单比对 MISSING/STALE/CHANGED把代码快照刷新为最新状态避免拿着过期快照做审计。4.4AutoProcessor/ProcessorMixin上游源src/transformers/processing_utils.py。调用点即上文 areal/utils/hf_utils.pyprocessor transformers.AutoProcessor.from_pretrained( model_name_or_path, trust_remote_codeTrue, force_downloadFalse, use_fastTrue, )另作为类型注解出现在 areal/infra/rpc/serialization.pyProcessorMixin与 areal/engine/fsdp_engine.py。Check 要点确认AutoProcessor.from_pretrained仍接受use_fastProcessorMixin仍可从transformers.ProcessorMixin顶层导入若 vision_rlvr.py 直接调用 processor 的前处理方法图像/文本预处理需核对这些方法签名。4.5 学习率调度器辅助函数上游源src/transformers/optimization.py。调用点在 areal/engine/fsdp_engine.py# linear 调度器 self.lr_scheduler get_linear_schedule_with_warmup( self.optimizer, num_warmup_steps, total_train_steps, ) # constant 调度器 self.lr_scheduler get_constant_schedule_with_warmup( self.optimizer, num_warmup_steps, )Check 要点这两个函数历史上曾被“软弃用”推荐统一的get_scheduler需确认目标版本中仍存在于transformers.optimization确认位置参数顺序(optimizer, num_warmup_steps, num_training_steps)未变返回类型仍是LambdaLR兼容的调度器。4.6transformers.set_seed上游源src/transformers/trainer_utils.py从顶层再导出。调用点在 areal/utils/seeding.py该文件把transformers.set_seed(seed)与random/numpy/torch的种子统一在一次set_random_seed中完成transformers.set_seed(seed)Check 要点确认set_seed仍从顶层transformers.set_seed导出签名仍是set_seed(seed: int)且无新增必填参数。4.7modeling_flash_attention_utils._flash_attention_forward高风险私有函数直导上游源src/transformers/modeling_flash_attention_utils.py。调用点在 areal/models/transformers/ulyssess_patch.pyfrom transformers.modeling_flash_attention_utils import _flash_attention_forward # 在 _ulysses_flash_attention_forward 内作为直通调用 attn_output _flash_attention_forward( query_states, key_states, value_states, *args, **kwargs, )Check 要点这是带下划线的私有函数。必须确认它在目标版本中仍存在于该精确导入路径且位置签名(query_states, key_states, value_states, ...)未变——任何参数换位或改名都会打断全部 Ulysses 序列并行注意力路径。从源码结构看它是 Ulysses 包装器内唯一真正调用 flash attention kernel 的位置先做gather_seq_scatter_heads的 SP 重分布再落到原实现因此是整个 SP 通路的咽喉。4.8integrations.flash_attention._flash_attention_forward高风险被 monkey-patch上游源src/transformers/integrations/flash_attention.py。它被两处 monkey-patchareal/models/transformers/ulyssess_patch.py非 VLM 模型约 244 行from transformers.integrations import flash_attention flash_attention._flash_attention_forward _ulysses_flash_attention_forwardareal/models/tree_attn/module_fsdp.py树注意力约 163–166 与 182–185 行采用“保存-替换-恢复”模式ORIGINAL_FLASH_ATTENTION_FORWARD flash_attention._flash_attention_forward flash_attention._flash_attention_forward _tree_attn_fwd_func # ... 使用完毕恢复 flash_attention._flash_attention_forward ORIGINAL_FLASH_ATTENTION_FORWARD ORIGINAL_FLASH_ATTENTION_FORWARD NoneCheck 要点确认transformers.integrations.flash_attention模块仍存在且仍暴露_flash_attention_forward属性——若模块改名、移动或函数被删上述 Ulysses 与树注意力 patch 会静默失效不抛异常、注意力退化为无 SP 的普通实现错误极难察觉。同时确认公开的flash_attention_forward无下划线仍存在——它被 qwen2_vl.py 与 qwen3_vl.py 直接导入。4.9 Qwen2-VL 内部符号高风险从私有模块导入上游源src/transformers/models/qwen2_vl/modeling_qwen2_vl.py。areal/models/transformers/qwen2_vl.py 直接导入内部 helperfrom transformers.models.qwen2_vl.modeling_qwen2_vl import ( apply_multimodal_rotary_pos_emb, repeat_kv, )ulyssess_patch.py 还用模块字符串表驱动地定位 patch 目标约 176–204 行qwen2_vl: { module: transformers.models.qwen2_vl.modeling_qwen2_vl, attn_class: Qwen2VLAttention, model_class: Qwen2VLTextModel, patch_module: areal.models.transformers.qwen2_vl, patch_attn_func: ulysses_flash_attn_forward, }patch 的落点是attn_class.forward patch_attn_func替换Qwen2VLAttention.forward。Check 要点确认apply_multimodal_rotary_pos_emb与repeat_kv仍从该子模块导出它们是内部 helper不属于公开 API重构时最容易被挪走确认Qwen2VLAttention、Qwen2VLTextModel类名未变确认Qwen2VLAttention.forward的签名仍与 qwen2_vl.py 中的ulysses_flash_attn_forward(self, hidden_states, attention_mask, position_ids, position_embeddings, **kwargs)兼容。4.10 Qwen2.5-VL 内部符号高风险按模块字符串访问上游源src/transformers/models/qwen2_5_vl/。ulyssess_patch.py 通过字符串表访问qwen2_5_vl: { module: transformers.models.qwen2_5_vl.modeling_qwen2_5_vl, attn_class: Qwen2_5_VLAttention, model_class: Qwen2_5_VLTextModel, patch_module: areal.models.transformers.qwen2_vl, # 复用 Qwen2-VL 的同一个 patch 函数 patch_attn_func: ulysses_flash_attn_forward, }注意Qwen2.5-VL 复用Qwen2-VL 的同一份patch 函数patch_module指向qwen2_vl并非独立文件——这意味着两者的Attention.forward签名必须一致。Check 要点确认子模块路径transformers.models.qwen2_5_vl.modeling_qwen2_5_vl未变Qwen2_5_VLAttention、Qwen2_5_VLTextModel类名仍存在Qwen2_5_VLAttention.forward与Qwen2VLAttention.forward签名保持一致因为共享同一个 patch 函数。4.11 Qwen3-VL 内部符号高风险独立 patch 签名上游源src/transformers/models/qwen3_vl/modeling_qwen3_vl.py。areal/models/transformers/qwen3_vl.py 导入from transformers.integrations.flash_attention import flash_attention_forward from transformers.models.qwen3_vl.modeling_qwen3_vl import ( apply_rotary_pos_emb, repeat_kv, )模块字符串表条目qwen3_vl: { module: transformers.models.qwen3_vl.modeling_qwen3_vl, attn_class: Qwen3VLTextAttention, model_class: Qwen3VLTextModel, patch_module: areal.models.transformers.qwen3_vl, patch_attn_func: ulysses_flash_attn_forward, }与 Qwen2-VL 不同Qwen3-VL 有自己的 patch 函数qwen3_vl.py签名已变化多了position_embeddings参数def ulysses_flash_attn_forward( self, hidden_states, position_embeddings, attention_maskNone, past_key_valuesNone, cache_positionNone, **kwargs, ) - tuple[torch.Tensor, torch.Tensor | None]: ...Check 要点确认apply_rotary_pos_emb、repeat_kv仍在该路径Qwen3VLTextAttention、Qwen3VLTextModel类名未变Qwen3VLTextAttention.forward签名与 patch 完全匹配(self, hidden_states, position_embeddings, attention_mask, past_key_values, cache_position, **kwargs)——签名任何漂移都会直接破坏 Qwen3-VL 的 Ulysses SP。4.12transformers.utils.import_utils.is_torch_npu_available上游源src/transformers/utils/import_utils.py。调用点在 areal/infra/platforms/init.pyfrom transformers.utils.import_utils import is_torch_npu_available is_npu_available is_torch_npu_available()该模块是 AReaL 平台探测CUDA → ROCm → NPU → CPU 优先级的入口之一。Check 要点确认函数仍在transformers.utils.import_utils这一私有子模块路径私有 utils 模块最容易被重构挪动确认没有被替代为其他 NPU 探测机制。4.13 Version-Guarded Code版本守卫代码清单末尾的结论是AReaL 当前没有针对transformers的已知版本守卫代码即不存在if version x.y.z之类的条件分支。这意味着升级后没有可清理的死代码但也意味着没有任何“版本适配层”兜底——所有兼容性问题都会以直接报错的形式暴露在首次运行中清单的完整性因此更加关键。5. 清单如何被使用与维护这份清单不是静态文档而是升级流水线的活动工件参与三个环节5.1 升级前Step 0.5 结构化校验对每个被点名的聚焦包按 CHECKLIST_MAINTENANCE.md §3 执行用包特定的 grep 模式对 transformers 是from transformers/import transformers需排除flash_attn.bert_padding这类误报扫描areal/、tests/、examples/与清单三层表比对产出 MISSING代码里有、清单没有/ STALE清单里有、代码里没了/ CHANGED导入内容与登记不符三类差异按“目录位置定层级”的规则补表、为新调用模式补 API 目录条目、删除过期条目并重排序号输出变更报告新增 N 个文件、M 个目录条目、移除 K 个过期条目后才允许动依赖。第 4.3 节展示的force_download快照漂移就是 Step 0.5 要拦截的典型问题。5.2 升级中Step 6 API 审计对清单 frontmatter 中的githubbranch_template浅克隆目标 tag然后逐条对照 API 目录打开upstream_paths列出的上游文件比对每个 AReaL 调用点的签名把发现按“必须修改调用点 / 只需记录 / 需查迁移指南”分类修复顺序遵循引擎层 → 模型层 → 基础设施层 → 测试文件的优先级且“只改必须改的不顺手重构”。遇到无法自动解决的破坏性变化时流程会停下并向用户确认。5.3 升级后Step 6e 内容回写按维护指南 §4 回写清单更新发生变化的 API 签名、被 6d 修改过的调用点代码快照含行号、版本守卫条目、upstream_paths与branch_template并同步 SKILL.md 底部“Checklist File Status”表的条目计数transformers 当前登记为 12 个 API 条目。5.4 写新条目的边界何时不建条目维护指南 §7 明确了四个“不建条目”的场景理解它有助于读懂本清单为什么只有 12 条而不是几十条纯类型导入仅为类型注解或isinstance导入的类如仅用作config: PretrainedConfig的文件只在 Affected Files 登记再导出/直通只转发符号不调用的文件稳定公开 API访问__version__、基础枚举值等从不变化的接口测试重复覆盖测试文件若与 Primary/Secondary 条目使用完全相同的 API 模式本清单中 30 个 tests/examples 文件即属此类归入 Tertiary 即可。“拿不准就建条目”是兜底原则——宁可有冗余的清单条目也不能有漏掉破坏性变化的空档。6. 小结把“依赖风险”变成可执行文档checklists/transformers.md 的价值在于把“transformers 升一个版本会不会炸”这个模糊问题拆解为 12 个可以逐条勾选、每条都有上游源路径 AReaL 调用点 明确核对项的审计单元并用三层 Affected Files 表标出爆炸半径引擎层的 Auto*/调度器调用是常规面真正的高风险集中在_flash_attention_forward私有函数的直导与 monkey-patch条目 7、8以及 Qwen2-VL / Qwen2.5-VL / Qwen3-VL 三个私有建模模块的内部符号条目 9–11——后者一旦上游重构patch 会静默失效必须靠清单显式盯防。配合 SKILL.md 的 Step 0.5升级前校验与 Step 6审计 回写这份清单在每一次版本跳跃前后都会被重新对齐仓库现状是 AReaL 双变体SGLang/vLLM依赖体系中共享依赖治理的标准范例。适用前提本清单反映当前仓库 transformers 5.x 约束pyproject.toml中5.0.0,5.3.0pyproject.vllm.toml中5.0且排除若干小版本下的调用面行号引用以清单编写时的代码状态为准实际审计时应以 Step 0.5 重新 grep 的结果为最终依据。【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考