[AI 개발] 5. Hugging Face 완전 가이드

모델 허브 · 파인튜닝 · LLM 서빙 가이드

Hugging Face 완전 가이드

Transformers와 Model Hub를 이용한 모델 실행부터 Inference API, LoRA·QLoRA 파인튜닝, 데이터셋 준비, TGI 기반 LLM 서빙, 모델 평가와 AI Agent 연동까지 정리합니다.

• Transformers
• Model Hub
• LoRA·QLoRA
• PEFT
• TGI
• smolagents

설치 없이 Hugging Face 예제를 실행해 보세요 브라우저에서 단계별 코드를 실행하고 결과를 확인할 수 있는 AI DevOps Learn Hugging Face 웹 IDE를 제공합니다.
Hugging Face 웹 IDE 열기 →

이 글의 핵심
Hugging Face는 모델을 다운로드하는 저장소만이 아니라 모델·토크나이저·데이터셋·학습 어댑터·평가·서빙을 연결하는 AI 개발 생태계입니다. 실무에서는 모델 선택보다 라이선스, tokenizer 호환성, 데이터 품질, 양자화 조건, 서빙 비용과 회귀 검증을 함께 관리해야 합니다.

목차

1. 모델 허브와 Pipeline
2. Inference API
3. LoRA 파인튜닝
4. QLoRA 4-bit
5. 데이터셋 준비
6. TGI 프로덕션 서버
7. 모델 평가
8. HF Agents와 Tool
9. 실무 설계
10. 운영 기준
11. 검증 전략

1. 모델 허브와 Pipeline

Hugging Face Hub에서는 다양한 자연어 처리, 이미지, 음성, 멀티모달 모델과 데이터셋을 탐색할 수 있습니다. pipeline은 모델 로드, 토크나이징, 추론과 후처리를 묶어 빠르게 기능을 확인할 때 유용합니다.

라이브러리	주요 역할
transformers	모델, tokenizer, pipeline과 학습 API
datasets	데이터셋 로드, 변환, streaming과 전처리
peft	LoRA·QLoRA 등 경량 파인튜닝 어댑터
trl	SFT, 선호도 학습과 정렬 학습 도구
accelerate	멀티 GPU 및 분산 학습 실행 지원
huggingface_hub	모델과 artifact 업로드, 다운로드, 버전 관리

Python

from transformers import pipeline
import torch

generator = pipeline(
    task="text-generation",
    model="meta-llama/Llama-3.1-8B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

messages = [
    {
        "role": "user",
        "content": "파이썬으로 퀵소트를 구현해줘",
    }
]

result = generator(
    messages,
    max_new_tokens=512,
    temperature=0.7,
)

print(result[0]["generated_text"][-1]["content"])

모델 사용 전 확인
모델마다 라이선스, 접근 승인, 사용 목적 제한과 권장 chat template이 다릅니다. Model Card를 확인하고 gated model은 계정 인증과 접근 승인을 먼저 진행하세요.

2. Inference API

로컬 GPU를 직접 구성하지 않고 Hugging Face가 제공하는 추론 엔드포인트를 호출할 수 있습니다. API token은 코드에 직접 입력하지 말고 환경 변수나 secret manager로 관리하는 것이 안전합니다.

Bash

export HF_TOKEN="hf_your_token"

# Windows PowerShell
# $env:HF_TOKEN="hf_your_token"

Python

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    api_key=os.environ["HF_TOKEN"],
)

stream = client.chat_completion(
    model="meta-llama/Llama-3.1-70B-Instruct",
    messages=[
        {
            "role": "user",
            "content": "LLM 파인튜닝의 핵심 개념을 설명해줘",
        }
    ],
    max_tokens=1024,
    stream=True,
)

for chunk in stream:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="", flush=True)

운영 시 확인할 항목

• 모델의 cold start와 첫 토큰 지연 시간
• 분당 요청 및 token 사용량 제한
• timeout, retry와 fallback 정책
• 입력·출력 데이터의 개인정보 및 기밀정보 포함 여부
• 모델 버전 고정과 변경 이력 관리

