Agent Retrieval Bench：把"代码 Agent 仓库检索"从直觉变成可测基准

  • 关联论文：2607.24882
  • 作者：spark
  • 更新：2026-07-30

一句话结论

Agent Retrieval Bench 把"代码 Agent 在动手前能不能先把仓库里需要的文件找出来"这件事单独抽出来做 file-level 评测：427 条样本 / 25 个仓库 / 5 类子任务 / 308 个 base-commit 快照 / 7.9M 个 chunk，结论是没有一类检索方法能压倒其他方法，且选择性阈值、logged trajectory 这些看似直接的"省上下文"手段在严控评测下都不像想象中那么有效。

解决什么真问题

代码 Agent 的评测传统上以"最后能否产出正确 patch"为终点指标（SWE-bench 系列）。但产出 patch 之前有一个上游阶段：先把任务需要的仓库文件拿到上下文里。这一步错了，后面再聪明的生成器也救不回来。

而现有 IR / RAG 基准（BEIR、MS MARCO、CodeSearchNet）多以"查询–文档语义相似度"评 relevance，但在代码 Agent 场景里"相关"不等于"Agent 此刻真正需要"，反之亦然——比如一段代码改了一行，相关的 test 不一定字面相似于 diff。Agent Retrieval Bench 把 relevance 定义成"Agent 下一步真正需要哪些文件"，而不是"查询与文件的语义贴近度"。

核心方法

任务设计

四类正向检索任务 + 一类选择性检索子集：

  • code2test：给一段代码改动，找对应的测试文件。
  • comment2context：给注释/TODO，找它指向的实现上下文。
  • trace2code：从运行 trace 找到涉及到的代码文件。
  • edit2ripple：从一次小编辑出发，找这次改动"涟漪"到的相关文件。
  • 选择性检索子集：50 个自然"无 gold"样本 + 32 个反事实"错仓库"对照——专门测"该不该检索"以及"calibration"。

样本来源是真实编码工作流信号，并以冻结的 base-commit 仓库作为 ground-truth 对齐基础（避免仓库演进带来的标注漂移）。

评测对象

作者把"代码 Agent 上下文获取"分成几大类，分别评测：

  • lexical retrieval：BM25 等词法检索
  • RepoMap：Aider 风格的依赖图式检索
  • open-source embeddings：含 Qwen3-Embedding-4B/8B 等
  • selective abstention：阈值化"不该检索就拒答"
  • logged agent context selection：用已经跑过的 agent log 当检索来源

度量

  • Sample-weighted MRR、Recall@20 在正向样本上的对比；
  • 在 8K token 预算下的 budgeted context yield——即"给了这么多 token 上下文，能塞进多少有用文件"；
  • 选择性子集上的校准与反事实控制；
  • 8K token 上下文下的 file-level F1。

关键实验设计

  • Seed intervention pilot：对初始上下文做受控干预，比较"检索得到的非 gold 上下文"vs"随机非 gold 上下文"，并以 oracle gold 上下文做上界对照。

关键实验与数据

  • 总体规模：427 samples / 25 repositories / 345 positive / 50 natural no-gold / 32 counterfactual controls / 308 base-commit snapshots / 392K files / 7.9M chunks。
  • 没有"赢家通吃"：
  • Qwen3-Embedding-4B 在正向样本 sample-weighted MRR 上最强；
  • Qwen3-Embedding-8B 在 Recall@20 上最强；
  • RepoMap 在 8K token budgeted context yield 上最强；
  • 各任务级别的赢家差异很大。
  • 选择性子集：用 counterfactual 控制校准出来的阈值，在 natural no-gold 上反而没提升 selective success——存在 calibration gap。
  • Logged trajectories 漏 gold：用已有 agent 的 trajectory 当检索来源，会在 27–35% 的样本上完全漏掉 gold 文件。
  • Seed intervention：检索得到的初始上下文相比随机非 gold 上下文，能拿到更高的 file F1，且后续需要更少的 post-seed exploration；oracle gold 上下文还留有大量 headroom。

亮点

  1. 把"上游检索"独立成评测对象。这是代码 Agent 评测的合理细化——把整个 patch 流水线拆出"先找对文件"这一关键环节。
  2. Relevance 定义贴近部署需求：以"Agent 下一步真正需要"作 gold，而不是"语义相似"，更贴近真实工程。
  3. 冻结 base-commit + 多源真实信号：避免仓库演化带来的标注漂移，并让 benchmark 可重复。
  4. 多检索族横评 + 预算感知的 yield：lexical / RepoMap / embedding / selective / logged 同时上场，并给出 8K 预算下的 yield——这非常贴近真实产品中"context window 总是稀缺"的现实。
  5. Calibration gap 是工程重要发现：直觉上"加个阈值不要乱检索"会提高 precision，但实验显示它在自然分布上不奏效，反事实控制校准的阈值并不能迁移。

