# Exportadores

Novos backends de exportação podem ser adicionados ao Transformers por meio da herança de `HfExporter`.

Aprenda a usar os exportadores integrados no guia [Exporters](../exporters).

## AutoHfExporter[[transformers.exporters.AutoHfExporter]]

#### transformers.exporters.AutoHfExporter[[transformers.exporters.AutoHfExporter]]

```python
transformers.exporters.AutoHfExporter()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L93)

A classe exportadora Auto-HF que cuida da instanciação automática para o `HfExporter` correto, dado o `ExportConfig`.

#### from_pretrained[[transformers.exporters.AutoHfExporter.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L113)

Carregue uma instância de exportador a partir de um modelo/checkpoint pré-treinado que inclui uma configuração de exportação.

**Ainda não implementado** — espaço reservado para um fluxo de trabalho de "receita de exportação" de primeira classe.

A ideia: os proprietários dos modelos publicam um `export_config.json` (ou um campo `export_config` em `config.json`) junto com seus pesos no Hub. Esse arquivo registra as configurações que o proprietário já validou para sua arquitetura — o formato de destino (`dynamo` / `onnx` / `executorch`), as especificações exatas de formas dinâmicas (por exemplo, `text_ids` dinâmico até 4096, tiles de imagem fixos em 448, `batch=1` para implantação em dispositivos de borda), a flag `strict`, o opset do ONNX, o layout de prefill versus decode, a escolha do backend do ExecuTorch e qualquer outra configuração que hoje existe como conhecimento tácito em um README ou em um notebook privado.

Em seguida, os consumidores recebem a exportação validada pelo proprietário em uma única chamada:

```python
exporter = AutoHfExporter.from_pretrained("org/model-name")
program = exporter.export(model, inputs)
```

        Complementa o registro [*register_export_input_preparer*]: o proprietário fornece a especificação de forma via `export_config.json`, enquanto o transformers fornece as pré-computações dependentes dos dados (`cu_seqlens`, ids de posição de visão, índices de janela, …) para essa arquitetura. Juntos, eles cobrem as duas partes mais difíceis da exportação de novos modelos — conhecer o contrato de forma correto e preparar os inputs corretos —, de modo que os usuários a jusante não precisem re-derivar nenhum dos dois do zero (e não quebrem em produção quando errarem).

#### supports_export_format[[transformers.exporters.AutoHfExporter.supports_export_format]]

```python
supports_export_format(export_config_dict: dict)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L145)

Retorna True se o dict fornecido descreve um `export_format` que possui tanto uma classe de configuração registrada quanto uma classe de exportador registrada. Emite um aviso com uma mensagem acionável quando o formato está totalmente ausente, desconhecido ou apenas parcialmente registrado.

## AutoExportConfig[[transformers.exporters.AutoExportConfig]]

#### transformers.exporters.AutoExportConfig[[transformers.exporters.AutoExportConfig]]

```python
transformers.exporters.AutoExportConfig()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L65)

A classe de configuração de exportação Auto-HF que se encarrega de despachar automaticamente para a configuração de exportação correta, dada uma configuração de exportação armazenada em um dicionário.

## HfExporter[[transformers.exporters.HfExporter]]

#### transformers.exporters.HfExporter[[transformers.exporters.HfExporter]]

```python
transformers.exporters.HfExporter()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L41)

Classe base abstrata para todos os exportadores do Transformers.

Subclasse e implemente `~HfExporter.export` para adicionar um novo backend de exportação.

#### export[[transformers.exporters.HfExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, torch.Tensor | Cache], config: ExportConfigMixin)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L61)

**Parâmetros:**

model ([PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel)) : O modelo a ser exportado.

sample_inputs (`dict[str, torch.Tensor | Cache]`) : **Forward** kwargs — o que você passaria para `model(**sample_inputs)`. Eles são usados diretamente como entradas de exemplo durante o tracing. Para uma exportação de etapa de decodificação autoregressiva, isso significa que você precisa incluir `past_key_values`, `cache_position`, etc. Se você tiver apenas entradas no estilo geração, use `~HfExporter.export_for_generation` em vez disso — ele executa `model.generate` para você e exporta cada etapa.

config (`ExportConfigMixin`) : Configuração específica do backend.

**Retorna:**

Artefato de exportação específico do backend.

Exporte o modelo e retorne o objeto de programa específico do backend.

#### export_for_generation[[transformers.exporters.HfExporter.export_for_generation]]

