TGI 모델 배포 (Launch)¶
개요¶
TGI(Text Generation Inference)로 모델을 서빙하려면, 모델을 내려받아 GPU에 올리고 요청을 받는 서버를 띄워야 해요. TGI는 text-generation-launcher 하나로 이 과정을 묶어줘요. 모델 ID 하나만 주면 나머지는 서버가 처리하죠. 이 페이지는 launcher를 어떻게 띄우고, 어떤 옵션이 메모리·성능을 결정하는지를 공식 문서 기준으로 설명해요.
핵심 개념¶
모델 ID로 시작¶
launcher를 실행할 때 --model-id로 Hugging Face Hub의 모델 이름(예: gpt2, OpenAssistant/oasst-sft-1-pythia-12b)이나 로컬 디렉터리를 지정해요. 기본값은 bigscience/bloom-560m이에요. 문서는 도커 이미지로 띄우는 걸 기본 안내합니다.
model=meta-llama/Llama-3-8B-Instruct
volume=$PWD/data
docker run --gpus all \
--shm-size 1g \
-p 8080:80 \
-v $volume:/data \
ghcr.io/huggingface/text-generation-inference:latest \
--model-id $model
GPU 분산 — sharding¶
TGI는 기본적으로 머신의 모든 GPU를 사용해 모델을 나눠 올려요. --sharded true/false로 켜고 끄고, --num-shard로 쓸 GPU 수를 지정해요. 예를 들어 CUDA_VISIBLE_DEVICES=0,1로 GPU 두 개만 보이게 한 뒤 --num-shard 2로 그 둘에 나눕니다. GPU가 아닌 다른 하드웨어(Neuron, Gaudi, TensorRT-LLM)를 쓰는 백엔드도 있어요.
양자화 — --quantize¶
--quantize 옵션으로 모델을 양자화할지 정해요. 예를 들어 gptq는 4비트 양자화라, 특정 GPTQ 양자화 모델을 필요로 하고 가능하면 더 빠른 exllama 커널을 쓰고 지원이 안 되면 triton 커널로 대체해요. 문서는 AWQ가 더 빠른 커널을 가진다고 언급합니다.
메모리 예산 — max-total-tokens, max-batch-total-tokens¶
--max-total-tokens는 "한 요청이 쓸 메모리 예산"이에요. 프롬프트 길이 + 생성 토큰 수의 합을 제한하죠. 기본값은 min(max_position_embeddings, 4096)이에요. 값이 클수록 요청 하나가 메모리를 많이 차지해 배칭 효율이 떨어져요.
--max-batch-total-tokens는 배치 전체가 가질 수 있는 토큰 총량이에요. 공식 문서가 "하드웨어를 최대로 쓰기 위한 중요한 조절 장치"라고 강조하는 값이죠. 모델을 올리고 남은 메모리에 맞춰 최대한 크게 잡아요. 비패딩(flash attention) 방식에선 세밀하게 조절돼요.
그 외 자주 쓰는 옵션¶
--max-input-tokens(프롬프트 최대 길이), --max-concurrent-requests(동시 요청 한도·백프레셔), --port(기본 3000), --trust-remote-code(허브의 커스텀 모델 코드 실행 여부) 등이 있어요. 발표용 문서는 이들을 env 변수로도 받아요.
실제 적용 (데이터스케쳐스)¶
- HF 모델 배포 대안 — 자체 GPU 서빙을 검토할 때 TGI로 모델을 컨테이너로 띄워, 기존 Hugging Face 모델을 그대로 올려 사용하는 흐름을 봐요.
- 메모리 예산 튜닝 —
--max-total-tokens와--max-batch-total-tokens로 "한 요청당·배치당" 메모리를 잡아, GPU를 꽉 채우되 OOM이 안 나는 지점을 찾는 작업이 핵심이에요. - 대안 검증 — vLLM과 함께 비교 후보예요. 모델 규모·비용·운영 편의에 따라 둘 중 하나를 정해요.
정확한 sharding·메모리 설정값은 배포 GPU 사양에 달려 있어요. 우리 환경에서 모델을 올려보고 남는 메모리 기준으로 확정합니다.