MetaX工具使用说明

C500 / MXMACA 工具详细说明与使用手册

生成日期：2026-06-08

本文档面向当前 /data/c500-mxmaca-benchmark 工程，详细说明我们现在有哪些工具、这些工具分别解决什么问题、应该怎么运行、输出在哪里、结果如何解释。

安全原则：默认只运行短时、轻量、非破坏性检查。不要执行 reset、刷固件、改功耗/频率/DPM、长时间 stress，除非用户明确要求并确认风险。

0. 快速入口

进入工程并加载 MXMACA 环境：

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

一键验收：

./run_acceptance.sh --exporter-smoke

运行 MoE 算子：

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
cd /data/tilelang-metax/race_tests/moe
bash run.sh

采集 MoE 的 mcTracer JSON：

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
mkdir -p artifacts/profiles/moe/manual_mctracer
mcTracer --ip 127.0.0.1 --mctx \
  --odname artifacts/profiles/moe/manual_mctracer \
  bash -lc "cd /data/tilelang-metax/race_tests/moe && bash run.sh"

1. 环境准备工具

1.1 `setup_env.sh`

作用：配置当前 shell 的 MXMACA 环境变量。

它会设置/追加：

MACA_PATH=/opt/maca
/opt/maca/bin
/opt/maca/mxgpu_llvm/bin
/opt/maca/tools/cu-bridge/bin
/opt/maca/lib
/opt/maca/lib64
/opt/maca/mxgpu_llvm/lib

用法：

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

必须用 source，否则变量只在子 shell 内生效。

检查：

echo $MACA_PATH
which mx-smi
which mxcc
which mcTracer

2. 一键验收工具

2.1 `run_acceptance.sh`

作用：一键执行 C500 / MXMACA 当前工程的完整轻量验收流程。

它覆盖：

系统环境检查；
GPU/C500 设备检查；
MXMACA SDK / 编译器检查；
官方 vectorAdd 编译运行；
mx-smi snapshot / dmon；
mxvs 轻量验证；
profiling 模板和 mcTracer 示例；
mx-exporter readiness；
vLLM-metax dry-run；
报告、回归、JUnit 输出。

普通运行：

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

包含 mx-exporter smoke：

./run_acceptance.sh --exporter-smoke

推荐参数：

./run_acceptance.sh --exporter-smoke \
  --exporter-port 18004 \
  --exporter-ready-timeout-sec 55 \
  --exporter-interval-ms 1000

主要输出：

文件	作用
`artifacts/raw/current_run.json`	最新验收 run 状态。
`artifacts/manifest.json`	机器可读 manifest。
`reports/c500_acceptance_report.md`	验收报告。
`reports/junit.xml`	CI/JUnit 输出。
`artifacts/logs/*.log`	各阶段日志。

结果解释：

PASS：硬门验收通过；
WARN：存在非阻断风险；
MISSING：工具或依赖缺失；
SKIPPED：按安全策略跳过；
FAIL：硬门失败，需要排查。

3. 设备与 MXMACA 基础检查工具

3.1 `scripts/env_check.sh`

作用：检查系统基础环境。

包括：

OS / kernel；
CPU / 内存 / 磁盘；
Python / pip / gcc / cmake / git；
Docker / 容器信息；
关键环境变量。

用法：

cd /data/c500-mxmaca-benchmark
./scripts/env_check.sh

输出：

artifacts/logs/env_check.log
artifacts/raw/env_check.json
artifacts/raw/env_check_status.json

3.2 `scripts/device_check.sh`

作用：检查 GPU 设备、C500 识别、驱动和硬件状态。

包括：

mx-smi 是否可用；
GPU model 是否为 MetaX C500；
HBM 是否约 64G；
driver / VBIOS / firmware；
PCIe；
RAS / event；
sGPU / VF 线索。

用法：

./scripts/device_check.sh

输出：

artifacts/logs/device_check.log
artifacts/raw/device_check.json
artifacts/raw/device_check_status.json

3.3 `scripts/mxmaca_check.sh`

作用：检查 MXMACA SDK、编译器、运行时和 Python 框架可见性。

会检查：

/opt/maca；
MACA_PATH；
LD_LIBRARY_PATH；
macainfo；
mxcc；
cucc；
/opt/maca/samples；
Python 中的 torch、vllm、jax 等线索。

