Transformers 5.20.0 업그레이드: 캐시·커널·vLLM 호환성 점검

Transformers 5.20.0으로 올리기 전에 vLLM 의존성 범위와 커스텀 캐시·모델 import·중첩 설정의 수정 지점을 확인한다.

2026-10-27

vLLM을 함께 쓴다면 의존성 상한부터 확인한다

vLLM v0.32.0을 사용하는 환경에 Transformers 5.20.0을 넣으면 vLLM이 명시한 의존성 범위를 벗어난다. 커스텀 모델을 수정하기 전에, 업그레이드할 환경에서 이 조합을 요구하고 있는지부터 확인해야 한다.

이 글의 기준 릴리스는 **Transformers v5.20.0 (2026-10-15), vLLM v0.32.0 (2026-10-18)**이다. vLLM v0.32.0 릴리스 노트는 Dependencies와 Breaking Changes에 다음 요구사항을 명시한다.

transformers>=5.16.1,<5.20.0
tokenizers>=0.23.2

여기서 <5.20.0은 5.20.0을 포함하지 않는다. 따라서 같은 환경에서 vLLM v0.32.0의 요구사항을 충족하면서 Transformers 5.20.0을 선택할 수는 없다. tokenizers 최소 버전을 맞추는 것만으로 이 충돌이 해소되지도 않는다.

아래 그림은 vLLM의 Transformers 허용 범위와 이번 업그레이드 대상이 어디서 충돌하는지 보여 준다.

⤢✕요구요구허용 범위 밖vLLM v0.32.0transformers>=5.16.1,<5.20.0tokenizers =0.23.2Transformers 5.20.0

의존성 선언과 실제 서빙 환경에 vLLM v0.32.0이 포함돼 있다면, 그 환경의 Transformers 업그레이드를 먼저 보류한다. 이번 자료에는 다른 vLLM 버전의 호환 범위가 없으므로 대체 버전을 특정할 수는 없다. 다른 조합을 선택하려면 그 조합의 의존성 근거가 추가로 필요하다.

수정 대상을 호출·import·설정 경계로 나눈다

Transformers v5.20.0 릴리스 노트의 Breaking changes는 커스텀 모델과 서빙 코드에서 확인할 경계를 구체적으로 제시한다. 제거된 캐시 메서드, 다른 모델을 경유한 import, 커널 의존성, 중첩 설정 초기화가 각각 다른 수정 대상이다.

업그레이드 검토에서는 다음 표를 코드 점검 범위로 사용할 수 있다.

변경 지점 해당하는 코드·환경 확인하거나 수정할 내용
cache_utils.py의 deprecated 검사·메서드 제거 기존 캐시 메서드를 직접 호출하는 코드 제거된 호출을 현재 캐시 API로 전환
교차 모델 import 제거 다른 모델 모듈에 노출된 이름을 가져오는 코드 해당 이름의 원래 모듈로 import 경로 변경
kernels 최소 버전 상향 kernels를 사용하는 환경 0.17.2 이상 충족 여부와 폴백 설정 확인
SubConfigSpec 도입 커스텀 중첩 설정과 기존 모델 설정 하위 설정 선언·기본값 초기화 방식 점검
LUKE·mLUKE 특수 토큰 처리 변경 엔티티 토큰의 인코딩·디코딩 결과에 의존하는 코드 기존 저장 출력과 토큰 처리 결과 비교
EP 추론 속도 회귀 경고 EP 추론을 사용하는 환경 업그레이드 전후 추론 속도 비교

이 표의 모든 항목을 모든 모델에 일괄 적용할 필요는 없다. 직접 호출하는 캐시 API가 있는지, 커스텀 설정을 정의하는지, EP 추론을 사용하는지에 따라 점검 범위를 정하면 된다. 다만 코드가 실행된다는 사실만으로 토큰 출력이나 추론 속도까지 검증된 것은 아니다.

캐시 호출과 import는 실제 사용 경로를 따라 수정한다

