Transformers v5.23.0 업그레이드: ExportedModel과 호환성 점검

Transformers v5.23.0의 ExportedModel 기반 내보내기를 적용하고 EP 설정, 오디오 의존성, 출력 처리에서 수정할 지점을 점검한다.

2026-11-22

내보내기 결과를 받는 코드부터 확인한다

OnnxConfig(output_path=...)로 저장 위치를 지정하거나 export()의 반환값을 기존 방식으로 처리하는 코드는 업그레이드 점검 대상이다. **transformers v5.23.0 (2026-11-13)**에서는 모든 내보내기가 ExportedModel을 반환하고, OnnxConfig와 OpenVINOConfig의 output_path 옵션은 제거됐다. 저장에는 save_pretrained를 사용한다.

공식 v5.23.0 릴리스노트는 이 변경을 breaking change로 명시한다. 내보내기 작업이 끝나는지만 확인해서는 부족하다. 반환값을 사용하는 코드와 저장된 결과를 다시 불러오는 코드까지 확인해야 한다.

새 API에서 ExportedModel은 원본 모델과 같은 kwargs를 받고 같은 출력 클래스를 반환한다. Hub에 올리고 다시 로드할 수 있으며, 로드한 모델은 해당 백엔드의 런타임에서 실행된다. 이 API는 Dynamo, ONNX Runtime, OpenVINO, ExecuTorch를 포괄한다.

아래 흐름에서 검증할 경계는 원본 모델의 호출 인터페이스, 저장되는 내보내기 결과, 재로딩 후 사용하는 백엔드 런타임이다.

⤢✕원본 모델export()ExportedModelsave_pretrainedHub 저장ExportedModel.from_pretrained백엔드 런타임같은 kwargs같은 출력 클래스

기존 호출부를 유지할 수 있는 인터페이스가 생겼다는 점과, 기존 내보내기 코드가 그대로 호환된다는 주장은 구분해야 한다. 특히 ONNX 프로그램은 onnx_ir.Model이 됐다. 반환값이나 프로그램 타입에 직접 의존하는 래퍼가 있다면 그 경계를 따로 점검한다.

생성과 저장, 재로딩을 이어서 검증한다

릴리스노트의 예시는 내보내기부터 Hub 저장, 재로딩, 호출까지 연결한다. 기존 파이프라인을 옮길 때도 이 범위를 검증 단위로 잡을 수 있다.

from transformers import AutoModel, AutoTokenizer
from transformers.exporters import ExportedModel, OnnxConfig, OnnxExporter

model = AutoModel.from_pretrained("google/embeddinggemma-2")
tokenizer = AutoTokenizer.from_pretrained("google/embeddinggemma-2")
inputs = tokenizer(["Exporters are here!"], return_tensors="pt")

exported = OnnxExporter().export(model, inputs, OnnxConfig(dynamic=True, ort_fusions="cuda"))
exported.push_to_hub("my-org/embeddinggemma-2-onnx")

exported_model = ExportedModel.from_pretrained("my-org/embeddinggemma-2-onnx", device="cuda")
outputs = exported_model(**inputs)  # same output class as model(**inputs)

이 코드는 릴리스노트에 제시된 예시다. 실제 적용에서는 Hub 저장소 이름을 자신의 대상으로 바꾸고, 내보내기 직후의 결과와 재로딩한 결과를 각각 호출해 확인한다. 원본과 같은 출력 클래스를 쓴다는 설명을 수치 결과까지 동일하다는 보장으로 확대해서는 안 된다.

수정 위치는 다음처럼 나눠 볼 수 있다.

점검 대상 v5.23.0의 계약 기존 코드에서 확인할 부분
export() 반환값 ExportedModel 반환 반환값을 직접 다루는 래퍼와 후속 처리
ONNX 프로그램 onnx_ir.Model 사용 프로그램 타입에 의존하는 처리
output_path OnnxConfig, OpenVINOConfig에서 제거 설정 생성부와 저장 호출부
사용자 정의 백엔드 register_backend로 등록 백엔드 등록 코드
저장·로드 모델처럼 저장·로드하고 모델 저장소의 subfolder도 선택 가능 배포 결과물의 저장·로딩 경로

저장 결과의 export.json에는 설정, 입력 shape, 패키지 버전, 입출력 이름이 기록된다. 배포 검토에서는 이 항목을 확인해 어떤 조건으로 내보낸 결과물인지 추적할 수 있다. PT2E, NNCF, ONNX Runtime의 양자화된 내보내기도 같은 방식으로 저장하고 실행한다.