用法：

source ./setup_env.sh
./scripts/mxmaca_check.sh

输出：

artifacts/logs/mxmaca_check.log
artifacts/raw/mxmaca_check.json
artifacts/raw/mxmaca_check_status.json

4. MXMACA 编译与样例工具

4.1 `mxcc`

作用：MXMACA 编译器，用来编译 .cpp / .cu 风格的 MXMACA 程序。

检查版本：

mxcc --version

典型用途：编译官方 vectorAdd sample 或自定义 MXMACA 程序。

4.2 `cucc`

作用：MXMACA CUDA bridge 编译工具。用于兼容/桥接 CUDA 风格代码的编译链路。

检查版本：

cucc --version

4.3 `scripts/sample_vectoradd.sh`

作用：复制、编译并运行官方 vectorAdd 样例，用作最小编译运行验收。

用法：

source ./setup_env.sh
./scripts/sample_vectoradd.sh

成功标志：日志包含：

Test PASSED

输出：

artifacts/raw/vectorAdd_src/
artifacts/logs/vectoradd_build.log
artifacts/logs/vectoradd_run.log
artifacts/raw/vectoradd_status.json

5. `mx-smi`：单卡设备监控工具

5.1 `mx-smi` 是干什么的

mx-smi 类似 NVIDIA 的 nvidia-smi，用于查看 C500 GPU 的状态。

可看：

GPU 型号；
显存；
温度；
功耗；
GPU usage；
进程；
PCIe；
HBM 带宽；
RAS / event。

5.2 常用命令

mx-smi
mx-smi -L
mx-smi --show-memory
mx-smi --show-temperature
mx-smi --show-board-power
mx-smi --show-usage
mx-smi --show-process
mx-smi --show-pcie
mx-smi --show-hbm-bandwidth
mx-smi --show-event all
mx-smi ras --show-count -i 0
mx-smi ras --show-status -i 0

5.3 dmon 持续采样

每秒采样一次，采 120 次：

mx-smi dmon \
  --show-temperature \
  --show-board-power \
  --show-usage \
  --show-memory \
  -i 0 \
  -l 1000 \
  -c 120

保存日志：

mx-smi dmon \
  --show-temperature \
  --show-board-power \
  --show-usage \
  --show-memory \
  -i 0 \
  -l 1000 \
  -c 120 \
  > artifacts/metrics/my_mxsmi_dmon.log 2>&1

5.4 项目封装脚本

./scripts/monitor_mxsmi.sh --mode snapshot --gpu-id 0
./scripts/monitor_mxsmi.sh --mode dmon --gpu-id 0 --duration-sec 10 --interval-ms 1000

输出：

artifacts/metrics/mxsmi_snapshot_*.log
artifacts/metrics/mxsmi_dmon_*.log
artifacts/metrics/mxsmi_dmon_*.csv
artifacts/raw/mxsmi_snapshot_status.json
artifacts/raw/mxsmi_dmon_status.json

5.5 禁止默认执行的命令

不要默认执行任何会改变硬件状态的命令，例如：

reset；
warm reset；
刷 VBIOS / Firmware；
set power mode；
set dpm max；
改频率/功耗/DPM。

6. `mxvs`：设备验证与轻量 benchmark

6.1 `mxvs` 是干什么的

mxvs 是沐曦设备验证/诊断工具，可用于：

设备列表；
dashboard；
PCIe bandwidth；
HBM / memory bandwidth；
memory benchmark；
stress（默认不跑）。

6.2 项目推荐用法

./scripts/mxvs_light.sh

它会运行轻量、短时、安全命令，并跳过 stress。

当前容器里如果 mxvs 需要 FUSE，但环境缺少 libfuse.so.2，脚本会尝试：

APPIMAGE_EXTRACT_AND_RUN=1 mxvs ...

6.3 输出

artifacts/logs/mxvs_light.log
artifacts/raw/mxvs_light_status.json
artifacts/raw/mxvs_memory_benchmark.json

6.4 结果解释

PASS：轻量诊断通过；
SKIPPED：stress 默认跳过，不算失败；
WARN：dashboard timeout 等非交互限制；
FAIL：轻量命令失败。

