metax-bench

面向沐曦（MetaX）GPU 的大模型推理可复现基准 + 可验证调用证据链工具，并以 Claude Code Skill / MCP / 智能体三形态同源接入开发工作流。

30 秒看懂价值：

真实沐曦调用证据链 —— 每次调用都落一行 JSONL（时延 / TTFT / Token / HTTP 状态）；通过「绑定沐曦资源包的令牌 + 端点白名单 + 显式关闭跨厂商故障转移」三重约束算力归属，整份日志即「推理确实跑在沐曦 GPU 上」的可验证凭证。
Skill / MCP / Agent 三形态同源 —— 同一套 mx_client 底座，分别以 Claude Code Skill、MCP Server、对话式智能体三种形态接入开发工作流。
可复现基准 —— --runs N 串行实测，自动汇总 P50/P95 时延、TTFT、吞吐（tokens/s），一键复现、横向对比。

🔥 最硬证据：4 模型真实横向基准 + 60+ 条可核验调用日志（全 HTTP 200，仅 1 条如实保留的网络失败）+ 两段真实运行 GIF + 智能体 3 轮真实对话。评委直达 → docs/REVIEW_GUIDE.md。

metax-bench 通过 Gitee.AI（模力方舟）的 OpenAI 兼容端点调用部署在沐曦 GPU 上的国产大模型，对每一次调用都记录结构化日志（时延、Token 用量、HTTP 状态），并据此产出可复现的性能基准。这份调用日志本身就是「推理确实跑在沐曦算力上」的可验证参赛证据。

觉得有用？欢迎点 ⭐ Star / Fork 支持，帮更多人发现沐曦 GPU 生态工具链。

评委导览：docs/REVIEW_GUIDE.md（按评分点逐条索引） · 架构总览：docs/architecture.md · 任务三设计：docs/task3-design.md

1. 项目简介

metax-bench 是一个轻量、可复现的大模型推理基准工具：它把请求统一打到 Gitee.AI 上承载于沐曦（MetaX）GPU 的模型端点，逐次记录端到端时延、首 Token 时延（TTFT）与 Token 用量，并将结果沉淀为一行行 JSONL 日志——既是性能数据，也是算力调用证据链。同时，它以 Claude Code Skill、MCP Server 与对话式智能体 MetaX Copilot 三种同源形态暴露能力，让 AI 编程助手可以直接调用沐曦算力并自动留痕。

2. 核心特性

真实沐曦算力调用证据链：每一次 chat 调用都落一行 JSONL（含 id / timestamp / model / endpoint / Token 用量 / ttft_ms / total_ms / http_status / ok），成功失败都记录——失败也是证据。整份日志可作为「推理跑在沐曦 GPU」的可复现凭证。
关闭跨厂商故障转移：客户端默认下发 X-Failover-Enabled: false，显式要求平台不要把绑定沐曦资源包的请求静默转移到其它算力（是否回退最终由平台语义决定）；它与「资源包绑定 + 端点白名单」共同构成算力归属的多重保险。
可复现基准：metax-bench --runs N 串行打多次同一请求，输出 TTFT、端到端时延、吞吐（tokens/s）等聚合指标，方便横向对比模型与复现实验。
Skill / MCP / 智能体三形态：既可作为 Claude Code Skill 在对话中触发，也可作为 MCP Server 被 Claude Code / Cursor 等客户端挂载，还可作为自研 ReAct 智能体 MetaX Copilot 独立运行；三者共用同一 mx_client 底座，调用与留痕全自动。
一套底座覆盖两个独立奖池：Skill/MCP（任务二）与对话式智能体 MetaX Copilot（任务三）共用同一份 mx_client 客户端、证据日志与基准引擎——同一份核心代码、同一条调用证据链，同时参评赛事任务二与任务三两个独立奖池，复用充分、维护单点。
OpenAI 兼容、零侵入：底层基于 openai SDK，仅锁定 base_url 到 ai.gitee.com，已有代码迁移成本极低。
密钥零明文：访问令牌只从环境变量 GITEE_AI_TOKEN 读取，绝不进入代码或文档。
**兼容 Python 3.9+**：纯标准库 + openai，无重型依赖。

与「随手写的调用脚本 / 通用基准工具」相比

能力维度	直接 curl / openai 脚本	通用 LLM 基准工具	metax-bench
算力归属强约束（端点白名单 + 关故障转移）	✗	✗	✓
每次调用落可核验 JSONL 证据（失败也留）	✗	部分	✓
Skill + MCP + 智能体三形态同源接入	✗	✗	✓
流式真实 TTFT + usage（非估算）	部分	部分	✓
测量完整性（关静默重试、超时上限）	✗	部分	✓
沐曦合规可辩护（资源包绑定 + 证据链原生）	✗	✗	✓

一句话护城河：别的方案能「跑通一次调用」，metax-bench 把「这次调用确实跑在沐曦 GPU 上」做成了绕不开的结构性保证，且同一套底座覆盖任务二与任务三两个奖池。

3. 演示

