4、vLLM快速上手：使用vLLM在单机GPU上部署一个开源大模型（如Llama-3-8B），完成推理请求测试

在完成了环境准备与基础概念学习之后，本章将正式进入vLLM的实战操作。我们将以Meta开源的Llama-3-8B模型为例，在一台配备单张NVIDIA GPU（建议显存≥24GB）的服务器上，完成从模型下载、vLLM服务启动到推理请求测试的全流程。本章的核心目标是帮助读者建立对vLLM部署的“肌肉记忆”，理解其关键启动参数的含义，并掌握通过OpenAI兼容接口进行文本生成的基本方法。通过本章的学习，你将能够独立完成一个生产级推理服务的初步搭建，为后续Kubernetes容器化部署打下坚实的操作基础。

上图清晰地展示了vLLM部署的三个核心阶段以及内部组件交互关系。在开始操作之前，我们需要明确一个关键点：vLLM的高性能主要来源于其独特的PagedAttention技术，该技术将KV Cache划分为固定大小的块，避免了显存碎片化，从而实现了更高的吞吐量和更灵活的批处理。理解这一点，有助于我们后续在调整--max-model-len和--gpu-memory-utilization参数时，能够知其然更知其所以然。

4.1 模型准备与验证

在启动vLLM服务之前，我们需要确保模型文件已经就绪。虽然vLLM支持从HuggingFace Hub直接加载模型，但在生产环境中，我们通常建议先将模型下载到本地，以避免运行时网络波动带来的风险。

4.1.1 核心原理：模型下载与目录结构

Llama-3-8B模型在HuggingFace上的仓库名为meta-llama/Meta-Llama-3-8B。该模型是一个基于Transformer架构的自回归语言模型，拥有8B参数。下载后的模型目录应包含以下关键文件：

• config.json：模型配置文件，包含模型结构、层数、注意力头数等关键超参数。
• model-00001-of-00004.safetensors：模型权重文件（分片存储），使用safetensors格式，更安全且加载速度更快。
• tokenizer.json 和 tokenizer_config.json：分词器文件，用于将文本转换为模型可理解的token ID序列。
• generation_config.json：生成配置，包含默认的采样参数（如temperature、top_p等）。

4.1.2 操作流程：使用huggingface-cli下载模型

我们推荐使用huggingface-cli工具进行模型下载，它支持断点续传和并发下载，效率远高于git clone。执行以下命令：

# 安装huggingface_hub（如未安装）
pip install -U huggingface_hub

# 登录HuggingFace账号（需输入Access Token）
huggingface-cli login

# 下载模型到指定目录（例如/data/models/）
huggingface-cli download meta-llama/Meta-Llama-3-8B --local-dir /data/models/Meta-Llama-3-8B --local-dir-use-symlinks False

下载完成后，务必检查模型目录的完整性。一个常见的错误是模型文件不完整，导致vLLM启动时报错KeyError或FileNotFoundError。

4.1.3 案例拆解：验证模型文件完整性

假设我们下载完成后，进入模型目录执行ls -lh，预期输出如下：

total 16G
-rw-r--r-- 1 root root  816 May 15 10:30 config.json
-rw-r--r-- 1 root root 4.9G May 15 10:35 model-00001-of-00004.safetensors
-rw-r--r-- 1 root root 4.9G May 15 10:40 model-00002-of-00004.safetensors
-rw-r--r-- 1 root root 4.9G May 15 10:45 model-00003-of-00004.safetensors
-rw-r--r-- 1 root root 4.9G May 15 10:50 model-00004-of-00004.safetensors
-rw-r--r-- 1 root root  556 May 15 10:30 generation_config.json
-rw-r--r-- 1 root root 1.5M May 15 10:30 tokenizer.json
-rw-r--r-- 1 root root  2.4K May 15 10:30 tokenizer_config.json

