AI 助理
备案控制台
开发者社区 云原生 文章 正文

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

2025-12-21 28
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： 本文详解如何将vLLM大模型推理服务从基础docker run升级为生产级Docker Compose部署。涵盖GPU支持、网络隔离、配置参数化、API优化与压测实践，解决命名冲突、环境混乱等痛点，助力AI/DevOps工程师构建可维护、可扩展的容器化推理平台。

从 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 编译问题

正确做法

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

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

文章标签：
容器
Docker
异构计算
API
测试技术
游客4d7nidhe5yrva
目录
相关文章
阿里云安全_
|
3天前
|
数据采集 人工智能 安全
阿里云Web应用防火墙市场份额和技术能力双第一
喜报～～
阿里云安全_
1166 1
阿里云安全_
|
13天前
|
云安全 监控 安全
助力企业应对React框架高危漏洞，阿里云多款安全产品限时免费
领取限时免费产品，立即开始防护
阿里云安全_
3100 5
bailiantest1
|
4天前
|
自然语言处理 API
万相 Wan2.6 全新升级发布！人人都能当导演的时代来了
通义万相2.6全新升级，支持文生图、图生视频、文生视频，打造电影级创作体验。智能分镜、角色扮演、音画同步，让创意一键成片，大众也能轻松制作高质量短视频。
bailiantest1
1089 152
modelscope
|
18天前
|
机器学习/深度学习 人工智能 自然语言处理
Z-Image：冲击体验上限的下一代图像生成模型
通义实验室推出全新文生图模型Z-Image，以6B参数实现“快、稳、轻、准”突破。Turbo版本仅需8步亚秒级生成，支持16GB显存设备，中英双语理解与文字渲染尤为出色，真实感和美学表现媲美国际顶尖模型，被誉为“最值得关注的开源生图模型之一”。
modelscope
1752 9
星哥玩云
|
9天前
|
人工智能 自然语言处理 API
一句话生成拓扑图！AI+Draw.io 封神开源组合，工具让你的效率爆炸
一句话生成拓扑图！next-ai-draw-io 结合 AI 与 Draw.io，通过自然语言秒出架构图，支持私有部署、免费大模型接口，彻底解放生产力，绘图效率直接爆炸。
星哥玩云
695 152
阿里云云原生
|
11天前
|
人工智能 安全 前端开发
AgentScope Java v1.0 发布，让 Java 开发者轻松构建企业级 Agentic 应用
AgentScope 重磅发布 Java 版本，拥抱企业开发主流技术栈。
阿里云云原生
660 14
云皓@
|
6天前
|
SQL 自然语言处理 调度
Agent Skills 的一次工程实践
**本文采用 Agent Skills 实现整体智能体**，开发框架采用 AgentScope，模型使用 **qwen3-max**。Agent Skills 是 Anthropic 新推出的一种有别于mcp server的一种开发方式，用于为 AI **引入可共享的专业技能**。经验封装到**可发现、可复用的能力单元**中，每个技能以文件夹形式存在，包含特定任务的指导性说明（SKILL.md 文件）、脚本代码和资源等 。大模型可以根据需要动态加载这些技能，从而扩展自身的功能。目前不少国内外的一些框架也开始支持此种的开发方式,详细介绍如下。
云皓@
446 5