文档
用户指南
Python SDK

Python SDK

Sirchmunk 提供 Python SDK，用于以编程方式访问其智能搜索能力。

安装

pip install sirchmunk

基本用法

import asyncio
from sirchmunk import AgenticSearch
from sirchmunk.llm import OpenAIChat

# 初始化 LLM 接口
llm = OpenAIChat(
    api_key="your-api-key",
    base_url="your-base-url",   # 如 https://api.openai.com/v1
    model="your-model-name"     # 如 gpt-5.2
)

async def main():
    searcher = AgenticSearch(llm=llm)

    # DEEP 模式（默认）：富文本 Markdown 报告，预算约束证据探索
    result: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
    )

    # FAST 模式：贪心搜索，2 次 LLM 调用，2-5s
    result_fast: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
        mode="FAST",
    )

    print(result)

asyncio.run(main())
警告

初始化时，AgenticSearch 会自动检查 ripgrep-all 和 ripgrep 是否已安装。如果缺失，系统会尝试自动安装。如果自动安装失败，请手动安装：

搜索参数

result = await searcher.search(
    query="database connection pooling",        # 必填：搜索问题
    paths=["/path/to/project/src"],             # 可选：省略时回退到 SIRCHMUNK_SEARCH_PATHS → cwd
    mode="DEEP",                                # DEEP（默认）、FAST 或 FILENAME_ONLY
    max_depth=10,                               # 最大目录深度
    top_k_files=20,                             # 最大文件数
    max_loops=10,                               # ReAct 最大迭代次数（DEEP 模式）
    include_patterns=["*.py", "*.java"],        # 要包含的文件模式
    exclude_patterns=["*test*", "*__pycache__*"], # 要排除的文件模式
    response_format="context",                   # 返回格式：rich、minimal、context、json
)

访问结果

基本结果

# 结果是格式化的 Markdown 字符串
result = await searcher.search(query="...", paths=["..."])
print(result)

含 SearchContext

# 获取完整的 SearchContext 对象
result = await searcher.search(
    query="...",
    paths=["..."],
    response_format="context",
)

# 访问上下文元数据
print(result.cluster_id)
print(result.confidence)
print(result.lifecycle_state)
print(result.evidence_units)

LLM 使用量跟踪

# 搜索完成后
for usage in searcher.llm_usages:
    print(f"提示词 Token: {usage.prompt_tokens}")
    print(f"补全 Token: {usage.completion_tokens}")
    print(f"总 Token: {usage.total_tokens}")

LLM 供应商兼容性

Sirchmunk 适用于任何 OpenAI 兼容的 API 端点：

  • OpenAI — GPT-4o、GPT-5.2
  • MiniMax — MiniMax-M3、MiniMax-M2.7、MiniMax-M2.7-highspeed
  • DeepSeek — DeepSeek-V3、DeepSeek-R1 及其他 DeepSeek 对话模型
  • Google Gemini、智谱（GLM）、百川、零一万物、硅基流动、火山引擎
  • Moonshot、Mistral、Groq、Together AI、Cohere
  • Azure OpenAI
  • 本地模型 — Ollama、llama.cpp、vLLM、SGLang
  • Claude — 通过 API 代理
  • 其他供应商 — 提供 OpenAI 兼容 HTTP API 的服务商
# 示例：使用本地 Ollama 模型
llm = OpenAIChat(
    api_key="ollama",
    base_url="http://localhost:11434/v1",
    model="llama3"
)

# 示例：使用自定义端点
llm = OpenAIChat(
    api_key="your-key",
    base_url="https://your-custom-endpoint.com/v1",
    model="your-model"
)
docs