算力集群智能运维 Agent

项目简介

算力集群智能运维 Agent 是一个面向国产 AI 算力平台的智能体应用原型，主要用于辅助开发者和运维人员排查大模型训练、推理服务和 GPU 资源调度过程中的常见问题。

项目以 CCF AIGC 与智能体开发任务为背景，采用“Mock/Real 双集群数据源 + 可切换大模型适配层”的方式实现。当前版本既可使用内置多节点 Mock 数据稳定演示，也可通过 SSH 探针实时采集租用的沐曦 C500 节点，并调用魔力方舟 / GiteeAI 资源包大模型完成真实推理验证。

本项目希望解决的问题是：当算力平台出现训练任务失败、显存不足、推理接口超时、容器异常退出、GPU 利用率异常等情况时，用户不需要手动翻查大量日志和指标，而是可以通过自然语言向 Agent 提问，由 Agent 自动调用工具、检索日志、整理证据并生成结构化运维报告。

整体流程如下：

用户输入问题
  -> Agent 识别故障类型
  -> 查询 Mock 或真实沐曦集群状态
  -> 查询任务 / GPU / 告警 / 日志
  -> 检索运维知识库
  -> 调用 mock 或真实大模型分析
  -> 生成结构化故障报告
  -> 留存 Agent 运行日志和模型调用日志

当前项目已经提供 CLI 和 Web 两种演示入口。Web 控制台更适合比赛展示和后续部署，包含算力快速接入、集群总览、GPU 指标、任务队列、告警中心、Agent 分析流程、模型调用日志和故障报告展示。

演示材料

• 演示视频：Bilibili - 算力集群智能运维 Agent 演示
• 阶段一创意规划 PPT：ppt/stage1_creative_plan/index.html
• 技术说明文档：docs/technical_spec.md
• 部署指南：docs/deployment.md
• 发布包部署指南：docs/deployment_package.md
• 真实沐曦集群接入：docs/real_cluster_integration.md
• 多节点集群接入与验证：docs/multi_node_cluster.md
• 真实集群与模型联合调用证据：docs/real_call_evidence.md
• 真实 GPU 任务与 Agent 可用性证据：docs/real_workload_validation.md
• 真实 GPU OOM 故障与恢复验证：docs/real_failure_validation.md
• 双节点真实算力集群与 Agent 验证：docs/real_multi_node_validation.md
• 四节点真实算力资源池与 Agent 验证：docs/real_four_node_validation.md
• 开发计划与过程记录：docs/development_plan.md
• 决赛最终版成果清单：docs/final_submission.md
• 最终合并 PR 清单：docs/final_merged_pr_list.md

  功能说明

已完成功能

1. Mock/Real 双集群数据源

项目内置一套 Mock 集群数据，位于：

data/mock_cluster/

包括：

• 4 个模拟节点；
• 5 张曦云 C500 GPU 资源；
• GPU 利用率、显存、温度、功耗等指标；
• 训练任务、推理服务任务和等待任务；
• OOM、推理延迟、容器重启、低利用率等告警；
• 训练日志、推理日志、容器日志和调度日志。

项目同时提供真实沐曦节点采集链路：

collectors/muxi_node_probe.py  远端 MX-SMI 与系统指标探针
tools/cluster_source.py        SSH 采集、TTL 缓存、断连状态管理
scripts/deploy_muxi_probe.py   探针部署与验证脚本
scripts/deploy_muxi_cluster.py 多节点并发探针部署与验证

当前已适配 MetaX C500 的 sGPU 输出，可分别记录租户切片利用率、显存配额、计算配额，以及共享物理板卡利用率、温度和功耗，避免混淆两类指标。

真实采集支持 2 至 32 个清单节点并发连接、稳定节点 ID、节点级独立缓存和部分故障降级。一个节点 SSH 失败时，其余节点仍可继续提供实时指标，故障节点生成 NODE_COLLECTOR_UNAVAILABLE 告警。

项目还提供真实 MACA Runtime 任务验证链路：

workloads/muxi_gpu_workload.cpp   有时限的 MACA GPU 计算任务
workloads/run_gpu_workload.py     远端任务状态启动器
scripts/run_muxi_workload.py      部署、编译、采样、Agent 调用与验收
scripts/run_muxi_cluster_validation.py 多节点并发场景与聚合 Agent 验收

