VLLM

VLLM (vLLM)

LiteLLM에서 vLLM의 모든 모델을 사용하는 방법을 알아봐요. OpenAI 호환 서버와 vLLM SDK 사용법을 모두 지원해요.

출처: 문서

본문

LiteLLM은 VLLM의 모든 모델을 지원해요.

속성	내용
설명	vLLM은 LLM 추론과 서빙을 위한 빠르고 사용하기 쉬운 라이브러리
LiteLLM 라우트	hosted_vllm/ (OpenAI 호환 서버용), vllm/ ([사용 중단] vLLM SDK 사용용)
공식 문서	vLLM ↗
지원 엔드포인트	/chat/completions, /embeddings, /completions, /rerank, /audio/transcriptions

빠른 시작

사용법 - litellm.completion (OpenAI 호환 엔드포인트 호출)

vLLM은 OpenAI 호환 엔드포인트를 제공해요. LiteLLM으로 호출하는 방법은 다음과 같아요.

호스팅된 vllm 서버를 litellm으로 호출하려면 completion 호출에 다음을 추가하세요:

• model="hosted_vllm/"
• api_base = "your-hosted-vllm-server"

import litellm

response = litellm.completion(
            model="hosted_vllm/facebook/opt-125m", # pass the vllm model name
            messages=messages,
            api_base="https://hosted-vllm-api.co",
            temperature=0.2,
            max_tokens=80)

print(response)

사용법 - LiteLLM Proxy 서버 (OpenAI 호환 엔드포인트 호출)

config.yaml 수정:

model_list:
  - model_name: my-model
    litellm_params:
      model: hosted_vllm/facebook/opt-125m  # add hosted_vllm/ prefix to route as OpenAI provider
      api_base: https://hosted-vllm-api.co      # add api base for OpenAI compatible provider

Proxy 시작:

$ litellm --config /path/to/config.yaml

OpenAI Python SDK로 요청:

import openai
client = openai.OpenAI(
    api_key="sk-",             # pass litellm proxy key, if you're using virtual keys
    base_url="http://0.0.0.0:4000" # litellm-proxy-base url
)

response = client.chat.completions.create(
    model="my-model",
    messages = [
        {
            "role": "user",
            "content": "what llm are you"
        }
    ],
)

print(response)

curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "my-model",
    "messages": [
        {
        "role": "user",
        "content": "what llm are you"
        }
    ],
}'

Reasoning Effort

from litellm import completion

response = completion(
    model="hosted_vllm/gpt-oss-120b",
    messages=[{"role": "user", "content": "whats 2 + 2"}],
    reasoning_effort="high",
    api_base="https://hosted-vllm-api.co",
)
print(response)

config.yaml:

model_list:
  - model_name: gpt-oss-120b
    litellm_params:
      model: hosted_vllm/gpt-oss-120b
      api_base: https://hosted-vllm-api.co

Proxy 시작:

litellm --config /path/to/config.yaml

테스트:

curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-oss-120b", "messages": [{"role": "user", "content": "whats 2 + 2"}], "reasoning_effort": "high"}'

임베딩

vLLM은 OpenAI 호환 /v1/embeddings를 제공해요. 클라이언트가 encoding_format을 생략하면 LiteLLM이 OpenAI 호환 임베딩 라우팅을 위한 기본값을 설정해요(요청 → 모델 litellm_params → LITELLM_DEFAULT_EMBEDDING_ENCODING_FORMAT → float).

from litellm import embedding
import os

os.environ["HOSTED_VLLM_API_BASE"] = "http://localhost:8000"

embedding = embedding(model="hosted_vllm/facebook/opt-125m", input=["Hello world"])

print(embedding)

config.yaml:

model_list:
    - model_name: my-model
      litellm_params:
        model: hosted_vllm/facebook/opt-125m  # add hosted_vllm/ prefix to route as OpenAI provider
        api_base: https://hosted-vllm-api.co      # add api base for OpenAI compatible provider

