# Exporters

새로운 export backends는 `HfExporter`를 서브클래스로 상속하고 [register_backend()](/docs/transformers/v5.23.0/ko/main_classes/exporters#transformers.exporters.register_backend)로 등록하여 Transformers에 추가할 수 있습니다.

[Exporters](../exporters) 가이드에서 내장된 내보내기 도구를 사용하는 방법을 배워보세요.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/auto.py#L112)

`ExportConfig`를 기반으로 올바른 `HfExporter`를 자동으로 인스턴스화하는 Auto-HF exporter 클래스입니다.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/auto.py#L101)

사전에 저장된 export config를 기반으로 올바른 export config로 자동으로 dispatch하는 작업을 담당하는 Auto-HF export config 클래스입니다.

## register_backend[[transformers.exporters.register_backend]]

#### transformers.exporters.register_backend[[transformers.exporters.register_backend]]

```python
transformers.exporters.register_backend(exporter: type[HfExporter], runner: type[ModelRunner] | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/auto.py#L61)

`config_class`와 함께 `export_format` 아래에 exporter를 등록하고, 해당 exporter의 내보내기를 실행하는 runner를 등록하여 auto 클래스가 이를 찾을 수 있도록 합니다.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L321)

모든 Transformers 내보내기기의 추상 베이스 클래스입니다.

백엔드를 추가하려면 서브클래스를 생성하고 `~HfExporter.export_program`을 구현하여 하나의 그래프를 추적하고, `~HfExporter.save_program` / `~HfExporter.load_program`을 구현하여 이를 작성하고 다시 읽습니다. 공개된 `~HfExporter.export`와 `~HfExporter.export_for_generation`는 이들을 기반으로 `ExportedModel`을 구성합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L407)

**반환값:** `ExportedModel`

`"model"` 단일 구성 요소; 백엔드의 프로그램은 `.program`이며, `save_pretrained`는 메타데이터와 모델 구성과 함께 이를 저장합니다.

모델을 하나의 그래프로 내보냅니다.

`~HfExporter.export_program`과 동일한 **forward** kwargs를 받습니다.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L426)

**매개변수:**

model ([PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)): 내보낼 생성 모델입니다. `model.generate(**sample_inputs)`를 지원해야 합니다.

sample_inputs (`dict[str, torch.Tensor | Cache]`) : **Generate** kwargs — `model.generate(**sample_inputs)`에 전달할 인자(일반적으로 `input_ids` + `attention_mask`, 멀티모달 모델의 경우 `pixel_values` / `input_features`와 같은 모달리티 입력 포함). 단계별 forward kwargs는 내부적으로 캡처됩니다.

config (`ExportConfigMixin` 또는 `dict[str, ExportConfigMixin]`) : 백엔드별 구성입니다. 모든 컴포넌트에 적용할 단일 구성을 전달하거나, 컴포넌트 이름(예: `"image_encoder"`, `"language_model"`, `"lm_head"`, `"decode"`)을 키로 하는 `dict`를 전달하여 컴포넌트별로 오버라이드할 수 있습니다. 이 경우 dict에 모든 컴포넌트 이름이 포함되어야 합니다.

generation_config ([GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig), *선택*) : `generate()` 캡처로 전달됩니다(기본값은 모델 자체의 설정). 고정 크기의 `StaticCache`에 대해 내보내려면 `cache_implementation="static"`가 포함된 설정을 전달하세요.

multi_token_decode (`bool`, *선택 사항*, 기본값 `False`) : `decode` 구성 요소가 여러 쿼리 토큰을 한 번에 처리하는지 여부입니다. 동적 쿼리 축(빈 캐시인 경우 prefill, 그렇지 않은 경우 과거로부터의 연속 처리)을 사용하는지, 아니면 고전적인 단일 토큰 단계( [decompose_for_generation()](/docs/transformers/v5.23.0/ko/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) 참조)를 사용하는지를 결정합니다. 동적 형식 내보내기(`config.dynamic=True`) 환경에서만 동적으로 유지됩니다.

**반환값:** `ExportedModel`

각 스테이지마다 `ExportedComponent`가 하나씩 있으며, [decompose_for_generation()](/docs/transformers/v5.23.0/ko/main_classes/exporters#transformers.exporters.utils.decompose_for_generation)과 동일한 키를 사용합니다.

생성 모델을 분해하고 각 구성 요소를 독립적으로 내보냅니다.

Thin wrapper around [decompose_for_generation()](/docs/transformers/v5.23.0/ko/main_classes/exporters#transformers.exporters.utils.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()](/docs/transformers/v5.23.0/ko/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) directly.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L351)

**매개변수:**

model ([PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)): 내보낼 모델.

sample_inputs (`dict[str, torch.Tensor | Cache]`) : **Forward** kwargs — `model(**sample_inputs)`에 전달할 인자입니다. 트레이싱 중 예시 입력으로 직접 사용됩니다. 오토레그레시브 디코드 스텝 내보내기의 경우, `past_key_values`, `cache_position` 등을 포함해야 합니다. 생성 스타일 입력만 있는 경우, 대신 `~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[[transformers.exporters.HfExporter.load_program]]

```python
load_program(path: str | Path)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L385)

`~HfExporter.save_program`로 저장된 프로그램을 다시 읽습니다. `~HfExporter.export_program`이 반환한 값과 다를 수 있습니다. ExecuTorch용 런타임 `Program`이며, `ExecutorchProgramManager`는 파일로부터 재구성할 수 없습니다.

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

```python
program_files(filename: str)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L392)

