Transformers 빠른 시작

Transformers 빠른 시작 (Quickstart)

Transformers는 빠르고 간단하게 쓸 수 있도록 설계된 라이브러리예요. 목표는 누구나 트랜스포머 모델을 배우고 만들기 시작하게 만드는 거죠. 그래서 사용자가 직접 만질 추상화는 세 개의 클래스(모델을 인스턴스화하는)와 두 개의 API(추론·훈련용)로 딱 줄여 두었어요.

이 가이드에서는 Transformers의 핵심 기능을 소개하면서 다음 세 가지를 실제로 해볼게요.

  • 사전 학습된 모델 불러오기
  • [Pipeline]로 추론 실행하기
  • [Trainer]로 모델 미세조정하기

설정

시작하려면 우선 Hugging Face 계정을 만드는 걸 추천해요. 계정이 있으면 버전 관리되는 모델·데이터셋·Spaces를 Hugging Face Hub에 올리고 쓸 수 있어요. Hub는 발견과 빌드를 위한 협업 플랫폼이죠.

User Access Token을 만들고 계정에 로그인해요.

노트북 환경이라면 프롬프트가 뜰 때 User Access Token을 [~huggingface_hub.notebook_login]에 붙여 넣으면 로그인돼요.

from huggingface_hub import notebook_login

notebook_login()

CLI를 쓴다면 huggingface_hub[cli] 패키지가 설치돼 있는지 확인하고 아래 명령을 실행해요. 프롬프트가 뜨면 User Access Token을 붙여 넣으면 돼요.

hf auth login

PyTorch를 설치해요.

# CLI에서 설치한다면 !를 지우세요
!pip install torch

그리고 최신 버전의 Transformers와 Hugging Face 생태계의 추가 라이브러리(데이터셋·비전 모델 접근, 훈련 평가, 대형 모델 훈련 최적화용)를 설치해요.

# CLI에서 설치한다면 !를 지우세요
!pip install -U transformers datasets evaluate accelerate timm

에이전트 스킬 (Agent skills)

Hugging Face Skills는 코딩 에이전트에게 Transformers 사용법을 가르쳐 줘요. 훈련 스크립트를 직접 쓰는 대신, 에이전트에게 비전 모델을 미세조정해 달라고 요청하면 스킬이 안내해 줘요.

Claude Code에서는 마켓플레이스와 플러그인을 추가해요.

/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface/skills

Codex에서는 마켓플레이스를 추가해요.

codex plugin marketplace add huggingface/skills

그 다음 Codex에서 /plugins를 실행해 huggingface/skills 저장소에서 스킬을 설치해요.

Cursor, Gemini 같은 더 많은 지원 플랫폼은 Installation 가이드를 확인해요.

스킬을 설치한 뒤에는 코딩 에이전트에게 주는 지시문에 포함시키면 돼요.

Use the HF Trainer skill to fine-tune RT-DETRv2 on [Lekim89/sportsmot](https://huggingface.co/datasets/Lekim89/sportsmot) for basketball player tracking.

사전 학습된 모델

사전 학습된 모델은 모두 세 개의 기본 클래스에서 파생돼요.

클래스 설명
[PreTrainedConfig] 어텐션 헤드 수나 어휘 크기 같은 모델의 속성을 담은 파일.
[PreTrainedModel] 설정 파일의 모델 속성으로 정의되는 모델(또는 아키텍처). 사전 학습된 모델은 원시 hidden states만 반환해요. 특정 작업에는 적절한 모델 헤드를 붙여 원시 hidden states를 의미 있는 결과로 바꿔야 해요(예: [LlamaModel] 대 [LlamaForCausalLM]).
Preprocessor 원시 입력(텍스트·이미지·오디오·멀티모달)을 모델에 넣을 수치 입력으로 바꾸는 클래스. 예를 들어 [PreTrainedTokenizer]는 텍스트를 텐서로, [ImageProcessingMixin]은 픽셀을 텐서로 변환해요.

모델과 전처리기를 불러올 때는 AutoClass API를 권장해요. 작업과 머신러닝 프레임워크에 맞는 아키텍처를 사전 학습된 가중치·설정 파일의 이름이나 경로만 보고 자동으로 추론해 주거든요.

[~PreTrainedModel.from_pretrained]로 Hub에서 가중치와 설정 파일을 모델·전처리기 클래스로 불러와요.

모델을 불러올 때 아래 파라미터를 설정하면 최적으로 로드돼요.

  • device_map="auto"는 모델 가중치를 가장 빠른 장치에 먼저 자동 배치해요.
  • dtype="auto"는 가중치를 저장된 데이터 타입 그대로 초기화해요. 가중치를 두 번 로드하는 걸 피할 수 있어요(PyTorch는 기본적으로 torch.float32로 로드함).
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf", dtype="auto", device_map="auto")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf")

