Hugging Face 완전 정복: AI 모델의 GitHub

개요

Hugging Face는 AI/ML 커뮤니티에서 가장 인기 있는 플랫폼으로, 수십만 개의 사전 학습된 모델과 데이터셋을 제공합니다. "AI 모델의 GitHub"라고 불리며, 누구나 모델을 공유하고 사용할 수 있습니다.

학습 목표

• ✅ Hugging Face 생태계 이해 (Hub, Transformers, Datasets)
• ✅ Pipeline API로 빠르게 모델 사용하기
• ✅ 다양한 NLP 태스크 실습 (텍스트 생성, 분류, 임베딩)
• ✅ 컴퓨터 비전 모델 활용
• ✅ 모델 검색 및 다운로드 방법

왜 Hugging Face인가?

1. Hugging Face 핵심 개념

1.1 Hugging Face Hub

Hub는 모델, 데이터셋, Spaces(데모 앱)를 호스팅하는 중앙 저장소입니다.

• 🔗 URL: https://huggingface.co
• 📦 모델: GPT, BERT, LLaMA, Stable Diffusion 등
• 📊 데이터셋: GLUE, SQuAD, ImageNet 등
• 🚀 Spaces: Gradio/Streamlit 기반 데모 앱

1.2 Transformers 라이브러리

Transformers는 사전 학습된 모델을 쉽게 로드하고 사용할 수 있는 Python 라이브러리입니다.

from transformers import pipeline
classifier = pipeline("sentiment-analysis")
classifier("I love Hugging Face!")
# [{'label': 'POSITIVE', 'score': 0.9998}]

1.3 주요 구성 요소

2. 환경 설정

필요한 라이브러리를 설치하고 임포트합니다.

# Hugging Face 라이브러리 설치 (이미 설치되어 있으면 스킵)
# !pip install transformers datasets pillow requests

# 필요한 라이브러리 임포트
from transformers import pipeline, AutoModel, AutoTokenizer
from PIL import Image
import requests
from io import BytesIO

print("✅ 라이브러리 임포트 완료!")

✅ 라이브러리 임포트 완료!

3. Pipeline API: 가장 쉬운 시작 방법

Pipeline은 전처리, 모델 추론, 후처리를 자동으로 처리하는 고수준 API입니다.

Pipeline 사용 흐름

입력 텍스트 → Tokenizer → Model → Post-processing → 결과

모든 과정이 자동화되어 3줄 코드로 SOTA 모델을 사용할 수 있습니다!

3.1 감정 분석 (Sentiment Analysis)

텍스트의 감정(긍정/부정)을 분류합니다.

Pipeline이란?

Pipeline은 복잡한 ML 워크플로우를 단순화하는 고수준 API입니다. 내부적으로 다음 3단계를 자동으로 처리합니다:

1. 전처리 (Preprocessing)
   └─ Tokenizer: 텍스트 → 토큰 ID로 변환
   └─ 배치 처리, 패딩, attention mask 생성

2. 모델 추론 (Model Inference)
   └─ 사전 학습된 모델에 토큰 입력
   └─ 각 클래스에 대한 logits(점수) 계산

3. 후처리 (Post-processing)
   └─ Softmax로 확률 변환
   └─ 결과를 사람이 읽기 쉬운 형태로 변환

Pipeline의 장점

✅ 간편함: 3줄 코드로 SOTA 모델 사용
✅ 자동화: 전처리/후처리 자동 처리
✅ 유연성: 다양한 모델로 쉽게 교체 가능
✅ 배치 처리: 여러 입력 동시 처리 지원

Pipeline 생성 옵션

pipeline() 함수는 다양한 파라미터를 지원합니다:

예시:

# 기본 모델 사용 (자동 선택)
pipeline("sentiment-analysis")

# 특정 모델 지정
pipeline("sentiment-analysis", model="nlptown/bert-base-multilingual-uncased-sentiment")

# GPU 사용
pipeline("sentiment-analysis", device=0)

# ============================================
# 1단계: Pipeline 생성
# ============================================

