从 Docker Run 到生产级部署：vLLM推理大模型服务的 Docker Compose 完整实战指南

作者：ceagle
适用读者：AI 工程师、DevOps 工程师、后端开发者，以及希望将大模型推理服务容器化部署的技术人员
技术栈：vLLM v0.12.0、Docker Compose、NVIDIA GPU、AWQ 量化模型、OpenAI 兼容 API
字数：约 4,200 字
阅读时间：15-20 分钟

一、引言：为什么需要将 vLLM 从 Docker Run 升级到 Compose？

在大模型推理服务的部署实践中，我们常常从简单的 docker run 命令开始。然而，当服务需要进入生产环境时，这种单命令方式暴露出诸多局限：

配置硬编码：模型路径、参数无法动态调整
环境隔离缺失：与其他服务（如 Dify、Nginx）难以通信
维护成本高：重启、更新、监控缺乏标准化流程
扩展性差：无法轻松实现多模型并行部署

本文将通过一个真实场景，完整演示如何将 vLLM 服务从原始 docker run 命令升级为生产级 Docker Compose 配置，解决 GPU 识别、网络隔离、命名冲突等关键问题，并提供 API 调用和性能测试的最佳实践。

核心价值：通过本文，你将获得一个可直接用于生产环境的 vLLM 部署方案，避免踩坑，提升部署效率。

二、前置依赖：确保环境就绪

在开始前，请确认你的环境满足以下要求：

硬件要求

NVIDIA GPU：计算能力 ≥ 7.0（如 Tesla V100、A10、RTX 3090/4090）
GPU 显存：≥ 16GB（8B 模型 AWQ 量化后约需 6-8GB）
系统内存：≥ 32GB
共享内存：≥ 2GB（通过 --shm-size 配置）

软件要求

# Docker Engine (支持 --gpus 参数)
$ docker version
Client: Docker Engine - Community
 Version:           24.0.7

# NVIDIA Container Toolkit (已验证支持 --gpus all)
$ docker run --rm --gpus all nvidia/cuda:12.2-base nvidia-smi

# Docker Compose V2 (关键!)
$ docker compose version
Docker Compose version v2.24.5

模型准备

模型格式：AWQ 量化模型（4-bit）
模型路径：/data/models/DeepSeek-R1-Distill-Llama-8B_AWQ/

目录结构：

/data/models/DeepSeek-R1-Distill-Llama-8B_AWQ/
├── config.json
├── tokenizer.json
├── quant_config.json
├── awq_model.safetensors
└── ...

提示：若尚未安装 NVIDIA Container Toolkit，参考官方文档完成安装。

三、问题背景：原始命令及其痛点

原始命令（已验证可用）

docker run --gpus all -p 8001:8000 \
  --name vllm-openai \
  --shm-size=2g \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  -v /data/models:/models \
  vllm/vllm-openai:v0.12.0 \
    --model /models/DeepSeek-R1-Distill-Llama-8B_AWQ \
    --dtype float16 \
    --quantization awq \
    --enforce-eager \
    --tensor-parallel-size 1 \
    --max-model-len 32768 \
    --max-num-seqs 4 \
    --disable-log-requests \
    --port 8000 \
    --host 0.0.0.0 \
    --gpu-memory-utilization 0.9

生产环境痛点分析

问题	具体表现	影响
硬编码模型	模型路径写死在命令中	无法动态切换模型
命名冲突	`--name vllm-openai` 导致重复创建失败	服务无法重启
网络隔离	无自定义网络配置	与 Dify 等服务通信困难
API ID 不友好	返回 `/models/DeepSeek-R1-Distill-Llama-8B_AWQ`	客户端调用体验差
项目管理混乱	`docker compose ps` 显示其他项目容器	运维效率低下

四、解决方案：从零构建生产级配置

Step 1: 创建项目结构

mkdir -p ~/vllm-service && cd ~/vllm-service
touch docker-compose.yaml .env

Step 2: 配置 `.env` 文件（参数化管理）

# .env
COMPOSE_PROJECT_NAME=vllm-service
MODEL_NAME=DeepSeek-R1-Distill-Llama-8B_AWQ
SERVED_MODEL_NAME=deepseek-r1-8b-awq

设计说明：

COMPOSE_PROJECT_NAME：确保项目隔离，避免命令混淆

MODEL_NAME：对应宿主机 /data/models/ 下的实际目录名

SERVED_MODEL_NAME：对外暴露的简洁模型 ID（符合 OpenAI 命名规范）

Step 3: 创建共享网络（一次性操作）

docker network create vllm-net

为什么用外部网络？
当 vLLM 需与 Dify、LangChain 等服务通信时，共享网络可避免 IP 变动问题，且 external: true 确保 Compose 不会尝试重建已有网络。

