算力集群智能运维 Agent

面向国产 AI 算力平台的智能运维 Agent Demo。项目围绕“模拟算力集群数据源 + 可切换大模型适配层”构建，目标是在没有完整真实 GPU 集群的情况下，先做出一个可以演示、可以部署、可以继续接入真实沐曦/GiteeAI 资源包的智能体应用闭环。

本项目用于 CCF AIGC 与智能体开发类比赛选题探索，重点展示 Agent 在算力平台运维场景中的任务理解、工具调用、日志分析、知识库检索、状态追踪、模型调用和报告生成能力。

项目定位

在实际 AI 算力平台中，训练任务失败、显存不足、推理接口超时、容器异常退出、GPU 利用率异常等问题非常常见。传统排查方式通常需要人工查看任务状态、GPU 指标、服务日志和调用记录，定位成本较高。

本项目希望把这些运维动作封装成 Agent 工具链：

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

当前版本已经具备可视化 Web 控制台和 CLI 演示入口，可作为后续接入真实算力集群、真实监控系统、真实模型服务的基础版本。

已完成功能

1. 模拟算力集群数据源

已构建一套用于演示的 Mock 集群数据，包括：

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

数据位于：

data/mock_cluster/

2. Agent 运维分析流程

已实现基础 Agent 工作流：

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

核心代码位于：

agent/engine.py

3. 工具调用能力

已实现多个工具模块：

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

目前支持的典型场景：

• 训练任务 OOM；
• 推理服务延迟升高；
• 容器异常退出；
• GPU 利用率偏低和调度异常。

4. 本地知识库

已整理轻量级运维知识库：

data/knowledge_base/

包含：

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

5. 模型适配层

项目支持两种模型模式：

mock：本地模拟模型，不访问网络，适合快速演示和离线测试
real：调用 GiteeAI / 沐曦资源包上的真实模型

已完成 GiteeAI OpenAI-compatible Chat Completions 接口适配：

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

默认模型配置：

MUXI_MODEL_NAME=Qwen3-32B

模型调用代码位于：

models/provider.py

详细配置说明见：

docs/model_config_summary.md

6. 可视化 Web 控制台

已完成可视化页面，包含：

• 集群总览；
• 集群拓扑；
• GPU 指标；
• 任务队列；
• 告警中心；
• Agent 分析输入区；
• Mock / Real 模型模式切换；
• Agent 执行时间线；
• 模型调用日志；
• 结构化故障报告展示和复制。

前端文件位于：

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

后端服务位于：

app/server.py

7. CLI 演示入口

支持命令行直接运行 Agent：

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

也可以强制调用真实模型：

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

8. 日志留存

运行日志默认写入：

logs/agent_runs.jsonl
logs/model_calls.jsonl

记录内容包括：

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

注意：日志目录默认不建议提交到公开仓库。

9. 部署材料

已提供：

• Dockerfile
• .dockerignore
• .env.example
• docs/deployment.md

可以本地运行，也可以部署到云服务器。

快速开始

环境要求

项目当前版本不依赖第三方 Python 包，推荐：

Python 3.10+

启动 Web 控制台

python -m app.server

浏览器访问：

http://127.0.0.1:7860

运行 CLI Demo

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

推荐测试问题：

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

使用真实模型

复制配置文件：

Copy-Item .env.example .env

填写：

MODEL_MODE=real
MUXI_API_BASE_URL=https://ai.gitee.com/v1
MUXI_API_KEY=你的 API Key
MUXI_MODEL_NAME=Qwen3-32B
MUXI_REQUEST_TIMEOUT=90
MUXI_NO_THINK=true

说明：

• MODEL_MODE=mock：只使用本地模拟模型；
• MODEL_MODE=real：调用真实 GiteeAI / 沐曦资源包模型；
• MODEL_MODE=auto：检测到 API Key 时调用真实模型，否则退回 mock；
• MUXI_NO_THINK=true：针对 Qwen3 模型，自动在用户消息前添加 /no_think，减少 content 为空的问题。

API Key 不要写入 README，不要提交到 GitLink。

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 分析

POST /api/chat 示例：

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

测试

python -m unittest discover

当前测试覆盖：

• 训练 OOM 流程；
• 推理延迟流程；
• 集群统计；
• Dashboard 聚合数据。

部署

直接部署

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

然后访问：

http://服务器公网IP:7860

Docker 部署

docker build -t muxi-ops-agent .
docker run -p 7860:7860 --env-file .env muxi-ops-agent

更多说明见：

docs/deployment.md

项目结构

