transformers 사용법 — pipeline 세 줄로 모델 돌리기

설치 — torch가 먼저다

transformers만 설치하면 모델을 못 돌립니다. 실제로 torch 없이 설치하면 이런 경고가 뜹니다.

[transformers] PyTorch was not found. Models won't be available and
only tokenizers, configuration and file/data utilities can be used.

python3 -m venv hf
source hf/bin/activate
pip install torch
pip install transformers

설치 후 확인은 한 줄입니다. 맥에서는 MPS 가속 사용 여부까지 같이 봅니다.

python -c "import torch, transformers; print(torch.__version__, transformers.__version__, torch.backends.mps.is_available())"

pipeline 세 줄로 돌리기

가장 단순한 형태입니다. 모델 이름만 주면 다운로드와 로딩을 알아서 합니다.

from transformers import pipeline
import torch

pipe = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct",
                dtype=torch.float16, device="mps")
out = pipe([{"role": "user", "content": "로컬 LLM의 장점 한 가지만 말해줘."}],
           max_new_tokens=40)
print(out[0]["generated_text"][-1]["content"])

맥이면 device="mps", 엔비디아 GPU면 device="cuda", CPU만 쓸 거면 생략합니다. 실제 측정에서 파이프라인 준비에 20.6초, 생성 40토큰에 1.41초가 걸렸습니다. 준비 시간에는 모델 다운로드가 포함돼 있어 두 번째 실행부터는 훨씬 짧아집니다.

반환값 구조를 헷갈리는 분이 많습니다. 대화 형식으로 넣으면 generated_text가 문자열이 아니라 메시지 리스트로 돌아옵니다. 마지막 원소의 role이 assistant이고 거기에 답변이 들어 있습니다. 그래서 위 코드처럼 [-1]["content"]로 꺼냅니다.

실행하면 실제로 뜨는 경고 세 개

문서에는 잘 안 나오는데 돌리면 바로 보이는 것들입니다.

세 번째가 특히 중요합니다. 경고 문구 자체가 이 후처리는 WordPiece용이고 BPE에서는 구두점 앞 공백을 지워버려 파괴적이라고 말합니다. Qwen이나 Llama 계열은 BPE라 해당됩니다. 출력 품질이 미묘하게 이상하면 이 옵션부터 꺼 보십시오.

pipeline과 직접 호출 중 뭘 써야 하나

직접 호출로 가면 토크나이저와 모델을 따로 다루게 되는데, 여기서 5.x의 가장 큰 변경점을 만납니다. apply_chat_template이 텐서가 아니라 딕셔너리를 돌려줍니다. 예전 코드를 그대로 쓰면 AttributeError가 납니다. 해결은 return_dict=True를 주고 generate(**inputs) 형태로 넘기는 것이고, 전체 코드는 허깅페이스 사용법에 있습니다.

자주 묻는 질문

pipeline 결과에서 답변만 꺼내려면요?

대화 형식 입력이면 out[0]["generated_text"][-1]["content"]입니다. 문자열 입력이면 generated_text가 그냥 문자열입니다.

device를 지정하지 않으면 어떻게 되나요?

CPU에서 돌아갑니다. 동작은 하지만 속도가 크게 떨어지므로 맥은 mps, 엔비디아는 cuda를 명시하는 편이 낫습니다.

max_length 경고는 무시해도 되나요?

경고 문구가 max_new_tokens이 우선한다고 밝히고 있어 동작에는 문제가 없습니다. 다만 둘 중 하나만 쓰는 게 깔끔합니다.

작은 모델로 테스트해도 되나요?

동작 확인용으로는 적합합니다. 다만 0.5B급은 한국어 답변 품질이 낮아 실사용에는 7B 이상을 권합니다.