semtools

Semtools：语义搜索

使用基于嵌入的相似度匹配，对代码和文档执行语义（基于含义的）搜索。

用途

semtools 技能提供对 Semtools 的访问。Semtools 是一款基于 Rust 的高性能命令行工具，用于语义搜索和文档处理。与匹配精确字符串的传统文本搜索工具（ripgrep）或匹配语法模式的结构化搜索工具（ast-grep）不同，semtools 通过嵌入理解语义含义。

主要功能：

1. 语义搜索：根据含义而非仅凭关键词查找代码或文本
2. 工作区管理：为大型代码库建立索引，以便快速重复搜索
3. 文档解析：将 PDF、DOCX、PPTX 转换为可搜索文本（需要 API 密钥）

semtools 擅长发现——当你不知道确切的关键词、函数名称或语法模式时，查找相关代码。

何时使用此技能

当你需要基于含义的搜索时，请使用 semtools 技能：

语义代码发现：

• 查找实现某个概念的代码（“错误处理”“数据验证”）
• 发现不同模块中的相似功能
• 不知道确切名称时，查找某种模式的示例
• 无需通读所有代码即可了解其作用

文档与知识：

• 按概念而非关键词搜索文档
• 在注释或文档中查找相关讨论
• 发现相似的问题或解决方案
• 分析技术文档（PDF、报告）

使用场景：

• “查找所有与身份验证相关的代码”（无需知道函数名称）
• “展示错误处理模式”（不受具体错误类型限制）
• “查找与此实现相似的代码”（语义相似性）
• “在研究论文中搜索‘分布式共识’”（文档搜索）

以下情况优先使用 semtools，而非 file-search（ripgrep/ast-grep）：

• 你知道概念，但不知道关键词
• 精确字符串匹配会遗漏相关结果
• 你想查找语义相似的代码，而非精确匹配
• 需要跨语言或在混合内容中搜索

以下情况仍应使用 file-search：

• 你知道确切的关键词、函数名称或模式
• 需要进行结构化代码匹配（ast-grep）
• 速度至关重要（ripgrep 的精确匹配速度更快）
• 需要搜索特定符号或引用

可用命令

Semtools 提供三个可通过 execute_command 使用的命令行命令：

• search - 对代码和文本文件执行语义搜索
• workspace - 管理用于缓存嵌入的工作区
• parse - 将文档（PDF、DOCX、PPTX）转换为可搜索文本

**所有命令在你的执行环境中均可开箱即用。**文档解析需要设置 LLAMA_CLOUD_API_KEY 环境变量。

核心操作

1. 语义搜索（search）

按语义含义查找文件和代码片段：

# Basic semantic search
search "authentication logic" src/

# Search with more context (5 lines before/after)
search "error handling" --n-lines 5 src/

# Get more results (default: 3)
search "database queries" --top-k 10 src/

# Control similarity threshold (0.0-1.0, lower = more lenient)
search "API endpoints" --max-distance 0.4 src/

参数：

• --n-lines N：显示匹配项周围的 N 行上下文（默认值：3）
• --top-k K：返回相似度最高的 K 个匹配项（默认值：3）
• --max-distance D：最大嵌入距离（0.0-1.0，默认值：0.3）
• -i：不区分大小写匹配

输出格式：

Match 1 (similarity: 0.12)
File: src/auth/handlers.py
Lines: 42-47
----
def authenticate_user(username: str, password: str) -> Optional[User]:
    """Authenticate user credentials against database."""
    user = get_user_by_username(username)
    if user and verify_password(password, user.password_hash):
        return user
    return None
----

Match 2 (similarity: 0.18)
File: src/middleware/auth.py
...

2. 工作区管理（workspace）

对于大型代码库，可创建工作区来缓存嵌入，从而加快重复搜索：

# Create/activate workspace
workspace use my-project

# Set workspace via environment variable
export SEMTOOLS_WORKSPACE=my-project

# Index files in workspace (workspace auto-detected from env var)
search "query" src/

# Check workspace status
workspace status

# Clean up old workspaces
workspace prune

优势：

• 快速重复搜索：缓存嵌入，无需重新计算
• 大型代码库：使用 IVF_PQ 索引实现可扩展性
• 会话持久化：在多次搜索中保留上下文

适合使用工作区的情况：

• 多次搜索同一代码库
• 项目规模非常大（1000+ 个文件）
• 交互式探索会话
• 需要重复搜索的 CI/CD 管道

3. 文档解析（parse）⚠️ 需要 API 密钥

将文档转换为可搜索的 Markdown（需要 LlamaParse API 密钥）：

