vLLM官方中文教程：快速入门

官方英文原文链接：https://docs.vllm.ai/en/stable/getting_started/quickstart.html

快速开始

本指南将帮助您快速开始使用 vLLM 执行以下两个任务：

• 离线批量推理
• 使用兼容 OpenAI 的服务器提供在线服务

环境依赖

• 操作系统：Linux
• Python版本：3.9 - 3.12

安装vLLM

如果使用英伟达™（NVIDIA®）GPU，可以直接使用 pip 安装 vLLM。

建议使用 uv（一个非常快速的 Python 环境管理器）来创建和管理 Python 环境。请按照文档安装 uv。安装 uv 后，可以使用以下命令创建新的 Python 环境并安装 vLLM：

uv venv myenv --python 3.12 --seed
source myenv/bin/activate
uv pip install vllm

您还可以使用 conda 创建和管理 Python 环境。

conda create -n myenv python=3.12 -y
conda activate myenv
pip install vllm

注意：对于非 CUDA 平台，有关如何安装 vLLM 的具体说明，请参阅此处安装指引。

离线批量推理

安装 vLLM 后，您就可以开始为输入的提示词列表生成文本（即离线批量推理）。请参阅示例脚本：examples/offline_inference/basic/basic.py，脚本如下

该示例的第一行导入了 LLM 和 SamplingParams 这两个类：

• LLM 是使用 vLLM 引擎运行离线推理的主要类。
• SamplingParams 指定了采样过程的参数。

from vllm import LLM, SamplingParams

下一节定义了文本生成的输入提示和采样参数列表。采样温度设置为 0.8，核采样概率设置为 0.95。有关采样参数的更多信息，请点击此处。

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 从 HuggingFace 下载模型。如果您想使用来自 ModelScope 的模型，请在初始化引擎前设置环境变量 VLLM_USE_MODELSCOPE。

现在，使用 llm.generate 生成输出。它将输入提示添加到 vLLM 引擎的等待队列中，并执行 vLLM 引擎以高吞吐量的方式生成输出。输出以 RequestOutput 对象列表的形式返回，其中包括所有输出标记tokens。

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}")

提供在线服务

vLLM 可以作为实现 OpenAI API 协议的服务器来部署。这样，vLLM 就能直接替代使用 OpenAI API 的应用程序。默认情况下，它会在 http://localhost:8000 上启动服务器。你可以使用 --host 和 --port 参数指定地址。目前，服务器只能托管一个模型，并实现了如下接口功能：list models,create chat completion, create completion

运行以下命令，使用 Qwen2.5-1.5B-Instruct 模型启动 vLLM 服务器：

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

注意：默认情况下，服务器使用存储在tokenizer中的预定义聊天模板。您可以在此了解如何重载该模板。

该服务器的查询格式与 OpenAI API 相同。例如，返回可用模型列表：

curl http://localhost:8000/v1/models

您可以通过参数 --api-key 或环境变量 VLLM_API_KEY，让服务器检查接口请求头中的 API 密钥。

使用 vLLM 的 OpenAI Completions 接口

服务器启动后，您可以通过输入提示词来进行模型推理：

curl http://localhost: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 = "http://localhost: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，代码如下：

# SPDX-License-Identifier: Apache-2.0

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 = "http://localhost:8000/v1"

client = OpenAI(
    # defaults to os.environ.get("OPENAI_API_KEY")
    api_key=openai_api_key,
    base_url=openai_api_base,
)

models = client.models.list()
model = models.data[0].id

# Completion API
stream = False
completion = client.completions.create(
    model=model,
    prompt="A robot may not injure a human being",
    echo=False,
    n=2,
    stream=stream,
    logprobs=3)

print("Completion results:")
if stream:
    for c in completion:
        print(c)
else:
    print(completion)

使用 vLLM 的 OpenAI Chat Completions 接口

