vllm-server

vLLM 服务管理

使用 vLLM 部署可用于生产环境的大模型推理服务——vLLM 是速度最快的开源大模型服务引擎，采用 PagedAttention 和连续批处理技术。

何时使用此技能

在以下情况下使用此技能：

• 大规模提供开源大模型（Llama、Mistral、Qwen、Gemma）服务
• 为可自托管模型构建兼容 OpenAI 的 API 端点
• 针对生产流量优化大模型吞吐量和延迟
• 使用张量并行或流水线并行运行多 GPU 推理
• 部署量化模型以降低 GPU 显存需求

前提条件

• 配备 CUDA 12.1+ 的 NVIDIA GPU（生产环境推荐 A100/H100）
• Docker，或安装了 pip 的 Python 3.9+
• 70B 模型需要 40GB+ VRAM；7B 模型需要 8GB+ VRAM
• 使用 Docker GPU 直通时需要 nvidia-container-toolkit

快速开始

# Install vLLM
pip install vllm

# Serve a model (OpenAI-compatible API)
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --api-key your-secret-key

# Test the endpoint
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Docker 部署

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --api-key your-secret-key

Docker Compose（生产环境）

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - model-cache:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    command: >
      --model meta-llama/Llama-3.1-70B-Instruct
      --tensor-parallel-size 2
      --max-model-len 32768
      --gpu-memory-utilization 0.90
      --api-key ${VLLM_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  model-cache:

关键配置选项

多 GPU 张量并行

# Split one model across 4 GPUs
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.90

量化（降低 VRAM 占用）

# AWQ quantization (70B on 2x A100 40GB)
vllm serve casperhansen/llama-3-70b-instruct-awq \
  --quantization awq \
  --tensor-parallel-size 2

# GPTQ quantization
vllm serve TheBloke/Llama-2-70B-Chat-GPTQ \
  --quantization gptq

# FP8 (H100 NVL native)
vllm serve meta-llama/Llama-3.1-405B-Instruct \
  --quantization fp8 \
  --tensor-parallel-size 8

结构化输出与工具

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-auto-tool-choice \
  --tool-call-parser llama3_json \
  --guided-decoding-backend outlines

LoRA 适配器

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-lora \
  --lora-modules sql-lora=/path/to/sql-lora \
                 code-lora=/path/to/code-lora \
  --max-lora-rank 64

性能调优

# Maximize throughput for batch workloads
vllm serve <model> \
  --max-num-seqs 256 \          # max concurrent sequences
  --max-num-batched-tokens 8192 \ # tokens per batch
  --gpu-memory-utilization 0.95 \ # use 95% VRAM
  --swap-space 4                  # CPU swap (GiB)

# Minimize latency for interactive use
vllm serve <model> \
  --max-num-seqs 32 \
  --enforce-eager              # disable CUDA graph capture

基准测试

# Install benchmark tool
pip install vllm

# Run throughput benchmark
python -m vllm.entrypoints.openai.run_batch \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --input-file prompts.jsonl \
  --output-file results.jsonl

# Benchmark with vllm bench
vllm bench throughput \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --num-prompts 1000 \
  --input-len 512 \
  --output-len 128

监控

# Check running server stats
curl http://localhost:8000/metrics  # Prometheus metrics

# Key metrics to watch:
# vllm:num_requests_running       - active requests
# vllm:gpu_cache_usage_perc       - KV cache utilization
# vllm:generation_tokens_per_s    - throughput
# vllm:time_to_first_token_ms     - TTFT latency
# vllm:e2e_request_latency_seconds - end-to-end latency

常见问题

问题	原因	解决方法
CUDA out of memory	模型对 VRAM 来说太大	添加 --quantization awq 或降低 --gpu-memory-utilization
冷启动缓慢	模型未缓存	使用 huggingface-cli download <model> 预先下载
吞吐量低	并发请求太少	增大 --max-num-seqs
KV 缓存已满错误	上下文长度过长	调低 --max-model-len
tokenizer error	分词器不匹配	使用 --tokenizer 指定正确的分词器

最佳实践

• 使用 --gpu-memory-utilization 0.90，为 CUDA 内核留出余量。
• 使用 --revision 固定模型版本，确保部署可复现。
• 在生产环境中设置 HF_HUB_OFFLINE=1，避免意外下载。
• 优先使用 AWQ 或 GPTQ 量化，再进行张量并行——先降低 VRAM 占用。
• 对长上下文工作负载启用 --enable-chunked-prefill。
• 监控 gpu_cache_usage_perc——超过 95% 会导致排队。

相关技能

• 大模型推理扩缩容 - 自动扩缩 vLLM 部署
• GPU 服务器管理 - GPU 驱动设置
• 大模型网关 - 在多个 vLLM 实例之间进行负载均衡
• 大模型成本优化 - 成本管理
• 模型服务 Kubernetes 部署 - K8s 部署