7. `gpuBenchmark`：可选 microbenchmark

7.1 是干什么的

gpuBenchmark 是上游/第三方 microbenchmark，用于更细的性能测试。

7.2 当前状态

默认：SKIPPED。

原因：项目默认不联网 clone、不运行未知 benchmark、不做长时间压测。

7.3 只读/安全入口

./scripts/gpubenchmark_light.sh

如果用户明确确认要 clone/read upstream README：

./scripts/gpubenchmark_light.sh --clone

8. `mx-exporter`：Prometheus 系统监控

8.1 是干什么的

mx-exporter 会把 C500 指标暴露成 Prometheus /metrics，供 Prometheus/Grafana 采集展示。

典型链路：

mx-exporter -> Prometheus scrape -> Grafana dashboard

本工程默认只验证 exporter，不部署 Prometheus/Grafana。

8.2 当前环境状态

当前 PATH 中可能没有全局 mx-exporter，但存在 wheel：

/opt/maca/wheel/mx_exporter-*.whl

所以项目使用 isolated venv，不用 sudo，不污染 user site-packages。

8.3 smoke test

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

输出：

artifacts/raw/mx_exporter_status.json
artifacts/logs/mx_exporter_check.log
artifacts/metrics/mx_exporter_metrics.prom

8.4 前台手动启动

./monitoring/start_mx_exporter.sh --isolated-venv --minimal-config \
  --port 8000 \
  --interval-ms 5000

然后另一个终端 curl：

curl http://127.0.0.1:8000/metrics

或使用项目脚本：

./monitoring/check_mx_exporter_metrics.sh \
  --endpoint http://127.0.0.1:8000/metrics \
  --output artifacts/metrics/mx_exporter_metrics_manual.prom

8.5 关键指标

常见指标包括：

mx_gpu_usage
mx_board_power
mx_memory_usage
mx_memory_total
mx_memory_used
温度相关指标
HBM bandwidth 指标
PCIe bandwidth 指标

9. `mcTracer`：timeline / trace 工具

9.1 是干什么的

mcTracer 是 Linux 端 trace 采集工具，用于分析：

Runtime API；
kernel launch；
kernel 执行时间；
memcpy；
MCTX 标注；
host/device 阶段排布。

输出是：

tracer_out-<pid>.json

该 JSON 可以用 Windows mcTracer-Viewer 打开。

9.2 关键注意事项

当前容器里必须显式加：

--ip 127.0.0.1

否则可能出现：

Rpc connect timeout!

并且没有 tracer_out-*.json。

9.3 采集 vectorAdd

推荐用项目脚本：

./profiling/run_mctracer_vectoradd.sh

成功后会生成：

artifacts/profiles/mctracer/<timestamp>/tracer_out-<pid>.json

9.3.1 采集 MoE 算子

现在可以直接用 MoE 专用脚本。该脚本会自动启动 /data/tilelang-metax/race_tests/moe/run.sh，并用 mcTracer 包裹采集：

./profiling/run_mctracer_moe.sh

等价于：

./profiling/run_mctracer_vectoradd.sh --moe

成功后会生成：

artifacts/profiles/moe/mctracer_<timestamp>/tracer_out-<pid>.json

9.4 手动采集任意程序

mkdir -p artifacts/profiles/mctracer/my_run

mcTracer \
  --ip 127.0.0.1 \
  --mctx \
  --odname artifacts/profiles/mctracer/my_run \
  ./my_program arg1 arg2

9.5 采集 MoE 算子

推荐脚本版：

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

或：

./profiling/run_mctracer_vectoradd.sh --moe

手动命令版：

mkdir -p artifacts/profiles/moe/manual_mctracer
mcTracer \
  --ip 127.0.0.1 \
  --mctx \
  --odname artifacts/profiles/moe/manual_mctracer \
  bash -lc "cd /data/tilelang-metax/race_tests/moe && bash run.sh"

查找 JSON：

find artifacts/profiles/moe -name 'tracer_out-*.json' -ls | tail

9.6 Windows Viewer 导入

把 tracer_out-*.json 拷贝到 Windows，用 mcTracer-Viewer 打开。

不要打开：

stdout.log
stderr.log
TRACE_JSON.txt
torch.profiler 的 trace.json

