目录
master
分支20
标签1
+ 疑修
Web IDE
3294682143-gif
docs: expand Iluvatar deployment and validation guide
2天前138次提交
README.md

天数智芯算力运维助手 - YOLO 训练平台

面向天数智芯（Iluvatar）GPU 的 YOLO 训练、推理与运维监控平台。同一套代码可以在智铠 100（MR-V100）和天垓 150（BI-V150）实例上运行，通过运行时探测选择卡型策略，不为不同型号复制训练 runner、监控器或前端页面。

系统提供 Web UI、FastAPI API 和 MCP Server，可完成 GPU 状态采集、数据集与模型管理、YOLO 训练、图片/视频推理、任务日志和 AI 辅助运维。GPU 指标来自 ixsmi，训练和推理通过天数智芯 CoreX PyTorch 执行。

上游仓库

本项目基于 MetaX GPU Ops Agent 迁移和适配。

功能概览

模块 功能
总览 系统指标、GPU 状态、任务统计和 MCP 连接状态
服务器 节点列表、GPU 详情、利用率/显存/温度曲线、GPU 进程和 AI 诊断
训练 数据集与模型选择、训练参数校验、任务确认、提交和实时进度
任务 任务列表、状态、指标曲线、日志、取消和产物查看
模型 预训练权重和训练产物扫描、任务类型与模型兼容性检查
推理 图片/视频上传、模型选择、检测结果和标注结果展示
日志 API、MCP、Web、部署和训练日志的实时流
设置 Gitee AI 和节点信息配置

模力方舟运行环境

项目已在模力方舟的天数智芯 GPU 容器实例中完成双卡实测。以下数值来自实际运行环境，不用产品规格页数值代替运行时探测结果。

项目 实测环境
平台 模力方舟 GPU 算力实例，项目与持久化数据位于 /data
容器用户 root
Python 3.10.18；项目要求 Python 3.10 或更高版本
Node.js 18.20.8；Vite 6 要求 Node.js 18 或更高版本
IX-ML / Driver 4.4.0 / 4.4.0
PyTorch 天数智芯 CoreX PyTorch 2.7.1
PyTorch 系统路径 /usr/local/corex-4.4.0/lib64/python3/dist-packages/torch/__init__.py
Ultralytics 8.4.115（验收环境）
GPU 管理命令 ixsmi，不是 nvidia-smi 或 ix-smi
项目目录 新部署建议 /data/Iluvatar-gpu-ops-agent；已有迁移实例可保留原目录名
模型目录 /data/yolo_models
数据集目录 /data/datasets
作业目录/数据库 /data/yolo_jobs、/data/yolo_jobs.db
可选 Ultralytics 源码 /data/ultralytics-src，与模型目录分离
固定日志 .logs/api.log、.logs/mcp.log、.logs/web.log、.logs/deploy.log

已验收 GPU 型号

模力方舟卡型 运行时设备名 实测显存 设备 AMP 建议 batch workers
智铠 100 Iluvatar MR-V100 32768 MiB cuda:0 false 2 0
天垓 150 Iluvatar BI-V150 32768 MiB cuda:0 true 8 0

显存、设备数量和设备名由 ixsmi 与 torch.cuda 实时读取。即使规格文档给出不同显存，也以当前实例实际暴露的数值为准。

ixsmi 中的 CUDA Version 表示 IX-ML/CoreX 提供的 CUDA 兼容接口版本，不表示实例安装了 NVIDIA CUDA Toolkit。项目使用 PyTorch 的 torch.cuda 兼容命名空间访问天数智芯设备，因此 torch.cuda.is_available() == True 和设备名为 Iluvatar 才能证明计算链路可用；只看到 ixsmi 的版本字段不能证明 YOLO 可以训练。

天数 PyTorch 适配

继承 CoreX PyTorch

天数智芯镜像已经提供与驱动匹配的 CoreX PyTorch。项目虚拟环境必须继承系统包：

python3 -m venv --system-site-packages .venv
source .venv/bin/activate

