Semble

在 AI 代理（Agent）辅助编程日益普及的今天，传统的 grep 或全量读取文件方式不仅延迟高，更会消耗巨额 Token 成本，且往往返回大量无关噪音。Semble是一个专为 AI Agent 构建的代码搜索库，它能在 CPU 上以毫秒级速度完成整个代码库的索引与搜索，相比传统方法减少约 98% 的 Token 消耗，同时保留与昂贵代码专用 Transformer 模型相当的 99% 检索质量。

Semble 采用创新的静态 Model2Vec 嵌入与混合检索策略，无需 GPU、API Key 或外部服务，即可为 Claude Code、Cursor、Codex 等任何 MCP 兼容代理提供即时、精准的代码上下文。它是构建高效、低成本 AI 编程助手的理想基石。

核心亮点：极速轻量、混合检索、MCP 原生

1. 极致性能，CPU 即可运行

• 毫秒级响应：索引一个典型仓库仅需约 250 毫秒，单次查询耗时约 1.5 毫秒。
• 零硬件门槛：完全在 CPU 上运行，无需 GPU 加速，无需云端 API 调用，保护隐私且降低成本。
• 超高效率：索引速度比代码专用 Transformer 快 200 倍，查询速度快 10 倍，大幅缩短 Agent 的思考与执行循环。

2. 混合检索与代码感知重排序

• 双路召回：
  • 语义检索：使用轻量级静态模型 potion-code-16M (Model2Vec) 捕捉代码语义相似性。
  • 词法检索：结合 BM25 算法，确保标识符、API 名称的精确匹配。
• 智能重排序：通过倒数排名融合（RRF）初步合并结果，再应用一套代码感知信号进行精细化重排：
  • 自适应加权：自动识别查询类型，符号类查询增加词法权重，自然语言查询保持平衡。
  • 定义提升：优先返回符号的定义处，而非仅引用处，提供更核心的上下文。
  • 标识符词干匹配：提取查询令牌词干，增强对变量命名变体的包容性。
  • 文件一致性：当同一文件多个块匹配时，提升该文件整体排名，保持上下文连贯。
  • 噪声惩罚：自动降权测试文件、遗留桩代码、示例代码及 .d.ts 存根，减少干扰。

3. MCP 原生支持，即插即用

• MCP 服务器模式：可作为标准 Model Context Protocol (MCP) 服务器运行，无缝集成到 Claude Code、Cursor、Codex、OpenCode 等主流 AI 代理中。
• 按需索引：支持即时克隆并索引任意远程 Git 仓库或本地路径，索引结果在会话期间缓存，避免重复计算。
• 零配置部署：无需复杂的环境变量或密钥管理，pip install 后即可立即使用。

4. 极致节省 Token 成本

• 精准片段返回：仅返回 Agent 真正需要的代码块（含文件路径、行号、内容），避免全文件读取带来的 Token 浪费。
• 成本对比：相比传统的 grep + read 模式，Token 消耗降低约 98%，显著提升 Agent 的运行经济性与上下文窗口利用率。

快速开始

1. 安装 Semble

pip install semble
# 或使用 uv
uv add semble

2. Python API 使用

from semble import SembleIndex

# 索引本地目录
index = SembleIndex.from_path("./my-project")

# 或索引远程 Git 仓库（自动克隆并缓存）
# index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# 使用自然语言或代码查询进行搜索
results = index.search("save model to disk", top_k=3)

# 查找与特定结果相似的代码
related = index.find_related(results[0], top_k=3)

# 访问结果详情
for result in results:
    print(f"File: {result.chunk.file_path}")
    print(f"Lines: {result.chunk.start_line}-{result.chunk.end_line}")
    print(f"Content:\n{result.chunk.content}\n---")

3. 作为 MCP 服务器运行

将 Semble 配置为 MCP 服务器后，Claude Code、Cursor 等代理即可通过工具调用直接搜索代码：

# 启动 MCP 服务器（具体命令视集成方式而定，通常由宿主 Agent 管理）
python -m semble.mcp_server

在 Agent 配置中添加 Semble MCP 服务器连接，即可在对话中自然触发代码搜索，如：“帮我找找项目中保存模型的代码在哪里？”

技术架构详解

1. 代码分块 (Chunking)：使用 Chonkie 进行代码感知的智能分块，保持函数/类的完整性。
2. 嵌入生成 (Embedding)：采用静态 potion-code-16M Model2Vec 模型，预计算所有块的向量，查询时无需实时推理。
3. 混合检索 (Hybrid Retrieval)：
   • Semantic Search：向量相似度匹配。
   • Lexical Search：BM25 关键词匹配。
4. 重排序 (Re-ranking)：
   • RRF Fusion：融合两路得分。
   • Code-Aware Signals：应用自适应加权、定义提升、词干匹配、文件一致性、噪声惩罚等规则，优化最终排名。

Semble 证明了在代码搜索领域，“快”与“准”并非不可兼得。通过巧妙的静态嵌入与混合检索设计，它在极低的资源消耗下实现了媲美大型 Transformer 模型的检索质量，为 AI Agent 的规模化应用扫清了关键障碍。