MinishLab/semble

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 的開發工作流程的實用補充。