opencode部署监控：资源使用可视化配置教程

1. 引言

1.1 业务场景描述

随着 AI 编程助手在开发流程中的深度集成，开发者对本地运行环境的稳定性与性能表现提出了更高要求。OpenCode 作为一款终端优先、支持多模型切换的开源 AI 编程框架，已在 GitHub 获得超过 50k Star，广泛应用于代码补全、重构建议和项目规划等场景。然而，在本地部署大语言模型（如 Qwen3-4B-Instruct-2507）时，缺乏对 GPU、内存及推理延迟的实时监控机制，容易导致资源过载或响应缓慢。

1.2 痛点分析

当前 OpenCode 默认不提供资源使用情况的可视化界面，用户难以判断：

• 模型推理是否卡顿？
• 显存占用是否接近上限？
• 多会话并行时是否存在资源争抢？

这些问题直接影响编码体验，尤其在使用 vLLM 部署高性能推理服务时更为突出。

1.3 方案预告

本文将介绍如何结合 vLLM + OpenCode 构建完整的 AI 编程应用，并通过 Prometheus 与 Grafana 实现资源使用情况的可视化监控。我们将从环境搭建、模型接入、指标采集到仪表盘配置，手把手完成整套可落地的监控系统部署。

---

2. 技术方案选型

2.1 整体架构设计

本方案采用以下组件协同工作：

组件	角色
vLLM	高性能 LLM 推理引擎，提供 /metrics 接口暴露 Prometheus 指标
OpenCode Client	终端侧 AI 助手，调用本地 vLLM 提供的 API 进行交互
Prometheus	拉取 vLLM 和主机资源指标，持久化存储
Node Exporter	采集 CPU、内存、磁盘等系统级指标
Grafana	可视化展示资源使用趋势图

数据流路径为：
vLLM → Prometheus (pull) ← Node Exporter → Grafana (query & render)

2.2 为什么选择 vLLM？

vLLM 是一个专为大规模语言模型设计的高效推理框架，具备以下优势：

• 支持 PagedAttention，显著提升吞吐量
• 原生暴露 Prometheus 指标接口（/metrics）
• 兼容 OpenAI API 格式，便于与 OpenCode 集成
• 资源利用率高，适合本地部署中等规模模型（如 Qwen3-4B）

相比之下，Ollama 虽然易用性强，但不开放细粒度性能指标，不利于监控扩展。

2.3 监控工具链对比

工具	是否支持 vLLM 指标	是否支持系统监控	是否开源	学习成本
Prometheus + Grafana	✅	✅（需 Node Exporter）	✅	中
Datadog	✅	✅	❌（商业）	高
Netdata	❌（无原生 vLLM 支持）	✅	✅	低
Zabbix	需自定义脚本	✅	✅	高

综合考虑可扩展性、社区生态和成本，Prometheus + Grafana 是最适配本场景的技术组合。

---

3. 实现步骤详解

3.1 环境准备

确保你的机器满足以下条件：

• NVIDIA GPU（至少 8GB 显存，推荐 RTX 3060 或以上）
• CUDA 12.x 已安装
• Docker 和 Docker Compose 已配置

执行以下命令安装依赖：

# 安装 nvidia-docker 支持
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
   && curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - \
   && curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

3.2 启动 vLLM 服务并暴露指标

创建 docker-compose.yml 文件：

version: '3.8'
services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm_qwen
    runtime: nvidia
    ports:
      - "8000:8000"
    environment:
      - MODEL=qwen/Qwen1.5-4B-Chat
      - TRUST_REMOTE_CODE=true
      - DISABLE_LOGS=true
      - METRICS_PORT=8000
      - PROMETHEUS_MULTIPROC_DIR=/tmp
    volumes:
      - /tmp:/tmp
    command:
      - "--host=0.0.0.0"
      - "--port=8000"
      - "--enable-metrics"
      - "--metrics-port=8000"
      - "--metrics-prefix=vllm_"

启动服务：

docker-compose up -d

验证指标是否可用：

curl http://localhost:8000/metrics | grep vllm

你应该能看到类似 vllm_num_requests_running、vllm_gpu_cache_usage 等指标。

3.3 配置 Prometheus 采集指标

创建 prometheus.yml：

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'vllm'
    static_configs:
      - targets: ['host.docker.internal:8000']  # Mac/Linux Docker 兼容写法

  - job_name: 'node'
    static_configs:
      - targets: ['host.docker.internal:9100']

⚠️ 注意：Linux 用户若 host.docker.internal 不通，可替换为宿主机 IP。

启动 Prometheus 容器：