cache_utils.py에서는 deprecated 상태였던 검사와 메서드가 제거됐다. 릴리스 노트는 영향을 받는 모델의 예로 minimax_m3_vl과 pi0를 들고, 해당 메서드를 계속 호출하는 코드를 현재 캐시 API로 전환하도록 안내한다.

직접 작성한 모델뿐 아니라 캐시를 감싸는 서빙 코드도 점검 대상이다. 확인할 것은 캐시 객체를 사용하는지 자체가 아니라, 그 객체에서 어떤 메서드를 호출하는지다. 제거된 메서드를 호출하는 경로를 찾았다면 해당 호출을 수정하고, 그 경로를 사용하는 생성 동작을 검증해야 한다.

제공된 릴리스 노트에는 제거된 메서드의 전체 이름이나 대체 호출 시그니처가 없다. 따라서 이름이 비슷한 메서드로 일괄 치환할 근거는 없다. 실제 호출과 현재 캐시 API를 대조해 수정 범위를 확정해야 한다.

캐시 수정 후에는 사용하는 실행 조건도 확인한다. 이번 릴리스에는 정적 캐시를 사용하는 generate()의 호스트 측 입력과 텐서 병렬 처리 관련 수정이 포함돼 있다. 해당 조건으로 서빙한다면 검증에서도 같은 조건을 사용해야 그 경로를 확인할 수 있다.

import 변경은 캐시 API와 별개다. embedding_gemma2, ijepa, lightglue 등에서는 다른 모델에서 우연히 가져와 노출하던 import가 제거됐다. modular converter도 이런 교차 모델 import를 추가하지 않도록 바뀌었다.

이 경로를 이용하던 코드는 필요한 이름을 원래 정의된 모듈에서 직접 가져오도록 수정한다. 중간 모델 모듈이 그 이름을 계속 노출하도록 되돌리는 방식은 릴리스가 제시한 수정 방향과 맞지 않는다. 캐시에서는 호출 대상 API를, import에서는 이름의 출처를 확인하는 식으로 문제를 구분하면 수정 지점이 분명해진다.

kernels 버전과 폴백 설정을 함께 확인한다

Transformers 5.20.0은 kernels 0.17.2 이상을 요구한다. 릴리스 노트는 이 최소 버전 상향을 커널 로드 실패 시 폴백 지원과 연결한다.

자료에 명시된 설정 표현은 다음과 같다.

use_fallback=KernelizeFallback.ALL

이 설정은 커널 로드가 실패했을 때 오류를 내는 대신 원래 구현으로 폴백할 수 있게 한다. 버전 요구사항을 충족하는 일과 폴백 설정을 확인하는 일은 구분해야 한다. 릴리스 노트는 0.17.2 이상에서 이 설정을 사용할 수 있다고 설명하지만, 버전만 올리면 모든 커널 호출에 자동으로 적용된다고 명시하지는 않는다.

다음 그림은 폴백 설정이 관여하는 커널 로드 실패 경로를 보여 준다.

⤢✕성공실패설정함설정하지 않음커널 로드로드 성공 여부커널 구현use_fallback=KernelizeFallback.ALL원래 구현으로 폴백오류

커널을 사용하는 코드에서는 의존성에 선언된 kernels 버전을 확인하고, 커널 로드 설정을 전달하는 위치에서 폴백 사용 여부를 확인한다. 로드 실패 시 원래 구현으로 계속 실행하려는 운영 요구가 있다면 그 경로도 검증 대상에 넣는다.

폴백이 가능하다는 사실만으로 성능이 같다고 판단할 수는 없다. 이번 자료에는 원래 구현과 커널 구현 사이의 성능 비교 수치가 없으므로, 폴백 지원을 성능 보장으로 해석해서는 안 된다.

SubConfigSpec은 중첩 설정의 기본값부터 점검한다