# task="sentiment-analysis"를 지정하면 자동으로:
# - 적합한 모델 선택 (기본: distilbert-base-uncased-finetuned-sst-2-english)
# - 해당 모델의 토크나이저 로드
# - 추론 파이프라인 구성
sentiment_analyzer = pipeline("sentiment-analysis")

print(f"📦 사용 중인 모델: {sentiment_analyzer.model.name_or_path}")
print(f"🔧 토크나이저: {sentiment_analyzer.tokenizer.__class__.__name__}\n")

# ============================================
# 2단계: 입력 데이터 준비
# ============================================

texts = [
    "I absolutely love this product! It's amazing!",  # 강한 긍정
    "This is the worst experience ever.",             # 강한 부정
    "It's okay, nothing special."                      # 중립적
]

# ============================================
# 3단계: 감정 분석 실행
# ============================================

# Pipeline에 텍스트(또는 텍스트 리스트)를 전달하면:
# - 자동으로 토큰화
# - 모델 추론
# - 결과를 딕셔너리 형태로 반환
sentiment_results = sentiment_analyzer(texts)

# 내부적으로 일어나는 일:
# 1. Tokenizer: "I love this" → [101, 1045, 2293, 2023, 102]
# 2. Model: [토큰 IDs] → logits [-2.5, 4.8] (NEGATIVE, POSITIVE 점수)
# 3. Softmax: logits → 확률 [0.0002, 0.9998]
# 4. Argmax: 가장 높은 확률의 레이블 선택 → "POSITIVE"

# ============================================
# 4단계: 결과 출력
# ============================================

print("=" * 60)
print("감정 분석 결과")
print("=" * 60)

for text, sentiment_result in zip(texts, sentiment_results):
    label = sentiment_result['label']        # 예측된 레이블 (POSITIVE/NEGATIVE)
    score = sentiment_result['score']        # 해당 레이블의 확률 (0~1)
    
    # 이모지 추가
    emoji = "😊" if label == "POSITIVE" else "😞"
    
    print(f"\n{emoji} 텍스트: \"{text}\"")
    print(f"   감정: {label}")
    print(f"   확률: {score:.4f} ({score*100:.2f}%)")

print("\n" + "=" * 60)

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
Cell In[3], line 9
      1 # ============================================
      2 # 1단계: Pipeline 생성
      3 # ============================================
   (...)      7 # - 해당 모델의 토크나이저 로드
      8 # - 추론 파이프라인 구성
----> 9 sentiment_analyzer = pipeline("sentiment-analysis1")
     11 print(f"📦 사용 중인 모델: {sentiment_analyzer.model.name_or_path}")
     12 print(f"🔧 토크나이저: {sentiment_analyzer.tokenizer.__class__.__name__}\n")

File ~/workspace/ws.study/ai-engineering/.venv/lib/python3.13/site-packages/transformers/pipelines/__init__.py:965, in pipeline(task, model, config, tokenizer, feature_extractor, image_processor, processor, framework, revision, use_fast, token, device, device_map, dtype, trust_remote_code, model_kwargs, pipeline_class, **kwargs)
    958         pipeline_class = get_class_from_dynamic_module(
    959             class_ref,
    960             model,
    961             code_revision=code_revision,
    962             **hub_kwargs,
    963         )
    964 else:
--> 965     normalized_task, targeted_task, task_options = check_task(task)
    966     if pipeline_class is None:
    967         pipeline_class = targeted_task["impl"]

File ~/workspace/ws.study/ai-engineering/.venv/lib/python3.13/site-packages/transformers/pipelines/__init__.py:536, in check_task(task)
    490 def check_task(task: str) -> tuple[str, dict, Any]:
    491     """
    492     Checks an incoming task string, to validate it's correct and return the default Pipeline and Model classes, and
    493     default models if they exist.
   (...)    534 
    535     """
--> 536     return PIPELINE_REGISTRY.check_task(task)

File ~/workspace/ws.study/ai-engineering/.venv/lib/python3.13/site-packages/transformers/pipelines/base.py:1549, in PipelineRegistry.check_task(self, task)
   1546         return task, targeted_task, (tokens[1], tokens[3])
   1547     raise KeyError(f"Invalid translation task {task}, use 'translation_XX_to_YY' format")
