transformers serve 기본 — 서버 띄우고 호출하기

transformers serve 기본 — 서버 띄우고 호출하기

transformers serve는 로컬·셀프호스팅 서버를 위한 가벼운 옵션이에요. 연속 배칭 같은 기능으로 처리량을 높이고 지연 시간도 낮출 수 있습니다. 대규모 운영이 필요하면 vLLM이나 SGLang을 백엔드로 쓰는 쪽을 권장해요.

출처: https://huggingface.co/docs/transformers/en/serve-cli/serving

서버 시작

서빙 의존성을 설치하고 실행합니다. 기본 주소는 http://localhost:8000이에요.

pip install transformers[serving]

transformers serve

서버는 OpenAI SDK와 호환되고, 아래 REST API들을 지원해요.

  • /v1/chat/completions — 텍스트·이미지·오디오·비디오 요청
  • /v1/completions — 자유 형식 프롬프트의 레거시 텍스트 완성
  • /v1/responses — Responses API
  • /v1/audio/transcriptions — 오디오 전사
  • /v1/models — 서드파티 통합용 모델 목록
  • /load_model — SSE로 모델 로딩 진행 스트리밍

chat/completions 호출하기

curl·InferenceClient·OpenAI 클라이언트 어느 쪽이든 쓸 수 있어요. InferenceClient 예시입니다.

from huggingface_hub import InferenceClient

messages = [{"role": "user", "content": "What is the Transformers library known for?"}]
client = InferenceClient("http://localhost:8000")

result = client.chat_completion(messages, model="Qwen/Qwen2.5-0.5B-Instruct", max_tokens=256)

curl로는 이렇게 요청합니다.

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [{"role": "user", "content": "What is the Transformers library known for?"}],
    "temperature": 0.9,
    "max_tokens": 256
  }'

이미지·오디오·비디오 입력도 image_url, audio_url, video_url 콘텐츠 타입으로 지원돼요. 비디오의 경우 모델이 오디오를 지원하면(Gemma 4, Qwen2.5-Omni 등) 서버가 비디오에서 오디오 트랙을 뽑아 시각 프레임과 함께 처리합니다.

다중 턴 대화

OpenAI 호환 서버는 무상태(stateless)라 모든 요청에 전체 대화 히스토리를 담아야 해요. messages 리스트에 user와 assistant 역할을 번갈아 넣어 완전한 기록을 보내면 됩니다.

v1/models와 /load_model

/v1/models는 로컬 Hugging Face 캐시를 스캔해 내려받은 모델 목록을 OpenAI 형식으로 돌려줘요. 서버 실행 전에 모델을 미리 내려받아 두면 좋습니다.

transformers download Qwen/Qwen2.5-0.5B-Instruct

/load_model은 모델을 미리 로딩하고 SSE로 진행 상황을 스트리밍합니다. model 필드는 @revision 접미사를 붙일 수 있고, 생략하면 main 리비전이 기본이에요.

curl -N -X POST http://localhost:8000/load_model \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen2.5-0.5B-Instruct"}'

타임아웃과 도구 호출

모델은 요청이 들어올 때 로드돼 GPU 메모리에 머물다가, 300초(기본) 활동이 없으면 자동으로 내려갑니다. --model-timeout으로 조절하거나 -1로 비활성화할 수 있어요. 또 OpenAI 스타일 함수 호출도 지원하는데, 토크나이저가 도구 호출 토큰을 선언한 모델이라면 됩니다(Qwen, Gemma 4 등은 기본 지원).

transformers serve --model-timeout 400

더 알아보기