`filename`로 저장된 프로그램에 대해 `~HfExporter.save_program`이 작성하는 파일들입니다: 파일 자체와 포맷이 파일 옆에 유지하는 것들(가중치, 외부 데이터)입니다.

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

```python
save_program(program: Any, path: str | Path)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L380)

`~HfExporter.export_program`에서 반환된 프로그램을 백엔드의 파일 형식으로 `path`에 작성합니다.

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

```python
validate_environment()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L347)

`required_packages`가 설치되어 있는지 확인하고 `tested_versions`와 버전이 일치하지 않으면 경고합니다.

## ExportedModel[[transformers.exporters.ExportedModel]]

#### transformers.exporters.ExportedModel[[transformers.exporters.ExportedModel]]

```python
transformers.exporters.ExportedModel(components: dict[str, ExportedComponent], export_format: ExportFormat | str, config: PreTrainedConfig | None = None, generation_config: GenerationConfig | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L67)

내보낸 모델: 그 그래프(`components`, `{name: ExportedComponent}`)와, 해당 그래프가 추적된 설정들. 이 모델은 원래 모델이 호출되던 방식과 동일한 방식으로 호출됩니다.

`~HfExporter.export`은 `.program`을 프로그램으로 하는 단일 `"model"` 컴포넌트를 생성하며, `~HfExporter.export_for_generation`은 각 generation 단계별로 하나의 컴포넌트를 생성합니다.

```python
>>> 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__[[transformers.exporters.ExportedModel.__call__]]

```python
__call__(share_inputs: bool = True, share_outputs: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L143)

단일 그래프 내보내기를 실행하며, 소스 모델이 반환하는 값을 반환합니다. 내보내기가 추적되지 않은 Kwargs는 제거되므로, 프로세서의 전체 출력을 전달할 수 있습니다. `share_inputs`와 `share_outputs`는 러너로 전달됩니다(`ModelRunner.__call__` 참조): `share_outputs`가 설정된 경우, 출력은 다음 호출까지 유효합니다.

#### 프로그램[[transformers.exporters.ExportedModel.program]]

```python
program()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L108)

backend의 자체 프로그램, 단일 그래프 내보내기에 사용됩니다.

#### to[[transformers.exporters.ExportedModel.to]]

```python
to(device = None, **runner_kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L130)

`device` ( `None`인 경우 백엔드의 기본값)의 백엔드 런타임에 프로그램을 로드합니다. `runner_kwargs`는 백엔드의 러너로 전달됩니다: ONNX Runtime의 경우 `providers`와 `session_options`, OpenVINO의 경우 `config`(컴파일 속성)와 `torch_threads`(모델 주위의 torch 작업과 CPU를 분할)입니다.

#### save_pretrained[[transformers.exporters.ExportedModel.save_pretrained]]

```python
save_pretrained(save_directory: str | Path, push_to_hub: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L156)

**매개변수:**

