MLOPS / 중급

TGI 완전 가이드: Hugging Face의 프로덕션급 LLM 서빙

Text Generation Inference(TGI)의 아키텍처, Continuous Batching·Flash Attention·Tensor Parallelism, Docker 배포, Python 클라이언트, 구조화 출력·투기적 디코딩 고급 옵션.

PALDYN Team2026.05.176 MIN READ

지난 글에서 개발 환경에 특화된 Ollama를 살펴봤다. 이번에는 Hugging Face가 만든 프로덕션 서빙 솔루션 TGI(Text Generation Inference)를 다룬다. HF Hub의 수천 개 모델을 Docker 한 줄로 서빙할 수 있고, Flash Attention·Continuous Batching·Tensor Parallelism이 기본 내장되어 있다. HF Inference Endpoints 서비스의 엔진이기도 하다.

TGI 아키텍처

TGI는 고성능 Rust 라우터와 Python GPU 워커의 조합이다.

Rust 라우터: HTTP 요청 수신, 입력 검증, Server-Sent Events(SSE) 스트리밍 전송을 담당한다. 비동기 처리로 수천 개의 동시 연결을 처리할 수 있다.

Scheduler: Continuous Batching 로직을 담당한다. 각 Forward Pass(iteration)마다 완료된 요청을 제거하고 대기 중인 요청을 추가한다.

GPU Worker: PyTorch 기반으로 실제 추론을 수행한다. Flash Attention, 양자화 커널, Tensor Parallelism 샤딩이 여기서 실행된다.

# Hugging Face 토큰 설정 (게이트 모델에 필요)
export HUGGING_FACE_HUB_TOKEN="hf_..."

# 기본 실행 (Docker)
docker run --gpus all \
  -e HUGGING_FACE_HUB_TOKEN=$HUGGING_FACE_HUB_TOKEN \
  -p 8080:80 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id meta-llama/Llama-3.1-8B-Instruct \
  --max-input-length 4096 \
  --max-total-tokens 8192 \
  --max-batch-prefill-tokens 8192

TGI 아키텍처

주요 실행 옵션

docker run --gpus all -p 8080:80 \
  -v $HF_HOME:/root/.cache/huggingface \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id meta-llama/Llama-3.1-70B-Instruct \
  --num-shard 4 \                  # 4 GPU Tensor Parallelism
  --quantize awq \                 # AWQ 4비트 양자화
  --max-input-length 8192 \
  --max-total-tokens 16384 \
  --max-batch-total-tokens 65536 \ # 배치 전체 최대 토큰
  --speculate 3 \                  # 투기적 디코딩 (K=3)
  --hostname 0.0.0.0 \
  --port 80

지원 양자화 옵션: awq, gptq, eetq(INT8), fp8, bitsandbytes(NF4)

Python 클라이언트

from huggingface_hub import InferenceClient

client = InferenceClient(model="http://localhost:8080")

# 단순 텍스트 생성
text = client.text_generation(
    "Python의 asyncio 이벤트 루프를 설명해줘",
    max_new_tokens=300,
    temperature=0.7,
    top_p=0.9,
    repetition_penalty=1.05,
)
print(text)

# 스트리밍
for token in client.text_generation(
    "한국 경제의 특징을 설명해줘",
    max_new_tokens=400,
    stream=True,
):
    print(token, end="", flush=True)
print()

# Chat Completion API (OpenAI 호환)
response = client.chat_completion(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "머신러닝과 딥러닝의 차이는?"},
    ],
    max_tokens=300,
    stream=False,
)
print(response.choices[0].message.content)

TGI 클라이언트 사용법

HF Inference Endpoints: 클라우드 서빙

직접 서버를 관리하기 싫다면 HF Inference Endpoints가 답이다. HF Hub에서 클릭 몇 번으로 TGI 인스턴스를 클라우드에 배포한다.

from huggingface_hub import InferenceClient

# HF Inference Endpoint URL로 연결
client = InferenceClient(
    model="https://xxx.us-east-1.aws.endpoints.huggingface.cloud",
    token="hf_...",
)

response = client.text_generation(
    "Explain transformer architecture",
    max_new_tokens=200,
)
print(response)

구조화 출력 (Grammar Constraints)

TGI는 JSON Schema나 Regex로 출력 형식을 강제할 수 있다.

import json

# JSON Schema로 출력 형식 강제
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "city": {"type": "string"},
    },
    "required": ["name", "age", "city"],
}

result = client.text_generation(
    "다음 텍스트에서 정보를 추출: 김민수(32세)는 부산에 삽니다.",
    grammar={"type": "json", "value": schema},
    max_new_tokens=100,
)
parsed = json.loads(result)
print(parsed)  # {"name": "김민수", "age": 32, "city": "부산"}

멀티모달: IDEFICS와 LLaVA

TGI는 멀티모달 모델도 지원한다.

from huggingface_hub import InferenceClient

client = InferenceClient(model="http://localhost:8080")

# 이미지 + 텍스트 입력
import base64
with open("diagram.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

result = client.chat_completion(
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}},
            {"type": "text", "text": "이 다이어그램을 설명해줘"},
        ],
    }],
    max_tokens=300,
)
print(result.choices[0].message.content)

Tensor Parallelism으로 대형 모델 실행

70B 모델을 멀티 GPU에 샤딩하는 방법이다.

# 4 GPU A100으로 Llama-3.1-70B 실행
docker run --gpus '"device=0,1,2,3"' \
  -p 8080:80 \
  -v $HF_HOME:/root/.cache/huggingface \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id meta-llama/Llama-3.1-70B-Instruct \
  --num-shard 4 \
  --max-input-length 8192 \
  --max-total-tokens 16384

# Python에서 대형 모델 성능 벤치마크
import time

prompts = ["Python은 어떤 언어인가요?"] * 32

start = time.time()
results = []
for p in prompts:
    r = client.text_generation(p, max_new_tokens=100)
    results.append(r)
elapsed = time.time() - start

total_tokens = sum(len(r.split()) for r in results)
print(f"총 시간: {elapsed:.1f}s, 처리량: {total_tokens/elapsed:.0f} tok/s")