Python 완전정복 시리즈 #35: Hugging Face Transformers 완벽 이해하기

지난 시간에는 Gradio를 이용해 Python 함수와 머신러닝 모델을 웹 데모로 만들었습니다.

함수만 준비되어 있다면 다음과 같이 화면을 만들 수 있었습니다.

import gradio as gr


def predict(text: str) -> str:
    return f"분석 결과: {text}"


demo = gr.Interface(
    fn=predict,
    inputs=gr.Textbox(),
    outputs=gr.Textbox()
)

demo.launch()

문제는 `predict()` 함수 안에 들어갈 진짜 AI 모델입니다.

감정 분석 모델이 필요하다고 가정해 보겠습니다.

직접 만들려면 다음 과정이 필요합니다.

학습 데이터 수집

→ 데이터 정제

→ 라벨링

→ Tokenizer 준비

→ 신경망 구조 선택

→ GPU 학습

→ 성능 평가

→ 모델 저장

→ 추론 코드 개발

번역 모델이나 문서 요약 모델은 더욱 어렵습니다.

개발자:
“한글 문장을 영어로 번역하고 싶습니다.”

AI 연구팀:
“좋습니다. 먼저 수백만 개의
한영 번역 문장을 준비해 주세요.”

개발자:
“그냥 번역기를 사용하겠습니다.”

다행히 이미 세계 곳곳의 연구자와 기업이 수많은 AI 모델을 학습해 공개하고 있습니다.

우리는 그 모델을 내려받아 바로 사용할 수 있습니다.

이번 시간의 주인공은 Hugging Face Transformers입니다.

Hugging Face Hub
→ 사전 학습 모델이 모여 있는 거대한 도서관

Transformers
→ 도서관의 모델을 Python에서 사용하는 도구

Pipeline
→ 복잡한 사용 절차를 자동화한 AI 버튼

오늘은 AI 모델을 처음부터 키우는 대신 이미 훈련을 마친 모델을 스카우트해 보겠습니다. 🤗🤖

1. Hugging Face란?

Hugging Face는 머신러닝 모델, 데이터셋, AI 애플리케이션을 검색하고 공유하며 사용할 수 있는 AI 플랫폼과 오픈소스 생태계입니다.

Hugging Face Hub에는 2026년 8월 기준 200만 개 이상의 모델, 150만 개 이상의 데이터셋, 150만 개 이상의 Spaces 애플리케이션이 등록되어 있습니다. 공개 저장소뿐 아니라 팀과 기업을 위한 비공개 협업 기능도 제공합니다.

Hugging Face를 흔히 GitHub와 비교하기도 합니다.

GitHub
→ 소스코드 공유

Hugging Face Hub
→ AI 모델·데이터셋·데모 공유

Hub에서 찾을 수 있는 자료는 크게 세 종류입니다.

Models
→ 학습된 AI 모델

Datasets
→ AI 학습과 평가 데이터

Spaces
→ Gradio·Streamlit 기반 AI 데모

Hugging Face의 얼굴 모양 이모지는 다음과 같습니다.

🤗

AI 업계에서 가장 많은 모델을 끌어안고 있는 이모지라고 볼 수 있습니다.

2. Hugging Face 생태계

Hugging Face는 하나의 Python 라이브러리만 의미하지 않습니다.

여러 도구가 하나의 생태계를 구성합니다.

사전 학습 모델을 불러오고 추론하거나 추가 학습할 수 있습니다.

from transformers import pipeline

모델, 데이터셋, Spaces를 저장하고 공유합니다.

from huggingface_hub import (
    hf_hub_download
)

대규모 데이터셋을 불러오고 가공합니다.

from datasets import load_dataset

텍스트를 빠르게 토큰으로 변환합니다.

from tokenizers import Tokenizer

CPU, GPU, 다중 GPU 환경에서 학습과 추론을 쉽게 실행하도록 도와줍니다.

전체 모델 대신 일부 파라미터만 효율적으로 학습하는 LoRA 등의 기능을 제공합니다.

모델 가중치를 안전하고 빠르게 저장하고 불러오는 형식입니다.

Gradio, Streamlit, Docker 등을 이용한 AI 애플리케이션을 배포합니다.

전체 관계를 단순화하면 다음과 같습니다.

Hub
├─ Models
├─ Datasets
└─ Spaces

Python 애플리케이션
├─ Transformers
├─ Datasets
├─ Tokenizers
├─ Accelerate
└─ huggingface_hub

AI 모델 마트에 갔더니 모델뿐 아니라 데이터, 포장 상자, 배송 차량까지 함께 판매하는 셈입니다.

3. Transformers란?

Transformers는 텍스트, 이미지, 오디오, 비디오, 멀티모달 분야의 사전 학습 모델을 추론과 학습에 사용할 수 있도록 통합된 API를 제공하는 라이브러리입니다.

2026년 8월 2일 기준 PyPI의 최신 안정 버전은 Transformers 5.14.1이며, 2026년 7월 16일 공개되었습니다. 현재 패키지는 Python 3.10 이상을 요구합니다.

Transformers에서 수행할 수 있는 대표 작업은 다음과 같습니다.

텍스트 분류

감정 분석

개체명 인식

질문 답변

문서 요약

번역

텍스트 생성

이미지 분류

객체 검출

이미지 세그멘테이션

음성 인식

오디오 분류

이미지·텍스트 멀티모달 처리

Transformers의 큰 장점은 모델마다 다른 구현 방식을 어느 정도 통일해 준다는 것입니다.

pipeline(
    task="text-classification",
    model="모델_ID"
)

모델 ID만 바꾸어 여러 모델을 비교할 수 있습니다.

4. Transformer 모델이란?

Transformer는 문장이나 이미지의 요소 사이 관계를 Attention이라는 구조로 학습하는 신경망 아키텍처입니다.

텍스트를 예로 들어 보겠습니다.

철수가 은행에 돈을 맡겼다.

여기서 `은행`은 금융 기관입니다.

철수가 강가의 은행나무를 바라봤다.

두 번째 문장에서 비슷한 글자가 등장하지만 의미는 달라집니다.

모델은 단어 하나만 따로 보는 것이 아니라 주변 단어와의 관계를 살펴야 합니다.

은행
+ 돈을 맡겼다
→ 금융 기관

은행나무
+ 바라봤다
→ 나무

Transformer의 Attention은 입력 요소들이 서로 얼마나 관련 있는지 계산합니다.

문장의 모든 토큰

→ 서로의 관계 확인

→ 중요한 관계에 더 높은 가중치

→ 문맥을 반영한 표현 생성

Transformer의 이름 때문에 자동차 로봇을 떠올릴 수 있지만, Optimus Prime은 설치되지 않습니다.

from transformers import pipeline

이 코드를 실행해도 노트북이 로봇으로 변신하지는 않습니다.

다만 문장은 숫자로 변신합니다.

5. 사전 학습 모델이란?

사전 학습 모델은 대규모 데이터로 먼저 학습된 모델입니다.

대량의 텍스트·이미지·음성

→ 기본 패턴 학습

→ 사전 학습 모델 완성

이 모델을 그대로 추론에 사용할 수도 있고, 특정 업무 데이터로 추가 학습할 수도 있습니다.

무작위 가중치

→ 대규모 데이터

→ 오랜 학습

→ 많은 GPU 비용

이미 학습된 가중치

→ 바로 추론

또는

→ 소규모 업무 데이터로 추가 학습

사전 학습 모델은 기본 교육을 마친 경력직과 비슷합니다.

회사 업무를 조금 더 알려 주면 새로운 업무에 비교적 빠르게 적응할 수 있습니다.

6. 모델·아키텍처·체크포인트 구분

AI 문서에서는 `모델`이라는 단어가 여러 의미로 사용됩니다.

신경망의 구조입니다.

BERT

GPT

T5

ViT

Whisper

건물의 설계도에 가깝습니다.

특정 데이터로 학습된 가중치입니다.

distilbert-base-uncased-finetuned-sst-2-english

같은 설계도로 지었지만 내부 경험이 다른 건물입니다.

상황에 따라 아키텍처와 체크포인트를 모두 모델이라고 부르기도 합니다.

Transformers 공식 문서도 아키텍처는 모델의 뼈대이고, 체크포인트는 그 아키텍처에 학습된 가중치라고 구분합니다.

BERT
→ 아키텍처

google-bert/bert-base-uncased
→ 특정 체크포인트

7. Hugging Face Hub 살펴보기

Hub에서 모델을 검색하면 각 모델의 페이지가 나타납니다.

모델 ID는 일반적으로 다음 구조입니다.

사용자명 또는 조직명/저장소명

예:

distilbert/
distilbert-base-uncased-finetuned-sst-2-english

전체 모델 ID:

distilbert/distilbert-base-uncased-finetuned-sst-2-english

Python에서는 이 문자열을 사용합니다.

MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)

모델 페이지에는 일반적으로 다음 정보가 있습니다.

Model Card
→ 모델 설명