```python
export_for_generation(model: PreTrainedModel, sample_inputs: MutableMapping[str, torch.Tensor | Cache], config: ExportConfigMixin | dict[str, ExportConfigMixin], generation_config: GenerationConfig | None = None, multi_token_decode: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L93)

**Parâmetros:**

model ([PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel)): O modelo generativo a ser exportado. Deve suportar `model.generate(**sample_inputs)`.

sample_inputs (`dict[str, torch.Tensor | Cache]`) : argumentos de **Generate** — o que você passaria para `model.generate(**sample_inputs)` (tipicamente `input_ids` + `attention_mask`, além de quaisquer entradas de modalidade, como `pixel_values` / `input_features`, para modelos multimodais). Os argumentos de forward por etapa são capturados internamente.

config (`ExportConfigMixin` ou `dict[str, ExportConfigMixin]`) : Configuração específica do backend. Passe uma única configuração para aplicar a todos os componentes, ou um `dict` com chaves pelo nome do componente (por exemplo, `"image_encoder"`, `"language_model"`, `"lm_head"`, `"decode"`) para sobrescrever por componente — todos os nomes de componentes devem estar presentes no dict.

generation_config ([GenerationConfig](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationConfig), *opcional*) : Encaminhado para a captura `generate()` (padrão: a própria do modelo). Passe um com `cache_implementation="static"` para exportar em relação a um `StaticCache` de tamanho fixo.

multi_token_decode (`bool`, *opcional*, padrão `False`) : Se o componente `decode` processa múltiplos tokens de consulta de uma vez — um eixo de consulta dinâmico (prefill em um cache vazio, continuação a partir do passado caso contrário) — em vez do passo clássico de um único token (veja [decompose_for_generation()](/docs/transformers/main/pt/main_classes/exporters#transformers.exporters.utils.decompose_for_generation)). Permanece dinâmico apenas sob uma exportação de forma dinâmica (`config.dynamic=True`).

**Retorna:** `dict[str, Any]`

`{component_name: backend_specific_artifact}` — mesmas chaves de [decompose_for_generation()](/docs/transformers/main/pt/main_classes/exporters#transformers.exporters.utils.decompose_for_generation). Os valores são o que `~HfExporter.export` retorna para o backend específico (`ExportedProgram`, `ONNXProgram`, `ExecutorchProgramManager`).

Decomponha um modelo generativo e exporte cada componente de forma independente.

Wrapper fino em torno de [decompose_for_generation()](/docs/transformers/main/pt/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) que chama `~HfExporter.export` em cada par `(submodel, forward_inputs)` retornado. Se você precisar dos pares intermediários `(submodel, forward_inputs)` (para verificação, entradas personalizadas, pular uma etapa, …), chame [decompose_for_generation()](/docs/transformers/main/pt/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) diretamente.

#### validate_environment[[transformers.exporters.HfExporter.validate_environment]]

```python
validate_environment(*args, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L57)

Verifique se os `required_packages` estão instalados e emita um aviso em caso de divergência de versão em relação aos `tested_versions`.

## DynamoExporter[[transformers.exporters.DynamoExporter]]

#### transformers.exporters.DynamoExporter[[transformers.exporters.DynamoExporter]]

```python
transformers.exporters.DynamoExporter()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_dynamo.py#L69)

Exportador que converte um [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel) em um `ExportedProgram`.

Exemplo:

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

>>> exporter = DynamoExporter()
>>> exported = exporter.export(model, inputs, config=DynamoConfig(dynamic=True))
>>> outputs = exported.module()(**inputs)
```

#### export[[transformers.exporters.DynamoExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, Any], config: DynamoConfig | dict[str, Any])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_dynamo.py#L87)

## OnnxExporter[[transformers.exporters.OnnxExporter]]

#### transformers.exporters.OnnxExporter[[transformers.exporters.OnnxExporter]]

```python
transformers.exporters.OnnxExporter()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_onnx.py#L108)

Exportador que converte um [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel) em um `ONNXProgram` ONNX.

Exemplo:

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

>>> exporter = OnnxExporter()
>>> onnx_program = exporter.export(model, inputs, config=OnnxConfig(dynamic=True))
>>> outputs = onnx_program(**inputs)  # run in-memory
>>> exporter.export(model, inputs, config=OnnxConfig(output_path="model.onnx"))  # save to disk
```

#### export[[transformers.exporters.OnnxExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, Any], config: OnnxConfig | dict[str, Any])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_onnx.py#L126)

