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 直通环境正常避免后续踩坑。# 1. 确认 Docker 版本 docker --version # 2. 验证 NVIDIA 容器工具包、GPU 直通正常 docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi能正常输出显卡型号、显存信息代表环境就绪。二、创建指定工作目录# 递归创建工作目录和模型目录 mkdir -p ~/proj_dir/code_dir/llm_work/models # 进入工作目录后续操作均在此目录下执行 cd ~/proj_dir/code_dir/llm_work三、下载模型文件宿主机下载后续挂载进容器使用 ModelScope 国内镜像高速下载避免容器内下载慢、丢包问题。先安装下载工具pip install modelscope双 48GB 及以上显存显卡使用模型大小约 65GB全精度无损失代码能力最强。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下载完成校验ls -lh /home/gyy/proj_dir/code_dir/llm_work/models/四、Docker 启动 vLLM 推理服务手动启动模式无自动重启完全由你按需启停。docker run -d \ --name vllm-qwen32b-coder \ --gpus all \ --ipchost \ -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. 查看实时加载日志bashdocker logs -f vllm-qwen32b-coder等待日志中出现Uvicorn running on http://0.0.0.0:8000代表模型加载完成、服务就绪。 按Ctrl C可退出日志查看容器继续后台运行。2. 健康状态检查bashcurl -v http://127.0.0.1:8000/health返回 HTTP/1.1 200 OK 即为服务正常。六、服务调用示例vLLM 提供标准 OpenAI 兼容接口所有支持 OpenAI 协议的工具、插件均可直接对接。6.1 curl 命令调用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 调用先安装依赖bashpip install openai新建测试脚本test_qwen_coder.pypython运行from openai import OpenAI # 对接本地 vLLM 服务 client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keydummy_key # 本地部署无鉴权时随意填写即可 ) response client.chat.completions.create( modelqwen2.5-coder, messages[ {role: user, content: 解释 C 中 unique_ptr 和 shared_ptr 的区别与适用场景} ], temperature0.2, max_tokens1024 ) print(模型回复) print(response.choices[0].message.content)执行脚本bashpython test_qwen_coder.py七、日常手动运维命令重要docker run仅在首次创建容器时执行 1 次后续启停一律使用docker start/stop不要重复执行 run 命令否则会报容器名冲突。# 查看所有容器状态 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 崩溃共享内存--ipchost是 vLLM 必加参数缺失会报共享内存不足、推理异常模型路径--model填的是容器内的路径不是宿主机路径必须和挂载目录对应数据安全模型文件存在宿主机删除 / 重建容器完全不会丢失模型放心调试端口访问局域网其他机器访问时使用宿主机IP:8000确保服务器防火墙开放 8000 端口官方参考文档Qwen2.5-Coder 官方仓库https://github.com/QwenLM/Qwen2.5-CodervLLM Docker 部署官方指南https://docs.vllm.ai/en/latest/serving/deploying_with_docker.htmlvLLM OpenAI 兼容接口文档https://docs.vllm.ai/en/latest/serving/openai_compatible_server.htmlModelScope 模型主页https://modelscope.cn/models/qwen/Qwen2.5-Coder-32B-Instruct-AWQ