Files
→ 모델 가중치와 설정 파일

Community
→ 토론과 질문

License
→ 사용 조건

Downloads
→ 다운로드 통계

Inference
→ 모델 실행 예제

8. 모델을 선택할 때 확인할 사항

검색 결과 상단에 나온 모델을 무조건 사용하면 안 됩니다.

다음 내용을 확인해야 합니다.

Text Classification

Text Generation

Translation

Summarization

Image Classification

감정 분석 모델을 번역 모델처럼 사용할 수는 없습니다.

영어 전용

한국어 전용

다국어

특정 산업 용어

영어 영화 리뷰로 학습된 모델에 한국어 화장품 리뷰를 넣으면 좋은 결과를 기대하기 어렵습니다.

상업적 사용, 수정, 재배포 가능 여부를 확인합니다.

작은 모델
→ 빠름
→ 메모리 적게 사용
→ 성능이 낮을 수 있음

큰 모델
→ 성능이 좋을 가능성
→ 메모리와 계산량 증가

어떤 데이터로 학습되었는지 확인합니다.

지원하지 않는 언어

편향 가능성

최대 입력 길이

권장하지 않는 사용 분야

알려진 오류

오래된 모델이 무조건 나쁜 것은 아니지만 라이브러리 호환성과 유지 상태를 확인해야 합니다.

모델 카드에는 모델의 용도, 제한사항, 학습 정보, 평가 결과와 라이선스 등을 기록할 수 있습니다. 사용 전 모델 카드와 라이선스를 확인하는 습관이 중요합니다.

모델 다운로드 수:
높음

모델 설명:
두 줄

라이선스:
없음

제한사항:
없음

→ 일단 멈추고 조사

인기와 안전성은 같은 단어가 아닙니다.

9. Transformers 설치하기

현재 Transformers 패키지는 Python 3.10 이상을 요구하며 PyTorch 지원을 포함한 설치 방식이 제공됩니다.

python -m venv venv
venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install "transformers[torch]"

python3 -m venv venv
source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install "transformers[torch]"

python -m pip install \
    "transformers[torch]" \
    accelerate \
    sentencepiece \
    pillow \
    gradio

Windows 명령 프롬프트에서는 한 줄로 입력합니다.

python -m pip install "transformers[torch]" accelerate sentencepiece pillow gradio

각 패키지 역할:

transformers
→ 모델과 Pipeline

torch
→ 모델 연산

accelerate
→ 장치 배치와 대형 모델 실행 지원

sentencepiece
→ 일부 번역·언어 모델 Tokenizer

pillow
→ 이미지 처리

gradio
→ 웹 데모

10. 설치 확인하기

import torch
import transformers


print(
    f"Transformers: "
    f"{transformers.__version__}"
)

print(
    f"PyTorch: "
    f"{torch.__version__}"
)

print(
    f"CUDA 사용 가능: "
    f"{torch.cuda.is_available()}"
)

간단한 Pipeline 테스트:

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('Hugging Face is useful'))"

공식 설치 문서도 감정 분석 Pipeline을 이용해 설치 결과를 확인하는 예제를 제공합니다.

11. 첫 번째 Pipeline 실행

`pipeline()`은 사전 학습 모델을 가장 쉽게 사용하는 방법입니다.

from transformers import pipeline


classifier = pipeline(
    task="sentiment-analysis"
)

result = classifier(
    "I really enjoyed this movie."
)

print(result)

결과 예:

[
    {
        'label': 'POSITIVE',
        'score': 0.9998
    }
]

`pipeline()`은 여러 머신러닝 작업을 통합된 방식으로 실행하는 고수준 추론 API입니다. 모델 로딩, 전처리, 추론, 후처리 과정을 대부분 자동화합니다.

모델을 지정하지 않으면 작업에 설정된 기본 모델이 선택될 수 있습니다.

학습이나 운영 코드에서는 모델을 명시하는 것이 좋습니다.

MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)


classifier = pipeline(
    task="text-classification",
    model=MODEL_ID
)

해당 체크포인트의 모델 페이지에서도 `text-classification` Pipeline 예제가 제공됩니다.

12. Pipeline 내부 동작

Pipeline 한 줄 뒤에서는 여러 작업이 수행됩니다.

원본 입력

→ 전처리

→ 모델 추론

→ 후처리

→ 읽기 쉬운 결과

텍스트 감정 분석을 더 자세히 보면 다음과 같습니다.

"I love Python"

→ Tokenizer

→ 토큰 ID

→ PyTorch Tensor

→ Transformer 모델

→ Logits

→ Softmax

→ POSITIVE 98%

Pipeline은 이 과정을 하나로 묶습니다.

result = classifier(
    "I love Python"
)

Pipeline은 편리하지만 내부 과정을 제어해야 한다면 Tokenizer와 AutoModel을 직접 사용할 수 있습니다.

Pipeline
→ 빠르고 편리함

AutoTokenizer + AutoModel
→ 세부 제어 가능

13. Pipeline의 주요 작업 종류

pipeline(
    "text-classification"
)

별칭:

pipeline(
    "sentiment-analysis"
)

pipeline(
    "text-generation"
)

pipeline(
    "summarization"
)

pipeline(
    "translation"
)

pipeline(
    "question-answering"
)

pipeline(
    "token-classification"
)

pipeline(
    "image-classification"
)

pipeline(
    "object-detection"
)

pipeline(
    "automatic-speech-recognition"
)

Pipeline은 자연어, 컴퓨터 비전, 오디오, 멀티모달 분야의 다양한 작업별 구현을 제공합니다.

14. 사용할 모델 직접 지정하기

from transformers import pipeline


MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)


classifier = pipeline(
    task="text-classification",
    model=MODEL_ID
)

Tokenizer도 별도로 지정할 수 있습니다.

classifier = pipeline(
    task="text-classification",
    model=MODEL_ID,
    tokenizer=MODEL_ID
)

대부분 모델과 같은 저장소의 Tokenizer를 사용합니다.

MODEL_ID = "모델_ID"

다른 모델을 비교하기 쉽습니다.

MODEL_ID 변경

→ 나머지 코드 유지

→ 새로운 모델 테스트

단, 같은 작업을 지원하는 모델이어야 합니다.

15. 여러 문장 한 번에 분석하기

sentences = [
    "This product is excellent.",
    "The delivery was terribly slow.",
    "The movie was surprisingly good."
]

results = classifier(
    sentences,
    batch_size=3
)

for sentence, result in zip(
    sentences,
    results
):
    print(sentence)
    print(result)
    print()

결과 구조:

This product is excellent.
{'label': 'POSITIVE', 'score': ...}

The delivery was terribly slow.
{'label': 'NEGATIVE', 'score': ...}

한 문장씩 반복 호출하는 것보다 배치 처리가 효율적일 수 있습니다.

다만 입력 길이가 크게 다르면 Padding으로 인해 불필요한 계산이 증가할 수 있습니다.

16. 감정 분석 실습

from transformers import pipeline


MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)


classifier = pipeline(
    task="text-classification",
    model=MODEL_ID
)


reviews = [
    "The camera quality is amazing.",
    "The battery died after one hour.",
    "The design is simple but useful."
]


results = classifier(
    reviews
)


for review, result in zip(
    reviews,
    results
):
    label = result["label"]
    score = result["score"]

    print(
        f"문장: {review}"
    )

    print(
        f"감정: {label}"
    )

    print(
        f"확률: {score:.2%}"
    )

    print(
        "-" * 40
    )

이 모델은 영어 SST-2 감정 분류에 맞춰진 체크포인트입니다. 한국어 문장을 분석하려면 한국어 또는 다국어 감정 분석 모델을 찾아야 합니다.

영어 감정 분석 모델

+ 한국어 리뷰

= 실행은 될 수 있음

≠ 결과를 신뢰해도 된다는 뜻

AI는 자신이 모르는 언어에서도 자신감 있는 표정을 지을 수 있습니다.

17. Tokenizer란?

신경망은 문자열을 직접 이해하지 못합니다.

"Python is fun"

→ 모델에 바로 전달 불가

Tokenizer는 문장을 모델이 처리할 수 있는 작은 단위로 나눕니다.

문장

→ 토큰

→ 토큰 ID

→ Tensor

예:

"Transformers are useful"

→ ["Transform", "ers", "are", "useful"]

→ [13809, 2545, 2024, 6179]

실제 토큰 분할 방식은 모델마다 다릅니다.

WordPiece

BPE

SentencePiece

Unigram

따라서 모델과 호환되는 Tokenizer를 사용해야 합니다.

BERT 모델

+ GPT Tokenizer

→ 입력 ID 의미가 다름

→ 정상적인 추론 불가

모델과 Tokenizer는 서로 합이 맞는 번역 파트너입니다.

18. 토큰화 과정 확인하기

from transformers import AutoTokenizer


MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)


tokenizer = (
    AutoTokenizer
    .from_pretrained(
        MODEL_ID
    )
)


