Awesome

OpenAI-Compatible vLLM Serverless Endpoint Worker

Deploy OpenAI-Compatible Blazing-Fast LLM Endpoints powered by the vLLM Inference Engine on RunPod Serverless with just a few clicks.

News:

1. UI for Deploying vLLM Worker on RunPod console:

2. Worker vLLM v1.7.0 with vLLM 0.6.3 now available under stable tags

Update v1.7.0 is now available, use the image tag runpod/worker-v1-vllm:v1.7.0stable-cuda12.1.0.

3. OpenAI-Compatible Embedding Worker Released

Deploy your own OpenAI-compatible Serverless Endpoint on RunPod with multiple embedding models and fast inference for RAG and more!

4. Caching Accross RunPod Machines

Worker vLLM is now cached on all RunPod machines, resulting in near-instant deployment! Previously, downloading and extracting the image took 3-5 minutes on average.

Table of Contents

• Setting up the Serverless Worker
  • Option 1: Deploy Any Model Using Pre-Built Docker Image [RECOMMENDED]
    • Prerequisites
    • Environment Variables
      • LLM Settings
      • Tokenizer Settings
      • Tensor Parallelism (Multi-GPU) Settings
      • System Settings
      • Streaming Batch Size
      • OpenAI Settings
      • Serverless Settings
  • Option 2: Build Docker Image with Model Inside
    • Prerequisites
    • Arguments
    • Example: Building an image with OpenChat-3.5
      • (Optional) Including Huggingface Token
  • Compatible Model Architectures
• Usage: OpenAI Compatibility
  • Modifying your OpenAI Codebase to use your deployed vLLM Worker
  • OpenAI Request Input Parameters
    • Chat Completions
  • Examples: Using your RunPod endpoint with OpenAI
• Usage: standard
  • Input Request Parameters
    • Text Input Formats
    • Sampling Parameters
• Worker Config
  • Writing your worker-config.json
  • Example of schema
  • Example of versions

Setting up the Serverless Worker

Option 1: Deploy Any Model Using Pre-Built Docker Image [Recommended]

[!NOTE] You can now deploy from the dedicated UI on the RunPod console with all of the settings and choices listed. Try now by accessing in Explore or Serverless pages on the RunPod console!

We now offer a pre-built Docker Image for the vLLM Worker that you can configure entirely with Environment Variables when creating the RunPod Serverless Endpoint:

RunPod Worker Images

Below is a summary of the available RunPod Worker images, categorized by image stability and CUDA version compatibility.

Prerequisites

• RunPod Account

Environment Variables/Settings

Note: 0 is equivalent to False and 1 is equivalent to True for boolean as int values.

[!TIP] If you are facing issues when using Mixtral 8x7B, Quantized models, or handling unusual models/architectures, try setting TRUST_REMOTE_CODE to 1.

Option 2: Build Docker Image with Model Inside

To build an image with the model baked in, you must specify the following docker arguments when building the image.

Prerequisites

• RunPod Account
• Docker

Arguments:

• Required
  • MODEL_NAME