3. LoRA 파인튜닝

LoRA는 원본 모델 가중치를 대부분 고정한 상태에서 일부 선형 계층에 작은 저차원 행렬을 추가해 학습하는 방식입니다. 전체 모델을 다시 학습하는 방식보다 필요한 학습 메모리와 저장 공간을 줄일 수 있습니다.

Python

import torch
from peft import LoraConfig, TaskType, get_peft_model
from transformers import AutoModelForCausalLM

model_id = "meta-llama/Llama-3.1-8B"

lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type=TaskType.CAUSAL_LM,
)

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

model = get_peft_model(
    model,
    lora_config,
)

model.print_trainable_parameters()

target_modules 주의
q_proj, v_proj, c_attn 등 계층 이름은 모델 아키텍처에 따라 다릅니다. 적용 전 model.named_modules()로 실제 모듈 이름을 확인하세요.

4. QLoRA와 4-bit 양자화

QLoRA는 양자화한 기반 모델에 LoRA 어댑터를 학습하는 접근입니다. 제한된 GPU 메모리에서 큰 모델을 다룰 때 유용하지만, 하드웨어, 모델 구조, sequence length와 batch size에 따라 실제 메모리 요구량과 학습 속도가 크게 달라집니다.

Python

import torch
from peft import (
    LoraConfig,
    TaskType,
    get_peft_model,
    prepare_model_for_kbit_training,
)
from transformers import (
    AutoModelForCausalLM,
    BitsAndBytesConfig,
)

model_id = "meta-llama/Llama-3.1-8B"

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=quantization_config,
    device_map="auto",
)

model = prepare_model_for_kbit_training(model)

lora_config = LoraConfig(
    r=64,
    lora_alpha=16,
    target_modules=["q_proj", "v_proj"],
    task_type=TaskType.CAUSAL_LM,
)

model = get_peft_model(
    model,
    lora_config,
)

QLoRA 적용 전 점검

• GPU compute capability와 bfloat16 지원 여부
• bitsandbytes와 CUDA 호환성
• sequence length와 gradient checkpointing 설정
• 양자화 전후 품질 비교용 benchmark set
• 학습과 추론에서 사용하는 tokenizer 및 chat template 일치 여부

5. 데이터셋 준비

파인튜닝 결과는 모델보다 데이터 품질에 크게 좌우됩니다. 중복, 잘못된 정답, 개인정보, 라이선스와 데이터 누수를 먼저 점검하고, 학습 시 사용한 chat template을 추론 단계에서도 동일하게 적용해야 합니다.

train.jsonl 예시

{"input":"환불 규정을 설명해 주세요.","output":"구매 후 7일 이내에는..."}
{"input":"비밀번호를 변경하고 싶습니다.","output":"설정 화면에서..."}

Python

from datasets import load_dataset
from transformers import AutoTokenizer

model_id = "meta-llama/Llama-3.1-8B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(
    model_id,
)

dataset = load_dataset(
    "json",
    data_files="train.jsonl",
    split="train",
)


def format_chat(example):
    messages = [
        {
            "role": "system",
            "content": "당신은 친절한 AI 어시스턴트입니다.",
        },
        {
            "role": "user",
            "content": example["input"],
        },
        {
            "role": "assistant",
            "content": example["output"],
        },
    ]

    text = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
    )

    return {"text": text}


dataset = dataset.map(
    format_chat,
    remove_columns=dataset.column_names,
)

print(dataset[0]["text"][:300])

데이터 품질 체크리스트

• 학습·검증·테스트 데이터가 서로 중복되지 않는지 확인합니다.
• 개인정보와 내부 기밀정보를 제거하거나 비식별 처리합니다.
• 원천 데이터와 생성 데이터의 라이선스를 기록합니다.
• 응답 길이, 문체와 정답 형식이 지나치게 편향되지 않았는지 확인합니다.
• 모델이 거절해야 하는 안전성 샘플을 별도로 구성합니다.