save_directory (`str` 또는 `Path`) : 작성할 디렉터리입니다. 존재하지 않으면 생성됩니다.

push_to_hub (`bool`, *선택 사항*, 기본값 `False`) : 저장된 파일을 `repo_id`로 Hub에도 업로드할지 여부입니다(기본값은 네임스페이스의 `save_directory` 이름입니다).

kwargs (`dict[str, Any]`, *선택 사항*) : Hub 업로드에 전달됩니다: `repo_id`, `commit_message`, `token`, `private`, ...

각 컴포넌트(파일 하나씩), 설정 파일, 그리고 각 컴포넌트의 파일 이름과 트레이싱 시 기록된 메타데이터를 명시하는 매니페스트를 작성합니다. `~ExportedModel.from_pretrained`는 이들을 다시 로드합니다.

#### from_pretrained[[transformers.exporters.ExportedModel.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | Path, device = None, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', subfolder: str = '', trust_remote_code: bool = False, **runner_kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L206)

**매개변수:**

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 기반 시스템을 사용하므로, `revision`은 git에서 허용하는 모든 식별자, 즉 브랜치 이름, 태그 이름 또는 커밋 id가 될 수 있습니다. Hub에서 만든 pull request를 테스트하려면 `revision="refs/pr/<pr_number>"`를 전달할 수 있습니다.

subfolder (`str`, *선택 사항*, 기본값 `""`) : 관련 파일이 huggingface.co의 모델 저장소 내 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.

trust_remote_code (`bool`, *선택 사항*, 기본값 `False`) : [from_pretrained()](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoConfig.from_pretrained)와 마찬가지로, 코드가 저장소에 있는 모델의 설정을 로드할지 여부.

runner_kwargs (*선택 사항*) : `~ExportedModel.to`와 동일한 백엔드 러너 옵션입니다. ONNX Runtime의 경우 `providers`와 `session_options`, OpenVINO의 경우 `config`와 `torch_threads`입니다.

`~ExportedModel.save_pretrained`가 작성한 내용을 로드합니다. 각 구성 요소는 해당 백엔드의 `~HfExporter.load_program`를 통해 메타데이터와 함께, 그리고 그 옆에 저장된 설정 파일과 함께 로드됩니다. 프로그램은 즉시 해당 백엔드의 런타임에 로드되어 실행 준비가 완료된 상태가 됩니다.

## ExportedComponent[[transformers.exporters.ExportedComponent]]

#### transformers.exporters.ExportedComponent[[transformers.exporters.ExportedComponent]]

```python
transformers.exporters.ExportedComponent(program: Any, metadata: ExportMetadata)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L60)

하나의 내보낸 그래프: 백엔드의 프로그램과 익스포터가 기록한 정보

## ExportMetadata[[transformers.exporters.ExportMetadata]]

#### transformers.exporters.ExportMetadata[[transformers.exporters.ExportMetadata]]

```python
transformers.exporters.ExportMetadata(architecture: str | None = None, packages: dict[str, str] = <factory>, export_config: dict[str, Any] = <factory>, export_dtype: str | None = None, export_device: str | None = None, kwargs: dict[str, dict] = <factory>, in_spec: str | None = None, out_spec: str | None = None, in_constants: dict[str, Any] = <factory>, out_constants: list = <factory>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/metadata.py#L58)

exporter가 하나의 그래프에 대해 기록한 내용(`build_export_metadata()`).

#### from_dict[[transformers.exporters.ExportMetadata.from_dict]]

```python
from_dict(values: Mapping[str, Any])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/metadata.py#L75)

dict에서 저장된 메타데이터를 빌드하되, 이 클래스에 없는 필드(새로운 버전에서 추가된 것)는 건너뜁니다.

## ModelRunner[[transformers.exporters.ModelRunner]]

#### transformers.exporters.ModelRunner[[transformers.exporters.ModelRunner]]

```python
transformers.exporters.ModelRunner(metadata: ExportMetadata)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/runners/base.py#L29)

백엔드에서 하나의 내보낸 프로그램을 실행합니다: `runner(**kwargs)`는 소스 모델이 반환하는 값을 반환합니다.

#### from_program[[transformers.exporters.ModelRunner.from_program]]

```python
from_program(program: Any, metadata: ExportMetadata, device = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/runners/base.py#L56)

프로그램의 러너가 export로 반환하거나 `~HfExporter.load_program`이 다시 읽을 때, `device`(`None`인 경우 백엔드의 기본값)에서 수행됩니다.

#### unflatten[[transformers.exporters.ModelRunner.unflatten]]

```python
unflatten(outputs: list)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/runners/base.py#L47)

…

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/exporter_dynamo.py#L69)

`ExportedProgram`으로 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)을 변환하는 Exporter입니다.