text = (
    "Transformers make AI models "
    "easier to use."
)


tokens = tokenizer.tokenize(
    text
)

token_ids = (
    tokenizer
    .convert_tokens_to_ids(
        tokens
    )
)


print(
    "토큰:"
)

print(tokens)

print(
    "토큰 ID:"
)

print(token_ids)

특수 토큰을 포함한 전체 인코딩:

encoded = tokenizer(
    text
)

print(encoded)

결과에는 일반적으로 다음 정보가 포함됩니다.

input_ids

attention_mask

19. input_ids와 attention_mask

각 토큰을 어휘 사전의 정수 ID로 변환한 값입니다.

encoded = tokenizer(
    "AI is useful",
    return_tensors="pt"
)

print(
    encoded["input_ids"]
)

실제 토큰과 Padding 영역을 구분합니다.

1
→ 실제 입력 토큰

0
→ Padding 토큰

예:

문장 A:
[101, 2023, 2003, 2204, 102]

문장 B:
[101, 2307, 102, 0, 0]

Attention Mask:

문장 A:
[1, 1, 1, 1, 1]

문장 B:
[1, 1, 1, 0, 0]

모델은 Mask를 보고 Padding 영역을 중요하게 처리하지 않습니다.

Padding은 단체사진에서 키를 맞추기 위해 놓은 발판과 비슷합니다.

사진 높이는 맞춰 주지만 사람으로 세면 안 됩니다.

20. Padding과 Truncation

여러 문장을 하나의 배치로 만들려면 길이를 맞춰야 합니다.

texts = [
    "Short sentence.",
    "This is a much longer sentence for testing."
]


encoded = tokenizer(
    texts,
    padding=True,
    truncation=True,
    return_tensors="pt"
)


print(
    encoded["input_ids"].shape
)

짧은 문장에 Padding 토큰을 추가합니다.

padding=True

모델이 받을 수 있는 최대 길이를 넘으면 잘라냅니다.

truncation=True

최대 토큰 수를 직접 정합니다.

encoded = tokenizer(
    texts,
    padding=True,
    truncation=True,
    max_length=128,
    return_tensors="pt"
)

너무 작은 `max_length`를 지정하면 중요한 내용이 잘릴 수 있습니다.

고객 문의:

“제품은 좋았지만
배송이 세 번이나 지연되었고
고객센터가...”

잘린 입력:

“제품은 좋았지만”

모델:
POSITIVE

문장의 결말이 사라지면 감정도 함께 사라질 수 있습니다.

21. AutoClass란?

Transformers에는 모델 구조를 자동으로 선택하는 AutoClass가 있습니다.

AutoTokenizer

AutoConfig

AutoModel

AutoModelForSequenceClassification

AutoModelForCausalLM

AutoModelForSeq2SeqLM

AutoModelForImageClassification

AutoClass는 모델 저장소의 설정 파일을 읽고 적절한 실제 클래스를 선택합니다. 따라서 정확한 모델 클래스 이름을 모두 외우지 않아도 됩니다.

from transformers import AutoModel


model = AutoModel.from_pretrained(
    MODEL_ID
)

Hidden State 같은 기본 표현을 출력합니다.

from transformers import (
    AutoModelForSequenceClassification
)


model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID
    )
)

분류를 위한 출력 Head가 포함됩니다.

from transformers import (
    AutoModelForCausalLM
)

from transformers import (
    AutoModelForSeq2SeqLM
)

작업에 맞는 AutoModel 클래스를 선택해야 합니다.

22. AutoTokenizer 사용하기

from transformers import AutoTokenizer


tokenizer = (
    AutoTokenizer
    .from_pretrained(
        MODEL_ID
    )
)

`from_pretrained()`는 Hub 또는 로컬 폴더에서 Tokenizer 설정과 어휘 파일을 불러옵니다.

inputs = tokenizer(
    "This library is convenient.",
    return_tensors="pt",
    truncation=True
)

출력:

{
    "input_ids": Tensor,
    "attention_mask": Tensor
}

Tokenizer 객체 정보 확인:

print(
    tokenizer.__class__.__name__
)

print(
    tokenizer.vocab_size
)

print(
    tokenizer.model_max_length
)

모델마다 최대 길이와 특수 토큰이 다릅니다.

23. AutoModel 직접 사용하기

Pipeline을 사용하지 않고 감정 분석을 실행해 보겠습니다.

import torch

from transformers import (
    AutoModelForSequenceClassification,
    AutoTokenizer
)


MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)


tokenizer = (
    AutoTokenizer
    .from_pretrained(
        MODEL_ID
    )
)


model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID
    )
)


text = (
    "The installation process "
    "was surprisingly easy."
)


inputs = tokenizer(
    text,
    return_tensors="pt",
    truncation=True
)


model.eval()


with torch.inference_mode():
    outputs = model(
        **inputs
    )


print(
    outputs.logits
)

이제 Pipeline 내부의 주요 과정이 밖으로 펼쳐졌습니다.

Tokenizer

→ Tensor

→ Model

→ Logits

24. Logits와 Softmax

모델의 원시 출력은 일반적으로 Logits입니다.

logits = outputs.logits

print(logits)

결과 예:

tensor([
    [-2.45, 2.91]
])

Logits는 확률이 아닙니다.

Softmax를 적용해 합이 1인 확률로 변환합니다.

probabilities = torch.softmax(
    logits,
    dim=-1
)

print(probabilities)

예:

tensor([
    [0.0047, 0.9953]
])

가장 높은 클래스:

predicted_id = (
    probabilities
    .argmax(
        dim=-1
    )
    .item()
)

클래스 이름:

predicted_label = (
    model.config.id2label[
        predicted_id
    ]
)

확률:

confidence = (
    probabilities[
        0,
        predicted_id
    ]
    .item()
)

전체 출력:

print(
    f"예측: {predicted_label}"
)

print(
    f"확률: {confidence:.2%}"
)

def classify_text(
    text: str
) -> dict[str, float | str]:
    inputs = tokenizer(
        text,
        return_tensors="pt",
        truncation=True
    )

    model.eval()

    with torch.inference_mode():
        outputs = model(
            **inputs
        )

    probabilities = torch.softmax(
        outputs.logits,
        dim=-1
    )[0]

    predicted_id = int(
        probabilities.argmax()
    )

    return {
        "label": (
            model.config.id2label[
                predicted_id
            ]
        ),
        "score": float(
            probabilities[
                predicted_id
            ]
        )
    }

Pipeline 한 줄이 꽤 많은 일을 하고 있었다는 사실이 드러납니다.

25. 텍스트 생성

텍스트 생성 Pipeline을 사용해 보겠습니다.

from transformers import (
    pipeline,
    set_seed
)


MODEL_ID = (
    "openai-community/gpt2"
)


generator = pipeline(
    task="text-generation",
    model=MODEL_ID
)


set_seed(
    2026
)


results = generator(
    "Python programming is",
    max_new_tokens=50,
    do_sample=True,
    temperature=0.8,
    top_p=0.9,
    num_return_sequences=2
)


for index, result in enumerate(
    results,
    start=1
):
    print(
        f"[결과 {index}]"
    )

    print(
        result["generated_text"]
    )

    print()

이 모델은 영어 텍스트 이어쓰기에 적합한 예제입니다.

대화형 AI처럼 지시를 정확히 따르는 Instruct 모델과는 용도가 다릅니다.

기본 언어 모델:
다음 텍스트 예측

Instruct 모델:
사용자 지시에 응답하도록 추가 학습

모델 페이지에서 `base`, `instruct`, `chat` 등의 성격을 확인해야 합니다.

26. 생성 옵션 이해하기

새로 생성할 최대 토큰 수입니다.

max_new_tokens=100

입력 토큰은 포함하지 않습니다.

확률 분포에서 샘플링할지 결정합니다.

do_sample=True

`False`이면 더 결정적인 생성 방식이 사용됩니다.

출력의 무작위성을 조절합니다.

낮은 Temperature
→ 안전하고 반복적

높은 Temperature
→ 다양하지만 불안정

temperature=0.7

확률이 높은 상위 K개 후보만 사용합니다.

top_k=50

누적 확률이 P에 도달하는 후보 집합에서 선택합니다.

top_p=0.9

반복되는 표현에 불이익을 줍니다.

repetition_penalty=1.1

여러 결과를 생성합니다.

num_return_sequences=3

옵션을 무조건 많이 넣는다고 글이 좋아지는 것은 아닙니다.

Temperature

Top K

Top P

Repetition Penalty

Beam Search

Sampling

개발자:
“모든 설정을 동시에 최대로!”

모델:
“무엇을 원하시는지 모르겠습니다.”

한 번에 하나씩 바꾸며 결과를 비교하는 편이 좋습니다.

27. 문서 요약

from transformers import pipeline


MODEL_ID = (
    "sshleifer/"
    "distilbart-cnn-12-6"
)


summarizer = pipeline(
    task="summarization",
    model=MODEL_ID
)


