代码智能基准测试工具

抹布长凳

代码智能真的能让你的AI编码代理变得更好吗？测量它。

ragbench回答了每个代理用户都会问的问题： “语义索引值得吗，还是grep就足够了？” --有两个互补的基准：

1. 代理A/B基准 (rag-bench agent)——标题。真正的无头 克劳德代码 会话两次回答105个基本事实代码库问题：一次仅使用内置词汇工具（Grep/Glob/Read），一次添加了代码智能MCP服务器。措施 答案准确性、令牌、代理回合、延迟和成本 根据条件。方法论类与 光标的上下文工作台，发现语义搜索使代理 准确率提高6.5-23.5% 仅限于grep。
2. 检索基准 (rag-bench run)--发动机水平视图。单独测量搜索服务器：Hit@K、MRR、符号分辨率、延迟、摄取速度。可用于调整检索；不足以声明代理级别值——这就是A/B模式的用途。

无其他基准覆盖 代码搜索+MCP协议+端到端代理A/B 在一个工具中。

代理A/B基准（最重要的一个）

# Requires: Claude Code CLI on PATH + nova-rag (or your server) installed
# Smoke run first — it spends real API/subscription usage:
rag-bench agent --repo flask --limit 10

# Full run, 105 queries × 2 conditions, with markdown report:
rag-bench agent -o results/agent_full.json -m results/agent_report.md

它对每个查询做什么：

              ┌─ condition A: claude -p "<question>" --bare --allowedTools Grep,Glob,Read
question ─────┤
              └─ condition B: same + --mcp-config nova-rag (tools: code_search, repo_map, …)
                       │
                       ▼
   grade answer vs ground truth (expected files + symbols, word-boundary matched)
   record: correct? · input/output tokens · num_turns · duration · cost

保持诚实的设计选择：

• 密封的: --bare --没有用户设置，没有CLAUDE.md，没有其他MCP服务器泄漏。
• 中性提示：该问题从未提及任何工具；两只手臂都没有得到任何暗示。
• 对称热身：每个手臂丢弃一个查询；nova-rag的索引构建发生在那里（像Cursor这样的索引在用户提问之前就已经存在）。
• 交错条件：每个查询背靠背运行A然后运行B，因此API漂移是平衡的。
• 透明分级：如果答案引用了预期的文件（最后两个路径组件），则答案是正确的 和 预期的符号（单词边界）。所有原始答案都存储在JSON结果中以供审计。可选的 --judge 增加了LLM评分规则。

首次出版（《快报》，克劳德·十四行诗4.6）

35个地面真实问题×2个条件，2026年6月，单次复制：

诚实地阅读这张表：

• 精度在小范围内达到饱和。 快递费约为15K LOC；前沿 使用grep的模型已经正确回答了97%的问题—— 没有获胜的准确空间。这与Cursor的发现相吻合 语义搜索收益集中在 大的 代码库。准确度 增量应在100K+LOC repos上进行测量（计划；PR增加一个 大型回购查询集非常受欢迎）。
• 70次运行中有2次出错（一个子进程超时，一次瞬态CLI 错误）；它们被排除在聚合之外，并在原始JSON中可见 (results/agent_express_sonnet46.json).

更新（v2运行，带有工具调用日志）： v1延迟获胜 （Express的折扣为-36%） 没有繁殖 --v2已测量~两者均为奇偶校验 Express和一个私有的2370文件C#monorepo（提交原始JSON）。这 新的每次通话工具日志记录解释了原因： MCP的采用率仅为9-18% --代理使用内置的Grep/Bash/Read和 从未调用过MCP工具，因此运行了v1的速度增量 差异，而不是产品效应。成绩单显示一致 ToolSearch → mcp__… 模式：在当前的Claude Code版本MCP工具中 模式被推迟到ToolSearch元工具之后，因此模型永远不会 在决策时查看MCP工具描述。值得注意的是：在8 查询代理所在的位置 做了 穿过诺瓦拉格的路线， 8/8个答案 正确.结论：工具 可见性，而不是检索质量，是 当前瓶颈——在相信任何A/B增量之前衡量采用率。

修复（经验验证）： "alwaysLoad": true 在服务器条目上 在MCP配置中，将所有工具重新内联到模型的工具列表中。 现在，线束将其设置在生成的配置中，与nova-rag的配置相匹配 记录安装命令。

v3运行（带有alwaysLoad修复）——采用率97–100%：