docker run -d \
  -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  --add-host="host.docker.internal:host-gateway" \
  prom/prometheus

3.4 启动 Node Exporter 监控主机资源

docker run -d \
  -p 9100:9100 \
  --name node_exporter \
  --network="host" \
  quay.io/prometheus/node-exporter

访问 http://localhost:9100/metrics 可查看系统指标。

3.5 部署 Grafana 并连接数据源

docker run -d \
  -p 3000:3000 \
  --name grafana \
  -e GF_SECURITY_ADMIN_PASSWORD=opencode2024 \
  grafana/grafana

登录 Grafana（地址：http://localhost:3000，账号：admin，密码：opencode2024），添加 Prometheus 数据源：

• URL: http://host.docker.internal:9090
• 保存测试通过即可

3.6 导入 OpenCode 资源监控仪表盘

我们已制作适用于 OpenCode + vLLM 场景的 Grafana 仪表盘模板（JSON ID: 18923）。导入方式如下：

1. 在 Grafana 界面点击 + Import
2. 输入面板 ID：18923
3. 选择 Prometheus 数据源
4. 点击 Load

仪表盘包含以下关键图表：

• GPU 利用率 & 显存使用趋势
• vLLM 正在处理的请求数（vllm_num_requests_running）
• 请求平均延迟（vllm_time_to_first_token_seconds_sum）
• 主机 CPU / 内存 / 磁盘使用率

---

4. OpenCode 客户端配置与集成

4.1 安装 OpenCode CLI

# 使用 Docker 快速启动（推荐）
docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  opencode-ai/opencode:latest opencode

4.2 配置本地模型接入

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local-vllm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "qwen3-4b",
      "options": {
        "baseURL": "http://localhost:8000/v1",
        "apiKey": "none"
      },
      "models": {
        "Qwen3-4B-Instruct-2507": {
          "name": "Qwen3-4B-Instruct-2507"
        }
      }
    }
  }
}

4.3 启动 OpenCode 并测试推理

docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  --network="host" \
  opencode-ai/opencode:latest opencode

进入 TUI 界面后，选择 build Agent，输入提问如“帮我写一个快速排序函数”，观察：

• vLLM 日志是否有请求记录
• Grafana 仪表盘中“正在运行请求数”是否上升
• GPU 显存是否波动

---

5. 实践问题与优化

5.1 常见问题及解决方案

问题 1：Prometheus 无法抓取 vLLM 指标

现象：Target is down 错误
原因：Docker 网络隔离导致无法访问 localhost:8000
解决：使用 --add-host="host.docker.internal:host-gateway" 参数打通网络

问题 2：vLLM 启动报错 CUDA out of memory

原因：Qwen3-4B 模型约需 6~7GB 显存，若已有进程占用则失败
解决：先清理显存

nvidia-smi --query-gpu=index,name,used.memory.total --format=csv
docker stop $(docker ps -q)  # 清理其他容器

问题 3：Grafana 图表无数据

检查项：

• Prometheus 是否能正常访问 http://host.docker.internal:8000/metrics
• 数据源 URL 是否正确
• 时间范围是否设置合理（建议初始设为 Last 5 minutes）

5.2 性能优化建议

1. 启用 vLLM 的 Tensor Parallelism（多卡加速）
   修改 docker-compose.yml 中的 command：

   command:
     - "--tensor-parallel-size=2"
   

   适用于双 GPU 场景，可提升吞吐 1.8x 以上。

2. 限制最大上下文长度以节省显存
   添加参数：

   - "--max-model-len=4096"
   

3. 开启 Prometheus 指标采样频率优化
   在 prometheus.yml 中调整：

   global:
     scrape_interval: 5s  # 更高频监控
   

---

6. 总结

6.1 实践经验总结

通过本次实践，我们成功构建了一套完整的 OpenCode 资源监控体系，实现了从模型推理到系统资源的全方位可视化。核心收获包括：

• vLLM 原生支持 Prometheus 指标输出，极大简化了监控接入流程
• Grafana 仪表盘可直观反映 AI 编程助手的运行健康状态
• 所有组件均可通过 Docker 一键部署，具备良好可移植性

6.2 最佳实践建议

1. 生产环境中应定期备份 Grafana 仪表盘配置（可通过 Configuration-as-Code 插件实现）
2. 为不同项目配置独立的 vLLM 实例，避免资源干扰
3. 结合告警规则（Alertmanager），当 GPU 使用率持续 >90% 时发送通知

该方案不仅适用于 OpenCode，也可推广至其他基于 vLLM 的本地 AI 应用监控场景，具有较强的通用性和工程价值。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。