大模型部署从0到1（三）：单机多卡 vLLM 部署Qwen3.6实战｜Docker Compose 一键启动

系列回顾：前两篇我们完成了底层 GPU 环境搭建与模型文件下载。本篇进入核心部署环节，手把手带你用 vLLM + Docker Compose 实现单机多卡大模型推理服务，兼容 OpenAI 接口规范，自带健康检查与故障自愈，生产可用。

🎯 一、部署方案概述

1.1 为什么选 vLLM

vLLM 是当前主流的高性能大模型推理框架，核心优势如下：

PagedAttention 技术：大幅提升显存利用率与并发吞吐，比原生推理快数倍
原生多卡支持：通过张量并行（Tensor Parallel）轻松实现单机多卡分布式推理
OpenAI 兼容接口：启动后直接提供与 OpenAI 一致的 API，业务代码零修改接入
工具调用原生支持：内置多种模型的工具调用解析器，无需额外开发

1.2 适用场景

单台服务器配备 2~8 张 GPU，单卡显存不足以承载大模型
需要稳定的 API 服务对外提供推理能力
希望容器化部署，便于迁移、扩容与运维

📋 二、前置准备

基础环境：已完成 NVIDIA 驱动、Docker、NVIDIA Container Toolkit 安装（参考第一篇）
模型文件：已下载完整的模型文件到本地目录（参考第二篇）
磁盘空间：模型目录预留足够空间，用于存放日志与缓存文件

💡 国内网络优化：配置 Hugging Face 镜像站，避免启动时拉取配置文件超时。
bash 复制代码
export HF_ENDPOINT=https://hf-mirror.com

🐳 三、Docker Compose 完整配置

3.1 配置文件全貌

在模型目录下创建 docker-compose.yml 文件，内容如下（已脱敏处理）：

yaml 复制代码

services:
  vllm-qwen3.6-35b:
    image: vllm/vllm-openai:latest
    container_name: llm-qwen3.6-35b-a3b-fp8
    restart: always
    init: true
    ipc: host
    shm_size: "16g"
    stop_grace_period: 120s

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 4
              capabilities: [gpu]

    ports:
      - "8000:8000"

    volumes:
      - /data/models/Qwen3.6-35B-A3B-FP8:/app/models/Qwen3.6-35B-A3B-FP8
      - /data/models/Qwen3.6-35B-A3B-FP8/cache:/root/.cache/huggingface
      - /data/models/Qwen3.6-35B-A3B-FP8/logs:/app/logs

    environment:
      - TZ=Asia/Shanghai
      - HUGGINGFACE_HUB_CACHE=/root/.cache/huggingface
      - TRANSFORMERS_CACHE=/root/.cache/huggingface
      - HF_HOME=/root/.cache/huggingface
      - HF_ENDPOINT=https://hf-mirror.com
      - HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,utility
      - PYTHONUNBUFFERED=1
      - PYTHONFAULTHANDLER=1
      - VLLM_LOGGING_LEVEL=INFO
      - NCCL_DEBUG=WARN

    logging:
      driver: json-file
      options:
        max-size: "200m"
        max-file: "5"

    entrypoint: []
    command:
      - /bin/bash
      - -lc
      - |
        set -o pipefail
        python3 -m vllm.entrypoints.openai.api_server \
          --model /app/models/Qwen3.6-35B-A3B-FP8 \
          --tensor-parallel-size 4 \
          --max-model-len 262144 \
          --gpu-memory-utilization 0.85 \
          --max-num-seqs 16 \
          --host 0.0.0.0 \
          --port 8000 \
          --served-model-name Qwen3.6-35B-A3B-FP8 \
          --enable-auto-tool-choice \
          --tool-call-parser qwen3_xml \
          2>&1 | tee -a /app/logs/vllm-server.log

    healthcheck:
      test: ["CMD-SHELL", "python3 -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/v1/models', timeout=15).read()\""]
      interval: 30s
      timeout: 20s
      retries: 3
      start_period: 600s

    labels:
      - autoheal=true

  autoheal:
    image: willfarrell/autoheal:latest
    container_name: vllm-autoheal
    restart: always
    environment:
      - AUTOHEAL_CONTAINER_LABEL=all
      - AUTOHEAL_INTERVAL=30
      - AUTOHEAL_START_PERIOD=600
      - AUTOHEAL_DEFAULT_STOP_TIMEOUT=120
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

3.2 核心配置分段详解

🔹 基础运行配置