document = """
Artificial intelligence is being used in many industries.
Companies use machine learning to analyze data, automate
repetitive tasks, and support decision-making. However,
AI systems can produce incorrect or biased outputs.
Organizations should evaluate models carefully, protect
sensitive data, and keep human oversight in important
decisions.
"""


result = summarizer(
    document,
    max_new_tokens=60,
    min_new_tokens=20,
    do_sample=False
)


print(
    result[0]["summary_text"]
)

해당 체크포인트의 모델 페이지에서도 `summarization` Pipeline 사용법을 제공합니다.

모델마다 최대 입력 토큰 수가 있습니다.

문서가 너무 길다면 다음 전략이 필요합니다.

문서를 여러 조각으로 나누기

→ 각 조각 요약

→ 요약 결과를 다시 통합

→ 최종 요약

이를 Map-Reduce 요약 방식으로 구성할 수 있습니다.

def split_text(
    text: str,
    chunk_size: int = 1000
) -> list[str]:
    words = text.split()

    chunks = []

    for start in range(
        0,
        len(words),
        chunk_size
    ):
        chunk = " ".join(
            words[
                start:start + chunk_size
            ]
        )

        chunks.append(
            chunk
        )

    return chunks

단, 단어 수와 토큰 수는 정확히 같지 않습니다.

실제 제한을 확인할 때는 Tokenizer 기준으로 길이를 계산해야 합니다.

28. 한국어·영어 번역

한국어를 영어로 번역하는 예제입니다.

from transformers import pipeline


MODEL_ID = (
    "Helsinki-NLP/"
    "opus-mt-ko-en"
)


translator = pipeline(
    task="translation",
    model=MODEL_ID
)


sentences = [
    "오늘은 파이썬을 공부하기 좋은 날입니다.",
    "인공지능 모델을 웹 서비스에 연결했습니다."
]


results = translator(
    sentences,
    max_new_tokens=128
)


for source, result in zip(
    sentences,
    results
):
    print(
        f"원문: {source}"
    )

    print(
        "번역: "
        f"{result['translation_text']}"
    )

    print()

해당 모델 저장소는 한국어에서 영어로 번역하는 Pipeline 예제를 제공합니다.

일부 번역 모델을 사용할 때 `sentencepiece` 패키지가 필요할 수 있습니다.

python -m pip install sentencepiece

번역 결과는 전문 번역이나 법률·의료 문서의 정확성을 보장하지 않습니다.

중요 문서는 전문가의 검토가 필요합니다.

29. 질문 답변

질문 답변 Pipeline은 질문과 문맥을 입력받습니다.

from transformers import pipeline


question_answerer = pipeline(
    task="question-answering"
)


context = """
Python was created by Guido van Rossum.
Its first public release was made in 1991.
Python emphasizes code readability.
"""


question = (
    "Who created Python?"
)


result = question_answerer(
    question=question,
    context=context
)


print(
    result
)

결과 구조:

{
    "answer": "Guido van Rossum",
    "score": ...,
    "start": ...,
    "end": ...
}

이 방식은 주어진 문맥에서 답에 해당하는 구간을 찾는 추출형 질문 답변입니다.

문맥에 답이 있음
→ 해당 구간 추출

문맥에 답이 없음
→ 틀린 구간을 자신 있게 선택할 수 있음

답이 없는 경우를 처리하도록 별도 기준을 설계해야 합니다.

30. 개체명 인식

개체명 인식은 문장에서 사람, 장소, 조직 등의 고유 개체를 찾습니다.

from transformers import pipeline


recognizer = pipeline(
    task="token-classification",
    aggregation_strategy="simple"
)


text = (
    "Alice works at OpenAI "
    "and lives in Seoul."
)


results = recognizer(
    text
)


for item in results:
    print(
        item
    )

결과 예:

Alice
→ PER

OpenAI
→ ORG

Seoul
→ LOC

대표 라벨:

PER
→ Person

ORG
→ Organization

LOC
→ Location

MISC
→ 기타 고유 개체

실제 라벨 이름은 모델에 따라 다릅니다.

31. 이미지 분류

Transformers는 텍스트뿐 아니라 이미지 모델도 지원합니다.

from PIL import Image

from transformers import pipeline


MODEL_ID = (
    "google/"
    "vit-base-patch16-224"
)


classifier = pipeline(
    task="image-classification",
    model=MODEL_ID
)


image = Image.open(
    "sample.jpg"
).convert(
    "RGB"
)


results = classifier(
    image,
    top_k=5
)


for result in results:
    print(
        f"{result['label']}: "
        f"{result['score']:.2%}"
    )

해당 ViT 체크포인트의 모델 페이지에서도 `image-classification` Pipeline 예제를 제공합니다.

모델이 특정 데이터셋의 클래스만 학습했다면 그 범위 밖의 물체를 정확하게 표현하지 못합니다.

입력:
회사 전용 보안 장비

모델 학습 클래스:
일반 사물 1,000종

결과:
“전자레인지 42%”

모델은 `모르겠습니다` 대신 가장 가까운 기존 클래스를 선택할 수 있습니다.

32. 음성 인식

from transformers import pipeline


MODEL_ID = (
    "openai/"
    "whisper-tiny"
)


transcriber = pipeline(
    task=(
        "automatic-"
        "speech-recognition"
    ),
    model=MODEL_ID
)


result = transcriber(
    "sample_audio.wav"
)


print(
    result["text"]
)

오디오 파일 형식과 실행 환경에 따라 추가 오디오 라이브러리나 FFmpeg가 필요할 수 있습니다.

긴 오디오에서는 청크 처리, 타임스탬프, 언어 설정 등을 검토해야 합니다.

짧은 음성 파일

→ 한 번에 처리

긴 회의 녹음

→ 구간 분할

→ 각 구간 인식

→ 타임스탬프 결합

33. CPU·CUDA·MPS 선택

import torch


def select_device():
    if torch.cuda.is_available():
        return torch.device(
            "cuda"
        )

    if torch.backends.mps.is_available():
        return torch.device(
            "mps"
        )

    return torch.device(
        "cpu"
    )


device = select_device()

print(
    f"사용 장치: {device}"
)

def select_pipeline_device():
    if torch.cuda.is_available():
        return 0

    if torch.backends.mps.is_available():
        return "mps"

    return -1

사용:

classifier = pipeline(
    task="text-classification",
    model=MODEL_ID,
    device=select_pipeline_device()
)

Pipeline은 GPU와 Apple Silicon 장치를 지원하며 일부 환경에서는 반정밀도 가중치를 이용해 메모리 사용량과 추론 시간을 줄일 수 있습니다.

model = model.to(
    device
)

inputs = {
    key: value.to(
        device
    )
    for key, value in (
        inputs.items()
    )
}

모델과 입력 Tensor는 같은 장치에 있어야 합니다.

모델:
cuda

입력:
cpu

PyTorch:
“두 분은 같은 회의실로 와 주세요.”

34. 모델 메모리 줄이기

대형 모델은 많은 메모리를 사용합니다.

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        dtype="auto"
    )
)

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        device_map="auto",
        dtype="auto"
    )
)

`device_map="auto"`는 Accelerate를 이용해 모델의 각 부분을 사용 가능한 장치에 배치할 수 있습니다. 대형 모델이 GPU에 모두 들어가지 않는 경우 CPU나 디스크 Offload도 구성할 수 있습니다.

python -m pip install accelerate

device_map="auto"
≠
모든 모델이 빠르게 실행된다는 뜻

CPU Offload
→ 메모리는 절약
→ 전송 비용으로 느려질 수 있음

Disk Offload
→ 더 많은 모델 적재 가능
→ 매우 느려질 수 있음

메모리 문제를 해결했지만 결과를 받을 때 계절이 바뀌면 실용성이 떨어집니다.

35. 여러 입력을 배치로 처리하기

texts = [
    "The service was excellent.",
    "I would not buy this again.",
    "The design looks fantastic.",
    "The application crashes often."
]


results = classifier(
    texts,
    batch_size=4,
    truncation=True
)

Generator를 사용할 수 있습니다.

def text_generator():
    for text in texts:
        yield text


for result in classifier(
    text_generator(),
    batch_size=8
):
    print(result)

배치 크기 증가

→ GPU 활용률 증가 가능

→ 메모리 사용량 증가

→ 입력 길이 차이가 크면 낭비 증가

다음 값을 비교하며 결정합니다.

처리 시간

GPU 메모리

CPU 메모리

입력 길이 분포

오류 발생 여부

36. 모델 로컬 저장

Hub에서 불러온 모델을 로컬 폴더에 저장할 수 있습니다.

from pathlib import Path


SAVE_DIR = Path(
    "saved_models/sentiment_model"
)


model.save_pretrained(
    SAVE_DIR
)

tokenizer.save_pretrained(
    SAVE_DIR
)

저장 폴더 예:

saved_models/
└─ sentiment_model/
   ├─ config.json
   ├─ model.safetensors
   ├─ tokenizer.json
   ├─ tokenizer_config.json
   ├─ special_tokens_map.json
   └─ vocab.txt

다시 불러오기:

tokenizer = (
    AutoTokenizer
    .from_pretrained(
        SAVE_DIR
    )
)


model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        SAVE_DIR
    )
)

`save_pretrained()`으로 저장한 모델과 설정은 `from_pretrained()`으로 다시 불러올 수 있습니다.

37. 오프라인 환경에서 사용하기

폐쇄망이나 인터넷이 제한된 환경에서는 모델을 미리 내려받아 전달할 수 있습니다.

model.save_pretrained(
    "offline_model"
)

tokenizer.save_pretrained(
    "offline_model"
)

`offline_model` 폴더 전체를 폐쇄망으로 전달합니다.

tokenizer = (
    AutoTokenizer
    .from_pretrained(
        "offline_model",
        local_files_only=True
    )
)


model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        "offline_model",
        local_files_only=True
    )
)

환경변수로 오프라인 모드를 설정할 수도 있습니다.

$env:HF_HUB_OFFLINE="1"

export HF_HUB_OFFLINE=1

모델뿐 아니라 다음 파일도 함께 준비해야 합니다.

가중치

설정 파일

Tokenizer

특수 토큰 정보

Generation 설정

사용하는 Python 패키지 Wheel

모델 파일만 가져왔는데 Tokenizer가 인터넷을 찾기 시작하는 사건을 방지해야 합니다.

38. Hugging Face 캐시

`from_pretrained()`으로 모델을 내려받으면 로컬 캐시에 저장됩니다.

같은 모델을 다시 사용할 때는 캐시 파일을 재사용할 수 있습니다. `hf_hub_download()`와 `snapshot_download()`도 내려받은 파일을 버전을 고려한 로컬 캐시에 저장합니다.

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        cache_dir=(
            "D:/huggingface_cache"
        )
    )
)

$env:HF_HOME="D:\huggingface_cache"

export HF_HOME="/data/huggingface_cache"

대형 모델을 여러 개 내려받으면 캐시 용량이 매우 커질 수 있습니다.

작은 분류 모델:
수백 MB

대형 언어 모델:
수 GB~수십 GB

여러 Revision:
각 버전이 추가 공간 사용 가능

디스크가 조용히 가득 차는 대표적인 경로입니다.

39. Hugging Face 로그인

공개 모델은 로그인 없이 내려받을 수 있는 경우가 많습니다.

비공개 모델이나 승인형 모델은 인증이 필요합니다.

hf auth login

브라우저 기반 인증 또는 액세스 토큰 입력 과정이 진행됩니다.

`huggingface_hub` CLI는 로그인, 파일 다운로드, 저장소 생성, 캐시 관리 등의 기능을 제공합니다. 로그인 토큰은 로컬 캐시에 저장되어 Hub 관련 도구에서 재사용됩니다.

from huggingface_hub import login


login()

토큰을 코드에 직접 작성하지 않는 것이 좋습니다.

# 위험한 예
login(
    token="hf_실제토큰"
)

Git 저장소에 올라가면 토큰이 Hugging Face보다 더 많은 사람과 포옹하게 됩니다.

40. 비공개·승인형 모델

일부 모델은 사용 조건에 동의하거나 제작자의 승인을 받아야 합니다.

이를 Gated Model이라고 합니다.

모델 페이지 접속

→ 사용 조건 확인

→ 접근 요청

→ 승인

→ 로그인 토큰으로 다운로드

Gated Model은 제작자가 사용자별 접근 요청을 관리할 수 있도록 하는 기능입니다.

승인을 받았더라도 라이선스와 사용 조건을 준수해야 합니다.

다운로드 가능

≠

아무 용도로나 사용 가능

41. 모델 카드와 라이선스

모델을 프로젝트에 사용하기 전에 모델 카드를 읽어야 합니다.

확인 목록:

모델 목적

지원 언어

학습 데이터

평가 결과

사용 예

제한사항

편향

라이선스

상업 이용 가능 여부

재배포 가능 여부

특히 다음 분야는 더 신중해야 합니다.

의료

금융

채용

교육 평가

신원 확인

법률

공공 안전

모델 카드의 정확도 숫자 하나만 보고 실제 업무 성능을 판단하면 안 됩니다.

벤치마크 정확도:
95%

우리 회사 데이터 정확도:
아직 측정하지 않음

둘은 서로 다른 숫자입니다.

42. trust_remote_code 보안

일부 모델은 Transformers 기본 구현에 없는 사용자 정의 Python 코드를 포함합니다.

이때 다음 옵션을 요구할 수 있습니다.

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        trust_remote_code=True
    )
)

이 옵션은 원격 저장소의 사용자 정의 코드를 실행할 수 있도록 허용합니다.

공식 문서도 추가적인 안전 조치로 특정 Commit Hash를 `revision`에 지정해 검토한 코드 버전을 고정할 것을 권장합니다.

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        trust_remote_code=True,
        revision=(
            "검토한_Commit_Hash"
        )
    )
)

저장소 제작자

모델 파일

사용자 정의 Python 코드

Commit 이력

커뮤니티 보고

라이선스

`trust_remote_code=True`의 의미는 다음에 가깝습니다.

“이 저장소의 Python 코드를
내 컴퓨터에서 실행해도 좋습니다.”

체크박스 하나처럼 보여도 권한은 매우 큽니다.

43. 모델 버전 고정하기

기본적으로 모델 저장소의 최신 Revision을 불러옵니다.

운영 중 저장소 내용이 변경되면 결과도 달라질 수 있습니다.

특정 Branch, Tag, Commit을 지정할 수 있습니다.

tokenizer = (
    AutoTokenizer
    .from_pretrained(
        MODEL_ID,
        revision=(
            "Commit_Hash"
        )
    )
)


model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        revision=(
            "Commit_Hash"
        )
    )
)

운영 환경에서는 다음 정보를 함께 기록하는 것이 좋습니다.

모델 ID

모델 Revision

Transformers 버전

PyTorch 버전

Tokenizer 버전

Python 버전

추론 옵션

전처리 코드

`모델은 같은데 결과가 달라졌다`는 사건을 조사하려면 버전 기록이 필요합니다.

44. 실전 프로젝트 준비

이번에는 지난 편에서 배운 Gradio와 Transformers를 연결해 Hugging Face 멀티 AI 연구소를 만들어 보겠습니다.

영어 감정 분석

영어 문서 요약

한국어 → 영어 번역

이미지 분류

모델 정보 표시

모델 지연 로딩

CPU·CUDA·MPS 자동 선택

huggingface_ai_lab/
├─ app.py
└─ requirements.txt

transformers[torch]
accelerate
sentencepiece
pillow
gradio

각 모델은 처음 사용할 때 Hub에서 내려받습니다.

초기 실행에는 모델 크기와 네트워크 속도에 따라 시간이 걸릴 수 있습니다.

45. 멀티 AI 모델 준비

모든 모델을 앱 시작 시 한꺼번에 불러오면 메모리 사용량이 커집니다.

필요할 때 처음 한 번만 불러오도록 캐시합니다.

from functools import lru_cache

import torch

from transformers import pipeline


def select_pipeline_device():
    if torch.cuda.is_available():
        return 0

    if torch.backends.mps.is_available():
        return "mps"

    return -1


PIPELINE_DEVICE = (
    select_pipeline_device()
)

감정 분석 모델:

@lru_cache(
    maxsize=1
)
def get_sentiment_pipeline():
    return pipeline(
        task="text-classification",
        model=(
            "distilbert/"
            "distilbert-base-uncased-"
            "finetuned-sst-2-english"
        ),
        device=PIPELINE_DEVICE
    )

번역 모델:

@lru_cache(
    maxsize=1
)
def get_translation_pipeline():
    return pipeline(
        task="translation",
        model=(
            "Helsinki-NLP/"
            "opus-mt-ko-en"
        ),
        device=PIPELINE_DEVICE
    )

`lru_cache`를 사용하면 같은 함수의 첫 번째 반환 객체를 재사용합니다.

46. 감정 분석 함수

import gradio as gr


def analyze_sentiment(
    text: str
) -> dict[str, float]:
    cleaned_text = text.strip()

    if not cleaned_text:
        raise gr.Error(
            "분석할 영어 문장을 "
            "입력해 주세요."
        )

    classifier = (
        get_sentiment_pipeline()
    )

    results = classifier(
        cleaned_text,
        top_k=None,
        truncation=True
    )

    if (
        results
        and isinstance(
            results[0],
            list
        )
    ):
        results = results[0]

    return {
        result["label"]: float(
            result["score"]
        )
        for result in results
    }

`gr.Label`에 딕셔너리를 반환하면 클래스별 확률을 표시할 수 있습니다.

47. 문서 요약 함수

@lru_cache(
    maxsize=1
)
def get_summary_pipeline():
    return pipeline(
        task="summarization",
        model=(
            "sshleifer/"
            "distilbart-cnn-12-6"
        ),
        device=PIPELINE_DEVICE
    )