如果发现某个分片文件大小明显异常（例如只有几KB），则说明下载不完整，需要删除该文件并重新执行下载命令。此外，vLLM在启动时会自动校验模型的SHA256哈希值，如果文件损坏，启动过程会直接报错。

4.2 启动vLLM推理服务

模型准备就绪后，我们即可启动vLLM服务。vLLM提供了两种启动方式：一种是直接使用Python模块命令，另一种是编写Python脚本调用LLM类。对于部署场景，我们推荐使用前者，因为它更简洁且易于通过命令行参数进行配置。

4.2.1 核心原理：关键启动参数解析

vLLM的启动参数众多，但以下参数是我们在单机部署时必须理解和掌握的：

其中，--max-model-len和--gpu-memory-utilization是影响服务稳定性和性能的关键参数。如果max-model-len设置过大，会导致KV Cache预留空间不足，从而触发CUDA out of memory错误；如果设置过小，则无法处理长文本请求。

4.2.2 操作流程：启动服务

在服务器终端执行以下命令启动vLLM服务：

python -m vllm.entrypoints.openai.api_server \
    --model /data/models/Meta-Llama-3-8B \
    --served-model-name llama3-8b \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.95 \
    --tensor-parallel-size 1 \
    --host 0.0.0.0 \
    --port 8000

启动过程中，vLLM会首先加载模型权重，然后初始化KV Cache池。当看到以下日志输出时，表示服务启动成功：

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

4.2.3 案例拆解：显存不足时的调整策略

假设我们在一张24GB显存的A10G GPU上启动服务，但日志报错CUDA out of memory。此时，我们需要分析显存占用情况：

1. 模型权重占用：Llama-3-8B的FP16权重约占用16GB显存。
2. KV Cache预留：vLLM会根据--gpu-memory-utilization参数预留剩余显存。若设置为0.95，则KV Cache可用空间约为(24-16)*0.95≈7.6GB。
3. 计算开销：激活值（Activation）和临时缓冲区也会占用少量显存。

如果--max-model-len设置为8192，每个token的KV Cache大小约为1MB（对于8B模型），那么7.6GB显存大约能支持7800个token的KV Cache，这不足以支撑8192的上下文长度。解决方案有两种：

• 将--max-model-len降低至4096，以减小KV Cache需求。
• 将--gpu-memory-utilization提高至0.98，但需注意这可能会增加显存碎片化的风险。

在实际操作中，我们建议通过nvidia-smi监控显存使用情况，逐步调整参数，找到最优配置。

4.3 推理请求测试

服务启动成功后，我们可以通过HTTP请求进行推理测试。vLLM提供了OpenAI兼容的API接口，这意味着我们可以使用OpenAI的Python SDK或简单的curl命令来发送请求。

4.3.1 核心原理：OpenAI兼容接口

vLLM的API接口与OpenAI的/v1/completions和/v1/chat/completions接口兼容。对于Llama-3-8B这类基础模型，我们通常使用/v1/completions接口进行文本补全测试。请求体中的关键参数包括：

• model：指定使用的模型名称，必须与启动时的--served-model-name一致。
• prompt：输入给模型的文本提示。
• max_tokens：生成的最大token数。
• temperature：采样温度，控制生成的随机性。值越低，输出越确定。

4.3.2 操作流程：使用curl进行测试

我们首先使用curl命令进行一个简单的补全测试：

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3-8b",
    "prompt": "The capital of France is",
    "max_tokens": 32,
    "temperature": 0.7
  }'

预期返回的JSON响应如下：

{
  "id": "cmpl-3f4e5a6b7c8d9e0f",
  "object": "text_completion",
  "created": 1715750000,
  "model": "llama3-8b",
  "choices": [
    {
      "index": 0,
      "text": " Paris. It is known for its art, fashion, and culture. The city is home to",
      "logprobs": null,
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 32,
    "total_tokens": 38
  }
}

在响应中，choices[0].text即为模型生成的文本。usage字段提供了token消耗统计，这对于成本核算和性能监控非常重要。

4.3.3 案例拆解：使用Python SDK进行流式请求

在实际应用中，我们往往需要处理流式响应（即逐token返回），以提升用户体验。以下是一个使用OpenAI Python SDK进行流式请求的示例：

from openai import OpenAI

# 初始化客户端，指向本地vLLM服务
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY"  # vLLM默认不校验API Key，但SDK要求非空
)