• Optional
  • MODEL_REVISION: Model revision to load (default: main).
  • BASE_PATH: Storage directory where huggingface cache and model will be located. (default: /runpod-volume, which will utilize network storage if you attach it or create a local directory within the image if you don't. If your intention is to bake the model into the image, you should set this to something like /models to make sure there are no issues if you were to accidentally attach network storage.)
  • QUANTIZATION
  • WORKER_CUDA_VERSION: 12.1.0 (12.1.0 is recommended for optimal performance).
  • TOKENIZER_NAME: Tokenizer repository if you would like to use a different tokenizer than the one that comes with the model. (default: None, which uses the model's tokenizer)
  • TOKENIZER_REVISION: Tokenizer revision to load (default: main).

For the remaining settings, you may apply them as environment variables when running the container. Supported environment variables are listed in the Environment Variables section.

Example: Building an image with OpenChat-3.5

sudo docker build -t username/image:tag --build-arg MODEL_NAME="openchat/openchat_3.5" --build-arg BASE_PATH="/models" .

(Optional) Including Huggingface Token

If the model you would like to deploy is private or gated, you will need to include it during build time as a Docker secret, which will protect it from being exposed in the image and on DockerHub.

1. Enable Docker BuildKit (required for secrets).

export DOCKER_BUILDKIT=1

2. Export your Hugging Face token as an environment variable

export HF_TOKEN="your_token_here"

2. Add the token as a secret when building

docker build -t username/image:tag --secret id=HF_TOKEN --build-arg MODEL_NAME="openchat/openchat_3.5" .

Compatible Model Architectures

Below are all supported model architectures (and examples of each) that you can deploy using the vLLM Worker. You can deploy any model on HuggingFace, as long as its base architecture is one of the following:

• Aquila & Aquila2 (BAAI/AquilaChat2-7B, BAAI/AquilaChat2-34B, BAAI/Aquila-7B, BAAI/AquilaChat-7B, etc.)
• Baichuan & Baichuan2 (baichuan-inc/Baichuan2-13B-Chat, baichuan-inc/Baichuan-7B, etc.)
• BLOOM (bigscience/bloom, bigscience/bloomz, etc.)
• ChatGLM (THUDM/chatglm2-6b, THUDM/chatglm3-6b, etc.)
• Command-R (CohereForAI/c4ai-command-r-v01, etc.)
• DBRX (databricks/dbrx-base, databricks/dbrx-instruct etc.)
• DeciLM (Deci/DeciLM-7B, Deci/DeciLM-7B-instruct, etc.)
• Falcon (tiiuae/falcon-7b, tiiuae/falcon-40b, tiiuae/falcon-rw-7b, etc.)
• Gemma (google/gemma-2b, google/gemma-7b, etc.)
• GPT-2 (gpt2, gpt2-xl, etc.)
• GPT BigCode (bigcode/starcoder, bigcode/gpt_bigcode-santacoder, etc.)
• GPT-J (EleutherAI/gpt-j-6b, nomic-ai/gpt4all-j, etc.)
• GPT-NeoX (EleutherAI/gpt-neox-20b, databricks/dolly-v2-12b, stabilityai/stablelm-tuned-alpha-7b, etc.)
• InternLM (internlm/internlm-7b, internlm/internlm-chat-7b, etc.)
• InternLM2 (internlm/internlm2-7b, internlm/internlm2-chat-7b, etc.)
• Jais (core42/jais-13b, core42/jais-13b-chat, core42/jais-30b-v3, core42/jais-30b-chat-v3, etc.)
• LLaMA, Llama 2, and Meta Llama 3 (meta-llama/Meta-Llama-3-8B-Instruct, meta-llama/Meta-Llama-3-70B-Instruct, meta-llama/Llama-2-70b-hf, lmsys/vicuna-13b-v1.3, young-geng/koala, openlm-research/open_llama_13b, etc.)
• MiniCPM (openbmb/MiniCPM-2B-sft-bf16, openbmb/MiniCPM-2B-dpo-bf16, etc.)
• Mistral (mistralai/Mistral-7B-v0.1, mistralai/Mistral-7B-Instruct-v0.1, etc.)
• Mixtral (mistralai/Mixtral-8x7B-v0.1, mistralai/Mixtral-8x7B-Instruct-v0.1, mistral-community/Mixtral-8x22B-v0.1, etc.)
• MPT (mosaicml/mpt-7b, mosaicml/mpt-30b, etc.)
• OLMo (allenai/OLMo-1B-hf, allenai/OLMo-7B-hf, etc.)
• OPT (facebook/opt-66b, facebook/opt-iml-max-30b, etc.)
• Orion (OrionStarAI/Orion-14B-Base, OrionStarAI/Orion-14B-Chat, etc.)
• Phi (microsoft/phi-1_5, microsoft/phi-2, etc.)
• Phi-3 (microsoft/Phi-3-mini-4k-instruct, microsoft/Phi-3-mini-128k-instruct, etc.)
• Qwen (Qwen/Qwen-7B, Qwen/Qwen-7B-Chat, etc.)
• Qwen2 (Qwen/Qwen1.5-7B, Qwen/Qwen1.5-7B-Chat, etc.)
• Qwen2MoE (Qwen/Qwen1.5-MoE-A2.7B, Qwen/Qwen1.5-MoE-A2.7B-Chat, etc.)
• StableLM(stabilityai/stablelm-3b-4e1t, stabilityai/stablelm-base-alpha-7b-v2, etc.)
• Starcoder2(bigcode/starcoder2-3b, bigcode/starcoder2-7b, bigcode/starcoder2-15b, etc.)
• Xverse (xverse/XVERSE-7B-Chat, xverse/XVERSE-13B-Chat, xverse/XVERSE-65B-Chat, etc.)
• Yi (01-ai/Yi-6B, 01-ai/Yi-34B, etc.)

Usage: OpenAI Compatibility

The vLLM Worker is fully compatible with OpenAI's API, and you can use it with any OpenAI Codebase by changing only 3 lines in total. The supported routes are <ins>Chat Completions</ins> and <ins>Models</ins> - with both streaming and non-streaming.

Modifying your OpenAI Codebase to use your deployed vLLM Worker

Python (similar to Node.js, etc.):

1. When initializing the OpenAI Client in your code, change the api_key to your RunPod API Key and the base_url to your RunPod Serverless Endpoint URL in the following format: https://api.runpod.ai/v2/<YOUR ENDPOINT ID>/openai/v1, filling in your deployed endpoint ID. For example, if your Endpoint ID is abc1234, the URL would be https://api.runpod.ai/v2/abc1234/openai/v1.

   • Before:

   from openai import OpenAI
   
   client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
   

   • After:

   from openai import OpenAI
   
   client = OpenAI(
       api_key=os.environ.get("RUNPOD_API_KEY"),
       base_url="https://api.runpod.ai/v2/<YOUR ENDPOINT ID>/openai/v1",
   )
   

2. Change the model parameter to your deployed model's name whenever using Completions or Chat Completions.

   • Before:

   response = client.chat.completions.create(
       model="gpt-3.5-turbo",
       messages=[{"role": "user", "content": "Why is RunPod the best platform?"}],
       temperature=0,
       max_tokens=100,
   )
   

   • After:

   response = client.chat.completions.create(
       model="<YOUR DEPLOYED MODEL REPO/NAME>",
       messages=[{"role": "user", "content": "Why is RunPod the best platform?"}],
       temperature=0,
       max_tokens=100,
   )
   

Using http requests:

1. Change the Authorization header to your RunPod API Key and the url to your RunPod Serverless Endpoint URL in the following format: https://api.runpod.ai/v2/<YOUR ENDPOINT ID>/openai/v1
   • Before:

   curl https://api.openai.com/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
   "model": "gpt-4",
   "messages": [
     {
       "role": "user",
       "content": "Why is RunPod the best platform?"
     }
   ],
   "temperature": 0,
   "max_tokens": 100
   }'
   

   • After:

   curl https://api.runpod.ai/v2/<YOUR ENDPOINT ID>/openai/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <YOUR OPENAI API KEY>" \
   -d '{
   "model": "<YOUR DEPLOYED MODEL REPO/NAME>",
   "messages": [
     {
       "role": "user",
       "content": "Why is RunPod the best platform?"
     }
   ],
   "temperature": 0,
   "max_tokens": 100
   }'
   