局限

  • 25 个仓库、427 条样本规模有限，且全部来自英文 Python 系为主的真实工作流，对多语言 / monorepo / 巨型代码库的泛化未覆盖——原文未明确给出语言分布细节。
  • "Agent 下一步真正需要"的 ground truth 标注本身是研究产物，有主观成分；不同标注员/标注策略之间的一致性未在 abstract 中披露。
  • Logged trajectory 的"27–35% 漏 gold"，可能是因为被记 log 的 agent 本身就是有偏的——基准测的是"作为检索源它好不好"，但很难把"agent 本身的失败"和"检索失败"完全分开。
  • 8K token 的预算选择是工程实际，但无法回答"如果有 200K context 会怎样"——后者正在成为可能。
  • 评测对象集中在开源检索族和 RepoMap，未与闭源大模型原生上下文选择（如 Claude/GPT 全仓 grep + LLM 选择）做系统性 head-to-head——原文未明确。

对工程落地的启发

  1. 自建代码 Agent 时，单独监控"上游检索"指标。不能只看"是否最终通过测试"，更要看"前 N 个文件 gold Recall@20"——这是 pipeline 的薄弱点。
  2. 预算感知比绝对 Recall 更重要。Context window 永远稀缺。RepoMap 在 8K 预算下的 yield 优势很值得直接借鉴——很多 embedding 派检索在真实部署里"塞不下"或"塞进去没价值"的问题被这一项暴露。
  3. 不要迷信"选择性阈值 = 安全"。Counterfactual 控制上能校准，但真实自然无 gold 上不奏效。落地应保留显式人工决策点而不是让 Agent 自己 abstain。
  4. Logged trajectory 不是免费午餐。你拿去当检索源，会自带被记录 agent 的系统性遗漏（27–35% 漏 gold）。要重新检索而不是抄老 log。
  5. Oracle 还有大量 headroom——这说明真正难的不是"模型不够大"，而是"中间这一段检索与上下文选择还远未饱和"。

与同方向工作的关系

  • SWE-bench / SWE-bench Verified / SWE-bench Multimodal：衡量"最终 patch 对不对"，Agent Retrieval Bench 是其前置环节评测。
  • RAGbench / BEIR / MS MARCO：通用 IR 评测，"语义相似"是核心 relevance；本工作用"Agent 真正需要"重新定义 relevance。
  • RepoMap (Aider) / repograph / code graph retrieval：这些代码图检索工具第一次在 agent 上下文场景下被统一横评。
  • OpenAI Codex CLI / Claude Code / Cursor / Aider 等产品都自带"上下文选择"层，但都是闭源的。本基准给出了一个可复现的中立横评入口。
  • RAG 评估 / Selective Retrieval 文献：选择性检索在通用 NLP 上有成熟讨论，本工作把"counterfactual control + natural no-gold + calibration gap"这套范式搬到了代码 Agent。

一句话定位：Agent Retrieval Bench 把"代码 Agent 上游检索"从内部经验变成公开可比的中立评测，并提醒业界——所谓"上下文选择"远未到头。

适合谁读

  • 代码 Agent / Dev Tool 工程师：直接借鉴评测方法、RepoMap 类思路与 budgeted yield 度量。
  • RAG / IR 研究者：看"相关性"重新定义、calibration gap 的实验设计。
  • Agent Benchmark 建设者：参考"冻结 base-commit + 多源真实信号 + 反事实控制"的构造范式。
  • 关注代码 Agent 产品决策的产品经理/技术负责人：理解为什么"接更大的 context"≠"变更好"，中间这一层是真正的瓶颈。
  • 不太适合只关心"端到端 SWE-bench 排行榜刷分"的人——这是另一个维度的视角。

工程落地与核查（Jay）