9.7 attach 模式

如果程序已运行：

mcTracer --ip 127.0.0.1 --mctx --odname artifacts/profiles/mctracer/attach_test --attach <pid>

结束 attach：在 mcTracer 窗口按：

Ctrl + t

10. `mcTracer-Viewer`：Windows trace 可视化

10.1 是干什么的

mcTracer-Viewer 是 Windows 端 UI 工具，用于打开 Linux mcTracer 生成的 JSON。

10.2 使用步骤

Linux 上生成 tracer_out-*.json；
把 JSON 拷贝到 Windows；
打开 mcTracer-Viewer；
选择该 JSON 文件；
查看 API/kernel/memcpy/MCTX timeline。

10.3 当前已验证 MoE JSON

最近一次 MoE 完整运行生成了：

/data/c500-mxmaca-benchmark/artifacts/profiles/moe/mctracer_20260607T091038Z/tracer_out-39991.json

11. `mcProfiler` / `win-perf-kit`：kernel counter / RoofLine 工具链

11.1 是干什么的

mcProfiler 用于比 timeline 更深入的 kernel 指标分析，例如：

kernel metrics；
SOL；
RoofLine；
memory；
compute；
scheduling。

11.2 当前状态

当前 Linux 环境未发现：

mcProfiler
mcprofiler

官方资料和当前复查结果指向 Windows 端：

win-perf-kit / gui-profiler.exe

也就是说，当前不是在 Linux 上直接找一个 CLI 来跑，而是需要 Windows GUI 通过 SSH/RPC 连接 Linux 目标机。

11.3 现有脚本

./profiling/run_mcprofiler_vectoradd.sh

当前作用：记录 MISSING，并提示下一步，不臆造未知 CLI 参数。

11.4 Runtime API smoke

./profiling/run_mcprofiler_api_smoke.sh

作用：编译运行官方 profilerScope sample，验证：

mcProfilerStart()
mcProfilerStop()

当前结果一般是 WARN：样例能编译运行，但没有产出 counter/profile dump。这不等于 mcProfiler 正式工具链可用。

12. `torch.profiler`：补充 timeline

12.1 是干什么的

torch.profiler 可用于 PyTorch 层面的 CPU/CUDA/MACA timeline 辅助观察。

12.2 适用场景

快速查看 PyTorch op 和部分 kernel 排布；
辅助分析 MoE / TileLang 流程；
在 mcProfiler 不可用时作为补充证据。

12.3 限制

它不能替代官方 mcProfiler 的 SOL/RoofLine/kernel counter 指标。

13. MoE 算子运行工具

13.1 算子目录

/data/tilelang-metax/race_tests/moe

13.2 文件说明

文件	作用
`run.sh`	运行入口。
`fusedmoe_benchmark.py`	功能和性能测试主脚本。
`custom_fusedmoe.py`	当前自定义 fused MoE kernel。
`ref_fusedmoe.py`	参考实现。
`moe_test_configs.json`	functional/performance 配置。

13.3 运行

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
cd /data/tilelang-metax/race_tests/moe
bash run.sh

成功输出：

✅ Functional test passed for config: ...
⏱ Performance test: ...ms for config: ...

13.4 上次完整运行结果

最近一次完整 MoE + mcTracer 运行：

Functional：PASS 2 / FAIL 0；
Performance case 1：约 380.65 ms；
Performance case 2：约 51.98 ms；
mcTracer JSON：artifacts/profiles/moe/mctracer_20260607T091038Z/tracer_out-39991.json。

报告：

reports/moe_full_run_20260607T091038Z.md

14. LLM / vLLM-metax 工具

14.1 `benchmarks/llm/vllm_metax_check.sh`

作用：dry-run 检查 vLLM-metax readiness。

检查：

Python；
Torch import；
vLLM import；
C500 GPU 可见性。

不会：

下载模型；
加载大模型；
占满显存。

用法：

./benchmarks/llm/vllm_metax_check.sh

输出：

artifacts/raw/vllm_metax_check.json
artifacts/logs/vllm_metax_check.log

14.2 LLM benchmark 模板

当前模板：

benchmarks/llm/start_server.sh
benchmarks/llm/run_benchmark.sh
benchmarks/llm/collect_mxsmi_dmon.sh
benchmarks/llm/stop_server.sh
benchmarks/llm/parse_results.py