요약 함수:

def summarize_text(
    text: str,
    maximum_length: int
) -> str:
    cleaned_text = text.strip()

    if len(cleaned_text) < 100:
        raise gr.Error(
            "요약할 문서를 조금 더 "
            "길게 입력해 주세요."
        )

    summarizer = (
        get_summary_pipeline()
    )

    result = summarizer(
        cleaned_text,
        max_new_tokens=maximum_length,
        min_new_tokens=20,
        do_sample=False,
        truncation=True
    )

    return result[0][
        "summary_text"
    ]

이 예제 요약 모델은 영어 문서에 맞춰져 있습니다.

48. 번역 함수

def translate_korean_to_english(
    text: str
) -> str:
    cleaned_text = text.strip()

    if not cleaned_text:
        raise gr.Error(
            "번역할 한국어 문장을 "
            "입력해 주세요."
        )

    translator = (
        get_translation_pipeline()
    )

    result = translator(
        cleaned_text,
        max_new_tokens=256
    )

    return result[0][
        "translation_text"
    ]

49. 이미지 분류 함수

모델 로딩:

@lru_cache(
    maxsize=1
)
def get_image_pipeline():
    return pipeline(
        task="image-classification",
        model=(
            "google/"
            "vit-base-patch16-224"
        ),
        device=PIPELINE_DEVICE
    )

분류 함수:

def classify_image(
    image
) -> dict[str, float]:
    if image is None:
        raise gr.Error(
            "이미지를 업로드해 주세요."
        )

    classifier = (
        get_image_pipeline()
    )

    results = classifier(
        image,
        top_k=5
    )

    return {
        result["label"]: float(
            result["score"]
        )
        for result in results
    }

50. Gradio 화면 구성

import gradio as gr


with gr.Blocks() as demo:
    gr.Markdown(
        """
        # 🤗 Hugging Face 멀티 AI 연구소

        사전 학습된 Transformers 모델을
        브라우저에서 직접 체험해 보세요.
        """
    )

    with gr.Tab(
        "😊 감정 분석"
    ):
        sentiment_input = gr.Textbox(
            label="영어 문장",
            lines=4,
            placeholder=(
                "The product was excellent."
            )
        )

        sentiment_button = gr.Button(
            "감정 분석",
            variant="primary"
        )

        sentiment_output = gr.Label(
            label="분석 결과"
        )

    with gr.Tab(
        "📝 문서 요약"
    ):
        summary_input = gr.Textbox(
            label="영어 문서",
            lines=12
        )

        summary_length = gr.Slider(
            minimum=30,
            maximum=150,
            value=60,
            step=10,
            label="최대 생성 토큰"
        )

        summary_button = gr.Button(
            "문서 요약",
            variant="primary"
        )

        summary_output = gr.Textbox(
            label="요약 결과",
            lines=6
        )

    with gr.Tab(
        "🌏 한영 번역"
    ):
        translation_input = gr.Textbox(
            label="한국어 문장",
            lines=6
        )

        translation_button = gr.Button(
            "영어로 번역",
            variant="primary"
        )

        translation_output = gr.Textbox(
            label="영어 번역 결과",
            lines=6
        )

    with gr.Tab(
        "🖼️ 이미지 분류"
    ):
        image_input = gr.Image(
            type="pil",
            image_mode="RGB",
            label="분류할 이미지"
        )

        image_button = gr.Button(
            "이미지 분석",
            variant="primary"
        )

        image_output = gr.Label(
            label="상위 예측",
            num_top_classes=5
        )

이벤트 연결:

sentiment_button.click(
    fn=analyze_sentiment,
    inputs=sentiment_input,
    outputs=sentiment_output,
    api_name="sentiment"
)


summary_button.click(
    fn=summarize_text,
    inputs=[
        summary_input,
        summary_length
    ],
    outputs=summary_output,
    api_name="summarize"
)


translation_button.click(
    fn=translate_korean_to_english,
    inputs=translation_input,
    outputs=translation_output,
    api_name="translate"
)


image_button.click(
    fn=classify_image,
    inputs=image_input,
    outputs=image_output,
    api_name="classify_image"
)

51. 전체 프로젝트 코드

다음 내용을 `app.py`로 저장합니다.

from functools import lru_cache

import gradio as gr
import torch

from transformers import pipeline


SENTIMENT_MODEL_ID = (
    "distilbert/"
    "distilbert-base-uncased-"
    "finetuned-sst-2-english"
)

SUMMARY_MODEL_ID = (
    "sshleifer/"
    "distilbart-cnn-12-6"
)

TRANSLATION_MODEL_ID = (
    "Helsinki-NLP/"
    "opus-mt-ko-en"
)

IMAGE_MODEL_ID = (
    "google/"
    "vit-base-patch16-224"
)


def select_pipeline_device():
    """사용 가능한 추론 장치를 선택합니다."""
    if torch.cuda.is_available():
        return 0

    if torch.backends.mps.is_available():
        return "mps"

    return -1


PIPELINE_DEVICE = (
    select_pipeline_device()
)


def device_description() -> str:
    """사용 장치 설명을 반환합니다."""
    if PIPELINE_DEVICE == 0:
        return (
            "CUDA GPU: "
            f"{torch.cuda.get_device_name(0)}"
        )

    if PIPELINE_DEVICE == "mps":
        return "Apple Silicon MPS"

    return "CPU"


@lru_cache(
    maxsize=1
)
def get_sentiment_pipeline():
    """영어 감정 분석 Pipeline을 로딩합니다."""
    return pipeline(
        task="text-classification",
        model=SENTIMENT_MODEL_ID,
        device=PIPELINE_DEVICE
    )


@lru_cache(
    maxsize=1
)
def get_summary_pipeline():
    """영어 문서 요약 Pipeline을 로딩합니다."""
    return pipeline(
        task="summarization",
        model=SUMMARY_MODEL_ID,
        device=PIPELINE_DEVICE
    )


@lru_cache(
    maxsize=1
)
def get_translation_pipeline():
    """한국어에서 영어 번역 Pipeline을 로딩합니다."""
    return pipeline(
        task="translation",
        model=TRANSLATION_MODEL_ID,
        device=PIPELINE_DEVICE
    )


@lru_cache(
    maxsize=1
)
def get_image_pipeline():
    """이미지 분류 Pipeline을 로딩합니다."""
    return pipeline(
        task="image-classification",
        model=IMAGE_MODEL_ID,
        device=PIPELINE_DEVICE
    )


def analyze_sentiment(
    text: str
) -> dict[str, float]:
    """영어 문장의 긍정·부정 확률을 반환합니다."""
    cleaned_text = text.strip()

    if not cleaned_text:
        raise gr.Error(
            "분석할 영어 문장을 "
            "입력해 주세요."
        )

    classifier = (
        get_sentiment_pipeline()
    )

    results = classifier(
        cleaned_text,
        top_k=None,
        truncation=True
    )

    if (
        results
        and isinstance(
            results[0],
            list
        )
    ):
        results = results[0]

    return {
        result["label"]: float(
            result["score"]
        )
        for result in results
    }


def summarize_text(
    text: str,
    maximum_length: int
) -> str:
    """영어 문서를 짧게 요약합니다."""
    cleaned_text = text.strip()

    if len(cleaned_text) < 100:
        raise gr.Error(
            "요약할 영어 문서를 "
            "조금 더 길게 입력해 주세요."
        )

    summarizer = (
        get_summary_pipeline()
    )

    result = summarizer(
        cleaned_text,
        max_new_tokens=int(
            maximum_length
        ),
        min_new_tokens=20,
        do_sample=False,
        truncation=True
    )

    return result[0][
        "summary_text"
    ]


def translate_korean_to_english(
    text: str
) -> str:
    """한국어 문장을 영어로 번역합니다."""
    cleaned_text = text.strip()

    if not cleaned_text:
        raise gr.Error(
            "번역할 한국어 문장을 "
            "입력해 주세요."
        )

    translator = (
        get_translation_pipeline()
    )

    result = translator(
        cleaned_text,
        max_new_tokens=256
    )

    return result[0][
        "translation_text"
    ]


def classify_image(
    image
) -> dict[str, float]:
    """이미지의 상위 분류 결과를 반환합니다."""
    if image is None:
        raise gr.Error(
            "이미지를 업로드해 주세요."
        )

    classifier = (
        get_image_pipeline()
    )

    results = classifier(
        image,
        top_k=5
    )

    return {
        result["label"]: float(
            result["score"]
        )
        for result in results
    }


