上下文基准测试
项目介绍
Context Bench
基准测试测量MCP服务器如何准确地为编码代理提供上下文
Context Bench 测量不同的 MCP 服务器如何有效地帮助 AI 代理理解和实现复杂的 AI 框架工作流程。它专注于一次性场景，即单个 MCP 工具调用为编码代理提供了文档上下文。
这个基准测试了什么
问题：哪个MCP服务器在实现现代AI框架时提供最有效的上下文？
- 任务：AI框架集成（Autogen、LangGraph、OpenAI Agents、Agno、OpenRouter）
- 测试的MCP服务器：
- NIA：混合包搜索，带有文档回退
- Context7：库特定的文档检索
- Deepcon：跨代码库的深度上下文理解
- Exa：语义网络搜索和代码发现
基准测试是如何工作的
概述
Context Bench 评估 MCP 服务器是否为实现复杂 AI 框架工作流程提供了足够的上下文。与传统的测试代码执行的基准不同，这个基准测试的是文档完整性——MCP 服务器提供的上下文的质量和充分性。
场景设计
每个场景都经过精心设计，以确保真实且具有挑战性
-
复杂查询：场景需要从多个文档页面中获取信息，模拟现实世界中的开发任务，开发者需要从各种来源综合知识（例如，在单一实现中结合流式传输、工具调用和错误处理）。
-
Oracle代码创建：对于每个场景查询，我们基于场景“sources”字段引用的官方文档创建 Oracle 实现代码。此 Oracle 代码代表了一个典型的、可工作的示例，说明如何使用框架推荐的模式和最佳实践来实现所需功能。
-
实际需求：查询指定了具体的任务（例如，“构建具有团队终止条件的多代理系统”），而不是简单的API查找，测试MCP服务器能否为多方面的实现提供全面的上下文。
目标是测试MCP服务器是否能够检索并呈现使开发人员能够实现复杂、多组件特性的文档——而不仅仅是查找单独的API签名。
基准测试过程
┌─────────────────────────────────────────────────────────────────┐
│ 第一步：查询MCP服务器（一次性模式） │
│ • 向MCP服务器发送场景查询 │
│ • MCP服务器返回文档/代码示例 │
│ • 每个场景单次工具调用 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 第二步：多模型评估 │
│ • 并行评估3个LLM： │
│ - GPT-5（OpenAI） │
│ - Grok-4（xAI） │
│ - Deepseek-v3.2（Deepseek） │
│ • 每个模型将MCP上下文与Oracle代码进行比较 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 第三步：评分标准 │
│ • 完整性（布尔值）：所有要求都能推断出来吗？ │
│ - API名称、参数类型、返回值 │
│ - 使用模式、错误处理 │
│ • 相关性（布尔值）：上下文是否解决了任务？ │
│ • 总评分（1-5）：质量评估 │
│ • 置信度（高/中/低）：评估者的确定性 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 第四步：多数投票决策 │
│ • 完整性：2/3模型必须同意 = 通过 │
│ • 相关性：2/3模型必须同意 = 通过 │
│ • 最终裁决：两个都通过，场景才能通过 │
└─────────────────────────────────────────────────────────────────┘
评估理念
我们评估的内容：
- ✅ MCP上下文是否包含足够的信息来实现Oracle代码？
- ✅ 是否可以从示例中推断出API签名、参数和返回类型？
- ✅ 使用模式是否展示得足够清晰？
- ✅ 文档是否涵盖了所有用户需求？
我们不评估的内容：
- ❌ 实现是否完全匹配Oracle（功能等价即可）
- ❌ 代码质量和风格
- ❌ 性能或效率
基准测试结果
根据MCP服务器的准确性
多模型评估（GPT-5、Grok-4、Deepseek-v3.2）跨越20个AI框架集成场景
| MCP服务器 | 通过的场景数 |
|---|---|
| Deepcon | 18 |
| Context7 | 13 |
| NIA | 11 |
| Exa | 5 |
| 基线（Claude Sonnet 4.5） | 0 |
关键发现：Deepcon为AI框架集成任务提供了最有效的文档上下文，成功率为90%。
注意：基线测试使用的是没有工具的Claude Sonnet 4.5。没有外部工具，该模型无法成功实施20个AI框架集成场景中的任何一个（因为知识截止）。
根据MCP服务器的令牌使用情况
基于最近跨越20个场景的基准测试运行：
| MCP服务器 | 每场景平均令牌数 | 总令牌数 |
|---|---|---|
| Context7 | 5,626 | 112,515 |
| Exa | 4,753 | 95,065 |
| Deepcon | 2,365 | 47,290 |
| NIA | 1,873 | 37,457 |
关键发现：更多的令牌并不保证更高的准确性。Deepcon以每场景平均2,365个令牌实现了90%的成功率，而Context7提供了5,626个令牌但仅实现了65%的成功率。
效率分析
上图显示了准确性和令牌使用之间的关系。Deepcon在理想象限（高准确性，低令牌）中脱颖而出，展示了优越的上下文质量和效率。
查看完整结果
完整的基准测试结果包括详细的评估、MCP响应以及每个场景的分解，可以在sample_workspace/中找到。每个运行目录包含：
- 包含完整MCP上下文的个别场景结果
- 多模型评估分数和推理
- 每个场景的令牌使用统计
- 按MCP服务器聚合的报告
示例：浏览sample_workspace/run-2025-11-06-1653/以查看包含所有20个场景的完整基准测试运行，涉及4个MCP服务器。
快速开始
先决条件
安装
git clone https://github.com/your-org/context-bench.git
cd context-bench
npm install
设置
# 创建环境文件
cp .env.example .env
# 添加您的API密钥
nano .env
所需的环境变量：
# MCP服务器凭证
NIA_API_KEY=your_nia_api_key
CONTEXT7_API_KEY=your_context7_api_key
DEEPCON_API_KEY=your_deepcon_api_key
# 评估
OPENROUTER_API_KEY=your_openrouter_api_key # 用于多模型评估
运行您的第一个基准测试
单个场景
# 使用NIA服务器测试
npx tsx harness/cli.ts \
--scenario autogen:streaming-tools \
--mode oneshot \
--config nia
# 使用Context7服务器测试
npx tsx harness/cli.ts \
--scenario autogen:streaming-tools \
--mode oneshot \
--config context7
# 使用Deepcon服务器测试
npx tsx harness/cli.ts \
--scenario autogen:streaming-tools \
--mode oneshot \
--config deepcon
多个场景
# 使用NIA运行所有autogen场景
npx tsx harness/cli.ts \
--package autogen \
--mode oneshot \
--config nia
# 运行特定场景
npx tsx harness/cli.ts \
--scenarios autogen:streaming-tools,langgraph:parallel-brief \
--mode oneshot \
--config context7
比较所有MCP服务器
# 在所有MCP配置下运行单个场景
npx tsx harness/cli.ts \
--scenario autogen:streaming-tools \
--mode oneshot \
--all-configs
# 使用所有配置运行所有场景（并行执行）
npx tsx harness/cli.ts \
--all-packages \
--mode oneshot \
--all-configs \
--max-workers 4
预期输出：
Context Bench v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
运行ID：run-2025-11-07-0900
模式：一次性
场景：autogen:streaming-tools
配置：nia
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ 正在运行配置：nia
▶ 场景：autogen:streaming-tools
[1/8] 加载场景规范... ✓
[2/8] 验证环境变量... ✓
[3/8] 初始化工作区... ✓
[4/8] 应用MCP配置... ✓
[5/8] 运行一次性模式（单个MCP工具调用）... ✓
[7.6/8] 对比结果与Oracle... ✓
[8/8] 生成报告... ✓
✓ 通过：1/1通过
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
结果：1/1场景通过（100%）
耗时：45.2秒
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
基准结构
包和场景
基准包括5个AI框架包和20个场景：
scenarios/
├── autogen.yaml # 包定义
├── autogen/ # Oracle实现
│ ├── streaming_tools.py
│ ├── selector_groupchat.py
│ ├── team_termination.py
│ └── hitl_persist.py
├── langgraph.yaml
├── langgraph/
│ ├── parallel_brief.py
│ ├── hil_writer.py
│ ├── functional_review.py
│ └── two_agent_subgraphs.py
├── openai-agents.yaml
├── openai-agents/
│ ├── streaming_tools.py
│ ├── handoffs_guardrails.py
│ ├── sessions_context.py
│ └── realtime_agent.py
├── agno.yaml
├── agno/
│ ├── trend_scout.py
│ ├── content_team.py
│ ├── visual_explainer.py
│ └── copy_workflow.py
├── openrouter-sdk.yaml
└── openrouter-sdk/ # TypeScript实现
├── usage_and_keys.ts
├── models_and_providers.ts
├── structured_tools.ts
└── auto_router_stream.ts
包定义格式
每个包在scenarios/根目录下的<package-name>.yaml中定义：
package-id: autogen
language: python # 运行语言
registry: py_pi # 包注册表（py_pi、npm，用于Nia）
context7-id: /microsoft/autogen # Context7库标识符
deepcon-id: autogen # Deepcon包名（可选）
scenarios:
- id: streaming-tools
query: "使用Autogen Python库，构建一个具有工具调用和流式传输能力的代理。计划一个30秒的‘市场简介’，针对EUR→KRW旅行者..."
oracle: scenarios/autogen/streaming_tools.py
sources:
- https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/quickstart.html
- https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/tutorial/agents.html
- id: selector-groupchat
query: "使用基于选择器的群聊的Autogen Python库，创建一个小的研究‘团队’：（1）规划子任务；（2）运行模拟网络搜索；（3）计算百分比变化..."
oracle: scenarios/autogen/selector_groupchat.py
sources:
- https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/tutorial/selector-group-chat.html
runtime:
version: "python3.11"
env_vars:
OPENAI_API_KEY: "${OPENAI_API_KEY}"
Oracle文件
每个场景都有一个Oracle实现文件（Python .py 或 TypeScript .ts），其中包含参考实现代码。这些Oracle实现被多模型评估系统用来评估MCP提供的文档是否包含了实现所需功能的足够信息。
注意：大多数包使用Python，但openrouter-sdk使用TypeScript，因为它是一个npm包。
理解结果
目录结构
workspace/
└── run-2025-11-07-0900/
├── oneshot/ # 一次性执行结果
│ ├── nia/ # NIA MCP服务器结果
│ │ ├── autogen:streaming-tools/
│ │ │ ├── oneshot_result.md # 原始MCP响应
│ │ │ ├── final_result.md # 包含评估的完整报告
│ │ │ └── evaluation_oneshot.json
│ │ └── autogen:selector-groupchat/
│ ├── context7/ # Context7结果
│ └── deepcon/ # Deepcon结果
├── nia/
│ └── nia_result.md # 配置摘要 + 令牌统计
├── context7/
│ └── context7_result.md
└── deepcon/
└── deepcon_result.md
CLI参考
主CLI选项
npx tsx harness/cli.ts [选项]
选项：
--package <名称> 运行包中的所有场景
--scenario <包:ID> 运行特定场景（格式：包:场景）
--scenarios <ID> 逗号分隔的场景ID
--mode <类型> 执行模式：一次性或代理（默认：代理）
--config <名称> MCP配置（nia、context7、deepcon）
--all-configs 使用所有MCP配置运行
--all-packages 运行所有包
--max-workers <n> 并行执行限制（默认：1）
--timeout <秒数> 每个场景的超时时间（默认：120）
--verbose 详细日志输出到stdout
--list-packages 列出所有可用包
--list-scenarios 列出所有可用场景
--list-configs 列出所有可用的MCP配置
--show-package <名称> 显示包详情
--show-scenario <ID> 显示场景详情
列表命令
# 列出所有包
npx tsx harness/cli.ts --list-packages
# 列出所有场景
npx tsx harness/cli.ts --list-scenarios
# 列出所有MCP配置
npx tsx harness/cli.ts --list-configs
# 显示包详情
npx tsx harness/cli.ts --show-package autogen
# 显示场景详情
npx tsx harness/cli.ts --show-scenario autogen:streaming-tools
令牌计数
计算一次性结果中的令牌数量：
# 计算特定配置和运行的令牌
npx tsx scripts/count-tokens.ts workspace/run-2025-11-07-0900 nia
# 计算运行