따라서 내보내기 성공 여부와 함께 export.json의 내용, 재로딩 가능 여부, 재로딩 후 호출 결과를 검증 기록에 남기는 편이 좋다. 사용자 정의 백엔드가 있다면 내장 백엔드의 성공만으로 검증을 끝내지 말고 등록 경로도 확인한다.

성능 수치는 입력과 런타임을 붙여 읽는다

OnnxConfig(ort_fusions=...)는 내보내기 시점에 그래프를 ONNX Runtime의 fused transformer 연산으로 다시 작성한다. 지원 값은 "cpu", "cuda", "webgpu", "dml"이다. 대상에는 attention, KV cache에 대한 GroupQueryAttention, rotary, norm, MoE가 포함된다.

설정을 검토할 때는 목표 런타임에 맞는 값을 선택했는지 확인한다. 위 코드의 ort_fusions="cuda"와 릴리스노트의 TensorRT EP 벤치마크를 같은 실행 조건이라고 간주해서는 안 된다. 예시 코드와 성능 측정 설명은 구분해서 읽어야 한다.

릴리스노트는 EmbeddingGemma2의 8 × 128 tokens 입력에 대해 다음 수치를 제시한다. 아래 배수는 모두 해당 릴리스노트의 측정값이다.

실행 구성 하드웨어 eager PyTorch 대비 torch.compile 대비
ONNX Runtime + TensorRT EP A100 7.6배 1.4배
OpenVINO Xeon Platinum 8570 4.1배 2.2배
OpenVINO, int8 가중치 Xeon Platinum 8570 4.9배 2.6배

같은 입력 조건에서도 비교 기준에 따라 배수의 의미가 달라지므로, 성능 그림은 eager PyTorch 대비와 torch.compile 대비를 분리해 읽도록 구성한다.

⤢✕ EmbeddingGemma2 내보내기 성능의 비교 기준 비교 기준: eager PyTorch 대비 · torch.compile 대비 공통 측정 입력 EmbeddingGemma2 · 8 × 128 tokens 모든 수치: v5.23.0 릴리스노트의 측정값 하드웨어 실행 구성 비교 기준 eager PyTorch 대비 torch.compile 대비 A100 ONNX Runtime + TensorRT EP 7.6배 1.4배 Xeon Platinum 8570 OpenVINO 4.1배 2.2배 OpenVINO int8 가중치 4.9배 2.6배 출처: Transformers v5.23.0 릴리스노트 | Transformers v5.23.0 업그레이드: ExportedModel과 호환성 점검

OpenVINO 내보내기는 attention, RoPE, MoE experts, 압축된 int8/int4 가중치에 대해 OpenVINO의 fused CPU 커널을 사용한다. 릴리스노트에는 decode가 이전보다 2.4–3.9배 빨라졌다는 설명도 있다. 이 수치는 위 표의 eager 또는 torch.compile 대비 수치와 비교 기준이 다르다.

실무에서는 측정값을 목표치로 복사하기보다 비교 조건을 가져온다. 사용하는 모델과 입력, 하드웨어, 런타임, 가중치 조건을 기록하고 현재 서빙 경로와 비교한다. 제시된 자료만으로는 다른 모델이나 입력 길이에서 같은 배수를 기대할 근거가 없다.

EP 설정과 출력 후처리를 따로 점검한다

Expert Parallel을 사용하는 경로에서는 ep_router 스타일 제거가 직접적인 수정 대상이다. 기존 설정에 이 이름이 남아 있는지 확인하고, 제거된 스타일을 전제로 하는 실행 경로를 다시 검증해야 한다.

MXFP4 GPT-OSS experts는 ep_dispatch_experts를 통해 실행하도록 바뀌었다. GPT-OSS를 사용하더라도 자신의 경로가 MXFP4 experts에 해당하는지 먼저 구분한다. 릴리스노트는 deepgemm_megamoe EP 구현도 breaking change 목록에 올렸지만, 제공된 발췌만으로 기존 구현과의 상세 대응 관계를 확정할 수는 없다.

이 변경들을 하나의 설정 이름 교체로 처리하지 않는 편이 좋다. ep_router 제거, MXFP4 GPT-OSS의 실행 변경, deepgemm_megamoe 관련 항목은 각각 자신이 쓰는 경로에 해당하는지 확인한다.

학습·서빙 코드가 반환값을 가공한다면 ModelOutput 변경도 확인해야 한다. 이번 릴리스에서는 rope deltas가 ModelOutput에서 제거됐다. 해당 값을 읽는 후처리가 있다면 출력 접근부가 점검 대상이다. 발췌에는 대체 값을 어디서 얻는지 제시돼 있지 않으므로 임의의 대체 필드를 가정해서는 안 된다.

