如何在 Transformers exporters 中注册自定义 patch 与 fix 处理不支持的模型【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers当你用 Transformers 的 exportersDynamoExporter、OnnxExporter、ExecutorchExporter把模型导出到某个后端时如果模型里存在后端无法处理的 PyTorch 模式——例如某个方法无法被torch.export追踪、某个算子无法被 ONNX 翻译——官方做法不是去改 modeling 代码而是向 exporter 的注册表登记一个 workaround写成一个小函数用装饰器注册exporter 会在导出的正确阶段自动安装它。这篇文档就讲这条操作路径适用于三个内置后端Dynamo / ONNX / ExecuTorch。patch 和 fix 怎么选择文档把 workaround 分为两类区别在于能否被还原见 exporters_extend.mdPatchFix做什么在导出期间把某个属性torch算子、ExecuTorch 内部实现或模型方法换成替代物重写追踪得到的图或程序是否还原是导出结束后恢复原对象否它在下一阶段运行前修复产物注册方式register_patch(backend, *paths)register_fx_node_fix(backend)或register_fx_program_fix(backend)文档给出的选择标准问题只出在单个后端的 lowering 上缺 ONNX 翻译、ORT 校验怪癖、FX 分解产生死算子时用 patch模式在多个后端都阻塞导出数据依赖循环、Cache之外的有状态缓存、手写 split-loop attention时应该直接修模型因为一次修复对所有 exporter 都有效。所有注册项存放在 src/transformers/exporters/utils.py 的注册表中_PATCHES/_FX_NODE_FIXES/_FX_PROGRAM_FIXESexporter 在对应阶段通过apply_patches/apply_fx_node_fixes/apply_fx_program_fixes一次性安装该 backend 的全部注册项。准备条件安装与版本固定exporters 目前是实验性的文档明确警告许多 patch 是针对特定上游 bugTorch、ONNX Script、ONNX Runtime、ExecuTorch的临时方案上游修复后会被移除在 API 稳定之前把 patch 视为与测试套件使用的版本绑定。因此生产工具里要固定文档给出的测试版本见 exporters.md 的 Installation 一节# Dynamo 后端 pip install transformers torch2.12.0 # ONNX 后端 pip install transformers torch2.12.0 onnx1.21.0 onnxscript0.7.0 onnxruntime # ExecuTorch 后端 pip install transformers torch2.12.0 executorch1.3.1版本漂移不会直接报错但HfExporter会打印警告behaviour may differ from what was validated遇到导出异常时应优先回到测试版本排查。注册一个 patch以文档给出的完整例子为准NLLB-MoE 的NllbMoeTop2Router._cast_classifier会把分类器权重 cast 到另一个 dtypetorch.export无法追踪。做法是写一个工厂函数——接收原方法、返回替代物——然后针对该方法的全限定点分路径注册from transformers.exporters.utils import register_patch register_patch(dynamo, transformers.models.nllb_moe.modeling_nllb_moe.NllbMoeTop2Router._cast_classifier) def _patch_classifier_cast(_original): # Replace the untraceable dtype cast with a no-op during export. return lambda self, *args, **kwargs: None导出期间 exporter 会在追踪前换上这个方法、追踪后恢复所以 patch 只影响导出流程。register_patch的机制在 utils.py 的 docstring 中有完整说明path是点分 Python 路径如torch.where、torch.Tensor.unsqueeze最右段是要替换的属性名其余是所属对象路径在装饰时解析解析失败比如对应后端没装会静默跳过模块仍能导入。传多个路径可以让同一个工厂作用于多个调用点例如register_patch(dynamo, path_a, path_b)或register_patch(onnx, torch.unsqueeze, torch.Tensor.unsqueeze)。想 patch 一个torch算子时把路径指向它即可例如register_patch(onnx, torch.where)工厂会收到真实算子作为参数替代实现可以透传调用它。各后端对应的扩展点在 exporter_dynamo.py、exporter_onnx.py、exporter_executorch.py 中文档建议用源码里的# ── Stage N: … ──注释块对号入座。各阶段与注册方式摘自 exporters_extend.md 的 Stage reference后端用 patch 解决的阶段用 fix 解决的阶段DynamoExporterStage 2 Model patchesregister_patch(dynamo, ...)—OnnxExporterStage 1/2 Torch / ONNX patchesregister_patch(onnx, ...)Stage 3 FX node fixesregister_fx_node_fix(onnx)ExecutorchExporterStage 2/3 Torch / ExecuTorch patchesregister_patch(executorch, ...)含executorch.xnnpack、executorch.cuda等后端子键Stage 4 FX program fixesregister_fx_program_fix(executorch)Stage 5 FX node fixesregister_fx_node_fix(executorch)注意 ONNX 的 Stage 4自定义 aten 算子翻译和 Stage 5ONNX IR 修复不走注册器而是分别往_ONNX_TRANSLATION_TABLE加_aten_*函数、往_IR_FIXES加_fix_ir_*函数——这两种是文件内的列表扩展不是装饰器注册。注册一个 fix如果需要重写追踪之后的图或程序用 fix 注册表机制相同在对应 backend 的注册表里放一个带装饰器的函数。函数签名约束来自 utils.pyregister_fx_node_fix(backend)函数签名为(gm, node) - bool逐节点处理call_function节点返回True表示该 fix 已消费此节点后续 fix 不再作用于它。apply_fx_node_fixes遍历所有子 GraphModulewalk 结束后对每个子图执行eliminate_dead_code()并调用gm.recompile()。参考实现exporter_onnx.py 中有 10 个register_fx_node_fix(onnx)条目alias 算子、in-place view、死 assert 等exporter_executorch.py 中有 5 个register_fx_node_fix(executorch)条目。register_fx_program_fix(backend)函数签名为(exported_program) - None用于需要程序级上下文的修复range_constraints、graph_signature、state_dict因为逐节点 fix 一次只能看到一个节点。ExecuTorch 用它放宽 range 约束、补全缺失的 placeholder metadata见 exporter_executorch.py 中的 3 个register_fx_program_fix(executorch)条目。让导出流程真正安装并验证结果注册发生在 Python 模块导入时装饰器执行即登记安装发生在export调用内部如 exporter_dynamo.py 中with apply_patches(dynamo)包住torch.export.export。因此只要保证你的注册函数所在模块在调用exporter.export(...)之前被 import导出的产物就会带上你的 workaround。用文档中的最小导出流程做端到端验证Dynamo 后端——导出后直接运行导出图from transformers import AutoModelForCausalLM, AutoTokenizer from transformers.exporters import DynamoExporter, DynamoConfig model AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen3-0.6B) inputs tokenizer(Hello, world!, return_tensorspt) exporter DynamoExporter() config DynamoConfig(dynamicTrue) exported exporter.export(model, inputs, configconfig) # run the exported graph directly outputs exported.module()(**inputs)ONNX 后端——保存为.onnx并用 ONNX Runtime 会话跑一次这一步能暴露 patch 没有正确覆盖节点翻译的问题from transformers import AutoModelForCausalLM, AutoTokenizer from transformers.exporters import OnnxExporter, OnnxConfig model AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen3-0.6B) inputs tokenizer(Hello, world!, return_tensorspt) exporter OnnxExporter() config OnnxConfig(dynamicTrue) onnx_program exporter.export(model, inputs, configconfig) onnx_program.save(model.onnx) import onnxruntime as ort session ort.InferenceSession(model.onnx) ort_inputs {k: v.numpy() for k, v in inputs.items()} outputs session.run(None, ort_inputs)排查与限制patch 解析失败是静默的register_patch在路径解析不到时直接跳过该路径不报错。如果你的 patch 看起来没生效先确认路径拼写和对应后端是否已安装。patch 与 fix 的适用边界patch 只替换单个后端的属性且导出后还原fix 直接改写产物且不可还原。把本可用 patch 解决的问题写成 fix或反之都会让 workaround 落在错误的阶段。跨后端问题不要靠 patch 解决文档明确建议此类模式数据依赖循环等修模型本身。测试套件中的例外清单有纪律要求tests/exporters/test_export.py 中ONNX_DISABLE_OPTIMIZE的每个条目必须对应一个具体的上游 bugonnxscript图优化器在SplitToSequence常量折叠崩溃、FPN initializer 丢失等EXPORT_SKIPS的每个条目必须写明模型侧需要做的修改。两份清单预期缩短而非增长——如果你给测试体系加跳过条目也要遵循这个引用规范。生命周期限制这些 workaround 都是临时的上游修复落地后会被删除旧 patch 会随版本变化消失新 patch 会随上游变化出现生产环境务必按上文固定版本并留意HfExporter的版本漂移警告。完成上述步骤后判断标准只有一个export不再在问题模式上失败且导出的产物ExportedProgram/ONNXProgram/ ExecuTorch 程序能按文档示例方式实际跑通一次输入。若导出仍失败回到 exporter 源码中对应的# ── Stage N ──注释块确认你登记的 backend 键与该阶段由哪次apply_*调用安装是否对得上。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何在 Transformers exporters 中注册自定义 patch 与 fix 处理不支持的模型？
如何在 Transformers exporters 中注册自定义 patch 与 fix 处理不支持的模型【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers当你用 Transformers 的 exportersDynamoExporter、OnnxExporter、ExecutorchExporter把模型导出到某个后端时如果模型里存在后端无法处理的 PyTorch 模式——例如某个方法无法被torch.export追踪、某个算子无法被 ONNX 翻译——官方做法不是去改 modeling 代码而是向 exporter 的注册表登记一个 workaround写成一个小函数用装饰器注册exporter 会在导出的正确阶段自动安装它。这篇文档就讲这条操作路径适用于三个内置后端Dynamo / ONNX / ExecuTorch。patch 和 fix 怎么选择文档把 workaround 分为两类区别在于能否被还原见 exporters_extend.mdPatchFix做什么在导出期间把某个属性torch算子、ExecuTorch 内部实现或模型方法换成替代物重写追踪得到的图或程序是否还原是导出结束后恢复原对象否它在下一阶段运行前修复产物注册方式register_patch(backend, *paths)register_fx_node_fix(backend)或register_fx_program_fix(backend)文档给出的选择标准问题只出在单个后端的 lowering 上缺 ONNX 翻译、ORT 校验怪癖、FX 分解产生死算子时用 patch模式在多个后端都阻塞导出数据依赖循环、Cache之外的有状态缓存、手写 split-loop attention时应该直接修模型因为一次修复对所有 exporter 都有效。所有注册项存放在 src/transformers/exporters/utils.py 的注册表中_PATCHES/_FX_NODE_FIXES/_FX_PROGRAM_FIXESexporter 在对应阶段通过apply_patches/apply_fx_node_fixes/apply_fx_program_fixes一次性安装该 backend 的全部注册项。准备条件安装与版本固定exporters 目前是实验性的文档明确警告许多 patch 是针对特定上游 bugTorch、ONNX Script、ONNX Runtime、ExecuTorch的临时方案上游修复后会被移除在 API 稳定之前把 patch 视为与测试套件使用的版本绑定。因此生产工具里要固定文档给出的测试版本见 exporters.md 的 Installation 一节# Dynamo 后端 pip install transformers torch2.12.0 # ONNX 后端 pip install transformers torch2.12.0 onnx1.21.0 onnxscript0.7.0 onnxruntime # ExecuTorch 后端 pip install transformers torch2.12.0 executorch1.3.1版本漂移不会直接报错但HfExporter会打印警告behaviour may differ from what was validated遇到导出异常时应优先回到测试版本排查。注册一个 patch以文档给出的完整例子为准NLLB-MoE 的NllbMoeTop2Router._cast_classifier会把分类器权重 cast 到另一个 dtypetorch.export无法追踪。做法是写一个工厂函数——接收原方法、返回替代物——然后针对该方法的全限定点分路径注册from transformers.exporters.utils import register_patch register_patch(dynamo, transformers.models.nllb_moe.modeling_nllb_moe.NllbMoeTop2Router._cast_classifier) def _patch_classifier_cast(_original): # Replace the untraceable dtype cast with a no-op during export. return lambda self, *args, **kwargs: None导出期间 exporter 会在追踪前换上这个方法、追踪后恢复所以 patch 只影响导出流程。register_patch的机制在 utils.py 的 docstring 中有完整说明path是点分 Python 路径如torch.where、torch.Tensor.unsqueeze最右段是要替换的属性名其余是所属对象路径在装饰时解析解析失败比如对应后端没装会静默跳过模块仍能导入。传多个路径可以让同一个工厂作用于多个调用点例如register_patch(dynamo, path_a, path_b)或register_patch(onnx, torch.unsqueeze, torch.Tensor.unsqueeze)。想 patch 一个torch算子时把路径指向它即可例如register_patch(onnx, torch.where)工厂会收到真实算子作为参数替代实现可以透传调用它。各后端对应的扩展点在 exporter_dynamo.py、exporter_onnx.py、exporter_executorch.py 中文档建议用源码里的# ── Stage N: … ──注释块对号入座。各阶段与注册方式摘自 exporters_extend.md 的 Stage reference后端用 patch 解决的阶段用 fix 解决的阶段DynamoExporterStage 2 Model patchesregister_patch(dynamo, ...)—OnnxExporterStage 1/2 Torch / ONNX patchesregister_patch(onnx, ...)Stage 3 FX node fixesregister_fx_node_fix(onnx)ExecutorchExporterStage 2/3 Torch / ExecuTorch patchesregister_patch(executorch, ...)含executorch.xnnpack、executorch.cuda等后端子键Stage 4 FX program fixesregister_fx_program_fix(executorch)Stage 5 FX node fixesregister_fx_node_fix(executorch)注意 ONNX 的 Stage 4自定义 aten 算子翻译和 Stage 5ONNX IR 修复不走注册器而是分别往_ONNX_TRANSLATION_TABLE加_aten_*函数、往_IR_FIXES加_fix_ir_*函数——这两种是文件内的列表扩展不是装饰器注册。注册一个 fix如果需要重写追踪之后的图或程序用 fix 注册表机制相同在对应 backend 的注册表里放一个带装饰器的函数。函数签名约束来自 utils.pyregister_fx_node_fix(backend)函数签名为(gm, node) - bool逐节点处理call_function节点返回True表示该 fix 已消费此节点后续 fix 不再作用于它。apply_fx_node_fixes遍历所有子 GraphModulewalk 结束后对每个子图执行eliminate_dead_code()并调用gm.recompile()。参考实现exporter_onnx.py 中有 10 个register_fx_node_fix(onnx)条目alias 算子、in-place view、死 assert 等exporter_executorch.py 中有 5 个register_fx_node_fix(executorch)条目。register_fx_program_fix(backend)函数签名为(exported_program) - None用于需要程序级上下文的修复range_constraints、graph_signature、state_dict因为逐节点 fix 一次只能看到一个节点。ExecuTorch 用它放宽 range 约束、补全缺失的 placeholder metadata见 exporter_executorch.py 中的 3 个register_fx_program_fix(executorch)条目。让导出流程真正安装并验证结果注册发生在 Python 模块导入时装饰器执行即登记安装发生在export调用内部如 exporter_dynamo.py 中with apply_patches(dynamo)包住torch.export.export。因此只要保证你的注册函数所在模块在调用exporter.export(...)之前被 import导出的产物就会带上你的 workaround。用文档中的最小导出流程做端到端验证Dynamo 后端——导出后直接运行导出图from transformers import AutoModelForCausalLM, AutoTokenizer from transformers.exporters import DynamoExporter, DynamoConfig model AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen3-0.6B) inputs tokenizer(Hello, world!, return_tensorspt) exporter DynamoExporter() config DynamoConfig(dynamicTrue) exported exporter.export(model, inputs, configconfig) # run the exported graph directly outputs exported.module()(**inputs)ONNX 后端——保存为.onnx并用 ONNX Runtime 会话跑一次这一步能暴露 patch 没有正确覆盖节点翻译的问题from transformers import AutoModelForCausalLM, AutoTokenizer from transformers.exporters import OnnxExporter, OnnxConfig model AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen3-0.6B) inputs tokenizer(Hello, world!, return_tensorspt) exporter OnnxExporter() config OnnxConfig(dynamicTrue) onnx_program exporter.export(model, inputs, configconfig) onnx_program.save(model.onnx) import onnxruntime as ort session ort.InferenceSession(model.onnx) ort_inputs {k: v.numpy() for k, v in inputs.items()} outputs session.run(None, ort_inputs)排查与限制patch 解析失败是静默的register_patch在路径解析不到时直接跳过该路径不报错。如果你的 patch 看起来没生效先确认路径拼写和对应后端是否已安装。patch 与 fix 的适用边界patch 只替换单个后端的属性且导出后还原fix 直接改写产物且不可还原。把本可用 patch 解决的问题写成 fix或反之都会让 workaround 落在错误的阶段。跨后端问题不要靠 patch 解决文档明确建议此类模式数据依赖循环等修模型本身。测试套件中的例外清单有纪律要求tests/exporters/test_export.py 中ONNX_DISABLE_OPTIMIZE的每个条目必须对应一个具体的上游 bugonnxscript图优化器在SplitToSequence常量折叠崩溃、FPN initializer 丢失等EXPORT_SKIPS的每个条目必须写明模型侧需要做的修改。两份清单预期缩短而非增长——如果你给测试体系加跳过条目也要遵循这个引用规范。生命周期限制这些 workaround 都是临时的上游修复落地后会被删除旧 patch 会随版本变化消失新 patch 会随上游变化出现生产环境务必按上文固定版本并留意HfExporter的版本漂移警告。完成上述步骤后判断标准只有一个export不再在问题模式上失败且导出的产物ExportedProgram/ONNXProgram/ ExecuTorch 程序能按文档示例方式实际跑通一次输入。若导出仍失败回到 exporter 源码中对应的# ── Stage N ──注释块确认你登记的 backend 键与该阶段由哪次apply_*调用安装是否对得上。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
