TGI - 텍스트 생성 추론 - 설치, 구성, 문제 해결

TGI 를 설치하고 빠르게 배포하며 더 빠르게 디버깅하세요.

Page content

Text Generation Inference(TGI) 는 매우 특유의 에너지를 지니고 있습니다. 추론 분야에서 가장 새로운 기술은 아니지만, 이미 프로덕션 환경에서 발생하는 문제를 잘 이해하고 있습니다.

그리고 그 교훈을 기본 설정에 반영했습니다. 목표가 “HTTP 를 통해 LLM 을 제공하되 계속 실행되도록 유지하는 것"이라면, TGI 는 실용적인 도구입니다.

어디에서 모델을 실행할지 여전히 고민 중이라면, 로컬, 자체 호스팅, 클라우드 설정을 모두 살펴보고 TGI 를 문맥에 맞게 이해할 수 있도록 돕는 2026 년 LLM 호스팅 비교 가이드 를 참고하세요.

먼저 현실 점검을 해보겠습니다. 2026 년 기준 TGI 는 유지보수 모드에 있으며, 업스트림 저장소는 읽기 전용으로 아카이브되었습니다. 이는 운영 (Ops) 관점에서 보면 오히려 좋은 소식처럼 들립니다. 실제 변화가 모델, 프롬프트, 제품 요구 사항에서 일어나고 있기 때문에, 안정적인 엔진은 오히려 특징이 될 수 있습니다.

laptop with server

이 가이드는 첫날과 30 일째에 중요한 네 가지 사항에 초점을 맞춥니다: 설치 경로, 실제로 작동하는 빠른 시작, 실제 동작을 변경하는 설정, 그리고 시간을 절약해 주는 문제 해결 마인드셋입니다.

2026 년에도 여전히 중요한 TGI 의 이유

추론 서버를 모두 동일하게 취급하는 것은 쉽습니다. 일반적인 로컬 스택에 대한 도구별 조사를 원한다면 Ollama vs vLLM vs LM Studio: 2026 년 로컬 LLM 실행의 최선의 방법? 에서 시작하세요.

실제로는 중요한 질문이 세 가지뿐입니다.

첫째, 부하 하에서 어떻게 작동하는가입니다. TGI 는 연속 배치 (continuous batching) 와 토큰 스트리밍을 중심으로 설계되어 있으므로, 처리량을 우선시하면서도 사용자에게 반응성의 환상을 줄 수 있습니다.

둘째, 기존 도구 환경과 소통할 수 있는가입니다. TGI 는 자체 “커스텀 API"를 지원하며, OpenAI Chat Completions 스키마와 호환되는 Messages API 도 제공합니다. 이는 OpenAI 형식의 엔드포인트를 기대하는 도구들이 최소한의 변경으로 TGI 를 사용할 수 있음을 의미합니다.

셋째, 추측 없이 관찰할 수 있는가입니다. TGI 는 Prometheus 메트릭을 노출하고 OpenTelemetry 을 통해 분산 추적 (distributed tracing) 을 지원합니다. 이는 “느린 것 같다"는 생각과 “prefill 이 포화 상태이고, 대기 시간이 증가하며, 배치 토큰 예산이 너무 높다"는 사실 사이의 차이를 만들어냅니다.

설치 경로 및 사전 요구 사항

TGI 는 Docker 나 소스 코드로 로컬 설치 두 가지 방식으로 접근할 수 있습니다. Docker 경로가 대부분의 사람들이 “TGI 설치"라고 할 때 의미하는 바입니다. 이는 라우터, 모델 서버, 커널을 하나의 이미지로 패키징하여 단일 명령어로 실행할 수 있기 때문입니다.

내부적으로 TGI 는 구별되는 구성 요소로 이루어진 시스템입니다. HTTP 를 받아들이고 배치를 수행하는 라우터, 하나 이상의 모델 서버 프로세스를 오케스트레이션하는 런처, 모델을 로드하고 추론을 수행하는 모델 서버가 있습니다. 이러한 분리는 설정 플래그와 일반적인 실패 모드 뒤에 숨겨진 ‘왜’를 설명합니다.

두 가지 실용적인 사전 요구 사항이 자주 나타납니다: 컨테이너에서의 GPU 접근과 모델 가중치를 위한 합리적인 캐시 전략입니다. Nvidia 의 GPU 접근은 일반적으로 Nvidia Container Toolkit 이 설치되어 있음을 의미하며, 캐싱은 모델 가중치가 매번 다시 다운로드되지 않도록 호스트 볼륨을 컨테이너에 매핑하는 것을 의미합니다.

소스 코드에서의 로컬 설치