-> 1549 raise KeyError(
   1550     f"Unknown task {task}, available tasks are {self.get_supported_tasks() + ['translation_XX_to_YY']}"
   1551 )

KeyError: "Unknown task sentiment-analysis1, available tasks are ['audio-classification', 'automatic-speech-recognition', 'depth-estimation', 'document-question-answering', 'feature-extraction', 'fill-mask', 'image-classification', 'image-feature-extraction', 'image-segmentation', 'image-text-to-text', 'image-to-image', 'image-to-text', 'keypoint-matching', 'mask-generation', 'ner', 'object-detection', 'question-answering', 'sentiment-analysis', 'summarization', 'table-question-answering', 'text-classification', 'text-generation', 'text-to-audio', 'text-to-speech', 'text2text-generation', 'token-classification', 'translation', 'video-classification', 'visual-question-answering', 'vqa', 'zero-shot-audio-classification', 'zero-shot-classification', 'zero-shot-image-classification', 'zero-shot-object-detection', 'translation_XX_to_YY']"

결과 구조 이해하기

Pipeline이 반환하는 결과는 리스트 형태의 딕셔너리입니다:

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

각 딕셔너리 구조:

• label: 예측된 클래스 레이블 (문자열)
  • 감정 분석의 경우: "POSITIVE" 또는 "NEGATIVE"
  • 모델에 따라 다른 레이블 사용 가능
• score: 해당 레이블의 확률 (float, 0~1)
  • 모델이 해당 레이블에 대해 얼마나 확신하는지
  • 1.0에 가까울수록 높은 확신도
  • Softmax 함수로 계산됨

주의사항:

⚠️ score는 항상 선택된 레이블의 확률입니다. 다른 레이블의 확률은 1 - score가 아닐 수 있습니다 (다중 클래스인 경우).

고급 옵션: 다른 모델 사용하기

기본 모델 대신 다른 모델을 사용할 수 있습니다.

# 5점 척도 감정 분석 모델 사용 (1~5 stars)
# 이 모델은 POSITIVE/NEGATIVE 대신 1~5점으로 평가합니다

star_classifier = pipeline(
    "sentiment-analysis",
    model="nlptown/bert-base-multilingual-uncased-sentiment"
)

# 다국어 지원 (영어, 한국어, 일본어 등)
multilingual_texts = [
    "This restaurant is amazing!",
    "이 제품은 정말 훌륭해요!",
    "最高のサービスです!"
]

print("5점 척도 감정 분석 (다국어 지원):\n")
for text in multilingual_texts:
    # Pipeline 호출: 단일 텍스트 → [{'label': '...', 'score': ...}]
    # [0]으로 첫 번째(그리고 유일한) 결과 추출
    star_result = star_classifier(text)[0]
    
    # label은 "5 stars" 같은 문자열
    # [0]으로 첫 번째 문자('5')를 추출하여 별 개수 결정
    stars = "⭐" * int(star_result['label'][0])
    
    print(f"텍스트: {text}")
    print(f"평가: {star_result['label']} {stars}")
    print(f"확률: {star_result['score']:.4f}\n")

Device set to use mps:0
5점 척도 감정 분석 (다국어 지원):

텍스트: This restaurant is amazing!
평가: 5 stars ⭐⭐⭐⭐⭐
확률: 0.8884

텍스트: 이 제품은 정말 훌륭해요!
평가: 5 stars ⭐⭐⭐⭐⭐
확률: 0.7375

텍스트: 最高のサービスです!
평가: 5 stars ⭐⭐⭐⭐⭐
확률: 0.9166

3.2 텍스트 생성 (Text Generation)

주어진 프롬프트를 기반으로 텍스트를 자동 생성합니다.

# 텍스트 생성 파이프라인 (GPT-2 모델 사용)
generator = pipeline("text-generation", model="gpt2")

# 프롬프트
prompt = "Artificial intelligence will"

# 텍스트 생성
generated_texts = generator(
    prompt,
    max_length=50,      # 최대 토큰 수
    num_return_sequences=2,  # 생성할 문장 개수
    temperature=0.8     # 창의성 조절 (높을수록 다양함)
)