OpenAI Request Input Parameters:

When using the chat completion feature of the vLLM Serverless Endpoint Worker, you can customize your requests with the following parameters:

Chat Completions [RECOMMENDED]

Examples: Using your RunPod endpoint with OpenAI

First, initialize the OpenAI Client with your RunPod API Key and Endpoint URL:

from openai import OpenAI
import os

# Initialize the OpenAI Client with your RunPod API Key and Endpoint URL
client = OpenAI(
    api_key=os.environ.get("RUNPOD_API_KEY"),
    base_url="https://api.runpod.ai/v2/<YOUR ENDPOINT ID>/openai/v1",
)

Chat Completions:

This is the format used for GPT-4 and focused on instruction-following and chat. Examples of Open Source chat/instruct models include meta-llama/Llama-2-7b-chat-hf, mistralai/Mixtral-8x7B-Instruct-v0.1, openchat/openchat-3.5-0106, NousResearch/Nous-Hermes-2-Mistral-7B-DPO and more. However, if your model is a completion-style model with no chat/instruct fine-tune and/or does not have a chat template, you can still use this if you provide a chat template with the environment variable CUSTOM_CHAT_TEMPLATE.

• Streaming:

  # Create a chat completion stream
  response_stream = client.chat.completions.create(
      model="<YOUR DEPLOYED MODEL REPO/NAME>",
      messages=[{"role": "user", "content": "Why is RunPod the best platform?"}],
      temperature=0,
      max_tokens=100,
      stream=True,
  )
  # Stream the response
  for response in response_stream:
      print(chunk.choices[0].delta.content or "", end="", flush=True)
  

• Non-Streaming:

  # Create a chat completion
  response = client.chat.completions.create(
      model="<YOUR DEPLOYED MODEL REPO/NAME>",
      messages=[{"role": "user", "content": "Why is RunPod the best platform?"}],
      temperature=0,
      max_tokens=100,
  )
  # Print the response
  print(response.choices[0].message.content)
  