Proxy 시작:

$ litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

테스트:

curl -L -X POST 'http://0.0.0.0:4000/embeddings' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{"input": ["hello world"], "model": "my-model"}'

리랭크

from litellm import rerank
import os

os.environ["HOSTED_VLLM_API_BASE"] = "http://localhost:8000"
os.environ["HOSTED_VLLM_API_KEY"] = ""  # [optional], if your VLLM server requires an API key

query = "What is the capital of the United States?"
documents = [
    "Carson City is the capital city of the American state of Nevada.",
    "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
    "Washington, D.C. is the capital of the United States.",
    "Capital punishment has existed in the United States since before it was a country.",
]

response = rerank(
    model="hosted_vllm/your-rerank-model",
    query=query,
    documents=documents,
    top_n=3,
)
print(response)

비동기 사용법

from litellm import arerank
import os, asyncio

os.environ["HOSTED_VLLM_API_BASE"] = "http://localhost:8000"
os.environ["HOSTED_VLLM_API_KEY"] = ""  # [optional], if your VLLM server requires an API key

async def test_async_rerank():
    query = "What is the capital of the United States?"
    documents = [
        "Carson City is the capital city of the American state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
        "Washington, D.C. is the capital of the United States.",
        "Capital punishment has existed in the United States since before it was a country.",
    ]

    response = await arerank(
        model="hosted_vllm/your-rerank-model",
        query=query,
        documents=documents,
        top_n=3,
    )
    print(response)

asyncio.run(test_async_rerank())

config.yaml:

model_list:
    - model_name: my-rerank-model
      litellm_params:
        model: hosted_vllm/your-rerank-model  # add hosted_vllm/ prefix to route as VLLM provider
        api_base: http://localhost:8000      # add api base for your VLLM server
        # api_key: your-api-key             # [optional] if your VLLM server requires authentication

Proxy 시작:

$ litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

테스트:

curl -L -X POST 'http://0.0.0.0:4000/rerank' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{
    "model": "my-rerank-model",
    "query": "What is the capital of the United States?",
    "documents": [
        "Carson City is the capital city of the American state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
        "Washington, D.C. is the capital of the United States.",
        "Capital punishment has existed in the United States since before it was a country."
    ],
    "top_n": 3
}'

긴 문서 잘라내기

vLLM의 /rerank 엔드포인트는 자체 잘라내기 제어를 받으며, LiteLLM은 설정 시 hosted_vllm 리랭크 모델로 전달해요. 이 중 하나가 없으면 리랭커의 컨텍스트 윈도우보다 긴 문서는 컨텍스트 길이 오류로 실패해요.

파라미터	타입	설명
truncate_prompt_tokens	integer	각 쿼리와 문서 쌍을 스코어링 전에 이 토큰 수로 자르기
truncation_side	left 또는 right	입력의 어느 끝을 잘라낼지
max_tokens_per_doc	integer	각 문서를 이 토큰 수로 제한
max_tokens_per_query	integer	쿼리를 이 토큰 수로 제한

truncation_side: "middle" 같은 유효하지 않은 값은 vLLM에 아무것도 보내기 전에 400이 반환돼요.

from litellm import rerank

response = rerank(
    model="hosted_vllm/your-rerank-model",
    query="What is the capital of the United States?",
    documents=[""],
    truncate_prompt_tokens=512,
    truncation_side="left",
)
print(response)

이미지 편집

