Ubuntu24.04 Docker+vLLM+qianwen2.5-coder-32B部署文档

硬件配置

宿主机工作目录：~/proj_dir/code_dir/llm_work
宿主机模型存放路径：~/proj_dir/code_dir/llm_work/models
容器内挂载路径：/models

硬件前置提醒：标准 RTX 4090 单卡 24GB，双卡总显存 48GB，无法运行 FP16 全精度 32B 模型（权重约 64GB），必须使用 AWQ 4bit 量化版；如果你的显卡是单卡 48GB 专业卡（总 96GB），可使用 FP16 完整版。下面两套方案分别给出。

一、前置环境校验（必做）

先确认 Docker 与 GPU 直通环境正常，避免后续踩坑。

bash 复制代码

# 1. 确认 Docker 版本
docker --version

# 2. 验证 NVIDIA 容器工具包、GPU 直通正常
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

能正常输出显卡型号、显存信息，代表环境就绪。

二、创建指定工作目录

bash 复制代码

# 递归创建工作目录和模型目录
mkdir -p ~/proj_dir/code_dir/llm_work/models

# 进入工作目录（后续操作均在此目录下执行）
cd ~/proj_dir/code_dir/llm_work

三、下载模型文件（宿主机下载，后续挂载进容器）

使用 ModelScope 国内镜像高速下载，避免容器内下载慢、丢包问题。

先安装下载工具

bash 复制代码

pip install modelscope

双 48GB 及以上显存显卡使用 模型大小约 65GB，全精度无损失，代码能力最强。

bash 复制代码

modelscope download --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --local_dir /home/gyy/proj_dir/code_dir/llm_work/models/qwen2.5-coder-32b-instruct

下载完成校验

bash 复制代码

ls -lh /home/gyy/proj_dir/code_dir/llm_work/models/

四、Docker 启动 vLLM 推理服务

手动启动模式，无自动重启，完全由你按需启停。

bash 复制代码

docker run -d \
  --name vllm-qwen32b-coder \
  --gpus all \
  --ipc=host \
  -p 8000:8000 \
  -v /home/gyy/proj_dir/code_dir/llm_work/models:/models \
  vllm/vllm-openai:v0.6.3 \
  --model /models/qwen2.5-coder-32b-instruct \
  --served-model-name qwen2.5-coder \
  --tensor-parallel-size 2 \
  --trust-remote-code \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.85 \
  --host 0.0.0.0 \
  --port 8000

核心路径参数说明

-v /home/gyy/proj_dir/code_dir/llm_work/models:/models：将宿主机的模型目录映射到容器内的 /models，容器直接读取宿主机文件，不额外占用磁盘
--model /models/xxx：容器内的模型路径，必须和挂载后的容器内路径完全一致
无 --restart always：服务器重启、容器退出后不会自动拉起，完全手动控制

五、服务启动验证

1. 查看实时加载日志

bash

复制代码

docker logs -f vllm-qwen32b-coder

等待日志中出现 Uvicorn running on http://0.0.0.0:8000，代表模型加载完成、服务就绪。按 Ctrl + C 可退出日志查看，容器继续后台运行。

2. 健康状态检查

bash

bash 复制代码

curl -v http://127.0.0.1:8000/health

返回 HTTP/1.1 200 OK 即为服务正常。

六、服务调用示例

vLLM 提供标准 OpenAI 兼容接口，所有支持 OpenAI 协议的工具、插件均可直接对接。

6.1 curl 命令调用

bash 复制代码

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder",
    "messages": [
      {"role": "system", "content": "你是专业的编程助手，擅长代码生成、调试与架构设计。"},
      {"role": "user", "content": "用 Python 写一个线程安全的单例模式，附带详细注释"}
    ],
    "temperature": 0.2,
    "max_tokens": 1024,
    "stream": false
  }'

6.2 Python SDK 调用

先安装依赖：

bash

复制代码

pip install openai

新建测试脚本 test_qwen_coder.py：

python

运行

bash 复制代码

from openai import OpenAI

# 对接本地 vLLM 服务
client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="dummy_key"  # 本地部署无鉴权时，随意填写即可
)

response = client.chat.completions.create(
    model="qwen2.5-coder",
    messages=[
        {"role": "user", "content": "解释 C++ 中 unique_ptr 和 shared_ptr 的区别与适用场景"}
    ],
    temperature=0.2,
    max_tokens=1024
)

print("模型回复：")
print(response.choices[0].message.content)

执行脚本：

bash

复制代码

python test_qwen_coder.py

七、日常手动运维命令

重要：docker run 仅在首次创建容器时执行 1 次，后续启停一律使用 docker start/stop，不要重复执行 run 命令，否则会报容器名冲突。

bash 复制代码

# 查看所有容器状态
docker ps -a

# 手动启动服务（需要使用模型时执行）
docker start vllm-qwen32b-coder

# 手动停止服务（用完释放显存，必做）
docker stop vllm-qwen32b-coder

# 查看实时运行日志
docker logs -f vllm-qwen32b-coder

# 查看最近 50 行日志
docker logs --tail 50 vllm-qwen32b-coder

# 删除容器（仅重建时使用，不会删除宿主机模型文件）
docker rm vllm-qwen32b-coder

八、关键避坑说明

显存匹配：双 24GB 4090 严禁直接跑 FP16 原版 32B，会直接 OOM 崩溃
共享内存 ：--ipc=host 是 vLLM 必加参数，缺失会报共享内存不足、推理异常
模型路径 ：--model 填的是容器内的路径，不是宿主机路径，必须和挂载目录对应
数据安全：模型文件存在宿主机，删除 / 重建容器完全不会丢失模型，放心调试
端口访问 ：局域网其他机器访问时，使用 宿主机IP:8000，确保服务器防火墙开放 8000 端口

官方参考文档

Qwen2.5-Coder 官方仓库：https://github.com/QwenLM/Qwen2.5-Coder
vLLM Docker 部署官方指南：https://docs.vllm.ai/en/latest/serving/deploying_with_docker.html
vLLM OpenAI 兼容接口文档：https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html
ModelScope 模型主页：https://modelscope.cn/models/qwen/Qwen2.5-Coder-32B-Instruct-AWQ