跳到內容

快速入門

本指南將幫助您快速開始使用 vLLM 進行

先決條件

  • 作業系統:Linux
  • Python:3.9 - 3.12

安裝

如果您正在使用 NVIDIA GPU,可以直接使用 pip 安裝 vLLM。

建議使用 uv(一個非常快的 Python 環境管理器)來建立和管理 Python 環境。請遵循 文件 安裝 uv。安裝 uv 後,您可以使用以下命令建立新的 Python 環境並安裝 vLLM:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

uv 可以透過 --torch-backend=auto(或 UV_TORCH_BACKEND=auto)在執行時檢查已安裝的 CUDA 驅動版本,從而自動選擇合適的 PyTorch 後端。要選擇特定的後端(例如 cu126),請設定 --torch-backend=cu126(或 UV_TORCH_BACKEND=cu126)。

另一種便捷的方法是使用 uv run 配合 --with [dependency] 選項,這允許您執行諸如 vllm serve 這樣的命令而無需建立任何永久環境。

uv run --with vllm vllm --help

您也可以使用 conda 來建立和管理 Python 環境。如果希望在 conda 環境中管理 uv,可以透過 pip 將其安裝到 conda 環境中。

conda create -n myenv python=3.12 -y
conda activate myenv
pip install --upgrade uv
uv pip install vllm --torch-backend=auto

注意

有關 vLLM 安裝的更多詳細資訊和非 CUDA 平臺,請參閱此處的特定說明。

離線批次推理

安裝 vLLM 後,您可以開始為一系列輸入提示生成文字(即離線批次推理)。請參閱示例指令碼: examples/offline_inference/basic/basic.py

此示例的第一行匯入了類 LLMSamplingParams

  • LLM 是使用 vLLM 引擎執行離線推理的主要類。
  • SamplingParams 指定了取樣過程的引數。
from vllm import LLM, SamplingParams

下一節定義了一系列輸入提示和用於文字生成的取樣引數。取樣溫度設定為 0.8核取樣機率設定為 0.95。您可以在此處找到有關取樣引數的更多資訊。

重要

預設情況下,如果 Hugging Face 模型倉庫中存在 generation_config.json 檔案,vLLM 將使用模型建立者推薦的取樣引數。在大多數情況下,如果未指定 SamplingParams,這將為您提供最佳的預設結果。

但是,如果偏好 vLLM 的預設取樣引數,請在建立 LLM 例項時設定 generation_config="vllm"

prompts = [
    "Hello, my name is",
    "The president of the United States is",
    "The capital of France is",
    "The future of AI is",
]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

LLM 類初始化了 vLLM 的引擎和 OPT-125M 模型用於離線推理。支援的模型列表可以在此處找到。

llm = LLM(model="facebook/opt-125m")

注意

預設情況下,vLLM 從 Hugging Face 下載模型。如果您希望使用 ModelScope 的模型,請在初始化引擎之前設定環境變數 VLLM_USE_MODELSCOPE

export VLLM_USE_MODELSCOPE=True

現在,有趣的部分來了!輸出透過 llm.generate 生成。它將輸入提示新增到 vLLM 引擎的等待佇列中,並執行 vLLM 引擎以高吞吐量生成輸出。輸出以 RequestOutput 物件的列表形式返回,其中包括所有輸出標記。

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

相容 OpenAI 的伺服器

vLLM 可以部署為實現 OpenAI API 協議的伺服器。這使得 vLLM 可以作為使用 OpenAI API 的應用程式的即插即用替代品。預設情況下,它在 https://:8000 啟動伺服器。您可以使用 --host--port 引數指定地址。伺服器目前一次託管一個模型,並實現了諸如列出模型建立聊天補全建立補全等端點。

執行以下命令,使用 Qwen2.5-1.5B-Instruct 模型啟動 vLLM 伺服器

vllm serve Qwen/Qwen2.5-1.5B-Instruct

注意

預設情況下,伺服器使用儲存在分詞器中的預定義聊天模板。您可以在此處瞭解如何覆蓋它。

重要

預設情況下,如果 huggingface 模型倉庫中存在 generation_config.json,伺服器將應用它。這意味著某些取樣引數的預設值可以被模型建立者推薦的值覆蓋。

要停用此行為,請在啟動伺服器時傳遞 --generation-config vllm

該伺服器可以與 OpenAI API 相同的格式進行查詢。例如,列出模型:

curl https://:8000/v1/models

您可以透過傳入引數 --api-key 或環境變數 VLLM_API_KEY 來使伺服器檢查 HTTP 頭中的 API 金鑰。

使用 vLLM 的 OpenAI Completions API

伺服器啟動後,您可以使用輸入提示查詢模型:

curl https://:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2.5-1.5B-Instruct",
        "prompt": "San Francisco is a",
        "max_tokens": 7,
        "temperature": 0
    }'

由於此伺服器與 OpenAI API 相容,您可以將其作為任何使用 OpenAI API 的應用程式的即插即用替代品。例如,另一種查詢伺服器的方式是透過 openai Python 包:

程式碼
from openai import OpenAI

# Modify OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "https://:8000/v1"
client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)
completion = client.completions.create(model="Qwen/Qwen2.5-1.5B-Instruct",
                                    prompt="San Francisco is a")
print("Completion result:", completion)

更詳細的客戶端示例可以在這裡找到: examples/online_serving/openai_completion_client.py

使用 vLLM 的 OpenAI Chat Completions API

vLLM 也被設計為支援 OpenAI Chat Completions API。聊天介面是一種更動態、互動性更強的方式與模型進行通訊,允許來回對話並存儲在聊天曆史中。這對於需要上下文或更詳細解釋的任務非常有用。

您可以使用建立聊天補全端點與模型進行互動:

curl https://:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2.5-1.5B-Instruct",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Who won the world series in 2020?"}
        ]
    }'

或者,您可以使用 openai Python 包:

程式碼
from openai import OpenAI
# Set OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "https://:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

chat_response = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me a joke."},
    ]
)
print("Chat response:", chat_response)

關於 Attention 後端

目前,vLLM 支援多種後端,可在不同平臺和加速器架構上高效進行注意力計算。它會自動選擇與您的系統和模型規範相容的最佳效能後端。

如果需要,您也可以透過將環境變數 VLLM_ATTENTION_BACKEND 配置為以下選項之一來手動設定您選擇的後端:FLASH_ATTNFLASHINFERXFORMERS

警告

沒有包含 Flash Infer 的預構建 vLLM wheel 檔案,因此您必須先在環境中安裝它。請參閱 Flash Infer 官方文件 或檢視 docker/Dockerfile 以獲取安裝說明。