처리 기본값이 클래스로 이동한 변경도 있다. 기본값을 직접 참조하거나 수정하는 코드라면 그 접근 방식을 확인한다. 기본 호출만 확인하는 검증과 별도로, 프로젝트가 처리 기본값이나 출력 객체의 내부 항목에 의존하는 부분을 찾아야 한다.

오디오 extras와 디코딩 지원 상태를 분리한다

[audio] extras는 torchaudio, soundfile, soxr로 축소됐다. librosa와 phonemizer는 빠졌다. 따라서 프로젝트가 [audio] 설치만으로 이들 패키지를 확보한다고 가정했다면 의존성 구성을 수정해야 한다.

확인할 것은 Transformers의 설치 성공 여부와 프로젝트의 실제 오디오 처리 경로다. 프로젝트 코드가 librosa나 phonemizer를 직접 사용한다면 필요한 패키지를 별도 의존성으로 선언하고, 그 구성이 반영된 환경에서 해당 경로를 검증한다.

Wav2Vec2ProcessorWithLM과 pyctcdecode/kenlm LM decoding은 deprecation 대상이다. 이는 extras에서 패키지가 빠진 변경과 별개의 지원 상태 변경이다. 제공된 자료에는 대체 API나 제거 일정이 없으므로, 여기서 특정 마이그레이션 경로나 시점을 단정할 수는 없다.

아래 분기는 설치 구성을 보완할 문제와 디코딩 지원 상태를 검토할 문제를 나눈다. 같은 프로젝트라면 두 경로 모두 해당할 수 있다.

⤢✕사용미사용사용미사용오디오 코드 점검librosa 또는 phonemizer사용 여부별도 의존성 선언과 설치 확인torchaudio · soundfile ·soxr 구성 확인Wav2Vec2ProcessorWithLM또는 pyctcdecode/kenlm사용 여부deprecation 영향 검토해당 디코딩 변경의 직접 점검대상 아님

기존 환경에서 우연히 남아 있는 패키지가 의존성 누락을 가릴 수 있으므로, 프로젝트에 선언된 설치 구성으로 오디오 경로를 확인하는 것이 검증 목적에 맞다. deprecation 대상 사용 여부는 설치 확인 결과와 별도로 기록한다.

사용하는 모델과 경로를 기준으로 업그레이드를 닫는다

신규 모델 지원을 도입 이유로 삼는 경우에도 지원 범위를 확인해야 한다. JEV와 decision pipeline은 실험적이며 API, 설정, 동작이 바뀔 수 있다고 명시돼 있다. 운영에 넣는다면 현재 호출 방식이 고정된 계약이라고 가정하지 말고 검증 범위에 포함한다.

IQuestCoder는 Transformers auto class에서 Llama 구현으로 로드되지만, IQuest-Coder-V1-*-Loop-* 체크포인트는 다른 아키텍처를 사용하며 지원되지 않는다. 모델 이름의 계열이 같다는 이유로 지원 여부를 넓혀 해석해서는 안 된다.

InternLM3 역시 Llama 구현으로 로드된다. InternLM3Config는 qkv_bias와 bias를 각각 attention_bias와 mlp_bias로 읽으며, 두 값이 같아야 한다. 릴리스된 체크포인트는 이 조건을 만족한다. 설정을 별도로 다루는 코드라면 이 제약을 확인한다.

업그레이드 완료 판단은 프로젝트가 사용하는 경로별로 남긴다.

  • 내보내기를 사용한다면 ExportedModel 반환값, 저장 방식, 재로딩 후 호출을 확인한다.
  • EP를 사용한다면 제거된 스타일과 해당 모델의 실행 변경을 확인한다.
  • 오디오를 사용한다면 선언된 의존성으로 실행되는지 확인하고 deprecation 대상 사용을 기록한다.
  • 출력 후처리나 처리 기본값을 직접 다룬다면 해당 접근부를 검증한다.
  • 신규 모델을 도입한다면 체크포인트의 지원 범위와 실험적 API 여부를 확인한다.

v5.23.0의 내보내기는 생성한 결과를 저장·공유하고 백엔드 런타임에서 다시 실행하는 흐름으로 이어진다. 업그레이드 검증도 이 경계를 따라가야 한다. 패키지를 바꾼 환경에서 실제 입력을 넣고, 프로젝트가 사용하는 저장·로드·호출 경로까지 확인한 결과가 완료 근거가 된다.

TransformersMLOpsONNX모델서빙의존성관리