허깅페이스 Transformers 라이브러리

허깅페이스의 Transformers 라이브러리는 Transformer 구조 기반의 다양한 모델을 지원하여 개발에 활용할 수 있다. pre-training된 모델도 지원하기 때문에 모델을 처음부터 학습 시킬 필요가 없어 시간과 리소스를 절약할 수 있다. 초기에는 자연어처리 관련 모델 위주로 지원했지만 현재는 여러 가지 도메인에 대한 모델을 지원한다. 2024년 기준 157개의 모델 아키텍처를 지원하고 있다. 또한 모델에 들어가는 컴포넌트를 모듈화해서 제공하기도 한다.

Transformers 라이브러리는 pip를 통해 설치할 수 있다.

pip install transformers

Pipeline을 이용한 간단한 사용법

Transformers에서 가장 간단하게 사용할 수 있는 방법은 pipeline API이다. pipeline은 입력 문장에 대해 어떤 작업을 수행하고 싶다는 목표만 정해주면 내부적으로 모델과 토크나이저 등을 자동으로 설정하여 동작한다.

from transformers import pipeline

# 감정 분석 파이프라인 생성
classifier = pipeline("sentiment-analysis") # sentiment-analysis는 문장이 어떤 감정인지 분류하는 Task

result = classifier("I love using Transformers")  
print(result)
# 출력 예 : [{'label': 'POSITIVE', 'score': 0.9998}]

위와 같이 pipeline(task_name, model=모델이름) 형태로 필요에 맞는 모델을 지정하면, 여러가지 작업을 간단한 코드로 수행할 수 있다.

Pipeline을 이용한 번역 예

from transformers import pipeline

translator = pipeline("translation_en_to_fr")
result = translator("Hugging Face is an open-source provider of NLP technologies.")
print(result[0]['translation_text'])

사전 학습 모델을 직접 불러와서 사용하는 방법

Pipeline을 사용하지 않고 모델과 토크나이저를 가져와 사용할 수도 있다. AutoModel, AutoTokenizer 등을 사용하면 된다. Hugging Face Model Hub에 많은 사람들이 만들어서 공개한 모델 체크포인트들이 올라와 있다. 아래와 같이 model_name을 지정하면 되는데 여기서 model_name은 Hugging Face Hub에 저장되어 있는 모델 저장소(Repo)의 식별자로 볼 수 있다.
모델마다 아키텍처가 다르고, 학습된 weights와 토크나이저 설정 등이 저장되어 있다.

from transformers import AutoModelForSequenceClassification, AutoTokenizer

model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
tokenizer = AutoTokenizer.from_pretrained(model_name) # 토크나이저 불러옴
model = AutoModelForSequenceClassification.from_pretrained(model_name) # 모델 불러옴

# 입력 텍스트
text = "한 소년이 사람이 붐비는 도심을 걷고 있다."

# 토큰화
inputs = tokenizer(text, return_tensors="pt")

# 모델 추론
outputs = model(**inputs)
print(outputs.logits)

만약 직접 만든 모델을 로컬 경로 ”./my_model/”에 저장했다면, model_name 대신 “./my_model/” 처럼 폴더 경로를 넣어주면 해당 폴더에 있는 체크포인트를 불러올 수 있다.

그리고 모델이 어떤 토크나이저를 사용해서 학습되었는지도 중요하다.
예를 들어 BERT 계열은 WordPiece 기반, GPT-2는 Byte-Pair Encoding(BPE) 기반, XLNet이나 RoBERTa는 SentencePiece/BPE 기반 등 서로 다르다. Hugging Face에서는 모델 저장소를 만들 때 config.json, tokenizer.json 또는 vocab.txt 같은 토크나이저 정보 등을 패키징해 두어, AutoTokenizer가 알아서 매칭된 형태로 불러올 수 있게 해준다. 만약 임의로 잘못된 토크나이저를 사용하면, 모델이 기대하는 토큰 ID 체계와 달라져서 제대로 추론이 안 되거나 에러가 발생할 수 있다.

위 내용의 핵심 포인트는 Hugging Face Hub에 업로드되어 있는 모델 이름만 알면, 해당 모델과 딱 맞는 토크나이저와 체크포인트 weights를 쉽게 불러와서 사용할 수 있다는 점이다. 이로 인해 모델을 직접 구현하거나 구조를 알 필요 없이, 곧바로 사전 학습된 대형 모델을 활용할 수 있다는 장점이 있다. 이것을 토대로, 원하는 Task에 맞춰 모델을 적용하거나 fine-tuning을 할 수 있다.

아래 코드는 Image Classification 샘플이다.

from transformers import pipeline

# 이미지 분류 파이프라인
classifier = pipeline(
    task="image-classification",
    model="google/vit-base-patch16-224"  # Vision Transformer
)

# 테스트용 이미지 URL (로컬 파일 경로도 가능)
image_path = "./cat_image.png"

results = classifier(image_path)
print(results)
# 예) [{'score': 0.999..., 'label': 'tabby, tabby cat'}, ...]

이미지 처리 관련 모듈

1. ViTImageProcessor

ViTImageProcessor는 이미지 전처리(Image Preprocessing)를 담당하는 클래스이다.
이미지 load → resize/crop/normalization 등 전처리 → 텐서 반환 과정을 처리해준다.

예를 들어 Vision Transformer(ViT) 모델은 일반적으로 (3, 224, 224) 크기의 텐서 형태의 입력을 받도록 설계되어 있는데, ViTImageProcessor가 입력 이미지를 적절히 리사이즈(224×224)하고, 픽셀 값 정규화(평균·표준편차 보정) 및 채널 순서 변환 (예: (H, W, C) → (C, H, W))을 자동으로 수행한 뒤 PyTorch/TensorFlow 텐서로 만들어 준다.

from transformers import ViTImageProcessor
processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224")

# Pillow 이미지나 NumPy 배열이 있다고 가정
inputs = processor(images=my_image, return_tensors="pt")
pixel_values = inputs["pixel_values"]  # shape: [batch_size, 3, 224, 224]

2. VisionEncoderDecoderModel

VisionEncoderDecoderModel은 이미지 인코더 (ViT, Swin, etc.), 텍스트 디코더 (GPT2, T5, Bart, etc.)를 한 모델 안에 통합한 “멀티모달” 구조를 제공한다. 즉, 이미지를 입력받아(인코더), 텍스트를 생성(디코더)하는 작업을 할 때 유용하다. VisionEncoderDecoderModel은 내부적으로 self.encoder (Vision 모델), self.decoder (Language Model) 두 부분이 합쳐져 있다. 이미지를 통해 얻은 벡터 표현(=인코더 출력)을 텍스트 디코더가 입력으로 받아, 최종적으로 “토큰 시퀀스”를 생성한다.

3. GenerationMixin

비전 모델과 결합해 텍스트를 생성하는 모델(VisionEncoderDecoderModel 등)에서 자주 사용. 모델에 .generate() 메서드를 제공하는 “믹스인(Mixin)” 클래스이다. greedy search, beam search, sampling 등 다양한 텍스트 생성 알고리즘을 지원한다.

4. AutoModelForObjectDetection

Object Detection 모델을 불러오기 위한 클래스이다. DETR, DINO, YOLOS 등의 모델을 지원한다.

from transformers import AutoModelForObjectDetection

model = AutoModelForObjectDetection.from_pretrained("facebook/detr-resnet-50")
outputs = model(pixel_values=pixel_values)
# outputs.logits: [batch_size, num_queries, num_classes]
# outputs.pred_boxes: [batch_size, num_queries, 4]