Transformers documentation

导出器

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

导出器

可以通过子类化 HfExporter 并使用 register_backend() 进行注册,向 Transformers 添加新的导出后端。

了解如何在 Exporters 指南中使用内置的导出器。

AutoHfExporter

class transformers.exporters.AutoHfExporter

< >

( )

自动 HF 导出器类,负责根据 ExportConfig 自动实例化为正确的 HfExporter。

AutoExportConfig

class transformers.exporters.AutoExportConfig

< >

( )

Auto-HF 导出配置类,负责根据存储在字典中的导出配置,自动分发到正确的导出配置。

register_backend

transformers.exporters.register_backend

< >

( exporter: type[HfExporter]runner: type[ModelRunner] | None = None )

在自动类中注册一个导出器,包括其 config_class、其 export_format 以及执行其导出的 runner,以便自动类能够找到它们。

HfExporter

class transformers.exporters.HfExporter

< >

( )

所有 Transformers 导出器的抽象基类。

要添加一个后端,请子类化并实现 ~HfExporter.export_program 以追踪一个图,以及 ~HfExporter.save_program / ~HfExporter.load_program 以写出并读回该图。公开的 ~HfExporter.export 和 ~HfExporter.export_for_generation 基于它们构建一个 ExportedModel。

导出

< >

( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel

返回值

ExportedModel

单个 "model" 组件;后端的程序为 .program,save_pretrained 会将其连同元数据和模型配置一起写入。

将模型导出为单个图。

接受与 ~HfExporter.export_program 相同的 forward 关键字参数。

export_for_generation

< >

( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, ExportConfigMixin]generation_config: GenerationConfig | None = Nonemulti_token_decode: bool = False ) → ExportedModel

参数

  • model (PreTrainedModel) — 要导出的生成式模型。必须支持 model.generate(**sample_inputs)。
  • sample_inputs (dict[str, torch.Tensor | Cache]) — Generate 关键字参数 — 即传递给 model.generate(**sample_inputs) 的参数 (通常为 input_ids + attention_mask,对于多模态模型还包括 pixel_values / input_features 等模态输入)。各阶段的 forward 关键字参数会在内部自动捕获。
  • config (ExportConfigMixin 或 dict[str, ExportConfigMixin]) — 后端特定配置。传入单个配置以应用于所有组件,或传入以组件名称为键的 dict(例如 "image_encoder"、"language_model"、"lm_head"、"decode")以按组件进行覆盖——dict 中必须包含所有组件名称。
  • generation_config (GenerationConfig, 可选) — 转发至 generate() 捕获(默认使用模型自身的配置)。传入一个包含 cache_implementation="static" 的配置,即可针对固定大小的 StaticCache 进行导出。
  • multi_token_decode (bool,可选,默认为 False) — decode 组件是否一次处理多个查询 token——即动态查询轴(在空缓存上执行 prefill,否则为基于 past 的续写)——而非经典的单 token 步进(参见 decompose_for_generation())。仅在动态形状导出(config.dynamic=True)下保持动态。

返回值

ExportedModel

每个阶段一个 ExportedComponent,其键与 decompose_for_generation() 相同。

分解生成模型,并独立导出每个组件。

Thin wrapper around decompose_for_generation() that calls ~HfExporter.export_program on every returned (submodel, forward_inputs) pair. If you need the intermediate (submodel, forward_inputs) pairs (for verification, custom inputs, skipping a stage, …), call decompose_for_generation() directly.

export_program

< >

( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin ) → tuple[Any, ExportMetadata]

参数

  • model (PreTrainedModel) — 要导出的模型。
  • sample_inputs (dict[str, torch.Tensor | Cache]) — Forward kwargs — 即传递给 model(**sample_inputs) 的参数。这些参数在追踪期间直接用作示例输入。对于自回归解码步骤的导出,这意味着您需要包含 cache 等参数。 如果您只有生成式输入,请改用 ~HfExporter.export_for_generation — 它会为您运行 model.generate 并导出每个阶段。
  • config (ExportConfigMixin) — 后端特定配置。

返回值

tuple[Any, ExportMetadata]

后端的程序对象(ExportedProgram、onnx_ir.Model、 ExecutorchProgramManager、openvino.Model)以及在跟踪过程中记录的元数据 (build_export_metadata()),由于只有部分格式能够携带元数据,因此分开返回。

跟踪单个图。后端扩展点,与 ~HfExporter.save_program 配对。

load_program

< >

( path: str | Path )

读取由 ~HfExporter.save_program 写入的程序。它可能与 ~HfExporter.export_program 返回的内容不同:对于 ExecuTorch,它是一个运行时 Program,其 ExecutorchProgramManager 无法从文件重建。

