快速入門¶
本指南將幫助您快速開始使用 vLLM 進行
先決條件¶
- 作業系統:Linux
- Python:3.9 - 3.12
安裝¶
如果您正在使用 NVIDIA GPU,可以直接使用 pip 安裝 vLLM。
建議使用 uv(一個非常快的 Python 環境管理器)來建立和管理 Python 環境。請遵循 文件 安裝 uv
。安裝 uv
後,您可以使用以下命令建立新的 Python 環境並安裝 vLLM:
uv
可以透過 --torch-backend=auto
(或 UV_TORCH_BACKEND=auto
)在執行時檢查已安裝的 CUDA 驅動版本,從而自動選擇合適的 PyTorch 後端。要選擇特定的後端(例如 cu126
),請設定 --torch-backend=cu126
(或 UV_TORCH_BACKEND=cu126
)。
另一種便捷的方法是使用 uv run
配合 --with [dependency]
選項,這允許您執行諸如 vllm serve
這樣的命令而無需建立任何永久環境。
您也可以使用 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
此示例的第一行匯入了類 LLM 和 SamplingParams。
- LLM 是使用 vLLM 引擎執行離線推理的主要類。
- 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 模型用於離線推理。支援的模型列表可以在此處找到。
注意
預設情況下,vLLM 從 Hugging Face 下載模型。如果您希望使用 ModelScope 的模型,請在初始化引擎之前設定環境變數 VLLM_USE_MODELSCOPE
。
現在,有趣的部分來了!輸出透過 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 伺服器
注意
預設情況下,伺服器使用儲存在分詞器中的預定義聊天模板。您可以在此處瞭解如何覆蓋它。
重要
預設情況下,如果 huggingface 模型倉庫中存在 generation_config.json
,伺服器將應用它。這意味著某些取樣引數的預設值可以被模型建立者推薦的值覆蓋。
要停用此行為,請在啟動伺服器時傳遞 --generation-config vllm
。
該伺服器可以與 OpenAI API 相同的格式進行查詢。例如,列出模型:
您可以透過傳入引數 --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_ATTN
、FLASHINFER
或 XFORMERS
。
警告
沒有包含 Flash Infer 的預構建 vLLM wheel 檔案,因此您必須先在環境中安裝它。請參閱 Flash Infer 官方文件 或檢視 docker/Dockerfile 以獲取安裝說明。