Semble：优化 AI 代理的代码搜索，实现 98% 令牌减少

对于构建 AI 编码代理的开发者来说，"grep-and-read" 循环是一个臭名昭著的瓶颈。当代理需要理解代码库时，通常会 grep 关键字，定位文件，然后将整个文件读取到其上下文窗口中。这个过程不仅慢，而且极其浪费，常常在无关代码上消耗数千个令牌，仅仅为了找到单个函数定义。

Semble 是一个旨在打破此循环的代码搜索库。通过为代理提供执行自然语言和语义查询的方式，仅返回最相关的代码块，Semble 声称相较于传统的基于 grep 的探索，可将令牌使用量降低高达 98%。

Semble 的架构

不同于重量级的基于 transformer 的搜索引擎，Semble 旨在实现高速和本地执行。它完全在 CPU 上运行，无需 GPU、API 密钥或外部服务。

Semble 采用混合检索策略，以确保精确度和召回率兼顾：

代码感知分块：使用 Chonkie 库，Semble 将文件拆分为符合代码逻辑结构的块。
混合检索：它结合两种互补的方法：
- 语义搜索：利用静态 Model2Vec 嵌入（通过 potion-code-16M 模型）实现概念相似性。
- 词法搜索：使用 BM25 对标识符和 API 名称进行精确匹配。
互惠排名融合 (RRF)：来自两种检索器的结果被融合，以生成统一的排序。
代码感知重新排序：最终结果通过多种特定信号进行细化：
- 自适应加权：符号式查询（例如 getUserById）优先词法匹配，而自然语言查询则保持平衡。
- 定义提升：定义类或函数的块排名高于仅引用它们的块。
- 标识符词干化：查询词被词干化，以匹配如 parseConfig 和 ConfigParser 的变体。
- 噪声惩罚：测试文件、旧版 shim 和声明存根被降级，以首先展示规范实现。

Semble 的核心价值主张在于速度与准确性的结合。根据项目的基准测试，它在 NDCG@10 上达到 0.854，几乎与更大的 transformer 模型（如 CodeRankEmbed Hybrid）相同，但延迟显著更低。

索引速度：平均仓库的索引时间约为 ~250ms。
查询延迟：查询通常在 ~1.5ms 内完成。
令牌效率：项目报告称，Semble 仅使用 2k 令牌即可达到 94% 的召回率，而 grep+read 方法则需要 100k 的上下文窗口才能仅达到 85% 的召回率。

Semble 被设计为现代代理框架的“即插即用”工具。它可以通过两种主要方式集成：

对于支持 MCP 的代理（如 Claude Code、Cursor 或 Codex），Semble 可以作为服务器运行。这使得代理能够直接调用 search 和 find_related 工具。仓库按需克隆并索引，且本地路径会被监视以实现自动重新索引。

对于子代理或基于 CLI 的框架，Semble 可以添加到 AGENTS.md 或 CLAUDE.md 中。这指示代理使用 semble search "query" ./path 而不是依赖 grep。

虽然基准测试令人印象深刻，但 Hacker News 社区提出了若干关于语义搜索在代理工作流中实际应用的关键点。

一个重要的担忧是 LLM 是否真的会信任语义搜索工具的结果。正如用户 (@jerezzprime) 所指出的，许多模型在 grep 上进行了大量的强化学习调优。如果模型不信任语义结果，它仍可能执行 grep 或重新读取文件，从而抵消令牌节省。

不同于确定性的 grep，Semble 是概率性的。一些用户担心小型嵌入模型可能错过关键且晦涩的标识符，而字面字符串搜索可以立即发现这些标识符。

更具哲学性的批评认为，通过提供“捷径”工具，可能会削弱代理的认知能力。一些人认为，代理使用 tree 和 grep 导航代码库的能力是其推理过程的核心部分，用黑盒检索工具取代它可能导致在长期任务中“可部署智能”出现净负面影响。

尽管有这些批评，一些用户报告了积极的结果。用户 (@aadishv) 进行了一项对比测试，发现虽然非 Semble 版本有时更详细，但 Semble 版本在特定追踪任务中始终更具上下文效率和成本效益。

Semble 代表了向“代理原生”代码搜索的转变。通过摆脱读取整个文件的昂贵且不精确的过程，它使代理能够在更小的上下文占用下运行。尽管关于概率搜索是否能完全取代 grep 的确定性仍有争论，但巨大的令牌开销削减使 Semble 成为任何扩展 AI 驱动开发的有力工具。