一文从零部署 Qwen 3.6:vLLM、接入 Agent 与监控面板实战指南
本文记录一次从零部署并应用大模型的实战流程:在 GPU 云服务器上使用 vLLM
v0.31.0部署Qwen/Qwen3.6-35B-A3B,再从 PC 上通过 OpenCode 接入模型并验证本地工具调用,最后在同一台云服务器部署 Prometheus、Grafana 和 DCGM Exporter,在 PC 浏览器打开监控链接查看服务与 GPU 状态。文章从环境准备、模型下载、服务启动和 API 验证写起,逐步完成 Agent 接入与监控配置。
提示:文中的服务器地址、目录和密钥均为示例值;部署时请替换为自己的配置,并确认 API 与监控端口和 Compose 映射一致。
图 1 展示了 PC 与云服务器之间的调用关系,模型推理与监控采集都在云端运行。
图 1:PC 运行 OpenCode 与浏览器,云服务器提供模型推理、指标采集和监控面板。
一、准备云服务器并确认 GPU 规格
本例使用 Qwen 官方模型 Qwen/Qwen3.6-35B-A3B作为该教程的示例模型。其中 35B 是模型总参数量,A3B 表示每个 token 推理时只激活约 3B 参数的 MoE 模型。稀疏激活可以减少每个 token 的计算量,但部署时仍要加载模型的大部分专家权重,因此不能按 3B 模型来估算显存。
Hugging Face 上的 Qwen/Qwen3.6-35B-A3B 仓库当前显示文件总量约为 71.9 GB,主要是 BF16 权重分片。这个数值可用来估算模型文件和权重加载的规模,不等于完整的推理显存需求;实际运行还需要为 KV Cache、运行时工作区等预留显存。Qwen3.6-35B-A3B 模型文件[1]
开始部署前,我们可以先查看下服务器的硬件资源情况:
记录 GPU 型号、卡数、单卡显存、已用显存、驱动版本、主机内存和可用磁盘。
当前 vLLM Qwen3.6 recipe[2] 为 BF16 路径列出约 84 GB 的显存门槛,并列出 FP8、NVFP4 等不同权重变体。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
本实战指南的示例命令以一张显存足够的 NVIDIA GPU为基线,参数从较小上下文开始。若实际实例需要多卡,可通过调整 --tensor-parallel-size 参数。
准备实例后,可以通过 SSH 终端和云控制台完成图 2 中的环境核验。GPU 与驱动、容器 GPU 访问、磁盘挂载和仓库出网在服务器终端检查,数据盘持久化属性与安全组来源在云控制台确认。
图 2:通过 PC 远程核验云服务器环境,检查 GPU、容器、数据盘、模型仓库出网与安全组。
1.1 安装 Docker 并验证 GPU 容器
为了减少主机 Python、PyTorch 和 CUDA 依赖之间的组合问题,本文用 vLLM 官方 Docker 镜像作为运行环境,见2.1节。云平台若提供预装 NVIDIA 驱动和容器工具包的 GPU 镜像,可以从该镜像开始;使用普通 Linux 镜像时,需要按对应发行版安装 NVIDIA Driver、Docker Engine 和 NVIDIA Container Toolkit,这里不再展开介绍。参见:云服务器上搭建和使用 Docker[3]
主机检查:
先确认宿主机能看到 GPU,再验证 Docker 容器是否能访问它:
如果宿主机的 nvidia-smi 正常、容器里看不到 GPU,应先检查 NVIDIA Container Toolkit 和 Docker runtime,不要先调整 vLLM 的模型参数。Docker Compose 可使用 GPU device reservation 将 GPU 分配给服务,count 与 device_ids 二选一;Compose 的 capabilities: [gpu] 是必填项。参见Docker Compose GPU 支持[4]
1.2 挂载模型缓存并设置网络边界
模型文件接近数十 GB。建议将模型权重放在云服务器的数据盘或明确可持久化的挂载盘,不要只留在容器可写层,也不要误放到实例释放后会清空的临时盘。示例目录如下:
二、下载 Qwen3.6 并固定 vLLM 版本
2.1 固定 vLLM 镜像版本
vLLM 和模型都在快速迭代。为便于排查,本文固定 vLLM 为 vLLM v0.31.0 Release[5],不使用 latest 代替。我们可以直接拉取该版本官方镜像,官方提供 CUDA 13.0 默认 NVIDIA 镜像,也提供 CUDA 12.9 变体;具体选择要与云服务器驱动兼容,并以目标实例实际启动为准。
2.2 下载模型权重并记录模型版本
模型仓库为 Qwen/Qwen3.6-35B-A3B。本教程先把权重下载到云服务器的数据盘,再让 vLLM 从本地目录加载。
Qwen 官方仓库同时提供 Hugging Face 与 ModelScope 下载入口;ModelScope CLI 的 --local_dir 参数可将模型直接保存到指定目录。Qwen3.6 官方仓库[6] · ModelScope 下载文档[7]
先创建统一的模型目录:
方式一:通过 Hugging Face CLI 下载。 先在模型仓库页面确认要使用的提交版本,将下面的占位值替换为对应 commit SHA:
方式二:通过 ModelScope 下载。 云服务器能访问 ModelScope、但访问 Hugging Face 不稳定时,可安装 ModelScope CLI 并直接下载到相同目录:
首次使用前,在下载环境安装 ModelScope CLI:
三、启动 vLLM 服务并验证 API
3.1 用 Docker Compose 启动服务
为了便于迁移部署和维护,我们推荐使用 Docker Compose 来启动服务。
在 /opt/qwen-vllm/.env 中填写本机参数。该文件包含 API Key,权限应限制为当前用户可读,并加入 .gitignore:
这里用 8192 仅作为较保守的起始上下文示例,不表示任何 GPU 配置下都保证能启动。根据 GPU 显存和实际服务目标调整 MAX_MODEL_LEN;如果模型权重本身无法装入,降低上下文也解决不了权重 OOM。
创建 compose.yaml:
检查 Compose 文件解析结果,再启动服务:
图 3 对应上面的 Compose 配置,展示了模型目录、GPU 和 API 端口与容器的关系。
图 3:持久化模型目录以只读方式挂载到 vLLM 容器,GPU 按配置分配,宿主机端口映射到容器内的 API 服务。
配置里几个容易混淆的点:
· entrypoint 和 command 组合后执行 vllm serve <model>。镜像固定到 v0.31.0,避免重新部署时悄悄拉到其他版本。
· 容器内服务监听 0.0.0.0:8000,是为了让 Docker 网络能访问容器。宿主机端口发布为 8000:8000,PC 才能通过服务器可访问地址来访问 vLLM 服务;能否连接由云平台安全组和服务器防火墙的来源规则决定,一般跟着云平台的教程来问题不大。
· VLLM_API_KEY 通过环境变量给到 vLLM。它保护 OpenAI 兼容 API,但不能替代网络隔离或 HTTPS;vLLM 的安全文档列出了一些不受 API Key 保护的操作端点,因此安全组和主机防火墙仍应限制访问来源。vLLM v0.31.0 安全说明[8]
· --reasoning-parser qwen3 和 --tool-call-parser qwen3_coder 用于解析 Qwen 的 reasoning 和工具调用输出。vLLM Qwen3.6 recipe[2] 提供了这组参数作为参考;实际是否正常工作,要进行实际端到端验证。
· count: 1 与 TP_SIZE=1 是单 GPU 示例。若目标模型需要多卡,Compose 的 GPU 数量和 TP_SIZE 都要改成实际规划值,并核实机器拓扑和 NCCL 初始化。
权重文件较大,首次启动需要完成模型下载、权重加载、显存规划和运行时初始化。只有日志出现模型加载完成并开始服务、且 API 检查成功,才算启动通过。
3.2 验证vLLM 服务 API
在服务器本机检查。先加载 .env 中的变量,让后续请求能读取 API Key:
第一步看服务健康状态:
第二步确认对外 model ID。因为配置了 API Key,/v1 请求要带 Bearer token:
第三步发送一个最小聊天请求:
检查 model 字段是否与 SERVED_MODEL_NAME 一致,并确认返回内容不是错误 JSON。服务器本机通过后,在 PC 机上将 YOUR_SERVER_ADDRESS 替换为 PC 能访问的服务器 IP 或域名,直接检查健康端点:
随后用同一地址请求 /v1/models 和 /v1/chat/completions,并携带 API Key。若连接超时,先确认安全组和服务器防火墙放行了来自 PC 的来源地址;若拒绝连接,再检查服务是否监听及 Docker 端口映射。若通过公网访问 API,应使用 HTTPS 入口,避免 API Key 和请求内容以明文传输。
四、接入 Agent 并验证工具调用
OpenCode 在 PC 上运行 Agent,模型推理仍由云服务器上的 vLLM 完成。它们分工不同:OpenCode 读取当前项目文件、组织对话并按权限执行本地工具;vLLM 接收请求并把 Qwen 的文本或工具调用结果返回给 OpenCode。代码上下文会随请求发送到云服务器,因此使用前要判断仓库内容是否适合发送到该服务。
这里选择 OpenCode 仅作为该实战指南的示例,当然,你可以选择其他任意Agent接入 vLLM 大模型服务。
如图 4 所示,模型返回工具调用后,由 PC 上的 OpenCode 检查权限、执行工具,再将结果发送给模型。
图 4:模型在云端生成工具调用,OpenCode 在 PC 侧确认权限并执行,将结果回传模型后获得最终回答。
4.1 配置自定义 Provider
先进入 OpenCode,在 /connect 中选择 Other,创建一个自定义 provider,例如 cloud-vllm,并录入与服务器一致的 API Key。OpenCode 将凭据存入自己的认证存储;具体字段应按所安装的 OpenCode 版本操作。参见OpenCode Provider 文档[9],这里不过多展开。
在当前项目的 opencode.json 中登记 endpoint 和模型。baseURL 指向 PC 可访问的服务器地址,模型 ID 对齐 vLLM 的 --served-model-name:
这里的上下文上限与输出上限是示例值,须与服务端 --max-model-len 和可用输出空间一致。
4.2 验证模型调用与工具权限
配置保存后,在 OpenCode 中用 /models 选择 cloud-vllm/qwen3.6-35b-a3b,先完成普通问答,再做一次经过确认的低风险工具任务,例如:
1. 让 Agent 读取项目中的一个指定 Markdown 文件并总结。
2. 检查它给出的文件引用和总结是否对应真实内容。
3. 再让它创建一个临时文本文件;在 OpenCode 的权限提示中确认操作。
4. 在 PC 本地检查文件是否创建、内容是否正确。
这个流程验证的不只是模型能否返回文本,还包括 vLLM 是否把工具调用解析为标准 API 格式、OpenCode 是否识别工具请求,以及本机权限流程是否按预期工作。模型不会因为部署在服务器上就自动获得服务器 shell 权限;这里执行文件和命令工具的是 PC 上的 OpenCode。
不同 Agent 产品对 OpenAI-compatible API、工具调用、reasoning 字段和权限模型的要求并不完全相同。迁移到其他 Agent 时,重新检查客户端支持的 API 类型、模型能力声明、上下文上限和工具调用格式。
五、部署监控面板
Prometheus、Grafana 与推理服务一起运行在云服务器上。Prometheus 定时采集 vLLM 和 DCGM Exporter 的指标,Grafana 查询这些数据并展示图表。在 PC 通过浏览器打开云端 Grafana 地址可随时查看相关服务指标。
下面继续使用云服务器上的 /opt/qwen-vllm/compose.yaml。四个服务共享同一个 Compose 网络,Prometheus 通过服务名采集,Grafana 通过内部地址查询。以下配置文件和启动命令均在云服务器上操作。
图 5 展示了云端的指标采集与查询关系,PC 通过 Grafana 查看结果。
图 5:Prometheus 在云端拉取 vLLM 与 GPU 指标,Grafana 查询并展示数据,PC 关闭后云端继续采集。
5.1 在云服务器运行 DCGM Exporter
vLLM 已通过 /metrics 暴露服务指标。DCGM Exporter 采集 GPU 利用率、显存等指标,默认监听容器内的 9400。在现有 compose.yaml 的 services 下追加以下服务,与 vllm 保持同级:
按所用 DCGM Exporter 版本配置 GPU 设备和容器权限。这里通过 Compose 内部网络访问 9400,无需发布到宿主机。
5.2 在云服务器配置 Prometheus 和 Grafana
在 /opt/qwen-vllm/prometheus.yml 中配置采集目标,使用 Compose 服务名和容器内端口:
继续在现有 compose.yaml 的 services 下追加 prometheus 和 grafana,并在文件顶层添加 volumes。下方是需要合并的配置片段,合并后应只有一个 services 节点,包含四个服务。命名卷分别保存指标历史和 Grafana 的用户、数据源与面板配置。参见Prometheus Docker 部署[10]
在云服务器原有 .env 中追加以下配置,保留前面的模型路径、API Key 等变量。将镜像占位值替换为实际选定的固定版本,DCGM Exporter 使用完整镜像地址与 tag;为 Grafana 设置独立的管理员密码:
在云服务器上启动新增服务:
Prometheus 的 9090 仅绑定云服务器回环地址。通过服务器终端检查采集状态:
在响应的 activeTargets 中确认 vllm 和 dcgm-exporter 对应的 health 均为 up。启动初期可等待一到两个采集周期后重试。修改 prometheus.yml 后,运行 docker compose restart prometheus 重新加载配置。
5.3 在 PC 浏览器打开云端监控面板
Grafana 的 3000 端口已发布到云服务器,安全组和主机防火墙需允许 PC 的固定出口 IP 或受控网段访问该端口。PC 浏览器打开 http://YOUR_SERVER_ADDRESS:3000,使用 .env 中设置的管理员账号和密码登录。通过公网长期访问时,为 Grafana 配置 HTTPS 域名入口,再使用 https://YOUR_GRAFANA_DOMAIN 访问。
在 Grafana 的数据源设置中添加 Prometheus,**URL 填 http://prometheus:9090**,保存并测试连接。这个地址由云端 Grafana 容器访问,浏览器只需能连接 Grafana。容器端口与持久化配置可参考官方文档Grafana Docker 部署[11]。
进入 Explore,选择 Prometheus 数据源并输入 PromQL。可以先查 GPU 利用率、vLLM 运行请求数和 KV Cache 使用率:
查询前缀缓存 token 命中率:
该比例按 token 数计算;最近 5 分钟没有缓存查询时可能没有曲线。vLLM 与 DCGM Exporter 指标的配置说明见 vLLM v0.31.0 Production Metrics[12] 和 DCGM Exporter Prometheus 指南[13]。
将这些查询保存为 Dashboard 面板后,PC 再次打开该 Dashboard 链接即可查看。GPU 和缓存占用可持续观察,TTFT 等请求指标需要在推理请求产生后才有相应数据。此处采集 GPU 和 vLLM 指标,CPU、主机内存和磁盘监控可通过额外部署 Node Exporter 扩展。
六、排查常见部署问题
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/connect 记录、provider ID 是否一致
|
|
|
|
--enable-auto-tool-choice
|
|
|
|
|
|
|
|
|
|
|
|
|
出现错误后,先保存完整日志和版本信息,确定问题是在主机、容器、模型加载、网络、API 还是 Agent 工具层,再一次改变一个条件。多卡错误尤其不要仅凭一条日志就认定是某个 NCCL 环境变量导致;用单卡/多卡对比和环境版本收集证据。
七、总结
完成部署后,云服务器上的 vLLM 提供 Qwen3.6 推理服务,PC 上的 OpenCode 调用模型并执行本地工具。Prometheus 持续采集服务与 GPU 指标,在浏览器打开 Grafana 就能查看运行状态和历史数据。
后续更换模型或接入其他 Agent 时,可以复用这套部署方式,再根据模型兼容性、显存需求和工具调用格式调整配置。
【从零走向AGI】旨在深入了解通用人工智能(AGI)的发展路径,从最基础的概念起,逐步构建完整的知识体系。
项目地址🔗:https://github.com/AI-mzq/From-Zero-to-AGI.git[14]
欢迎关注【魔方AI空间】👇
AIGC技术交流社区(涵盖AI绘画、AI视频、大模型、AI多模态、数字人、具身智能等AIGC干货资源及教程)欢迎大家加入:
► AIGCmagic社区
► 从零走向 AGI 系列
► 技术专栏: 多模态大模型最新技术解读专栏 | AI 视频最新技术解读专栏 | 大模型基础入门系列专栏 | 视频内容理解技术专栏 |
参考链接
1. Qwen3.6-35B-A3B 模型文件:https://huggingface.co/Qwen/Qwen3.6-35B-A3B/tree/main
2. vLLM Qwen3.6 recipe:https://github.com/vllm-project/recipes/blob/main/models/Qwen/Qwen3.6-35B-A3B.yaml
3. 云服务器上搭建和使用 Docker:https://cloud.tencent.com/document/product/213/46000
4. Docker Compose GPU 支持:https://docs.docker.com/compose/how-tos/gpu-support/
5. vLLM v0.31.0 Release:https://github.com/vllm-project/vllm/releases/tag/v0.31.0
6. Qwen3.6 官方仓库:https://github.com/AlibabaCloud-Official/Qwen3.6
7. ModelScope 下载文档:https://modelscope.cn/docs/models/download
8. vLLM v0.31.0 安全说明:https://docs.vllm.ai/en/v0.31.0/usage/security/
9. OpenCode Provider 文档:https://opencode.ai/docs/providers/
10. Prometheus Docker 部署:https://prometheus.io/docs/prometheus/latest/installation/
11. Grafana Docker 部署:https://grafana.com/docs/grafana/latest/setup-grafana/installation/docker/
12. vLLM v0.31.0 Production Metrics:https://docs.vllm.ai/en/v0.31.0/usage/metrics/
13. DCGM Exporter Prometheus 指南:https://docs.nvidia.com/datacenter/dcgm/latest/learn/getting-started-for-system-administrators/configure-prometheus-for-dcgm-exporter.html
14. https://github.com/AI-mzq/From-Zero-to-AGI.git:https://github.com/AI-mzq/From-Zero-to-AGI.git