Step 4: 编写 `docker-compose.yaml`（核心配置）

# docker-compose.yaml
version: '3.8'

services:
  vllm-openai:
    image: vllm/vllm-openai:v0.12.0
    ports:
      - "8001:8000"
    shm_size: "2g"
    ulimits:
      memlock: -1
      stack: 67108864
    volumes:
      - /data/models:/models
    environment:
      - MODEL_NAME=${
   MODEL_NAME}
      - SERVED_MODEL_NAME=${
   SERVED_MODEL_NAME}
    command: >
      --model /models/${MODEL_NAME}
      --served-model-name ${SERVED_MODEL_NAME}
      --dtype float16
      --quantization awq
      --enforce-eager
      --tensor-parallel-size 1
      --max-model-len 32768
      --max-num-seqs 4
      --disable-log-requests
      --port 8000
      --host 0.0.0.0
      --gpu-memory-utilization 0.9
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    networks:
      - vllm-net

networks:
  vllm-net:
    external: true
    name: vllm-net

五、重要提示：YAML 配置中的注释陷阱

在 YAML 配置文件中，命令行参数块内的 # 注释会导致容器启动失败，这是一个常见但容易被忽视的错误。

错误示例

command: >
  --model /models/${MODEL_NAME}
  --served-model-name ${SERVED_MODEL_NAME}  # 关键：自定义 API 模型 ID
  --dtype float16
  --quantization awq
  --enforce-eager  # 避免 CUDA Graph 编译问题

错误现象

vllm-openai-1  | vllm: error: unrecognized arguments: # 关键：自定义 API 模型 ID # 避免 CUDA Graph 编译问题

正确做法

移除命令行参数中的所有注释（如上文 Step 4 的配置所示）

在命令行参数上方添加 YAML 注释：

# 配置 vLLM 启动参数
# - --served-model-name: 自定义 API 模型 ID
# - --enforce-eager: 避免 CUDA Graph 编译问题
command: >
--model /models/${
     MODEL_NAME}
--served-model-name ${
     SERVED_MODEL_NAME}
--dtype float16
--quantization awq
--enforce-eager

调试技巧

当容器启动失败时，检查完整命令：

docker inspect vllm-service-vllm-openai-1 | grep -A 10 "Cmd"

黄金法则：在 YAML 的字符串值中，# 不是注释符号，而是普通字符。Docker Compose 不会对命令参数做任何注释过滤处理。

六、部署与验证：确保服务正常运行

1. 启动服务

cd ~/vllm-service
docker compose up -d

2. 验证容器状态

docker compose ps
# 正确输出应仅包含当前项目容器
# NAME                         IMAGE                         STATUS
# vllm-service-vllm-openai-1   vllm/vllm-openai:v0.12.0      Up 5 seconds

3. 检查 GPU 利用率

nvidia-smi
# 应看到 vllm-service-vllm-openai-1 进程占用 GPU

4. 验证模型 API

curl http://localhost:8001/v1/models

成功响应：

{
   
  "object": "list",
  "data": [
    {
   
      "id": "deepseek-r1-8b-awq",  // 简洁的自定义名称！
      "object": "model",
      "created": 1766132292,
      "owned_by": "vllm",
      "root": "/models/DeepSeek-R1-Distill-Llama-8B_AWQ",  // 实际路径
      "max_model_len": 32768,
      "permission": [/* ... */]
    }
  ]
}

七、API 调用示例：集成到你的应用

1. 基础聊天接口（cURL）

curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1-8b-awq",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "请用中文解释量子计算的基本原理。"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

2. Python 客户端示例

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8001/v1",
    api_key="EMPTY"  # vLLM 不需要真实 API key
)

response = client.chat.completions.create(
    model="deepseek-r1-8b-awq",
    messages=[
        {
   "role": "system", "content": "你是一个专业的AI助手"},
        {
   "role": "user", "content": "如何优化Docker Compose的GPU性能？"}
    ],
    temperature=0.3,
    max_tokens=300
)

print(response.choices[0].message.content)

3. 流式响应（SSE）

curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1-8b-awq",
    "messages": [{"role": "user", "content": "写一首关于春天的诗"}],
    "stream": true
  }'

八、性能测试：使用 Vegeta 进行压测

1. 安装 Vegeta（Ubuntu/Debian）

# 下载最新版本
wget https://github.com/tsenart/vegeta/releases/download/v12.13.0/vegeta_12.13.0_linux_amd64.tar.gz

# 解压并安装
tar -xzf vegeta_12.13.0_linux_amd64.tar.gz
sudo install vegeta /usr/local/bin/