架构总览见 docs/architecture.md：一图看清 mx_client 底座如何同时支撑 Skill / MCP / Agent 三形态与证据日志。

真实调用已验证：已用沐曦算力券购买「沐曦-模型资源包」并在沐曦 GPU 上实跑。4 个国产模型横向基准（2026-06-12）见下文 §8.3 性能基准与 docs/benchmark.md，逐次调用证据见 docs/real-call-log-20260612.jsonl（49 次，含如实保留的 1 次网络失败记录）与 docs/real-call-log-20260604.jsonl，智能体真实对话演示见 docs/agent-demo-20260604.md。

CLI 基准实录（真实调用沐曦 GPU：跑基准 → 输出性能表 → 查看 JSONL 证据）：

metax-bench 真实运行演示

MetaX Copilot 智能体实录（ReAct：自主调用 list_models 工具后作答，全程留痕）：

metax-copilot 真实运行演示

4. 快速开始

# 1) 在 Gitee.AI 创建访问令牌，并绑定到「沐曦(MetaX)资源包」：
#    https://ai.gitee.com/dashboard/settings/tokens
#    随后以环境变量注入（切勿写入代码或提交到仓库）
export GITEE_AI_TOKEN="你的_gitee_ai_令牌"

# 2) 安装（源码可编辑安装）
pip install -e .

# 3) 跑一次 5 连发基准，验证端到端调用与日志
metax-bench --runs 5

运行后：

控制台打印每次调用的时延与 Token 用量，以及聚合的基准结果；
logs/metax-YYYYMMDD.jsonl 中追加 5 行调用记录，作为沐曦算力调用证据。

提示：可复制 .env.example 为 .env 填入令牌；本仓库 .gitignore 已忽略 .env，不会泄露密钥。

5. 安装

Python 版本要求：核心库与 CLI 兼容 Python ≥ 3.9；MCP 形态需 Python ≥ 3.10（mcp 依赖要求）。在 3.9 环境下安装 [mcp] extra 会失败，请用 3.10+ 环境。

从源码（开发 / 参赛复现推荐）

git clone https://www.gitlink.org.cn/recorder/metax-bench.git
cd metax-bench
pip install -e .                 # 仅核心：CLI + 客户端 + 基准（Python ≥ 3.9）
pip install -e ".[mcp]"          # 额外启用 MCP Server 形态（需 Python ≥ 3.10）
pip install -e ".[mcp,dev]"      # 再加测试 / lint 工具链（需 Python ≥ 3.10）

从 PyPI（发布后）

pip install metax-bench          # 核心（Python ≥ 3.9）
pip install "metax-bench[mcp]"   # 含 MCP Server（需 Python ≥ 3.10）

环境要求：核心库 / CLI 需 Python ≥ 3.9，依赖 openai>=1.40.0；MCP 形态需 Python ≥ 3.10，额外依赖 mcp>=1.2.0。

6. 配置（Claude Code / Cursor）

在 Python ≥ 3.10 环境下安装 [mcp] extra 后，metax-bench 可作为 MCP Server 挂载到支持 MCP 的客户端。令牌统一用 ${GITEE_AI_TOKEN} 占位，由客户端从你的 shell 环境注入，不要在配置文件里写明文密钥。

启动命令为 metax-bench-mcp（安装后即在 PATH 中）；如未挂到 PATH，可改用备选 python -m metax_bench.mcp_server。

Claude Code（~/.claude.json 或项目级 .mcp.json 的 mcpServers 段）：

{
  "mcpServers": {
    "metax-bench": {
      "command": "metax-bench-mcp",
      "args": [],
      "env": {
        "GITEE_AI_TOKEN": "${GITEE_AI_TOKEN}"
      }
    }
  }
}

Cursor（~/.cursor/mcp.json 或项目级 .cursor/mcp.json）：

{
  "mcpServers": {
    "metax-bench": {
      "command": "metax-bench-mcp",
      "args": [],
      "env": {
        "GITEE_AI_TOKEN": "${GITEE_AI_TOKEN}"
      }
    }
  }
}

可选环境变量（均有默认值，按需覆盖）：GITEE_AI_BASE_URL（默认 https://ai.gitee.com/v1）、METAX_DEFAULT_MODEL（默认 DeepSeek-V3.2）、METAX_LOG_DIR（默认 logs）、METAX_TIMEOUT_S（单次调用超时秒数，默认 120）。客户端固定 max_retries=0：失败不静默重试，如实落日志，时延数据不被重试污染。

7. 工具与参数

7.1 CLI 参数

metax-bench 命令用于一次性跑基准并落证据日志。

参数	类型	默认值	说明
`--model`	str（可重复）	`DeepSeek-V3.2`	目标模型；重复指定可横向对比多个模型
`--runs`	int	`10`	每个模型串行重复调用次数
`--prompt`	str	内置中文示例	每次调用发送的用户提示词
`--output`	str	`benchmark.md`	Markdown 基准报告输出路径
`--max-tokens`	int	`256`	单次生成最大 Token 数

证据日志目录由环境变量 METAX_LOG_DIR 控制（默认 logs）。完整参数说明见 metax-bench --help。