四节点实测资源池由三个 16 GB/25% sGPU 实例和一个 32 GB/50% sGPU 实例组成。健康并发场景的峰值利用率为 93%、93%、94%、94%，四个任务均正常完成；隔离故障场景中，32 GB 节点在 94% 负载后触发真实 mcMalloc out of memory，其余三个节点均正常完成且没有收到 OOM 告警。Agent 通过真实 Qwen/Qwen3-32B 准确定位故障节点，随后原节点以 94% 峰值通过恢复任务。详细证据见 docs/real_four_node_validation.md。

2. Agent 运维分析流程

核心流程位于：

agent/engine.py

支持：

• 接收自然语言问题；
• 识别故障意图；
• 根据任务编号或节点编号匹配相关数据；
• 调用工具读取任务状态、GPU 指标、告警和日志；
• 检索本地运维知识库；
• 调用模型适配层生成分析；
• 输出结构化故障报告；
• 记录每一步执行状态。

3. 工具调用能力

工具模块位于：

tools/

主要包括：

tools/cluster_tools.py  集群、节点、GPU、任务、告警、API 统计查询
tools/log_tools.py      日志检索
tools/rag_tools.py      运维知识库检索
tools/report_tools.py   故障报告生成

4. 本地知识库

知识库位于：

data/knowledge_base/

当前包含：

• 训练任务 OOM 处理手册；
• 推理服务延迟升高处理手册；
• 容器异常退出处理手册；
• GPU 调度与利用率优化说明。

5. 模型适配层

模型调用代码位于：

models/provider.py

支持两种模式：

mock：本地模拟模型，不访问网络，适合离线演示和测试
real：调用魔力方舟 / GiteeAI 资源包上的真实大模型

6. 可视化 Web 控制台

前端文件位于：

web/index.html
web/styles.css
web/app.js

后端服务位于：

app/server.py

页面功能包括：

• 集群总览；
• Mock/Real 集群来源与采集状态；
• 集群拓扑；
• GPU 指标；
• 任务队列；
• 告警中心；
• Agent 分析输入区；
• Mock / Real 模型模式切换；
• Agent 执行时间线；
• 模型调用日志；
• 结构化故障报告展示和复制；
• 在“算力接入中心”批量解析 SSH 命令、核验 Host Key、部署探针和管理节点。

7. CLI 演示入口

CLI 入口位于：

app/cli.py

可用于快速验证 Agent 分析流程。

8. 日志留存

运行日志默认写入：

logs/agent_runs.jsonl
logs/model_calls.jsonl

日志记录内容包括：

• Agent run id；
• 用户问题；
• 故障意图；
• 执行步骤；
• 模型模式；
• 模型名称；
• 调用状态；
• 延迟；
• prompt 和 response 摘要。

注意：logs/ 默认不建议上传到公开仓库。

项目同时提供脱敏后的真实联合调用样例 docs/real_call_evidence.md，用于 GitLink 公开验收；原始 JSONL 日志仅用于私密提交或现场演示。

当前支持的典型问题

job-20260531 训练失败了，帮我分析原因
DeepSeek 推理接口今天变慢了，帮我看看原因
node-c500-03 上的容器为什么异常退出？
GPU 利用率一直很低，帮我分析调度问题

使用的模型与算力环境

模型接入方式

项目当前适配魔力方舟 / GiteeAI 资源包的 OpenAI-compatible Chat Completions 接口：

POST https://ai.gitee.com/v1/chat/completions

默认模型配置：

MUXI_MODEL_NAME=Qwen3-32B

项目测试中接口实际返回的模型名可能显示为：

Qwen/Qwen3-32B

算力环境说明

本项目面向沐曦 GPU 算力环境设计。当前 Demo 采用两条可独立切换的真实链路：

模型链路：通过魔力方舟 / GiteeAI 资源包调用部署在国产算力环境上的 Qwen3-32B 等模型
集群链路：通过 SSH 探针采集真实 MetaX C500 节点，或使用本地 Mock 数据还原多节点场景

这种设计既保留比赛现场不依赖外部网络的稳定演示能力，也能够提供真实沐曦算力、真实指标和真实模型调用日志作为验收证据。详细接入说明见 docs/real_cluster_integration.md。