ipc: host：使用宿主机 IPC 命名空间，多卡通信必需，否则 NCCL 通信报错
shm_size: "16g"：设置共享内存大小，大模型推理、多卡通信需要较大共享内存
stop_grace_period: 120s：优雅停止时长，给模型足够时间释放显存

🔹 GPU 资源分配

yaml 复制代码

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 4
          capabilities: [gpu]

通过 Docker 官方 GPU 调度方式分配显卡，count 改为你实际使用的卡数；也可以用 device_ids: ["0", "1", "2", "3"] 指定具体显卡编号。

🔹 目录挂载

模型本体目录挂载到容器内，避免镜像内置模型、体积过大
缓存目录独立挂载，重启容器不丢失缓存，加速下次启动
日志目录挂载到宿主机，便于排查问题与日志归档

🔹 国内环境优化

HF_ENDPOINT=https://hf-mirror.com：配置 Hugging Face 国内镜像，启动时拉取配置文件不走国外线路
HF_TOKEN：填写你自己的 Hugging Face 令牌，用于访问需要授权的模型，公开模型可省略

🔹 启动命令核心参数

参数	作用
`--tensor-parallel-size 4`	张量并行数，必须与使用的 GPU 数量一致，模型权重拆分到多张卡上
`--max-model-len 262144`	最大上下文长度，根据模型支持的上下文与显存情况调整
`--gpu-memory-utilization 0.85`	显存利用率上限，预留部分显存防止溢出，建议 0.8~0.9
`--max-num-seqs 16`	最大并发序列数，数值越高并发越强，但占用显存越多
`--served-model-name`	API 调用时使用的模型名称，可自定义
`--enable-auto-tool-choice`	开启自动工具调用能力
`--tool-call-parser qwen3_xml`	指定工具调用解析器，不同模型对应不同解析器

🔹 健康检查与自愈

healthcheck：容器内置健康检测，通过访问 /v1/models 接口判断服务是否正常
autoheal：独立的自愈容器，检测到服务不健康时自动重启容器，实现生产级高可用

▶️ 四、启动与验证

4.1 启动服务

在 docker-compose.yml 所在目录执行：

bash 复制代码

docker compose up -d

4.2 查看启动日志

bash 复制代码

# 实时查看日志
docker compose logs -f vllm-qwen3.6-35b

✅ 启动成功标志：日志中出现 Application startup complete 字样，代表服务已就绪。

4.3 接口验证

服务启动后，使用 curl 测试接口可用性：

bash 复制代码

curl http://127.0.0.1:8000/v1/models

测试聊天接口：

bash 复制代码

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.6-35B-A3B-FP8",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ],
    "temperature": 0.7
  }'

⚙️ 五、关键参数调优建议

5.1 张量并行数设置

必须满足：张量并行数 ≤ 实际分配的 GPU 数量
显存不够时优先增加并行数，而不是盲目调大显存利用率
建议使用偶数张卡做张量并行，通信效率更高

5.2 显存与并发平衡

显存充足：调大 --max-num-seqs 提升并发吞吐
显存紧张：降低 --gpu-memory-utilization、减小 --max-model-len
长上下文场景：优先保证上下文长度，适当降低并发数

5.3 日志级别调整

生产环境建议 VLLM_LOGGING_LEVEL=INFO，减少日志量
排查问题时临时改为 DEBUG，定位完成后改回

❗ 六、常见问题排查

启动卡在下载配置文件

检查 HF_ENDPOINT 是否配置正确，确认网络能正常访问镜像站；也可提前将所有配置文件下载到本地。
多卡通信报错（NCCL error）

检查 ipc: host 是否配置；确认显卡之间拓扑正常，同一服务器的显卡通常无需额外配置。
显存溢出 OOM

先减小 --gpu-memory-utilization，若仍报错则增加 --tensor-parallel-size，或减小 --max-model-len。
容器反复重启

查看容器日志定位具体报错；常见原因是模型路径错误、文件不完整、显存不足。

📝 本篇小结

通过 Docker Compose + vLLM，我们用一份配置文件实现了单机多卡大模型推理服务的一键部署、健康检查、故障自愈，并且完全兼容 OpenAI 接口规范，可以直接对接上层业务。

下一篇我们将讲解多机分布式部署，实现跨服务器的大模型推理，承载更大参数量的模型。

原创不易，如果内容对你有帮助，欢迎点赞、收藏、关注，持续更新大模型部署实战干货~