Transformers Exporters 主类 API 详解HfExporter、三大后端导出器与配置/工具函数参考【免费下载链接】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 的 Exporters 主类参考文档为主体系统讲解HfExporter抽象基类、AutoHfExporter/AutoExportConfig自动分派类、三个内置导出器Dynamo/ONNX/ExecuTorch、三类导出配置以及decompose_for_generation背后的底层工具函数。读完本文你可以掌握从任意PreTrainedModel导出到 PyTorch 程序、ONNX 或 ExecuTorch 的完整 API 用法并具备自定义新导出后端的扩展能力。Exporters 模块位于 src/transformers/exporters/由 6 个核心文件组成文件职责base.py抽象基类HfExporter与生成式导出入口export_for_generationauto.pyAutoHfExporter/AutoExportConfig工厂与注册表configs.pyExportConfigMixin基类与DynamoConfig/OnnxConfig/ExecutorchConfigexporter_dynamo.pyDynamoExporter输出ExportedProgramexporter_onnx.pyOnnxExporter输出ONNXProgramexporter_executorch.pyExecutorchExporter输出ExecutorchProgramManagerutils.pypatch/fix 注册表、张量工具、生成流程分解函数三个后端导出的产物与目标运行时如下摘自 docs/source/en/exporters.mdExporter输出产物目标运行时DynamoExporterExportedProgram任意 PyTorch 运行时、AOT 编译OnnxExporterONNXProgram任意 ONNX 运行时ONNX Runtime、TensorRT、OpenVINOExecutorchExporterExecutorchProgramManager移动与边缘设备ExecuTorch需要提醒的是官方文档明确标注exporters 目前处于实验阶段模块内大量补丁用于绕过上游Torch、ONNX Script、ONNX Runtime、ExecuTorch的具体 bug上游修复后会被移除。生产工具链应固定测试套件所锁定的依赖版本当HfExporter检测到版本漂移时也会记录警告这一点由源码中的validate_environment保证见下文。HfExporter所有导出器的抽象基类HfExporter定义在 base.py是整个模块的扩展契约新导出后端通过继承HfExporter并实现抽象方法export加入 Transformers。类级依赖声明与运行时校验每个具体导出器在类体上声明三类元数据见 base.py#L50-L54required_packages运行该导出器必须安装的包min_versions硬性最低版本低于此版本直接抛错tested_versions导出器所验证过的版本不一致时仅告警。__init__会调用validate_environment()其实现base.py#L59-L99采用单次遍历策略一次性收集所有缺失包与版本漂移最后统一报告而不是遇到第一个缺失就失败本地版本后缀如cu126、cpu会被剥离后再比较因为补丁针对的是公共 API 而非构建缺失包会抛出携带安装建议的ImportError版本漂移则记录一条警告提示exporter 是实验性的、补丁了多处后端内部实现请改用测试版本。三个内置导出器的实际声明如下Exporterrequired_packagestested_versionsDynamoExportertorch最低2.11.0torch 2.12.0OnnxExportertorch,onnx,onnxscripttorch 2.12.0,onnx 1.21.0,onnxscript 0.7.0ExecutorchExportertorch,executorchtorch 2.12.0,executorch 1.3.1对应的安装命令版本与导出器测试套件锁定一致见 exporter_dynamo.py#L83-L85、exporter_onnx.py#L102-L103、exporter_executorch.py#L123-L124# 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.1export 抽象方法export的签名base.py#L101-L131是所有导出器统一遵守的契约def export(self, model, sample_inputs, config): Args: model (PreTrainedModel): 要导出的模型。 sample_inputs (dict[str, torch.Tensor | Cache]): **forward** kwargs——即你传给 model(**sample_inputs) 的参数 直接用作追踪阶段的示例输入。导出自回归 decode 步骤时 需自行包含 past_key_values、cache_position 等。 如果手里只有 generate 风格的输入请改用 export_for_generation。 config (ExportConfigMixin): 后端特定配置。 Returns: 后端特定的导出产物。 要点sample_inputs是forward kwargs不是 generate kwargs这与export_for_generation的入参语义不同是文档中最容易混淆的一处。export_for_generation生成式模型的一键分解导出export_for_generationbase.py#L133-L205是生成式模型导出的主入口它是decompose_for_generation的薄封装先分解出各组件的(submodel, forward_inputs)对再对每个组件调用export。关键行为config可以传单个配置对象应用于所有组件也可以传以组件名为键的 dict如image_encoder、language_model、lm_head、decode做逐组件覆盖——此时 dict 必须覆盖所有组件缺键会抛出明确的ValueErrorbase.py#L184-L191generation_config会转发给捕获阶段的generate()传cache_implementationstaticmax_cache_len即可针对固定大小的StaticCache导出multi_token_decodeTrue使decode组件捕获为多 token 解码动态查询轴仅在动态形状导出下保持符号化任一组件导出失败时异常会被包装为携带组件名、子模型类型与输入键名的RuntimeError便于定位base.py#L195-L204。返回值是{组件名: 后端产物}产物类型取决于具体后端Dynamo 为ExportedProgramONNX 为ONNXProgramExecuTorch 为ExecutorchProgramManager。配置类ExportConfigMixin 及其三个子类配置基类ExportConfigMixinconfigs.py#L35-L72是一个 dataclass提供to_dict/from_dict序列化能力使配置可以在不感知具体子类的情况下存取export_format字段ExportFormat枚举取值executorch/dynamo/onnx在反序列化时用于识别子类。DynamoConfigDynamoConfigconfigs.py#L75-L106对应torch.export导出字段如下字段类型 / 默认值说明dynamicbool默认False是否为动态符号化形状导出。为True且未显式给出dynamic_shapes时所有张量维度自动标记为Dim.AUTOstrictbool默认False是否启用torch.export严格模式。会执行完整符号化追踪、捕获更多错误但更慢复杂模型上更易失败dynamic_shapesdict或None显式的逐输入动态形状规格直接传给torch.export优先级高于dynamicprefer_deferred_runtime_asserts_over_guardsbool默认False数据相关的形状 guard 以运行时断言形式进入导出图而不是在 guard 无法覆盖整个符号区间时直接让导出失败。使用细粒度Dim(min, max)边界的 Transformer LLM 通常需要置TruedynamicTrue/Dim.AUTO下由torch.export推断形状关系则不需要OnnxConfigOnnxConfig继承DynamoConfig的全部字段另加configs.py#L109-L149字段类型 / 默认值说明output_pathstr/PathLike或None.onnx输出路径。None默认时模型保留在内存中的ONNXProgram不落盘opset_versionint或None目标 ONNX opset 版本默认取已安装onnxscript支持的最新版external_databool默认True大权重张量存到独立的.onnx_data旁挂文件而非内嵌 protobuf。权重超过 2 GB protobuf 上限的模型必须开启optimizebool默认True运行onnxscript优化通道常量折叠、死代码消除等撞上上游优化器 bug 的模型可关闭export_paramsbool默认True将模型权重嵌入 ONNX 图。置False导出无权重图权重需运行时提供keep_initializers_as_inputsbool默认False将权重 initializer 暴露为显式图输入部分旧版 ONNX 运行时opset 9需要ExecutorchConfigExecutorchConfig同样继承DynamoConfigconfigs.py#L152-L185字段类型 / 默认值说明backendstr默认xnnpack目标 ExecuTorch 后端。xnnpack走 XNNPACK 库的 CPU 推理默认CPU 环境即可运行cuda走 GPU 推理无 CUDA 环境请求它会抛RuntimeErroralloc_graph_inputbool默认True内存规划 pass 是否为图输入预留 arena 内存。False时运行时直接使用调用方提供的输入缓冲不拷贝进 arena因此 in-place 的USER_INPUT_MUTATION如StaticCache写入会落在调用方张量上alloc_graph_outputbool默认True是否为图输出预留 arena 内存。False时调用方须在运行时绑定输出缓冲Method::set_output_data_ptr把输出绑到其被变异输入的缓冲上可避免拷贝回读alloc_mutable_buffersbool默认True是否为可变缓冲模型常驻状态预留 arena 内存透传给MemoryPlanningPassAutoHfExporter 与 AutoExportConfigAuto 工厂AutoHfExporter与AutoExportConfig遵循 Transformers 一贯的 Auto 类模式适合运行时才决定后端、而非在调用点硬编码的场景。AutoExportConfig.from_dict从配置 dict 中取出export_format键缺失则抛ValueError兼容ExportFormat枚举值与普通字符串两种写法再分派到对应配置类的from_dictauto.py#L48-L67。AutoHfExporter.from_config / from_pretrainedfrom_config(export_config, **kwargs)接受配置对象或 dict先经supports_export_format统一把关再实例化AUTO_EXPORTER_MAPPING中登记的导出器auto.py#L76-L88。supports_export_format检查给定export_format是否同时拥有已注册的配置类与导出器未注册/仅半注册时分别给出可操作的告警信息提示用register_export_config/register_exporter补齐。from_pretrained目前显式raise NotImplementedError。文档字符串中描述了一个导出配方export recipe工作流的规划模型所有者在 Hub 上随权重发布export_config.json记录该架构已验证的目标格式、动态形状规格、strict标志、ONNX opset、prefill/decode 布局、ExecuTorch 后端选择等消费者即可一行完成 owner 已验证的导出。在实现落地前请按提示显式加载/导出配置后调用AutoHfExporter.from_config(...)auto.py#L90-L120。典型用法与 docs/source/en/exporters.md 一致from transformers.exporters import AutoExportConfig, AutoHfExporter export_config_dict {export_format: onnx, dynamic: True} config AutoExportConfig.from_dict(export_config_dict) exporter AutoHfExporter.from_config(config) onnx_program exporter.export(model, inputs, configconfig)此外auto.py 还导出两个注册装饰器与一个便捷函数register_exporter(name)把HfExporter子类登记进AUTO_EXPORTER_MAPPING覆盖同名时告警非HfExporter子类直接TypeErrorregister_export_config(name)把ExportConfigMixin子类登记进AUTO_EXPORT_CONFIG_MAPPINGget_hf_exporter(export_config)等价于AutoHfExporter.from_config的快捷方式。三个内置导出器最小可运行示例所有导出器共享同一接口创建导出器、给出配置、调用export切换运行时只需更换导出器类。DynamoExporter导出并直接运行 ExportedProgramfrom 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) # 直接运行导出图 outputs exported.module()(**inputs)从源码看exporter_dynamo.py#L87-L128export在torch.export.export调用外围按序执行五步扁平化forward签名避免**kwargs被打包成与dynamic_shapes不匹配的 bundle、安装_PATCHES[dynamo]中的可逆模型补丁、为 Cache 子类注册 pytree 节点、dynamicTrue时自动推导Dim.AUTO形状、清理状态化模块属性防止上次 eager forward 泄漏进追踪。另外config.dynamicTrue且未给dynamic_shapes时会收到一次性警告所有轴包括实际固定的 batch、num_heads 等都会做符号形状解析显式指定dynamic_shapes只标记真正变化的轴可以显著加快导出。OnnxExporter导出并交给 ONNX Runtimefrom 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 Runtime 加载 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)OnnxExporter在torch.onnx.export外围增加了五个阶段Torch 补丁、ONNX 补丁、FX 节点修复、自定义 aten 翻译、ONNX IR 修复用于处理 ONNX 无法直接降级的模式详见下文扩展点一节与 docs/source/en/exporters_extend.md。ExecutorchExporter导出 .pte 供端侧部署from transformers import AutoModelForCausalLM, AutoTokenizer from transformers.exporters import ExecutorchExporter, ExecutorchConfig model AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen3-0.6B) inputs tokenizer(Hello, world!, return_tensorspt) exporter ExecutorchExporter() config ExecutorchConfig(backendxnnpack, dynamicTrue) et_program exporter.export(model, inputs, configconfig) # 保存用于端侧部署 et_program.save(model.pte) # 通过 ExecuTorch Python 运行时加载并运行 from executorch.runtime import Runtime program Runtime.get().load_program(model.pte) method program.load_method(forward) outputs method.execute(list(inputs.values()))backendxnnpack默认面向 CPUCPU-only 安装即可用backendcuda需要 CUDA 环境否则请求即抛RuntimeError。细粒度动态形状dynamicTrue把所有张量维度标记为动态导出图运行时接受任意输入尺寸、无需重新追踪。若需精确控制哪些维度动态传显式dynamic_shapes直接转发给torch.export.export三个后端写法一致import torch 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!, Hi], paddingTrue, return_tensorspt) batch torch.export.Dim(batch, min1, max32) seq torch.export.Dim(seq, min1, max2048) exporter OnnxExporter() config OnnxConfig( dynamic_shapes{input_ids: {0: batch, 1: seq}, attention_mask: {0: batch, 1: seq}}, # 数据相关的形状 guard 以运行时断言形式发射而不是在显式符号区间下导出失败 prefer_deferred_runtime_asserts_over_guardsTrue, ) onnx_program exporter.export(model, inputs, configconfig)DynamoExporter与ExecutorchExporter的用法完全相同替换导出器与配置类即可ExecuTorch 侧还需backendxnnpack。生成式模型导出export_for_generation 与多组件分解自回归生成中prefill 步骤完整 prompt、无 KV cache与 decode 步骤单 token、带 KV cache的forward形状不同export_for_generation把两个阶段拆开分别导出。多模态模型 additionally 会把 prefill 拆成视觉/音频编码器、语言模型与lm_head编码器与语言模型的发现使用PreTrainedModel.get_encodermodalityimage/audio与get_decoder访问器因此任何遵循这些访问器的新架构无需额外胶水代码即可工作。projector 组件仅在模型以约定属性名multi_modal_projector、connector、embed_vision、embed_audio暴露时才出现——这一约定来自 utils.py#L798-L800 的_MULTIMODAL_PROJECTOR_NAMES新架构应对齐这些属性名而不是继续扩充列表。以 Qwen2-VL 为例三个后端仅需替换导出器/配置类结构一致from transformers import AutoModelForImageTextToText, AutoProcessor from transformers.exporters import OnnxExporter, OnnxConfig model AutoModelForImageTextToText.from_pretrained(Qwen/Qwen2-VL-2B-Instruct) processor AutoProcessor.from_pretrained(Qwen/Qwen2-VL-2B-Instruct) messages [{role: user, content: [ {type: image, url: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg}, {type: text, text: Describe this image.}]}] text processor.apply_chat_template(messages, add_generation_promptTrue, tokenizeFalse) inputs processor(texttext, imagesmessages[0][content][0][url], return_tensorspt).to(model.device) exporter OnnxExporter() config OnnxConfig(dynamicTrue) components exporter.export_for_generation(model, inputs, configconfig) # components {image_encoder: ONNXProgram, language_model: ONNXProgram, # lm_head: ONNXProgram, decode: ONNXProgram}注意导出出的组件是相互独立的图不是开箱即用的推理流水线。各编码器的运行、embedding 的投影拼装、生成循环的编排由调用方负责。底层工具函数Utilities参考文档专门列出了一组驱动export_for_generation的底层函数——当你在分解模型与导出各组件之间需要介入时它们会派上用场。它们全部位于 utils.pyget_leaf_tensors递归地从嵌套结构tensor、dataclass、dict、list、tuple 及其任意嵌套中提取所有叶子张量返回{点号路径: tensor}的扁平映射。它由内部的_map_leaf_tensors/_iter_leaf_tensors遍历驱动会跳过enum.Enum、torch.SymInt等不可遍历类型以避免无限递归同一遍历机制还支撑duplicate_leaf_tensors对重复出现的同名张量做 clone防止 ONNX 优化器去重后破坏输出名映射与cast_leaf_tensors。prepare_for_export导出前对模型与输入做统一准备并原地修改两者返回(model, inputs, output_flags)utils.py#L344-L396剥离labels/future_values导出期不支持 loss 计算出现即抛ValueErrormodel.config.return_lossTrue同样会被拦截从inputs中弹出use_cache、return_dict等输出标志交由追踪期的patch_model_config可逆地应用到model.config上避免它们成为被追踪的 kwargs调用precompute_export_inputs按register_export_input_preparer(marker)注册表预计算数据相关的视觉/音频张量cu_seqlens、position_ids、窗口索引、音频 chunk 等——这些在模型 forward 里原本依赖.tolist()、nonzero()、循环等操作无法被 dynamo 追踪故提前算好注入inputs让 forward 跳过不可追踪分支将输入张量统一 cast 到模型的dtype/device。内置 preparer 按输入中的 marker kwargs 分派grid_thwQwen 系视觉编码器、target_sizesNaViT 风格打包编码器、(input_features, feature_lens)Omni 音频编码器、(input_features, input_features_mask)Qwen3-ASR等外层 LLM 的 RoPEposition_ids则通过hasattr(model, get_rope_index)自检后在 prefill 阶段预计算。decompose_prefill_decode通过一次真实的model.generate()调用捕获 prefill 与 decode 的 forward kwargsutils.py#L727-L795捕获窗口设在capture_config上max_new_tokens为 2multi_token_decodeTrue时为 3而非generate()kwargs且对传入的generation_config做深拷贝绝不改动调用方的对象通过_capture_forward上下文管理器包裹model.forward用inspect.signature把位置参数归一化为 kwargs逐次调用记录深拷贝——这样捕获的 dict 可直接作为kwargsinputs传给torch.export捕获到的logits_to_keep会被移除它是生成期的 top-k 剪枝提示不是 forward 输入若捕获到的 forward 调用数不足例如generate()绕过了顶层forward会抛出解释性明确的RuntimeError返回{prefill: (model, prefill_inputs), decode: (model, decode_inputs)}。generation_config传cache_implementationstaticmax_cache_lenN时捕获到的 decode 输入即使用固定大小的 cache这是静态 cache 导出的基础。multi_token_decodeTrue时_merge_decode_calls会把两个连续的单 token decode 步骤沿序列轴拼接成一个多 token decode 输入4D 因果 mask 沿 query 轴拼接2D padding mask 取覆盖最广的最后一步混合注意力的 dict mask 逐条合并。原因很直接单 token decode 会让torch.export把查询序列轴特化成 1导出的 decode 永远只能跑一个 token合并后该轴保持符号化一个图即可同时服务单 token 解码、多 token 续跑如投机解码接受、以及空 cache 时的 prefill。is_multimodal 与 decompose_multimodalis_multimodal(model)当且仅当模型是PreTrainedModel且_find_multimodal_submodules找到至少一个模态编码器 语言模型时返回Trueutils.py#L841-L847。编码器经get_encoder(image/audio)解析get_encoder找不到匹配时返回self作为兜底需显式排除projector 与lm_head在model及其base_model上按属性名查找decompose_multimodal(model, inputs)用ExitStack同时给每个子模块挂上_capture_forward跑一次model(**inputs)返回每个被调用子模块的(module, 最后一次调用的 kwargs)未被调用的如 base 模型上的lm_head会被跳过。token 合并步骤如masked_scatter有意留在导出图之外由调用方负责从编码器输出拼装inputs_embeds。decompose_for_generation总装配函数utils.py#L894-L928先decompose_prefill_decode捕获 prefill/decode再按is_multimodal判断是否进一步用decompose_multimodal拆分 prefill。返回键约定普通生成模型为prefill/decode多模态生成模型为modality_encoder/multi_modal_projector/language_model/lm_head/decode。需要介入时导出前先 eager 校验、替换某个子模块的输入、跳过某阶段直接调用它并逐组件导出from transformers.exporters.utils import decompose_for_generation components decompose_for_generation(model, inputs) # {image_encoder: (submodel, fwd_kwargs), language_model: (...), ..., decode: (...)} exported {} for name, (submodel, subinputs) in components.items(): eager_outputs submodel(**subinputs) # 导出前先做 eager 前向 sanity check exported[name] exporter.export(submodel, subinputs, configconfig)由于捕获阶段是以 eager 方式真实运行模型官方建议传入小而具代表性的输入短 prompt、单张小图、几帧音频——导出产物并不绑定这些尺寸动态形状照常透传但更小的捕获输入让分解更廉价、符号形状推断更可处理。多 token decode 与静态 KV cache两个进阶组合均摘自 docs/source/en/exporters.md多 token decodemulti_token_decodeTrue使decode组件的查询轴保持动态仅动态形状导出dynamicTrue下该轴才保持符号化静态导出会冻结在捕获长度。静态 KV cachegenerate()默认增长DynamicCache对导出图是移动靶静态 cache 是固定大小缓冲每步在当前位置原地写入。配合多 token decode整个生成过程可坍缩为单一导出图decode图接受固定大小 cache 可变数量查询 token空 cache 时即 prefill、有内容时即 decode。导出时转发GenerationConfig(cache_implementationstatic, max_cache_len2048)与multi_token_decodeTrue即可from transformers import GenerationConfig from transformers.exporters import DynamoExporter, DynamoConfig exporter DynamoExporter() gen_config GenerationConfig(cache_implementationstatic, max_cache_len2048) components exporter.export_for_generation( model, inputs, configDynamoConfig(dynamicTrue), generation_configgen_config, multi_token_decodeTrue, )此时decode图有两个符号轴查询长度与 cache 长度max_cache_len加载时可调整。零拷贝原地更新是各后端剩下的唯一差异点Dynamo 把 cache 写入建模为USER_INPUT_MUTATION直接原地更新你传入的StaticCacheONNX Runtime 通过CudaSession.set_buffer_sharing把input.name/output.name成对绑定到同一设备缓冲ExecuTorch 则需关闭alloc_graph_input/alloc_graph_output/alloc_mutable_buffers且 Python 运行时尚未暴露Method::set_output_data_ptr真正的零拷贝路径是 C 专属。三种运行时的完整 decode-loop 示例含 C 端Program::load/MemoryManager/set_output_data_ptr绑定细节可直接查阅 docs/source/en/exporters.md 的折叠代码块。扩展添加新的导出后端参考文档的核心结论是新导出后端通过子类化HfExporter加入 Transformers。结合 auto.py#L160-L181 的注册机制完整步骤为继承HfExporter实现export(model, sample_inputs, config)返回后端产物定义配置 dataclass 继承ExportConfigMixin声明export_format字段或新增一个ExportFormat枚举值用register_exporter(name)与register_export_config(name)装饰器分别登记之后AutoHfExporter.from_config即可自动分派建议声明required_packages/min_versions/tested_versions让validate_environment在构造时完成依赖检查与版本漂移告警。骨架示例from transformers.exporters import ( ExportConfigMixin, HfExporter, register_export_config, register_exporter, ) register_export_config(myformat) class MyFormatConfig(ExportConfigMixin): export_format: MyFormat # 对应你的格式标识 my_option: bool True register_exporter(myformat) class MyFormatExporter(HfExporter): required_packages [torch, myformat-runtime] tested_versions {torch: 2.12.0} def export(self, model, sample_inputs, config): # 后端特定的追踪/降级流水线消费 config 并返回运行时产物 ...若新后端需要在导出流水线中对模型做临时替换不可导出模式的规避还可使用 utils.py 中的 patch/fix 注册体系register_patch(backend, *dotted_paths)登记可逆属性替换导出期安装、退出即还原register_fx_node_fix(backend)/register_fx_program_fix(backend)登记追踪后的图节点/程序级重写。两者在问题属于哪个阶段上的取舍patch 换属性、可回滚fix 改图、不回滚、各后端阶段编号与对应扩展点完整说明在 docs/source/en/exporters_extend.md。已知限制与常用注意点综合 docs/source/en/exporters.md 的 Limitations 小节与prepare_for_export的源码行为注意力实现FlashAttention 与 FlexAttention 在任何后端都不可导出sdpa是首选设置eager也可用更慢。若模型当前使用其他实现应在调用export之前切换。MoE / grouped_mmgrouped_mm经DynamoExporter可正常追踪OnnxExporter自动翻译ExecutorchExporter XNNPACK 后端下由于 XNNPACK 没有_grouped_mm.outkernel导出器会把 MoE experts 换成batched_mm。输入约束labels、future_values、return_lossTrue一律导致ValueError见 utils.py#L360-L377输出标志类 kwargs 会被自动剥离并在追踪期应用到model.config。版本固定exporters 为实验性模块补丁与测试套件所用版本绑定validate_environment对版本漂移只告警不阻断生产环境仍应手动 pin 住 安装命令 中给出的版本组合。生成组件不是流水线export_for_generation返回的是独立图集合编排责任在调用方若generate()绕过顶层forward()分解捕获失败decompose_prefill_decode会给出明确报错说明。相关文档与源码索引主类参考本文主体对应文档docs/source/en/main_classes/exporters.md使用指南安装、快速上手、动态形状、静态 cache 与 decode-loop 完整示例docs/source/en/exporters.md扩展指南patch/fix 注册表与各后端阶段参考docs/source/en/exporters_extend.md核心源码base.py、auto.py、configs.py、utils.py、exporter_dynamo.py、exporter_onnx.py、exporter_executorch.py测试用例tests/exporters/test_export.py、tests/exporters/test_utils.py、tests/exporters/test_runtime.py【免费下载链接】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），仅供参考