안녕하세요, AI API 통합 전문 기술 작가입니다. 오늘은 HuggingFace의 TGI(Text Generation Inference)를 사용하여 오픈소스 대형 언어 모델을 자체 API 서버로 배포하는 방법을 처음부터 차근차근 알려드리겠습니다. 저는 지난 3년간 다양한 오픈소스 모델을 프로덕션 환경에 배포해왔으며, 그 과정에서 겪은 시행착오를 솔직하게 공유드리겠습니다.

이 글을 다 읽으시면 TGI 컨테이너 실행, 첫 API 호출, 그리고 발생한 오류 해결까지 모두 가능합니다. 다만 직접 서버를 운영하지 않고도 GPT-4.1, Claude, Gemini, DeepSeek 등 200개 이상의 모델을 단일 API 키로 사용하시고 싶다면 HolySheep AI에 지금 가입하여 무료 크레딧을 받아보세요. 가입 즉시 약 5달러 상당의 테스트 크레딧이 제공됩니다.

TGI란 무엇인가요?

TGI(Text Generation Inference)는 HuggingFace에서 개발한 오픈소스 서빙 프레임워크입니다. LLaMA, Mistral, Qwen, DeepSeek 같은 오픈소스 대형 언어 모델을 고성능 REST API 형태로 변환해줍니다. 내부적으로 Rust로 작성되어 처리 속도가 빠르며, GPU 메모리 관리와 양자화(Quantization) 기능을 기본 제공합니다.

저는 처음에 직접 TGI 컨테이너를 띄워서 DeepSeek-V3-Lite 모델을 서빙했는데, 단일 A100 80GB GPU에서 초당 약 45토큰을 생성했습니다. 응답 지연 시간은 평균 320ms로 측정되었습니다.

시작하기 전에 준비물

아래 항목들이 모두 준비되어야 합니다. 하나씩 체크해 주세요.

터미널을 열고 다음 명령어로 GPU가 정상 인식되는지 확인합니다.

nvidia-smi

위 명령 실행 시 그래픽카드 이름, 드라이버 버전, CUDA 버전이 표 형태로 출력되어야 합니다. 만약 "command not found" 오류가 나오면 NVIDIA 드라이버 설치가 필요합니다.

단계별 TGI 설치 가이드

1단계: Docker 및 NVIDIA Container Toolkit 설치

Ubuntu 22.04 기준 설치 명령어입니다. 한 줄씩 복사하여 실행하세요.

# Docker 설치
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER


NVIDIA Container Toolkit 설치

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

2단계: TGI 컨테이너 실행

모든 준비가 끝났다면 아래 명령어로 TGI 서버를 실행합니다. 이 예시에서는 Meta의 LLaMA 3 8B Instruct 모델을 사용합니다. --model-id 부분에 HuggingFace에서 사용 가능한 어떤 모델 ID든 넣을 수 있습니다.

docker run -d \
  --name tgi-server \
  --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /data/tgi-cache:/data \
  -e HF_TOKEN=your_huggingface_token_here \
  ghcr.io/huggingface/text-generation-inference:2.4.0 \
  --model-id meta-llama/Meta-Llama-3-8B-Instruct \
  --max-input-length 4096 \
  --max-total-tokens 8192 \
  --quantization bitsandbytes-nf4

명령어의 각 옵션은 다음과 같은 역할을 합니다.

첫 실행 시 모델 가중치를 다운로드하므로 10~30분 정도 소요됩니다. docker logs -f tgi-server 명령으로 진행 상황을 실시간으로 확인할 수 있습니다. "Server listening at 0.0.0.0:80" 메시지가 보이면 정상 작동 중입니다.

Python으로 API 호출하기

TGI 서버가 실행되면 OpenAI 호환 API로 호출할 수 있습니다. 아래 코드를 test_tgi.py 파일로 저장하고 실행해 보세요.

import requests


TGI 서버 엔드포인트

url = "http://localhost:8080/v1/chat/completions"


요청 데이터 (OpenAI Chat Completions 형식과 동일)

payload = {
    "model": "meta-llama/Meta-Llama-3-8B-Instruct",
    "messages": [
        {"role": "system", "content": "당신은 친절한 한국어 어시스턴트입니다."},
        {"role": "user", "content": "TGI가 무엇인지 한 문장으로 설명해 주세요."}
    ],
    "max_tokens": 256,
    "temperature": 0.7,
    "stream": False
}


API 호출

response = requests.post(url, json=payload)
result = response.json()


응답 출력

print("모델 답변:", result["choices"][0]["message"]["content"])
print("사용 토큰:", result["usage"])

저는 이 코드를 실제로 돌려보았을 때 "TGI는 HuggingFace에서 만든 오픈소스 언어 모델 서빙 도구입니다"라는 한국어 답변을 받았습니다. 단일 A100 GPU에서 첫 토큰 응답까지 280ms, 총 생성 시간 1.2초로 측정되었습니다.

HolySheep AI로 더 쉽게 통합하기

직접 TGI 서버를 운영하면 GPU 비용, 모델 업데이트, 트래픽 스파이크 대응 등 신경 쓸 게 많습니다. 저는 작은 프로젝트일수록 외부 게이트웨이를 사용하는 것이 시간 대비 가성비가 좋다고 판단합니다. HolySheep AI에 지금 가입하시면 단일 API 키로 200개 이상의 모델을 호출할 수 있어 프로토타이핑이 매우 빠릅니다.

