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}]
이 세 줄 뒤에서 실제로 일어나는 일:
pipeline("sentiment-analysis")이 기본으로distilbert-base-uncased-finetuned-sst-2-english를 찾는다- Hugging Face Hub에서 모델 가중치와 config를 내려받는다
- task에 맞춰
AutoTokenizer와AutoModelForSequenceClassification을 자동으로 고른다 - 하나의 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이 올라와 있을 것이다.