vLLM 还支持 OpenAI Chat Completions API。聊天界面是一种与模型进行交流的更动态、更互动的方式，允许进行可存储在聊天历史记录中的来回交流。这对于需要上下文或更详细解释的任务非常有用。

您可以使用 create chat completions 接口 与模型进行交互：

curl http://localhost: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 = "http://localhost: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)

使用docker部署

使用 vLLM 的官方 Docker 镜像

vLLM 提供用于部署的官方 Docker 映像。该镜像可用于运行兼容 OpenAI 的服务器，并以 vllm/vllm-openai 的形式出现在 Docker Hub 上。

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HUGGING_FACE_HUB_TOKEN=<secret>" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model mistralai/Mistral-7B-v0.1

您可以在图像标记 (vllm/vllm-openai:latest) 后添加任何其他引擎参数。

注意：可以使用 --ipc=host 标志或 --shm-size 标志允许容器访问主机的共享内存。vLLM 使用 PyTorch，它使用共享内存在进程间共享数据，尤其适用于张量并行推理。

从源代码构建 vLLM 的 Docker 镜像

您可以通过提供的 Dockerfile 从源代码构建和运行 vLLM。构建 vLLM：

# optionally specifies: --build-arg max_jobs=8 --build-arg nvcc_threads=2
DOCKER_BUILDKIT=1 docker build . --target vllm-openai --tag vllm/vllm-openai

默认情况下，vLLM 将为所有 GPU 类型构建，以实现最广泛的分布。如果只为当前机器运行的 GPU 类型构建，可以添加参数 --build-arg torch_cuda_arch_list=“”，让 vLLM 查找当前 GPU 类型并为其构建。

如果您使用的是 Podman 而不是 Docker，可能需要在运行 podman 生成命令时添加 --security-opt label=disable 来禁用 SELinux 标签，以避免某些现有问题。

使用定制的 vLLM Docker 映像

使用定制的 Docker 镜像运行 vLLM：

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HUGGING_FACE_HUB_TOKEN=<secret>" \
    vllm/vllm-openai <args...>

参数 vllm/vllm-openai 指定要运行的映像，并应替换为自定义构建的映像名称（构建命令中的 -t 标记）。

仅适用于 0.4.1 和 0.4.2 版本–这些版本下的 vLLM docker 镜像应该在根用户下运行，因为在运行时需要加载根用户主目录下的一个库，即 /root/.config/vllm/nccl/cu12/libnccl.so.2.18.1。

如果在不同用户下运行容器，可能需要先更改库（以及所有父目录）的权限，允许用户访问，然后使用环境变量 VLLM_NCCL_SO_PATH=/root/.config/vllm/nccl/cu12/libnccl.so.2.18.1 运行 vLLM。

使用Kubernetes部署

使用 Kubernetes 部署 vLLM 是一种可扩展且高效的机器学习模型服务方式。本文将指导您完成使用 Kubernetes 部署 vLLM 的过程，包括必要的前提条件、部署步骤和测试。

前置条件

在开始之前，请确保您具备以下条件：

• 运行中的 Kubernetes 集群
• 英伟达 Kubernetes 设备插件（k8s-device-plugin）： 请访问 https://github.com/NVIDIA/k8s-device-plugin/
• 集群中可用的 GPU 资源

部署步骤

1. 为 vLLM 创建 PVC、Secret 和 Deployment
   PVC 用于存储模型缓存，它是可选的，你可以使用 hostPath 或其他存储选项

PVC是PersistentVolumeClaim的缩写，它是Kubernetes中的一个资源对象，用于申请和使用持久化存储。在Kubernetes集群中，PVC扮演着类似“存储请求”的角色，它是由用户创建的，旨在绑定到某个合适的PersistentVolume（PV），从而为Pod提供持久化存储。
概念上，PVC允许用户无需关心底层存储技术的具体实现细节，就能方便地请求所需的存储资源。用户定义PVC时会指定存储的大小、访问模式等参数，而管理员则负责提供匹配这些声明的PersistentVolumes。一旦PVC与PV成功绑定，Pod就可以通过这个PVC来使用该持久化存储资源了。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mistral-7b
  namespace: default
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi
  storageClassName: default
  volumeMode: Filesystem