默认都是 dry-run。正式跑 LLM benchmark 前必须明确：

模型；
dtype；
prompt length；
output length；
batch / concurrency；
tensor parallel；
框架和镜像版本；
是否允许下载模型和占用显存。

15. 报告、回归和 CI 工具

15.1 `scripts/generate_report.py`

作用：生成验收报告和 manifest。

python3 scripts/generate_report.py

输出：

artifacts/manifest.json
reports/c500_acceptance_report.md

15.2 `scripts/compare_baseline.py`

作用：和 baseline / 阈值比较，判断是否回归。

无 baseline 时：只做 acceptance gate 检查。

python3 scripts/compare_baseline.py \
  --manifest artifacts/manifest.json \
  --thresholds configs/regression_thresholds.yml

输出：

artifacts/raw/regression_status.json
reports/regression_report.md

15.3 `scripts/export_junit.py`

作用：导出 JUnit XML，用于 CI 展示。

python3 scripts/export_junit.py \
  --manifest artifacts/manifest.json \
  --regression-status artifacts/raw/regression_status.json \
  --output reports/junit.xml

输出：

reports/junit.xml
artifacts/raw/junit_status.json

16. 性能工具部署检查

16.1 `scripts/perf_tools_deploy_check.sh`

作用：检查性能工具 readiness。

会检查：

mx-smi
mxvs
mx-exporter CLI / wheel
mcTracer
mcTracer-Viewer
mcProfiler CLI
win-perf-kit
libmcToolsExt.so
profilerScope sample
SSH / RPC port 线索

用法：

./scripts/perf_tools_deploy_check.sh

输出：

artifacts/raw/perf_tools_deploy_check.json
artifacts/logs/perf_tools_deploy_check.log
reports/performance_tools_deployment_report.md

17. 推荐工作流

17.0 先说明：不是所有工具都要同时开启

“推荐使用顺序”不是指先把所有工具都开起来，再运行算子。更准确的理解是：

一次性健康确认：先用 run_acceptance.sh、mx-smi、mxvs 确认机器、驱动、MXMACA、显存和基础 benchmark 没问题。这类工具通常不需要和算子同时运行。
运行时监控：如果要看算子运行期间的温度、功耗、显存、GPU usage，就在算子运行前启动 mx-smi dmon 或 mx-exporter，然后再运行算子。
Timeline profiling：如果要看 API/kernel/memcpy 时间线，用 mcTracer 包裹算子运行；它不是后台常驻工具，而是作为启动器运行目标命令。
深度 kernel 指标：如果要看 SOL/RoofLine/counter，需要 mcProfiler/win-perf-kit，当前本机 Linux CLI 不可用，需要 Windows GUI 工具链补齐。

不同工具会带来不同开销。正式测性能时，不建议同时开启所有 profiling 工具；应按问题选择最少工具。

目标	应该怎么做
确认环境是否正常	跑一次 `run_acceptance.sh --exporter-smoke`。
看运行时温度/功耗/GPU 使用率	先开 `mx-smi dmon` 或 `mx-exporter`，再跑算子。
生成 Windows Viewer 可看的 timeline	用 `mcTracer --ip 127.0.0.1 ... <算子命令>` 包裹运行。
做轻量硬件/带宽健康检查	单独跑 `mxvs_light.sh`，不需要和算子一起跑。
做最干净的性能数字	只跑算子，最多配一个低开销 `mx-smi dmon`；避免同时开启重 profiling。

17.1 只想确认机器是否可用

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
./run_acceptance.sh --exporter-smoke

17.2 只想运行 MoE 算子

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
cd /data/tilelang-metax/race_tests/moe
bash run.sh

17.3 运行 MoE 同时采集 `mx-smi`

终端 1：

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
mx-smi dmon --show-temperature --show-board-power --show-usage --show-memory \
  -i 0 -l 1000 -c 120 \
  > artifacts/metrics/moe_mxsmi_dmon_manual.log 2>&1

终端 2：

cd /data/c500-mxmaca-benchmark
source ./setup_env.sh
cd /data/tilelang-metax/race_tests/moe
bash run.sh

17.4 运行 MoE 同时采集 mcTracer