6. TGI 프로덕션 서버

Text Generation Inference(TGI)는 Hugging Face 모델을 GPU 서버에서 제공하기 위한 LLM 추론 서버입니다. Docker로 모델 서버를 실행하고 애플리케이션은 HTTP API를 통해 호출할 수 있습니다.

Bash

# 실제 배포 전에는 현재 권장 이미지 태그를 확인하세요.
docker run --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v "$HOME/.cache/huggingface:/data" \
  -e HF_TOKEN="$HF_TOKEN" \
  ghcr.io/huggingface/text-generation-inference:3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct \
  --max-total-tokens 4096 \
  --max-input-tokens 3072

Python · OpenAI 호환 API 호출

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-used",
)

stream = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[
        {
            "role": "user",
            "content": "Hugging Face TGI의 장점을 설명해줘",
        }
    ],
    max_tokens=512,
    stream=True,
)

for chunk in stream:
    print(
        chunk.choices[0].delta.content or "",
        end="",
        flush=True,
    )

서빙 성능에 영향을 주는 요소

• 모델 크기, dtype, quantization 방식
• 입력 token과 최대 생성 token 제한
• 동시 요청 수와 batch 처리 전략
• KV cache 메모리 사용량
• 첫 token 지연 시간과 초당 생성 token 수
• 모델 로딩 시간과 readiness probe 기준

7. 모델 평가

파인튜닝 전후 결과를 같은 평가셋으로 비교해야 합니다. 요약이나 번역처럼 정답 문자열이 있는 작업은 자동 metric을 사용할 수 있지만, 대화형 LLM은 도메인 평가셋, 사람 평가와 안전성 검증을 함께 운영하는 것이 좋습니다.

Python

import evaluate

rouge = evaluate.load("rouge")
bertscore = evaluate.load("bertscore")

predictions = [
    "모델이 생성한 요약문입니다.",
]

references = [
    "참조 정답 요약문입니다.",
]

rouge_result = rouge.compute(
    predictions=predictions,
    references=references,
)

bert_result = bertscore.compute(
    predictions=predictions,
    references=references,
    lang="ko",
)

print(rouge_result)
print("BERTScore F1:", bert_result["f1"][0])

자동 metric은 모델 품질의 한 측면만 보여 줍니다. 사실성, 지시 준수, 안전성, 응답 형식과 도메인 정확성을 별도 기준으로 평가하세요.

8. Hugging Face Agents와 Tool

smolagents를 사용하면 LLM이 검색이나 사용자 정의 도구를 호출하는 Agent 흐름을 구성할 수 있습니다. 코드 실행형 Agent는 강력하지만, 반드시 격리된 실행 환경과 허용 도구 목록을 적용해야 합니다.

Python

from smolagents import (
    CodeAgent,
    DuckDuckGoSearchTool,
    HfApiModel,
)

model = HfApiModel(
    model_id="meta-llama/Llama-3.1-70B-Instruct",
)

agent = CodeAgent(
    tools=[
        DuckDuckGoSearchTool(),
    ],
    model=model,
    max_steps=10,
)

result = agent.run(
    "최신 LLM 벤치마크 결과를 찾아 표로 정리해줘"
)

print(result)

Agent 보안 주의
코드 실행 기능은 임의 명령 실행, 파일 접근과 외부 통신으로 이어질 수 있습니다. 컨테이너 또는 샌드박스에서 실행하고 네트워크, 파일 시스템, 실행 시간과 사용 가능한 도구를 제한하세요.

9. Hugging Face 실무 설계

모델 선택만으로 프로젝트 구조가 완성되지는 않습니다. tokenizer, generation config, prompt template, adapter, dataset과 evaluation artifact를 한 세트로 버전 관리해야 결과를 재현할 수 있습니다.