Getting a list of names for available models:

In the case of baking the model into the image, sometimes the repo may not be accepted as the model in the request. In this case, you can list the available models as shown below and use that name.

models_response = client.models.list()
list_of_models = [model.id for model in models_response]
print(list_of_models)

Usage: Standard (Non-OpenAI)

Request Input Parameters

You may either use a prompt or a list of messages as input. If you use messages, the model's chat template will be applied to the messages automatically, so the model must have one. If you use prompt, you may optionally apply the model's chat template to the prompt by setting apply_chat_template to true.

Sampling Parameters

Below are all available sampling parameters that you can specify in the sampling_params dictionary. If you do not specify any of these parameters, the default values will be used.

Text Input Formats

You may either use a prompt or a list of messages as input.

1. prompt The prompt string can be any string, and the model's chat template will not be applied to it unless apply_chat_template is set to true, in which case it will be treated as a user message.

   Example:

   "prompt": "..."
   

2. messages Your list can contain any number of messages, and each message usually can have any role from the following list:

   • user
   • assistant
   • system

   However, some models may have different roles, so you should check the model's chat template to see which roles are required.

   The model's chat template will be applied to the messages automatically, so the model must have one.

   Example:

   "messages": [
       {
         "role": "system",
         "content": "..."
       },
       {
         "role": "user",
         "content": "..."
       },
       {
         "role": "assistant",
         "content": "..."
       }
     ]
   

Worker Config

The worker config is a JSON file that is used to build the form that helps users configure their serverless endpoint on the RunPod Web Interface.

Note: This is a new feature and only works for workers that use one model

Writing your worker-config.json

The JSON consists of two main parts, schema and versions.

• schema: Here you specify the form fields that will be displayed to the user.
  • env_var_name: The name of the environment variable that is being set using the form field.
  • value: This is the default value of the form field. It will be shown in the UI as such unless the user changes it.
  • title: This is the title of the form field in the UI.
  • description: This is the description of the form field in the UI.
  • required: This is a boolean that specifies if the form field is required.
  • type: This is the type of the form field. Options are:
    • text: Environment variable is a string so user inputs text in form field.
    • select: User selects one option from the dropdown. You must provide the options key value pair after type if using this.
    • toggle: User toggles between true and false.
    • number: User inputs a number in the form field.
  • options: Specify the options the user can select from if the type is select. DO NOT include this unless the type is select.
• versions: This is where you call the form fields specified in schema and organize them into categories.
  • imageName: This is the name of the Docker image that will be used to run the serverless endpoint.
  • minimumCudaVersion: This is the minimum CUDA version that is required to run the serverless endpoint.
  • categories: This is where you call the keys of the form fields specified in schema and organize them into categories. Each category is a toggle list of forms on the Web UI.
    • title: This is the title of the category in the UI.
    • settings: This is the array of settings schemas specified in schema associated with the category.

Example of schema

{
  "schema": {
    "TOKENIZER": {
      "env_var_name": "TOKENIZER",
      "value": "",
      "title": "Tokenizer",
      "description": "Name or path of the Hugging Face tokenizer to use.",
      "required": false,
      "type": "text"
    }, 
    "TOKENIZER_MODE": {
      "env_var_name": "TOKENIZER_MODE",
      "value": "auto",
      "title": "Tokenizer Mode",
      "description": "The tokenizer mode.",
      "required": false,
      "type": "select",
      "options": [
        { "value": "auto", "label": "auto" },
        { "value": "slow", "label": "slow" }
      ]
    },
    ...
  }
}

Example of versions

{
  "versions": {
    "0.5.4": {
      "imageName": "runpod/worker-v1-vllm:v1.2.0stable-cuda12.1.0",
      "minimumCudaVersion": "12.1",
      "categories": [
        {
          "title": "LLM Settings",
          "settings": [
            "TOKENIZER", "TOKENIZER_MODE", "OTHER_SETTINGS_SCHEMA_KEYS_YOU_HAVE_SPECIFIED_0", ...
          ]
        },
        {
          "title": "Tokenizer Settings",
          "settings": [
            "OTHER_SETTINGS_SCHEMA_KEYS_0", "OTHER_SETTINGS_SCHEMA_KEYS_1", ...
          ]
        },
        ...
      ]
    }
  }
}