토크나이저로 텍스트를 토큰화하고 PyTorch 텐서를 반환받아요. 추론 전에 토큰화된 입력을 모델과 같은 장치로 옮겨야 모델이 처리할 수 있어요.

model_inputs = tokenizer(["The secret to baking a good cake is "], return_tensors="pt").to(model.device)

이제 모델은 추론이나 훈련에 사용할 준비가 됐어요.

추론이라면 토큰화된 입력을 [~GenerationMixin.generate]에 넘겨 텍스트를 생성하고, [~PreTrainedTokenizerBase.batch_decode]로 토큰 아이디를 다시 텍스트로 디코딩해요.

generated_ids = model.generate(**model_inputs, max_length=30)
tokenizer.batch_decode(generated_ids)[0]
'<s> The secret to baking a good cake is 100% in the preparation. There are so many recipes out there,'

[!TIP] 모델을 미세조정하는 방법은 Trainer 섹션으로 건너뛰어도 돼요.

Pipeline

[Pipeline] 클래스는 사전 학습된 모델로 추론을 실행하는 가장 편리한 방법이에요. 텍스트 생성, 이미지 분할, 자동 음성 인식, 문서 질의응답 등 다양한 작업을 지원해요.

[!TIP] 사용 가능한 작업 전체 목록은 Pipeline API 레퍼런스를 참고해요.

[Pipeline] 객체를 만들고 작업을 선택해요. 기본적으로 [Pipeline]은 주어진 작업에 대한 기본 사전 학습 모델을 다운로드해 캐시해요. 다른 모델을 쓰고 싶다면 model 파라미터에 모델 이름을 넘겨요.

텍스트 생성은 [Accelerator]로 사용 가능한 가속기를 자동 감지해요.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipe = pipeline("text-generation", model="meta-llama/Llama-2-7b-hf", device=device)

[Pipeline]에 초기 텍스트를 프롬프트로 넘겨 더 많은 텍스트를 생성하게 해요.

pipe("The secret to baking a good cake is ", max_length=50)
[{'generated_text': 'The secret to baking a good cake is 100% in the batter. The secret to a great cake is the icing.\nThis is why we’ve created the best buttercream frosting reci'}]

이미지 분할도 [Accelerator]로 가속기를 자동 감지해요.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipeline = pipeline("image-segmentation", model="facebook/detr-resnet-50-panoptic", device=device)

[Pipeline]에 이미지(URL 또는 로컬 경로)를 넘겨요.

parrots