# 결과 출력
print(f"프롬프트: {prompt}\n")
for i, gen_result in enumerate(generated_texts, 1):
    print(f"생성 {i}: {gen_result['generated_text']}\n")

model.safetensors:   0%|          | 0.00/548M [00:00<?, ?B/s]
generation_config.json:   0%|          | 0.00/124 [00:00<?, ?B/s]
tokenizer_config.json:   0%|          | 0.00/26.0 [00:00<?, ?B/s]
vocab.json:   0%|          | 0.00/1.04M [00:00<?, ?B/s]
merges.txt:   0%|          | 0.00/456k [00:00<?, ?B/s]
tokenizer.json:   0%|          | 0.00/1.36M [00:00<?, ?B/s]
Device set to use mps:0
Truncation was not explicitly activated but `max_length` is provided a specific value, please use `truncation=True` to explicitly truncate examples to max length. Defaulting to 'longest_first' truncation strategy. If you encode pairs of sequences (GLUE-style) with the tokenizer you can select this strategy more precisely by providing a specific strategy to `truncation`.
Setting `pad_token_id` to `eos_token_id`:50256 for open-end generation.
Both `max_new_tokens` (=256) and `max_length`(=50) seem to have been set. `max_new_tokens` will take precedence. Please refer to the documentation for more information. (https://huggingface.co/docs/transformers/main/en/main_classes/text_generation)
프롬프트: Artificial intelligence will

생성 1: Artificial intelligence will be used to make robots smarter. And we will be able to create intelligent machines capable of learning from the experiences of human human beings.

AI will come to society in the form of machines that will be able to do things that humans cannot. In this way, AI will become a part of what we call the "human social reality."

And this social reality is the social reality that allows us to become familiar with what we can do with AI. The social reality that allows us to be able to be more creative and more open to new ideas.

This social reality is what makes you more compassionate, is what makes us more free and more creative.

Human beings are not perfect people without a great deal of human experience.

What we are doing now is creating an AI that will be able to think and react better with more human wisdom and compassion.

But there is one problem with this system. It only has one way of thinking, and that is the artificial intelligence of tomorrow that is already in the work of AI.

The biggest problem with this system is that it is already making mistakes—because it has no idea how to make decisions—so it actually has no way of knowing what kind of decisions are right for it

생성 2: Artificial intelligence will be crucial for all industries. So should our workflows on a daily basis.

The fact that most of the world's firms are already on board with automated systems to design and deploy systems that are completely automated in some cases just indicates their interest in automated systems.

But, as I stated, human labor is another big issue. It should be part of this discussion.

The next question is, "How can you support your employees to make that leap?"

When I spoke at the SITIAC conference last month, I talked about how software-based systems like AI and machine learning can provide great value for the future for companies.

And, again, we saw this.

Companies have been working hard on AI, as long as systems like Google and Facebook are on board.

Companies in the software field have been working hard on AI through their partnerships with AI partners like Google, Facebook, IBM in the cloud, AI companies within the digital services industry, and even Microsoft.

And I don't think AI will ever be the thing we want to be.

We need real progress.

But, even if we could, I believe the next time you see an industry that is getting ready to be

3.3 질문 답변 (Question Answering)

문맥(context)이 주어졌을 때, 질문에 대한 답변을 추출합니다.

# 질문 답변 파이프라인
qa_pipeline = pipeline("question-answering")

# 문맥과 질문
context = """
Hugging Face is a company that provides tools and infrastructure for machine learning.
It was founded in 2016 and is based in New York City. The company is known for its
Transformers library, which allows developers to easily use pre-trained models.
"""

questions = [
    "When was Hugging Face founded?",
    "Where is Hugging Face based?",
    "What is Hugging Face known for?"
]

# 각 질문에 대한 답변 추출
for question in questions:
    qa_result = qa_pipeline(question=question, context=context)
    print(f"질문: {question}")
    print(f"답변: {qa_result['answer']} (확률: {qa_result['score']:.4f})\n")

3.4 번역 (Translation)

다양한 언어 간 번역을 수행합니다.

# 영어 → 프랑스어 번역
translator = pipeline("translation_en_to_fr")

text = "Hugging Face is an amazing platform for AI developers."
translation = translator(text)

print(f"원문 (영어): {text}")
print(f"번역 (프랑스어): {translation[0]['translation_text']}")

3.5 요약 (Summarization)

긴 텍스트를 짧게 요약합니다.

# 요약 파이프라인
summarizer = pipeline("summarization")

# 긴 텍스트
article = """
The transformer architecture has revolutionized natural language processing since its 
introduction in 2017. Unlike previous recurrent neural networks, transformers process 
entire sequences in parallel using self-attention mechanisms. This allows them to 
capture long-range dependencies more effectively. Models like BERT, GPT, and T5 are 
all based on the transformer architecture. These models have achieved state-of-the-art 
results on numerous NLP benchmarks and are now widely used in production systems.
"""

# 요약 생성
summary = summarizer(article, max_length=50, min_length=20)

print("원문:")
print(article.strip())
print("\n요약:")
print(summary[0]['summary_text'])

3.6 이미지 분류 (Image Classification)

Hugging Face는 NLP뿐만 아니라 컴퓨터 비전 모델도 제공합니다.

# 이미지 분류 파이프라인
image_classifier = pipeline("image-classification")

# 샘플 이미지 URL (고양이 사진)
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
response = requests.get(url)
image = Image.open(BytesIO(response.content))

# 이미지 분류
image_predictions = image_classifier(image)

# 상위 3개 결과 출력
print("이미지 분류 결과:")
for pred in image_predictions[:3]:
    print(f"- {pred['label']}: {pred['score']:.4f}")

# 이미지 표시
display(image)

4. 고급 사용법: Tokenizer와 Model 직접 사용

Pipeline은 편리하지만, 세밀한 제어가 필요할 때는 Tokenizer와 Model을 직접 사용합니다.

4.1 Tokenizer 이해하기

Tokenizer는 텍스트를 모델이 이해할 수 있는 숫자(토큰 ID)로 변환합니다.

# BERT 토크나이저 로드
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

text = "Hugging Face is awesome!"

# 토큰화
tokens = tokenizer.tokenize(text)
print(f"토큰: {tokens}")

# 토큰 ID로 변환
token_ids = tokenizer.encode(text)
print(f"토큰 ID: {token_ids}")

# ID를 다시 텍스트로 변환
decoded = tokenizer.decode(token_ids)
print(f"디코딩: {decoded}")

4.2 임베딩 생성 (Sentence Embeddings)

텍스트를 고정 길이의 벡터로 변환하여 유사도 계산, 검색 등에 활용합니다.

import torch
from transformers import AutoModel, AutoTokenizer

# Sentence-BERT 모델 로드
model_name = "sentence-transformers/all-MiniLM-L6-v2"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)

