QWen3.8-27B-FP8 双 4090D24GUbuntu22.04 Docker 完整部署报告可公开教程一、部署概述本次部署基于Ubuntu 22.04 LTS工作站硬件为双 RTX 4090D 24GB 显存显卡采用 DockerDocker Compose 容器化方案使用 vLLM 框架高性能部署 QWen3.8-27B-FP8 多模态大模型。重要说明模型权重包为手动下载后上传至服务器本地vLLM 基础镜像也为预先手动拉取规避 compose 编排构建时长时间拉取镜像超时中断问题。整套方案容器化、参数针对双卡显存做适配支持 FP8 推理、张量并行、超长上下文、多图文模态自带 API 鉴权可直接复现适合技术教程分享。1.1 核心部署信息硬件环境双 RTX 4090D 显卡单卡 24GB 显存NVIDIA-SMI 595.91.07系统环境Ubuntu 22.04 LTS网络环境国内互联网推理框架vLLM v0.27.1部署方式Docker Docker Composenvidia-container-runtime GPU 直通模型QWen3.8-27B-FP8本地手动上传权重非在线 huggingface 下载核心特性双卡张量并行、FP8 KV Cache、21952 上下文窗口、多模态图文、API Key 鉴权镜像策略vLLM 镜像提前手动拉取避免 compose 启动阶段长时间拉取超时打断部署流程二、前置环境准备2.1 基础依赖清单部署前服务器需要预先装好docker-ce、docker-compose-plugin、nvidia-container-runtime、NVIDIA 驱动版本匹配 vLLM 0.27.1。建议提前验证 nvidia 容器可用性nvidia-container-cli info2.2 Docker 守护进程配置 daemon.json保留全部 registry-mirrors 源不删减sudo tee /etc/docker/daemon.json -EOF { max-concurrent-downloads: 3, max-download-attempts: 5, registry-mirrors: [ https://docker.xuanyuan.me, https://docker.1panel.live ], runtimes: { nvidia: { args: [], path: nvidia-container-runtime } } } EOF配置生效命令sudo systemctl daemon-reload sudo systemctl restart docker备注registry-mirrors 为 docker 镜像加速地址用于加速 dockerhub 镜像拉取本方案 vLLM 镜像我们手动提前拉取规避 compose 构建阶段长时间下载中断。三、镜像与模型文件准备重点教程关键这一节专门说明你的场景模型、vLLM 镜像都是离线提前准备避免 compose 里拉取超时。vLLM 镜像预先手动拉取推荐在执行 compose 前单独执行docker pull vllm/vllm-openai:v0.27.1手动拉取完成后执行docker images确认镜像存在再执行 compose 构建不再由 compose 负责拉取基础镜像防止长时间网络传输被打断。模型权重包准备模型文件手动下载后上传至服务器路径/home/qwen38-27b-fp8检查目录内包含完整模型权重、config、tokenizer 等全套文件不要压缩包直接解压到该目录。容器会通过 volume 挂载该目录离线读取模型设置HF_HUB_OFFLINE1启动时不会联网下载模型。新建缓存目录mkdir -p ./cache四、完整部署配置文件4.1 Dockerfilecat Dockerfile -EOF FROM vllm/vllm-openai:v0.27.1 WORKDIR /app VOLUME [/app/model, /app/cache] EXPOSE 8000 EOF说明基于已经提前 pull 好的 vLLM 镜像构建仅定义工作目录、挂载卷、端口不会再次拉取基础镜像。4.2 docker-compose.yml原版完整保留参数完全沿用你的配置cat docker-compose.yml -EOF version: 3.3 services: qwen38-multimodal: build: . container_name: qwen38-27b-fp8 restart: always runtime: nvidia shm_size: 16g ports: - 8000:8000 volumes: - /home/qwen38-27b-fp8:/app/model - ./cache:/app/cache environment: - HF_HOME/app/cache - TORCH_USE_CUDA_DSA1 - HF_HUB_OFFLINE1 entrypoint: [] command: - python3 - -m - vllm.entrypoints.openai.api_server - --model - /app/model - --tensor-parallel-size - 2 - --kv-cache-dtype - fp8 - --max-model-len - 21952 - --max-num-seqs - 17 - --gpu-memory-utilization - 0.84 - --trust-remote-code - --limit-mm-per-prompt - {image:4,video:1} - --port - 8000 - --host - 0.0.0.0 # 新增两行放在末尾 - --served-model-name - qwen3.8-27b-fp8 - --api-key - admin-qwen38-27b-20260918 EOF五、vLLM 启动参数详细说明5.1 硬件并行 显存控制--tensor-parallel-size 2双卡张量并行27B 模型拆分到两张 4090D分摊显存负载--gpu-memory-utilization 0.84显存占用上限 84%预留显存防止 OOM适配单卡 24GBshm_size: 16g扩大容器共享内存多并发推理避免 shm 不足报错5.2 模型与 KV 缓存优化--kv-cache-dtype fp8KV 缓存使用 FP8 量化显著降低显存开销提升吞吐--max-model-len 21952最大上下文窗口 21952 token支持长文本、长图文输入--max-num-seqs 17最大并发序列数控制同时处理请求数量平衡并发与显存占用HF_HUB_OFFLINE1离线模式不访问 huggingface hub完全读取本地挂载模型目录--trust-remote-code加载模型自定义代码多模态模型必需参数5.3 多模态、网络与安全--limit-mm-per-prompt {image:4,video:1}单 prompt 最多 4 张图片、1 个视频防止超大媒体请求耗尽显存--host 0.0.0.0监听所有网卡允许局域网其他机器访问 API--port 8000服务端口--served-model-name自定义模型名称调用 API 时使用--api-key接口鉴权密钥禁止匿名访问六、部署启动流程前提已经手动 pull vLLM 镜像、模型文件上传解压完成在 Dockerfile 与 docker-compose.yml 所在目录执行构建 启动docker-compose up -d --build本次构建仅在本地基础镜像上叠加层不会重新拉取 vLLM 基础镜像速度很快不会长时间等待。查看容器状态docker-compose ps实时日志查看排查启动报错docker-compose logs -f✅ 启动成功标识日志打印Uvicorn running on http://0.0.0.0:8000同时 vLLM 打印模型加载完成信息。七、服务管理常用命令# 停止服务 docker-compose down # 重启服务容器不销毁 docker-compose restart # 仅查看日志不实时跟踪 docker-compose logs # 删除容器保留镜像与模型文件 docker-compose down # 删除容器缓存卷谨慎执行会清空cache目录 docker-compose down -v八、接口调用测试OpenAI 兼容接口8.1 curl 调用示例curl http://localhost:8000/v1/chat/completions \ -H Authorization: Bearer admin-qwen38-27b-20260918 \ -H Content-Type: application/json \ -d { model: qwen3.8-27b-fp8, messages: [{role: user, content: 你好请介绍自己}], temperature: 0.7 }8.2 Python 调用示例from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyadmin-qwen38-27b-20260918 ) resp client.chat.completions.create( modelqwen3.8-27b-fp8, messages[ {role:user, content:你好请介绍自己} ], temperature0.7 ) print(resp.choices[0].message.content)依赖安装pip install openai九、常见故障排查OOM 显存溢出现象推理时报 CUDA out of memory解决调低gpu-memory-utilization或减小max-num-seqs并发数量降低单次请求图片 / 视频数量。模型加载失败现象找不到模型文件 / 权重损坏解决确认/home/qwen38-27b-fp8目录文件完整确认挂载路径正确开启--trust-remote-code。容器启动 nvidia runtime 报错解决检查 nvidia-container-runtime 安装确认 daemon.json 的 nvidia runtime 配置正确重启 docker。镜像拉取超时为什么我们选择手动 pull 镜像如果把镜像拉取交给 compose 的 build 阶段大镜像网络不稳定时极易长时间传输被中断。最佳实践是预先单独执行 docker pull 拉取 vLLM 镜像再执行 compose up规避该问题。共享内存不足报错提示shm相关确认 compose 里shm_size:16g配置生效。十、部署总结本方案基于 Ubuntu22.04 双 RTX4090D 24G使用 vLLM v0.27.1 容器化部署 QWen3.8-27B-FP8 多模态模型。核心方案特点vLLM 基础镜像手动提前拉取模型权重本地上传完全规避 compose 编排时大文件下载超时中断问题保留原始 docker 镜像加速源配置不修改 daemon.json 镜像源列表双卡张量并行 FP8 KV Cache参数针对 24G 双卡做精细调优OpenAI 兼容 API支持鉴权支持多模态图文推理可直接对外提供服务。
