企业官网建设流程全解析

Docker 部署大模型，2026 年还有人被卡在镜像和端口上，我不太能理解。这篇就是给新手和刚接触容器化的团队准备的速通指南，半小时能跑通一个可用的 LLM 服务，不是我夸张，前提是你按我下面的顺序来，别瞎折腾。

我假设三件事：你有一台带 NVIDIA 显卡的 Linux 机器，驱动已经装好；你了解 Docker 的基本命令，知道docker run大概是什么意思；你想部署的是开源模型，比如 Qwen、Llama、ChatGLM 这一类。如果你这三样都满足，那直接往下看，很多坑我已经替你踩完了。

1. 大模型容器化到底解决什么问题

大模型部署最烦的从来不是模型本身，而是环境。Python 版本冲突、CUDA 版本不匹配、torch编译出来的乱七八糟的依赖，能让你在部署阶段消耗掉比训练还多的耐心。Docker 的价值就是把这些全都锁进一个只读层里，让应用和宿主机彻底解耦。

1.1 为什么“最新镜像”不等于“最新模型”

很多人一上来就搜“最新大模型 docker 镜像”，然后拉了一个几百 GB 的镜像，跑起来发现不是自己要的版本，或者干脆不能跑。2026 年了，镜像仓库里的latest标签依然是个危险的东西，尤其是 AI 领域，模型权重迭代太快，latest可能是三天前发布的，也可能是三个月前没人维护的。

我的习惯是固定标签，而且要区分两个维度：一个是运行时镜像（比如pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime），另一个是模型权重版本（比如Qwen/Qwen2.5-7B-Instruct）。这两个必须分开管理，因为运行时可以复用，权重文件则可以放在宿主机目录挂载进容器，没必要把几十 GB 的权重打进镜像里。

1.2 涉及到的核心技术组件拆解

一个标准的 LLM 部署容器，至少包含四个技术点。首先是推理框架，现在主流是 vLLM、SGLang 这类高性能方案，也有很多人用 llama.cpp 的server子命令。其次是 API 接口层，OpenAI 兼容格式已经是事实标准，你可以直接用框架自带的 HTTP 服务，也可以用 FastAPI 自己包装一层。然后是模型加载器，负责从磁盘把权重加载到显存，这一步的显存分配策略会影响并发能力。最后是前端界面，如果要做 WebUI，Open WebUI 或者 Gradio 都能快速实现，但速通阶段可以暂时不装，先验证 API 通不通。

这四个组件在 Docker 化之后，依赖关系变成了层与层之间的关系。镜像层缓存得好，重新部署一个新模型只需要换权重挂载，几秒钟就能完成。这就是容器化的最大收益。

2. 30分钟部署路径拆解：从镜像选型到端口规划

很多教程把 Docker 部署大模型写得像魔法，几条命令往下贴，复制粘贴就完事了。但我建议你花五分钟理解一下整体路径，不然中间任何一个报错都会让你卡住。

2.1 先说结论：推荐方案是“运行时镜像 + 权重挂载”

这个方案的四步流程是：准备一个干净的推理运行时镜像，或者在官方镜像基础上加一层依赖；启动容器时把宿主机上的模型权重目录挂载进去；容器启动后由推理框架自动加载模型并监听端口；通过 curl 或者 HTTP 客户端发送请求验证。这个方案的优点是镜像小、权重更新只需替换目录，不涉及重新 Build；缺点是要求你对 Docker 挂载和文件权限有基本概念。

另一个方案是把权重直接 COPY 进镜像，优点是迁移到另一台机器时只要传输镜像即可；缺点是镜像体积会膨胀几十 GB，而且每次换模型都要重新 Build，缓存策略不好还会白白浪费磁盘。我一个人开发时用挂载方案，团队交付或者离线部署时才做整镜像打包。

2.2 端口、显存和并发量的提前预估

端口规划看起来小事，实际踩坑很多。默认情况下 vLLM 监听 8000，SGLang 监听 30000，llama.cpp 的server监听 8080，Open WebUI 监听 8080。如果你一条命令里同时起两个框架，端口冲突概率非常高。

