Hugging Face Inference Endpoints — vLLM 배포

Hugging Face Inference Endpoints — vLLM 배포

vLLM과 호환되는 모델은 Hugging Face Inference Endpoints에 배포할 수 있습니다. Hugging Face Hub에서 직접 시작하거나 Inference Endpoints 인터페이스에서 바로 시작할 수 있습니다. 이를 통해 GPU 가속, 자동 스케일링, 모니터링이 포함된 완전 관리형 환경에서 모델을 서빙하고, 인프라를 수동으로 관리하지 않아도 됩니다.

출처: 문서

본문

배포 방법

세 가지 방법이 있습니다.

  • 방법 1: 카탈로그에서 배포 — 준비된 최적화 설정으로 Hugging Face Hub의 모델을 원클릭 배포.
  • 방법 2: 가이드 배포(Transformers 모델) — Hub UI에서 transformers 태그가 달린 모델을 Deploy 버튼으로 즉시 배포.
  • 방법 3: 수동 배포(고급 모델) — transformers 태그와 커스텀 코드를 쓰거나, 표준 transformers로는 안 돌지만 vLLM이 지원하는 모델용. 수동 설정 필요.

방법 1: 카탈로그에서 배포

Inference Endpoints에서 vLLM을 시작하는 가장 쉬운 방법입니다. 검증되고 최적화된 배포 설정이 있는 모델 카탈로그를 둘러볼 수 있습니다.

  • Endpoints Catalog로 이동해 Inference Server 옵션에서 vLLM 선택 → 최적화된 사전 설정이 있는 모델 목록 표시.
  • 원하는 모델을 선택하고 Create Endpoint 클릭.
  • 배포가 완료되면 콘솔에서 받은 URL로 DEPLOYMENT_URL을 업데이트하고, 필요에 따라 /v1을 덧붙입니다.
# pip install openai
from openai import OpenAI
import os

client = OpenAI(
    base_url=DEPLOYMENT_URL,
    api_key=os.environ["HF_TOKEN"],  # https://huggingface.co/settings/tokens
)

chat_completion = client.chat.completions.create(
    model="HuggingFaceTB/SmolLM3-3B",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Give me a brief explanation of gravity in simple terms.",
                }
            ],
        }
    ],
    stream=True,
)

for message in chat_completion:
    print(message.choices[0].delta.content, end="")

참고: 카탈로그에는 vLLM에 최적화된 모델(GPU 설정, 추론 엔진 구성 포함)이 제공됩니다. Inference Endpoints UI에서 엔드포인트를 모니터링하고 컨테이너나 구성을 업데이트할 수 있습니다.

방법 2: 가이드 배포(Transformers 모델)

메타데이터에 transformers 라이브러리 태그가 있는 모델에 적용됩니다. 수동 설정 없이 Hub UI에서 바로 배포할 수 있습니다.

  • Hub에서 모델로 이동합니다(예: ibm-granite/granite-docling-258M). README의 front matter에 library: transformers로 태그되어 있는지 확인해 호환성을 검증합니다.
  • 모델 카드 오른쪽 위에 있는 Deploy 버튼을 찾습니다(transformers 태그가 있는 모델에 표시).
  • Deploy 버튼 > HF Inference Endpoints 클릭 → 배포 구성 화면으로 이동.
  • 하드웨어(예: AWS>GPU>T4)와 Container Configuration을 선택하고, 컨테이너 타입으로 vLLM을 선택한 뒤 Create Endpoint로 마무리합니다.
  • 배포된 엔드포인트의 DEPLOYMENT_URL을 콘솔의 URL(필요한 /v1 추가)로 업데이트하고, 프로그래매틱 또는 SDK로 사용합니다.
# pip install openai
from openai import OpenAI
import os

client = OpenAI(
    base_url=DEPLOYMENT_URL,
    api_key=os.environ["HF_TOKEN"],
)

chat_completion = client.chat.completions.create(
    model="ibm-granite/granite-docling-258M",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://huggingface.co/ibm-granite/granite-docling-258M/resolve/main/assets/new_arxiv.png",
                    },
                },
                {
                    "type": "text",
                    "text": "Convert this page to docling.",
                },
            ]
        }
    ],
    stream=True,
)

for message in chat_completion:
    print(message.choices[0].delta.content, end="")

참고: 이 방법은 best-guess 기본값을 사용하므로, 특정 요구 사항에 맞춰 구성을 조정해야 할 수 있습니다.

방법 3: 수동 배포(고급 모델)

다음처럼 커스텀 코드를 transformers 태그로 쓰거나, 표준 transformers로는 안 돌지만 vLLM이 지원하는 모델은 수동 배포가 필요하며, Deploy 버튼으로는 배포할 수 없습니다. 예시로 vLLM에 통합된 OCR 모델 rednote-hilab/dots.ocr로 진행합니다.

  • Inference Endpoints에서 New 클릭으로 새 배포 시작.
  • Hub에서 모델 검색.
  • 구성 페이지에서 클라우드 프로바이더와 하드웨어 선택(예: AWS + L4 GPU).
  • Container Configuration으로 스크롤해 컨테이너 타입 vLLM 선택.
  • Create Endpoint 클릭.

배포가 준비되면 OpenAI Completion API, cURL 또는 기타 SDK로 사용할 수 있습니다. 필요하면 배포 URL에 /v1을 덧붙이세요.

참고: Inference Endpoints UI에서 컨테이너 설정(Container URI, Container Arguments)을 바꾸고 Update Endpoint를 누르면, 업데이트된 구성으로 재배포됩니다. 모델 자체의 변경은 새 엔드포인트를 만들거나 다른 모델로 재배포해야 합니다. 예를 들어 이 데모에서는 Container URI를 nightly 이미지(vllm/vllm-openai:nightly)로 바꾸고 컨테이너 인자에 --trust-remote-code 플래그를 추가해야 할 수 있습니다.

고급 배포 세부사항

transformers 백엔드 통합 덕분에 vLLM은 transformers와 호환되는 모든 모델에 Day 0 지원을 제공합니다. 서버를 구성하거나 의존성을 설치하거나 클러스터를 관리할 필요 없이, 완전 관리형 환경에서 즉시 배포할 수 있습니다. AWS, Azure, GCP 등 여러 클라우드 프로바이더에 걸쳐 배포를 지원하며, Hugging Face Hub와 원활히 통합되어 모델 배포·사용량 추적·추론 엔진 업데이트를 하나의 플랫폼에서 처리할 수 있습니다.

더 알아보기 (Learn more)