CCF_AGENT_PROJECT/
  app/                  CLI、配置、Web API 服务
  agent/                Agent 工作流与提示词
  models/               模型适配层和调用日志
  tools/                集群、日志、知识库、报告工具
  data/mock_cluster/    模拟节点、GPU、任务、告警和日志
  data/knowledge_base/  运维知识库
  web/                  可视化控制台页面
  docs/                 开发计划、部署说明、模型配置说明
  tests/                单元测试
  Dockerfile            容器化部署文件
  .env.example          环境变量模板

上传 GitLink 前注意事项

上传前请确认不要提交敏感或运行产物：

APIKEY.txt
.env
logs/
__pycache__/
*.pyc

这些文件已经在 .gitignore 或 .dockerignore 中配置，但上传前仍建议人工检查一次。

后续规划

1. 接入真实算力集群监控

当前集群数据来自 Mock JSON 文件。后续计划抽象真实数据采集器，支持接入：

• GPU 指标采集工具；
• 容器运行时日志；
• 训练任务调度系统；
• 推理服务网关日志；
• Prometheus / Grafana / Loki 等监控系统。

2. 增强 Agent 编排能力

当前 Agent 是轻量流程式实现。后续计划引入更标准的 Agent 编排方式：

• LangGraph 状态图；
• 多 Agent 协作；
• 故障分类 Agent；
• 日志分析 Agent；
• 报告生成 Agent；
• 工单生成 Agent。

3. 增强 RAG 能力

当前知识库采用轻量文本检索。后续计划支持：

• 向量数据库；
• 运维手册批量导入；
• 厂商文档检索；
• 真实故障案例沉淀；
• 回答引用来源。

4. 增强真实模型调用

后续将继续完善：

• 多模型选择；
• 模型调用失败重试；
• 流式输出；
• token 使用统计；
• 调用成本统计；
• Qwen、DeepSeek 等模型的差异化 prompt。

5. 产品化与运营数据

为满足比赛第三阶段要求，后续计划补充：

• 公网部署；
• 用户反馈收集；
• 使用次数统计；
• 故障类型统计；
• 用户满意度记录；
• Demo 演示视频；
• 更完整的 GitLink 开源说明。

遇到的困难

1. 真实算力集群不易完整复现

比赛要求强调沐曦 GPU 算力环境，但完整搭建多节点 GPU 集群成本较高。当前采用“模拟集群数据源 + 真实模型适配层”的方式先完成可运行闭环，保证系统结构可以后续替换为真实数据采集器。

2. Qwen3 模型返回内容存在特殊性

在测试 Qwen3-32B 时，出现过接口调用成功但 message.content 为空的情况。排查后发现模型可能优先返回 reasoning_content，如果 max_tokens 太小，会在正式回答前被截断。

当前处理方式：

• 默认追加 /no_think；
• 增大 max_tokens；
• 响应解析时兼容读取 reasoning_content。

3. Agent 输出稳定性需要工程约束

单纯依赖大模型直接回答，容易出现格式不稳定、建议泛化、证据引用不清晰的问题。当前通过工具证据、知识库片段和固定报告模板来约束输出，保证 Demo 结果更稳定。

4. 可视化页面需要兼顾展示和部署

为了降低部署复杂度，当前 Web 控制台使用标准库 HTTP 服务和原生 HTML/CSS/JS 实现，没有引入复杂前端构建链。好处是部署简单，缺点是大型前端工程能力仍有限，后续如果继续产品化可以迁移到 React / Vue。

5. 日志与密钥安全

项目需要保存模型调用日志作为比赛证明，但又不能泄露 API Key 和敏感 prompt。当前只保存摘要信息，并通过 .gitignore 排除 .env、APIKEY.txt 和 logs/。

开发反馈

从开发过程看，这个选题比较适合比赛要求，原因是：

• 场景和国产算力平台强相关；
• 很容易展示工具调用能力；
• 故障日志、GPU 指标、任务状态天然适合做 Agent 证据链；
• 模型调用日志可以作为阶段二验收材料；
• Web 控制台适合阶段三部署展示。

当前版本的工程策略是先保证“可运行、可演示、可部署”，再逐步增强真实集群接入和 Agent 编排能力。这个路线比较务实：即使暂时没有完整真实集群，也能用 Mock 数据验证产品流程；一旦拿到真实沐曦/GiteeAI 资源，就可以通过模型适配层和数据采集器继续扩展。

后续开发中，最值得优先投入的是两件事：

1. 把 Mock 集群数据源替换为真实监控/日志数据源；
2. 把 Agent 流程从规则式编排升级为 LangGraph 状态图。

这样项目会从“比赛 Demo”逐步变成一个更完整的国产算力平台智能运维原型。