segments = pipeline("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
segments[0]["label"]
'bird'
segments[1]["label"]
'bird'

자동 음성 인식도 [Accelerator]로 가속기를 감지해요.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipeline = pipeline("automatic-speech-recognition", model="openai/whisper-large-v3", device=device)

[Pipeline]에 오디오 파일을 넘겨요.

pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/1.flac")
{'text': ' He hoped there would be stew for dinner, turnips and carrots and bruised potatoes and fat mutton pieces to be ladled out in thick, peppered flour-fatten sauce.'}

Trainer

[Trainer]는 PyTorch 모델을 위한 완전한 훈련·평가 루프예요. 훈련 루프를 직접 작성할 때 흔히 필요한 보일러플레이트를 많이 추상화해 주므로, 더 빨리 훈련을 시작하고 훈련 설계 결정에 집중할 수 있어요. 모델, 데이터셋, 전처리기, 그리고 데이터셋에서 데이터 배치를 만드는 데이터 콜레이터만 있으면 돼요.

[TrainingArguments] 클래스로 훈련 과정을 커스터마이즈해요. 훈련·평가 등에 대한 많은 옵션을 제공해요. 배치 크기, 학습률, 혼합 정밀도, torch.compile 같은 훈련 하이퍼파라미터·기능을 실험해서 훈련 요구에 맞춰요. 기본 파라미터를 써서 베이스라인을 빠르게 만들 수도 있어요.

훈련용 모델, 토크나이저, 데이터셋을 불러와요.

from transformers import AutoModelForSequenceClassification, AutoTokenizer
from datasets import load_dataset

model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased")
tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased")
dataset = load_dataset("rotten_tomatoes")

텍스트를 토큰화해 PyTorch 텐서로 바꾸는 함수를 만들고, 이 함수를 [~datasets.Dataset.map] 메서드로 데이터셋 전체에 적용해요.

def tokenize_dataset(dataset):
    return tokenizer(dataset["text"])
dataset = dataset.map(tokenize_dataset, batched=True)

데이터 배치를 만들 데이터 콜레이터를 불러오고, 그 안에 토크나이저를 넘겨요.

from transformers import DataCollatorWithPadding

data_collator = DataCollatorWithPadding(tokenizer=tokenizer)

다음으로 [TrainingArguments]를 훈련 기능·하이퍼파라미터와 함께 설정해요.

from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="distilbert-rotten-tomatoes",
    learning_rate=2e-5,
    per_device_train_batch_size=8,
    per_device_eval_batch_size=8,
    num_train_epochs=2,
    push_to_hub=True,
)

마지막으로 이 모든 구성 요소를 [Trainer]에 넘기고 [~Trainer.train]을 호출해 훈련을 시작해요.

from transformers import Trainer

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=dataset["train"],
    eval_dataset=dataset["test"],
    processing_class=tokenizer,
    data_collator=data_collator,
)

trainer.train()

모델과 토크나이저를 [~Trainer.push_to_hub]로 Hub에 공유해요.

trainer.push_to_hub()

축하해요, Transformers로 첫 모델을 훈련했어요!

다음 단계

Transformers에 대한 이해와 제공 기능을 익혔으니, 이제 가장 관심 가는 내용을 계속 탐색해 볼 차례예요.

  • 기본 클래스: 설정·모델·프로세서 클래스를 더 배워요. 모델을 만들고 커스터마이즈하는 법, 다양한 입력(오디오·이미지·멀티모달) 전처리, 모델 공유에 대한 이해가 깊어져요.
  • 추론: [Pipeline]을 더 탐구하고, LLM 추론·채팅, 에이전트, 그리고 머신러닝 프레임워크·하드웨어로 추론을 최적화하는 법을 다뤄요.
  • 훈련: [Trainer]를 더 자세히 살펴보고, 분산 훈련·특정 하드웨어에서의 훈련 최적화를 배워요.
  • 양자화: 가중치를 더 적은 비트로 표현해 메모리·저장 요구를 줄이고 추론을 빨라지게 해요.
  • 리소스: 특정 작업에 모델을 훈련·추론하는 엔드투엔드 레시피가 필요하다면 작업 레시피를 확인해요!

출처: Hugging Face Transformers — Quickstart

더 알아보기 (Learn more)

  • [Pipeline] API 레퍼런스 — 지원 작업 전체 목록
  • [Trainer] 문서 — 훈련 루프 자세히 보기
  • Model Hub — 모델·데이터셋·Spaces 공유와 발견