模型与集群配置项

配置模板位于：

.env.example

主要配置：

MODEL_MODE=real
MUXI_API_BASE_URL=https://ai.gitee.com/v1
MUXI_API_KEY=your-api-key
MUXI_MODEL_NAME=Qwen3-32B
MUXI_REQUEST_TIMEOUT=90
MUXI_NO_THINK=true
CLUSTER_MODE=real
CCF_CREDENTIAL_MASTER_KEY=生产环境使用的 Fernet 主密钥
MUXI_SSH_HOST=你的 SSH 地址
MUXI_SSH_PORT=SSH 端口
MUXI_SSH_USER=SSH 用户名
MUXI_SSH_AUTH=password
MUXI_SSH_PASSWORD_FILE=本机私有密码文件路径
MUXI_REMOTE_PROBE_PATH=/data/ccf_agent/muxi_node_probe.py
CLUSTER_SSH_TIMEOUT=12
CLUSTER_CACHE_TTL=5

说明：

• MODEL_MODE=mock：只使用本地模拟模型；
• MODEL_MODE=real：调用真实魔力方舟 / GiteeAI 模型；
• MODEL_MODE=auto：检测到 API Key 时调用真实模型，否则退回 mock；
• MUXI_NO_THINK=true：针对 Qwen3 模型，自动在用户消息前添加 /no_think，减少 content 为空的问题。
• CLUSTER_MODE=mock：读取内置多节点演示数据；
• CLUSTER_MODE=real：通过 SSH 读取真实沐曦节点，断连时使用最后一次成功快照并明确标记 stale；
• CLUSTER_MODE=auto：优先读取真实节点，无缓存且连接失败时回退 Mock。
• CCF_CREDENTIAL_MASTER_KEY：加密网页录入的 SSH 凭据；本地可留空自动生成，生产环境应固定配置并安全备份。

详细模型配置说明见：

docs/model_config_summary.md

运行与部署方法

环境要求

推荐环境：

Python 3.10+

安装 SSH 客户端依赖：

python -m pip install -r requirements.txt

本地运行 Web 控制台

python -m app.server

浏览器访问：

http://127.0.0.1:7860

使用网页快速接入算力

1. 点击页面右上角“连接算力”。
2. 每行粘贴一条平台提供的 SSH 命令，例如 ssh user@host -p 32222。
3. 点击“解析并检测指纹”，并与算力平台展示的 SSH Host Key 指纹核对。
4. 为每个节点选择密码或私钥认证，填写凭据后确认指纹。
5. 点击“连接并部署探针”，等待 SSH 验证、环境检测、探针部署和指标采集完成。

多个节点会并发接入；其中一个节点失败不会阻止其他节点加入资源池。成功后系统自动使用网页托管的真实集群清单，无需手工编辑 .env 或 JSON。远端仅写入 ~/.ccf-agent/muxi_node_probe.py，用于读取 Python、MX-SMI、MACA 和 GPU 指标。

在“已连接节点”中可以逐节点断开和重新连接。断开只会将节点移出实时采集资源池，保留节点配置、Host Key 和加密凭据，也不会终止远端正在运行的任务；重新连接会使用现有凭据验证 SSH 和 GPU 探针，无需再次输入密码。配置文件节点首次断开时，系统会自动生成运行时启停清单，不修改原配置文件。

本地连接状态保存在被 Git 忽略的 runtime/ 目录：