显存预估我用过一个比较粗糙但实用的公式：模型权重占用约为参数量乘以 2 字节（FP16），例如 7B 模型至少需要 14 GB 显存存放权重；如果开启 KV Cache，需要再加上 2 到 4 GB；如果上下文长度设置得很长，比如 32K，KV Cache 会占掉非常大的比例。你部署之前先去查卡的真实可用显存，别被nvidia-smi显示的显存总量迷惑，驱动和桌面环境本身也要吃掉几百 MB。

并发量的规划同样影响启动参数。max-model-len决定上下文窗口长度，gpu-memory-utilization控制显存分配比例，max-num-seqs控制同时处理的序列数量。这几个参数的逻辑是：显存固定时，上下文越长，单序列占用的缓存越多，能处理的并发就越少。我个人的速通参数组合会在第三步给出，你先按它能跑通，再优化性能。

2.3 为什么不用 docker-compose 之外的编排工具

30 分钟能完成的目标，不需要上 Kubernetes。K8s 的优势在于多节点调度、自动伸缩、滚动更新，但单机部署大模型时这些反而是负担。一个docker-compose.yml就可以把容器、端口、目录挂载、环境变量管理得井井有条，我甚至建议你可以不用命令行直接docker run，就用 Compose，因为 Compose 的配置可以版本化，下次换机器直接docker compose up -d就能恢复环境。

如果你的团队已经有 K8s，那可以考虑用 Operator 管理推理负载，但那是另外一个话题了。速通场景用 Compose 足够。

3. 手把手部署：构建镜像与启动服务的五个关键步骤

现在进入实操。我说一下我的测试环境：某台双卡 Linux 服务器，显卡驱动版本在某较新版本，Docker 版本支持 GPU 直通，宿主机已经安装了nvidia-container-toolkit。如果你还没装这个 toolkit，先去装，否则--gpus all参数是不生效的，这是新手最常见的卡点。

3.1 前置检查：GPU 支持能不能用

在拉任何镜像之前，先跑这条命令验证 Docker 的 GPU 支持：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

如果能看到显卡信息，说明环境没问题。如果报错could not select device driver "" with capabilities: [[gpu]]，那就是nvidia-container-toolkit没装或者 Docker 守护进程没重启。这个检查只需要一分钟，但能省掉后面所有的迷茫。

我见过不少人跳过这一步，直接启动一个大模型容器，结果容器一直在重启，日志里全是驱动加载失败，排查了半天才发现基础环境没就绪。

3.2 选择运行时镜像：以 vLLM 官方镜像为基底

这里我以 vLLM 为例，因为它对 OpenAI 兼容接口的支持最成熟，部署 Qwen、Llama 这类主流模型基本零适配成本。官方 Dockerfile 构建起来有点慢，我推荐直接拉编译好的镜像：

docker pull vllm/vllm-openai:v0.6.3

拉完检查一下镜像大小，基础镜像加完整运行时一般在 8 到 10 GB 左右，这个体积是正常的。如果你想要更小的镜像，可以用llama.cpp的 CUDA 镜像，但没有必要为了几个 GB 的体积增加兼容性风险。

提示：镜像标签里的v0.6.3是示例，2026 年虽然会有更新的版本，但请按项目文档固定一个稳定版本，不要追最新。推理框架更新频繁，新版本经常会引入一些 breaking change，生产环境里稳定大于一切。

3.3 目录挂载与权重准备

在宿主机上规划一个目录存放模型权重，我的习惯是放/data/models下，每个模型一个子目录：

mkdir -p /data/models/Qwen2.5-7B-Instruct

然后把你下载的权重文件放进去。权重可以从 Hugging Face 或者国内的镜像站下载，下载时注意文件完整性，缺失了某个分片会导致加载中途报错。

启动容器时，通过-v把目录挂载进去，容器里的路径建议统一为/models：

docker run -d \ --name llm-qwen \ --gpus all \ --shm-size=8g \ -v /data/models:/models \ -p 8000:8000 \ vllm/vllm-openai:v0.6.3 \ --model /models/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b \ --max-model-len 8192 \ --gpu-memory-utilization 0.9