# 임베딩 생성 함수
def get_embedding(text):
    # 토큰화
    inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True)
    
    # 모델 추론
    with torch.no_grad():
        outputs = model(**inputs)
    
    # Mean pooling
    embeddings = outputs.last_hidden_state.mean(dim=1)
    return embeddings

# 예제 문장들
sentences = [
    "I love machine learning",
    "I enjoy artificial intelligence",
    "The weather is nice today"
]

# 임베딩 생성
embeddings = [get_embedding(sent) for sent in sentences]

# 임베딩 크기 확인
print(f"임베딩 차원: {embeddings[0].shape}")

# 코사인 유사도 계산
from torch.nn.functional import cosine_similarity

sim_01 = cosine_similarity(embeddings[0], embeddings[1]).item()
sim_02 = cosine_similarity(embeddings[0], embeddings[2]).item()

print(f"\n유사도:")
print(f"'{sentences[0]}' vs '{sentences[1]}': {sim_01:.4f}")
print(f"'{sentences[0]}' vs '{sentences[2]}': {sim_02:.4f}")
print(f"\n💡 첫 두 문장(ML 관련)이 더 유사합니다!")

5. 모델 탐색 및 선택

5.1 Hub에서 모델 검색

Hugging Face Hub에서는 태스크, 언어, 라이센스 등으로 모델을 필터링할 수 있습니다.