vLLM-Omni는 Qwen/Qwen-Image-Edit-2511 같은 이미지 편집 모델용 OpenAI 호환 /v1/images/edits를 제공해요. hosted_vllm/ 접두사를 사용하고 api_base를 vLLM-Omni 서버로 지정해요. seed, negative_prompt 같은 추가 제공사 필드는 폼 필드로 전달돼요. vLLM-Omni에는 quality나 input_fidelity 폼 필드가 없고 마스크를 OpenAI의 mask 파일이 아닌 mask_image(URL 문자열)로 받으므로, LiteLLM은 drop_params: true가 설정되어 있지 않으면 hosted_vllm/ 모델의 mask, quality, input_fidelity를 거부하며, 설정 시 요청 전에 삭제해요. 편집을 마스킹하려면 mask_image를 마스크의 URL과 함께 추가 필드로 전달해요.

from litellm import image_edit
import os

os.environ["HOSTED_VLLM_API_BASE"] = "http://localhost:8091"

response = image_edit(
    model="hosted_vllm/Qwen/Qwen-Image-Edit-2511",
    image=open("original_image.png", "rb"),
    prompt="Add a red hat to the person in the image",
)

print(response)

config.yaml:

model_list:
    - model_name: qwen-image-edit
      litellm_params:
        model: hosted_vllm/Qwen/Qwen-Image-Edit-2511  # add hosted_vllm/ prefix to route as OpenAI provider
        api_base: http://localhost:8091              # your vLLM-Omni server
      model_info:
        mode: image_edit

Proxy 시작:

$ litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

테스트:

curl -X POST 'http://0.0.0.0:4000/v1/images/edits' \
-H "Authorization: Bearer ***" \
-F 'model=qwen-image-edit' \
-F 'image=@original_image.png' \
-F 'prompt=Add a red hat to the person in the image'

VLLM에 비디오 URL 보내기

OpenAI의 files 메시지 타입을 사용해 같은 형식으로 VLLM + Gemini에 비디오 URL을 보낼 수 있어요. VLLM에 비디오 URL을 보내는 두 가지 방법이 있어요:

• 비디오 URL 직접 전달: {"type": "file", "file": {"file_id": video_url}}
• 비디오 데이터를 base64로 전달: {"type": "file", "file": {"file_data": f"data:video/mp4;base64,{video_data_base64}"}}

from litellm import completion

messages=[
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Summarize the following video"
            },
            {
                "type": "file",
                "file": {
                    "file_id": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
                }
            }
        ]
    }
]

# call vllm
os.environ["HOSTED_VLLM_API_BASE"] = "https://hosted-vllm-api.co"
os.environ["HOSTED_VLLM_API_KEY"] = "" # [optional], if your VLLM server requires an API key
response = completion(
    model="hosted_vllm/qwen", # pass the vllm model name
    messages=messages,
)

# call gemini
os.environ["GEMINI_API_KEY"] = "your-gemini-api-key"
response = completion(
    model="gemini/gemini-3.8-flash", # pass the gemini model name
    messages=messages,
)

print(response)

config.yaml:

model_list:
    - model_name: my-model
      litellm_params:
        model: hosted_vllm/qwen  # add hosted_vllm/ prefix to route as OpenAI provider
        api_base: https://hosted-vllm-api.co      # add api base for OpenAI compatible provider
    - model_name: my-gemini-model
      litellm_params:
        model: gemini/gemini-3.8-flash  # add gemini/ prefix to route as Google AI Studio provider
        api_key: os.environ/GEMINI_API_KEY

테스트:

curl -X POST http://0.0.0.0:4000/chat/completions \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{
    "model": "my-model",
    "messages": [
        {"role": "user", "content":
            [
                {"type": "text", "text": "Summarize the following video"},
                {"type": "file", "file": {"file_id": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}}
            ]
        }
    ]
}'

VLLM의 네이티브 메시지 형식(video_url)으로 비디오 URL을 보낼 수도 있어요. 두 가지 방법:

• 비디오 URL 직접 전달: {"type": "video_url", "video_url": {"url": video_url}}
• 비디오 데이터를 base64로 전달: {"type": "video_url", "video_url": {"url": f"data:video/mp4;base64,{video_data_base64}"}}

from litellm import completion