有几个参数我得单独说明一下。--shm-size=8g很多人会忽略，但 vLLM 在数据加载和批处理时会用到共享内存，默认的 64 MB 很可能不够，数值根据模型大小调整。--gpu-memory-utilization 0.9表示允许框架用掉 90% 的显存，给 CUDA context 和驱动留了点余量。--max-model-len 8192是上下文长度上限，如果你希望 32K 长上下文，显存必须够大。

3.4 用 Compose 固化配置，避免每次敲长命令

命令行方式适合验证，日常维护我更喜欢 Compose。写一个docker-compose.yml：

version: "3.8" services: llm-qwen: image: vllm/vllm-openai:v0.6.3 container_name: llm-qwen command: - --model=/models/Qwen2.5-7B-Instruct - --served-model-name=qwen2.5-7b - --max-model-len=8192 - --gpu-memory-utilization=0.9 - --host=0.0.0.0 - --port=8000 volumes: - /data/models:/models ports: - "8000:8000" shm_size: "8g" deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped

注意 Compose 的 GPU 配置在旧版本用的是runtime: nvidia，新版本推荐用deploy.resources.reservations.devices这种写法。如果你用的 Docker Compose 版本比较老，可能需要调整。启动命令：

docker compose up -d

3.5 日志观察与冷启动判断

容器启动后，用docker logs -f llm-qwen观察日志。第一次启动要加载权重，可能会等几分钟，这是正常的，不是卡死。当你看到类似Starting vLLM API server on http://0.0.0.0:8000的日志时，就说明服务已经就绪。

冷启动期间如果访问接口，返回连接拒绝很正常。我做速通时会直接写一个小脚本轮询健康状态，日志出现Uvicorn running on或者类似的监听字样，就可以进入下一步测试了。

4. 接口测试与常见报错排查实录

部署完成只是第一步，能不能正常对话才是真正要验证的。我习惯用 curl 模拟一次请求，这样能排除很多前端问题，直接暴露后端服务是否正常。

4.1 用 curl 验证 OpenAI 兼容接口

标准的 OpenAI 兼容接口是POST /v1/chat/completions，请求体包含model、messages等字段。示例：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5-7b", "messages": [ {"role": "user", "content": "写一段关于 Docker 部署大模型的简短介绍"} ], "max_tokens": 256 }'

返回里应该包含choices数组和生成的文本。如果返回错误码 404，大概率是你用的模型名不对，确认--served-model-name参数；如果返回 400，看一下报错信息里的字段是否符合接口规范。

通了以后，你就可以用任意支持 OpenAI 接口的客户端配置 Base URL 为http://服务器IP:8000/v1来对接了。很多开源项目都兼容这个接口，配置里填地址就完事。

4.2 常见报错与排查速查表

我整理一个遇到过比较多次的问题速查表，不一定每条都会遇到，但遇到了可以快速定位。

4.3 两处我自己踩过的坑

第一个是共享内存。我第一次部署时没设置--shm-size，启动后日志里出现RuntimeError: DataLoader worker (pid(s) ...) exited unexpectedly，折腾了半天才想到是/dev/shm空间不够。大模型推理的数据加载涉及大量共享内存读写，默认的 64 MB 完全不是你该承受的，直接调到 8 GB 以上。

第二个是--gpu-memory-utilization调太高。我曾在一张 24 GB 的卡上跑一个 13B 模型，权重占 27 GB？等等，13B 模型 FP16 是 26 GB，已经放不下 24 GB 的卡了，所以说不能只看参数名。你选模型之前，把量化和精度换算做清楚，宁可先用 4-bit 量化部署，也别硬挤，挤到后来就是各种奇怪的 session 混乱。

4.4 速通常见问题与时间管理技巧

30 分钟内完成部署，本质上不是靠手速，而是靠减少无效操作。我在速通时会把时间分配为：前置检查 2 分钟，镜像拉取 10 分钟，权重准备 5 分钟，配置启动 5 分钟，接口验证 5 分钟，其余时间留给报错。如果你用的机器网络不好，镜像拉取会是最大的耗时变量，建议提前在本地缓存好镜像和权重。