# 验证
vegeta --version
# 输出：vegeta version 12.13.0

2. 最佳实践：分离 header 和 body

在压测 vLLM 服务时，分离 header 和 body 是最可靠的方法，特别适合包含复杂 JSON 的 API 请求。

# 1. 创建 body 文件（纯 JSON，无额外格式）
echo '{"model":"deepseek-r1-8b-awq","messages":[{"role":"user","content":"Explain quantum computing"}],"max_tokens":256,"temperature":0.7}' > body.json

# 2. 创建 target 文件（仅包含 method + URL + headers）
echo "POST http://localhost:8001/v1/chat/completions
Content-Type: application/json" > target.txt

# 3. 执行压测（指定 body 文件）
vegeta attack -targets=target.txt -body=body.json -rate=10 -duration=30s | vegeta report

3. 生成可视化报告

# 3.生成 HTML 报告
# 3.1 运行攻击并将原始结果保存为二进制文件
vegeta attack -targets=target.txt -body=body.json -rate=1 -duration=30s > results.bin

# 3.2 用 vegeta plot 生成交互式 HTML 报告（含延迟、吞吐量时序图）
vegeta plot results.bin > vllm-report.html

# 生成 JSON 报告（便于分析）
vegeta attack -targets=target.txt -body=body.json -rate=1 -duration=30s | vegeta report -type=json > vllm-report.json

4. 关键指标解读

指标	说明	健康阈值
Requests/sec	每秒请求数	越高越好
Latency P99	99% 请求的延迟	< 1000ms
Success Ratio	成功率	100%
Bytes In/Out	网络带宽	根据负载变化
GPU Util	GPU 利用率	70-85%（平衡点）

生产建议：从低 QPS（5-10）开始逐步增加，当 GPU 利用率 > 85% 或延迟陡增时，即达到服务瓶颈。

九、常见问题排查手册

问题1：`unknown or invalid runtime name: nvidia`

根本原因：环境未注册 nvidia runtime，但已支持 --gpus all。
解决方案：

不要使用 runtime: nvidia，改用 deploy.resources.devices（如上文配置）
验证：docker info | grep -i runtime 应包含 nvidia 在 Runtimes 列表中

问题2：`container name "/vllm-openai" is already in use`

根本原因：旧容器未清理，且配置中保留了 container_name。
解决方案：

移除 container_name 字段（推荐），或
每次启动前执行：docker compose down && docker compose up -d

问题3：`network ... exists but was not created for project`

根本原因：Compose 尝试管理非本项目创建的网络。
解决方案：

声明 external: true（如上文配置），或
删除旧网络重建：docker network rm vllm-net && docker network create vllm-net

问题4：vegeta 报 `bad target` 或 `can't detect encoding`

根本原因：target 文件格式不正确。
解决方案：

使用分离 header/body 的方法（如上文 Step 2 所示）
验证 JSON 有效性：jq empty body.json
检查文件编码：file target.txt 应为 UTF-8

十、最佳实践总结

实践	说明	避免的问题
使用 `.env` 管理配置	分离敏感信息与配置	硬编码、版本控制冲突
移除 `container_name`	让 Compose 自动生成名称	容器命名冲突
网络设为 `external`	复用已有网络	项目间网络隔离问题
设置 `COMPOSE_PROJECT_NAME`	唯一项目标识	`docker compose ps` 混淆
使用 `--served-model-name`	自定义 API 模型 ID	冗长/不友好的模型标识
共享内存 ≥2GB	`shm_size: "2g"`	vLLM 性能下降或崩溃
限制 GPU 显存	`--gpu-memory-utilization 0.9`	OOM 导致服务中断
分离 header/body	vegeta 压测的最佳实践	JSON 格式错误

多模型部署模板

