프레임워크

Transformers 라이브러리: pipeline() 한 줄 뒤에 숨은 100+ 모델 통합 인터페이스

164k 스타를 받은 ML 인프라의 핵심. AutoClass, Tokenizer, Model Hub이 어떻게 오픈소스 AI 생태계 전체를 하나로 연결하는지 코드 한 줄을 분해해 살펴본다.

글자 크기

GitHub에서 ML 프레임워크를 검색하면 Transformers가 가장 위에 뜬다 — 164k 스타, PyTorch보다도 많다.

하지만 그 숫자 자체는 핵심이 아니다. 진짜 중요한 건 이것이다: 누군가 arXiv에 새 모델을 올리는 순간, 제일 먼저 하는 일이 Transformers에 PR을 올려서 from_pretrained()로 로드할 수 있게 만드는 것이다. 이 라이브러리는 이미 오픈소스 AI의 사실 표준 인터페이스 계층이 됐다.

무엇을 해결하는가

2018년 BERT가 나오기 전까지, 모든 모델은 고립된 섬이었다. GPT-2를 돌리고 싶다? 작성자 코드를 찾아서 loader를 직접 고쳐야 했다. XLNet은? 또 다른 세트로 갈아끼워야 했다. 연구자는 논문을 쓰고, 엔지니어는 코드를 옮기고, 같은 일이 반복됐다.

Transformers가 한 가지를 했다: "모델 로드", "입력 전처리", "추론 실행", "출력 후처리" — 이 네 단계를 하나의 API로 추상화한 것이다. 새 모델을 만드는 사람은 PreTrainedModel 인터페이스에 맞게 서브클래스만 작성하면, pipeline, Trainer, 양자화, 분산 처리까지 생태계 전체가 즉시 동작한다.

현재 규모: 100개 이상의 모델 아키텍처, 텍스트·비전·오디오·비디오·멀티모달 전부 커버한다. 아래에 나열한 프레임워크들을 들어본 적 있을 텐데, 그 밑바탕은 전부 이 라이브러리다:

  • LLaMA-Factory (파인튜닝)
  • LangChain (Agent)
  • vLLM (추론 서빙)
  • peft (LoRA)
  • trl (RLHF)

Apache 2.0 라이선스, 상업적 사용 무제한.

사용법

설치는 한 줄:

pip install transformers

감성 분석은 세 줄:

from transformers import pipeline

classifier = pipeline("sentiment-analysis")
result = classifier("I love this library!")
print(result)
# [{'label': 'POSITIVE', 'score': 0.9998}]

이 세 줄 뒤에서 실제로 일어나는 일:

  1. pipeline("sentiment-analysis")이 기본으로 distilbert-base-uncased-finetuned-sst-2-english를 찾는다
  2. Hugging Face Hub에서 모델 가중치와 config를 내려받는다
  3. task에 맞춰 AutoTokenizer와 AutoModelForSequenceClassification을 자동으로 고른다
  4. 하나의 callable로 조립: 입력 텍스트 → tokenizer → model → 후처리 → label 출력

멀티모달로 바꿀 때도 문자열 하나만 바꾸면 된다:

vision = pipeline("image-classification", model="google/vit-base-patch16-224")
# vision("cat.jpg")

API는 완전히 동일하다. 모델을 바꿀 때 코드 손댈 필요 없이 문자열만 바꾼다.

각 단계를 직접 보고 싶다면 pipeline을 분해하면 된다:

from transformers import AutoTokenizer, AutoModelForSequenceClassification

tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased-finetuned-sst-2-english")
model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased-finetuned-sst-2-english")

inputs = tokenizer("I love this library!", return_tensors="pt")
outputs = model(**inputs)
prediction = outputs.logits.argmax(dim=-1)
print(model.config.id2label[prediction.item()])  # POSITIVE

이게 "로드 → 전처리 → 추론 → 후처리"의 풀 수동 버전이다.

동작 원리 (아키텍처)

세 가지 핵심 메커니즘이 라이브러리 전체를 연결한다:

1. AutoClass 체계

AutoModel, AutoTokenizer, AutoConfig는 한 묶음의 라우터다. checkpoint 이름(예: bert-base-chinese)을 넘기면 CONFIG_MAPPING_NAMES 딕셔너리를 조회해서 해당 설정 클래스(예: BertConfig)를 찾고 인스턴스화한다.

이 설계의 핵심: 100개 이상의 모델이 동일한 API를 공유한다. 모델을 바꿀 때 코드를 손댈 필요 없이 문자열만 바꾸면 된다.

2. Model Hub

huggingface.co/models는 세계 최대의 사전훈련 모델 저장소다. 백만 개가 넘는 checkpoint, 모델 카드, 버전, 평가 결과가 전부 올라와 있다. from_pretrained() 한 줄이 사실은 HTTP 요청 + 로컬 ~/.cache/huggingface/로의 캐싱이다.

국내 사용자는 환경변수로 미러를 설정한다:

export HF_ENDPOINT=https://hf-mirror.com

다운로드 속도가 수십 KB/s에서 수 MB/s로 바뀐다.

3. Pipeline 래퍼

tokenizer + model + postprocessor를 하나의 callable로 직렬화한다. pipeline("sentiment-analysis") 내부에서 task에 맞는 전처리 클래스와 후처리 클래스를 자동으로 선택한다.

전체 호출 체인:

사용자 코드 → pipeline() 팩토리 → AutoClass 라우팅 → Hub 가중치 다운로드
→ PreTrainedModel 로드 → tokenizer 전처리 → forward() 추론
→ 후처리기 → 사람이 읽을 수 있는 결과 반환

하단의 세 기둥: PreTrainedModel(모든 모델의 베이스 클래스), GenerationMixin(생성 로직), Trainer(훈련 루프). 위에서는 애플리케이션이 돌고, 아래에서는 훈련이 돌고, 그 사이에는 같은 회사에서 나온 datasets, accelerate 같은 보조 라이브러리들이 있다.

PyTorch가 주력이다. TF/Flax 지원은 아직 있지만 우선순위는 낮고, 새 모델은 거의 PyTorch 버전만 출시된다.

장점과 단점

좋은 점:

  • 생태계 두께: datasets, accelerate, peft, trl, tokenizers 모두 Hugging Face 제품이라 서로 맞물려 돌아간다
  • 신규 모델 출시의 표준 경로: 작성자가 논문을 내고 Transformers PR을 올리면, Hugging Face 팀이 직접 리뷰한다
  • 최상급 문서: 모든 모델이 독립 페이지를 가지고 있고, 논문 요약, 사용 예제, 추론 성능 데이터가 포함된다
  • 넘쳐나는 튜토리얼: 공식 코스, 각종 블로그, BiliBili 영상까지, 거의 모든 함정을 검색으로 해결할 수 있다

아쉬운 점:

  • 저수준 추상화가 무거워서 런타임 오버헤드가 작지 않다. 프로덕션에서 처리량을 추구한다면 vLLM, TGI, SGLang을 쓴다
  • 대형 모델은 메모리를 많이 먹는다. Qwen-7B fp16이면 14GB 넘게 필요하고, 로드도 느리고 추론도 느리다
  • pip 의존성 충돌이 가끔 발생한다. transformers를 올리면 accelerate, peft까지 영향을 미친다
  • Model Hub의 국내 직접 연결이 불안정해서 미러 설정이 필수다
  • TensorFlow 지원은 사실상 중단 상태. 팀이 여전히 TF 위에서 살고 있다면 마이그레이션 비용이 크다

직접 테스트해 봤다

테스트 1: M2 Mac에서 bert-base-chinese 감성 분석

import time, psutil
from transformers import pipeline

start = time.time()
classifier = pipeline("sentiment-analysis", model="bert-base-chinese")
load_time = time.time() - start  # 최초 로드 (다운로드 포함) 약 8초

start = time.time()
result = classifier("这个产品真的很好用")
latency = time.time() - start  # 단일 추론 약 120ms

mem = psutil.Process().memory_info().rss / 1024**2  # 약 1.2GB
print(f"로드: {load_time:.2f}s, 지연: {latency*1000:.0f}ms, 메모리: {mem:.0f}MB")

결과: M2 Mac에서 최초 로드(모델 다운로드 포함) 약 8초, 단일 추론 약 120ms, 메모리 사용량 약 1.2GB. MPS 가속 없이 CPU로만 돌렸다. 데모 수준으로는 충분하다.

테스트 2: Transformers vs vLLM, Qwen-7B 추론 비교

같은 하드웨어(A100 40GB), 같은 입력(512 tokens):

  • transformers 직접 model.generate(): 약 28 tokens/s
  • vLLM으로 서비스 띄움: 약 180 tokens/s

약 6배 차이. 이유는 단순하다. transformers는 범용 프레임워크라 continuous batching, PagedAttention 같은 추론 최적화를 하지 않는다. 프로덕션에서는 vLLM으로 바로 가는 게 맞다.

테스트 3: HF_ENDPOINT 미러 효과

Qwen/Qwen2.5-7B-Instruct(약 15GB) 다운로드:

  • 미러 미설정: 끊김 반복, 평균 200KB/s, 20분 이상 소요
  • HF_ENDPOINT=https://hf-mirror.com 설정: 안정적으로 8MB/s, 2분 만에 완료

국내 개발자의 필수 설정이다.

누가 써야 하는가

적합한 대상:

  • ML 엔지니어의 일상 개발, 모델 튜닝, 실험
  • 신규 논문의 모델을 빠르게 검증하려는 연구자
  • 프로토타입 단계에서 모델을 유연하게 교체해야 하는 경우
  • 튜토리얼, 데모 작성 등 문서 지원이 필요한 경우

적합하지 않은 대상:

  • 극한의 처리량을 추구하는 프로덕션 환경 (vLLM, TGI, SGLang 사용)
  • 고정된 모델 하나만 돌리는 작은 프로젝트 (해당 프레임워크가 더 가볍다)
  • 임베디드나 의존성 크기에 민감한 시나리오 (transformers + torch가 기본 몇 GB부터 시작)
  • 순수 TF 스택 팀 (마이그레이션 의지가 없다면 비추)

정리

Transformers는 가장 빠르지도, 가장 가볍지도 않다. 하지만 가장 "전부 갖춘" 라이브러리다. 이 "전부"라는 점이 오픈소스 AI의 사실 표준 인터페이스 계층으로 자리잡게 만들었다.

Transformers를 배워두는 건 가성비가 높다. 익히면 100개 이상 모델의 사용법과 Hugging Face 생태계 전반을 동시에 익히는 셈이다. 앞으로 새 모델이 나올 때마다 Hub에서 먼저 검색해보자. 어김없이 이미 돌릴 수 있는 pipeline이 올라와 있을 것이다.

참고: Transformers GitHub 저장소

출처: https://github.com/huggingface/transformers