Secret是可选项，只有访问gated门控模型时才需要，如果不使用门控模型，可以跳过此步骤

apiVersion: v1
kind: Secret
metadata:
  name: hf-token-secret
  namespace: default
type: Opaque
stringData:
  token: "REPLACE_WITH_TOKEN"

接下来为 vLLM 创建deployment文件，以便运行模型服务器。下面的示例部署了 Mistral-7B-Instruct-v0.3 模型。

下面是使用 NVIDIA GPU 和 AMD GPU 的两个示例。

NVIDIA GPU:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mistral-7b
  namespace: default
  labels:
    app: mistral-7b
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mistral-7b
  template:
    metadata:
      labels:
        app: mistral-7b
    spec:
      volumes:
      - name: cache-volume
        persistentVolumeClaim:
          claimName: mistral-7b
      # vLLM needs to access the host's shared memory for tensor parallel inference.
      - name: shm
        emptyDir:
          medium: Memory
          sizeLimit: "2Gi"
      containers:
      - name: mistral-7b
        image: vllm/vllm-openai:latest
        command: ["/bin/sh", "-c"]
        args: [
          "vllm serve mistralai/Mistral-7B-Instruct-v0.3 --trust-remote-code --enable-chunked-prefill --max_num_batched_tokens 1024"
        ]
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token-secret
              key: token
        ports:
        - containerPort: 8000
        resources:
          limits:
            cpu: "10"
            memory: 20G
            nvidia.com/gpu: "1"
          requests:
            cpu: "2"
            memory: 6G
            nvidia.com/gpu: "1"
        volumeMounts:
        - mountPath: /root/.cache/huggingface
          name: cache-volume
        - name: shm
          mountPath: /dev/shm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 60
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 60
          periodSeconds: 5

AMD GPU:
如果使用 MI300X 等 AMD ROCm GPU，可以参考下面的 deployment.yaml。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mistral-7b
  namespace: default
  labels:
    app: mistral-7b
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mistral-7b
  template:
    metadata:
      labels:
        app: mistral-7b
    spec:
      volumes:
      # PVC
      - name: cache-volume
        persistentVolumeClaim:
          claimName: mistral-7b
      # vLLM needs to access the host's shared memory for tensor parallel inference.
      - name: shm
        emptyDir:
          medium: Memory
          sizeLimit: "8Gi"
      hostNetwork: true
      hostIPC: true
      containers:
      - name: mistral-7b
        image: rocm/vllm:rocm6.2_mi300_ubuntu20.04_py3.9_vllm_0.6.4
        securityContext:
          seccompProfile:
            type: Unconfined
          runAsGroup: 44
          capabilities:
            add:
            - SYS_PTRACE
        command: ["/bin/sh", "-c"]
        args: [
          "vllm serve mistralai/Mistral-7B-v0.3 --port 8000 --trust-remote-code --enable-chunked-prefill --max_num_batched_tokens 1024"
        ]
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token-secret
              key: token
        ports:
        - containerPort: 8000
        resources:
          limits:
            cpu: "10"
            memory: 20G
            amd.com/gpu: "1"
          requests:
            cpu: "6"
            memory: 6G
            amd.com/gpu: "1"
        volumeMounts:
        - name: cache-volume
          mountPath: /root/.cache/huggingface
        - name: shm
          mountPath: /dev/shm

您可以从ROCM/K8S-Device-Plugin中获得步骤和YAML文件的完整示例。

2. 为 vLLM 创建 Kubernetes 服务
   接下来，创建一个 Kubernetes 服务文件，用于暴露 mistral-7b 这个deployment服务：

apiVersion: v1
kind: Service
metadata:
  name: mistral-7b
  namespace: default