program_files

< >

( filename: str )

~HfExporter.save_program 为保存为 filename 的程序写入的文件:该文件本身,以及该格式保存在其旁边的任何文件(权重、外部数据)。

save_program

< >

( program: Anypath: str | Path )

将 ~HfExporter.export_program 返回的一个程序以该后端的文件格式写入 path。

validate_environment

< >

( )

检查 required_packages 是否已安装,并在版本与 tested_versions 存在偏差时发出警告。

ExportedModel

类 transformers.exporters.ExportedModel

< >

( components: dict[str, ExportedComponent]export_format: ExportFormat | strconfig: PreTrainedConfig | None = Nonegeneration_config: GenerationConfig | None = None )

导出的模型:其计算图(components、{name: ExportedComponent})以及用于追踪这些图的配置,调用方式与调用其来源模型的方式相同。

~HfExporter.export 生成一个 "model" 组件,其程序为 .program;~HfExporter.export_for_generation 为每个生成阶段生成一个组件。

>>> exported = OnnxExporter().export(model, inputs, OnnxConfig(dynamic=True))
>>> exported.save_pretrained("exported")
>>> outputs = ExportedModel.from_pretrained("exported", device="cuda")(**inputs)
>>> outputs.last_hidden_state

__call__

< >

( share_inputs: bool = Trueshare_outputs: bool = False**kwargs )

执行单图导出,返回源模型的返回值。导出时未跟踪的关键字参数会被丢弃,因此可以传入处理器的完整输出。share_inputs 和 share_outputs 会传递给运行器(参见 ModelRunner.__call__):当使用 share_outputs 时,输出在下一次调用之前保持有效。

程序

< >

( )

用于单图导出的后端自身程序。

到

< >

( device = None**runner_kwargs )

在 device(当为 None 时,使用后端的默认设备)上,于其后端运行时加载程序。runner_kwargs 会传递给后端的 runner:对于 ONNX Runtime,为 providers 和 session_options;对于 OpenVINO,为 config(编译属性)和 torch_threads(在模型周围将 CPU 与 torch 工作分开)。

save_pretrained

< >

( save_directory: str | Pathpush_to_hub: bool = False**kwargs )

参数

  • save_directory (str 或 Path) — 要写入的目录,如果该目录不存在则会自动创建。
  • push_to_hub (bool,可选,默认为 False) — 是否同时将保存的文件上传到 Hub 的 repo_id(默认为您命名空间中 save_directory 的名称)。
  • kwargs (dict[str, Any], 可选) — 传递给 Hub 上传: repo_id、commit_message、token、private、……

编写各个组件(每个组件一个文件)、配置文件以及清单文件,清单中需指明每个组件的文件及其在追踪时记录的元数据。~ExportedModel.from_pretrained 会将它们重新加载。

from_pretrained

< >