在私人monorepo上，代理人几乎完全转向了nova-rag (44 code_search + 14 rag_source 电话； Read 下降327→ 5) and 回答 在同等精度下速度提高3.5倍.

v4验证运行 （添加信任校准提示后：“符号不 在指数中，卖方存款不包括在内，“小额回购”和“小额回购 搜索就足够了”）：私有monorepo进一步改进为 p50 11.8s vs 100%时为60.7秒（-81%），而100%时为100%，令牌减少17%.快递 连续运行时仍存在噪声（n=35时±2个问题）和结构 尴尬：Express 5是外部包裹的薄壳 （路由器/主体解析器），因此一些“内部”问题在repo中没有 答案——仅将Express号码视为有方向性的。两个诚实的警告 快报：（1）最初的“准确性下降”主要是 基本事实 程序错误 --Express 5将路由器移动到外部包中；陈腐的 数据集因引用而奖励基线 lib/router/*.js 路径 那 结账时不存在 （训练数据幻觉）并受到惩罚 诺瓦接地回答“这是一个外部包裹”。固定在 数据集；所有跑步都根据存储的答案重新评分(scripts/regrade.py). （2） 剩下的差距是真实存在的，并被命名为：新星指数不包括 node_modules 从设计上讲，供应商提供的依赖性问题是盲目的 spot和代理在小型回购上过度调用搜索（+61%的代币）。 两者都作为产品跟进进行跟踪。

第二次运行（Django 5.2，~350K LOC）——以及方法论课程

30个经过验证的地面真实问题×Django上的2个条件：

一条完美的领带——还有 为什么 比表格更重要： 前沿 模型通过训练了解著名的开源代码库.代理人 在大约2个回合内回答了大多数Django问题，几乎没有搜索-- 它已经“记住”了 QuerySet 住在 django/db/models/query.py. 在充斥着模型世界知识的仓库中，没有检索工具可以 显示精度增量，因为检索几乎不发生。

含义，明确指出：

• 精度增量必须在模型具有的代码上进行测量 不 记住：私有代码库、训练后截止库或模糊库 项目。（这大概就是为什么Cursor的长凳使用了他们自己的eval 语料库而不是著名的OSS。)添加截断后查询集是 首要路线图项目——欢迎PR。
• 上面的Express运行仍然是效率方面的信息：当 代理人 做 搜索，nova-rag缩短了循环（-36%的延迟， −7.3%的令牌，精度相同）。
• 数据集完整性：每个Django地面真实条目都经过机器验证 对抗被钉住的5.2震源(scripts/verify_django_queries.py) — 文件必须存在，并且必须在声明的地方定义符号。

在您自己的计算机和模型层上运行它，然后发布您的表。欢迎有结果表的PR（包括基线获胜的PR）。

检索基准（引擎级别）

ragbench索引真实的开源存储库（Flask、FastAPI、Express），并运行105个已知正确答案的代码搜索查询。它衡量：

查询类型

• locate --“X在哪里定义？”（最常见的开发人员问题）
• callers --“什么叫X？”
• explain --“X是如何工作的？”（需要多个相关文件）
• impact --“如果我改变X，会发生什么？”
• multi_hop --“通过多个文件跟踪X到Y”（传递性推理）
• cross_package --“模块A如何与模块B交互？”
• architecture --“项目的结构和层次是怎样的？”
• dead_code --“函数X真的在任何地方被调用吗？”
• conditional_path --“当条件C为真时，存在哪些代码路径？”
• test_traceability --“哪些测试涵盖了函数X？”

A/B模式

比较RAG与grep/glob基线，以衡量RAG提供的实际改善：

• 工具调用减少了多少？
• 找到正确的代码要快多少？
• RAG真的有帮助吗？或者grep足够吗？

快速开始

# From PyPI (distribution name is nova-rag-bench; the CLI is `rag-bench`)
pip install nova-rag-bench

# Or from source
git clone https://github.com/Miro96/nova-rag-benchmark.git
cd nova-rag-benchmark
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,bm25,cocoindex]"

# Run benchmark on your RAG MCP server
rag-bench run --command "python -m your_server" --transport stdio

# Or use a preset
rag-bench run --preset mcp-local-rag

# Run tests (761 tests)
pytest tests/ -v

用法

对单个服务器进行基准测试

# With a preset
rag-bench run --preset nova-rag

# With a custom command
rag-bench run --command "npx -y mcp-local-rag" --transport stdio

# With a config file
rag-bench run --config my-server.json

# Only test on one repo
rag-bench run --preset nova-rag --repo flask

# A/B comparison vs grep baseline
rag-bench run --preset nova-rag --ab-baseline

比较多台服务器

rag-bench compare --presets nova-rag,mcp-local-rag,chroma-mcp

运输方式

rag bench支持三种客户端传输模式 BaseClient 接口：

# MCP stdio (default)
rag-bench run --command "python -m my_server" --transport stdio

# CLI subprocess
rag-bench run --command "my-rag search" --transport cli

# In-process (requires Python module)
rag-bench run --preset naive-rag --transport inprocess

排行榜

# Start the web leaderboard
rag-bench serve --port 8080

# Submit results
rag-bench submit results/run_*.json \
  --git-url https://github.com/you/your-rag \
  --git-user yourusername \
  --server-url http://localhost:8080

打开 http://localhost:8080 查看带有排序、过滤和雷达图比较的排行榜。

服务器配置格式

为RAG MCP服务器创建JSON配置：

{
  "name": "my-rag-server",
  "git_url": "https://github.com/you/my-rag",
  "command": "python -m my_rag.server",
  "transport": "stdio",
  "tool_mapping": {
    "ingest": {
      "tool": "index_directory",
      "params": { "path": "{path}" }
    },
    "query": {
      "tool": "search",
      "params": { "query": "{query}", "limit": "{top_k}" }
    }
  }
}

如果 tool_mapping 如果省略，rag bench将通过分析来自的工具名称和模式来自动检测工具 tools/list.

预摄取命令

您可以通过以下方式声明在索引之前运行shell命令 pre_ingest 现场。使用 {repo_path} 作为存储库目录的模板变量，以及 {cwd} 对于基准时间的工作目录：

{
  "name": "my-rag-server",
  "pre_ingest": [
    "pip install -r {repo_path}/requirements.txt",
    "cd {repo_path} && npm install"
  ]
}

索引目录

预设配置可以声明要索引的目录（默认为repo根目录）：

{
  "name": "my-rag-server",
  "index_directories": ["src/", "lib/"]
}

默认情况下，所有未被忽略的文件都会被索引； index_directories 限制对特定子目录的索引。

内置预设

比较结果（105个查询，3个重复）

Flask+FastAPI+Express上所有内置预设的四向比较：

rag-bench compare --presets nova-rag,naive-rag,cocoindex-code,grep-glob --replicates 3

关键要点：

• 诺瓦拉格 是解析符号的唯一预设（33.3%符号Hit@5)--grep/glob和仅嵌入的方法无法识别函数/类名。
• grep glob 在原始文件召回中获胜（55.2%Hit@5)--但请仔细阅读这个数字：grep通过返回候选文件的广泛列表来“赢得”召回。使用该列表的代理仍然必须打开并读取每个候选，燃烧回合和令牌。文件召回测量发动机；确实如此 不 衡量代理人的经历。这种差距正是 代理A/B基准 存在——它衡量端到端的答案准确性和令牌成本，其中符号解析和图查询（调用者/影响）会得到回报。
• 天真的破布 （仅嵌入）在文件召回方面表现最差（6.7%）Hit@5)，表明仅凭语义相似性不足以进行代码搜索。
• cocoindex代码 具有高延迟（~450ms p50），而其他方法的延迟低于25ms。
• 诺瓦拉格 索引速度比原始rag快13倍（2675比206文件/秒）。

再现性：所有预设在3个重复的复合评分中的CV均小于0.05。

数据集

4个真正的开源存储库，135个查询包含基本事实：

Django条目通过以下方式根据固定的5.2源代码进行机器验证 scripts/verify_django_queries.py （文件必须存在，符号必须 在声明处定义）——但请注意代理中的训练数据警告 基准测试部分：著名的repos无法揭示 前沿模型。

每个查询都有：

• 预期文件（地面实况）
• 预期符号（函数/类名）
• 难度级别（易/中/难）
• 查询类型（定位/调用者/解释/影响/多操作/交叉包/架构/死代码/条件路径/测试跟踪性）

指标

综合得分公式

Score = 0.30 * Hit@5
      + 0.15 * SymbolHit@5
      + 0.15 * MRR
      + 0.15 * ToolCallEfficiency
      + 0.15 * LatencyScore
      + 0.10 * ResourceScore

运作原理

建筑流水线

Presets (JSON configs)
    │
    ▼
Runner ──► ingest ──► warmup ──► benchmark ──► results
    │
    ▼
Report generator (Rich tables / JSON / leaderboard submit)

该基准遵循严格的三相管道每次运行：

1. 摄取 --RAG服务器为数据集中的每个存储库建立索引。挂钟时间以“摄取速度”（文件/秒）来衡量。支持预先存在的索引的服务器可以在第一次运行后跳过此阶段。

2. 热身 --每种查询类型都会运行一次（结果被丢弃），以确保缓存、JIT编译器和连接池在测量开始前处于稳定状态。

3. 基准 --所有105个查询都以随机顺序对每个存储库执行。每个查询都是单独计时的（p50/p95/平均延迟）。将结果与已知的地面真实值进行比较以进行计算Hit@K、MRR、MAP和符号Hit@5.

4. 结果 --指标在3个独立的重复中汇总。中值以四分位数间距（IQR）报告。计算多服务器比较的统计显著性（A/B增量）。

预设

每个预设都是一个JSON配置文件，声明服务器的传输、工具映射和可选的预摄取步骤。该基准测试附带了5个预设，涵盖了所有代码检索方法：

查询类型

该基准测试包括10个不同类别的105个查询，每个查询都测试了不同的现实世界代码搜索需求：

指标

每次运行都会计算一组全面的检索质量、性能和效率指标：

再现性

比较表中的每个结果都是 3个独立重复的中位数 具有种子随机性（对于确定性洗牌，每个复制的种子都是固定的）。这确保了：

• 在复制决定论中：相同的种子→ 相同的查询顺序→ 给定服务器版本的相同结果
• 跨复制差异：每个复制使用不同的随机种子，捕捉服务器启动、操作系统调度和I/O中的自然变化
• IQR报告：四分位数间距显示了分布——较小的IQR意味着度量是稳定的；大IQR标记噪声
• 统计严谨性：A/B比较使用跨重复的配对测试来计算增量置信区间

比较表中的所有预设值在3个重复的复合评分中的变异系数（CV）均小于0.05。

代码布局

rag_bench/
├── cli.py              # CLI entry point (click)
├── transport/          # Client transport layer
│   ├── base.py         # BaseClient interface
│   ├── mcp_client.py   # MCP JSON-RPC client (stdio)
│   ├── cli_client.py   # Subprocess CLI client
│   └── in_process.py   # In-process (Python import) client
├── adapter.py          # Normalizes different RAG server interfaces
├── runner.py           # Orchestrates: ingest → warmup → benchmark → metrics
├── metrics.py          # Hit@K, MRR, latency percentiles, composite score
├── baseline.py         # Grep/Glob baseline for A/B comparison
├── report.py           # Rich terminal tables
├── submit.py           # HTTP submit to leaderboard
├── presets/            # JSON configs for known servers
└── datasets/           # Repos + 105 queries with ground truth

server/
├── app.py              # FastAPI leaderboard server
├── db.py               # SQLite storage
├── models.py           # Pydantic models
└── static/             # Leaderboard web UI

贡献

1. 添加查询 --更多的查询提高了基准测试的可靠性。增添 rag_bench/datasets/queries/
2. 添加预设 --中新RAG MCP服务器的配置文件 rag_bench/presets/
3. 添加仓库 --中的新测试存储库 rag_bench/datasets/repos.json
4. 提交结果 --运行基准测试并提交到公共排行榜

为什么存在

现有的基准测试不包括RAG+MCP+代码搜索交集：

与其他基准的比较

现有的基准测试要么评估嵌入模型、文档检索，要么评估编码代理——没有一个衡量端到端的代码智能检索管道。以下是抹布长凳的不同之处：

为什么这些差异很重要

• 仅嵌入基准测试（MTEB、CoIR） 告诉您使用哪种模型，但不告诉您的检索管道是否正常工作。一个具有较差分块、没有图、没有混合回退的优秀嵌入模型在实际代码查询中仍然会失败。
• 记录质量保证基准（CRAG） 测试一个根本不同的问题：在散文文档中查找事实与在具有导入、继承和控制流的代码库中查找正确的函数。
• 代理基准（SWE工作台） 将检索质量与编码能力混为一谈。一只完美的寻回犬搭配一只较弱的LLM成绩很差；具有强LLM的弱检索器仍然可以重新读取整个仓库。

ragbench将检索质量与LLM隔离开来，因此您可以独立衡量和改进搜索引擎。

许可证

麻省理工学院