response = completion(
            model="hosted_vllm/qwen", # pass the vllm model name
            messages=[
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "text",
                            "text": "Summarize the following video"
                        },
                        {
                            "type": "video_url",
                            "video_url": {
                                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
                            }
                        }
                    ]
                }
            ],
            api_base="https://hosted-vllm-api.co")

print(response)

(사용 중단) 패키지형 vllm 설치용

litellm.completion 사용

uv add litellm vllm

import litellm

response = litellm.completion(
            model="vllm/facebook/opt-125m", # add a vllm prefix so litellm knows the custom_llm_provider==vllm
            messages=messages,
            temperature=0.2,
            max_tokens=80)

print(response)

배치 완성

from litellm import batch_completion

model_name = "facebook/opt-125m"
provider = "vllm"
messages = [[{"role": "user", "content": "Hey, how's it going"}] for _ in range(5)]

response_list = batch_completion(
            model=model_name,
            custom_llm_provider=provider, # can easily switch to huggingface, replicate, together ai, sagemaker, etc.
            messages=messages,
            temperature=0.2,
            max_tokens=80,
        )
print(response_list)

프롬프트 템플릿

특수 프롬프트 템플릿이 있는 모델(예: Llama2)은 해당 템플릿에 맞게 프롬프트를 포맷해요.

아직 지원하지 않는 모델이 있다면 사용자 정의 프롬프트 포맷팅을 지정할 수 있어요. 기본적으로 메시지 콘텐츠를 연결해 프롬프트를 만듦니다(Bloom, T-5, Llama-2 base 모델 등에 기대되는 형식).

기본 프롬프트 템플릿:

def default_pt(messages):
    return " ".join(message["content"] for message in messages)

이미 프롬프트 템플릿이 있는 모델:

모델명	적용 모델	함수 호출
meta-llama/Llama-2-7b-chat	모든 meta-llama llama2 chat 모델	completion(model='vllm/meta-llama/Llama-2-7b', messages=messages, api_base="your_api_endpoint")
tiiuae/falcon-7b-instruct	모든 falcon instruct 모델	completion(model='vllm/tiiuae/falcon-7b-instruct', messages=messages, api_base="your_api_endpoint")
mosaicml/mpt-7b-chat	모든 mpt chat 모델	completion(model='vllm/mosaicml/mpt-7b-chat', messages=messages, api_base="your_api_endpoint")
codellama/CodeLlama-34b-Instruct-hf	모든 codellama instruct 모델	completion(model='vllm/codellama/CodeLlama-34b-Instruct-hf', messages=messages, api_base="your_api_endpoint")
WizardLM/WizardCoder-Python-34B-V1.0	모든 wizardcoder 모델	completion(model='vllm/WizardLM/WizardCoder-Python-34B-V1.0', messages=messages, api_base="your_api_endpoint")
Phind/Phind-CodeLlama-34B-v2	모든 phind-codellama 모델	completion(model='vllm/Phind/Phind-CodeLlama-34B-v2', messages=messages, api_base="your_api_endpoint")

사용자 정의 프롬프트 템플릿:

# Create your own custom prompt template works
litellm.register_prompt_template(
	model="togethercomputer/LLaMA-2-7B-32K",
	roles={
            "system": {
                "pre_message": "[INST] >\n",
                "post_message": "\n>\n [/INST]\n"
            },
            "user": {
                "pre_message": "[INST] ",
                "post_message": " [/INST]\n"
            },
            "assistant": {
                "pre_message": "\n",
                "post_message": "\n",
            }
        } # tell LiteLLM how you want to map the openai messages to this model
)

def test_vllm_custom_model():
    model = "vllm/togethercomputer/LLaMA-2-7B-32K"
    response = completion(model=model, messages=messages)
    print(response['choices'][0]['message']['content'])
    return response

test_vllm_custom_model()

더 알아보기 (Learn more)

• vLLM 공식 문서
• LiteLLM 임베딩 문서