with gr.Blocks(
    title=(
        "Hugging Face "
        "멀티 AI 연구소"
    ),
    fill_width=True
) as demo:
    gr.Markdown(
        f"""
        # 🤗 Hugging Face 멀티 AI 연구소

        Hugging Face Hub의 사전 학습 모델을
        브라우저에서 직접 체험합니다.

        **현재 실행 장치:** {device_description()}

        모델은 각 기능을 처음 실행할 때 다운로드됩니다.
        첫 번째 요청은 시간이 걸릴 수 있습니다.
        """
    )

    with gr.Tab(
        "😊 감정 분석"
    ):
        gr.Markdown(
            """
            영어 문장의 긍정·부정 감정을 분석합니다.
            """
        )

        with gr.Row():
            with gr.Column():
                sentiment_input = gr.Textbox(
                    label="영어 문장",
                    lines=5,
                    value=(
                        "The installation was "
                        "simple and the result "
                        "was excellent."
                    )
                )

                sentiment_button = gr.Button(
                    "감정 분석",
                    variant="primary"
                )

            with gr.Column():
                sentiment_output = gr.Label(
                    label="감정별 확률",
                    num_top_classes=2
                )

        gr.Examples(
            examples=[
                [
                    "This product is amazing."
                ],
                [
                    "The application crashes every day."
                ],
                [
                    "The design is simple and useful."
                ]
            ],
            inputs=sentiment_input
        )

    with gr.Tab(
        "📝 문서 요약"
    ):
        gr.Markdown(
            """
            영어 문서를 핵심 내용 중심으로 요약합니다.
            """
        )

        summary_input = gr.Textbox(
            label="영어 문서",
            lines=14,
            placeholder=(
                "요약할 영어 문서를 "
                "입력하세요."
            )
        )

        summary_length = gr.Slider(
            minimum=30,
            maximum=150,
            value=60,
            step=10,
            label="최대 생성 토큰"
        )

        summary_button = gr.Button(
            "문서 요약",
            variant="primary"
        )

        summary_output = gr.Textbox(
            label="요약 결과",
            lines=7
        )

    with gr.Tab(
        "🌏 한영 번역"
    ):
        gr.Markdown(
            """
            한국어 문장을 영어로 번역합니다.
            """
        )

        with gr.Row():
            with gr.Column():
                translation_input = gr.Textbox(
                    label="한국어 원문",
                    lines=8,
                    value=(
                        "Hugging Face를 이용하면 "
                        "사전 학습된 인공지능 모델을 "
                        "Python에서 쉽게 사용할 수 있습니다."
                    )
                )

                translation_button = gr.Button(
                    "영어로 번역",
                    variant="primary"
                )

            with gr.Column():
                translation_output = gr.Textbox(
                    label="영어 번역",
                    lines=8
                )

    with gr.Tab(
        "🖼️ 이미지 분류"
    ):
        gr.Markdown(
            """
            이미지를 업로드하면 상위 5개 클래스를 표시합니다.
            """
        )

        with gr.Row():
            image_input = gr.Image(
                type="pil",
                image_mode="RGB",
                sources=[
                    "upload",
                    "webcam",
                    "clipboard"
                ],
                label="이미지"
            )

            image_output = gr.Label(
                label="상위 예측",
                num_top_classes=5
            )

        image_button = gr.Button(
            "이미지 분석",
            variant="primary"
        )

    with gr.Tab(
        "📚 모델 정보"
    ):
        gr.Markdown(
            f"""
            ### 영어 감정 분석

            `{SENTIMENT_MODEL_ID}`

            ### 영어 문서 요약

            `{SUMMARY_MODEL_ID}`

            ### 한국어 → 영어 번역

            `{TRANSLATION_MODEL_ID}`

            ### 이미지 분류

            `{IMAGE_MODEL_ID}`

            모델을 실제 서비스에 사용하기 전에는
            각 저장소의 모델 카드, 라이선스,
            학습 데이터와 제한사항을 확인해야 합니다.
            """
        )

    sentiment_button.click(
        fn=analyze_sentiment,
        inputs=sentiment_input,
        outputs=sentiment_output,
        api_name="sentiment",
        concurrency_limit=2
    )

    sentiment_input.submit(
        fn=analyze_sentiment,
        inputs=sentiment_input,
        outputs=sentiment_output,
        concurrency_limit=2
    )

    summary_button.click(
        fn=summarize_text,
        inputs=[
            summary_input,
            summary_length
        ],
        outputs=summary_output,
        api_name="summarize",
        concurrency_limit=1
    )

    translation_button.click(
        fn=translate_korean_to_english,
        inputs=translation_input,
        outputs=translation_output,
        api_name="translate",
        concurrency_limit=2
    )

    image_button.click(
        fn=classify_image,
        inputs=image_input,
        outputs=image_output,
        api_name="classify_image",
        concurrency_limit=2
    )


if __name__ == "__main__":
    demo.queue(
        default_concurrency_limit=2,
        max_size=30
    )

    demo.launch()

52. 프로젝트 실행 방법

mkdir huggingface_ai_lab
cd huggingface_ai_lab

python -m venv venv
venv\Scripts\activate

python3 -m venv venv
source venv/bin/activate

transformers[torch]
accelerate
sentencepiece
pillow
gradio

python -m pip install \
    -r requirements.txt

python app.py

브라우저에서 일반적으로 다음 주소로 접속합니다.

http://127.0.0.1:7860

각 탭을 처음 실행할 때 해당 모델이 다운로드됩니다.

감정 분석 첫 실행
→ 감정 모델 다운로드

요약 첫 실행
→ 요약 모델 다운로드

번역 첫 실행
→ 번역 모델 다운로드

이미지 분류 첫 실행
→ 이미지 모델 다운로드

모델을 모두 사용하면 디스크와 메모리 사용량이 증가합니다.

53. 성능 최적화

모든 모델을 앱 시작 시 한꺼번에 로딩하지 않습니다.

@lru_cache(
    maxsize=1
)
def get_model():
    ...

프로토타입에서는 작은 모델로 기능을 검증합니다.

작은 모델로 UI와 기능 검증

→ 품질 평가

→ 필요할 때 큰 모델로 교체

tokenizer(
    text,
    truncation=True,
    max_length=512
)

여러 요청을 내부적으로 묶을 수 있는 구조인지 검토합니다.

concurrency_limit=1

GPU가 지원한다면 `float16`이나 `bfloat16`을 검토할 수 있습니다.

import time


start_time = time.perf_counter()

result = classifier(
    text
)

elapsed = (
    time.perf_counter()
    - start_time
)

print(
    f"추론 시간: {elapsed:.3f}초"
)

`빠른 것 같다`는 성능 지표가 아닙니다.

초시계가 개발자의 감정을 검증해 줍니다.

54. 자주 발생하는 오류

ModuleNotFoundError:
No module named 'transformers'

설치:

python -m pip install "transformers[torch]"

확인:

python -m pip show transformers

No module named 'torch'

설치:

python -m pip install torch

GPU를 사용할 때는 PyTorch 공식 설치 방식에서 CUDA 환경에 맞는 명령을 확인합니다.

SentencePiece is not available

설치:

python -m pip install sentencepiece

설치 후 Python 프로세스나 Notebook Kernel을 다시 시작합니다.

Repository Not Found

또는

not a valid model identifier

확인:

사용자명·조직명

저장소 이름

대소문자

접근 권한

모델 삭제 여부

401 Unauthorized

403 Forbidden

로그인:

hf auth login

승인형 모델이라면 모델 페이지에서 접근 승인을 받아야 합니다.

첫 실행에는 모델 파일 다운로드가 필요합니다.

프록시

방화벽

SSL 검사

인터넷 차단

DNS

Hub 접속 정책

폐쇄망에서는 모델을 미리 내려받아 로컬 경로로 사용합니다.

CUDA out of memory

대응:

작은 모델 사용

입력 길이 줄이기

배치 크기 줄이기

동시 실행 제한

반정밀도 사용

CPU Offload 검토

Expected all tensors to be
on the same device

수정:

model = model.to(
    device
)

inputs = {
    key: value.to(
        device
    )
    for key, value in (
        inputs.items()
    )
}

Token indices sequence length is
longer than the specified maximum

수정:

tokenizer(
    text,
    truncation=True,
    max_length=512
)

또는 긴 문서를 여러 조각으로 나눕니다.

일부 생성 모델에는 Padding Token이 지정되지 않을 수 있습니다.

if tokenizer.pad_token is None:
    tokenizer.pad_token = (
        tokenizer.eos_token
    )

모델 특성에 따라 올바른 Padding 정책을 확인해야 합니다.

모델의 지원 언어를 확인합니다.

영어 전용 모델

+ 한국어 입력

→ 출력 품질 보장 안 됨

다국어 또는 한국어 전용 모델을 선택합니다.

일부 모델 설정에는 사람이 읽기 쉬운 라벨 이름이 없을 수 있습니다.

LABEL_0

LABEL_1

모델 카드에서 라벨 의미를 확인합니다.

print(
    model.config.id2label
)

라벨 의미를 추측하면 안 됩니다.

가능한 원인:

캐시 폴더가 매번 초기화됨

Docker 컨테이너가 임시 파일 시스템 사용

HF_HOME 경로가 변경됨

모델 Revision이 바뀜