예:

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L407)

**반환값:** `ExportedModel`

`"model"` 단일 구성 요소; 백엔드의 프로그램은 `.program`이며, `save_pretrained`는 메타데이터와 모델 구성과 함께 이를 저장합니다.

모델을 하나의 그래프로 내보냅니다.

`~HfExporter.export_program`과 동일한 **forward** kwargs를 받습니다.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/exporter_onnx.py#L113)

[PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)을 ONNX 그래프(`onnx_ir.Model`)로 변환하는 Exporter입니다.

예:

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L407)

**반환값:** `ExportedModel`

`"model"` 단일 구성 요소; 백엔드의 프로그램은 `.program`이며, `save_pretrained`는 메타데이터와 모델 구성과 함께 이를 저장합니다.

모델을 하나의 그래프로 내보냅니다.

`~HfExporter.export_program`과 동일한 **forward** kwargs를 받습니다.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/exporter_executorch.py#L107)

[PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)을 ExecuTorch `ExecutorchProgramManager`로 변환하는 Exporter입니다.

예:

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/base.py#L407)

**반환값:** `ExportedModel`

`"model"` 단일 구성 요소; 백엔드의 프로그램은 `.program`이며, `save_pretrained`는 메타데이터와 모델 구성과 함께 이를 저장합니다.

모델을 하나의 그래프로 내보냅니다.

`~HfExporter.export_program`과 동일한 **forward** kwargs를 받습니다.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/configs.py#L92)

**매개변수:**

dynamic (*bool*, *optional*, 기본값 *False*) : 동적(상징적) shape로 내보낼지 여부입니다. *True*이고 *dynamic_shapes*가 설정되지 않은 경우, 모든 텐서 차원이 자동으로 *Dim.AUTO*로 설정됩니다.

strict (*bool*, *optional*, 기본값 *False*) : *torch.export*에서 strict mode를 활성화할지 여부입니다. 전체 symbolic trace를 실행하여 더 많은 오류를 포착하지만, 속도가 느리고 복잡한 모델에서 실패할 가능성이 더 높습니다.

dynamic_shapes (*dict[str, Any]*, *선택*) : *torch.export*에 전달되는 입력별 명시적 동적 shape 사양입니다. *dynamic*보다 우선합니다.