如果你部署的是量化权重，比如 GGUF 格式，那镜像选择就换成llama.cpp的服务器镜像，挂载方式相同，但启动命令变成：

docker run -d \ --name llm-gguf \ --gpus all \ -v /data/models:/models \ -p 8080:8080 \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/qwen2.5-7b-q4_k_m.gguf \ --host 0.0.0.0 \ --port 8080

这种方式对显存要求更低，但生成的流畅度和效果跟完整精度相比有细微差异。综合下来，速通用它没问题，正式产品要看你的场景能不能接受。

5. 把模型服务接入业务系统的三个细节

跑通 API 之后，还有一个很多人忽视的环节：怎么把这个容器化的大模型服务稳定地接进你的业务系统。这里有几个细节，我写代码时经常遇到。

5.1 健康检查与优雅重启

容器编排工具会根据健康检查决定何时重启容器。vLLM 服务本身不需要额外加健康检查端点，但你可以用curl -f定期请求/health。如果你的 Compose 文件没有加healthcheck，容器进程在时不一定代表模型服务可用，尤其是长上下文占满显存之后的假死状态。

我习惯在 Compose 里加一段：

healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 5s retries: 3

这样监控系统可以看到服务真正的健康状态，而不是只看进程是否存在。

5.2 并发、排队和超时策略

大模型服务不是普通 Web 服务，单个请求可能耗时几秒甚至几十秒。如果你强依赖网关默认的 30 秒超时，长文生成很可能会被切断。我踩过这个坑，所以建议你在接入层显式设置更长的超时时间，至少 60 到 120 秒，并且开启流式输出。流式输出不仅能解决超时焦虑，也能让用户看到生成过程，体验好很多。

并发控制也很重要。vLLM 自身有调度机制，但你要设置合理上限，不让请求无限堆积。当max-num-seqs满了之后，新请求会排队，你要决定是让客户端等待，还是快速失败走降级策略。我见过一种做法，是额外起一个小模型服务处理简单问题，大模型只处理复杂请求，成本省很多。

5.3 多模型共存与显存隔离

很多人一台机器上不只跑一个模型。Docker 的 GPU 隔离能力很弱，默认--gpus all会让所有模型竞争显存，互相拖垮。一个比较实用的方案是用 NVIDIA MPS 或者 MIG，把显存切给不同容器，或者直接在一张卡上跑一个小模型，另一张卡跑一个大模型。

我在 Compose 里会限定count: 1，并且给不同服务指定不同的 GPU 序号，比如：

deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]

另一个服务就用device_ids: ["1"]。这样两个模型互不打扰，资源利用率也更高。

6. 部署后如何判断"够用"以及下一步怎么走

服务跑起来了，你可能想知道这个方案到底算不算“可以交付”。我一般看四个指标：启动时间、单请求延迟、并发吞吐、显存余量。启动时间从容器创建到接口就绪，目标最好在两分钟内完成，剩下时间都是我在调参。单请求延迟取决于模型大小和硬件，7B 模型在消费级显卡上首 token 延迟做到几百毫秒算正常。并发吞吐要看tokens/s，这个数值才是用户体感的关键。显存余量则提醒你还有多少空间可以支持更长上下文或更大并发。

如果你后续要接入 WebUI，直接用 Open WebUI 的容器镜像，把OPENAI_API_BASE_URL指向这个服务的地址就行。这里有一个小经验：WebUI 容器和推理服务最好放在同一个 Docker 网络里，用容器名互联，比通过宿主机端口转发更稳定。这样部署完不只是一个裸 API，而是一套完整可用的产品雏形。

从我个人项目管理角度看，Docker 大模型部署的价值不在于把服务跑起来，而在于让模型版本、硬件配置、服务参数全部变成可复现的配置。拿到一台新机器，一条docker compose up就能恢复整个环境，这才是 30 分钟速通真正的底气。