MetaX可用工具

C500 / MXMACA 当前可用工具简明说明

2026-06-07

本文档简要说明当前 c500-mxmaca-benchmark 工程里已经整理出的工具、用途和当前可用状态。

1. 一键验收与环境准备

工具 / 脚本	当前状态	作用
setup_env.sh	可用	配置 MXMACA 环境变量，例如 MACA_PATH、PATH、LD_LIBRARY_PATH。
run_acceptance.sh	可用	一键执行 C500/MXMACA 验收流程，包括环境、设备、编译、监控、benchmark、profiling 模板、报告生成等。
scripts/env_check.sh	可用	检查系统、CPU、内存、磁盘、Python、容器等基础环境。
scripts/device_check.sh	可用	检查 C500 GPU、显存、驱动、VBIOS、Firmware、RAS/event、mx-smi 等。
scripts/mxmaca_check.sh	可用	检查 /opt/maca、MXMACA SDK、macainfo、mxcc、cucc、Python 框架可见性。

2. MXMACA / 设备基础工具

工具	当前状态	作用
mx-smi	可用	查看 GPU 型号、显存、温度、功耗、利用率、进程、PCIe/HBM、RAS/event 等信息。
macainfo	可用	查看 MXMACA runtime、agent/device 能力信息。
mxcc	可用	MXMACA 编译器，用于编译 vectorAdd 等 MXMACA 示例程序。
cucc	可用	MXMACA CUDA bridge 编译工具。
官方 vectorAdd sample	可用	最小编译和运行验证样例，用于确认 MXMACA 编译链路正常。

3. 单卡 benchmark 与健康检查

工具 / 脚本	当前状态	作用
mxvs	可用	沐曦设备验证/轻量诊断工具，可做设备检查、PCIe 带宽、HBM/memory bandwidth、memory benchmark 等。默认不跑 stress。
scripts/mxvs_light.sh	可用	对 mxvs 做轻量、安全、可复现封装；容器缺 FUSE 时会尝试 APPIMAGE_EXTRACT_AND_RUN=1 fallback。
scripts/benchmark_light.sh	可用	轻量 benchmark 兼容入口，主要串联 mxvs_light 和可选 gpuBenchmark。
gpuBenchmark / scripts/gpubenchmark_light.sh	默认跳过	第三方/上游 microbenchmark；默认不 clone、不运行，需用户明确启用。

4. 监控工具

工具 / 脚本	当前状态	作用
scripts/monitor_mxsmi.sh	可用	采集 mx-smi snapshot 或短周期 dmon 数据。
monitoring/mx_smi_dmon_sample.sh	可用	在 benchmark 期间采集 mx-smi dmon 样本。
mx-exporter	可用，走 wheel/venv	暴露 Prometheus /metrics 指标，用于 GPU 利用率、显存、功耗等系统监控。
scripts/mx_exporter_check.sh	可用	使用项目内 isolated venv 启动 mx-exporter 并验证 /metrics。
monitoring/start_mx_exporter.sh	可用	前台启动 mx-exporter，适合手动监控实验。
monitoring/check_mx_exporter_metrics.sh	可用	curl /metrics 并提取关键指标线索。
Prometheus/Grafana 配置示例	模板可用	提供 scrape 配置和 Grafana 指标清单；本工程默认不部署 Prometheus/Grafana。

5. Profiling / 性能分析工具

工具 / 脚本	当前状态	作用
mcTracer	可用但有 RPC timeout 风险	Linux 端 timeline/trace 采集工具，用于 Runtime API、kernel、MCTX 标注、阶段排布分析。
profiling/run_mctracer_vectoradd.sh	可用	用 mcTracer 对 vectorAdd 或指定轻量命令采集 trace。
mcTracer-Viewer	当前缺失	Windows 端 trace 可视化工具，用于打开 mcTracer 生成的 JSON。需要从官方/平台工具包补齐。
mcProfiler / mcprofiler Linux CLI	当前缺失	预期用于 kernel metrics、SOL、RoofLine、memory/compute/scheduling 分析；当前本机未发现 CLI。
win-perf-kit / gui-profiler.exe	当前缺失	官方 mcProfiler GUI 工具包，通常在 Windows 端通过 SSH/RPC 连接 Linux 目标机采样。
profiling/run_mcprofiler_vectoradd.sh	模板可用	mcProfiler CLI 模板；当前主要记录 MISSING，不臆造未知参数。
profiling/run_mcprofiler_api_smoke.sh	可用但结果 WARN	编译运行官方 profilerScope 样例，验证 mcProfilerStart() / mcProfilerStop() API；当前未产出 counter/profile dump。
torch.profiler	可作为补充	可辅助查看 PyTorch/算子 timeline，但不能替代官方 mcProfiler 的 SOL/RoofLine/counter 指标。

6. LLM / vLLM 相关工具

工具 / 脚本	当前状态	作用
benchmarks/llm/vllm_metax_check.sh	可用，dry-run	检查 Python、Torch、vLLM import 和 C500 GPU 可见性；不下载模型、不加载大模型。
benchmarks/llm/start_server.sh	模板	LLM serving 启动模板，默认 dry-run。
benchmarks/llm/run_benchmark.sh	模板	LLM benchmark 模板，默认 dry-run。
benchmarks/llm/collect_mxsmi_dmon.sh	模板	LLM benchmark 期间的 dmon 采集模板，默认 dry-run。
benchmarks/llm/parse_results.py	模板	LLM benchmark 结果解析模板。

7. 报告与回归工具

工具 / 脚本	当前状态	作用
scripts/generate_report.py	可用	生成 artifacts/manifest.json 和 reports/c500_acceptance_report.md。
scripts/compare_baseline.py	可用	与 baseline/阈值比较，做回归判断。
scripts/export_junit.py	可用	导出 reports/junit.xml，用于 CI/JUnit 展示。
configs/regression_thresholds.yml	可用	定义验收和回归阈值，例如 C500 识别、显存、benchmark regression、RAS/event 等。

8. 当前建议使用顺序

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh

# 一键验收，包含 exporter smoke
./run_acceptance.sh --exporter-smoke

# 单独检查性能工具部署状态
./scripts/perf_tools_deploy_check.sh

# 单卡监控
./scripts/monitor_mxsmi.sh --mode snapshot --gpu-id 0
./scripts/monitor_mxsmi.sh --mode dmon --gpu-id 0 --duration-sec 10 --interval-ms 1000

# 轻量 benchmark
./scripts/mxvs_light.sh

# mx-exporter smoke
./scripts/mx_exporter_check.sh --isolated-venv --minimal-config --start \
  --port 18004 --interval-ms 1000 --ready-timeout-sec 55

# mcTracer trace 尝试
./profiling/run_mctracer_vectoradd.sh

9. 简短结论

当前稳定可用的是：

• C500/MXMACA 一键验收链路；
• mx-smi 单卡监控；
• mxvs 轻量诊断和 benchmark；
• mx-exporter Prometheus 指标采集；
• vectorAdd 编译运行验证；
• 报告、回归、JUnit 输出；
• mcTracer Linux 端 trace 尝试。

当前需要外部补齐的是：

• mcTracer-Viewer；
• mcProfiler 正式工具链，即 Windows win-perf-kit/gui-profiler.exe；
• 如需完整 LLM benchmark，还需要用户确认模型、dtype、输入输出长度、并发和运行策略。
  MoE算子测试