Skip to content

TGI 추론 API (Inference API)

개요

TGI 서버를 띄우고 나면, 애플리케이션은 HTTP로 추론 결과를 받아가야 해요. TGI는 OpenAI 호환 Messages API와 비(非)챗용 /generate 계열 엔드포인트를 제공해서, 상황에 맞는 호출 방식을 고를 수 있어요. 이 페이지는 그 엔드포인트들을 어떻게 부르고, 스트리밍은 어떻게 받는지를 공식 문서 기준으로 설명합니다.

핵심 개념

Messages API — /v1/chat/completions

서버를 띄운 뒤 가장 표준적인 경로는 Messages API의 /v1/chat/completions예요. OpenAI Chat Completion 스펙과 호환되어, messages 배열을 그대로 보내고 choices 구조로 받아요. stream: true를 보내면 토큰 흐름(스트리밍)으로 돌아와요.

curl localhost:8080/v1/chat/completions \
  -X POST \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is deep learning?"}
    ],
    "stream": true,
    "max_tokens": 20
  }' \
  -H 'Content-Type: application/json'

비챗 엔드포인트 — /generate, /generate_stream

채팅 형식이 아닌 단순 완성(completion)엔 /generate를 써요. inputs에 프롬프트를 넣고 parameters에 max_new_tokens 같은 옵션을 담아요. /generate_stream은 같은 요청을 토큰 단위로 흘려보내요.

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

InferenceClient — 파라미터 검증이 되는 편의 클라이언트

Hugging Face의 huggingface_hub 라이브러리는 InferenceClient를 제공해요. OpenAI 클라이언트와 비슷하게 쓰되, 파라미터 검증까지 해주는 고수준 인터페이스예요. base_url만 TGI 서버 주소로 잡으면 됩니다.

from huggingface_hub import InferenceClient

client = InferenceClient(base_url="http://localhost:8080/v1/")
output = client.chat.completions.create(
    model="tgi",
    messages=[{"role": "user", "content": "Count to 10"}],
    stream=True,
    max_tokens=1024,
)

스트리밍이 동작하는 방식 — SSE

TGI의 스트리밍은 이벤트 스트림으로 첫 응답을 빨리 받는 방식이에요. 동작 원리를 보면, 클라이언트가 요청을 보내면서 HTTP 연결을 열고 Server-Sent Events(SSE)로 토큰 조각을 계속 구독하는 구조예요. 첫 토큰만 받아도 화면에 바로 보여줄 수 있죠. 높은 동시성을 다뤄야 하면 AsyncInferenceClient도 제공합니다.

실제 적용 (데이터스케쳐스)

  • 뉴런 생성 단계 후보 — OpenAI 호환 Messages API 덕분에, 기존 OpenAI SDK 기반 코드를 base_url만 바꿔 TGI 서버에 연결할 수 있어요.
  • 구조화·스트리밍 — 채팅형 제품이면 /v1/chat/completions + stream으로, 단순 완성 작업이면 /generate로 경로를 나눠 써요.
  • 검증 시점 — 실제 모델·엔드포인트 선택은 자체 GPU 서빙 계획이 구체화될 때 확정하고, 그 전엔 단정하지 않아요.

엔드포인트별 정확한 요청·응답 필드는 서버 버전에 따라 조금씩 달라질 수 있어요. 상세 스펙은 OpenAPI 문서에서 확인할 수 있어요.

더 알아보기