소스 코드 설치는 존재하지만, 개발자와 커널 빌더를 염두에 둔 의견이 반영되어 있습니다. Rust, Python 3.9+, 빌드 도구를 필요로 하며, 컨테이너를 실행하는 것보다 첫 단계가 더 느린 경우가 많습니다. 내부 수정, 패치 테스트, 또는 매우 구체적인 환경과의 통합이 필요할 때 유용합니다.

Docker 를 활용한 빠른 시작

정석적인 빠른 시작은 짧습니다. 이것이 바로 의도입니다. 모델 ID 를 선택하고, 캐시 볼륨을 마운트하며, 포트를 노출한 후 컨테이너를 실행합니다.

Nvidia GPU 빠른 시작

이는 첫 부팅에 잘 작동하는 최소 패턴입니다.

model=HuggingFaceH4/zephyr-7b-beta
volume=$PWD/data

docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model

이 한 명령은 “Nvidia GPU 에서 Docker 와 함께 TGI 를 어떻게 실행합니까?“라는 빈번한 FAQ 질문을 암묵적으로 답변합니다. --gpus all, 포트 매핑, 모델 ID 라는 세 가지 필수 요소를 보여주기 때문입니다.

미묘하지만 중요한 점은 포트 매핑입니다. 컨테이너는 일반적으로 포트 80 에서 HTTP 를 제공하도록 구성되어 있으므로, 호스트 8080 을 컨테이너 80 으로 매핑합니다. Docker 밖에서 TGI 를 실행할 경우 런처의 기본 포트는 종종 3000 이므로, 포트 혼란이 첫날에 발생하는 일반적인 버그입니다.

커스텀 API 를 사용한 첫 요청

TGI 는 간단한 JSON “생성 (generate)“스타일 API 를 노출합니다. 스트리밍 요청은 다음과 같습니다.

curl 127.0.0.1:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"What is Deep Learning?","parameters":{"max_new_tokens":40}}'

단일 응답을 선호한다면 스트리밍되지 않는 엔드포인트를 사용하세요.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Explain continuous batching in one paragraph.","parameters":{"max_new_tokens":120}}'

Messages API 를 사용한 첫 요청

생태계가 OpenAI 스타일 채팅 요청을 기대한다면 Messages API 를 사용하세요. 이는 또 다른 FAQ 질문인 “OpenAI 호환 채팅 클라이언트와 TGI 를 어떻게 사용합니까?“와 직접적으로 관련이 있습니다.

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give a one sentence definition of tensor parallelism."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

게이트드 (Gated) 또는_private_모델 제공

“게이트드 또는 사적인 Hugging Face 모델을 TGI 로 어떻게 제공합니까?“라고 한 번이라도问过 있다면, 답은 의도적으로 지루합니다: HF_TOKEN을 통해 Hub 토큰을 제공하면 됩니다.

model=meta-llama/Meta-Llama-3.1-8B-Instruct
volume=$PWD/data
token=hf_your_read_token_here

docker run --gpus all --shm-size 1g -e HF_TOKEN=$token -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model

여기서의 실패 모드도 지루합니다: 권한 누락, 유효하지 않은 토큰 범위, 또는 라이선스 수락이 필요한 모델을 끌어오려는 시도입니다.

AMD ROCm 빠른 시작

TGI 는 ROCm 이미지와 다른 장치 설정도 지원합니다. AMD GPU 를 사용 중이라면 부팅 모양이 달라집니다.

model=HuggingFaceH4/zephyr-7b-beta
volume=$PWD/data

docker run --device /dev/kfd --device /dev/dri --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5-rocm \
  --model-id $model

CPU 만 실행

CPU 만 실행은 존재하지만, TGI 가 훌륭하게 설계된 플랫폼은 아닙니다. 그래도 실행할 경우, 커스텀 커널을 비활성화하면 하드웨어 특정 문제를 피할 수 있습니다.

model=gpt2
volume=$PWD/data

docker run --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model \
  --disable-custom-kernels

실제로 효과를 내는 설정

TGI 는 플래그가 많습니다. 대부분 외울 필요는 없습니다. 몇 가지는 이해할 가치가 있습니다. 이 분야에서 가장 많이 검색되는 질문인 “어떤 TGI 설정이 GPU 메모리와 요청 제한을 제어합니까?“에 답변하기 때문입니다.

메모리 예산은 최대 총 토큰 수입니다.

TGI 설정에서 가장 중요한 단일 개념은 서버가 배치를 계획하고 메모리 폭주를 피하기 위해 토큰 예산이 필요하다는 것입니다.

