SuperAPI AI 工具集

transformers-upgrade

编程与开发

查看项目

更新于 10-28 23:59

技能介绍

该技能是 vLLM 仓库中用于变更 Transformers 版本边界的操作手册。支持范围位于 requirements/common.txt,CI 在 requirements/test/.in 与编译后的 requirements/test/.txt 中固定一个精确版本。版本变更通常分为两项任务,且往往成对出现。

一、提升固定版本(Bump the pin) 新的 Transformers 发布成为 CI 版本与上限,vLLM 为其增加兼容代码。需编辑各 requirements/test/*.in 和 *.txt 中的 pin 行,以及 requirements/common.txt 中的上限;过往升级只改编译文件中的 pin 行,可参考 git log -- requirements/common.txt。需阅读发布说明,关注配置校验变化、自动映射格式重命名和属性移除等问题。应在 tests/ 中搜索命名新版本的 min_transformers_version 和 skip 标记,并在新 pin 上运行这些测试;门槛保留条件是新版本达到下限后才移除。运行 Testing 部分的套件并修复问题,每个兼容层标注 # Transformers >= X 注释,以便下次提高下限时定位。完成标准是 Testing 套件及所有以该版本为门槛的测试在新 pin 上通过。

二、提高下限(Raise the floor,去内置化流程)

  1. 盘点:在下限版本已安装的情况下运行脚本 find_upstreamed.py,列出上游已接管的 vendored 配置、_CONFIG_REGISTRY 中的上游类型覆盖、与上游类名或模型冲突的已注册处理器、位于或低于下限的版本门槛代码、读取已安装 Transformers 版本的代码,以及引用 Transformers issue/PR 或未来最低版本的补丁。脚本仅按名称查找,每个命中项仍需人工判定。
  2. 将每个候选项移植到上游:默认删除所有命中项,将 vLLM 模型代码移植到上游 schema,重命名属性读取并由上游字段推导值。可将候选项分发给并行子代理,比较 vendored 与上游类并 grep vLLM 模型代码读取的每个属性。仅在 upstream 无法加载 vLLM 必须继续服务的检查点时保留 vendored 类,并在 PR 描述中记录原因。
  3. 在真实检查点上验证:对 tests/models/registry.py 中所有使用被移植配置的检查点,分别在变更前后转储 vLLM 构建结果并比较。dump_configs.py 逐属性记录解析后的配置;dump_model.py 在 meta 设备上构建模型,记录 ModelConfig 尺寸、参数形状和各模块标量属性。使用 git worktree 检出基准版本,分别运行两个转储并执行 diff_dumps.py。对 config.json 含 auto_map 的检查点添加 --trust-remote-code 并两种方式都转储。读取差异:模型读取的 <MISSING> 配置字段会导致崩溃或静默回退默认值,需移植模型代码;新的上游专属默认值通常无害,模型差异为 0 可确认;任何模型差异都是数值变化,PR 需要模型评估。
  4. 删除:删除文件;从 vllm/transformers_utils/configs/init.py 的 _CLASS_TO_MODULE 和 all 移除条目;从 vllm/transformers_utils/config.py 的 _CONFIG_REGISTRY 移除条目;将所有导入方(含测试)改为 from transformers import ...;从 .buildkite/ 移除命名该文件的 source_file_dependencies 行。处理器按相同步骤在 processors/init.py 中处理。合并前需 rebase 并再次 grep 旧字段名。完成标准是盘点输出每一行都已删除,或保留理由符合第 2 步标准;PR 同时附带配置差异结果和任何值变更的评估。

三、上游化风险 手册以表格列出常见风险、信号与修复方式,包括:上游消费遗留键、字段重命名或删除、未声明字段无默认值、顶层配置不再转发、配置类型检查依赖 vendored 基类、远程代码接管、上游只读字段、行为性重写、原始检查点格式、处理器输出契约和名称冲突。版本门槛代码需决策:仅低于下限可达的代码删除;条件恒为真的 skipif 变为同理由的无条件 skip;位于或低于下限的 min_transformers_version 移除;低于下限的 max_transformers_version 意味着 CI 从未测试该模型,应报告而非静默删除。引用 Transformers issue/PR 的补丁:修复已在下限发布中则删除;对 issue 需找到关闭它的 PR 并核查;删除前重新运行被修补的行为。

四、测试 运行 pytest tests/transformers_utils tests/config tests/tokenizers_;运行 pytest tests/models/multimodal/processing/test_common.py -k "<models>";在可用 GPU 时添加 tests/models/test_initialization.py -k "<archs>",并对解析配置发生变化的模型进行模型评估。vllm/models/ 中的模型为高优先级:配置或模型代码变化时,即使转储无差异,也需在 main 和分支上运行 GSM8k 与 GPQA Diamond 并附上两项分数;由于 FlashInfer 自动调优会在每次服务启动时重新选择内核策略,两个服务都应传入 --kernel-config '{"enable_flashinfer_autotune": false}' 以保证贪心输出可比。

适用场景:vLLM 维护者升级 Transformers 依赖、清理兼容层、移植 vendored 配置或处理器时使用。限制:该手册针对 vLLM 仓库内部流程,依赖仓库内脚本与测试结构;部分验证步骤需要 GPU 与模型评估环境。