결정 지점	확인 질문	실무 기준
모델	어떤 모델과 revision을 사용했는가?	모델 ID, revision, 라이선스와 Model Card를 기록합니다.
Tokenizer	학습과 추론 설정이 일치하는가?	tokenizer와 chat template을 모델과 함께 고정합니다.
Adapter	LoRA artifact가 어떤 기반 모델용인가?	base model, PEFT config와 adapter 버전을 연결합니다.
데이터	데이터 출처와 정제 과정이 추적 가능한가?	Dataset Card와 전처리 버전을 관리합니다.
장애	추론 실패 시 호출자는 무엇을 받는가?	timeout, retry, fallback과 error contract를 정의합니다.

권장 artifact 구성

Directory

hf-project/
├── configs/
│   ├── model.yaml
│   ├── training.yaml
│   └── generation.yaml
├── datasets/
│   └── dataset-card.md
├── adapters/
├── evaluations/
│   ├── benchmark.jsonl
│   └── safety-prompts.jsonl
├── src/
│   ├── train.py
│   ├── infer.py
│   └── serve.py
└── model-card.md

10. Hugging Face 운영 기준

LLM 운영 비용과 지연 시간은 최대 token, 동시성, batch size, quantization, cache와 GPU 메모리 사용 방식에 영향을 받습니다. 평균 응답 시간만 보지 말고 첫 token 지연과 token 처리량을 분리해 측정하세요.

운영 전 확인 목록

• 모델, tokenizer, revision과 generation config를 고정합니다.
• HF token을 코드와 이미지에 포함하지 않습니다.
• 모델 라이선스와 상업적 사용 가능 여부를 확인합니다.
• 최대 입력·출력 token과 timeout을 제한합니다.
• GPU memory, KV cache, 처리량과 첫 token 지연을 모니터링합니다.
• 모델 로딩 중에는 트래픽을 받지 않도록 readiness를 구성합니다.
• 입력과 출력 로그에서 개인정보 및 기밀정보를 보호합니다.
• 안전성 필터와 fallback 모델 또는 정책을 준비합니다.

11. Hugging Face 검증 전략

모델, 프롬프트, 데이터셋 또는 양자화 설정을 변경할 때는 고정된 benchmark set과 regression prompt로 변경 전후를 비교해야 합니다.

품질 축	검증 방법	완료 기준
정확성	정상·경계·실패 프롬프트를 자동화합니다.	핵심 업무 시나리오가 반복 실행되어도 통과합니다.
회귀 방지	버그와 품질 저하 사례를 regression prompt로 유지합니다.	같은 오류가 다시 배포되지 않습니다.
데이터 품질	중복, 오염, 누수와 라이선스를 확인합니다.	학습 데이터의 출처와 정제 이력이 추적됩니다.
안전성	유해 요청, prompt injection과 정보 유출 사례를 평가합니다.	정의한 정책에 따라 거절 또는 안전한 응답을 반환합니다.
성능	TTFT, token/s, 동시성, GPU memory를 측정합니다.	서비스 목표와 비용 기준을 충족합니다.
운영성	로그, metric, alert와 장애 복구 절차를 검증합니다.	장애 발생 시 원인 추적과 복구 경로가 존재합니다.

마무리

Hugging Face를 잘 활용하려면 모델을 불러오는 코드뿐 아니라 데이터 준비, 경량 파인튜닝, 평가, 서빙과 운영 검증을 하나의 흐름으로 설계해야 합니다. 작은 모델과 제한된 데이터로 먼저 검증한 뒤 실제 품질과 성능 측정 결과를 기준으로 모델 크기와 인프라를 확장하는 방식이 안전합니다.

핵심 정리

• Model Hub와 Transformers로 모델과 tokenizer를 함께 관리합니다.
• LoRA·QLoRA는 경량 파인튜닝에 활용할 수 있습니다.
• 데이터 품질과 chat template 일치 여부를 우선 확인합니다.
• TGI 등 추론 서버에서는 token, batch, cache와 GPU memory를 관리합니다.
• 고정 평가셋, 안전성 샘플과 regression prompt를 운영합니다.

원문: AI DevOps Korea Hugging Face 가이드  ·  Hugging Face 웹 IDE