요청 모양을 정의하는 두 가지 제한이 있습니다: max_input_tokens 와 max_total_tokens.

max_total_tokens 는 입력 토큰과 생성된 토큰의 합을 제한하기 때문에 요청당 메모리 예산처럼 작동합니다. 이 값이 너무 높으면 각 요청이 비싸고 배치가 어색해지며 메모리 압력이 커집니다. 너무 낮으면 사용자가 일찍 길이 제한에 부딪히며 서버는 유효한 워크로드를 거부합니다.

예산이 명시적인 설정은 다음과 같습니다.

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --max-input-tokens 2048 \
  --max-total-tokens 3072

중요한 배치 조절기

토큰 예산이 설정되면, 배치 제어가 다음 레버입니다.

max_batch_prefill_tokens 는 프리필 (prefill) 작업을 제한합니다. 이는 종종 메모리 집약적이고 계산에 제약이 가장 큰 단계입니다. max_batch_total_tokens 는 서버가 전체적으로 배치에 맞추려고 시도하는 토큰 수를 설정합니다. 이는 실제 처리량 제어 중 하나입니다.

관심 있는 조절기는 waiting_served_ratio입니다. 이는 하드웨어 제약이 아닌 정책 결정을 인코딩합니다. 이는 서버가 대기 중인 요청을 새로운 프리필로 가져와 디코드 그룹에 참여시키기 위해 디코드 작업을 일시 중지할 때를 제어합니다. 낮은 값은 기존 요청을 선호하고, 높은 값은 새로 대기열에 추가된 요청의 꼬리 대기 시간 (tail latency) 을 줄이는 경향이 있으며, 트래픽 모양에 따라 둘 다 “맞을” 수 있습니다.

썸딩 (Sharding), num_shard 및 NCCL 이 등장하는 이유

모델이 하나의 GPU 에 맞지 않거나 텐서 병렬 처리를 통해 더 높은 처리량을 원한다면, 썸딩이 다음 단계입니다.

정신 모델은 간단합니다: --sharded true는 썸딩을 활성화하고, --num-shard는 썸드 개수를 제어합니다. 서버는 기본적으로 모든 가시적인 GPU 를 사용하거나 부분집합을 사용할 수 있습니다.

멀티 GPU 호스트에서 유용한 패턴은 GPU 를 그룹으로 나누고, 각 복제본이 자체 GPU 부분집합에 걸쳐 썸딩되도록 여러 TGI 복제본을 실행하는 것입니다. 이는 부하를 분산시키면서도 썸딩 토폴로지를 단순하게 유지합니다.

이 부분에서 FAQ 질문인 “왜 여러 GPU 에서 TGI 가 NCCL 또는 공유 메모리 오류로 실패합니까?“가 관련이 깊습니다. 멀티 GPU 설정은 집단 통신에 의존하며, 컨테이너는 SHM 폴백이 사용될 때 안전한 작동을 위한 충분한 공유 메모리가 필요합니다.

양자화 (Quantisation) 선택 및 트레이드오프

양자화는 “맞게 만드는” 설정 중 가장 오해받는 부분으로, 두 가지 다른 목표를 혼합합니다: 메모리 감소와 속도입니다.

TGI 는 GPTQ 와 AWQ 와 같은 스키밍에 대한 사전 양자화된 가중치를 지원하며, bitsandbytes 와 EETQ 와 같은 특정 방법에 대한 온더플라이 양자화도 지원합니다. 일부 방법은 메모리를 줄이지만 네이티브 반정밀도보다 느리기 때문에, 양자화는 무료 성능 업그레이드로 취급해서는 안 됩니다.

간단한 온더플라이 8 비트 양자화 예시는 다음과 같습니다.

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --quantize bitsandbytes

4 비트 변형은 다음과 같습니다.

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --quantize bitsandbytes-nf4

API 형성 및 기본 보호 장치

TGI 는 내부 서비스로 실행하거나 더 광범위하게 노출할 수 있습니다. 노출이 가능하다면 두 가지 플래그가 중요합니다: max_concurrent_requests 와 api_key.

max_concurrent_requests 는 백프레셔를 제공합니다. 모든 것을 대기열에 넣고 타임아웃이 발생하도록 하기보다는 서버가 과도한 요청을 거부하게 만듭니다.

API 키는 거친 인증 장벽을 제공합니다. 이는 전체 인증 시스템은 아니지만, 우발적인 공개 사용을 막습니다.

CORS 도 cors_allow_origin을 통해 구성할 수 있으며, 브라우저 기반 UI 가 서버를 직접 호출할 경우 중요합니다.

운영 및 가시성