prefer_deferred_runtime_asserts_over_guards (*bool*, *optional*, 기본값 *False*) : *True*인 경우, 데이터 의존형 shape guard가 trace 시점에 guard가 전체 symbolic shape 범위에서 유지되지 않아 export가 실패하는 대신, export된 그래프에서 런타임 assert로 출력됩니다. 대부분의 transformer LLM은 세밀한 `Dim(min=, max=)` 경계를 사용할 때 이 값을 *True*로 설정해야 합니다. `dynamic=True` / `Dim.AUTO`를 사용하는 경우, `torch.export`가 사용자가 명시한 경계와 대조하여 shape 관계를 검증하는 대신 이를 추론하므로 이 설정은 필요하지 않습니다.

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[[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, opset_version: int | None = None, optimize: bool = True, ort_fusions: Literal['cpu', 'cuda', 'webgpu', 'dml'] | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/configs.py#L134)

**매개변수:**

opset_version (`int`, *선택 사항*) : 대상이 될 ONNX opset 버전입니다. 설치된 `onnxscript` 버전이 지원하는 최신 opset이 기본값입니다.

optimize (`bool`, *선택 사항*, 기본값 `True`) : 내보낸 그래프에 `onnxscript` 최적화 패스(상수 접기, 데드 코드 제거, …)를 실행합니다. 상위 `onnxscript` 최적화기 버그에 걸리는 모델의 경우 비활성화하세요.

ort_fusions (`str`, *선택 사항*) : 실행되는 execution provider(`"cpu"`, `"cuda"`, `"webgpu"` 또는 `"dml"`)의 ONNX Runtime ops로 그래프를 융합합니다. 융합된 그래프는 ONNX Runtime에서만 실행됩니다. `optimize=True`가 필요합니다.

`torch.onnx.export`를 통해 모델을 ONNX로 내보내는 데 사용되는 구성 클래스입니다.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/configs.py#L168)

**매개변수:**

backend (`str`, *선택 사항*, 기본값 `"xnnpack"`) : 대상 ExecuTorch 백엔드. 지원되는 값:  - `"xnnpack"` — XNNPACK 라이브러리를 통한 CPU 추론(기본값; 어디서든 실행 가능). - `"cuda"` — ExecuTorch CUDA 백엔드를 통한 GPU 추론. - `"mlx"` — Apple Silicon에서 ExecuTorch MLX 백엔드를 통한 GPU 추론.

alloc_graph_input (`bool`, *선택 사항*, 기본값 `True`) : 메모리 계획 패스가 그래프 입력을 위해 아레나 메모리를 예약하는지 여부입니다. `False`인 경우 런타임은 아레나로 복사하는 대신 호출자가 제공한 입력 버퍼를 직접 사용합니다. 따라서 인플레이스 `USER_INPUT_MUTATION`(예: `StaticCache` 쓰기)는 아레나 사본이 아니라 호출자의 텐서에 반영됩니다.

alloc_graph_output (`bool`, *선택 사항*, 기본값 `True`) : 메모리 계획 패스가 그래프 출력에 대한 아레나 메모리를 예약하는지 여부입니다. `False`인 경우, 호출자는 런타임에 출력 버퍼를 바인딩해야 합니다(`Method::set_output_data_ptr`). 출력을 변경된 입력의 버퍼에 바인딩하면 복사-아웃 왕복을 피할 수 있습니다.

alloc_mutable_buffers (`bool`, *선택 사항*, 기본값 `True`) : 메모리 계획 패스가 가변 버퍼(모델 상주 상태)에 대한 아레나 메모리를 예약하는지 여부입니다. `MemoryPlanningPass`로 전달됩니다.

ExecuTorch 형식으로 모델을 내보내기 위한 구성 클래스입니다.

`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, compress_to_fp16: bool = False, stateful: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/configs.py#L205)

**매개변수:**

compress_to_fp16 (*bool*, *optional*, 기본값 *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*)를 상속합니다.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/base.py#L33)

**매개변수:**

calibration_dataset (`Iterable[dict]`, *선택 사항*) : 양자화기가 보정(calibration)에 사용하는 입력 딕셔너리입니다. 리스트이거나, 배치 collate 결과가 모델 입력이 되는 `DataLoader`일 수 있습니다. `~HfExporter.export_for_generation`의 경우, 이는 generate kwargs이며, 컴포넌트별로 보정 세트로 캡처됩니다. `None`인 경우, 데이터가 필요한 양자화기는 경고와 함께 export 자체의 샘플 입력으로 보정합니다.

export 과정에서 적용되는 사후 학습 양자화기의 기본 클래스입니다.

Quantizer는 지원되는 내보내기 형식과 필요한 패키지(exporter와 마찬가지로 테스트된 버전 포함)를 선언하며, `torch.export` FX 그래프를 변환 전에 양자화하는지(즉, 모든 백엔드가 결과를 받는 경우) 아니면 백엔드가 변환한 모델(`onnx_ir.Model`, `openvino.Model`)을 양자화하는지를 명시합니다. Exporter는 이를 내보내기 전에 검증한 후, 해당 모델과 내보내기의 샘플 입력을 인자로 `~ExportQuantizer.quantize`를 호출합니다. 새로운 양자화 방법을 추가하려면 이를 서브클래스로 상속받아 `quantize`를 구현하세요. `CalibrationSet`는 교정 샘플을 모델 자체의 입력에 매핑합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/base.py#L83)

`model`(`quantizes_fx_graph`이 True인 경우 FX 그래프, 그렇지 않으면 백엔드 모델)을 양자화하고, `calibration_dataset` 또는 해당 데이터셋이 없는 경우 export의 `sample_inputs`로 보정된 결과를 반환합니다.

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

```python
traced_calibration(sample_inputs: dict[str, Any])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/base.py#L76)

FX-graph 양자화기를 위한 traced kwargs로 사용되는 보정 샘플.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/base.py#L68)

이 quantizer가 `export_format` export에서 실행할 수 없거나, 필요한 패키지가 없거나 버전이 너무 오래된 경우 예외를 발생시키고, 테스트된 버전과 다른 경우 경고를 표시합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/base.py#L62)

`calibration_dataset`에서 보정(calibration)을 수행하도록 설정된 이 양자화기의 복사본입니다.

#### 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])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/base.py#L89)

모델 입력으로 사용될 보정 샘플의 반복 가능한 뷰.

샘플은 양자화기의 `calibration_dataset`이거나, 해당 값이 없는 경우 내보내기의 자체 `sample_inputs`입니다(읽어 들여질 때 경고가 한 번 표시됩니다). 토크나이저의 `BatchEncoding`과 같은 임의의 매핑일 수 있습니다. `transform`는 모든 패스에서 한 번에 하나의 샘플씩 지연 방식으로, 각 forward-kwarg 샘플을 양자화 모델이 받는 형태(추적된 kwargs, ONNX feeds, OpenVINO port feeds)로 매핑합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_pt2e.py#L33)

**매개변수:**

quantizer (`torchao.quantization.pt2e.quantizer.Quantizer`) : 그래프에 주석을 달아주는 PT2E quantizer입니다. 해당 quantize/dequantize 연산은 대상 백엔드가 지원하는 것이어야 합니다: inductor의 경우 `X86InductorQuantizer`, ONNX (QDQ) 또는 OpenVINO, ExecuTorch의 경우 `XNNPACKQuantizer`.

calibration_dataset (`Iterable[dict]`, *선택 사항*) : 옵저버가 보정(calibrate)에 사용하는 입력 딕셔너리(자세한 내용은 `ExportQuantizer` 참조)로, 각 전방 전파(forward)마다 하나씩 전달됩니다. 배치 단위로 보정하려면 단일 샘플의 목록 대신 샘플을 배치된 입력 딕셔너리로 collate하는 `DataLoader`를 전달하세요.

[PyTorch 2 Export (PT2E) 양자화](https://docs.pytorch.org/ao/main/pt2e_quantization/index.html)로 FX 그래프를 양자화합니다: `prepare_pt2e`가 옵저버를 삽입하고, 캘리브레이션 세트가 이를 구동하며, `convert_pt2e`가 이를 양자화/디양자화 연산으로 대체합니다. 모든 내보내기 백엔드와 호환됩니다.

예:

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L78)

변환된 ONNX 모델을 ONNX Runtime 자체 도구(`onnxruntime.quantization`)로 양자화합니다: 기본값인 `OnnxRuntimeStaticConfig`와 함께 `quantize_static`을 사용하거나, `OnnxRuntimeDynamicConfig`와 함께 `quantize_dynamic`를 사용할 수 있습니다.

예:

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L41)

`onnxruntime.quantization.quantize_static`의 인자: int8 활성화 및 가중치(기본적으로 QDQ), 퀀타이저의 `calibration_dataset`로 보정됩니다. `None`으로 남겨진 필드는 ONNX Runtime의 기본값을 유지합니다. 각 인자에 대해서는 [`quantize_static`](https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html)을 참조하세요.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L62)