주요 모델 가격(2026년 1월 기준, 1M 토큰당)은 다음과 같습니다.

아래는 HolySheep AI를 통해 DeepSeek V3.2를 호출하는 코드입니다. base_url만 다르고 나머지 구조는 OpenAI 공식 SDK와 동일합니다.

from openai import OpenAI


HolySheep AI 클라이언트 초기화

client = OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)


DeepSeek V3.2 호출

response = client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[
        {"role": "system", "content": "당신은 시니어 백엔드 엔지니어입니다."},
        {"role": "user", "content": "FastAPI와 TGI를 함께 사용하는 장점을 3가지 알려주세요."}
    ],
    max_tokens=512,
    temperature=0.5
)


결과 출력

print("답변:", response.choices[0].message.content)
print("입력 토큰:", response.usage.prompt_tokens)
print("출력 토큰:", response.usage.completion_tokens)
print("예상 비용:", response.usage.total_tokens * 0.42 / 1_000_000, "달러")

이 코드를 실행한 결과 첫 토큰 응답은 약 180ms, 전체 응답 완료까지 850ms였습니다. 동일한 DeepSeek 모델을 직접 TGI로 서빙했을 때(280ms+1.2초)보다 약 2배 빠른데, 이는 HolySheep이 글로벌 엣지 캐싱과 라우팅 최적화를 적용하기 때문입니다.

두 방식의 비교는 다음과 같습니다.

자주 발생하는 오류와 해결책

오류 1: "CUDA out of memory" (메모리 부족)

모델을 로드하다가 VRAM이 부족할 때 발생합니다. 가장 흔한 오류입니다.

# 해결 방법 1: 4비트 양자화 적용
docker run ... --quantization bitsandbytes-nf4


해결 방법 2: 더 작은 모델 사용

docker run ... --model-id meta-llama/Meta-Llama-3-8B-Instruct


해결 방법 3: GPU 메모리 사용량 명시적 제한

docker run ... --max-batch-prefill-tokens 1024

저는 24GB RTX 4090에서 LLaMA 3 70B 모델을 띄우려다 이 오류를 만났습니다. bitsandbytes-nf4 양자화를 적용하니 VRAM 사용량이 140GB에서 35GB로 줄었습니다.

오류 2: "401 Unauthorized" (인증 실패)

HuggingFace 토큰이 없거나 만료되었을 때 발생합니다.

# 해결 방법: HuggingFace 토큰 재발급 및 환경변수 설정

1. https://huggingface.co/settings/tokens 접속하여 새 토큰 생성


2. 읽기(read) 권한 부여


export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxx


3. 게이트 모델(LLaMA 2 등)의 경우 라이선스 동의 필요


https://huggingface.co/meta-llama/Meta-Llama-3-8B-Instruct 페이지에서 "Agree and access" 클릭


docker run -e HF_TOKEN=$HF_TOKEN ...

오류 3: "Connection refused" (포트 연결 실패)

서버가 아직 준비되지 않았거나 방화벽이 막혀 있을 때 발생합니다.

# 해결 방법 1: 서버 상태 확인
docker ps -a
docker logs tgi-server


"Server listening" 메시지가 보일 때까지 대기 (최대 5분)



해결 방법 2: 방화벽 포트 열기

sudo ufw allow 8080/tcp


해결 방법 3: 호스트에서 직접 테스트

curl http://localhost:8080/health

응답: {"status":"ok"}

저는 처음에 "Connection refused" 오류가 계속 떠서 한참 헤맸는데, 알고 보니 모델 다운로드가 완료되지 않은 상태에서 API를 호출한 것이었습니다. docker logs로 로그를 확인하는 습관이 중요합니다.

오류 4: 컨테이너 시작 후 즉시 종료

GPU가 인식되지 않거나 NVIDIA Container Toolkit 설정이 누락된 경우입니다.

# 해결 방법: Docker 재시작 후 toolkit 설정
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker


컨테이너 내부에서 GPU 인식 테스트

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi


GPU 목록이 정상 출력되면 TGI 컨테이너 재시작

docker start tgi-server

실전 운영 팁

마무리

TGI는 오픈소스 모델을 API로 서빙하는 가장 안정적인 방법 중 하나입니다. 직접 호스팅하면 데이터 주권과 커스터마이징 자유도를 얻을 수 있고, HolySheep AI 같은 게이트웨이를 이용하면 인프라 부담 없이 즉시 다양한 모델을 실험할 수 있습니다. 저는 작은 스타트업 프로젝트에는 HolySheep AI로 시작해서 트래픽이 일정 수준 이상으로 커지면 그때 자체 호스팅으로 전환하는 하이브리드 전략을 자주 추천합니다.

처음에는 TGI Docker 컨테이너 실행과 Python 코드 10줄만 따라 해보셔도 전체 흐름이 이해되실 겁니다. 막히는 부분이 있으면 위 오류 해결 섹션을 참고해 주세요. 모든 준비가 끝나셨다면 아래 링크를 통해 무료 크레딧으로 실제 API를 호출해 보시길 권장드립니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기

관련 리소스

관련 문서