이 섹션은 실제 운영자 질문인 “TGI 서버에서 Prometheus 메트릭을 어디서 수집할 수 있습니까?“에 답변합니다.

OpenAPI 문서 및 인터랙티브 문서

TGI 는 /docs 경로 아래에서 OpenAPI 와 Swagger UI 를 노출합니다. 이는 클라이언트를 작성하지 않고도 요청 및 응답 모양을 빠르게 확인하거나 엔드포인트를 테스트할 때 유용합니다.

Prometheus 메트릭

TGI 는 /metrics 엔드포인트에서 Prometheus 메트릭을 내보냅니다. 이 메트릭은 대기열 크기, 요청 대기 시간, 토큰 수, 배치 수준 타이밍을 포함합니다. 그 결과 시스템이 프리필, 디코드, 또는 대기열에 의해 제한되는지 관찰할 수 있습니다.

종단 간 프로덕션 모니터링 (PromQL, Grafana 대시보드, 알림, Docker 나 Kubernetes 스택에 대한 수집 레이아웃) 은 프로덕션에서 LLM 추론 모니터링 (2026): vLLM, TGI, llama.cpp 를 위한 Prometheus & Grafana 에서 다룹니다.

추적 및 구조화된 로그

TGI 는 OpenTelemetry 을 통해 분산 추적을 지원합니다. 로그는 JSON 으로도 방출할 수 있어 로그 파이프라인을 쉽게 만듭니다.

문제 해결 플레이북

TGI 실패는 몇 가지 범주로 모이는 경향이 있으며, 각 범주는 매우 다른 해결책을 가집니다.

컨테이너는 실행되지만 GPU 가 감지되지 않음

가장 일반적인 원인은 컨테이너 런타임이 GPU 통과를 위해 구성되어 있지 않기 때문입니다. Nvidia 의 경우, 이는 종종 Nvidia Container Toolkit 지원 누락 또는 호스트 드라이버 스택이 기대와 일치하지 않아 발생합니다.

모델 다운로드 실패 및 권한 오류

서버가 모델 파일을 다운로드할 수 없다면, 일반적인 범인은 게이트드 모델의 인증 토큰 누락, 모델 읽기 권한이 없는 토큰, 또는 속도 제한입니다. HF_TOKEN을 올바르게 설정하면 게이트드 모델 사례가 해결됩니다.

CUDA 메모리 부족 또는 부하 하에서 갑작스런 재시작

가장 일반적인 원인은 지나치게 관대한 토큰 예산입니다. max_total_tokens가 크고 클라이언트가 긴 생성을 요청하면, 서버는 최악의 경우 요청을 위해 메모리를 예약합니다. 예산을 줄이고, 동시성을 줄이거나, 제약 조건에 맞는 양자화 방법을 선택하세요.

멀티 GPU NCCL 오류, 멈춤 또는 극심한 속도 저하

여러 GPU 에서 썸딩할 때, 공유 메모리와 NCCL 이 중요합니다. 컨테이너 내부의 부족한 공유 메모리는 종종 불안정성을 만듭니다. 공유 메모리 할당을 늘리거나 NCCL_SHM_DISABLE 를 통해 SHM 공유를 비활성화하면 동작이 변하며 성능 트레이드오프가 발생합니다.

NCCL 문제는 NCCL 디버그 로깅이 활성화되면 더 쉽게 디버그할 수 있습니다. 오류 보고서가 더 명확하기 때문입니다.

A100 하드웨어가 아닌 곳에서 발생하는 이상한 커널 오류

일부 모델은 특정 하드웨어에서 먼저 테스트된 커스텀 커널을 사용합니다. 설명할 수 없는 커널 실패를 보다면, --disable-custom-kernels가 커스텀 커널이 관련되어 있는지 확인하는 가장 간단한 방법인 경우가 많습니다.

포트 혼란 및 “실행되지만 접근할 수 없음”

고전적인 실수는 Docker 포트 매핑 모델과 로컬 기본 포트 모델을 혼합하는 것입니다. Docker 예시에서 컨테이너는 일반적으로 80 에서 서비스를 제공하며, 로컬 실행은 기본 3000 입니다. 잘못된 포트를 매핑하면 curl 요청이 아무것도 닿지 않고, 시스템은 고장난 것처럼 보이지만 실제로는 단순히 접근할 수 없는 것입니다.

마무리

TGI 는 인프라처럼 느껴집니다. 이것이 칭찬입니다. TGI 는 텍스트 생성을 운영하기에 지루하게, 디버깅하기에 측정 가능하게, 기존 OpenAI 형식 클라이언트 스택에 맞도록 유연하게 설계된 시스템입니다.