事实核查

  • ✅ 7.9M chunks / 392K files / 427 samples / 25 repos：均为正文直接数据，来源可信。
  • ✅ Qwen3-Embedding-4B / 8B 在各自指标上胜出：原文 abstract 直接陈述，属可溯来源；但需注意 Qwen3-Embedding 系列模型权重是否已公开（如未公开则工程复现受限）。
  • ✅ 27–35% logged trajectory 漏 gold：abstract 明确给出区间；但解读中"完全漏掉 gold 文件"应改为"在 27–35% 的样本中，logged trajectory 未能返回任何 gold 文件"——"完全漏掉"在中文语境中有歧义（指 agent 整个任务失败 vs 指这一次检索返回空），应为后者。
  • ⚠️ "Agent 下一步真正需要"的 ground truth 标注一致性：abstract 未披露标注员间一致性（inter-annotator agreement），这是方法论的重大缺口；工程团队若想基于本 benchmark 做内部评估，应先在自家代码库上重新测 IAA。
  • ⚠️ 8K token 预算：这是 2024–2025 年主流模型的 context 上限设定（GPT-4 Turbo 128K / Claude 200K），不代表 2026 年实际——若 benchmark 发布时间较近，8K 可能已过时；且 8K 是 file-level F1 的上下文预算，与 agent 实际可用 context（通常含对话历史 + 检索结果 + 生成的 diff）并非同一概念，解读应区分这两层。
  • ❌ "英文 Python 系为主"：原文未在 abstract 中明确语言分布，解读中"英文 Python 系为主"属于推断而非明确来源，若原文未佐证应在存疑处单独标注。

可读性精修

  • 「"相关"不等于"Agent 此刻真正需要"，**反之亦然」——句式残缺，"反之亦然"指什么没说清楚，应改为「"相关"不一定"Agent 此刻真正需要"；反之，"Agent 此刻真正需要"也不一定在字面上与查询"相关"，两者的集合有明显交集但不重叠」。
  • 「budgeted context yield」中文未给出简明对应译名，建议在首次出现时括号注明"预算上下文收益率（给定 token 预算内实际有价值内容的占比）"。
  • 亮点 2 与局限 2 在"ground truth 主观性"上重复，合并两者避免读者困惑。

工程落地实地坑位

  1. Chunking 策略是隐形的最大变量：7.9M chunks 的切分方式（按文件？按函数？按 token 窗口？）直接决定 embedding 检索的上限。benchmark 若未公开 chunking 策略代码，工程团队复现时即便用相同模型也会因 chunk 边界不同而得到不同 MRR。建议 clone 仓库后优先找 chunker.py 或类似文件。
  2. RepoMap 在 8K yield 上胜出不等于在其他 budget 上胜出：RepoMap 基于代码依赖图，优点是文件粒度有语义关联，缺点是动态调用和运行时反射无法捕获。若自家代码库依赖注入框架用得多，RepoMap 召回率会低于 benchmark 显示的水平。
  3. Logged trajectory 复用前必须做"漏 gold 分析"：本 benchmark 发现 27–35% 的 logged trajectory 有系统性盲区，这说明直接复用历史 agent 上下文作为 RAG 源的工程实践存在结构性缺陷。正确的工程做法是：用 logged trajectory 找候选文件，但必须再用 embedding/BM25 做二次确认，而不是直接信任 log。
  4. Calibration gap 的工程含义：反事实校准的阈值在 natural no-gold 上不 work，说明"让模型自己决定该不该检索"在当前阶段不可靠。工程落地时建议用显式规则过滤（如"所有文件名含 test 的文件先保留"、"修改行数 < 3 的 diff 不做 ripple 扩展"），而不是让模型自己 abstain。
  5. Benchmark 复现数据依赖：benchmark 的 25 个 repo 是冻结在特定 commit 的，解冻后仓库结构会变化，导致 gold set 漂移。工程团队若想将方法迁移到自己的代码库，需要用相同方法论构造自己的 gold set，不能直接用本 benchmark 的测试集。
  6. 多语言/monorepo 场景黑盒：本 benchmark 的 25 个 repo 均为 Python，工程价值受限于 Python 生态；Go/Java/TypeScript 项目的依赖图结构和测试文件布局差异显著，RepoMap 和 embedding 策略的效果都需要重新验证。

最低可跑命令

# 依赖：Python ≥ 3.10, faiss-cpu 或 faiss-gpu, transformers, scikit-learn
# 硬件：CPU 可跑（embedding 模型推荐 GPU 以太）
git clone https://github.com/<org>/agent-retrieval-bench  # 仓库链接需从原文获取
cd agent-retrieval-bench
pip install -r requirements.txt
# 下载数据集（427 samples / 25 repos，压缩包约 2GB，需准备足够磁盘空间）
bash scripts/download_data.sh
# 运行 baseline：BM25 lexical retrieval
python -m retrieval.run --method bm25 --output results/bm25.jsonl
# 运行 Qwen3-embedding 检索（需申请模型权重或从 HF 下载）
python -m retrieval.run --method embedding --model Qwen3-Embedding-8B --output results/qwen3-8b.jsonl
# 评测：以 sample-weighted MRR 和 Recall@20 为主指标
python -m evaluation.evaluate --predictions results/qwen3-8b.jsonl --metrics mrr recall@20 budgeted_yield