## ExecutorchExporter[[transformers.exporters.ExecutorchExporter]]

#### transformers.exporters.ExecutorchExporter[[transformers.exporters.ExecutorchExporter]]

```python
transformers.exporters.ExecutorchExporter()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_executorch.py#L109)

Exportador que converte um [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel) em um `ExecutorchProgramManager` do ExecuTorch.

Exemplo:

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

>>> exporter = ExecutorchExporter()
>>> et_program = exporter.export(model, inputs, config=ExecutorchConfig(backend="xnnpack"))
>>> et_program.write_to_file("model.pte")
```

#### export[[transformers.exporters.ExecutorchExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, Any], config: ExecutorchConfig | dict[str, Any])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_executorch.py#L126)

Exporte um modelo para o ExecuTorch, aplicando a preparação do backend e patches de operações do torch.

## DynamoConfig[[transformers.exporters.DynamoConfig]]

#### transformers.exporters.DynamoConfig[[transformers.exporters.DynamoConfig]]

```python
transformers.exporters.DynamoConfig(export_format: ExportFormat = <ExportFormat.DYNAMO: 'dynamo'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L83)

**Parâmetros:**

dynamic (*bool*, *opcional*, padrão *False*) : Se deve exportar com formas dinâmicas (simbólicas). Quando *True* e *dynamic_shapes* não está definido, todas as dimensões dos tensors são definidas automaticamente como *Dim.AUTO*.

strict (*bool*, *opcional*, padrão *False*) : Se deve habilitar o modo estrito no *torch.export*. Executa o rastreamento simbólico completo e captura mais erros, mas é mais lento e tem maior probabilidade de falhar em modelos complexos.

dynamic_shapes (*dict[str, Any]*, *opcional*) : Especificações explícitas de formas dinâmicas por entrada passadas para *torch.export*. Tem precedência sobre *dynamic*.

prefer_deferred_runtime_asserts_over_guards (*bool*, *opcional*, padrão *False*) : Quando *True*, as verificações de forma dependentes dos dados são emitidas como asserts em tempo de execução no grafo exportado, em vez de falhar a exportação no momento do trace quando uma verificação não se mantém ao longo de todo o intervalo de formas simbólicas. A maioria dos LLMs de transformadores precisa que isso seja definido como *True* ao usar limites finos de `Dim(min=, max=)`. Não é necessário com `dynamic=True` / `Dim.AUTO`, onde o `torch.export` infere as relações de forma em vez de verificá-las contra os limites declarados pelo usuário.

quantizer ([*~exporters.quantizers.ExportQuantizer*], *opcional*) : Quantização pós-treinamento aplicada durante a exportação: [*~exporters.quantizers.PT2EQuantizer*] ou [*~exporters.quantizers.NNCFTorchFXQuantizer*] no grafo FX para todos os backends, [*~exporters.quantizers.OnnxRuntimeQuantizer*] no modelo ONNX convertido, ou [*~exporters.quantizers.NNCFOpenVINOQuantizer*] / [*~exporters.quantizers.NNCFOnnxQuantizer*] no modelo OpenVINO / ONNX convertido.

Classe de configuração para exportar modelos via *torch.export*.

## OnnxConfig[[transformers.exporters.OnnxConfig]]

#### transformers.exporters.OnnxConfig[[transformers.exporters.OnnxConfig]]

```python
transformers.exporters.OnnxConfig(export_format: ExportFormat = <ExportFormat.ONNX: 'onnx'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None, output_path: str | PathLike | None = None, opset_version: int | None = None, external_data: bool = True, optimize: bool = True, export_params: bool = True, keep_initializers_as_inputs: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L125)

**Parâmetros:**

output_path (`str` ou `PathLike`, *opcional*) : Caminho de saída para o arquivo `.onnx`. Quando `None` (padrão), o modelo exportado é mantido em memória como um `ONNXProgram` e não é gravado em disco.

opset_version (`int`, *opcional*) : Versão do opset ONNX a ser usada como alvo. O padrão é o opset mais recente suportado pela versão instalada do `onnxscript`.

external_data (`bool`, *opcional*, padrão `True`) : Armazena tensores de pesos grandes em um arquivo lateral `.onnx_data` separado, em vez de incorporá-los ao protobuf. Obrigatório para modelos cujos pesos excedem o limite de 2 GB do protobuf.