runtime/cluster_inventory.json  网页托管的节点清单
runtime/connections.json        最近连接状态和硬件能力
runtime/known_hosts             已确认的 SSH Host Key
runtime/credentials/*.enc       Fernet 加密后的 SSH 凭据
runtime/credential.key          本地自动生成的加密主密钥

密码和私钥不会写入清单或 API 响应，提交连接任务后也会立即从页面输入框清除。runtime/ 仍属于敏感运行数据，不得上传 GitLink、打包进镜像或公开分发。

本地运行 CLI

python -m app.cli "job-20260531 训练失败了，帮我分析原因"

强制调用真实模型：

python -m app.cli --real-model "job-20260531 训练失败了，帮我分析原因"

强制读取真实沐曦节点：

python -m app.cli --real-cluster "GPU 利用率一直很低，帮我分析调度问题"

执行真实 GPU 任务并调用真实模型验收：

python scripts\run_muxi_workload.py --node muxi-node-01 --duration 90 --model-mode real --sample-interval 3

执行真实受控 OOM 故障并验证 Agent 诊断：

python scripts\run_muxi_workload.py --node muxi-node-02 --duration 60 --failure-mode oom --failure-after-seconds 12 --model-mode real --sample-interval 3

OOM 模式下，远端任务按预期以非零码失败；只有状态文件、critical 告警、真实模型调用和 Agent 诊断全部通过时，本地验证脚本才返回 0。公开验证结果见 docs/real_failure_validation.md。

一次完成清单内全部节点的并发健康任务、单节点受控 OOM、故障隔离和聚合 Agent 诊断：

python scripts\run_muxi_cluster_validation.py --scenario all --failure-node muxi-node-03 --model-mode real

脚本先并发部署探针，再依次执行 healthy 和 isolated-oom 场景。默认使用清单中的全部节点，也可以重复传入 --node 选择子集。节点任务只负责产生并采集证据，每个场景最后由聚合集群快照触发一次 Agent / Qwen 调用；完整证据写入 logs/cluster_validation/<run-id>/combined_evidence.json。

配置真实模型与集群

复制配置文件：

Copy-Item .env.example .env

填写 .env：

MODEL_MODE=real
MUXI_API_BASE_URL=https://ai.gitee.com/v1
MUXI_API_KEY=your-api-key
MUXI_MODEL_NAME=Qwen3-32B
MUXI_REQUEST_TIMEOUT=90
MUXI_NO_THINK=true

请勿将 .env、APIKEY.txt 或任何真实 API Key 上传到 GitLink。

多节点集群使用不含密码的 JSON 清单和独立密码文件：

.\scripts\set_muxi_cluster_passwords.ps1
python scripts\deploy_muxi_cluster.py

配置格式和状态说明见 docs/multi_node_cluster.md。

Web API

当前后端提供以下接口：

GET  /api/dashboard      控制台聚合数据
GET  /api/cluster        集群概览
GET  /api/jobs           任务列表
GET  /api/metrics        GPU 指标
GET  /api/alerts         告警列表
GET  /api/model-calls    模型调用日志
GET  /api/runs           Agent 运行日志
POST /api/chat           执行 Agent 分析
GET  /api/connections    查询脱敏后的节点连接状态
POST /api/connections/parse         解析 SSH 命令
POST /api/connections/fingerprints  检测 SSH Host Key 指纹
POST /api/connections/connect       异步连接并部署探针
GET  /api/connection-tasks/{id}     查询连接任务进度
POST /api/connections/{id}/disconnect 停止采集并保留配置与凭据
POST /api/connections/{id}/reconnect 使用现有凭据重新连接节点
DELETE /api/connections/{id}         删除网页托管节点

POST /api/chat 示例：

{
  "query": "job-20260531 训练失败了，帮我分析原因",
  "model_mode": "mock"
}

测试

python -m unittest discover

当前测试覆盖：

• 训练 OOM 流程；
• 推理延迟流程；
• 集群统计；
• Dashboard 聚合数据。
• MetaX C500 物理卡与 sGPU 指标解析；
• 真实快照与统一集群查询契约；
• SSH 命令解析、危险语法拦截和主机脱敏；
• 凭据静态加密及连接任务响应不泄露凭据。

云服务器部署

HOST=127.0.0.1 PORT=7860 python -m app.server

第一版后端没有内置登录系统。由于算力接入接口会接收 SSH 密码或私钥，禁止把 7860 端口直接暴露到公网；云部署必须在服务前增加 HTTPS 反向代理和身份认证，只允许受信用户访问。完整配置原则见 docs/deployment.md。

Docker 部署

docker build -t muxi-ops-agent .
docker run -p 127.0.0.1:7860:7860 --env-file .env \
  -v "${PWD}/runtime:/app/runtime" \
  -v "${PWD}/logs:/app/logs" \
  muxi-ops-agent

更多部署说明见：

docs/deployment.md

上传 GitLink 前检查

请确认以下文件或目录没有被提交：

APIKEY.txt
.env
logs/
runtime/
config/muxi_cluster.local.json
__pycache__/
*.pyc

这些内容已配置在 .gitignore 或 .dockerignore 中，但上传前仍建议执行：

git status

示例输入输出

示例一：训练任务 OOM

输入：

job-20260531 训练失败了，帮我分析原因

系统执行流程：

1. 识别为训练任务显存不足或失败
2. 查询任务 job-20260531
3. 查询 node-c500-02 的 GPU 指标
4. 检索训练日志
5. 命中 OOM 告警和日志片段
6. 检索 OOM 处理知识库
7. 调用模型适配层完成分析
8. 生成结构化故障报告

输出摘要：

故障类型：训练任务显存不足
严重等级：high
根因判断：任务日志和 GPU 指标显示显存长时间接近上限，batch size 与序列长度配置偏高。

处置建议：
- 降低 batch size 或 max sequence length。
- 开启混合精度、梯度累积或检查点重计算。
- 清理同节点异常占用进程，必要时迁移到空闲 GPU。

示例二：推理服务变慢

输入：

DeepSeek 推理接口今天变慢了，帮我看看原因

输出摘要：

故障类型：模型推理服务延迟升高
严重等级：medium
根因判断：API 记录显示 P95 延迟升高，GPU 利用率和请求队列存在同时上升迹象。

处置建议：
- 临时降低并发或启用备用推理实例。
- 限制 max_tokens，检查长上下文请求占比。
- 观察模型服务是否发生重启、OOM 或队列积压。

示例三：容器异常退出

输入：

node-c500-03 上的容器为什么异常退出？

输出摘要：

故障类型：容器异常退出
严重等级：medium
根因判断：节点日志显示容器进程退出并触发重启，疑似依赖版本或启动参数不匹配。

处置建议：
- 查看容器启动命令和最近镜像变更。
- 回滚依赖版本或固定运行时镜像。
- 将退出码、stderr 和健康检查日志纳入告警。

示例四：GPU 利用率偏低

输入：

GPU 利用率一直很低，帮我分析调度问题

输出摘要：

故障类型：GPU 利用率偏低
严重等级：low
根因判断：任务队列和 GPU 指标显示部分节点空闲，可能存在数据加载瓶颈或调度不均衡。

处置建议：
- 检查 DataLoader worker、数据盘 IO 和网络读取延迟。
- 优化任务调度策略，把等待任务分配到空闲 GPU。
- 对低利用率任务增加指标采样和自动迁移策略。

参考来源说明

本项目的设计和实现参考了以下材料与来源：

1. CCF AIGC 与智能体开发比赛任务要求

项目围绕比赛中“基于国产算力平台的 AIGC 与智能体开发与应用”任务要求设计，重点覆盖：

• 智能体基础构建；
• 大模型 API 调用；
• 多轮对话与上下文管理；
• 工具调用能力；
• 任务执行状态跟踪；
• 可运行 Demo；
• Web 部署和开源提交。

2. 魔力方舟 / GiteeAI OpenAPI 文档

模型调用接口参考魔力方舟 / GiteeAI OpenAPI 文档中的 Chat Completions 接口：

https://ai.gitee.com/docs/openapi/v1

当前项目使用的接口形式：

POST https://ai.gitee.com/v1/chat/completions

3. 项目自建 Mock 数据

当前 data/mock_cluster/ 中的节点、任务、告警、日志和 GPU 指标均为项目演示构造数据，用于还原算力集群运维场景，不包含真实用户数据或真实生产日志。

4. 项目自建运维知识库

当前 data/knowledge_base/ 中的知识库内容由项目根据常见 AI 训练、推理服务和 GPU 调度故障场景整理，主要用于演示 RAG 检索流程和 Agent 证据链生成。

5. 开发过程总结

项目开发中遇到的主要问题包括：

• 真实多节点算力集群不易完整复现；
• Qwen3 模型可能优先返回 reasoning_content，导致 message.content 为空；
• Agent 输出需要通过工具证据和固定报告模板进行约束；
• Web 展示需要兼顾比赛演示效果和部署复杂度；
• 模型调用日志需要保留证明材料，同时避免泄露 API Key。

当前版本的处理方式是先保证“可运行、可演示、可部署”，再逐步替换 Mock 数据源、增强真实模型调用和 Agent 编排能力。