# 创建流式补全请求
stream = client.completions.create(
    model="llama3-8b",
    prompt="Write a short poem about AI:",
    max_tokens=128,
    temperature=0.8,
    stream=True  # 启用流式模式
)

# 逐token打印输出
for chunk in stream:
    if chunk.choices[0].text:
        print(chunk.choices[0].text, end="", flush=True)
print()  # 换行

运行上述脚本，你将看到模型逐字生成诗句的效果。流式接口的核心优势在于首token延迟（TTFT）更低，用户无需等待完整生成即可开始阅读。

4.4 性能验证与监控

完成基本推理测试后，我们需要对服务的性能进行初步验证，以确保其满足业务需求。vLLM提供了内置的指标监控接口，同时我们也可以通过简单的脚本测试服务的吞吐量和延迟。

4.4.1 核心原理：性能指标解读

在推理服务中，我们主要关注以下三个核心指标：

vLLM的调度器通过Continuous Batching技术，能够在等待GPU计算的同时处理新到达的请求，从而显著提升吞吐量。但这也意味着，在高并发下，单个请求的延迟可能会有所增加。

4.4.2 操作流程：使用vLLM内置指标

vLLM在启动时会暴露Prometheus格式的监控指标，默认端口为8000，路径为/metrics。我们可以通过以下命令查看关键指标：

curl http://localhost:8000/metrics | grep -E "vllm:num_requests_running|vllm:num_requests_waiting|vllm:gpu_cache_usage_perc"

输出示例：

# HELP vllm:num_requests_running Number of requests currently running.
# TYPE vllm:num_requests_running gauge
vllm:num_requests_running 2.0
# HELP vllm:num_requests_waiting Number of requests waiting to be processed.
# TYPE vllm:num_requests_waiting gauge
vllm:num_requests_waiting 0.0
# HELP vllm:gpu_cache_usage_perc GPU KV cache usage percentage.
# TYPE vllm:gpu_cache_usage_perc gauge
vllm:gpu_cache_usage_perc 0.35

其中，vllm:gpu_cache_usage_perc表示KV Cache的使用率。如果该值长期接近1.0，说明显存资源紧张，可能需要扩容或优化参数。

4.4.3 案例拆解：并发测试与结果分析

为了验证服务的并发处理能力，我们编写一个简单的Python脚本，模拟10个并发请求：

import concurrent.futures
import time
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

def send_request(prompt):
    start = time.time()
    response = client.completions.create(
        model="llama3-8b",
        prompt=prompt,
        max_tokens=64,
        temperature=0.5
    )
    latency = time.time() - start
    return latency, response.usage.total_tokens

prompts = ["Explain quantum computing in simple terms."] * 10

with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
    futures = [executor.submit(send_request, p) for p in prompts]
    results = [f.result() for f in futures]

total_tokens = sum(r[1] for r in results)
total_time = max(r[0] for r in results)  # 取最大延迟作为总耗时
throughput = total_tokens / total_time
avg_latency = sum(r[0] for r in results) / len(results)

print(f"总耗时: {total_time:.2f}s")
print(f"平均延迟: {avg_latency:.2f}s")
print(f"吞吐量: {throughput:.2f} tokens/s")

运行结果示例：

总耗时: 4.23s
平均延迟: 3.87s
吞吐量: 151.30 tokens/s

通过这个测试，我们可以初步评估服务的性能基线。如果吞吐量远低于预期，我们需要检查GPU利用率（使用nvidia-smi）和KV Cache使用率，判断是否存在显存瓶颈或参数配置不合理。