optimize (`bool`, *opcional*, padrão `True`) : Executa as passes de otimização do `onnxscript` (dobramento de constantes, eliminação de código morto, …) no grafo exportado. Desative para modelos que encontram bugs no otimizador upstream do `onnxscript`.

export_params (`bool`, *opcional*, padrão `True`) : Incorpora os pesos do modelo no grafo ONNX. Defina como `False` para exportar um grafo sem pesos (os pesos devem ser fornecidos em tempo de execução).

keep_initializers_as_inputs (`bool`, *opcional*, padrão `False`) : Expor inicializadores de pesos como entradas explícitas do grafo. Necessário para alguns runtimes ONNX mais antigos (opset < 9).

Classe de configuração para exportar modelos para ONNX via `torch.onnx.export`.

Herdita todos os campos de `DynamoConfig` (`dynamic`, `strict`, `dynamic_shapes`, `prefer_deferred_runtime_asserts_over_guards`).

## ExecutorchConfig[[transformers.exporters.ExecutorchConfig]]

#### transformers.exporters.ExecutorchConfig[[transformers.exporters.ExecutorchConfig]]

```python
transformers.exporters.ExecutorchConfig(export_format: ExportFormat = <ExportFormat.EXECUTORCH: 'executorch'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None, backend: str = 'xnnpack', alloc_graph_input: bool = True, alloc_graph_output: bool = True, alloc_mutable_buffers: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L167)

**Parâmetros:**

backend (`str`, *opcional*, padrão `"xnnpack"`) : Backend do ExecuTorch de destino. Valores suportados:  - `"xnnpack"` — Inferência em CPU por meio da biblioteca XNNPACK (padrão; funciona em qualquer lugar). - `"cuda"` — Inferência em GPU por meio do backend CUDA do ExecuTorch. - `"mlx"` — Inferência em GPU por meio do backend MLX do ExecuTorch em Apple Silicon.

alloc_graph_input (`bool`, *opcional*, padrão `True`) : Indica se a etapa de planejamento de memória reserva memória de arena para as entradas do grafo. Quando `False`, o tempo de execução usa diretamente os buffers de entrada fornecidos pelo chamador, em vez de copiá-los para a arena — assim, uma `USER_INPUT_MUTATION` in-place (por exemplo, uma escrita em `StaticCache`) é aplicada ao tensor do chamador, e não a uma cópia na arena.

alloc_graph_output (`bool`, *opcional*, padrão `True`) : Indica se a etapa de planejamento de memória reserva memória de arena para as saídas do grafo. Quando `False`, o chamador deve vincular os buffers de saída em tempo de execução (`Method::set_output_data_ptr`); vincular uma saída ao buffer da sua entrada mutada evita a cópia de saída.

alloc_mutable_buffers (`bool`, *opcional*, padrão `True`) : Indica se a etapa de planejamento de memória reserva memória de arena para buffers mutáveis (estado residente no modelo). Transmitido para o `MemoryPlanningPass`.

Classe de configuração para exportar modelos para o formato ExecuTorch.

Herdita todos os campos de `DynamoConfig` (`dynamic`, `strict`, `dynamic_shapes`, `prefer_deferred_runtime_asserts_over_guards`).

## OpenVINOConfig[[transformers.exporters.OpenVINOConfig]]

#### transformers.exporters.OpenVINOConfig[[transformers.exporters.OpenVINOConfig]]

```python
transformers.exporters.OpenVINOConfig(export_format: ExportFormat = <ExportFormat.OPENVINO: 'openvino'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None, output_path: str | PathLike | None = None, compress_to_fp16: bool = True, stateful: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L204)

**Parâmetros:**

output_path (*str* ou *PathLike*, *opcional*) : Caminho de saída para o arquivo *.xml* (o arquivo *.bin* correspondente é gravado junto). Quando *None* (padrão), o modelo convertido é mantido em memória como um `openvino.Model`.

compress_to_fp16 (*bool*, *opcional*, padrão *True*) : Comprime pesos de ponto flutuante para FP16 ao salvar — reduz o tamanho em disco pela metade com impacto desprezível na precisão na maioria dos modelos. Aplicado apenas quando `output_path` está definido.

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.

Classe de configuração para exportar modelos para o IR do OpenVINO via `openvino.convert_model`.

Herdita todos os campos de [*DynamoConfig*] (*dynamic*, *strict*, *dynamic_shapes*, *prefer_deferred_runtime_asserts_over_guards*).

## Quantizadores[[transformers.exporters.ExportQuantizer]]