`onnxruntime.quantization.quantize_dynamic`의 인자: int8 가중치, 런타임에 양자화되는 활성화, 보정 없음. `None`으로 남겨둔 필드는 ONNX Runtime의 기본값을 유지합니다. 각 인자에 대한 자세한 내용은 [`quantize_dynamic`](https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html)을(를) 참조하세요.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_nncf.py#L143)

변환된 OpenVINO 모델을 [NNCF](https://github.com/openvinotoolkit/nncf)로 양자화합니다: `nncf.quantize`에 `NNCFQuantizationConfig`(기본값)를 사용하거나, `nncf.compress_weights`에 `NNCFWeightCompressionConfig`를 사용합니다.

예:

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_nncf.py#L175)

변환된 ONNX 모델을 [NNCF](https://github.com/openvinotoolkit/nncf)의 ONNX 백엔드를 통해 양자화합니다: `nncf.quantize`에 `NNCFQuantizationConfig`(기본값, int8 QDQ)를 사용하거나, `nncf.compress_weights`에 `NNCFWeightCompressionConfig`(ONNX Runtime의 `MatMulNBits`로 int4)를 사용합니다.

예:

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_nncf.py#L231)

`nncf.quantize`에 `NNCFQuantizationConfig`(기본값, `quantize`/`dequantize` 연산) 또는 `nncf.compress_weights`에 `NNCFWeightCompressionConfig`를 전달하여 [NNCF](https://github.com/openvinotoolkit/nncf)의 TorchFX 백엔드를 통해 `torch.export` FX 그래프를 양자화합니다. `PT2EQuantizer`와 마찬가지로 모든 변환 전에 실행되므로 모든 백엔드가 그 결과를 사용합니다. ExecuTorch는 weight-only 결과만 lowering합니다. XNNPACK은 `quantize`/`dequantize` 연산을 위임하지 않으며, ExecuTorch에는 해당 연산에 대한 커널이 없습니다.

예:

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_nncf.py#L58)

`nncf.quantize`의 인자: int8 activations 및 weights, quantizer의 `calibration_dataset`로 보정됩니다. `None`으로 남겨둔 필드는 `model_type`를 제외하고 NNCF의 기본값을 유지하며, `model_type`의 기본값은 `nncf.ModelType.TRANSFORMER`입니다. 각 인자에 대한 자세한 내용은 [`nncf.quantize`](https://openvinotoolkit.github.io/nncf/autoapi/nncf/index.html#nncf.quantize)를 참조하세요.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/quantizers/quantizer_nncf.py#L76)

`nncf.compress_weights`의 인수: 데이터 인식 방식(AWQ, scale estimation, GPTQ)을 지원하는 weight-only int8 또는 int4입니다. int8 모드는 데이터가 필요 없으며, 나머지 모드는 quantizer의 `calibration_dataset`로 calibrate합니다. `gptq`와 `lora_correction`은 OpenVINO 전용입니다. `None`으로 남겨 두면 NNCF의 기본값이 유지됩니다. 각 인수에 대한 자세한 내용은 [`nncf.compress_weights`](https://openvinotoolkit.github.io/nncf/autoapi/nncf/index.html#nncf.compress_weights)를 참조하세요.

## 유틸리티[[transformers.exporters.utils.get_leaf_tensors]]

`export_for_generation`를 뒷받침하는 저수준 함수로, 모델을 분해하는 단계와 각 구성 요소를 내보내는 단계 사이에 개입해야 할 때 유용합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/utils.py#L348)

**매개변수:**

obj (`Any`) : 텐서, dataclass, dict, list, tuple 또는 이들의 임의의 중첩 구조.

**반환값:** `dict[str, torch.Tensor]`

점으로 구분된 경로 문자열에서 텐서로의 평탄 매핑

…

#### 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])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/utils.py#L519)

내보내기를 위해 모델과 입력을 구성합니다. `model`과 `inputs`을 모두 인플레이 변경하며, `use_cache`, `return_dict` 등의 값이 `inputs`에서 제거되어 `output_flags`에 저장된 `(model, inputs, output_flags)`를 반환합니다. 이 값들은 트레이스 중에 `patch_model_config`에 의해 `model.config`에 가역적으로 적용됩니다.

- 레이블 입력(`labels`, `future_values`)을 제거합니다. 손실 계산은 지원되지 않습니다.
- `inputs`에서 출력 플래그(`use_cache`, `return_dict`, …)를 제거하여 추적된 kwargs로 나타나지 않도록 합니다. 해당 값은 반환되어 trace 블록이 `model.config`에 적용합니다.
- `@register_export_input_preparer`를 통해 등록된 데이터 의존형 vision/audio kwargs를 사전 계산하여 `inputs`에 기록합니다.
- 모델의 `dtype` / `device`에 맞게 입력 텐서를 변환합니다.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/utils.py#L922)

**반환값:** `dict[str, tuple[torch.nn.Module, dict]]`

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

`model.generate()`를 실행하고 prefill 및 decode 입력을 캡처합니다.

전체 생성 메커니즘을 재사용하여, 모든 아키텍처(decoder-only, SSM, encoder-decoder, multi-modal, …)가 루프를 다시 구현하지 않고도 올바른 입력을 받을 수 있도록 합니다.

`generation_config`은 `generate()`로 전달되며(기본값은 모델 자체의 설정), 캡처된 입력은 `generate()`가 구축할 캐시를 사용합니다. `cache_implementation="static"`와 `max_cache_len=N`를 전달하면 디코딩 입력에 **정적 크기의** 캐시를 캡처할 수 있으며, 이는 static-cache 내보내기의 기반이 됩니다. `max_cache_len`은 캡처와 무관하게 캐시 크기를 결정하므로, 내보낸 디코딩은 확장되는 캐시가 아닌 고정된 `[..., N, ...]` 캐시를 사용합니다.

`multi_token_decode`가 True인 경우, `decode` 구성 요소는 **멀티 토큰** 디코드로 캡처됩니다. 이는 두 개의 연속된 디코드 스텝을 병합한 것입니다(`_merge_decode_calls` 참조). 이렇게 하면 쿼리 시퀀스 축이 심볼릭 상태로 유지됩니다(단일 토큰 디코드의 경우 해당 축이 1로 특화됩니다). 이후 이 구성 요소는 단일 토큰(일반 디코딩)과 다중 토큰(과거 컨텍스트 기반 연속 처리 또는 캐시가 비어 있는 경우의 일반 프리필)을 모두 처리합니다. 그렇지 않은 경우 `decode`는 고전적인 단일 토큰 디코딩입니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/utils.py#L1045)

**반환값:** `dict[str, tuple[torch.nn.Module, dict]]`

감지된 서브모듈(이미지/오디오 인코더, 프로젝터, 언어 모델, lm_head)마다 `name: (module, inputs)` 항목이 하나씩 있습니다.

**예외:** ``ValueError``

- ``ValueError`` -- 모델에서 알려진 멀티모달 서브모듈을 찾지 못한 경우.

forward 패스 한 번으로 각 멀티모달 서브모듈의 입력을 캡처합니다.

속성 이름(vision tower, projector, language model, lm_head, …)을 기준으로 알려진 모든 멀티모달 서브모듈을 감지하고, `model(**inputs)` 호출 한 번 동안의 forward kwargs를 캡처합니다.

각 서브모듈은 독립적인 내보내기를 위해 `name: (module, inputs)` 항목으로 개별 반환됩니다. 토큰 병합 단계(예: 멀티모달 모델의 `masked_scatter`)는 의도적으로 내보낸 그래프 외부에 두며, 디코더를 실행하기 전에 인코더 출력에서 `inputs_embeds`를 조립하는 것은 호출자의 책임입니다.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/utils.py#L1089)

**매개변수:**

model : 생성 모델. `model.generate(**inputs)`를 지원해야 합니다.

inputs : **Generate** kwargs — `model.generate(**inputs)`에 전달할 인자.

generation_config : 캡처 중에 `generate()`로 전달되는 선택적 `GenerationConfig`입니다. 정적 크기의 캐시에 대해 내보내려면 `cache_implementation="static"` + `max_cache_len=N`를 포함하여 전달하세요(`decompose_prefill_decode` 참조).

multi_token_decode : `True`인 경우, `decode` 구성 요소를 다중 토큰 디코딩으로 캡처합니다(동적 쿼리 시퀀스 축: 한 번에 여러 토큰 — 과거에서 계속되는 경우 또는 캐시가 비어 있는 경우의 일반 prefill). 단일 토큰 디코딩은 동적으로 유지될 수 없습니다(`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 forward kwargs를 캡처합니다. prefill이 멀티모달인 경우(`is_multimodal` 기준), `decompose_multimodal`을 통해 서브모듈(비전/오디오 인코더, 프로젝터, 언어 모델, `lm_head`)별로 하나의 항목씩으로 추가 분할합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/exporters/utils.py#L1036)

모델이 모달 인코더와 언어 모델을 갖춘 멀티모달인 경우 `True`를 반환합니다.

`PreTrainedModel`이 아닌 모델(예: 단순한 `nn.Module`)은 정해진 `get_encoder`/`get_decoder` 접근자가 없으며, 당연히 멀티모달이 아니므로 `False`로 바로 반환됩니다.