캐시 쓰기 권한 없음

Docker에서는 캐시 폴더를 Volume으로 연결할 수 있습니다.

모델이 사용자 정의 코드를 요구할 수 있습니다.

trust_remote_code=True

설정 전에 저장소 코드를 검토하고 가능하면 Revision을 고정합니다.

확인:

번역 방향이 맞는가?

지원 언어가 맞는가?

문장이 너무 긴가?

전문 용어가 많은가?

전처리가 필요한가?

`ko-en` 모델에 영어를 넣어 한국어로 번역해 달라고 요청하면 방향이 반대입니다.

가능한 원인:

원문이 너무 짧음

max_new_tokens가 너무 큼

모델이 해당 문서 분야에 적합하지 않음

입력이 잘려 중요한 내용이 사라짐

다른 요약 모델과 설정을 비교합니다.

확인:

이미지 색상 모드

학습 클래스 범위

이미지 해상도

물체 크기

복잡한 배경

모델 도메인

image = image.convert(
    "RGB"
)

여러 대형 Pipeline을 동시에 로딩했을 수 있습니다.

감정 모델

요약 모델

번역 모델

이미지 모델

음성 모델

필요한 모델만 로딩하거나 프로세스를 기능별로 분리하는 방식을 검토합니다.

55. 연습 문제

영어 문장을 입력받아 감정 분석 결과와 확률을 출력하세요.

세 개 이상의 문장을 리스트로 전달해 배치 감정 분석을 수행하세요.

Tokenizer를 이용해 다음 내용을 출력하세요.

토큰 목록

토큰 ID

input_ids

attention_mask

길이가 다른 문장 세 개를 Padding하여 하나의 Tensor로 만드세요.

`AutoModelForSequenceClassification`을 이용해 Pipeline 없이 감정을 분석하세요.

Logits에 Softmax를 적용해 클래스별 확률을 출력하세요.

텍스트 생성 Pipeline에서 다음 설정을 비교하세요.

temperature=0.3

temperature=0.8

temperature=1.3

영어 문서를 요약하고 원문 길이와 요약문 길이를 비교하세요.

한국어 문장 리스트를 영어로 일괄 번역하세요.

질문과 문맥을 입력받는 질문 답변 프로그램을 만드세요.

문장에서 사람, 조직, 장소 이름을 찾아 표로 출력하세요.

이미지를 업로드해 상위 5개의 분류 결과를 출력하세요.

CUDA, MPS, CPU 순서로 장치를 선택하는 함수를 만드세요.

모델과 Tokenizer를 로컬 폴더에 저장하고 다시 불러오세요.

`local_files_only=True`로 오프라인 추론을 수행하세요.

모델의 `id2label`, 최대 입력 길이, 어휘 사전 크기를 출력하세요.

특정 Commit Hash를 `revision`으로 지정해 모델 버전을 고정하세요.

Gradio 멀티 AI 연구소에 다음 기능을 추가하세요.

영어 텍스트 생성

음성 파일 받아쓰기

분석 결과 JSON 출력

각 모델 추론 시간 표시

입력 예제 추가

결과 파일 다운로드

56. 핵심 요약

python -m pip install \
    "transformers[torch]" \
    accelerate \
    sentencepiece

from transformers import pipeline


classifier = pipeline(
    task="text-classification",
    model="모델_ID"
)

result = classifier(
    "분석할 문장"
)

from transformers import (
    AutoTokenizer
)


tokenizer = (
    AutoTokenizer
    .from_pretrained(
        MODEL_ID
    )
)

inputs = tokenizer(
    text,
    padding=True,
    truncation=True,
    return_tensors="pt"
)

from transformers import (
    AutoModelForSequenceClassification
)


model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID
    )
)

with torch.inference_mode():
    outputs = model(
        **inputs
    )

probabilities = torch.softmax(
    outputs.logits,
    dim=-1
)

generator = pipeline(
    "text-generation",
    model=MODEL_ID
)

summarizer = pipeline(
    "summarization",
    model=MODEL_ID
)

translator = pipeline(
    "translation",
    model=MODEL_ID
)

classifier = pipeline(
    "image-classification",
    model=MODEL_ID
)

model.save_pretrained(
    "saved_model"
)

tokenizer.save_pretrained(
    "saved_model"
)

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        "saved_model",
        local_files_only=True
    )
)

model = (
    AutoModelForSequenceClassification
    .from_pretrained(
        MODEL_ID,
        device_map="auto",
        dtype="auto"
    )
)

57. 마무리

이번 시간에는 Hugging Face Hub와 Transformers를 이용해 사전 학습 AI 모델을 Python에서 사용하는 방법을 알아보았습니다.

전체 흐름을 다시 정리해 보겠습니다.

Hugging Face Hub에서 모델 검색

→ 모델 카드와 라이선스 확인

→ 모델 ID 선택

→ Pipeline 또는 AutoClass로 로딩

→ 입력 데이터 전처리

→ 모델 추론

→ 결과 후처리

→ 로컬 저장 또는 웹앱 연결

가장 쉬운 시작점은 Pipeline입니다.

from transformers import pipeline


classifier = pipeline(
    "text-classification"
)

result = classifier(
    "AI models are useful."
)

Pipeline 뒤에서는 다음 과정이 자동으로 수행됩니다.

입력 문장

→ Tokenizer

→ input_ids

→ attention_mask

→ Transformer 모델

→ Logits

→ 확률과 라벨

더 세밀하게 제어하려면 AutoClass를 사용할 수 있습니다.

AutoTokenizer

+ AutoModelFor...

+ PyTorch Tensor

= 직접 제어하는 추론

Hugging Face의 가장 큰 장점은 이미 학습된 수많은 모델을 공통된 방식으로 사용할 수 있다는 점입니다.

감정 분석

요약

번역

질문 답변

이미지 분류

음성 인식

텍스트 생성

작업은 달라도 사용 흐름은 비슷합니다.

pipeline(
    task="작업_이름",
    model="모델_ID"
)

하지만 모델을 쉽게 내려받을 수 있다는 사실과 모델을 안전하게 사용할 수 있다는 사실은 서로 다릅니다.

모델을 찾았다

≠

우리 업무에 적합하다

모델이 실행된다

≠

결과가 정확하다

모델이 공개되어 있다

≠

모든 용도로 사용할 수 있다

따라서 모델을 선택할 때는 다음 질문이 필요합니다.

어떤 데이터로 학습했는가?

어떤 언어를 지원하는가?

어떤 작업을 수행하는가?

어떤 상황에서 틀리는가?

라이선스는 무엇인가?

상업적으로 사용할 수 있는가?

사용자 정의 코드를 실행하는가?

우리 데이터에서 성능을 평가했는가?

Hugging Face는 AI 모델이 모인 거대한 도서관입니다.

하지만 도서관에 책이 많다고 모든 책이 내 문제의 정답지는 아닙니다.

개발자:
“다운로드 수가 가장 많은 모델을 골랐습니다.”

모델 카드:
“영어 영화 리뷰 전용입니다.”

개발자:
“한국어 보안 로그를 분석하려고 했는데요.”

모델:
“이 영화는 POSITIVE입니다.”

모델의 이름보다 모델의 목적을 먼저 확인해야 합니다.

이제 AI 기능이 필요할 때마다 처음부터 학습을 시작할 필요는 없습니다.

Hub에서 적절한 모델을 찾고, Pipeline으로 빠르게 검증하고, AutoClass로 내부를 제어한 뒤, Gradio나 Streamlit으로 사용자에게 제공할 수 있습니다.

Hugging Face
→ 모델 발견

Transformers
→ 모델 실행

PyTorch
→ 세부 연산 제어

Gradio
→ AI 웹 데모

Streamlit
→ 데이터·AI 애플리케이션

지금까지 배운 Python 도구들이 하나의 AI 서비스 제작팀으로 합류했습니다. 🤗🚀

[Python 완전정복 시리즈 #36] Hugging Face Datasets 완벽 이해하기 | AI 학습 데이터를 불러오고 가공하는 가장 쉬운 방법

다음 시간에는 Hugging Face Hub의 데이터셋을 Python으로 불러오고 탐색하는 방법을 알아봅니다.

`load_dataset()`, Dataset과 DatasetDict, Train·Validation·Test 분리, `map()`, `filter()`, `shuffle()`, Tokenizer 일괄 적용, Streaming, 캐시, CSV·JSON 파일 로딩, PyTorch DataLoader 연결까지 실습해 보겠습니다.

#Python #파이썬 #Python강좌 #파이썬기초 #HuggingFace #허깅페이스 #Transformers #트랜스포머 #사전학습모델 #인공지능 #머신러닝 #딥러닝 #생성형AI #LLM #Pipeline #AutoTokenizer #AutoModel #Tokenizer #감정분석 #텍스트생성 #문서요약 #번역AI #이미지분류 #음성인식 #PyTorch #Gradio #AI웹앱 #모델배포 #코딩공부 #프로그래밍