feat: prepare worker-vllm for the hub (#214)
Release / release (push) Waiting to run
Release / release (push) Waiting to run
* docs: remove outdated video; remove old info; added missing config for tools * ci: use proper release for dev (pr only) and production (release only) * ci(hub): added openai example; use smollm2 as base model * docs: added conventions to be able to work with ai ide's * chore: remove outdated stuff * chore: update copyright to 2025 * ci: added github permissions * feat: added gpuIds, gputCount and allowedCudaVersions; removed default value for LOAD_FORMAT to check which influence this has on the ui --------- Co-authored-by: Tim Pietrusky <tim.pietrusky@runpod.io>
This commit is contained in:
NERDDISCO
co-authored by
Tim Pietrusky
Tim Pietrusky
parent
aef1187a30
commit
5f0fc69d75
@@ -0,0 +1,79 @@
|
||||
# Contributing to worker-vllm
|
||||
|
||||
## 🚀 Release Process
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Feature Development**
|
||||
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
# Make your changes
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
- Creates pull request → triggers dev build: `runpod/worker-v1-vllm:dev-feature-your-feature-name`
|
||||
|
||||
2. **Main Branch**
|
||||
```bash
|
||||
git checkout main
|
||||
git merge feature/your-feature-name
|
||||
git push origin main
|
||||
```
|
||||
- No automatic builds on main (staging area)
|
||||
|
||||
### Creating Releases
|
||||
|
||||
**Method 1: GitHub UI (Recommended)**
|
||||
|
||||
1. Go to [Releases](https://github.com/runpod-workers/worker-vllm/releases)
|
||||
2. Click **"Create a new release"**
|
||||
3. **Tag version**: `v2.8.0` (with "v" prefix, semantic versioning)
|
||||
4. **Target**: `main` branch
|
||||
5. **Title**: `Release 2.8.0`
|
||||
6. **Description**: Brief changelog
|
||||
7. Click **"Publish release"**
|
||||
|
||||
**Method 2: Git CLI**
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git tag v2.8.0
|
||||
git push origin v2.8.0
|
||||
```
|
||||
|
||||
### What Happens Automatically
|
||||
|
||||
✅ **GitHub Release** created (if using Method 1)
|
||||
✅ **Docker Image** built and pushed: `runpod/worker-v1-vllm:v2.8.0`
|
||||
✅ **Documentation** updated with new version references
|
||||
|
||||
## 📋 Version Format
|
||||
|
||||
- **Format**: `vMAJOR.MINOR.PATCH` (e.g., `v2.8.0`)
|
||||
- **With "v" prefix**: Use `v2.8.0` for git tags
|
||||
- **Semantic Versioning**: Follow [SemVer](https://semver.org/)
|
||||
|
||||
## 🐛 Development
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Update test configuration in .runpod/tests.json
|
||||
# Tests run automatically via RunPod platform
|
||||
```
|
||||
|
||||
### Model Updates
|
||||
|
||||
- Update `MODEL_NAME` in `.runpod/tests.json` and `worker-config.json`
|
||||
- Ensure model has vLLM support and chat template (for OpenAI compatibility)
|
||||
|
||||
### Environment Variables
|
||||
|
||||
See [README.md](../README.md) for full list of supported environment variables.
|
||||
|
||||
## 🔧 CI/CD Workflows
|
||||
|
||||
- **Dev builds**: All pull requests → `dev-<branch-name>` images
|
||||
- **Release builds**: Git tags → versioned images + GitHub releases
|
||||
- **Manual triggers**: Available in GitHub Actions for emergency releases
|
||||
@@ -0,0 +1,60 @@
|
||||
name: Development
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches:
|
||||
- "**"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
dev:
|
||||
runs-on: [blacksmith-8vcpu-ubuntu-2204, linux]
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Clear space to remove unused folders
|
||||
run: |
|
||||
rm -rf /usr/share/dotnet
|
||||
rm -rf /opt/ghc
|
||||
rm -rf "/usr/local/share/boost"
|
||||
rm -rf "$AGENT_TOOLSDIRECTORY"
|
||||
|
||||
- name: Set up QEMU
|
||||
uses: docker/setup-qemu-action@v3
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Login to Docker Hub
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: blacksmith docker layer cache
|
||||
uses: useblacksmith/build-push-action@v1
|
||||
with:
|
||||
setup-only: true
|
||||
|
||||
- name: Set environment variables
|
||||
run: |
|
||||
echo "DOCKERHUB_REPO=${{ vars.DOCKERHUB_REPO || 'runpod' }}" >> $GITHUB_ENV
|
||||
echo "DOCKERHUB_IMG=${{ vars.DOCKERHUB_IMG || 'worker-v1-vllm' }}" >> $GITHUB_ENV
|
||||
echo "HUGGINGFACE_ACCESS_TOKEN=${{ secrets.HUGGINGFACE_ACCESS_TOKEN }}" >> $GITHUB_ENV
|
||||
# Convert branch name to safe docker tag (replace / with -)
|
||||
BRANCH_NAME="${GITHUB_REF##refs/heads/}"
|
||||
SAFE_BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g')
|
||||
echo "RELEASE_VERSION=dev-${SAFE_BRANCH_NAME}" >> $GITHUB_ENV
|
||||
|
||||
- name: Build and push the images to Docker Hub
|
||||
uses: docker/bake-action@v2
|
||||
with:
|
||||
push: true
|
||||
set: |
|
||||
*.args.DOCKERHUB_REPO=${{ env.DOCKERHUB_REPO }}
|
||||
*.args.DOCKERHUB_IMG=${{ env.DOCKERHUB_IMG }}
|
||||
*.args.RELEASE_VERSION=${{ env.RELEASE_VERSION }}
|
||||
*.args.HUGGINGFACE_ACCESS_TOKEN=${{ env.HUGGINGFACE_ACCESS_TOKEN }}
|
||||
@@ -0,0 +1,102 @@
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v[0-9]+.[0-9]+.[0-9]+*" # Trigger on version tags like v1.0.0, v2.1.0, etc.
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Version to release (e.g., v2.8.0)"
|
||||
required: true
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
contents: write # Required for creating GitHub releases
|
||||
packages: write # Required for pushing Docker images (if using GitHub packages)
|
||||
|
||||
jobs:
|
||||
release:
|
||||
runs-on: [blacksmith-8vcpu-ubuntu-2204, linux]
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Clear space to remove unused folders
|
||||
run: |
|
||||
rm -rf /usr/share/dotnet
|
||||
rm -rf /opt/ghc
|
||||
rm -rf "/usr/local/share/boost"
|
||||
rm -rf "$AGENT_TOOLSDIRECTORY"
|
||||
|
||||
- name: Set up QEMU
|
||||
uses: docker/setup-qemu-action@v3
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Login to Docker Hub
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: blacksmith docker layer cache
|
||||
uses: useblacksmith/build-push-action@v1
|
||||
with:
|
||||
setup-only: true
|
||||
|
||||
- name: Set environment variables
|
||||
run: |
|
||||
echo "DOCKERHUB_REPO=${{ vars.DOCKERHUB_REPO || 'runpod' }}" >> $GITHUB_ENV
|
||||
echo "DOCKERHUB_IMG=${{ vars.DOCKERHUB_IMG || 'worker-v1-vllm' }}" >> $GITHUB_ENV
|
||||
echo "HUGGINGFACE_ACCESS_TOKEN=${{ secrets.HUGGINGFACE_ACCESS_TOKEN }}" >> $GITHUB_ENV
|
||||
|
||||
# Determine version based on trigger type
|
||||
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
|
||||
# Manual trigger: use input version
|
||||
VERSION="${{ github.event.inputs.version }}"
|
||||
echo "RELEASE_VERSION=${VERSION}" >> $GITHUB_ENV
|
||||
echo "IS_MANUAL_RELEASE=true" >> $GITHUB_ENV
|
||||
else
|
||||
# Tag trigger: use tag name (remove refs/tags/ prefix)
|
||||
VERSION=${GITHUB_REF#refs/tags/}
|
||||
echo "RELEASE_VERSION=${VERSION}" >> $GITHUB_ENV
|
||||
echo "IS_MANUAL_RELEASE=false" >> $GITHUB_ENV
|
||||
fi
|
||||
|
||||
- name: Build and push the images to Docker Hub
|
||||
uses: docker/bake-action@v2
|
||||
with:
|
||||
push: true
|
||||
set: |
|
||||
*.args.DOCKERHUB_REPO=${{ env.DOCKERHUB_REPO }}
|
||||
*.args.DOCKERHUB_IMG=${{ env.DOCKERHUB_IMG }}
|
||||
*.args.RELEASE_VERSION=${{ env.RELEASE_VERSION }}
|
||||
*.args.HUGGINGFACE_ACCESS_TOKEN=${{ env.HUGGINGFACE_ACCESS_TOKEN }}
|
||||
|
||||
- name: Create GitHub Release
|
||||
if: env.IS_MANUAL_RELEASE == 'false'
|
||||
uses: actions/create-release@v1
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
tag_name: ${{ github.ref_name }}
|
||||
release_name: Release ${{ github.ref_name }}
|
||||
body: |
|
||||
Release ${{ github.ref_name }}
|
||||
|
||||
Docker Image: `${{ env.DOCKERHUB_REPO }}/${{ env.DOCKERHUB_IMG }}:${{ env.RELEASE_VERSION }}`
|
||||
|
||||
## Changes
|
||||
See [commit history](https://github.com/${{ github.repository }}/commits/${{ github.ref_name }}) for detailed changes.
|
||||
draft: false
|
||||
prerelease: false
|
||||
|
||||
- name: Manual Release Summary
|
||||
if: env.IS_MANUAL_RELEASE == 'true'
|
||||
run: |
|
||||
echo "🚀 Manual release completed!"
|
||||
echo "Version: ${{ env.RELEASE_VERSION }}"
|
||||
echo "Docker Image: ${{ env.DOCKERHUB_REPO }}/${{ env.DOCKERHUB_IMG }}:${{ env.RELEASE_VERSION }}"
|
||||
echo "Note: No GitHub release created for manual triggers"
|
||||
@@ -1,3 +0,0 @@
|
||||
[submodule "vllm-base-image/vllm"]
|
||||
path = vllm-base-image/vllm
|
||||
url = https://github.com/runpod/vllm-fork-for-sls-worker.git
|
||||
+13
-1
@@ -7,6 +7,19 @@
|
||||
"config": {
|
||||
"runsOn": "GPU",
|
||||
"containerDiskInGb": 200,
|
||||
"gpuIds": "ADA_80_PRO, AMPERE_80",
|
||||
"gpuCount": 1,
|
||||
"allowedCudaVersions": [
|
||||
"12.9",
|
||||
"12.8",
|
||||
"12.7",
|
||||
"12.6",
|
||||
"12.5",
|
||||
"12.4",
|
||||
"12.3",
|
||||
"12.2",
|
||||
"12.1"
|
||||
],
|
||||
"presets": [
|
||||
{
|
||||
"name": "deepseek-ai/deepseek-r1-distill-llama-8b",
|
||||
@@ -129,7 +142,6 @@
|
||||
"value": "bitsandbytes"
|
||||
}
|
||||
],
|
||||
"default": "auto",
|
||||
"advanced": true
|
||||
}
|
||||
},
|
||||
|
||||
+24
-4
@@ -6,6 +6,28 @@
|
||||
"prompt": "Write a short poem about artificial intelligence."
|
||||
},
|
||||
"timeout": 30000
|
||||
},
|
||||
{
|
||||
"name": "openai_messages_test",
|
||||
"input": {
|
||||
"openai_route": "/v1/chat/completions",
|
||||
"openai_input": {
|
||||
"model": "HuggingFaceTB/SmolLM2-135M-Instruct",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "You are a helpful assistant that writes concise responses."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Explain what a neural network is in one sentence."
|
||||
}
|
||||
],
|
||||
"max_tokens": 50,
|
||||
"temperature": 0.7
|
||||
}
|
||||
},
|
||||
"timeout": 30000
|
||||
}
|
||||
],
|
||||
"config": {
|
||||
@@ -14,7 +36,7 @@
|
||||
"env": [
|
||||
{
|
||||
"key": "MODEL_NAME",
|
||||
"value": "facebook/opt-350m"
|
||||
"value": "HuggingFaceTB/SmolLM2-135M-Instruct"
|
||||
}
|
||||
],
|
||||
"allowedCudaVersions": [
|
||||
@@ -24,9 +46,7 @@
|
||||
"12.4",
|
||||
"12.3",
|
||||
"12.2",
|
||||
"12.1",
|
||||
"12.0",
|
||||
"11.7"
|
||||
"12.1"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2023 runpod-workers
|
||||
Copyright (c) 2025 Runpod
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
||||
@@ -1,40 +1,15 @@
|
||||
<div align="center">
|
||||
|
||||
# OpenAI-Compatible vLLM Serverless Endpoint Worker
|
||||
Deploy OpenAI-Compatible Blazing-Fast LLM Endpoints powered by the [vLLM](https://github.com/vllm-project/vllm) Inference Engine on RunPod Serverless with just a few clicks.
|
||||
<!--
|
||||
|
||||
|
||||
\
|
||||
 -->
|
||||
<!--
|
||||
 -->
|
||||
|
||||
Deploy OpenAI-Compatible Blazing-Fast LLM Endpoints powered by the [vLLM](https://github.com/vllm-project/vllm) Inference Engine on RunPod Serverless with just a few clicks.
|
||||
|
||||
</div>
|
||||
|
||||
# News:
|
||||
|
||||
### 1. UI for Deploying vLLM Worker on RunPod console:
|
||||
|
||||
|
||||
### 2. Worker vLLM `v2.7.0` with vLLM `0.9.1` now available under `stable` tags
|
||||
|
||||
Update v2.7.0 is now available, use the image tag `runpod/worker-v1-vllm:v2.7.0stable-cuda12.1.0`.
|
||||
|
||||
### 3. OpenAI-Compatible [Embedding Worker](https://github.com/runpod-workers/worker-infinity-embedding) 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](#setting-up-the-serverless-worker)
|
||||
- [Option 1: Deploy Any Model Using Pre-Built Docker Image **[RECOMMENDED]**](#option-1-deploy-any-model-using-pre-built-docker-image-recommended)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [LLM Settings](#llm-settings)
|
||||
- [Tokenizer Settings](#tokenizer-settings)
|
||||
@@ -57,45 +32,26 @@ Worker vLLM is now cached on all RunPod machines, resulting in near-instant depl
|
||||
- [Input Request Parameters](#input-request-parameters)
|
||||
- [Text Input Formats](#text-input-formats)
|
||||
- [Sampling Parameters](#sampling-parameters)
|
||||
- [Worker Config](#worker-config)
|
||||
- [Writing your worker-config.json](#writing-your-worker-configjson)
|
||||
- [Example of schema](#example-of-schema)
|
||||
- [Example of versions](#example-of-versions)
|
||||
|
||||
# Setting up the Serverless Worker
|
||||
|
||||
### Option 1: Deploy Any Model Using Pre-Built Docker Image [Recommended]
|
||||
## 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!
|
||||
**🚀 Deploy Guide**: Follow our [step-by-step deployment guide](https://docs.runpod.io/serverless/vllm/get-started) to deploy using the RunPod Console.
|
||||
|
||||
**📦 Docker Image**: `runpod/worker-v1-vllm:<version>stable-cuda12.1.0`
|
||||
|
||||
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:
|
||||
- **Available Versions**: See [GitHub Releases](https://github.com/runpod-workers/worker-vllm/releases)
|
||||
- **CUDA Compatibility**: Requires CUDA >= 12.1
|
||||
|
||||
---
|
||||
### Environment Variables
|
||||
|
||||
## RunPod Worker Images
|
||||
|
||||
Below is a summary of the available RunPod Worker images, categorized by image stability and CUDA version compatibility.
|
||||
|
||||
| CUDA Version | Stable Image Tag | Development Image Tag | Note |
|
||||
|--------------|-----------------------------------|-----------------------------------|----------------------------------------------------------------------|
|
||||
| 12.1.0 | `runpod/worker-v1-vllm:v2.7.0stable-cuda12.1.0` | `runpod/worker-v1-vllm:v2.7.0dev-cuda12.1.0` | When creating an Endpoint, select CUDA Version 12.3, 12.2 and 12.1 in the filter. |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
#### Prerequisites
|
||||
- RunPod Account
|
||||
|
||||
#### Environment Variables
|
||||
> Note: `0` is equivalent to `False` and `1` is equivalent to `True` for boolean as int values.
|
||||
Use these to configure worker-vllm so it works for your use case / model.
|
||||
|
||||
#### LLM Settings
|
||||
|
||||
| `Name` | `Default` | `Type/Choices` | `Description` |
|
||||
|-------------------------------------------|-----------------------|--------------------------------------------|---------------|
|
||||
| ------------------------------------------------ | ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `MODEL_NAME` | 'facebook/opt-125m' | `str` | Name or path of the Hugging Face model to use. |
|
||||
| `TOKENIZER` | None | `str` | Name or path of the Hugging Face tokenizer to use. |
|
||||
| `SKIP_TOKENIZER_INIT` | False | `bool` | Skip initialization of tokenizer and detokenizer. |
|
||||
@@ -159,11 +115,10 @@ Below is a summary of the available RunPod Worker images, categorized by image s
|
||||
| `DISABLE_LOGGING_REQUEST` | False | `bool` | Disable logging requests. |
|
||||
| `MAX_LOG_LEN` | None | `int` | Max number of prompt characters or prompt ID numbers being printed in log. |
|
||||
|
||||
|
||||
#### Tokenizer Settings
|
||||
|
||||
| `Name` | `Default` | `Type/Choices` | `Description` |
|
||||
|-------------------------------------------|-----------------------|--------------------------------------------|---------------|
|
||||
| ---------------------- | --------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `TOKENIZER_NAME` | `None` | `str` | Tokenizer repository to use a different tokenizer than the model's default. |
|
||||
| `TOKENIZER_REVISION` | `None` | `str` | Tokenizer revision to load. |
|
||||
| `CUSTOM_CHAT_TEMPLATE` | `None` | `str` of single-line jinja template | Custom chat jinja template. [More Info](https://huggingface.co/docs/transformers/chat_templating) |
|
||||
@@ -171,7 +126,7 @@ Below is a summary of the available RunPod Worker images, categorized by image s
|
||||
#### System and Parallelism Settings
|
||||
|
||||
| `Name` | `Default` | `Type/Choices` | `Description` |
|
||||
|-------------------------------------------|-----------------------|--------------------------------------------|---------------|
|
||||
| ------------------------------ | --------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `GPU_MEMORY_UTILIZATION` | `0.95` | `float` | Sets GPU VRAM utilization. |
|
||||
| `MAX_PARALLEL_LOADING_WORKERS` | `None` | `int` | Load model sequentially in multiple batches, to avoid RAM OOM when using tensor parallel and large models. |
|
||||
| `BLOCK_SIZE` | `16` | `8`, `16`, `32` | Token block size for contiguous chunks of tokens. |
|
||||
@@ -180,14 +135,12 @@ Below is a summary of the available RunPod Worker images, categorized by image s
|
||||
| `MAX_SEQ_LEN_TO_CAPTURE` | `8192` | `int` | Maximum context length covered by CUDA graphs. When a sequence has context length larger than this, we fall back to eager mode. |
|
||||
| `DISABLE_CUSTOM_ALL_REDUCE` | `0` | `int` | Enables or disables custom all reduce. |
|
||||
|
||||
|
||||
#### Streaming Batch Size Settings
|
||||
|
||||
The way this works is that the first request will have a batch size of `DEFAULT_MIN_BATCH_SIZE`, and each subsequent request will have a batch size of `previous_batch_size * DEFAULT_BATCH_SIZE_GROWTH_FACTOR`. This will continue until the batch size reaches `DEFAULT_BATCH_SIZE`. E.g. for the default values, the batch sizes will be `1, 3, 9, 27, 50, 50, 50, ...`. You can also specify this per request, with inputs `max_batch_size`, `min_batch_size`, and `batch_size_growth_factor`. This has nothing to do with vLLM's internal batching, but rather the number of tokens sent in each HTTP request from the worker
|
||||
|
||||
|
||||
| `Name` | `Default` | `Type/Choices` | `Description` |
|
||||
|-------------------------------------------|-----------------------|--------------------------------------------|---------------|
|
||||
| ---------------------------------- | --------- | -------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `DEFAULT_BATCH_SIZE` | `50` | `int` | Default and Maximum batch size for token streaming to reduce HTTP calls. |
|
||||
| `DEFAULT_MIN_BATCH_SIZE` | `1` | `int` | Batch size for the first request, which will be multiplied by the growth factor every subsequent request. |
|
||||
| `DEFAULT_BATCH_SIZE_GROWTH_FACTOR` | `3` | `float` | Growth factor for dynamic batch size. |
|
||||
@@ -195,31 +148,31 @@ The way this works is that the first request will have a batch size of `DEFAULT_
|
||||
#### OpenAI Settings
|
||||
|
||||
| `Name` | `Default` | `Type/Choices` | `Description` |
|
||||
|-------------------------------------------|-----------------------|--------------------------------------------|---------------|
|
||||
| ----------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `RAW_OPENAI_OUTPUT` | `1` | boolean as `int` | Enables raw OpenAI SSE format string output when streaming. **Required** to be enabled (which it is by default) for OpenAI compatibility. |
|
||||
| `OPENAI_SERVED_MODEL_NAME_OVERRIDE` | `None` | `str` | Overrides the name of the served model from model repo/path to specified name, which you will then be able to use the value for the `model` parameter when making OpenAI requests |
|
||||
| `OPENAI_RESPONSE_ROLE` | `assistant` | `str` | Role of the LLM's Response in OpenAI Chat Completions. |
|
||||
| `ENABLE_AUTO_TOOL_CHOICE` | `false` | `bool` | Enables automatic tool selection for supported models. Set to `true` to activate. |
|
||||
| `TOOL_CALL_PARSER` | `None` | `str` | Specifies the parser for tool calls. Options: `mistral`, `hermes`, `llama3_json`, `llama4_json`, `llama4_pythonic`, `granite`, `granite-20b-fc`, `deepseek_v3`, `internlm`, `jamba`, `phi4_mini_json`, `pythonic` |
|
||||
|
||||
#### Serverless Settings
|
||||
|
||||
| `Name` | `Default` | `Type/Choices` | `Description` |
|
||||
|-------------------------------------------|-----------------------|--------------------------------------------|---------------|
|
||||
| ---------------------- | --------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `MAX_CONCURRENCY` | `300` | `int` | Max concurrent requests per worker. vLLM has an internal queue, so you don't have to worry about limiting by VRAM, this is for improving scaling/load balancing efficiency |
|
||||
| `DISABLE_LOG_STATS` | False | `bool` | Enables or disables vLLM stats logging. |
|
||||
| `DISABLE_LOG_REQUESTS` | False | `bool` | Enables or disables vLLM request logging. |
|
||||
|
||||
> [!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
|
||||
|
||||
|
||||
### 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
|
||||
### Prerequisites
|
||||
|
||||
- Docker
|
||||
|
||||
#### Arguments:
|
||||
### Arguments
|
||||
|
||||
- **Required**
|
||||
- `MODEL_NAME`
|
||||
- **Optional**
|
||||
@@ -232,77 +185,58 @@ To build an image with the model baked in, you must specify the following docker
|
||||
|
||||
For the remaining settings, you may apply them as environment variables when running the container. Supported environment variables are listed in the [Environment Variables](#environment-variables) section.
|
||||
|
||||
#### Example: Building an image with OpenChat-3.5
|
||||
### Example: Building an image with OpenChat-3.5
|
||||
|
||||
```bash
|
||||
sudo docker build -t username/image:tag --build-arg MODEL_NAME="openchat/openchat_3.5" --build-arg BASE_PATH="/models" .
|
||||
docker build -t username/image:tag --build-arg MODEL_NAME="openchat/openchat_3.5" --build-arg BASE_PATH="/models" .
|
||||
```
|
||||
|
||||
##### (Optional) Including Huggingface Token
|
||||
### (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).
|
||||
|
||||
```bash
|
||||
export DOCKER_BUILDKIT=1
|
||||
```
|
||||
|
||||
2. Export your Hugging Face token as an environment variable
|
||||
|
||||
```bash
|
||||
export HF_TOKEN="your_token_here"
|
||||
```
|
||||
|
||||
2. Add the token as a secret when building
|
||||
|
||||
```bash
|
||||
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:
|
||||
# Compatible Model Architectures
|
||||
|
||||
- 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.)
|
||||
You can deploy **any model on Hugging Face** that is supported by vLLM. For the complete and up-to-date list of supported model architectures, see the [vLLM Supported Models documentation](https://docs.vllm.ai/en/latest/models/supported_models.html#list-of-text-only-language-models).
|
||||
|
||||
# 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:
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
|
||||
```
|
||||
|
||||
- After:
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
@@ -311,6 +245,7 @@ The vLLM Worker is fully compatible with OpenAI's API, and you can use it with a
|
||||
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:
|
||||
```python
|
||||
@@ -332,6 +267,7 @@ The vLLM Worker is fully compatible with OpenAI's API, and you can use it with a
|
||||
```
|
||||
|
||||
**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:
|
||||
```bash
|
||||
@@ -373,11 +309,12 @@ The vLLM Worker is fully compatible with OpenAI's API, and you can use it with a
|
||||
When using the chat completion feature of the vLLM Serverless Endpoint Worker, you can customize your requests with the following parameters:
|
||||
|
||||
### Chat Completions [RECOMMENDED]
|
||||
|
||||
<details>
|
||||
<summary>Supported Chat Completions Inputs and Descriptions</summary>
|
||||
|
||||
| Parameter | Type | Default Value | Description |
|
||||
|--------------------------------|----------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| ------------------- | -------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `messages` | Union[str, List[Dict[str, str]]] | | List of messages, where each message is a dictionary with a `role` and `content`. The model's chat template will be applied to the messages automatically, so the model must have one or it should be specified as `CUSTOM_CHAT_TEMPLATE` env var. |
|
||||
| `model` | str | | The model repo that you've deployed on your RunPod Serverless Endpoint. If you are unsure what the name is or are baking the model in, use the guide to get the list of available models in the **Examples: Using your RunPod endpoint with OpenAI** section |
|
||||
| `temperature` | Optional[float] | 0.7 | Float that controls the randomness of the sampling. Lower values make the model more deterministic, while higher values make the model more random. Zero means greedy sampling. |
|
||||
@@ -391,6 +328,7 @@ When using the chat completion feature of the vLLM Serverless Endpoint Worker, y
|
||||
| `frequency_penalty` | Optional[float] | 0.0 | Float that penalizes new tokens based on their frequency in the generated text so far. Values > 0 encourage the model to use new tokens, while values < 0 encourage the model to repeat tokens. |
|
||||
| `logit_bias` | Optional[Dict[str, float]] | None | Unsupported by vLLM |
|
||||
| `user` | Optional[str] | None | Unsupported by vLLM |
|
||||
|
||||
Additional parameters supported by vLLM:
|
||||
| `best_of` | Optional[int] | None | Number of output sequences that are generated from the prompt. From these `best_of` sequences, the top `n` sequences are returned. `best_of` must be greater than or equal to `n`. This is treated as the beam width when `use_beam_search` is True. By default, `best_of` is set to `n`. |
|
||||
| `top_k` | Optional[int] | -1 | Integer that controls the number of top tokens to consider. Set to -1 to consider all tokens. |
|
||||
@@ -405,12 +343,13 @@ When using the chat completion feature of the vLLM Serverless Endpoint Worker, y
|
||||
| `min_p` | Optional[float] | 0.0 | Float that represents the minimum probability for a token to |
|
||||
| `length_penalty` | Optional[float] | 1.0 | Float that penalizes sequences based on their length. Used in beam search.. |
|
||||
| `include_stop_str_in_output` | Optional[bool] | False | Whether to include the stop strings in output text. Defaults to False.|
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
## Examples: Using your RunPod endpoint with OpenAI
|
||||
### Examples: Using your RunPod endpoint with OpenAI
|
||||
|
||||
First, initialize the OpenAI Client with your RunPod API Key and Endpoint URL:
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
import os
|
||||
@@ -423,7 +362,9 @@ client = OpenAI(
|
||||
```
|
||||
|
||||
### 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**:
|
||||
```python
|
||||
# Create a chat completion stream
|
||||
@@ -452,7 +393,9 @@ This is the format used for GPT-4 and focused on instruction-following and chat.
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```python
|
||||
models_response = client.models.list()
|
||||
list_of_models = [model.id for model in models_response]
|
||||
@@ -460,6 +403,7 @@ print(list_of_models)
|
||||
```
|
||||
|
||||
# Usage: Standard (Non-OpenAI)
|
||||
|
||||
## Request Input Parameters
|
||||
|
||||
<details>
|
||||
@@ -481,11 +425,12 @@ print(list_of_models)
|
||||
### 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.
|
||||
|
||||
<details>
|
||||
<summary>Click to expand table</summary>
|
||||
|
||||
| Argument | Type | Default | Description |
|
||||
|---------------------------------|-----------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| ------------------------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `n` | int | 1 | Number of output sequences generated from the prompt. The top `n` sequences are returned. |
|
||||
| `best_of` | Optional[int] | `n` | Number of output sequences generated from the prompt. The top `n` sequences are returned from these `best_of` sequences. Must be ≥ `n`. Treated as beam width in beam search. Default is `n`. |
|
||||
| `presence_penalty` | float | 0.0 | Penalizes new tokens based on their presence in the generated text so far. Values > 0 encourage new tokens, values < 0 encourage repetition. |
|
||||
@@ -505,9 +450,10 @@ Below are all available sampling parameters that you can specify in the `samplin
|
||||
| `skip_special_tokens` | bool | True | Whether to skip special tokens in the output. |
|
||||
| `spaces_between_special_tokens` | bool | True | Whether to add spaces between special tokens in the output. |
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -523,17 +469,16 @@ The prompt string can be any string, and the model's chat template will not be a
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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`
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"input": {
|
||||
@@ -560,85 +505,3 @@ Your list can contain any number of messages, and each message usually can have
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
# 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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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", ...
|
||||
]
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
+13
-19
@@ -1,32 +1,26 @@
|
||||
variable "PUSH" {
|
||||
default = "true"
|
||||
}
|
||||
|
||||
variable "REPOSITORY" {
|
||||
variable "DOCKERHUB_REPO" {
|
||||
default = "runpod"
|
||||
}
|
||||
|
||||
variable "BASE_IMAGE_VERSION" {
|
||||
default = "v2.8.0stable"
|
||||
variable "DOCKERHUB_IMG" {
|
||||
default = "worker-v1-vllm"
|
||||
}
|
||||
|
||||
group "all" {
|
||||
targets = ["main"]
|
||||
variable "RELEASE_VERSION" {
|
||||
default = "latest"
|
||||
}
|
||||
|
||||
|
||||
group "main" {
|
||||
targets = ["worker-1210"]
|
||||
variable "HUGGINGFACE_ACCESS_TOKEN" {
|
||||
default = ""
|
||||
}
|
||||
|
||||
group "default" {
|
||||
targets = ["worker-vllm"]
|
||||
}
|
||||
|
||||
target "worker-1210" {
|
||||
tags = ["${REPOSITORY}/worker-v1-vllm:${BASE_IMAGE_VERSION}-cuda12.1.0"]
|
||||
target "worker-vllm" {
|
||||
tags = ["${DOCKERHUB_REPO}/${DOCKERHUB_IMG}:${RELEASE_VERSION}"]
|
||||
context = "."
|
||||
dockerfile = "Dockerfile"
|
||||
args = {
|
||||
BASE_IMAGE_VERSION = "${BASE_IMAGE_VERSION}"
|
||||
WORKER_CUDA_VERSION = "12.1.0"
|
||||
}
|
||||
output = ["type=docker,push=${PUSH}"]
|
||||
platforms = ["linux/amd64"]
|
||||
}
|
||||
@@ -0,0 +1,342 @@
|
||||
# Worker vLLM - Development Conventions & Architecture Guide
|
||||
|
||||
## Project Overview
|
||||
|
||||
**worker-vllm** is a RunPod serverless worker that provides OpenAI-compatible endpoints for Large Language Model (LLM) inference, powered by the vLLM engine. It enables blazing-fast LLM deployment on RunPod's serverless infrastructure with minimal configuration.
|
||||
|
||||
### Core Purpose
|
||||
|
||||
- **Primary Function**: Deploy any Hugging Face LLM as an OpenAI-compatible API endpoint
|
||||
- **Platform**: RunPod Serverless infrastructure
|
||||
- **Engine**: vLLM (high-performance LLM inference engine)
|
||||
- **Compatibility**: Drop-in replacement for OpenAI API (Chat Completions, Models)
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
### 1. **Entry Point & Request Flow**
|
||||
|
||||
```
|
||||
RunPod Request → handler.py → JobInput → Engine Selection → vLLM Generation → Streaming Response
|
||||
```
|
||||
|
||||
**Key Components:**
|
||||
|
||||
- `src/handler.py`: Main entry point using RunPod serverless framework
|
||||
- `src/utils.py`: Request parsing and utility classes (`JobInput`, `BatchSize`)
|
||||
- Two engine modes: OpenAI-compatible vs. standard vLLM
|
||||
|
||||
### 2. **Engine Architecture**
|
||||
|
||||
#### Core Classes:
|
||||
|
||||
- **`vLLMEngine`**: Base engine handling vLLM initialization and generation
|
||||
- **`OpenAIvLLMEngine`**: Wrapper providing OpenAI API compatibility
|
||||
- **Engine Selection**: Automatic routing based on `job_input.openai_route`
|
||||
|
||||
#### Key Design Patterns:
|
||||
|
||||
- **Dual API Support**: Same codebase serves both OpenAI-compatible and native vLLM APIs
|
||||
- **Streaming by Default**: Token-level streaming with configurable batching
|
||||
- **Dynamic Batching**: Adaptive batch sizes that grow from min → max for efficiency
|
||||
|
||||
### 3. **Configuration System**
|
||||
|
||||
#### Environment-Based Configuration:
|
||||
|
||||
- **Single Source of Truth**: All configuration via environment variables
|
||||
- **Hierarchical Loading**: `DEFAULT_ARGS` → `os.environ` → `local_model_args.json` (for baked models)
|
||||
- **vLLM Argument Mapping**: Automatic translation of env vars to vLLM `AsyncEngineArgs`
|
||||
|
||||
#### Key Configuration Files:
|
||||
|
||||
- `src/engine_args.py`: Centralized configuration management
|
||||
- `src/constants.py`: Default values for core settings
|
||||
- `worker-config.json`: UI form generation for RunPod console
|
||||
|
||||
## Core Development Concepts
|
||||
|
||||
### 1. **Deployment Models**
|
||||
|
||||
#### Option 1: Pre-built Images (Recommended)
|
||||
|
||||
- **Image**: `runpod/worker-v1-vllm:<version>` (see [GitHub Releases](https://github.com/runpod-workers/worker-vllm/releases))
|
||||
- **Configuration**: Entirely via environment variables
|
||||
- **Model Loading**: Downloads model at runtime from Hugging Face
|
||||
- **Use Case**: Quick deployment, model experimentation
|
||||
|
||||
#### Option 2: Baked Model Images
|
||||
|
||||
- **Build Process**: Model downloaded during Docker build
|
||||
- **Storage**: Model embedded in container image
|
||||
- **Configuration**: Stored in `/local_model_args.json`
|
||||
- **Use Case**: Production deployments, faster cold starts
|
||||
|
||||
### 2. **Request Processing Patterns**
|
||||
|
||||
#### Input Handling:
|
||||
|
||||
```python
|
||||
class JobInput:
|
||||
- llm_input: str | List[Dict] (prompt or messages)
|
||||
- sampling_params: SamplingParams (generation settings)
|
||||
- stream: bool (streaming vs batch response)
|
||||
- openai_route: bool (API compatibility mode)
|
||||
- batch_size configs: Dynamic batching parameters
|
||||
```
|
||||
|
||||
#### Response Streaming:
|
||||
|
||||
- **Batched Streaming**: Tokens grouped into configurable batch sizes
|
||||
- **Dynamic Growth**: `min_batch_size * growth_factor^n` up to `max_batch_size`
|
||||
- **Usage Tracking**: Input/output token counting for billing
|
||||
|
||||
### 3. **Model & Tokenizer Management**
|
||||
|
||||
#### Tokenizer Handling:
|
||||
|
||||
- **Wrapper Pattern**: `TokenizerWrapper` for consistent chat template application
|
||||
- **Special Cases**: Mistral models use vLLM's native tokenizer
|
||||
- **Chat Templates**: Automatic application for message-based inputs
|
||||
|
||||
#### Model Loading:
|
||||
|
||||
- **Multi-GPU Support**: Automatic tensor parallelism detection
|
||||
- **Quantization**: Support for AWQ, GPTQ, BitsAndBytes
|
||||
- **Caching**: Hugging Face cache management
|
||||
|
||||
## Development Patterns & Best Practices
|
||||
|
||||
### 1. **Code Organization**
|
||||
|
||||
#### File Structure:
|
||||
|
||||
```
|
||||
src/
|
||||
├── handler.py # RunPod entry point
|
||||
├── engine.py # Core vLLM engines
|
||||
├── engine_args.py # Configuration management
|
||||
├── utils.py # Request parsing & utilities
|
||||
├── tokenizer.py # Tokenizer wrapper
|
||||
├── constants.py # Default constants
|
||||
└── download_model.py # Model downloading logic
|
||||
```
|
||||
|
||||
#### Separation of Concerns:
|
||||
|
||||
- **Engine Logic**: Isolated in `engine.py` classes
|
||||
- **Configuration**: Centralized in `engine_args.py`
|
||||
- **Request Handling**: Abstracted via `JobInput` class
|
||||
- **Platform Integration**: Contained in `handler.py`
|
||||
|
||||
### 2. **Error Handling & Logging**
|
||||
|
||||
#### Logging Strategy:
|
||||
|
||||
- **Structured Logging**: Consistent format across components
|
||||
- **Performance Tracking**: Timer decorators for critical operations
|
||||
- **Error Context**: Detailed error messages with configuration context
|
||||
|
||||
#### Error Responses:
|
||||
|
||||
- **OpenAI Compatibility**: Standard OpenAI error format
|
||||
- **Graceful Degradation**: Fallback behaviors for edge cases
|
||||
|
||||
### 3. **Environment Variable Conventions**
|
||||
|
||||
#### Naming Patterns:
|
||||
|
||||
- **vLLM Settings**: Match vLLM parameter names (uppercase)
|
||||
- **RunPod Settings**: `MAX_CONCURRENCY`, `DEFAULT_BATCH_SIZE`
|
||||
- **OpenAI Settings**: `OPENAI_` prefix for compatibility settings
|
||||
- **Feature Flags**: `ENABLE_*`, `DISABLE_*` pattern
|
||||
|
||||
#### Type Conventions:
|
||||
|
||||
- **Booleans**: String 'true'/'false' or int 0/1
|
||||
- **Lists**: Comma-separated strings
|
||||
- **Objects**: JSON strings for complex configurations
|
||||
|
||||
### 4. **Docker & Deployment**
|
||||
|
||||
#### Multi-Stage Builds:
|
||||
|
||||
- **Base**: CUDA runtime environment
|
||||
- **Dependencies**: Python packages and vLLM
|
||||
- **Model Download**: Optional model baking stage
|
||||
- **Runtime**: Final application layer
|
||||
|
||||
#### Build Arguments:
|
||||
|
||||
- **MODEL_NAME**: Primary model identifier
|
||||
- **BASE_PATH**: Storage location strategy
|
||||
- **QUANTIZATION**: Optimization settings
|
||||
- **WORKER_CUDA_VERSION**: CUDA compatibility
|
||||
|
||||
#### CI/CD Strategy:
|
||||
|
||||
- **Development Builds**: All non-main branches → `runpod/worker-v1-vllm:dev-<branch-name>`
|
||||
- **Release Builds**: Git tags (numeric) only → `runpod/worker-v1-vllm:<version>`
|
||||
- **Dependency Updates**: Automated runpod package version monitoring
|
||||
|
||||
#### Docker Bake Configuration:
|
||||
|
||||
- **File**: `docker-bake.hcl` (flexible variable-based configuration)
|
||||
- **Variables**: `DOCKERHUB_REPO`, `DOCKERHUB_IMG`, `RELEASE_VERSION`, `HUGGINGFACE_ACCESS_TOKEN`
|
||||
- **Platform**: `linux/amd64` (GPU-optimized)
|
||||
|
||||
## Release & Versioning Strategy
|
||||
|
||||
### 1. **Version Tagging**
|
||||
|
||||
- **Development**: `dev-<branch-name>` (e.g., `dev-feature-new-api`)
|
||||
- **Specific Versions**: `2.7.0`, `2.8.0` (semantic versioning without "v" prefix)
|
||||
- **Version Discovery**: Check [GitHub Releases](https://github.com/runpod-workers/worker-vllm/releases) for available versions
|
||||
|
||||
### 2. **Release Workflow**
|
||||
|
||||
1. **Feature Development**: Work on feature branches → triggers dev builds
|
||||
2. **Main Branch Staging**: Merge features to main → stable codebase (no builds)
|
||||
3. **Version Release**: Create git tag from main branch (e.g., `2.8.0`) → triggers versioned release + GitHub release
|
||||
4. **Docker Hub**: Versioned image pushed with tag
|
||||
|
||||
### 3. **Branch Strategy**
|
||||
|
||||
- **Feature Branches**: `feature/*`, `fix/*`, `feat/*` etc. → Dev builds
|
||||
- **Main Branch**: Stable codebase ready for release (no automatic builds)
|
||||
- **Git Tags**: Must be created from main branch for formal version releases
|
||||
|
||||
### 4. **Deployment Recommendations**
|
||||
|
||||
- **Production**: Use specific version tags (e.g., `2.7.0`) for stability
|
||||
- **Development**: Use `dev-<branch>` for testing specific features
|
||||
- **Version Selection**: Check [GitHub Releases](https://github.com/runpod-workers/worker-vllm/releases) for available versions
|
||||
- **Release Process**: Always tag from main branch: `git checkout main && git tag 2.8.0 && git push origin 2.8.0`
|
||||
|
||||
## Performance & Scaling Considerations
|
||||
|
||||
### 1. **Memory Management**
|
||||
|
||||
- **GPU Utilization**: Default 95% GPU memory utilization
|
||||
- **KV Cache**: Configurable cache types (auto, fp8)
|
||||
- **Swap Space**: CPU offloading for large contexts
|
||||
|
||||
### 2. **Concurrency Patterns**
|
||||
|
||||
- **Max Concurrency**: 300 concurrent requests by default
|
||||
- **vLLM Queuing**: Internal request batching and scheduling
|
||||
- **RunPod Integration**: Concurrency modifier for auto-scaling
|
||||
|
||||
### 3. **Optimization Features**
|
||||
|
||||
- **Prefix Caching**: Automatic caching of common prefixes
|
||||
- **Speculative Decoding**: Draft model acceleration
|
||||
- **Chunked Prefill**: Memory-efficient long context handling
|
||||
|
||||
## Testing & Development
|
||||
|
||||
### 1. **Local Development**
|
||||
|
||||
- **Environment**: Virtual environment with GPU support
|
||||
- **Configuration**: `.env` files for local testing
|
||||
- **Model Testing**: Small models for development (facebook/opt-125m)
|
||||
|
||||
### 2. **Docker Development**
|
||||
|
||||
- **Build Strategy**: `docker-bake.hcl` for consistent builds
|
||||
- **Testing Images**: Separate dev/stable image tags
|
||||
- **Layer Caching**: Optimized for rapid iteration
|
||||
|
||||
### 3. **Configuration Validation**
|
||||
|
||||
- **Argument Matching**: Automatic validation against vLLM parameters
|
||||
- **Environment Validation**: Type checking and default value handling
|
||||
- **Runtime Validation**: Model compatibility checks
|
||||
|
||||
## API Conventions
|
||||
|
||||
### 1. **OpenAI Compatibility**
|
||||
|
||||
- **Endpoint Mapping**: `/openai/v1/chat/completions`, `/openai/v1/models`
|
||||
- **Request Format**: Exact OpenAI request/response schemas
|
||||
- **Authentication**: RunPod API key in Authorization header
|
||||
- **Model Names**: Hugging Face repo names or custom overrides
|
||||
|
||||
### 2. **Native vLLM API**
|
||||
|
||||
- **Input Format**: `prompt` or `messages` with `sampling_params`
|
||||
- **Streaming**: Token-level streaming with configurable batching
|
||||
- **Extensibility**: Support for vLLM-specific features
|
||||
|
||||
## Common Patterns & Utilities
|
||||
|
||||
### 1. **Configuration Loading**
|
||||
|
||||
```python
|
||||
# Standard pattern for new configuration options
|
||||
def get_engine_args():
|
||||
args = DEFAULT_ARGS
|
||||
args.update(os.environ) # Environment override
|
||||
args.update(get_local_args()) # Baked model override
|
||||
return match_vllm_args(args) # Validate against vLLM
|
||||
```
|
||||
|
||||
### 2. **Error Handling**
|
||||
|
||||
```python
|
||||
# Standard error response pattern
|
||||
def create_error_response(message: str, err_type: str = "BadRequestError"):
|
||||
return ErrorResponse(message=message, type=err_type)
|
||||
```
|
||||
|
||||
### 3. **Async Generation**
|
||||
|
||||
```python
|
||||
# Standard streaming pattern
|
||||
async def generate(self, job_input: JobInput):
|
||||
async for batch in self._generate_vllm(...):
|
||||
yield batch # Batch-level yielding for efficiency
|
||||
```
|
||||
|
||||
## Extension Points
|
||||
|
||||
### 1. **New Model Architectures**
|
||||
|
||||
- **Engine Args**: Add new parameters in `engine_args.py`
|
||||
- **Compatibility**: Update vLLM argument mapping
|
||||
- **Validation**: Add architecture-specific validation
|
||||
|
||||
### 2. **New API Features**
|
||||
|
||||
- **Engine Extension**: Extend `vLLMEngine` or `OpenAIvLLMEngine`
|
||||
- **Input Parsing**: Extend `JobInput` class
|
||||
- **Response Format**: Add new response generators
|
||||
|
||||
### 3. **Performance Optimizations**
|
||||
|
||||
- **Batching Strategy**: Modify `BatchSize` class
|
||||
- **Memory Management**: Add new caching strategies
|
||||
- **Hardware Optimization**: GPU-specific optimizations
|
||||
|
||||
## Security & Best Practices
|
||||
|
||||
### 1. **Secret Management**
|
||||
|
||||
- **Build Secrets**: Docker secrets for HF tokens
|
||||
- **Runtime Secrets**: Environment variable injection
|
||||
- **Token Handling**: Secure authentication patterns
|
||||
|
||||
### 2. **Resource Limits**
|
||||
|
||||
- **Memory Bounds**: Configurable GPU memory limits
|
||||
- **Request Limits**: Concurrency and timeout controls
|
||||
- **Model Safety**: Trust remote code flags
|
||||
|
||||
### 3. **Logging Security**
|
||||
|
||||
- **Sanitization**: No secrets in logs
|
||||
- **Request Logging**: Configurable request/response logging
|
||||
- **Performance Monitoring**: Safe metrics collection
|
||||
|
||||
---
|
||||
|
||||
This guide should be consulted whenever working on the worker-vllm codebase to ensure consistency with established patterns and architectural decisions.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 27 MiB |
Submodule vllm-base-image/vllm deleted from 6a1a31c41e
Reference in New Issue
Block a user