# Parse PDFs to markdown
parse research_papers/*.pdf

# Parse Word documents
parse reports/*.docx

# Parse presentations
parse slides/*.pptx

# Parse and pipe to search
parse docs/*.pdf | xargs search "neural networks"

支持的格式：

• PDF（.pdf）
• Word（.docx）
• PowerPoint（.pptx）

配置：

# Via environment variable
export LLAMA_CLOUD_API_KEY="llx-..."

# Via config file
cat > ~/.parse_config.json << EOF
{
  "api_key": "llx-...",
  "max_concurrent_requests": 10,
  "timeout_seconds": 3600
}
EOF

重要说明：文档解析为可选功能。无需文档解析也能使用语义搜索。

工作流模式

模式 1：概念发现

当你知道要找什么概念，但不知道它的名称时：

# Step 1: Broad semantic search
search "rate limiting implementation" src/

# Step 2: Review results, refine query
search "throttle requests per user" src/ --top-k 10

# Step 3: Use ripgrep for exact follow-up
rg "RateLimiter" --type py src/

模式 2：相似代码查找器

当你想查找与参考实现相似的代码时：

# Step 1: Extract key concepts from reference code
# [Read example_auth.py and identify key concepts]

# Step 2: Search for similar implementations
search "user authentication with JWT tokens" src/

# Step 3: Compare implementations
# [Review semantic matches to find similar approaches]

模式 3：文档搜索

当你要在文档或注释中研究概念时：

# Search code comments semantically
search "thread safety guarantees" src/ --n-lines 10

# Search markdown documentation
search "deployment best practices" docs/

# Combined search
search "performance optimization" --top-k 20

模式 4：跨语言搜索

当你要跨不同语言搜索概念时：

# Semantic search works across languages
search "connection pooling" src/

# May find:
# - Java: "ConnectionPool manager"
# - Python: "database connection reuse"
# - Go: "pool of persistent connections"
# All semantically related despite different terminology

模式 5：文档分析（需要 API 密钥）

当你要分析 PDF 或文档时：

# Step 1: Parse documents to markdown
parse research/*.pdf > papers.md

# Step 2: Search converted content
search "transformer architecture" papers.md

# Step 3: Combine with code search
search "attention mechanism implementation" src/

与 file-search 集成

Semtools 和 file-search（ripgrep/ast-grep）是互补工具。将它们结合使用，可实现全面搜索：

搜索策略矩阵

你知道什么	首先使用	然后使用	原因
确切关键词	ripgrep	search	快速精确匹配，然后查找相似内容
仅知道概念	search	ripgrep	找到相关代码，然后搜索具体内容
函数名称	ripgrep	search	找到定义，然后查找相似用法
代码模式	ast-grep	search	找到结构，然后查找相似逻辑
大致思路	search	ripgrep + ast-grep	先探索，再深入查找

分层搜索方法

# Layer 1: Semantic discovery (what's related?)
search "user session management" --top-k 10

# Layer 2: Exact text search (what's the implementation?)
rg "SessionManager|session_store" --type py

# Layer 3: Structural search (how is it used?)
sg --pattern 'session.$METHOD($$$)' --lang python

# Layer 4: Reference tracking (where is it called?)
# [Use serena skill for symbol-level tracking]

最佳实践

1. 先广泛搜索，再逐步缩小范围

使用语义搜索进行探索，然后用精确搜索缩小范围：

# GOOD: Broad semantic discovery first
search "authentication" src/ --top-k 10
# [Review results to learn terminology]
rg "authenticate|verify_credentials" --type py src/

# AVOID: Starting too narrow and missing variations
rg "authenticate" --type py  # Misses "verify_credentials", "check_auth", etc.

2. 调整相似度阈值

根据结果调整 --max-distance：

# Too many irrelevant results? Decrease distance (more strict)
search "query" --max-distance 0.2

# Missing relevant results? Increase distance (more lenient)
search "query" --max-distance 0.5

# Default (0.3) works well for most cases
search "query"

3. 重复搜索时使用工作区

进行交互式探索时，始终使用工作区：

# GOOD: Create workspace once, search many times
export SEMTOOLS_WORKSPACE=my-analysis
search "concept1" src/
search "concept2" src/
search "concept3" src/

# INEFFICIENT: Re-compute embeddings every time
search "concept1" src/
search "concept2" src/

4. 结合上下文工具

获取语义匹配结果的更多上下文：

# Find semantically similar code
search "retry logic" src/ --n-lines 2

# Get more context with ripgrep
rg -C 10 "retry" src/specific_file.py

# Or read the full file
cat src/specific_file.py

5. 使用概念表述查询

将查询写成概念，而非确切关键词：

# GOOD: Conceptual queries
search "handling network timeouts"
search "user input validation"
search "concurrent data access"

# LESS EFFECTIVE: Exact keyword queries (use ripgrep instead)
search "timeout"  # Use: rg "timeout"
search "validate"  # Use: rg "validate"

理解语义距离

Semtools 使用嵌入向量衡量语义相似度：

• 距离 0.0：含义相同
• 距离 0.1-0.2：非常相似（同义词、释义）
• 距离 0.2-0.3：相关概念（默认阈值）
• 距离 0.3-0.4：有一定关联
• 距离 0.5+：关联较弱或无关

实用指南：

# Strict matching (only close matches)
--max-distance 0.2

# Balanced matching (default, recommended)
--max-distance 0.3

# Lenient matching (exploratory search)
--max-distance 0.4

# Very lenient (may include false positives)
--max-distance 0.5

本地与云端嵌入

语义搜索（本地）：

• 使用本地嵌入（model2vec、potion-multilingual-128M）
• 不调用 API，也不依赖云服务
• 快速、私密、免费
• 可离线运行

文档解析（云端）：

• 使用 LlamaParse API（基于云端）
• 需要 API 密钥和互联网连接
• 处理 PDF、DOCX、PPTX
• 按使用量计费（请查看 LlamaIndex 定价）

**隐私注意事项：**语义搜索完全在本地进行。只有文档解析会将数据发送到 LlamaParse API。

性能注意事项

速度特征

不使用工作区时：

• 首次搜索：约 2-5 秒（计算嵌入）
• 后续搜索：每次约 2-5 秒（重新计算嵌入）

使用工作区（缓存的嵌入）时：

• 首次搜索：约 2-5 秒（构建索引）
• 后续搜索：约 0.1-0.5 秒（使用缓存）
• 大型代码库：使用 IVF_PQ 索引以提升可扩展性

对比：

• ripgrep：0.01-0.1 秒（最快，精确匹配）
• ast-grep：0.1-0.5 秒（快速，结构化）
• semtools（已缓存）：0.1-0.5 秒（快速，语义搜索）
• semtools（未缓存）：2-5 秒（较慢，语义搜索）

优化技巧

# 1. Use workspaces for repeated searches
export SEMTOOLS_WORKSPACE=my-project

# 2. Limit search scope to relevant directories
search "query" src/ --not tests/

# 3. Use --top-k to control result count
search "query" --top-k 5

# 4. Pipe to head for quick preview
search "query" | head -50

Unix 管道集成

Semtools 专为 Unix 风格的组合操作而设计：

# Find and parse PDFs, then search
find docs/ -name "*.pdf" | xargs parse | xargs search "topic"

# Search and filter with grep
search "authentication" src/ | grep -i "jwt"

# Count matches
search "error handling" src/ | grep "Match" | wc -l

# Combine with other tools
search "API" src/ | xargs -I {} rg -l "REST" {}

局限性

不适合使用 Semtools 的情况

1. 精确关键词搜索：已知关键词时使用 ripgrep

   # WRONG TOOL: Semantic search for exact function name
   search "authenticate_user"
   
   # RIGHT TOOL: Use ripgrep for exact matches
   rg "authenticate_user" --type py
   

2. 结构化代码模式：进行语法匹配时使用 ast-grep

   # WRONG TOOL: Semantic search for code structure
   search "class with constructor"
   
   # RIGHT TOOL: Use ast-grep for structure
   sg --pattern 'class $NAME { constructor($$$) { $$$ } }'
   

3. 符号引用：使用 serena 进行基于 LSP 的跟踪

   # WRONG TOOL: Semantic search for all usages
   search "MyClass usage"
   
   # RIGHT TOOL: Use serena for precise references
   serena find_referencing_symbols --name 'MyClass'
   

4. 小型代码库：对于少于 100 个文件的项目，额外开销不值得

   • 对于小型项目，ripgrep 更快、更简单

已知边缘情况

• 查询模糊：模糊的概念会返回范围较广的结果
• 技术术语：特定领域的术语准确率可能较低
• 代码片段较短：上下文有限会降低嵌入质量
• 混合语言：嵌入针对英语进行了优化（使用了多语言模型）
• 生成的代码：重复模式可能会聚集在一起

故障排除

未找到语义匹配项

如果语义搜索返回零条结果：

1. 确认文件存在：使用 ripgrep 确认内容

   rg "concept" src/
   

2. 提高相似度阈值：放宽要求

   search "query" --max-distance 0.5
   

3. 改写查询：尝试使用不同的术语

   search "user authentication"
   search "verify user credentials"
   search "login validation"
   

4. 检查文件类型：确保搜索了正确的扩展名

   search "query" src/*.py  # Target specific types
   

不相关结果过多

如果语义搜索返回了太多无关结果：

1. 降低相似度阈值：提高要求

   search "query" --max-distance 0.2
   

2. 限制结果数量：仅查看最匹配的结果

   search "query" --top-k 3
   

3. 缩小目录范围：搜索特定路径

   search "query" src/specific_module/
   

4. 优化查询：添加更具体的概念

   # Vague
   search "data"
   
   # Specific
   search "data validation with regex patterns"
   

文档解析失败

如果 parse 失败：

1. 确认已设置 API 密钥：

   echo $LLAMA_CLOUD_API_KEY
   

2. 检查文件格式：确保使用受支持的格式（PDF、DOCX、PPTX）

   file document.pdf  # Verify file type
   

3. 检查文件大小：大文件可能会导致超时

   du -h document.pdf  # Check size
   

4. 检查解析配置：根据需要调整超时时间

   cat ~/.parse_config.json
   

工作区问题

如果工作区命令失败：

# Check workspace status
workspace status

# Prune corrupted workspaces
workspace prune

# Recreate workspace
rm -rf ~/.semtools/workspaces/my-workspace
export SEMTOOLS_WORKSPACE=my-workspace

资源

• Semtools GitHub
• LlamaParse 文档
• model2vec 嵌入
• 语义搜索概念