deploy.sh 和 start.sh 都按此方式创建 .venv。requirements.txt 不声明 torch、torchvision、torchaudio 或 triton，安装逻辑还会再次过滤这些包，防止 PyPI 公版覆盖 CoreX 版本。

不要执行以下操作：

pip install torch torchvision torchaudio
pip install --upgrade torch

公版 PyTorch 即使能够导入，也通常不能加载 IX-ML/CoreX 运行库，会造成 torch.cuda.is_available() == False、计算卡死或运行时符号冲突。

ABI 与子进程环境

  • numpy>=1.26,<2：CoreX PyTorch 2.7.1 按 NumPy 1.x ABI 构建，NumPy 2.x 会导致 torch.from_numpy 等路径失败。
  • opencv-python==4.6.0.66 与 opencv-python-headless==4.6.0.66：与 CoreX/IGIE 环境保持一致。
  • typing_extensions>=4.12：保证 runner 的最小子进程环境能够导入 Pydantic、FastAPI 和 PyTorch 依赖。
  • runner 仅继承受控环境变量，并保留 LD_LIBRARY_PATH，确保 libixml.so 和 CoreX 动态库在训练子进程中可见。

GPU 探测与设备门禁

mcp_server/gpu_runtime.py、mcp_server/gpu_profile.py 和 mcp_server/device_config.py 共同提供统一运行时事实源：

  1. 使用 ixsmi 获取卡名、IX-ML 版本和真实显存。
  2. 使用 CoreX PyTorch 获取 torch.cuda 可用性、设备名、设备数量和总显存。
  3. 在独立子进程中执行最小 CUDA 张量计算、同步、反向传播和优化器更新，并设置超时。
  4. 只有计算健康检查通过，auto 才解析为 cuda:0。
  5. 设备白名单仅允许 auto、cpu 和 cuda:0。GPU 请求失败会返回具体错误，不会静默回退 CPU；CPU 只能显式选择。

健康结果带缓存和 single-flight 合并，避免 Web /nodes 轮询并发触发多次昂贵的 GPU 初始化。

YOLO 训练适配

双卡运行时策略

mcp_server/gpu_profile.py 是卡型、显存、AMP 和推荐 batch 的单一策略入口：

  • MR-V100 使用稳定优先配置：device=cuda:0、amp=false、batch=2、workers=0。
  • BI-V150 使用已实测配置：device=cuda:0、amp=true、batch=8、workers=0。
  • 未知天数智芯卡采用 MR-V100 的保守策略。
  • ILUVATAR_RECOMMENDED_BATCH 可以由运维人员覆盖推荐 batch；用户请求仍需通过 1..64 参数校验。
  • ILUVATAR_DEFAULT_AMP 只影响允许 AMP 的 BI-V150，MR-V100 不接受 amp=true。

Ultralytics 执行链路

训练任务由 Web/API/MCP 进入同一个受控 runner：

参数校验 -> 资产解析 -> 确认令牌 -> 作业入队 -> GPU 租约
         -> CoreX CUDA 健康检查 -> Ultralytics YOLO -> 日志/指标/权重归档

适配内容包括：

  • device=auto 通过统一设备解析器转换为 cuda:0，训练和推理使用同一门禁。
  • 训练参数使用固定 argv 和受控字段，不通过 shell 拼接用户输入。
  • 默认 workers=0，避免容器内多进程 DataLoader 与国产运行时组合出现阻塞。
  • 数据集 YAML 会校正 path/train/val/test，并将 image/img/imgs 目录规范为 images。
  • 根据 kpt_shape、mask 等字段推断 detect、pose 或 segment，并检查权重任务类型是否匹配。
  • 预置系统字体替代 Arial，关闭 Ultralytics 在线探测，避免训练时访问 GitHub。
  • 模型权重、可选源码和训练作业分别存放，部署不会覆盖已有 .pt 或训练产物。
  • yolov8n.pt 是离线 detect 服务的必需权重；yolov8n-pose.pt、yolo11s-pose.pt 等可选权重缺失只告警，不阻止 detect 服务启动。

训练前检查

