又是一个让程序员狂欢的研究！来自 OpenHands、耶鲁、南加大和斯坦福的研究团队刚刚发布了 LocAgent—— 一个专门用于代码定位的图索引 LLM Agent 框架，直接把代码定位准确率拉到了 92.7% 的新高度。该研究已被 ACL 2025 录用。
-
论文标题：LocAgent: Graph-Guided LLM Agents for Code Localization
-
论文链接：https://arxiv.org/abs/2503.09089
-
代码链接：https://github.com/gersteinlab/LocAgent
一、痛点很真实：代码定位到底有多难？
相信每个程序员都有过这样的经历：看到一个 bug 报告，满脸问号地想「这到底要改哪里？」。传统方法要么靠关键词匹配（太粗糙），要么直接把整个代码库丢给 LLMs（太低效），要么让 Agent 盲目遍历目录（太笨拙）。
问题的核心在于：自然语言描述的问题和真正需要修复的代码位置之间，往往隔着好几层调用关系。比如用户反馈「XSS 漏洞」，但实际需要修改的可能是某个深层的验证工具函数。
换言之，代码定位指的是在大型代码库中精确找到需要修改的代码位置，在软件开发与维护中，准确地定位代码问题是提高开发效率的关键（图 1 展示了四种常见的代码修复场景）。
图 1：给定一个代码库（左）和问题描述（中，包含四种场景的示例），代码定位需要识别出需要修改的相关代码位置（右），包括具体的文件、类和函数。LocAgent 旨在让 LLM Agent 自动完成这一过程。
自然语言中的问题描述（如错误报告）往往与真正的故障根因存在显著的语义差异与结构距离（如图 2 所示）。这不仅要求模型能够深入理解自然语言编写的错误报告，还需具备在庞大代码库中跨越层级结构和复杂依赖关系进行推理和追踪的能力。
图 2: 图中红色节点表示问题描述中明确提及的函数，黄色节点表示实际需要修改（修补）的函数。任务难度定义为代码图中从提及函数到目标修补函数之间的最短路径长度（最少跳数），图示例中任务难度为 2 跳。
二、LocAgent：给 LLM 装上「代码地图」
该研究团队的解决方案相当巧妙：首先他们把整个代码库解析成一张图，包含文件、类、函数之间的包含、调用、继承、导入关系。然后该团队为 LLM Agent 提供简洁统一的图原语接口，以支持离效探索代码库。该方法通过将代码库解析为异构图表示，让大语言模型能够像使用地图一样高效地在代码中「移动」，实现多跳推理，逐步接近目标代码。
图 3：LocAgent 框架概览
如图 3 所示，LocAgent 首先将代码库解析为一个异构图表示，图中包含多种类型的代码实体及其依赖关系。在此基础上，系统构建了分层稀疏索引，用于支持高效的内容检索与结构化探索。借助这些索引，LocAgent 能够结合图结构与工具接口，执行由 Agent 驱动的逐步搜索过程，精准完成代码定位任务。
2.1 代码表示构建过程
代码图表示构建：为统一表示代码库中的结构与语义信息，LocAgent 基于抽象语法树（AST） 对代码库进行解析，构建一个异构有向图 作为结构化索引，详细表示了代码目录、文件、类、函数之间的包含、调用、导入和继承关系，使得隐式依赖显性化，便于 LLM 高效推理。
这种图结构的优势在于：即使两个代码片段分处不同模块，只要存在调用或继承关系，在图上它们就会变得「邻近」。比如，以往基于目录导航的方法会认为远隔两个子目录的模块毫不相干，但如果模块 A 函数调用了模块 B，在 LocAgent 的图中 A 和 B 会通过调用边直接连接，使它们在该图结构上靠近。对于代码定位任务，这种「邻近」至关重要，因为许多问题不是局限在单个文件夹内部，而是通过调用链跨越多个模块。
2.2 提供工具接口供 Agent 查询
构建好代码图后，LocAgent 提供了统一的工具接口，让 LLM Agent 能够方便地查询图结构和代码内容。主要包括以下三个 API：
-
SearchEntity：该工具基于层次化实体索引，使用关键词搜索代码库中相关实体。当在上层索引中未能找到匹配项时，系统会自动使用下一层索引进行搜索，从精确匹配到模糊搜索，以查找最接近的匹配项。对于检索到的每个实体，SearchEntity 会返回该代码片段的摘要（如图 4，有折叠级别、预览级别和完整代码三级，可根据需要展开）。
图 4: 为高效的 Agent 代码交互而设计的不同输出格式示例。
-
RetrieveEntity：当 Agent 确定了某个代码实体很可能就是目标时，可以用此工具提取该实体的完整信息。当输入实体 ID，RetrieveEntity 输出该实体的文件路径、起止行号、完整代码内容等详细属性。
-
TraverseGraph：该工具在代码图上执行类型感知的广度优先搜索。Agent 可以指定起始的实体 ID，以及希望遍历的方向、步数（hops）、实体类型和关系类型等参数。工具会在图中从起点出发按照要求走指定步数，返回遍历到的子图结构。通过设置不同的类型过滤，Agent 可以灵活地探索比如「沿调用关系向下追踪两步」或「查看从某类出发的继承层次」等等。值得一提的是，TraverseGraph 将返回的子图格式化成一种树状结构文本（见图 5），以便 LLM 更容易理解关系拓扑。
图 5：TraverseGraph 工具输出示例。
2.3 Agent 驱动的推理阶段
LocAgent 在提示设计上采用了「逐步思考」(Chain-of-Thought, CoT) 的策略，引导 LLM Agent 将代码定位任务分解为一系列步骤，模拟人类调试思路一步步逼近目标。整个问题求解过程可以概括为以下阶段：
-
问题理解与关键词提取：Agent 首先对输入的 issue 描述进行分析，划分出不同方面的信息，然后提取出与问题相关的关键词。这些关键词相当于为后续搜索指明了初步方向。
-
链接关键词到代码实体：针对每个提取的关键词，Agent 调用 SearchEntity 工具在代码索引中查找匹配的代码实体。
-
多跳推理，生成故障链路：接下来，Agent 会尝试串联线索，从报错表征推导故障原因。它先确定问题触发的初始入口点（例如触发错误的 API 或函数），然后以这些点为起点，在代码图上进行迭代探索：调用 TraverseGraph 沿调用关系或依赖关系向相关方向搜索；用 RetrieveEntity 查看某些关键节点的实现细节；必要时再次 SearchEntity 引入新的关键词。通过多轮交替使用这些工具，Agent 逐步构建起一条从问题症状到潜在根因的逻辑路径。
-
锁定目标代码：在形成对问题的全面理解后，Agent 根据「故障链路」中暴露的可疑环节，定位出所有可能需要修改的目标代码实体（可能是若干个函数或类）。随后，Agent 对这些候选实体按相关性进行排序输出，并给出它们的文件路径以及简要的原因说明。
整个 LocAgent 的使用对用户来说非常简洁：只需输入自然语言的问题描述， LLM Agent 就会如上所述自主地完成一系列搜索、遍历、读取操作，最后给出代码定位结果。
三、实验结果：真香警告
LocAgent 在真实数据集上的表现和分析结果令人瞩目。研究中使用了既有的基准数据集（SWE-Bench Lite）以及团队新构建的 Loc-Bench，对比了多种基线方法的代码定位效果。
（1）代码定位效果出色
SWE-Bench Lite 是从 GitHub issue 中构建的仓库级代码修复数据集，也常用于代码定位评估，包含 300 个问题及其对应的修复代码，其中大部分为 bug 报告。基于该基准，LocAgent 实现了目前最优的代码定位准确率，显著优于现有方法。
-
相比传统的向量检索方法有显著提升：BM25 在文件级 Acc@5 上仅为 61.7%，而先进的代码嵌入模型如 CodeRankEmbed 也仅达到 84.7%；而 LocAgent 准确率高达 92.7%，在函数级定位中也同样显著优于这些方法。
-
多步推理的 Agent 类方法整体上胜过基于固定流程的方法。基于固定流程的方法（如 Agentless）往往只能依据字面匹配找到有限的候选，而引入了 Agent 逐步探索后，能够考虑更广的范围，定位效果更好。
-
在文件、模块、函数三个粒度上，LocAgent 全面超越了基于 GPT-4o 或 Claude-3.5 的现有 Agent 系统。使用 Claude-3.5 时，LocAgent 在 SWE-Bench Lite 文件级 Acc@5 达到 94%，在函数级定位上同样优于其他方法。
-
LocAgent 搭配 Qwen2.5-32B (微调) 模型的性能几乎与 Claude-3.5 持平：在 SWE-Bench Lite 文件级 Top-5 准确率上，前者为 92.7%，后者约 94.2%，差距很小。而如果使用 Qwen2.5-7B (微调) 小模型，虽然准确率略有下降（约 88.3%，但仍超过绝大多数 baseline），其表现已能够逼近 GPT-4o 的效果。
（2）多任务场景下的泛化能力
由于 SWE-Bench Lite 数据集过于偏重 Bug 类型，团队打造了新的 Loc-Bench 基准，用于全面评估方法在多样化软件维护任务中的定位能力。Loc-Bench 共包含 560 个真实 GitHub issue，覆盖 Bug 修复、功能新增、安全漏洞与性能优化四大类，任务类型更加均衡，贴近实际工程场景。
四、开源福利：小模型也能打
这个研究最让人兴奋的地方在于：开源模型经过微调后，也能达到商用大模型的效果。他们提供了两个版本，1. Qwen2.5-7B 微调版：性能媲美 GPT-4o，单次处理成本仅 $0.05；2.Qwen2.5-32B 微调版：逼近 Claude-3.5 水平，成本节省 86%。这对于需要大规模部署的企业来说，这简直是降本增效的神器。
具体而言，微调的 Qwen2.5-7B 模型，LocAgent 在 Loc-Bench 四类场景下的平均文件级 Acc@5 为 76.8%，函数级 Acc@15 为 46.9%，已接近 SWE-Agent 搭配 Claude-3.5 的表现（后者函数级约 45.4%）。进一步将 LocAgent 与 Claude-3.5 结合后，文件级平均准确率可提升至 81.1%，在四类任务中几乎全面超越其他方法。
五、实际应用：不仅是定位，还能助力解决问题
研究团队验证了一个关键点：更准确的代码定位直接提升问题解决率。在 GitHub 问题自动修复任务中，使用 LocAgent 的 Pass@10 成功率比基线方法提升了 12%。这意味着这项技术不仅仅是个「定位工具」，而是能实实在在提升整个软件维护流程效率的利器。
该团队进一步从不同角度展开分析，探讨其在复杂任务中的稳定性、成本效率、关键组件作用以及对下游应用的实际价值。
（1）难度分级实验与多跳鲁棒性
为了深入了解 LocAgent 的能力，该团队还按照任务的难度对性能进行了分析。该团队将「难度」用代码图上函数距离（hop 数）来衡量：即 Issue 描述中提及的函数与实际需要修改的函数之间的最短路径。直观地说，hop=0 表示 Issue 直接提到了需要改的函数名；hop=1 表示目标函数是 Issue 中提到的函数之间有直接关系，hop 数越大则定位难度越高。
实验发现：随着 hop 数增加，所有方法的定位准确率都在下降。毕竟关联越不直观，模型需要推理的链路就越长。不过，不同方法的鲁棒性差异明显：Agent 类方法在高难度下的性能下降幅度明显小于检索类方法。特别是 LocAgent 借助图结构索引，在 hop 数增加时仍能保持相对较高的准确率，表现出较好的鲁棒性。
相比之下，传统检索方法在需要两跳以上时几乎失效，在函数级定位上即使目标函数名字就出现在查询里，有时都找不到（因为它们往往把查询当做整体，无法拆解处理细节）。
（2）效果与成本比较
借助结构化图索引与工具调用，LocAgent 仅需 6～9 轮交互即可完成一次代码定位任务，推理过程高效。此外，该团队利用开源模型取得了媲美商用大模型的结果，同时大幅降低推理成本，具备实际落地部署的可行性。
具体来看，使用 Claude-3.5 等商用 API 模型时，每个 Issue 的平均处理成本约为 $0.66；而使用本地部署的 Qwen2.5-32B 模型，成本降至约 $0.09，降低了 86%。若进一步采用 7B 的小模型，处理成本可低至 $0.05，仍能保持优于大多数方法的性能。从函数级准确率与成本的比值来看，微调后的 Qwen-2.5-7B 是性价比最高的方案，其效率优于所有商用模型；Qwen-2.5-32B 次之，也显著优于 Claude-3.5。这表明，结合 LocAgent 框架，开源模型不仅具备性能竞争力，更具部署经济性。
（3）应用效果：高质量定位显著提升问题解决率
为评估代码定位在实际软件维护任务中的影响，该团队进一步分析了 LocAgent 在自动解决 GitHub 问题中的效果。结果表明，随着定位准确率的提升，问题解决成功率显著提高，说明更精准的定位结果能够显著增强自动化代码修改的质量与稳定性。该发现验证了 LocAgent 不仅在定位本身表现优秀，也能有效推动下游任务的整体性能，具备实际工程价值。
六、技术启示：结构化索引 + 智能推理
LocAgent 的成功揭示了一个重要趋势：从「暴力计算」到「智能决策」的范式转变。传统方法要么把整个代码库直接丢给 LLM 进行暴力匹配，要么让 Agent 按照预设规则盲目遍历目录，这些都属于「计算密集型」的解决方案。而 LocAgent 通过图索引等结构化中间表示，将复杂问题进行结构化分解，然后让 LLM 承担更高层次的推理和决策任务。
这种「agentic retrieval」范式的核心在于决策智能化。通过图、树等结构化中间表示，信息变得更易于推理，Agent 能够根据具体问题动态调整搜索策略，而非死板地遵循预设路径。这代表了从「人工设计各种 RAG pipeline」向「让 AI 自主决策如何检索」的转变。
这种结合结构化索引与 LLM 智能体协同设计的范式，很可能成为未来 AI 工程应用的标准模式。不再是让 LLM 做更多计算，而是让 LLM 做更智能的决策 – 程序员的 debugging 体验又要迎来一次重大升级了！
©
（文：机器之心）