AI 2026年5月31日 3 分钟阅读

Semble 实战指南：用 98% 更少 Token 为 AI Agent 实现精准代码搜索

tinyash 0 条评论

AI 编程 Agent（Claude Code、Cursor、Codex 等）在代码库中寻找信息时的默认做法是 grep+read——先 grep 找文件，再读完整文件内容。这在小型项目上勉强可行，但在大型代码库中，Agent 可能为了理解一个函数需要读取上千行无关代码，每次搜索消耗数万甚至数十万 Token。

Semble 正是为了解决这个问题而生的开源工具（MIT 协议，4580⭐）。它是一个专为 AI Agent 设计的代码搜索库，在保证高召回率的前提下，将 Token 消耗降低约 98%，而且全部在 CPU 上运行，不需要 GPU、不需要 API Key。

本文将从安装配置、MCP 集成、AGENTS.md 配置、CLI 使用到 Python 库集成，带你一步步掌握 Semble。

安装与快速启动

Semble 的安装非常简单，推荐使用 uv：

uv tool install semble

pip install semble

uv tool install "semble[mcp]"

安装完成后，直接在终端中搜索代码库：

semble search "authentication flow" ./my-project

semble search "save model to disk" https://github.com/MinishLab/model2vec

semble search "database connection pool" ./my-project --top-k 5

第一次搜索会自动建立索引。一个中型项目的索引构建仅需约 250 毫秒，后续搜索响应时间约 1.5 毫秒——真正的”眨眼即答”。

将 Semble 接入 AI Agent（三种方式）

方式一：MCP Server（推荐）

Semble 提供了官方的 MCP Server，只需一行命令即可接入：

Claude Code：

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

Cursor： 在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Codex： 在 ~/.codex/config.toml 中添加：

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

MCP Server 提供了两个工具：

工具功能
search用自然语言或代码片段搜索代码库
find_related根据文件路径和行号查找语义相似的代码

方式二：AGENTS.md / CLAUDE.md

如果不想用 MCP，可以在项目的 AGENTS.md 或 CLAUDE.md 中加入 Semble 的使用指引，让 Agent 在需要搜索代码时自动调用 CLI：

## Code Search

Use `semble search` to find code by describing what it does:

​```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
​```

`--content` 参数控制搜索范围：`code`（默认）、`docs`（文档）、`config`（配置文件）、`all`（全部）。

`semble find-related` 可以基于已知位置发现相关的代码实现：
​```bash
semble find-related src/auth.py 42 ./my-project
​```

方式三：Sub-agent

Semble 还提供了专用的子 Agent 配置，一键生成：

semble init                      # → .claude/agents/semble-search.md

semble init --agent gemini       # → .gemini/agents/semble-search.md

semble init --agent cursor       # → .cursor/agents/semble-search.md

semble init --agent opencode     # → .opencode/agents/semble-search.md

GitHub Copilot CLI 和 VS Code 集成

Semble 的 MCP Server 兼容几乎所有主流 MCP 客户端。以 GitHub Copilot CLI 为例，在 ~/.copilot/mcp-config.json 中添加：

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

VS Code 用户则在 .vscode/mcp.json 中添加：

{
  "servers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

高级用法

搜索不同类型的内容

Semble 默认只索引代码文件。如需搜索文档或配置文件：

semble search "deployment guide" ./my-project --content docs

semble search "database host port" ./my-project --content config

semble search "authentication" ./my-project --content all

使用 .sembleignore 文件

Semble 会读取 .gitignore 和 .sembleignore。如果你想排除某些文件但不影响 .gitignore，可以创建 .sembleignore：

generated/     # 排除生成目录
*.pb.go        # 排除 protobuf 生成的 Go 文件

如果要包含非默认扩展名的文件，使用 ! 前缀：

!*.proto       # 包含 Protobuf 文件
!*.cob         # 包含 COBOL 文件

Token 节省统计

想知道 Semble 到底帮你省了多少 Token？运行：

semble savings           # 按时间段汇总
semble savings --verbose # 按调用类型细分

输出示例：

  Semble Token Savings
  ═══════════════════════════════════════
  Period        Calls   Savings
  ───────────────────────────────────────
  Today         42      ~58.4k tokens (95%)
  Last 7 days   287     ~312.4k tokens (90%)
  All time      1.4k    ~1.2M tokens (89%)

Python 库模式

如果你想在自定义工具中集成 Semble：

from semble import ContentType, SembleIndex

index = SembleIndex.from_path("./my-project")

index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

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)

result = results[0]
print(result.chunk.file_path)    # "model2vec/model.py"
print(result.chunk.start_line)   # 127
print(result.chunk.end_line)     # 150

性能基准

Semble 的 README 中提供了详尽的基准测试数据。在 63 个代码库、19 种编程语言的约 1,250 个查询测试中：

  • NDCG@10: 0.854（检索质量指标，接近 137M 参数的 CodeRankEmbed 模型的 99%）
  • 索引速度: 比 CodeRankEmbed 快 218 倍
  • 查询速度: 比 CodeRankEmbed 快 约 10 倍
  • Token 节省: 平均减少 98% 的 Token 消耗
  • 召回率: 仅 2k Token 即可达到 94% 召回率；而 grep+read 需要 100k Token 才能达到 85%

Semble 通过 tree-sitter 做代码感知的智能分块，再用 Model2Vec 嵌入（code-specialized potion-code-16M 模型）做语义匹配 + BM25 做标识符精确匹配，最后用 Reciprocal Rank Fusion（RRF）合并两个检索结果。这种双引擎架构在精度和效率之间取得了出色的平衡。

实战技巧

  1. 不要放弃 grep 完全：Semble 不是 grep 的替代品，而是它的互补。对于精确字符串匹配（如需要确认某个确切的函数签名），grep 仍然是最快的方式。Semble 擅长的是自然语言语义搜索——当你”描述”想找什么而不是”输入”具体字符时。
  1. 从浅到深的搜索策略：先用 semble search 获取相关代码片段，只在这些片段不够用时才用 read 读取完整文件。这种”先片段后全文”的策略正是 98% Token 节省的来源。
  1. 定期查看 savings：semble savings 不仅是一个趣味功能，它也能帮你评估自己的 Agent 使用效率——如果 Token 节省率持续低于 80%，可能说明你的 Agent 仍然过度依赖 grep，可以考虑在 AGENTS.md 中强化 Semble 的优先级。
  1. 与 MCP 配合的最佳实践：在 AGENTS.md 中同时配置 CLI 说明和 MCP Server 说明。这样即使 Agent 的 MCP 功能暂时不可用，CLI 说明仍可作为后备方案。

总结

Semble 解决了一个真实且广泛存在的痛点：AI Agent 在代码库中搜索信息时的 Token 浪费。通过智能分块、语义匹配和双引擎融合，它在保持高精度的同时将 Token 消耗降低了一个数量级。最重要的是——零 API 费用、零 GPU 需求、纯 CPU 运行，任何人都可以立即上手。

对于每天都和 AI 编程助手打交道的开发者来说，Semble 是一个让 Agent 更省 Token、同时提供更精准代码搜索体验的利器。无论你是 Claude Code、Cursor、Codex 还是 Copilot 的用户，花 5 分钟配置好 Semble，Agent 的代码搜索效率就会有质的提升。

参考链接： – Semble GitHub 仓库（4580⭐ | MIT 协议） – PyPI 包 – HN 讨论

AI AI Tools LLM 开发工具 开源 教程

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。