# 扩展配置：多模型并行
services:
  vllm-deepseek:
    image: vllm/vllm-openai:v0.12.0
    ports: ["8001:8000"]
    shm_size: "2g"
    ulimits:
      memlock: -1
      stack: 67108864
    volumes: ["/data/models:/models"]
    environment:
      - MODEL_NAME=DeepSeek-R1-Distill-Llama-8B_AWQ
      - SERVED_MODEL_NAME=deepseek-r1-8b-awq
    command: >
      --model /models/${MODEL_NAME}
      --served-model-name ${SERVED_MODEL_NAME}
      --dtype float16
      --quantization awq
      --enforce-eager
      --tensor-parallel-size 1
      --max-model-len 32768
      --max-num-seqs 4
      --disable-log-requests
      --port 8000
      --host 0.0.0.0
      --gpu-memory-utilization 0.9
    deploy: {
   resources: {
   reservations: {
   devices: [{
   driver: nvidia, count: all, capabilities: [gpu]}]}}}
    networks: [vllm-net]

  vllm-qwen:
    image: vllm/vllm-openai:v0.12.0
    ports: ["8002:8000"]
    shm_size: "2g"
    ulimits:
      memlock: -1
      stack: 67108864
    volumes: ["/data/models:/models"]
    environment:
      - MODEL_NAME=Qwen2-7B-Instruct-AWQ
      - SERVED_MODEL_NAME=qwen2-7b-awq
    command: >
      --model /models/${MODEL_NAME}
      --served-model-name ${SERVED_MODEL_NAME}
      --dtype float16
      --quantization awq
      --enforce-eager
      --tensor-parallel-size 1
      --max-model-len 32768
      --max-num-seqs 4
      --disable-log-requests
      --port 8000
      --host 0.0.0.0
      --gpu-memory-utilization 0.9
    deploy: {
   resources: {
   reservations: {
   devices: [{
   driver: nvidia, count: all, capabilities: [gpu]}]}}}
    networks: [vllm-net]

networks:
  vllm-net:
    external: true
    name: vllm-net

十一、结语：从运维到工程化的思维转变

将 vLLM 从简单的 docker run 升级到生产级 Docker Compose 配置，本质是从临时性运维向工程化思维的转变。通过合理的配置分离、资源管理、网络设计，我们不仅解决了具体的技术问题，更构建了一个可维护、可扩展、可观测的推理服务框架。

在 AI 工程化日益重要的今天，基础设施的质量直接决定模型价值的释放效率。一个精心设计的 docker-compose.yaml，往往比复杂的 AI 代码更能事半功倍。

部署不是终点，而是价值交付的起点。

附录：完整文件与命令清单

1. 完整 `.env` 文件

COMPOSE_PROJECT_NAME=vllm-service
MODEL_NAME=DeepSeek-R1-Distill-Llama-8B_AWQ
SERVED_MODEL_NAME=deepseek-r1-8b-awq

2. 服务管理命令

# 启动/停止/重启
docker compose up -d
docker compose stop
docker compose restart

# 查看日志
docker compose logs -f

# 更新模型后重建
docker compose up -d --force-recreate

# 彻底清理
docker compose down --volumes --remove-orphans

3. 性能监控命令

# GPU 监控
watch -n 1 nvidia-smi

# 容器资源
docker stats vllm-service-vllm-openai-1

# HTTP 负载测试（正确方式）
vegeta attack -targets=target.txt -body=body.json -rate=10 -duration=30s | vegeta report

从 Docker Run 到生产级部署：vLLM推理大模型服务的 Docker Compose 完整实战指南

从 Docker Run 到生产级部署：vLLM推理大模型服务的 Docker Compose 完整实战指南

一、引言：为什么需要将 vLLM 从 Docker Run 升级到 Compose？

二、前置依赖：确保环境就绪

硬件要求

软件要求

模型准备

三、问题背景：原始命令及其痛点

原始命令（已验证可用）

生产环境痛点分析

四、解决方案：从零构建生产级配置

Step 1: 创建项目结构

Step 2: 配置 .env 文件（参数化管理）

Step 3: 创建共享网络（一次性操作）

Step 4: 编写 docker-compose.yaml（核心配置）

五、重要提示：YAML 配置中的注释陷阱

错误示例

错误现象

正确做法

调试技巧

六、部署与验证：确保服务正常运行

1. 启动服务

2. 验证容器状态

3. 检查 GPU 利用率

4. 验证模型 API

七、API 调用示例：集成到你的应用

1. 基础聊天接口（cURL）

2. Python 客户端示例

3. 流式响应（SSE）

八、性能测试：使用 Vegeta 进行压测

1. 安装 Vegeta（Ubuntu/Debian）

2. 最佳实践：分离 header 和 body

3. 生成可视化报告

4. 关键指标解读

九、常见问题排查手册

问题1：unknown or invalid runtime name: nvidia

问题2：container name "/vllm-openai" is already in use

问题3：network ... exists but was not created for project

问题4：vegeta 报 bad target 或 can't detect encoding

十、最佳实践总结

多模型部署模板

十一、结语：从运维到工程化的思维转变

附录：完整文件与命令清单

1. 完整 .env 文件

2. 服务管理命令

3. 性能监控命令

云原生

热门文章

最新文章

相关电子书

Step 2: 配置 `.env` 文件（参数化管理）

Step 4: 编写 `docker-compose.yaml`（核心配置）

问题1：`unknown or invalid runtime name: nvidia`

问题2：`container name "/vllm-openai" is already in use`

问题3：`network ... exists but was not created for project`

问题4：vegeta 报 `bad target` 或 `can't detect encoding`

1. 完整 `.env` 文件