MinishLab/semble
Fast and Accurate Code Search for Agents. Uses 99% fewer tokens than grep+read
Semble – 面向 AI 编码代理的快速、高 Token 效率代码搜索
是什么 – Semble 是一个 Python 库 / CLI / MCP 兼容服务器，让基于大语言模型的编码助手（Claude Code、Cursor、Codex、OpenCode 等）能够从代码库中精准检索所需代码片段。它相比简单的「grep + 读取完整文件」方法，节省约 99% 的 Token，同时检索质量与 1.37 亿参数的专用代码 Transformer 模型相当。
为何重要 – 代理经常需要探索陌生的代码库。将整个文件拉入模型上下文成本高且缓慢。Semble 在约 0.5 秒内完成代码库索引，CPU 上自然语言查询响应时间约 1 毫秒，使代理能立即获取相关代码片段，无需任何 API 密钥、GPU 或外部服务。
主要特性
- 速度 – 平均代码库索引时间约 500 毫秒；查询延迟约 1 毫秒（仅 CPU）。相比同类 Transformer 基础检索器，索引速度提升 340 倍，查询速度提升 17 倍。
- 准确性 – 在作者的基准测试中，NDCG@10 = 0.854，与 1.37 亿参数模型性能相当。
- Token 效率 – 仅返回所需代码片段，相比读取完整文件节省约 99% 的 Token。
- 零配置 – 无需 GPU，无需 API 密钥，仅需
pip/uv安装即可使用。 - MCP 服务器 – 作为原生工具暴露
search和find_related，供任何 MCP 兼容代理调用。 - 本地与远程仓库 – 支持文件系统路径或 Git URL。
- 细粒度控制 – 通过
.gitignore和专用的.sembleignore文件，可选择性包含或排除文件和扩展名。 - 缓存与统计 – 索引和 Token 节省统计信息被缓存；
semble savings可查看已避免的 Token 数量。
快速开始（CLI）
# 安装工具（需 uv）
uv tool install semble
semble install # 交互式安装 – 选择代理和集成类型
# 在本地仓库中进行基本搜索
semble search "authentication flow" ./my-project
# 搜索远程仓库（按需克隆）
semble search "save model to disk" https://github.com/MinishLab/model2vec
# 限制结果数量、仅显示少量代码行，或搜索文档/配置
semble search "deployment guide" ./my-project --content docs --top-k 5 --max-snippet-lines 10
使用 semble uninstall 移除集成，或 semble clear ... 清除缓存。
作为 Python 库使用
from semble import ContentType, SembleIndex
# 构建索引（首次使用时缓存）
idx = SembleIndex.from_path("./my-project", content=ContentType.CODE)
# 或包含文档/配置
# idx = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])
# 自然语言或代码查询
results = idx.search("save model to disk", top_k=3)
for r in results:
print(r.chunk.file_path, r.chunk.start_line, r.chunk.content[:120])
# 查找与某位置相似的代码
related = idx.find_related(results[0], top_k=3)
该库适用于构建自定义工具，或直接嵌入到您自己的应用程序中。
MCP 服务器模式
作为 MCP 工具安装后，代理可调用：
| 工具 | 描述 |
|---|---|
search |
在本地路径或 Git URL 的仓库上执行自然语言或代码查询。 |
find_related |
给定文件路径和行号，返回语义上相似的代码块。 |
安装说明见 docs/installation.md#mcp-server。 |
内部工作原理
- 分块 – 使用 tree-sitter 将文件分割为代码感知的代码块。
- 双检索器 –
- Model2Vec 静态嵌入（potion-code-16M-v2）提供语义相似性。
- BM25 提供对标识符和 API 名称的快速词法匹配。
- 融合 – 两个检索器的得分通过 Reciprocal Rank Fusion 进行融合。
- 重排序 – 采用自适应加权、定义优先级、标识符词干匹配、文件连贯性奖励和噪声惩罚，优化最终排序。
- 缓存 – 索引存储在磁盘上；文件变更时进行增量更新，避免完全重建。
- 模型灵活性 – 可通过设置
SEMBLE_MODEL_NAME指向自定义 Model2Vec 模型。
所有操作在单个 CPU 核心上以毫秒级完成，因为嵌入模型是静态的（查询时无需 Transformer 前向传播）。
基准测试（报告结果）
- 质量 – 在 63 个仓库、19 种语言上，NDCG@10 = 0.854，与 1.37 亿参数的 CodeRankEmbed 模型相当。
- 速度 – 索引速度比 Transformer 基线快 340 倍，查询速度快 17 倍。
- Token 节省 – 比 grep+read 基线节省约 99% 的 Token；在 2k Token 时系统达到 97% 召回率，而 grep+read 需要约 10 万 Token 才能达到 85% 召回率。
完整基准详情见
benchmarks/README.md。
安装与缓存位置
- 通过 uv（
uv tool install semble）或pip install semble安装。 - 缓存目录默认为操作系统缓存位置（Linux 上为
~/.cache/semble等）。可通过SEMBLE_CACHE_LOCATION覆盖。 - 模型文件缓存于标准 Hugging-Face 缓存目录（
~/.cache/huggingface）。 - 默认跳过大于 1 MiB 的文件；可通过
SEMBLE_MAX_FILE_BYTES调整。
许可证与引用
- 许可证：MIT（宽松，允许商业使用）。
- 引用：学术用途请使用提供的 BibTeX 条目（Zenodo DOI 10.5281/zenodo.19785932）。
总结
Semble 为 AI 编码助手提供了一种本地化、快速且 Token 成本低廉的代码检索方式，彻底消除对昂贵 API 调用或大上下文窗口的需求。它开箱即用，支持 CLI、Python 库或 MCP 服务器模式，是任何基于 LLM 的开发工作流的实用补充。
相关
- Dispatch
- 项目
- 项目
- 项目