#### transformers.exporters.ExportQuantizer[[transformers.exporters.ExportQuantizer]]

```python
transformers.exporters.ExportQuantizer(calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L32)

**Parâmetros:**

calibration_dataset (`Iterable[dict]`, *opcional*) : Dicionários de entrada nos quais o quantizador realiza a calibração: uma lista, ou um `DataLoader` cujos lotes são colacionados para as entradas do modelo. Para `~HfExporter.export_for_generation`, são os kwargs de generate, capturados em um conjunto de calibração por componente. Quando `None`, um quantizador que precisa de dados realiza a calibração nas próprias entradas de amostra da exportação, com um aviso.

Classe base para quantizadores de pós-treino aplicados durante a exportação.

Um quantizador declara os formatos de exportação que suporta e os pacotes de que precisa (com as versões em que foi testado, assim como os exportadores), bem como se ele quantiza o grafo FX de `torch.export`, antes de qualquer conversão (de modo que todos os backends recebem o resultado), ou o modelo para o qual um backend o converte (`onnx_ir.Model`, `openvino.Model`). O exportador valida-o em relação à exportação antecipadamente e, em seguida, chama `~ExportQuantizer.quantize` com esse modelo e as entradas de exemplo da exportação. Subclasse-o e implemente `quantize` para adicionar um novo método de quantização; um `CalibrationSet` mapeia as amostras de calibração para as entradas próprias do modelo.

#### quantize[[transformers.exporters.ExportQuantizer.quantize]]

```python
quantize(model: Any, sample_inputs: dict[str, Any], export_format: ExportFormat)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L77)

Quantize `model` (o grafo FX se `quantizes_fx_graph`, caso contrário, o modelo do backend) e retorne o resultado, calibrado em `calibration_dataset`, ou nos `sample_inputs` da exportação, quando não houver nenhum.

#### validate_environment[[transformers.exporters.ExportQuantizer.validate_environment]]

```python
validate_environment(export_format: ExportFormat)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L67)

Gera um erro se este quantizer não puder ser executado em uma exportação `export_format`, ou se um pacote necessário estiver ausente ou for muito antigo; emite um aviso quando a versão for diferente daquela em que foi testado.

#### with_calibration[[transformers.exporters.ExportQuantizer.with_calibration]]

```python
with_calibration(calibration_dataset: Iterable[dict[str, Any]])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L61)

Uma cópia deste quantizador que calibra em `calibration_dataset`.

#### transformers.exporters.quantizers.CalibrationSet[[transformers.exporters.quantizers.CalibrationSet]]