cd /data/Iluvatar-gpu-ops-agent
source .venv/bin/activate

python -V
node -v
ixsmi

python - <<'PY'
import torch

print("torch_version:", torch.__version__)
print("torch_path:", torch.__file__)
print("cuda_available:", torch.cuda.is_available())
print("device_count:", torch.cuda.device_count())
if torch.cuda.is_available():
    props = torch.cuda.get_device_properties(0)
    print("device:", torch.cuda.get_device_name(0))
    print("memory_mib:", props.total_memory // 1024 // 1024)
PY

期望看到 CoreX PyTorch 路径、cuda_available: True、一个或多个设备，以及 Iluvatar MR-V100 或 Iluvatar BI-V150。

部署

克隆当前仓库

cd /data
git clone https://www.gitlink.org.cn/huowentan/Iluvatar-gpu-ops-agent.git
cd Iluvatar-gpu-ops-agent

首次在线安装并启动

在线模式只在 install、setup 或 all 阶段安装缺失依赖和尝试获取缺失的可选资产。已有依赖和权重会跳过，start 与 restart 永不安装或下载。

bash ./deploy.sh all

也可以拆分执行：

bash ./deploy.sh install
bash ./deploy.sh start
bash ./deploy.sh health

脚本要求：

  • Python 3.10 或更高版本，且基础镜像已经包含匹配驱动的 CoreX PyTorch。
  • Node.js 18 或更高版本。
  • 在线安装需要能够访问 Python/npm 软件源；外网受限时请预置依赖并使用离线模式。
  • 脚本不会安装或升级 PyTorch，不会覆盖已有模型权重。

真正离线部署

离线模式不会执行 pip/npm/apt 安装、Git 克隆或模型下载。使用前必须已经具备：

  • .venv 和全部 Python 依赖；
  • web/node_modules；
  • /data/yolo_models/yolov8n.pt；
  • 基础镜像中的 CoreX PyTorch 和 ixsmi。

以下两种写法等价：

ILUVATAR_OFFLINE=1 bash ./deploy.sh all
bash ./deploy.sh --offline all

离线缺少必需依赖或 detect 权重时会立即失败并列出缺失项；缺少 pose 等可选权重只产生告警。

服务管理

deploy.sh 是公开部署入口，内部将服务生命周期委托给 start.sh：

bash ./deploy.sh start
bash ./deploy.sh status
bash ./deploy.sh health
bash ./deploy.sh restart
bash ./deploy.sh stop

诊断和日志命令：

bash ./start.sh diagnostics
bash ./start.sh logs
tail -f .logs/api.log .logs/mcp.log .logs/web.log .logs/deploy.log

不要使用旧的 scripts/run.sh 启动生产服务。

端口与访问方式

端口 服务 监听/路径 用途
3001 Vite Web http://127.0.0.1:3001/ React 管理界面；浏览器请求通过 /api/* 代理到 8007
8007 FastAPI http://127.0.0.1:8007/ REST API
8007 FastAPI 文档 http://127.0.0.1:8007/docs OpenAPI/Swagger UI
8007 API 健康检查 http://127.0.0.1:8007/health 服务、监控与 GPU 计算状态
8007 节点 API http://127.0.0.1:8007/nodes 卡型、显存、AMP、batch 和设备状态
8765 MCP Server http://127.0.0.1:8765/mcp streamable-http MCP 入口
8765 MCP 健康检查 http://127.0.0.1:8765/health MCP 服务健康状态

http://127.0.0.1:3001/nodes 是前端路由，会返回 Vite/React HTML；节点 JSON 应请求 http://127.0.0.1:8007/nodes 或前端代理地址 http://127.0.0.1:3001/api/nodes。

模力方舟实例通常通过 SSH 网关进入。不要把实例密码、访问令牌或真实实例 ID 写入仓库。需要在本机浏览器验收时，使用占位信息建立隧道：

ssh -N \
  -L 3001:127.0.0.1:3001 \
  -L 8007:127.0.0.1:8007 \
  -L 8765:127.0.0.1:8765 \
  'root+<实例ID>@<模力方舟SSH主机>' -p <SSH端口>

只查看 Web 时仅转发 3001 即可；直接调用 API 或 MCP 时再转发 8007、8765。项目端口与 SSH 网关端口是两层不同映射，不要让 Web 占用平台预留的 Jupyter 端口。

配置

默认端口和数据目录可通过环境变量覆盖：

export API_PORT=8007
export WEB_PORT=3001
export MCP_PORT=8765
export DATA_ROOT=/data
export MODELS_ROOT=/data/yolo_models
export JOBS_ROOT=/data/yolo_jobs

部署脚本首次运行会生成 .env。Web 登录默认值仅用于本机首次启动；对外提供服务前必须修改：

export OPS_AUTH_USERNAME='<管理员用户名>'
export OPS_AUTH_PASSWORD='<高强度密码>'
export OPS_AUTH_SECRET='<随机长字符串>'

AI 助手是可选能力。未配置 Gitee AI 时，GPU 监控、训练和推理不受影响：

export GITEE_AI_API_KEY='<访问令牌>'
export GITEE_AI_MODEL='internlm3-8b-instruct'

令牌和密码只应写入服务器本地 .env 或密钥管理系统，不要提交到 Git。

完整验收流程

1. 代码与环境基线

git status --short
git rev-parse HEAD
python3 -V
node -v
ixsmi

确认工作区没有意外修改，设备名和显存与所选实例一致。随后执行“训练前检查”中的 PyTorch 探针，确认 CoreX Torch 路径和 cuda:0。

2. 两次离线幂等部署

使用无效代理作为联网门禁，并为每次运行使用独立日志：

set -o pipefail

env \
  ILUVATAR_OFFLINE=1 \
  HTTPS_PROXY=http://127.0.0.1:9 \
  HTTP_PROXY=http://127.0.0.1:9 \
  ALL_PROXY=http://127.0.0.1:9 \
  NO_PROXY=127.0.0.1,localhost \
  bash ./deploy.sh all 2>&1 | tee /tmp/iluvatar-offline-all-1.log
echo "OFFLINE_ALL_1_EXIT=${PIPESTATUS[0]}"

以 /tmp/iluvatar-offline-all-2.log 为日志文件再执行一次。两次退出码都必须为 0，并检查没有实际联网尝试：

grep -nEi \
  'Download failure|Downloading|github\.com|ultralytics\.com/assets|ConnectionPool|curl:|wget:' \
  /tmp/iluvatar-offline-all-1.log /tmp/iluvatar-offline-all-2.log \
  || echo 'OFFLINE_NO_NETWORK_OK'

需要看到 OFFLINE_NO_NETWORK_OK。不要扫描长期追加的 .logs/deploy.log 判断本轮结果，否则可能命中旧部署留下的下载记录。

3. 服务和端口

bash ./deploy.sh status
bash ./deploy.sh health

curl --noproxy '*' -fsS http://127.0.0.1:8007/health
curl --noproxy '*' -fsS http://127.0.0.1:8007/nodes
curl --noproxy '*' -fsS http://127.0.0.1:8765/health
curl --noproxy '*' -I http://127.0.0.1:3001/

期望 API、MCP、Web 全部健康，Web 返回 HTTP 200，/nodes 显示正确的 gpu_family、memory_total_mib、amp_allowed、recommended_batch、training_device=cuda:0 和 inference_device=cuda:0。

继续验证生命周期：

bash ./deploy.sh restart
bash ./deploy.sh health
bash ./deploy.sh stop
bash ./deploy.sh status
bash ./deploy.sh start
bash ./deploy.sh health

4. YOLO 训练与推理

在 Web 的“训练”页面导入本地数据集 YAML/ZIP，选择本地 detect 权重并运行 1 epoch：

卡型 device batch workers AMP
MR-V100 auto 或 cuda:0 2 0 false
BI-V150 auto 或 cuda:0 8 0 true

验收要求：

  1. 参数校验通过并取得确认令牌。
  2. 任务状态从 queued/staging/running 进入 succeeded，退出码为 0。
  3. 日志明确显示 execution_device=cuda:0，ixsmi 能看到训练进程和显存变化。
  4. 作业目录生成 weights/best.pt 和 weights/last.pt。
  5. 在“推理”页面选择刚生成的 best.pt，上传本地图片，结果状态为 succeeded，并生成检测结果与标注图。
  6. 训练和推理期间不能下载数据集、模型或字体；不要使用会触发自动下载的远程 coco8.yaml。

5. 权重和 CoreX 完整性

部署和训练前后分别记录：

sha256sum /data/yolo_models/*.pt

.venv/bin/python - <<'PY'
import torch
print(torch.__version__)
print(torch.__file__)
print(torch.cuda.is_available())
print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'unavailable')
PY

已有模型 SHA256 不得因重复部署发生变化，PyTorch 仍应来自 CoreX 系统目录。

6. 自动化回归

source .venv/bin/activate
pytest -q

cd web
npm run build

迁移基线 96b219f 的验收结果为 1240 passed / 0 failed，前端 TypeScript 检查和 Vite 生产构建通过。真实 MR-V100 与 BI-V150 均完成 cuda:0 的 1 epoch YOLO 训练和 best.pt 推理；MR-V100 使用 batch=2, workers=0, amp=false，BI-V150 使用 batch=8, workers=0, amp=true。

常见问题

ixsmi 正常，但 PyTorch 不能使用 GPU

ixsmi 只证明管理驱动可见。继续检查 torch.__file__、torch.cuda.is_available() 和最小张量计算。如果 torch 来自 .venv/site-packages 或 PyPI，重建采用 --system-site-packages 的虚拟环境，并恢复镜像自带的 CoreX PyTorch；不要安装公版 torch。

YOLO 尝试下载 coco8.zip 或权重

这通常表示数据集或权重只写了逻辑名称，但本地文件不存在。将数据集 YAML、图片、标签和 .pt 权重放入 /data/datasets、/data/yolo_models，使用绝对路径或已注册别名，并开启 ILUVATAR_OFFLINE=1。离线模式缺少必需 detect 权重会明确失败，不会继续尝试联网。

Web 可访问，但节点或训练页面无数据

检查 8007 和 8765，而不只检查 3001：

curl --noproxy '*' http://127.0.0.1:8007/health
curl --noproxy '*' http://127.0.0.1:8007/nodes
curl --noproxy '*' http://127.0.0.1:8765/health

如果 status 显示未响应但 health 正常，检查 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 和 localhost 的 IPv4/IPv6 解析，优先使用 127.0.0.1 与 --noproxy '*' 复核。

Vite 启动时报 Node.js 语法错误

Vite 6 不支持 Node.js 12。升级到 Node.js 18 或更高版本并重新安装前端依赖，不要在 Node.js 12 环境继续运行 npm run dev。

GPU 训练失败或卡住

  • MR-V100 确认 amp=false, batch=2, workers=0。
  • BI-V150 从已验收的 amp=true, batch=8, workers=0 开始，显存不足时再降低 batch。
  • 检查 .logs/api.log、.logs/mcp.log 和 /data/yolo_jobs/<job_id>/runner.log。
  • 检查 numpy<2、固定 OpenCV 版本以及 runner 子进程中的 LD_LIBRARY_PATH。
  • GPU 不健康时系统不会自动改用 CPU；如需临时 CPU 验证，必须显式选择 cpu。

技术栈

层 技术
Web React 18.3、Ant Design 5、Recharts 2、Vite 6、TypeScript 5.6
API FastAPI、Uvicorn、Pydantic 2
MCP MCP Python SDK 1.x、streamable-http
训练/推理 Ultralytics YOLO 8.4、CoreX PyTorch 2.7.1
GPU 监控 天数智芯 ixsmi / IX-ML 4.4.0
持久化 SQLite、文件系统作业目录、SHA256 证据

文档

License

Apache-2.0

关于

天数算力运维助手 - 基于MCP协议的国产GPU运维智能体

README.md
299.8 MB
Apache-2.0
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号