웹 인터페이스로 검색:

• 🔗 https://huggingface.co/models
• 왼쪽 필터로 태스크, 라이브러리, 언어 선택
• 인기순, 최신순 정렬 가능

Python으로 검색:

from huggingface_hub import list_models

# 감정 분석 모델 검색 (상위 5개)
models = list_models(
    filter="text-classification",
    sort="downloads",
    limit=5
)

print("인기 감정 분석 모델 TOP 5:")
for i, model in enumerate(models, 1):
    print(f"{i}. {model.modelId}")

인기 감정 분석 모델 TOP 5:
1. cross-encoder/ms-marco-MiniLM-L6-v2
2. cardiffnlp/twitter-roberta-base-sentiment-latest
3. facebook/bart-large-mnli
4. distilbert/distilbert-base-uncased-finetuned-sst-2-english
5. BAAI/bge-reranker-v2-m3

5.2 모델 정보 확인

from huggingface_hub import model_info

# GPT-2 모델 정보 조회
info = model_info("gpt2")

print(f"모델 ID: {info.modelId}")
print(f"파이프라인 태그: {info.pipeline_tag}")
print(f"다운로드 수: {info.downloads:,}")
print(f"라이브러리: {info.library_name}")
print(f"라이센스: {info.cardData.get('license', 'N/A')}")

모델 ID: openai-community/gpt2
파이프라인 태그: text-generation
다운로드 수: 6,397,931
라이브러리: transformers
라이센스: mit

6. 모델 다운로드 및 캐싱

6.1 자동 캐싱

Hugging Face는 모델을 자동으로 캐시합니다:

• 위치: ~/.cache/huggingface/hub/
• 동일 모델 재사용 시 다운로드 스킵

6.2 오프라인 사용

모델을 미리 다운로드하여 인터넷 없이 사용할 수 있습니다.

# 모델과 토크나이저 다운로드
model_name = "distilbert-base-uncased"

print("모델 다운로드 중...")
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)

print("✅ 모델이 로컬 캐시에 저장되었습니다!")
print(f"캐시 위치: ~/.cache/huggingface/hub/")

# 이제 오프라인에서도 사용 가능
# tokenizer = AutoTokenizer.from_pretrained(model_name, local_files_only=True)
# model = AutoModel.from_pretrained(model_name, local_files_only=True)

7. 지원하는 주요 태스크

Hugging Face는 다양한 AI 태스크를 지원합니다:

NLP (자연어 처리)

Computer Vision

Audio

8. 결론 및 요약

핵심 정리

1. Hugging Face는 AI 모델의 GitHub

   • 50만+ 사전 학습된 모델
   • 무료로 사용 가능
   • 활발한 커뮤니티

2. Pipeline으로 빠른 시작

   • 3줄 코드로 SOTA 모델 사용
   • 전처리-추론-후처리 자동화
   • 다양한 태스크 지원

3. 세밀한 제어가 필요하면 Tokenizer + Model

   • 커스텀 전처리 가능
   • 임베딩 추출
   • 파인튜닝 준비

4. 자동 캐싱으로 효율적 사용

   • 한 번 다운로드하면 재사용
   • 오프라인 사용 가능

다음 학습 방향

• ✅ 파인튜닝: 자신의 데이터로 모델 커스터마이징
• ✅ Datasets 라이브러리: 대용량 데이터 효율적 처리
• ✅ Trainer API: 학습 코드 간소화
• ✅ Gradio/Spaces: 모델 데모 앱 배포
• ✅ Quantization: 모델 경량화로 추론 속도 향상

유용한 링크

• 📚 공식 문서
• 🤗 Hugging Face Hub
• 📖 Transformers Course
• 💬 커뮤니티 포럼

실습 과제

1. Hub에서 한국어 감정 분석 모델을 찾아 사용해보기
2. 다양한 이미지 분류 모델을 비교해보기
3. 자신만의 텍스트로 임베딩 유사도 계산해보기

print("🎉 Hugging Face 기초 학습 완료!")
print("이제 여러분도 최신 AI 모델을 자유롭게 활용할 수 있습니다!")