```python
transformers.exporters.quantizers.CalibrationSet(calibration_dataset: Iterable[dict[str, Any]] | None, sample_inputs: dict[str, Any], transform: Callable[[dict[str, Any]], Any])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L83)

Visualização re-iterável das amostras de calibração como entradas do modelo.

As amostras são o `calibration_dataset` do quantizador, ou o próprio `sample_inputs` da exportação (com um aviso, uma vez que são lidos) quando ele não possui nenhum. Elas podem ser qualquer mapeamento, como um `BatchEncoding` de um tokenizer. O `transform` mapeia cada amostra de kwarg de forward para o que o modelo quantizado recebe (kwarg rastreados, feeds ONNX, feeds de porta OpenVINO), de forma preguiçosa, uma amostra por vez, em cada passagem.

#### transformers.exporters.PT2EQuantizer[[transformers.exporters.PT2EQuantizer]]

```python
transformers.exporters.PT2EQuantizer(quantizer: Any, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_pt2e.py#L34)

**Parâmetros:**

quantizer (`torchao.quantization.pt2e.quantizer.Quantizer`) : O quantizador PT2E que anota o grafo. Suas operações de quantização/desquantização devem ser aquelas suportadas pelo backend de destino: `X86InductorQuantizer` para inductor, ONNX (QDQ) ou OpenVINO, `XNNPACKQuantizer` para ExecuTorch.

calibration_dataset (`Iterable[dict]`, *opcional*) : Dicionários de entrada nos quais os observadores calibram (veja `ExportQuantizer`), um forward cada. Para calibrar em lotes, passe um `DataLoader` que agrupa as amostras em dicionários de entrada em lote, em vez de uma lista de amostras individuais.

Quantize o grafo FX com a quantização [PyTorch 2 Export (PT2E)](https://docs.pytorch.org/ao/main/pt2e_quantization/index.html): `prepare_pt2e` insere observadores, o conjunto de calibração os direciona e `convert_pt2e` os substitui por operações de quantize/dequantize. Funciona com todos os backends de exportação.

Exemplo:

```python
>>> 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))
```

#### transformers.exporters.OnnxRuntimeQuantizer[[transformers.exporters.OnnxRuntimeQuantizer]]

```python
transformers.exporters.OnnxRuntimeQuantizer(config: OnnxRuntimeStaticConfig | OnnxRuntimeDynamicConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L78)

Quantize o modelo ONNX convertido com as próprias ferramentas do ONNX Runtime (`onnxruntime.quantization`): `quantize_static` com um `OnnxRuntimeStaticConfig` (o padrão) ou `quantize_dynamic` com um `OnnxRuntimeDynamicConfig`.

Exemplo:

```python
>>> 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[[transformers.exporters.OnnxRuntimeStaticConfig]]

```python
transformers.exporters.OnnxRuntimeStaticConfig(quant_format: Any = None, op_types_to_quantize: list[str] | None = None, per_channel: bool | None = None, reduce_range: bool | None = None, activation_type: Any = None, weight_type: Any = None, nodes_to_quantize: list[str] | None = None, nodes_to_exclude: list[str] | None = None, calibrate_method: Any = None, calibration_providers: list[str] | None = None, extra_options: dict[str, Any] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L41)

Argumentos de `onnxruntime.quantization.quantize_static`: ativações e pesos int8 (QDQ por padrão), calibrados no `calibration_dataset` do quantizador. Um campo deixado como `None` mantém o padrão do ONNX Runtime. Consulte [`quantize_static`](https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html) para cada um.

#### transformers.exporters.OnnxRuntimeDynamicConfig[[transformers.exporters.OnnxRuntimeDynamicConfig]]

```python
transformers.exporters.OnnxRuntimeDynamicConfig(op_types_to_quantize: list[str] | None = None, per_channel: bool | None = None, reduce_range: bool | None = None, weight_type: Any = None, nodes_to_quantize: list[str] | None = None, nodes_to_exclude: list[str] | None = None, extra_options: dict[str, Any] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L62)

Argumentos de `onnxruntime.quantization.quantize_dynamic`: pesos int8, ativações quantizadas em tempo de execução, sem calibração. Um campo deixado como `None` mantém o padrão do ONNX Runtime. Consulte [`quantize_dynamic`](https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html) para cada um deles.

#### transformers.exporters.NNCFOpenVINOQuantizer[[transformers.exporters.NNCFOpenVINOQuantizer]]

```python
transformers.exporters.NNCFOpenVINOQuantizer(config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L143)

Quantize o modelo OpenVINO convertido com [NNCF](https://github.com/openvinotoolkit/nncf): `nncf.quantize` com um `NNCFQuantizationConfig` (o padrão), ou `nncf.compress_weights` com um `NNCFWeightCompressionConfig`.

Exemplo:

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

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

#### transformers.exporters.NNCFOnnxQuantizer[[transformers.exporters.NNCFOnnxQuantizer]]

```python
transformers.exporters.NNCFOnnxQuantizer(config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L175)

Quantize o modelo ONNX convertido com [NNCF](https://github.com/openvinotoolkit/nncf) por meio de seu backend ONNX: `nncf.quantize` com uma `NNCFQuantizationConfig` (o padrão, int8 QDQ), ou `nncf.compress_weights` com uma `NNCFWeightCompressionConfig` (int4 como `MatMulNBits` do ONNX Runtime).

Exemplo:

```python
>>> 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[[transformers.exporters.NNCFTorchFXQuantizer]]

```python
transformers.exporters.NNCFTorchFXQuantizer(config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L231)

Quantize o grafo FX do `torch.export` com [NNCF](https://github.com/openvinotoolkit/nncf) por meio de seu backend TorchFX: `nncf.quantize` com um `NNCFQuantizationConfig` (o padrão, ops `quantize`/`dequantize`), ou `nncf.compress_weights` com um `NNCFWeightCompressionConfig`. Assim como o `PT2EQuantizer`, ele é executado antes de qualquer conversão, de modo que todos os backends recebem seu resultado. O ExecuTorch reduz apenas o resultado somente de pesos: o XNNPACK não delega os ops `quantize`/`dequantize`, e o ExecuTorch não possui kernels para eles.

Exemplo:

```python
>>> from transformers.exporters import DynamoConfig, NNCFTorchFXQuantizer

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

#### transformers.exporters.NNCFQuantizationConfig[[transformers.exporters.NNCFQuantizationConfig]]

```python
transformers.exporters.NNCFQuantizationConfig(mode: Any = None, preset: Any = None, target_device: Any = None, subset_size: int | None = None, fast_bias_correction: bool | None = None, model_type: Any = None, ignored_scope: Any = None, advanced_parameters: Any = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L58)

Argumentos de `nncf.quantize`: ativações e pesos int8, calibrados no `calibration_dataset` do quantizador. Um campo deixado como `None` mantém o padrão do NNCF, exceto `model_type`, que tem como padrão `nncf.ModelType.TRANSFORMER`. Consulte [`nncf.quantize`](https://openvinotoolkit.github.io/nncf/autoapi/nncf/index.html#nncf.quantize) para cada um deles.

#### transformers.exporters.NNCFWeightCompressionConfig[[transformers.exporters.NNCFWeightCompressionConfig]]

```python
transformers.exporters.NNCFWeightCompressionConfig(mode: Any = None, ratio: float | None = None, group_size: int | None = None, ignored_scope: Any = None, all_layers: bool | None = None, sensitivity_metric: Any = None, subset_size: int | None = None, awq: bool | None = None, scale_estimation: bool | None = None, gptq: bool | None = None, lora_correction: bool | None = None, backup_mode: Any = None, compression_format: Any = None, advanced_parameters: Any = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L76)

Argumentos de `nncf.compress_weights`: int8 ou int4 apenas para pesos, com métodos conscientes dos dados (AWQ, estimativa de escala, GPTQ) para os modos int4. Os modos int8 são independentes de dados; os outros calibram no `calibration_dataset` do quantizador. `gptq` e `lora_correction` são exclusivos do OpenVINO. Um campo deixado como `None` mantém o padrão do NNCF. Consulte [`nncf.compress_weights`](https://openvinotoolkit.github.io/nncf/autoapi/nncf/index.html#nncf.compress_weights) para cada um.

## Utilitários[[transformers.exporters.utils.get_leaf_tensors]]

Funções de nível inferior que sustentam o `export_for_generation`, úteis quando você precisa intervir entre a decomposição de um modelo e a exportação de cada componente.

#### transformers.exporters.utils.get_leaf_tensors[[transformers.exporters.utils.get_leaf_tensors]]

```python
transformers.exporters.utils.get_leaf_tensors(obj: Any)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L340)

**Parâmetros:**

obj (`Any`) : Um tensor, dataclass, dict, list, tuple ou qualquer aninhamento desses.

**Retorna:** `dict[str, torch.Tensor]`

Mapeamento plano de strings de caminho pontuado para tensores.

Recupere recursivamente todos os tensores folha de uma estrutura potencialmente aninhada.

#### transformers.exporters.utils.prepare_for_export[[transformers.exporters.utils.prepare_for_export]]

```python
transformers.exporters.utils.prepare_for_export(model: PreTrainedModel | torch.nn.Module, inputs: MutableMapping[str, Any])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L407)

Configure o modelo e as entradas para a exportação. Modifica tanto `model` quanto `inputs` no local, retornando `(model, inputs, output_flags)`, onde `output_flags` contém os valores removidos de `inputs` para `use_cache`, `return_dict`, etc. (a serem aplicados de forma reversível em `model.config` por `patch_model_config` durante o trace).

- Remove as entradas de rótulo (`labels`, `future_values`) — o cálculo de perda não é suportado.
- Extrai as flags de saída (`use_cache`, `return_dict`, …) de `inputs` para que não apareçam como kwargs rastreados; os valores são retornados para que o bloco de trace os aplique em `model.config`.
- Pré-computa os kwargs de visão/áudio dependentes de dados registrados via `@register_export_input_preparer` e os grava em `inputs`.
- Converte os tensores de entrada para corresponder ao `dtype` / `device` do modelo.

#### transformers.exporters.utils.decompose_prefill_decode[[transformers.exporters.utils.decompose_prefill_decode]]

```python
transformers.exporters.utils.decompose_prefill_decode(model: PreTrainedModel, inputs: dict[str, Any], generation_config: Any = None, multi_token_decode: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L811)

**Retorna:** `dict[str, tuple[torch.nn.Module, dict]]`

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

Execute `model.generate()` e capture as entradas de prefill e decode.

Reutiliza todo o mecanismo de geração para que cada arquitetura (somente decodificador, SSM, codificador-decodificador, multimodal, …) receba entradas corretas sem reimplementar o loop.

`generation_config` é encaminhado para `generate()` (padrão: o próprio do modelo), de modo que as entradas capturadas utilizam o cache que `generate()` construiria. Passe um com `cache_implementation="static"` e `max_cache_len=N` para capturar um cache de **tamanho estático** nas entradas de decodificação — a base para uma exportação com cache estático. `max_cache_len` dimensiona o cache de forma independente da captura, de modo que a decodificação exportada utiliza um cache fixo `[..., N, ...]` em vez de um que cresce.

Quando `multi_token_decode`, o componente `decode` é capturado como um **multi-token** decode — duas etapas consecutivas de decode mescladas (veja `_merge_decode_calls`) para que o eixo de sequência de consulta permaneça simbólico (um decode de token único especializaria esse eixo para 1). Em seguida, ele lida tanto com um token (decodificação comum) quanto com muitos (continuação a partir do passado, ou um prefill simples quando o cache está vazio). Caso contrário, `decode` é o decode clássico de token único.

#### transformers.exporters.utils.decompose_multimodal[[transformers.exporters.utils.decompose_multimodal]]

```python
transformers.exporters.utils.decompose_multimodal(model: PreTrainedModel, inputs: dict[str, Any])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L934)

**Retorna:** `dict[str, tuple[torch.nn.Module, dict]]`

Uma entrada `name: (module, inputs)` para cada submódulo detectado (codificador de imagem/áudio, projetor, modelo de linguagem, lm_head).

**Exceções:** ``ValueError``

- ``ValueError`` -- se nenhum submódulo multi-modal conhecido for encontrado no modelo.

Capture as entradas de cada submódulo multimodal por meio de uma única passagem de frente.

Detecta todos os submódulos multimodais conhecidos pelo nome do atributo (torre de visão, projetor, modelo de linguagem, lm_head, …) e captura os kwargs do forward durante uma chamada de `model(**inputs)`.

Cada submódulo é retornado como uma entrada separada `name: (module, inputs)` para exportação independente. A etapa de mesclagem de tokens (por exemplo, `masked_scatter` para modelos multimodais) é intencionalmente deixada fora dos grafos exportados — é responsabilidade do chamador montar `inputs_embeds` a partir das saídas do codificador antes de executar o decodificador.

#### transformers.exporters.utils.decompose_for_generation[[transformers.exporters.utils.decompose_for_generation]]

```python
transformers.exporters.utils.decompose_for_generation(model: PreTrainedModel, inputs: dict[str, Any], generation_config: Any = None, multi_token_decode: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L978)

**Parâmetros:**

model : Modelo generativo. Deve suportar `model.generate(**inputs)`.

inputs : kwargs de **Generate** — o que você passaria para `model.generate(**inputs)`.

generation_config : `GenerationConfig` opcional encaminhado para `generate()` durante a captura. Passe um com `cache_implementation="static"` + `max_cache_len=N` para exportar em relação a um cache de tamanho estático (veja `decompose_prefill_decode`).

multi_token_decode : Quando `True`, captura o componente `decode` como um decode de múltiplos tokens (eixo de sequência de consulta dinâmico: múltiplos tokens de uma vez — continuação a partir do passado, ou um prefill simples quando o cache está vazio); um decode de token único não pode permanecer dinâmico (veja `decompose_prefill_decode`).

**Retorna:** `{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.

Decomponha um modelo generativo em pares `(model, forward_inputs)` exportáveis de forma independente.

Executa `decompose_prefill_decode` para capturar os kwargs de forward de prefill e decode a partir de uma chamada real de `model.generate(**inputs, max_new_tokens=2)`. Se o prefill for multimodal (conforme `is_multimodal`), ele é dividido ainda mais em uma entrada por submódulo (codificador de visão/áudio, projetor, modelo de linguagem, `lm_head`) por meio de `decompose_multimodal`.

#### transformers.exporters.utils.is_multimodal[[transformers.exporters.utils.is_multimodal]]

```python
transformers.exporters.utils.is_multimodal(model: PreTrainedModel | torch.nn.Module)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L925)

Retorna `True` se o modelo for multimodal, com codificadores de modalidade e um modelo de linguagem.

Um modelo que não é um `PreTrainedModel` (por exemplo, um `nn.Module` simples) não possui os acessores canônicos `get_encoder`/`get_decoder` e, trivialmente, não é multimodal, portanto, retorna `False` diretamente.