# 从 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` 配置）

### 软件要求
```bash
# 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，参考[官方文档](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)完成安装。

---

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

### 原始命令（已验证可用）
```bash
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: 创建项目结构
```bash
mkdir -p ~/vllm-service && cd ~/vllm-service
touch docker-compose.yaml .env
```

### Step 2: 配置 `.env` 文件（参数化管理）
```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: 创建共享网络（一次性操作）
```bash
docker network create vllm-net
```

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

### Step 4: 编写 `docker-compose.yaml`（核心配置）
```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 配置文件中，**命令行参数块内的 `#` 注释会导致容器启动失败**，这是一个常见但容易被忽视的错误。

### 错误示例
```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 编译问题
```

### 正确做法
1. **移除命令行参数中的所有注释**（如上文 Step 4 的配置所示）
2. **在命令行参数上方添加 YAML 注释**：
```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
```

### 调试技巧
当容器启动失败时，检查完整命令：
```bash
docker inspect vllm-service-vllm-openai-1 | grep -A 10 "Cmd"
```

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

---

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

### 1. 启动服务
```bash
cd ~/vllm-service
docker compose up -d
```

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

### 3. 检查 GPU 利用率
```bash
nvidia-smi
# 应看到 vllm-service-vllm-openai-1 进程占用 GPU
```

### 4. 验证模型 API
```bash
curl http://localhost:8001/v1/models
```

**成功响应**：
```json
{
  "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）
```bash
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 客户端示例
```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）
```bash
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）
```bash
# 下载最新版本
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 请求。

```bash
# 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. 生成可视化报告
```bash
# 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 格式错误 |

### 多模型部署模板
```yaml
# 扩展配置：多模型并行
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` 文件
```env
COMPOSE_PROJECT_NAME=vllm-service
MODEL_NAME=DeepSeek-R1-Distill-Llama-8B_AWQ
SERVED_MODEL_NAME=deepseek-r1-8b-awq
```

### 2. 服务管理命令
```bash
# 启动/停止/重启
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. 性能监控命令
```bash
# 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
```

---

**版权声明**：本文所有配置已在 Ubuntu 22.04 + NVIDIA RTX 3060 环境验证通过，适用于 DeepSeek、Qwen、Llama 等主流 AWQ 量化模型。欢迎转载，需保留作者信息及原文链接。**实践是检验真理的唯一标准**——请根据你的实际环境调整配置。

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

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

编程语言

vLLM大模型推理服务DockerCompose生产级部署指南，详解从DockerRun到Compose的升级方案。包含GPU配置、网络隔离、API优化及性能测试，提供可直接用于生产环境的vLLM部署模板，解决模型切换、命名冲突等痛点问题。

量子计算

容器运维

负载测试

性能测试

Docker

DevOps

Python

容器

Ubuntu

Debian

JSON

AI驱动 智领未来

tione

4核4G3M云服务器 新用户低至38元/年！

coding

5位重磅专家聚焦 AI 时代开发者核心成长需求，带你深入解锁全栈进化、人机协作关键路径！点击报名到场：<a href="https://cloud.tencent.com/developer/salon/salon-2403/signup" target="_blank">https://cloud.tencent.com/developer/salon/salon-2403/signup</a><br/> 
 <img src="https://qcloudimg.tencent-cloud.cn/raw/487c82639d2338df3ef66dfb1450601a.png"/>

腾讯技术创作特训营「年度论坛」正在报名中！

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

从 Docker Run 到生产级部署：vLLM大模型推理服务的 Docker Compose 完整实战指南-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