spec:
  ports:
  - name: http-mistral-7b
    port: 80
    protocol: TCP
    targetPort: 8000
  # The label selector should match the deployment labels & it is useful for prefix caching feature
  selector:
    app: mistral-7b
  sessionAffinity: None
  type: ClusterIP

3. 部署和测试
   使用 kubectl apply -f <文件名> 应用部署和服务配置：

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

要测试部署，请运行以下 curl 命令：

curl http://mistral-7b.default.svc.cluster.local/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.3",
        "prompt": "San Francisco is a",
        "max_tokens": 7,
        "temperature": 0
      }'

如果服务部署正确，您应该会收到来自 vLLM 模型的响应。

使用Nginx部署

本章节展示了如何启动多个 vLLM 服务容器，并使用 Nginx 作为服务器之间的负载平衡器。

构建 Nginx 容器

本指南假定您刚刚克隆了 vLLM 项目，并且当前位于 vllm 根目录下。

export vllm_root=`pwd`

创建名为 Dockerfile.nginx 的文件：

FROM nginx:latest
RUN rm /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

构建容器：

docker build . -f Dockerfile.nginx --tag nginx-lb

创建简单的 Nginx 配置文件

创建名为 nginx_conf/nginx.conf 的文件。注意，你可以添加任意数量的服务器。在下面的示例中，我们先添加两个服务器。要添加更多服务器，请添加另一个服务器 vllmN:8000 max_fails=3 fail_timeout=10000s 到upstream backend里面

upstream backend {
    least_conn;
    server vllm0:8000 max_fails=3 fail_timeout=10000s;
    server vllm1:8000 max_fails=3 fail_timeout=10000s;
}
server {
    listen 80;
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

构建 vLLM 容器

cd $vllm_root
docker build -f Dockerfile . --tag vllm

如果你使用的是代理，可以将代理设置传递给 docker build 命令，如下图所示：

cd $vllm_root
docker build -f Dockerfile . --tag vllm --build-arg http_proxy=$http_proxy --build-arg https_proxy=$https_proxy

创建 Docker 网络

docker network create vllm_nginx

启动 vLLM 容器

注意：

• 如果您在其他地方缓存了 HuggingFace 模型，请更新下面的 hf_cache_dir。
• 如果您没有现有的 HuggingFace 缓存，则需要启动 vllm0 并等待模型下载完成和服务器准备就绪。这将确保 vllm1 可以使用刚刚下载的模型，而无需再次下载。
• 下面的示例假定使用的是 GPU 。如果使用的是 CPU ，请移除 --gpus all，并在 docker run 命令中添加 VLLM_CPU_KVCACHE_SPACE 和 VLLM_CPU_OMP_THREADS_BIND 环境变量。
• 如果不想使用 Llama-2-7b-chat-hf，请调整 vLLM 服务器中要使用的模型名称。

mkdir -p ~/.cache/huggingface/hub/
hf_cache_dir=~/.cache/huggingface/
docker run -itd --ipc host --privileged --network vllm_nginx --gpus all --shm-size=10.24gb -v $hf_cache_dir:/root/.cache/huggingface/ -p 8081:8000 --name vllm0 vllm --model meta-llama/Llama-2-7b-chat-hf
docker run -itd --ipc host --privileged --network vllm_nginx --gpus all --shm-size=10.24gb -v $hf_cache_dir:/root/.cache/huggingface/ -p 8082:8000 --name vllm1 vllm --model meta-llama/Llama-2-7b-chat-hf

注意：如果使用代理，可以通过 -e http_proxy=$htt{p}_{p}roxy-ehttp{s}_{p}roxy=$https_proxy，将代理设置传递给 docker run 命令。

启动 Nginx

docker run -itd -p 8000:80 --network vllm_nginx -v ./nginx_conf/:/etc/nginx/conf.d/ --name nginx-lb nginx-lb:latest

验证 vLLM 服务器是否准备就绪

docker logs vllm0 | grep Uvicorn
docker logs vllm1 | grep Uvicorn

两个输出应该是这样的

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)