RoadMap 写的是“部署一个 7B 模型”。这里用 Qwen/Qwen2.5-7B-Instruct 作为默认练习模型: 它是开放模型,适合中文实验,也能走标准 chat template。 如果显存不足,先把 --max-model-len 降到 2048/4096, 或暂时换 1.5B 模型把服务链路跑通。

环境检查

nvidia-smi
python --version
pip --version

# 可选:新建虚拟环境
python -m venv .venv-vllm
source .venv-vllm/bin/activate

pip install -U pip
pip install -U vllm openai

# 如果模型需要授权,先登录 Hugging Face
huggingface-cli login

vLLM 的在线服务入口是 vllm serve。 它会拉起兼容 OpenAI 协议的 HTTP 服务,默认端口是 8000。 生产环境会有反向代理、鉴权、限流和多实例;今天先把单实例跑稳。

最小启动命令

export MODEL=Qwen/Qwen2.5-7B-Instruct

vllm serve ${MODEL} \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name qwen2.5-7b \
  --dtype bfloat16 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.85 \
  --max-num-seqs 64 \
  --api-key local-dev-key

用配置文件启动

# config.yaml
model: Qwen/Qwen2.5-7B-Instruct
host: 0.0.0.0
port: 8000
served-model-name: qwen2.5-7b
dtype: bfloat16
max-model-len: 4096
gpu-memory-utilization: 0.85
max-num-seqs: 64
api-key: local-dev-key

# 启动
vllm serve --config config.yaml

vLLM 的价值之一是把本地开源模型伪装成一个 OpenAI-compatible endpoint。 上层应用只要把 base_url 指向本地服务, 多数 Chat Completions 调用就能复用原来的客户端代码。

列出模型

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer local-dev-key"

Chat Completions

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer local-dev-key" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [
      {"role": "system", "content": "你是一个简洁的 AI Infra 助教。"},
      {"role": "user", "content": "用三点解释 vLLM 为什么适合 LLM 推理服务。"}
    ],
    "temperature": 0.2,
    "max_tokens": 256
  }'

Streaming

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer local-dev-key" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [{"role": "user", "content": "解释 TTFT 和 TPOT 的区别。"}],
    "stream": true,
    "max_tokens": 128
  }'

OpenAI Python SDK

from openai import OpenAI
import time

client = OpenAI(
    api_key="local-dev-key",
    base_url="http://localhost:8000/v1",
)

start = time.perf_counter()
stream = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[
        {"role": "user", "content": "给我一个 vLLM 调参检查清单。"},
    ],
    temperature=0.2,
    max_tokens=256,
    stream=True,
)

first = None
token_count = 0
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    if delta and first is None:
        first = time.perf_counter()
    token_count += 1 if delta else 0
    print(delta, end="", flush=True)

end = time.perf_counter()
print()
print({"ttft_s": first - start if first else None, "elapsed_s": end - start, "chunks": token_count})

RoadMap 点名的两个参数分别控制不同资源: --gpu-memory-utilization 决定 vLLM 实例可使用的 GPU 显存预算, 进而影响 KV Cache 可分配空间; --max-num-seqs 限制单次调度迭代能处理的序列数量, 影响并发、batching、CUDA graph 捕获规模和延迟。

实验矩阵

# 每组只改一个变量,记录启动日志、显存、吞吐、TTFT/TPOT

gpu_memory_utilization: [0.80, 0.85, 0.90, 0.92]
max_num_seqs: [16, 32, 64, 128]
max_model_len: [2048, 4096, 8192]

report:
  model: qwen2.5-7b
  gpu: "A10 24GB / L40S 48GB / A100 80GB ..."
  vllm_version: "..."
  prompt_len: 512
  output_len: 128
  concurrency: [1, 4, 16, 32]
  metrics:
    - p50_ttft_ms
    - p95_ttft_ms
    - p50_tpot_ms
    - output_tokens_per_s
    - gpu_memory_used_gb
    - oom_or_preemption

上线前至少要压三种负载:短 prompt 短输出、长 prompt 短输出、短 prompt 长输出。 这三类分别压到不同阶段:调度开销、prefill、decode 和 KV Cache。

轻量压测脚本

import asyncio
import time
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key="local-dev-key", base_url="http://localhost:8000/v1")

async def one_request(i, prompt):
    t0 = time.perf_counter()
    resp = await client.chat.completions.create(
        model="qwen2.5-7b",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.0,
        max_tokens=128,
    )
    dt = time.perf_counter() - t0
    text = resp.choices[0].message.content
    return {"id": i, "latency_s": dt, "chars": len(text)}

async def main(concurrency=16):
    prompt = "用 5 条 bullet 总结 vLLM 调参方法。"
    tasks = [one_request(i, prompt) for i in range(concurrency)]
    results = await asyncio.gather(*tasks)
    lat = sorted(r["latency_s"] for r in results)
    print({
        "concurrency": concurrency,
        "p50_s": lat[len(lat)//2],
        "p95_s": lat[int(len(lat)*0.95) - 1],
        "max_s": lat[-1],
    })

asyncio.run(main(concurrency=32))

1. 写出你今天的 vllm serve 启动命令,解释每个关键参数的作用。
2. --gpu-memory-utilization 调大后,KV Cache、并发和 OOM 风险分别如何变化?
3. --max-num-seqs 和 batch size 是什么关系?为什么它会影响 TPOT?
4. 如何验证 OpenAI 兼容 API 的模型名、鉴权和 streaming 都正常?
5. 设计一个调参实验矩阵:你会固定哪些变量,记录哪些指标?
6. 如果 p95 TTFT 变差但 tokens/s 变高,你会如何判断这个参数配置能不能上线?