( pretrained_model_name_or_path: str | Pathdevice = Nonecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'subfolder: str = ''trust_remote_code: bool = False**runner_kwargs )

参数

  • pretrained_model_name_or_path (str 或 Path) — 本地目录或 Hub 仓库 ID。从 Hub 下载时,仅下载清单中列出的文件,因此导出文件可以与模型自身的权重文件放在一起。
  • device (str 或 torch.device,可选) — 运行位置(当为 None 时,使用后端的默认值)。
  • cache_dir (Union[str, os.PathLike], 可选) — 如果不应使用标准缓存,则用于缓存已下载的预训练模型配置的目录路径。
  • force_download (bool,可选,默认为 False) — 是否强制(重新)下载模型权重和配置文件,如果存在缓存版本则覆盖它们。
  • local_files_only (bool,可选,默认为 False) — 是否仅查看本地文件(即不尝试下载模型)。
  • token (str 或 bool,可选) — 用于远程文件的 HTTP bearer 授权令牌。如果为 True 或未指定,则使用运行 hf auth login 时生成的令牌(存储在 ~/.huggingface 中)。
  • revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。由于我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件,因此它可以是分支名称、标签名称或提交 ID,所以 revision 可以是 git 允许的任何标识符。

    要测试您在 Hub 上创建的拉取请求,可以传入 revision="refs/pr/<pr_number>"。

  • subfolder (str,可选,默认为 "") — 如果相关文件位于 huggingface.co 上模型仓库的子文件夹中,您可以在此处指定该文件夹的名称。
  • trust_remote_code (bool,可选,默认为 False) — 是否运行导出中包含的代码:例如,对于代码位于其仓库中的模型配置(类似于 from_pretrained()),以及加载时会执行代码的格式(torch.export 的 pickle 序列化 .pt2),后者若缺少此代码则无法加载。仅对可信的导出传递此参数。
  • runner_kwargs (可选) — 后端运行器选项,与 ~ExportedModel.to 相同:ONNX Runtime 的 providers 和 session_options,OpenVINO 的 config 和 torch_threads。

加载 ~ExportedModel.save_pretrained 写入的内容:每个组件都通过其后端的 ~HfExporter.load_program 加载,并附带相应的元数据以及保存在旁边的配置文件。程序会立即在其后端的运行时上加载,随时可以运行。

ExportedComponent

类 transformers.exporters.ExportedComponent

< >

( program: Anymetadata: ExportMetadata )

一个导出的图:后端的程序,以及导出器记录的相关信息。

ExportMetadata

类 transformers.exporters.ExportMetadata

< >

( architecture: str | None = Nonepackages: dict[str, str] = <factory>export_config: dict[str, Any] = <factory>export_dtype: str | None = Noneexport_device: str | None = Nonekwargs: dict[str, dict] = <factory>in_spec: str | None = Noneout_spec: str | None = Nonein_constants: dict[str, Any] = <factory>out_constants: list = <factory> )

导出器针对单个图所记录的内容(build_export_metadata())。

from_dict

< >

( values: Mapping[str, Any] )

从其保存的字典构建元数据,跳过此类中不存在的字段(由更新版本添加)。

ModelRunner

类 transformers.exporters.ModelRunner

< >

( metadata: ExportMetadata )

在对应后端上运行一个已导出的程序:runner(**kwargs) 返回源模型所返回的结果。

from_program

< >

( program: Anymetadata: ExportMetadatadevice = None )

作为导出的程序运行器会返回该程序,或者 ~HfExporter.load_program 会将其读回,并放置在 device 上(当 None 时,使用后端的默认设备)。

unflatten

< >

( outputs: list )

根据程序的扁平化输出(位于末尾)和记录的常量,重建模型的输出。

DynamoExporter

class transformers.exporters.DynamoExporter

< >

( )

用于将 PreTrainedModel 转换为 ExportedProgram 的导出器。

示例:

>>> from transformers.exporters.exporter_dynamo import DynamoExporter, DynamoConfig

>>> exporter = DynamoExporter()
>>> exported = exporter.export(model, inputs, config=DynamoConfig(dynamic=True))
>>> outputs = exported(**inputs)
>>> exported.save_pretrained("exported")  # `model.pt2`, its metadata and the model config

导出

< >

( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel

返回值

ExportedModel

单个 "model" 组件;后端的程序为 .program,save_pretrained 会将其连同元数据和模型配置一起写入。

将模型导出为单个图。

接受与 ~HfExporter.export_program 相同的 forward 关键字参数。

OnnxExporter

class transformers.exporters.OnnxExporter

< >

( )

用于将 PreTrainedModel 转换为 ONNX 图(即 onnx_ir.Model)的导出器。

示例:

>>> from transformers.exporters.exporter_onnx import OnnxExporter, OnnxConfig

>>> exporter = OnnxExporter()
>>> exported = exporter.export(model, inputs, config=OnnxConfig(dynamic=True))
>>> outputs = exported(**inputs)  # on ONNX Runtime
>>> onnx_model = exported.program  # an `onnx_ir.Model`
>>> exported.save_pretrained("exported")  # `model.onnx`, its metadata and the model config

导出

< >

( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel

返回值

ExportedModel

单个 "model" 组件;后端的程序为 .program,save_pretrained 会将其连同元数据和模型配置一起写入。

将模型导出为单个图。

接受与 ~HfExporter.export_program 相同的 forward 关键字参数。

ExecutorchExporter

class transformers.exporters.ExecutorchExporter

< >

( )

用于将 PreTrainedModel 转换为 ExecuTorch ExecutorchProgramManager 的导出器。

示例:

>>> from transformers.exporters.exporter_executorch import ExecutorchExporter, ExecutorchConfig

>>> exporter = ExecutorchExporter()
>>> exported = exporter.export(model, inputs, config=ExecutorchConfig(backend="xnnpack"))
>>> outputs = exported(**inputs)  # on the ExecuTorch runtime
>>> exported.save_pretrained("exported")  # `model.pte`, its metadata and the model config

导出

< >

( model: PreTrainedModelsample_inputs: MutableMapping[str, torch.Tensor | Cache]config: ExportConfigMixin | dict[str, Any] ) → ExportedModel

返回值

ExportedModel

单个 "model" 组件;后端的程序为 .program,save_pretrained 会将其连同元数据和模型配置一起写入。

将模型导出为单个图。

接受与 ~HfExporter.export_program 相同的 forward 关键字参数。

DynamoConfig

class transformers.exporters.DynamoConfig

< >

( export_format: ExportFormat = <ExportFormat.DYNAMO: 'dynamo'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = None )

参数

  • dynamic(bool,可选,默认为 False) — 是否以动态(符号)形状进行导出。当 True 且未设置 dynamic_shapes 时,所有张量维度将自动设置为 Dim.AUTO。
  • strict (bool,可选,默认为 False) — 是否启用 torch.export 的严格模式。该模式会执行完整的符号追踪并捕获更多错误,但速度更慢,且在复杂模型上更容易失败。
  • dynamic_shapes (dict[str, Any],可选) — 传递给 torch.export 的显式逐输入动态形状规范。其优先级高于 dynamic。
  • prefer_deferred_runtime_asserts_over_guards (bool,可选,默认为 False) — 当 True 时,数据依赖的形状守卫会以运行时断言的形式输出到导出的图中,而不是在追踪阶段因守卫无法在整个符号形状范围内成立而导致导出失败。大多数 Transformer LLM 在使用细粒度的 Dim(min=, max=) 边界时,需要将其设置为 True。如果使用 dynamic=True / Dim.AUTO,则无需设置,因为 torch.export 会推断形状关系,而不是将其与用户声明的边界进行验证。
  • quantizer ([~exporters.quantizers.ExportQuantizer],可选) — 导出期间应用的训练后量化:针对每个后端,在 FX 图上使用 [~exporters.quantizers.PT2EQuantizer] 或 [~exporters.quantizers.NNCFTorchFXQuantizer],在转换后的 ONNX 模型上使用 [~exporters.quantizers.OnnxRuntimeQuantizer],或在转换后的 OpenVINO / ONNX 模型上使用 [~exporters.quantizers.NNCFOpenVINOQuantizer] / [~exporters.quantizers.NNCFOnnxQuantizer]。

用于通过 torch.export 导出模型的配置类。

OnnxConfig

class transformers.exporters.OnnxConfig

< >

( export_format: ExportFormat = <ExportFormat.ONNX: 'onnx'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = Noneopset_version: int | None = Noneoptimize: bool = Trueort_fusions: Literal['cpu', 'cuda', 'webgpu', 'dml'] | None = None )

参数

  • opset_version (int, 可选) — 要使用的 ONNX opset 版本。默认值为已安装的 onnxscript 版本所支持的最新 opset。
  • optimize (bool,可选,默认为 True) — 对导出的图运行 onnxscript 优化通道(常量折叠、死代码消除等)。如果模型触发了上游 onnxscript 优化器的 bug,请禁用此选项。
  • ort_fusions (str, 可选) — 将图融合为 ONNX Runtime 在其运行执行提供程序上使用的算子:"cpu"、"cuda"、 "webgpu" 或 "dml"。融合后的图仅在 ONNX Runtime 上运行。需要 optimize=True。

用于通过 torch.onnx.export 将模型导出为 ONNX 的配置类。

继承 DynamoConfig 的所有字段(dynamic、strict、dynamic_shapes、prefer_deferred_runtime_asserts_over_guards)。

ExecutorchConfig

class transformers.exporters.ExecutorchConfig

< >

( export_format: ExportFormat = <ExportFormat.EXECUTORCH: 'executorch'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = Nonebackend: str = 'xnnpack'alloc_graph_input: bool = Truealloc_graph_output: bool = Truealloc_mutable_buffers: bool = True )

参数

  • backend (str, 可选, 默认为 "xnnpack") — 目标 ExecuTorch 后端。支持的取值:
    • "xnnpack" — 通过 XNNPACK 库进行 CPU 推理(默认;可在任何地方运行)。
    • "cuda" — 通过 ExecuTorch CUDA 后端进行 GPU 推理。
    • "mlx" — 在 Apple Silicon 上通过 ExecuTorch MLX 后端进行 GPU 推理。
  • alloc_graph_input (bool,可选,默认为 True) — 内存规划阶段是否为图输入保留 arena 内存。当设置为 False 时,运行时将直接使用调用方提供的输入缓冲区,而不是将其复制到 arena 中——因此,就地执行的 USER_INPUT_MUTATION(例如对 StaticCache 的写入)会作用于调用方的张量,而非 arena 中的副本。
  • alloc_graph_output (bool,可选,默认为 True) — 内存规划阶段是否为图输出保留 arena 内存。当设置为 False 时,调用方必须在运行时绑定输出缓冲区(Method::set_output_data_ptr);将输出绑定到其被修改的输入缓冲区可以避免复制出的往返开销。
  • alloc_mutable_buffers (bool,可选,默认为 True) — 内存规划阶段是否为可变缓冲区(驻留于模型中的状态)保留 arena 内存。该参数会传递给 MemoryPlanningPass。

用于将模型导出为 ExecuTorch 格式的配置类。

继承 DynamoConfig 的所有字段(dynamic、strict、dynamic_shapes、prefer_deferred_runtime_asserts_over_guards)。

OpenVINOConfig

class transformers.exporters.OpenVINOConfig

< >

( export_format: ExportFormat = <ExportFormat.OPENVINO: 'openvino'>dynamic: bool = Falsestrict: bool = Falsedynamic_shapes: dict[str, Any] | None = Noneprefer_deferred_runtime_asserts_over_guards: bool = Falsequantizer: ExportQuantizer | None = Nonecompress_to_fp16: bool = Falsestateful: bool = True )

参数

  • compress_to_fp16 (bool,可选,默认为 False) — 将转换后模型的 float32 权重压缩为 float16,使其体积减半。由于数值范围较窄,默认关闭此功能。
  • stateful (bool, optional, defaults to True) — Fold round-tripped state tensors (KV cache, SSM states, …) into internal OV variables (ReadValue/Assign`). The runtime then carries state across `infer()` calls instead of marshalling cache tensors through inputs/outputs on every step, and a fused `beam_idx input reorders state in-graph for beam search. No-op for models without round-tripped state (encoders, prefill-only exports). Set it to False for targets that take no stateful model, such as the NPU plugin.

用于通过 openvino.convert_model 将模型导出为 OpenVINO IR 的配置类。

继承自 [DynamoConfig] 的所有字段(dynamic、strict、dynamic_shapes、prefer_deferred_runtime_asserts_over_guards)。

量化器

class transformers.exporters.ExportQuantizer

< >

( calibration_dataset: Iterable[dict[str, Any]] | None = None )

参数

  • calibration_dataset (Iterable[dict], 可选) — 量化器用于校准的输入字典:一个列表,或一个批次可整理为模型输入的 DataLoader。 对于 ~HfExporter.export_for_generation,它们是 generate 的关键字参数,并按组件捕获到校准集中。当 None 时,需要数据的量化器将使用导出自身的示例输入进行校准,并给出警告。

在导出期间应用的训练后量化器的基类。

量化器会声明其支持的导出格式以及所需的依赖包(包括经过测试的版本,与导出器类似),并说明它是在任何转换之前对 torch.export FX 图进行量化(因此所有后端都会接收该结果),还是对后端转换后的模型(onnx_ir.Model、openvino.Model)进行量化。导出器会预先针对导出进行验证,然后使用该模型及导出的示例输入调用 ~ExportQuantizer.quantize。请继承该类并实现 quantize 以添加新的量化方法;CalibrationSet 用于将校准样本映射到模型自身的输入。

quantize

< >

( model: Anysample_inputs: dict[str, Any]export_format: ExportFormat )

对 model(若 quantizes_fx_graph 为真,则为 FX 图,否则为后端模型)进行量化并返回结果, 校准数据使用 calibration_dataset,若其不存在,则使用导出时的 sample_inputs。

traced_calibration

< >

( sample_inputs: dict[str, Any] )

作为 FX 图量化器的追踪 kwargs 的校准样本。

validate_environment

< >

( export_format: ExportFormat )

如果此量化器无法在 export_format 导出上运行,或其所需的包缺失或版本过旧,则抛出异常;如果版本与其测试所用版本不一致,则发出警告。

with_calibration

< >

( calibration_dataset: Iterable[dict[str, Any]] )

一个在 calibration_dataset 上进行校准的该量化器的副本。

class transformers.exporters.quantizers.CalibrationSet

< >

( calibration_dataset: Iterable[dict[str, Any]] | Nonesample_inputs: dict[str, Any]transform: Callable[[dict[str, Any]], Any] )

作为模型输入的校准样本的可重复迭代视图。

这些样本是量化器的 calibration_dataset,或者在量化器没有提供样本时,是导出自身的 sample_inputs(读取时会发出一次警告)。它们可以是任意映射,例如分词器的 BatchEncoding。transform 会将每个前向传播关键字参数样本映射为量化模型所接受的内容(即被追踪的关键字参数、ONNX 输入或 OpenVINO 端口输入),该过程是惰性的,每次遍历都会逐个样本进行处理。

class transformers.exporters.PT2EQuantizer

< >

( quantizer: Anycalibration_dataset: Iterable[dict[str, Any]] | None = None )

参数

  • quantizer (torchao.quantization.pt2e.quantizer.Quantizer) — 用于标注图的 PT2E 量化器。其量化/反量化算子必须是目标后端所支持的算子:inductor、ONNX (QDQ) 或 OpenVINO 使用 X86InductorQuantizer,ExecuTorch 使用 XNNPACKQuantizer。
  • calibration_dataset (Iterable[dict], 可选) — 观测器用于校准的输入字典(参见 ExportQuantizer),每次前向传播对应一个。若需基于批次进行校准,请传入一个 DataLoader,将样本整理为批处理输入字典,而不是传入单个样本的列表。

使用 PyTorch 2 Export (PT2E) 量化 对 FX 图进行量化:prepare_pt2e 会插入观测器,校准集驱动这些观测器,随后 convert_pt2e 将它们替换为量化/反量化算子。支持所有导出后端。

示例:

>>> from torchao.quantization.pt2e.quantizer.x86_inductor_quantizer import (
...     X86InductorQuantizer,
...     get_default_x86_inductor_quantization_config,
... )
>>> from transformers.exporters import DynamoConfig, PT2EQuantizer

>>> x86 = X86InductorQuantizer().set_global(get_default_x86_inductor_quantization_config())
>>> DynamoConfig(quantizer=PT2EQuantizer(x86, calibration_dataset=samples))

class transformers.exporters.OnnxRuntimeQuantizer

< >

( config: OnnxRuntimeStaticConfig | OnnxRuntimeDynamicConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )

使用 ONNX Runtime 自带的工具(onnxruntime.quantization)对转换后的 ONNX 模型进行量化:使用 OnnxRuntimeStaticConfig(默认)的 quantize_static,或使用 OnnxRuntimeDynamicConfig 的 quantize_dynamic。

示例:

>>> from transformers.exporters import (
...     OnnxConfig,
...     OnnxRuntimeDynamicConfig,
...     OnnxRuntimeQuantizer,
...     OnnxRuntimeStaticConfig,
... )

>>> static = OnnxRuntimeStaticConfig(per_channel=True)
>>> OnnxConfig(quantizer=OnnxRuntimeQuantizer(static, calibration_dataset=samples))
>>> OnnxConfig(quantizer=OnnxRuntimeQuantizer(OnnxRuntimeDynamicConfig()))

类 transformers.exporters.OnnxRuntimeStaticConfig

< >

( quant_format: Any = Noneop_types_to_quantize: list[str] | None = Noneper_channel: bool | None = Nonereduce_range: bool | None = Noneactivation_type: Any = Noneweight_type: Any = Nonenodes_to_quantize: list[str] | None = Nonenodes_to_exclude: list[str] | None = Nonecalibrate_method: Any = Nonecalibration_providers: list[str] | None = Noneextra_options: dict[str, Any] | None = None )

onnxruntime.quantization.quantize_static 的参数:int8 激活值和权重(默认采用 QDQ 格式),基于量化器的 calibration_dataset 进行校准。将某个字段保留为 None 即可沿用 ONNX Runtime 的默认值。各项参数的详细说明请参见 quantize_static。

类 transformers.exporters.OnnxRuntimeDynamicConfig

< >

( op_types_to_quantize: list[str] | None = Noneper_channel: bool | None = Nonereduce_range: bool | None = Noneweight_type: Any = Nonenodes_to_quantize: list[str] | None = Nonenodes_to_exclude: list[str] | None = Noneextra_options: dict[str, Any] | None = None )

onnxruntime.quantization.quantize_dynamic 的参数:int8 权重,激活值在运行时进行量化,无需校准。将某个字段保留为 None 即可沿用 ONNX Runtime 的默认值。各项参数的详细说明请参见 quantize_dynamic。

class transformers.exporters.NNCFOpenVINOQuantizer

< >

( config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )

使用 NNCF 对转换后的 OpenVINO 模型进行量化:使用 nncf.quantize 和 NNCFQuantizationConfig(默认),或使用 nncf.compress_weights 和 NNCFWeightCompressionConfig。

示例:

>>> import nncf
>>> from transformers.exporters import NNCFOpenVINOQuantizer, NNCFWeightCompressionConfig, OpenVINOConfig

>>> OpenVINOConfig(quantizer=NNCFOpenVINOQuantizer(calibration_dataset=samples))
>>> OpenVINOConfig(
...     quantizer=NNCFOpenVINOQuantizer(NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM))
... )

class transformers.exporters.NNCFOnnxQuantizer

< >

( config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )

使用 NNCF 的 ONNX 后端对转换后的 ONNX 模型进行量化:使用 nncf.quantize 和 NNCFQuantizationConfig(默认,int8 QDQ),或使用 nncf.compress_weights 和 NNCFWeightCompressionConfig(int4,作为 ONNX Runtime 的 MatMulNBits)。

示例:

>>> import nncf
>>> from transformers.exporters import NNCFOnnxQuantizer, NNCFWeightCompressionConfig, OnnxConfig

>>> OnnxConfig(quantizer=NNCFOnnxQuantizer(calibration_dataset=samples))
>>> OnnxConfig(quantizer=NNCFOnnxQuantizer(NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM)))

类 transformers.exporters.NNCFTorchFXQuantizer

< >

( config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = Nonecalibration_dataset: Iterable[dict[str, Any]] | None = None )

通过 NNCF 的 TorchFX 后端对 torch.export FX 图进行量化:使用 nncf.quantize 配合 NNCFQuantizationConfig(默认使用 quantize/dequantize 算子),或使用 nncf.compress_weights 配合 NNCFWeightCompressionConfig。与 PT2EQuantizer 类似,它在任何转换之前运行,因此所有后端都会接收其结果。ExecuTorch 仅降低仅权重(weight-only)的结果:XNNPACK 不会委托 quantize/dequantize 算子,且 ExecuTorch 没有针对这些算子的内核。

示例:

>>> from transformers.exporters import DynamoConfig, NNCFTorchFXQuantizer

>>> DynamoConfig(quantizer=NNCFTorchFXQuantizer(calibration_dataset=samples))

class transformers.exporters.NNCFQuantizationConfig

< >

( mode: Any = Nonepreset: Any = Nonetarget_device: Any = Nonesubset_size: int | None = Nonefast_bias_correction: bool | None = Nonemodel_type: Any = Noneignored_scope: Any = Noneadvanced_parameters: Any = None )

nncf.quantize 的参数:对量化器的 calibration_dataset 进行校准后的 int8 激活值和权重。 除 model_type 外,将字段保留为 None 会沿用 NNCF 的默认值;model_type 的默认值为 nncf.ModelType.TRANSFORMER。 有关每个参数的详细信息,请参阅 nncf.quantize。

class transformers.exporters.NNCFWeightCompressionConfig

< >

( mode: Any = Noneratio: float | None = Nonegroup_size: int | None = Noneignored_scope: Any = Noneall_layers: bool | None = Nonesensitivity_metric: Any = Nonesubset_size: int | None = Noneawq: bool | None = Nonescale_estimation: bool | None = Nonegptq: bool | None = Nonelora_correction: bool | None = Nonebackup_mode: Any = Nonecompression_format: Any = Noneadvanced_parameters: Any = None )

nncf.compress_weights 的参数:仅针对权重的 int8 或 int4 量化,其中 int4 模式支持数据感知方法(AWQ、scale estimation、GPTQ)。int8 模式无需数据;其他模式则基于量化器的 calibration_dataset 进行校准。gptq 和 lora_correction 仅适用于 OpenVINO。将某个字段保留为 None 时,将沿用 NNCF 的默认值。有关每个参数的详细说明,请参阅 nncf.compress_weights。

实用工具

export_for_generation 底层函数,适用于需要在分解模型和导出各个组件之间进行干预的场景。

transformers.exporters.utils.get_leaf_tensors

< >

( obj: Any ) → dict[str, torch.Tensor]

参数

  • obj (Any) — 张量、dataclass、字典、列表、元组,或它们的任意嵌套组合。

返回值

dict[str, torch.Tensor]

从点分路径字符串到张量的扁平映射。

递归地从可能嵌套的结构中获取所有叶张量。

transformers.exporters.utils.prepare_for_export

< >

( model: PreTrainedModel | torch.nn.Moduleinputs: MutableMapping[str, Any] )

配置用于导出的模型和输入。会就地修改 model 和 inputs, 并返回 (model, inputs, output_flags),其中 output_flags 保存了从 inputs 中弹出的 use_cache、return_dict 等值(在跟踪期间,patch_model_config 会将其可逆地应用到 model.config 上)。

  • 移除标签输入(labels、future_values)——不支持损失计算。
  • 从 inputs 中弹出输出标志(use_cache、return_dict、……),使其不会作为被追踪的 kwargs 出现;这些值会被返回,供 trace 块应用到 model.config 上。
  • 预先计算通过 @register_export_input_preparer 注册的数据依赖型视觉/音频 kwargs,并将其写入 inputs。
  • 将输入张量转换为与模型的 dtype / device 相匹配。

transformers.exporters.utils.decompose_prefill_decode

< >

( model: PreTrainedModelinputs: dict[str, Any]generation_config: Any = Nonemulti_token_decode: bool = False ) → dict[str, tuple[torch.nn.Module, dict]]

返回值

dict[str, tuple[torch.nn.Module, dict]]

{"prefill": (model, prefill_inputs), "decode": (model, decode_inputs)}.

运行 model.generate() 并捕获 prefill 和 decode 的输入。

复用完整的生成机制,使每种架构(仅解码器、SSM、编码器-解码器、多模态等)都能获得正确的输入,而无需重新实现循环。

generation_config 会转发给 generate()(默认使用模型自身的配置),因此捕获的输入会使用 generate() 构建的缓存。传入一个包含 cache_implementation="static" 和 max_cache_len=N 的配置,即可在解码输入中捕获一个 静态大小 的缓存——这是静态缓存导出的基础。max_cache_len 独立于捕获过程来设定缓存大小,因此导出的解码将使用固定大小的 [..., N, ...] 缓存,而不是不断增长的缓存。

当 multi_token_decode 为真时,decode 组件会被捕获为 多 token 解码——即将两个连续的解码步骤合并(参见 _merge_decode_calls),从而使其查询序列轴保持符号化(单 token 解码会将该轴特化为 1)。随后,它既能处理单个 token(常规解码),也能处理多个 token(基于过去状态的续写,或在缓存为空时的普通预填充)。否则,decode 即为经典的单 token 解码。

transformers.exporters.utils.decompose_multimodal

< >

( model: PreTrainedModelinputs: dict[str, Any] ) → dict[str, tuple[torch.nn.Module, dict]]

返回值

dict[str, tuple[torch.nn.Module, dict]]

每个检测到的子模块(图像/音频编码器、投影器、语言模型、lm_head)对应一个 name: (module, inputs) 条目。

引发

ValueError

  • ValueError — 如果在模型中未找到任何已知的多模态子模块。

通过单次前向传播捕获每个多模态子模块的输入。

通过属性名称(视觉塔、投影器、语言模型、lm_head 等)检测所有已知的多模态子模块,并在一次 model(**inputs) 调用中捕获它们的 forward kwargs。

每个子模块都会作为独立的 name: (module, inputs) 条目返回,以便进行独立导出。Token 合并步骤(例如多模态模型中的 masked_scatter)被有意排除在导出的图之外——调用方有责任在运行解码器之前,根据编码器输出组装 inputs_embeds。

transformers.exporters.utils.decompose_for_generation

< >

( model: PreTrainedModelinputs: dict[str, Any]generation_config: Any = Nonemulti_token_decode: bool = False ) → `{component_name

参数

  • model — 生成式模型。必须支持 model.generate(**inputs)。
  • inputs — Generate 关键字参数 — 即传递给 model.generate(**inputs) 的内容。
  • generation_config — 可选的 GenerationConfig,在捕获期间转发给 generate()。传入一个包含 cache_implementation="static" + max_cache_len=N 的配置,以针对静态大小的缓存进行导出(参见 decompose_prefill_decode)。
  • multi_token_decode — 当 True 时,将 decode 组件捕获为多 token 解码(动态查询序列轴:一次处理多个 token —— 基于过去状态的续写,或在缓存为空时执行普通的 prefill);单 token 解码无法保持动态(参见 decompose_prefill_decode)。

返回值

`{component_name

(submodel, forward_inputs)}. Keys are “prefill”/“decode”for plain generative models and”<modality>_encoder”/“multi_modal_projector”/“language_model”/“lm_head”/“decode”` for multi-modal generative models.

将生成式模型分解为可独立导出的 (model, forward_inputs) 对。

运行 decompose_prefill_decode,以从真实的 model.generate(**inputs, max_new_tokens=2) 中捕获 prefill 和 decode 的前向 kwargs。如果 prefill 是多模态的(根据 is_multimodal),则通过 decompose_multimodal 将其进一步拆分为每个子模块(视觉/音频编码器、projector、语言模型、lm_head)各一个条目。

transformers.exporters.utils.is_multimodal

< >

( model: PreTrainedModel | torch.nn.Module )

如果模型是多模态模型,包含模态编码器和语言模型,则返回 True。

非PreTrainedModel(例如裸的nn.Module)没有标准的get_encoder/get_decoder访问器,并且显然不是多模态的,因此会直接短路返回False。

Update on GitHub