SubConfigSpec은 하위 설정 초기화를 중앙화하기 위해 도입됐다. 기본 하위 설정을 얻는 방식도 클래스 인스턴스화에서 dataclass 필드 기반 수집으로 바뀐다. 설정 유틸리티와 여러 모델 설정이 영향을 받으며, 커스텀 또는 기존 중첩 설정은 이 메커니즘으로 하위 설정을 선언하도록 수정이 필요할 수 있다.

따라서 커스텀 모델 설정을 관리한다면, 하위 설정 값을 명시한 경우와 생략해 기본값을 사용하는 경우를 함께 확인한다. 변경 지점이 기본 하위 설정을 수집하는 방식이므로, 완성된 설정을 넘기는 경로만 확인해서는 기본값 초기화가 유지되는지 알 수 없다.

아래 비교는 릴리스가 밝힌 기본 하위 설정 수집 방식의 변화를 보여 준다.

⤢✕ 기본 하위 설정 수집 방식의 변화 변경 전 vs 변경 후 비교 축 · 기본 하위 설정을 수집하는 방식 변경 전 클래스 인스턴스화로 기본 하위 설정 수집 VS 변경 후 dataclass 필드에서 기본 하위 설정 수집 SubConfigSpec 하위 설정 초기화 중앙화 Transformers 5.20.0 업그레이드: 캐시·커널·vLLM 호환성 점검

여기서 곧바로 전체 설정 클래스를 다시 작성할 필요는 없다. 먼저 하위 설정을 어디서 선언하고 기본값을 어떻게 구성하는지 확인한 뒤, SubConfigSpec 도입과 맞지 않는 부분을 수정한다. 자료에는 선언 예시나 전체 API가 없으므로 구체적인 생성자 인자와 코드 형태까지 확정할 수는 없다.

검증 결과에는 “설정 객체 생성 성공”보다 구체적인 내용을 남기는 편이 좋다. 어떤 하위 설정을 생략했고, 그때 필요한 기본 하위 설정이 구성됐는지를 기록하면 이번 변경의 영향을 직접 확인할 수 있다.

출력과 속도는 별도의 통과 조건으로 둔다

LUKE와 mLUKE는 <ent> 같은 엔티티 특수 토큰을 실제 특수 토큰으로 처리하도록 바뀌었다. 해당 토큰은 분리되지 않고, skip_special_tokens가 적용되며, 정규화 대상이 된다. 디코딩에서는 일반 어휘 토큰과 같은 공백 처리를 유지한다.

엔티티 토큰을 포함한 저장 출력이나 문자열 비교에 의존하는 코드라면 이 변경을 회귀 검증에 넣어야 한다. 같은 입력에서 토큰이 분리되는지, 특수 토큰을 건너뛸 때 결과가 어떻게 달라지는지, 디코딩 공백이 기대와 맞는지 확인한다. 결과가 이전과 다르더라도 곧바로 오류로 판단하지 말고, 릴리스가 명시한 처리 변경과 일치하는지 대조해야 한다.

EP 추론은 별도의 성능 확인이 필요하다. Transformers 5.20.0 릴리스 노트는 EP 추론에 속도 회귀가 있으며 수정 중이라고 경고한다. 같은 릴리스에 expert-parallel dispatch 수정 등이 포함됐다는 사실만으로 이 경고가 해소됐다고 볼 수는 없다.

EP를 사용하는 환경에서는 실제로 쓰는 모델과 입력 조건으로 업그레이드 전후 속도를 비교한다. 자료에는 회귀 폭이나 해결 버전이 없으므로 특정 감소율이나 수정 시점을 전제로 배포를 결정할 수 없다.

업그레이드의 통과 조건은 환경에 맞게 잡는다. vLLM v0.32.0 환경은 의존성 상한에서 먼저 걸러야 한다. Transformers 5.20.0을 적용할 수 있는 환경은 제거된 호출과 import, 중첩 설정 기본값, 커널 로드 실패 경로를 검증한다. LUKE·mLUKE나 EP를 사용한다면 출력과 속도까지 확인한 뒤 적용 여부를 결정한다.

TransformersvLLM의존성 관리모델 서빙커스텀 모델