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），一键复现、横向对比。

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 两种形态暴露能力，让 AI 编程助手可以直接调用沐曦算力并自动留痕。

2. 核心特性

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

3. 演示

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

演示动图待录制（算力券到位后补）：将呈现「在 Claude Code 中触发 Skill → 调用沐曦端点 → 自动写入 JSONL 日志 → 跑基准并输出性能表」的完整流程。

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）。

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 性能基准

完整基准报告见 docs/benchmark.md。以下为示例结构，真实数据待算力券到位回填：

模型	运行次数	TTFT 中位数 (ms)	端到端时延中位数 (ms)	吞吐 (tokens/s)
DeepSeek-V3.2	—	待回填	待回填	待回填

以上为示例结构。真实性能数据将在沐曦算力券到位、完成实跑后回填，并附 logs/ 下对应日期的 JSONL 证据日志以供复现核验。

任务三延伸：MetaX Copilot 智能体

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

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，绑定沐曦资源包的 Token 不会静默回落到非沐曦算力，保证证据归属可信。
调用日志即证据：每次调用（含失败）都追加一行 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）