7.2 MCP 工具

挂载 MCP Server 后，客户端可调用以下工具：

工具	入参	返回	说明
`metax_chat`	`prompt`、`model?`（默认 `DeepSeek-V3.2`）	模型回复文本 + 一行性能页脚（ttft / total / tokens）	单轮对话补全，自动写入证据日志
`metax_benchmark`	`model?`（默认 `DeepSeek-V3.2`）、`runs?`（默认 5，上限 50）	Markdown 基准表（成功率 / P50·P95 时延 / TTFT / 吞吐）	固定提示词重复 N 次并汇总性能
`metax_list_models`	无	沐曦在线可用模型列表	列出当前可调用的沐曦在线模型，便于选型

8. 示例输入输出与性能表

8.1 作为库直接调用

from metax_bench import MetaXClient

client = MetaXClient()  # 自动读取环境变量 GITEE_AI_TOKEN
result = client.chat([{"role": "user", "content": "用一句话介绍沐曦 GPU。"}])

print(result.content)            # 模型回复文本
print(result.record.ttft_ms)     # 首 Token 时延（ms）
print(result.record.total_tokens)  # 本次总 Token 数
print(result.record.to_json())   # 即落入 logs/*.jsonl 的证据行

8.2 一行 JSONL 证据日志（示意）

{"id": "a1b2c3d4e5f6", "timestamp": "2026-05-30T08:00:00+00:00", "model": "DeepSeek-V3.2", "endpoint": "https://ai.gitee.com/v1/chat/completions", "prompt_tokens": 18, "completion_tokens": 42, "total_tokens": 60, "ttft_ms": 0.0, "total_ms": 0.0, "http_status": 200, "ok": true, "error": null}

8.3 性能基准（✅ 真实实测）

已用沐曦算力券购买「沐曦-模型资源包」并在沐曦 GPU 上实跑 4 个国产大模型横向对比（2026-06-12，国内直连）。 完整报告（含指标解读、代理对时延污染的实测注记）见 docs/benchmark.md，逐次调用证据见 docs/real-call-log-20260612.jsonl：

模型	运行次数	TTFT 中位数 (ms)	端到端时延中位数 (ms)	吞吐 (tokens/s)
DeepSeek-V3.2	5	1898.61	8126.89	23.98
Qwen3-Coder-30B-A3B-Instruct	5	371.53	730.72	27.07
GLM-4.6	5	2783.16	16642.11	47.04
Qwen2.5-72B-Instruct	5	563.68	1487.41	14.44

实测于沐曦-模型资源包（端点 ai.gitee.com、X-Failover-Enabled: false 关故障转移、max_retries=0 不静默重试），20 次基准调用全部成功，每次自动落 JSONL 证据日志，可复现核验。证据日志中另如实保留 1 条网络瞬时失败记录（失败也是证据）。历史单模型基准（2026-06-04）见 docs/real-call-log-20260604.jsonl。

任务三延伸：MetaX Copilot 智能体

本仓库基于同一套 mx_client 底座，额外实现了一个对话式智能体 MetaX Copilot（自研 ReAct 框架，对应赛事任务三）：你用自然语言提问，它在沐曦算力上选型 / 评测 / 推理，多轮对话 + 工具调用 + 任务状态跟踪，每一步调用同样落 JSONL 证据。已在沐曦 GPU 上真实运行验证（见 docs/agent-demo-20260604.md）。

metax-copilot            # 交互式 CLI（或 python -m metax_bench.agent.cli）

工具集：list_models（列沐曦在线模型）、benchmark（实测性能）、chat_once（沐曦推理）。设计方案、架构图与创意 PPT 大纲见 docs/task3-design.md。

沐曦合规说明

端点白名单：base_url 仅允许 ai.gitee.com（默认 https://ai.gitee.com/v1），不调用 OpenAI 等任何外部推理服务，确保推理真实发生在 Gitee.AI 承载的沐曦（MetaX）GPU 上。
关闭跨厂商故障转移：客户端默认下发 X-Failover-Enabled: false，显式要求不要把绑定沐曦资源包的请求静默转移到其它算力。算力归属的主要保证是「令牌绑定沐曦资源包 + 端点白名单仅 ai.gitee.com」，该头为额外保险（是否回退最终由平台语义决定）。
调用日志即证据：每次调用（含失败）都追加一行 JSONL 到 logs/metax-YYYYMMDD.jsonl，记录时延、Token 用量与 HTTP 状态，整份日志可作为「推理跑在沐曦算力」的可复现参赛证据。
密钥安全：访问令牌只经环境变量 GITEE_AI_TOKEN 注入，绝不写入代码、配置或文档明文；.env 已被 .gitignore 忽略。

License

本项目以 Apache-2.0 许可证开源。

致谢

中国计算机学会（CCF） 主办「CCF 开源创新大赛」及沐曦 GPU 生态赛道。
光华设计发展基金会 对赛事的支持。
沐曦（MetaX） 提供国产 GPU 算力，以及 Gitee.AI（模力方舟）提供的部署与推理服务平台。

作者：何开元（GitLink: recorder）