# sirchmunk
**Repository Path**: lzdn/sirchmunk
## Basic Information
- **Project Name**: sirchmunk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-20
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Sirchmunk：无需向量数据库和预索引的自进化搜索引擎
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://nextjs.org/)
[](https://tailwindcss.com/)
[](https://duckdb.org/)
[](LICENSE)
[](https://github.com/phiresky/ripgrep-all)
[](https://github.com/openai/openai-python)
[](https://github.com/kreuzberg-dev/kreuzberg)
[](https://github.com/modelcontextprotocol/python-sdk)
📖 **[官方文档](https://modelscope.github.io/sirchmunk-web/zh/)**
[**快速开始**](#-快速开始) · [**核心特性**](#-核心特性) · [**MCP 服务器**](#-mcp-服务器) · [**Web UI**](#️-web-ui) · [**Docker 部署**](#-docker-部署) · [**工作原理**](#️-工作原理) · [**FAQ**](#-faq)
🔍 **智能体搜索** • 🧠 **知识聚类** • 📊 **蒙特卡洛证据采样**
⚡ **无索引检索** • 🔄 **自进化知识库** • 💬 **实时对话**
[English](README.md) | [中文](README_zh.md)
---
## 🌰 为什么选择 “Sirchmunk”？
基于向量检索的智能流水线往往 _僵硬且脆弱_。它们依赖静态向量嵌入，**计算成本高、对实时变化不敏感，并且脱离原始上下文**。我们引入 **Sirchmunk**，开启更敏捷的范式：数据不再是静态的快照和分块，而是直接从原始数据中洞见所查。
---
## ✨ 核心特性
### 1. 无需向量数据库和预索引：直接面向原始数据形态
**Sirchmunk** 直接处理 **原始数据** —— 无需将大量而繁杂的文件压缩为固定维度向量，或是构建为图数据库。
* **即开即用搜索：** 不再需要复杂、耗时的预处理与索引；直接添加文件即可检索。
* **全量保真：** 零信息损失，避免向量近似带来的偏差。
### 2. 自进化：实时动态索引
数据是流动的，而非静态快照。**Sirchmunk** 天然具备动态特性。相比之下，向量数据库可能在数据变化的瞬间就过时。
* **上下文感知：** 随数据上下文实时演化。
* **LLM 自主驱动：** 面向智能体设计，通过精心设计的上下文检索技术，仅在必要时触发LLM推理，提高Token使用效率，兼顾智能与成本。
### 3. 规模化：实时与海量数据支持
**Sirchmunk** 具备 **高吞吐** 与 **实时感知** 的特性，能够高效处理本地大型数据集和文件系统。
> 更多技术细节，参考 [Sirchmunk blog](https://modelscope.github.io/sirchmunk-web/zh/blog/).
---
### 传统 RAG vs. Sirchmunk
| 维度 |
传统 RAG |
✨Sirchmunk |
| 💰 搭建成本 |
高开销
（VectorDB、GraphDB、复杂文档解析器...） |
✅ 零基础设施
直接面向数据检索，无向量孤岛
|
| 🕒 数据新鲜度 |
滞后（批量重建索引） |
✅ 即时 & 动态
自进化索引反映实时变化
|
| 📈 可扩展性 |
线性成本增长 |
✅ 极低 RAM/CPU 占用
原生弹性支持，高效处理大规模数据集
|
| 🎯 准确性 |
近似向量匹配 |
✅ 确定性 & 上下文相关
混合逻辑确保语义精度
|
| ⚙️ 工作流 |
复杂 ETL 流水线 |
✅ 直接检索
零配置集成，快速部署
|
---
## 演示
---
| 微信群 | 钉钉群 |
|:--------:|:--------:|
| 
| 
|
---
## 🎉 News
* 🚀 **2026年4月13日**: Sirchmunk v0.0.7
- **C/S 部署加固**：远程模式下严格的 `allowed_paths` 路径约束与符号链接检测；按 IP 速率限制与 JSON Lines 审计日志；本地模式保持向后兼容。
- **远程文件上传**：三种上传模式（选择文件 / 选择文件夹 / 拖拽上传）；服务端上传前重复检测，支持跳过/覆盖；基于 manifest 的存储统计。
- **服务端文件浏览**：`FileBrowser` 默认打开服务端 `data/` 目录；手动路径输入校验 `allowed_paths`；远程访问的权限感知错误提示。
- **Init 对齐**：`sirchmunk init` 生成与 `config/env.example` 完全对齐的 `.env`，覆盖所有 C/S 部署变量。
* 🚀 **2026年3月31日**: Sirchmunk v0.0.6post3
- **Docker 多架构支持**：通过 Docker Buildx 原生构建 `linux/amd64` 和 `linux/arm64` 镜像；CI 自动构建双架构。
- **FAST 模式优化**：`_fast_find_best_file` 新增文件级去重与动态分数剪枝；知识集群复用增加搜索范围感知。
* 🚀 **2026年3月20日**: Sirchmunk v0.0.6post1
- **🐿️x🦞OpenClaw 技能**：Sirchmunk 已发布为 [OpenClaw](https://openclaw.org/) 技能，上架 [ClawHub](https://clawhub.ai/wangxingjun778/sirchmunk) — 任何兼容 OpenClaw 的 AI Agent均可通过自然语言搜索本地文件。详见 [openclaw-recipe](recipes/openclaw_skills/README.md)。
- **Search API**：新增 SSE 流式端点（`POST /api/v1/search/stream`），支持实时日志输出；通过 `SIRCHMUNK_MAX_CONCURRENT_SEARCHES` 控制并发；`paths` 参数同时支持字符串和数组，且为可选（回退到 `SIRCHMUNK_SEARCH_PATHS`）。
- **依赖修复**：`sirchmunk serve` 不再要求安装 `sirchmunk[web]` — `uvicorn` 已纳入核心依赖；`psutil` 改为可选。
* 🚀 **2026年3月12日**: Sirchmunk v0.0.6
- **多轮对话**：上下文管理与 LLM 查询重写；配置项 `CHAT_HISTORY_MAX_TURNS` / `CHAT_HISTORY_MAX_TOKENS`；搜索默认 token 预算 128K
- **文档摘要与跨语言检索**：摘要流水线（分块/合并/重排）、跨语言关键词提取、聊天历史相关性过滤
- **Docker**：支持 `SIRCHMUNK_SEARCH_PATHS` 环境变量；更新 entrypoint；文档处理依赖
- **OpenAI 客户端**：`_ProviderProfile` 多提供商管理；按 `base_url` 自动检测；统一流式处理；支持 `thinking_content`
历史版本（v0.0.2 – v0.0.5）
* 🚀 **2026.3.5**: **Sirchmunk v0.0.5 发布**
- **破坏性变更**：统一搜索 API：重构 search() 接口的返回类型，引入 SearchContext 对象并简化返回参数控制，API 调用更简洁。
- **高可用 RAG 对话**：引入重试机制与细粒度异常处理，大幅提升了 RAG 聊天在复杂网络环境下的稳定性。
- **稳定 MCP 集成**：修复 mcp run 初始化问题，确保 MCP 协议服务器在各环境下均能顺畅启动。
- **PyPI 安装修复**：解决了标准 pip 安装后的 Web 源码定位问题，确保 Web UI 即装即用。
* 🚀 **2026.2.27**: **Sirchmunk v0.0.4 发布**
- **Docker 部署支持**：提供预构建 Docker 镜像，支持容器化一键部署。
- **FAST 检索模式**：新增默认贪心搜索模式，采用两级关键词级联与上下文窗口采样策略，仅需 2 次 LLM 调用（2-5s vs 10-30s），大幅提升检索速度。
- **简化部署链路**：精简命令行与 Web 端的部署和配置流程，降低上手门槛。
- **Windows 兼容性修复**：修复 Windows 环境下的兼容性问题。
* 🚀 **2026.2.12**: **Sirchmunk v0.0.3 发布：核心搜索算法与 MCP 集成双升级**
- **MCP 增强**：深度优化 Model Context Protocol 集成及配置文档。
- **搜索精细化**：搜索工具支持 Glob 模式过滤，默认自动排除缓存与日志文件。
- **算法文档**：新增“蒙特卡洛证据采样”与“自进化知识簇”核心原理深度解析。
- **架构稳定性**：重构搜索管线（AgenticSearch.search），引入 SHA256 确定性 ID 确保知识簇一致性。
* 🚀 **2026.2.5**: 发布 **v0.0.2** — MCP 支持、CLI 命令行 & 知识持久化！
- **MCP 集成**：完整支持 [Model Context Protocol](https://modelcontextprotocol.io)，与 Claude Desktop 和 Cursor IDE 无缝协作。
- **CLI 命令行**：全新 `sirchmunk` 命令行工具，支持 `init`、`serve`、`search`、`web` 和 `mcp` 命令。
- **KnowledgeCluster 持久化**：基于 DuckDB 存储，支持 Parquet 导出，高效管理知识聚类。
- **知识复用**：基于语义相似度的知识聚类检索，通过 embedding 向量加速搜索。
* 🎉🎉 2026.1.22: **Sirchmunk** 初始版本 v0.0.1 现已发布！
---
## 🚀 快速开始
### 前置条件
- **Python** 3.10+
- **LLM API Key**（OpenAI 兼容 Endpoint，本地或远程）
- **Node.js** 18+（可选，用于 Web 界面）
### 安装
```bash
# 创建虚拟环境（推荐）
conda create -n sirchmunk python=3.13 -y && conda activate sirchmunk
pip install sirchmunk
# 或使用 UV：
uv pip install sirchmunk
# 或从源码安装：
git clone https://github.com/modelscope/sirchmunk.git && cd sirchmunk
pip install -e .
```
### Python SDK 使用
```python
import asyncio
from sirchmunk import AgenticSearch
from sirchmunk.llm import OpenAIChat
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():
agent_search = AgenticSearch(llm=llm)
# FAST 模式（默认）：贪心搜索，2 次 LLM 调用，2-5s
result: str = await agent_search.search(
query="How does transformer attention work?",
paths=["/path/to/documents"],
)
# DEEP 模式：全面分析，蒙特卡洛证据采样，10-30s
result_deep: str = await agent_search.search(
query="How does transformer attention work?",
paths=["/path/to/documents"],
mode="DEEP",
)
print(result)
asyncio.run(main())
```
**⚠️ 注意：**
- 初始化时，AgenticSearch 会自动检查是否安装 ripgrep-all 和 ripgrep。如缺失，会尝试自动安装。若自动安装失败，请手动安装。
- 参考：https://github.com/BurntSushi/ripgrep | https://github.com/phiresky/ripgrep-all
- 将 `"your-api-key"`、`"your-base-url"`、`"your-model-name"` 和 `/path/to/documents` 替换为实际值。
使用 MiniMax
```python
from sirchmunk.llm import OpenAIChat
llm = OpenAIChat(
api_key="your-minimax-api-key",
base_url="https://api.minimax.io/v1", # 海外版
# base_url="https://api.minimaxi.com/v1", # 国内版
model="MiniMax-M2.7" # 或 "MiniMax-M2.7-highspeed"
)
```
### 命令行界面
Sirchmunk 提供强大的 CLI，用于服务器管理和搜索操作。
#### 安装
```bash
pip install "sirchmunk[web]"
# 或使用UV安装
uv pip install "sirchmunk[web]"
```
#### 初始化
```bash
# 使用默认设置初始化 Sirchmunk，默认工作路径为 `~/.sirchmunk/`
sirchmunk init
# 或者，也可以使用自定义工作路径初始化
sirchmunk init --work-path /path/to/workspace
```
#### 启动服务器
```bash
# 仅启动后端 API 服务器
sirchmunk serve
# 自定义主机和端口
sirchmunk serve --host 0.0.0.0 --port 8000
```
#### 搜索
```bash
# 在当前目录搜索（默认 FAST 模式）
sirchmunk search "认证是如何工作的？"
# 在指定路径搜索
sirchmunk search "查找所有 API 端点" ./src ./docs
# DEEP 模式：蒙特卡洛证据采样全面分析
sirchmunk search "数据库架构" --mode DEEP
# 快速文件名搜索
sirchmunk search "config" --mode FILENAME_ONLY
# 输出为 JSON 格式
sirchmunk search "数据库模式" --output json
# 通过 API 服务器搜索（需要先启动服务器）
sirchmunk search "查询" --api --api-url http://localhost:8584
```
#### 可用命令
| 命令 | 说明 |
|------|------|
| `sirchmunk init` | 初始化工作目录、.env 及 MCP 配置 |
| `sirchmunk serve` | 仅启动后端 API 服务器 |
| `sirchmunk search` | 执行搜索查询 |
| `sirchmunk web init` | 构建 WebUI 前端（需要 Node.js 18+） |
| `sirchmunk web serve` | 启动 API + WebUI（单端口） |
| `sirchmunk web serve --dev` | 开发模式，Next.js 热重载 |
| `sirchmunk mcp serve` | 启动 MCP 服务器（stdio/HTTP） |
| `sirchmunk mcp version` | 显示 MCP 版本信息 |
| `sirchmunk version` | 显示版本信息 |
---
## 🔌 MCP 服务器
Sirchmunk 提供 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，将其智能搜索能力作为 MCP 工具暴露。可与 **Claude Desktop** 和 **Cursor IDE** 等 AI 助手无缝集成。
### 快速开始
```bash
# 安装（含 MCP 支持）
pip install sirchmunk[mcp]
# 初始化（生成 .env 和 mcp_config.json）
sirchmunk init
# 可选：使用自定义工作目录
# sirchmunk init --work-path /path/to/your_work_path
# 编辑 ~/.sirchmunk/.env 配置 LLM API Key
# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector sirchmunk mcp serve
# 可选：本次 MCP 运行使用自定义工作目录
# npx @modelcontextprotocol/inspector sirchmunk mcp serve --work-path /path/to/your_work_path
```
### `mcp_config.json` 配置
运行 `sirchmunk init` 后会生成 `~/.sirchmunk/mcp_config.json` 文件。将其复制到你的 MCP 客户端配置目录即可。
**示例：**
```json
{
"mcpServers": {
"sirchmunk": {
"command": "sirchmunk",
"args": ["mcp", "serve"],
"env": {
"SIRCHMUNK_SEARCH_PATHS": "",
"SIRCHMUNK_WORK_PATH": "/path/to/your_work_path"
}
}
}
}
```
| 参数 | 说明 |
|---|---|
| `command` | 启动 MCP 服务器的命令。如果在虚拟环境中运行，请使用完整路径（如 `/path/to/venv/bin/sirchmunk`）。 |
| `args` | 命令参数。`["mcp", "serve"]` 以 stdio 模式启动 MCP 服务器。 |
| `env.SIRCHMUNK_SEARCH_PATHS` | 默认文档搜索目录（逗号分隔）。同时支持英文逗号 `,` 和中文逗号 `，` 作为分隔符。设置后，若工具调用时未提供 `paths` 参数，将使用这些路径作为默认值。 |
| `env.SIRCHMUNK_WORK_PATH` | 指定 MCP 服务器使用的 Sirchmunk 工作目录（`.env`、缓存、知识库、历史记录）。推荐在持久化 MCP 客户端中配置。 |
> **提示**：MCP Inspector 非常适合在连接 AI 助手之前测试集成是否正常。
> 在 MCP Inspector 中：**Connect** → **Tools** → **List Tools** → `sirchmunk_search` → 输入参数（`query` 和 `paths`，如 `["/path/to/your_docs"]`）→ **Run Tool**。
> 也可通过 `sirchmunk mcp serve --work-path /path/to/your_work_path` 临时覆盖工作目录。
### 特性
- **多模式搜索**：FAST 模式（默认，贪心搜索 2-5s）、DEEP 模式（全面分析 10-30s）、FILENAME_ONLY 模式（快速文件发现）
- **知识聚类管理**：自动提取、存储和复用知识
- **标准 MCP 协议**：支持 stdio 和 Streamable HTTP 传输
📖 **详细文档请参阅 [Sirchmunk MCP README](src/sirchmunk_mcp/README.md)**。
---
## 🖥️ Web UI
Web UI 专为快速、透明的工作流设计：对话、知识分析、系统监控一体化。
Home — 流式日志聊天、基于文件的 RAG 与会话管理。
Monitor — 系统健康、聊天活动、知识分析与 LLM 用量。
### 方式一：单端口模式（推荐）
一次构建前端，随后通过单端口同时提供 API 和 WebUI — 运行时无需 Node.js。
```bash
# 构建 WebUI 前端（构建时需要 Node.js 18+）
sirchmunk web init
# 启动含内嵌 WebUI 的服务器
sirchmunk web serve
```
**访问地址：** http://localhost:8584（API + WebUI 同端口）
### 方式二：开发模式
支持前端热重载的开发环境：
```bash
# 启动后端 + Next.js 开发服务器
sirchmunk web serve --dev
```
**访问地址：**
- 前端（热重载）：http://localhost:8585
- 后端 API：http://localhost:8584/docs
### 方式三：传统脚本
```bash
# 通过脚本启动前后端
python scripts/start_web.py
# 停止所有服务
python scripts/stop_web.py
```
**配置：**
- 访问 `Settings` → `Envrionment Variables` 设置 LLM API Key 和其他环境变量
---
## 🐳 Docker 部署
预构建的 Docker 镜像托管在阿里云容器镜像服务：
| 区域 | 镜像 |
|---|---------------------------------------------------------------------------------------------------------|
| 美西 | `modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7` |
| 北京 | `modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7` |
```bash
# 拉取镜像（根据地理位置选择最近的 Registry）
docker pull modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7
# 启动服务
docker run -d \
--name sirchmunk \
--cpus="4" \
--memory="2g" \
-p 8584:8584 \
-e LLM_API_KEY="your-api-key-here" \
-e LLM_BASE_URL="https://api.openai.com/v1" \
-e LLM_MODEL_NAME="gpt-5.2" \
-e LLM_TIMEOUT=60.0 \
-e UI_THEME=light \
-e UI_LANGUAGE=en \
-e SIRCHMUNK_VERBOSE=false \
-e SIRCHMUNK_ENABLE_CLUSTER_REUSE=false \
-e SIRCHMUNK_SEARCH_PATHS=/mnt/docs \
-v /path/to/your_work_path:/data/sirchmunk \
-v /path/to/your/docs:/mnt/docs:ro \
modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7
# 停止和删除容器
docker stop sirchmunk && docker rm sirchmunk
```
历史版本
| 版本 | 区域 | 镜像 |
|---|---|---|
| v0.0.6post3 | 美西 | `modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.6post3` |
| v0.0.6post3 | 北京 | `modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.6post3` |
| v0.0.4 | 美西 | `modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.4` |
| v0.0.4 | 北京 | `modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.4` |
打开 http://localhost:8584 访问 WebUI，或直接调用 API：
```python
import requests
response = requests.post(
"http://localhost:8584/api/v1/search",
json={
"query": "你的搜索问题",
"paths": ["/mnt/docs"],
},
)
print(response.json())
```
📖 **完整 Docker 参数和使用说明，请参阅 [docker/README.md](docker/README.md)**。
---
## 🏗️ 工作原理
### Sirchmunk 框架
### 核心组件
| 组件 | 说明 |
|:------------------------|:-----------------------------------------------------------------------|
| **AgenticSearch** | 搜索编排器，具备 LLM 增强检索能力 |
| **KnowledgeBase** | 将原始结果转化为结构化知识聚类并附带证据 |
| **EvidenceProcessor** | 基于蒙特卡洛重要性采样的证据处理 |
| **GrepRetriever** | 高性能 _无索引_ 文件检索，支持并行处理 |
| **OpenAIChat** | 统一 LLM 接口，支持流式与用量统计 |
| **MonitorTracker** | 实时系统与应用指标采集 |
### 蒙特卡洛证据采样
传统检索系统要么读取完整文档，要么依赖固定大小的分块，导致 Token 浪费或上下文丢失。Sirchmunk 借鉴**蒙特卡洛方法**，采用了截然不同的策略——将证据提取视为一个**采样问题**而非解析问题。
蒙特卡洛证据采样 — 从大文档中提取相关证据的三阶段启发式探索-利用策略。
该算法分为三个阶段：
1. **第一阶段 — 撒网（探索）：** 模糊锚定匹配结合分层随机采样。系统在识别潜在相关种子区域的同时，通过随机探测保持广泛覆盖，确保不会遗漏高价值区域。
2. **第二阶段 — 聚焦（利用）：** 以第一阶段高分种子为中心进行高斯重要性采样。采样密度集中在最有前景的区域，提取上下文并对每个片段评分。
3. **第三阶段 — 合成：** 将 Top-K 评分片段传递给 LLM，合成为连贯的兴趣区域（ROI）摘要，并附带置信度标志——使管线能够判断证据是否充分，或是否需要启用 ReAct 智能体进行更深层的自适应检索。
**核心特性：**
- **文档无关性：** 同一算法在 2 页备忘录和 500 页技术手册上同样有效，无需针对特定文档的分块启发式规则。
- **Token 高效：** 仅将最相关的区域发送给 LLM，相比全文档方案大幅降低 Token 消耗。
- **探索-利用平衡：** 随机探索防止视野盲区，重要性采样确保在关键区域深入挖掘。
### 自进化知识聚类（Knowledge Cluster）
Sirchmunk 不会在回答完查询后丢弃搜索结果。相反，每次搜索都会产生一个 **KnowledgeCluster（知识聚类）**——一个结构化、可复用的知识单元，随着使用不断变得更加智能。这正是系统具备_自进化_能力的核心机制。
#### 什么是 KnowledgeCluster？
KnowledgeCluster 是一个丰富标注的对象，完整记录了单次搜索周期的认知产出：
| 字段 | 用途 |
|:-----|:-----|
| **Evidences（证据）** | 通过蒙特卡洛采样提取的源文件片段，包含文件路径、摘要和原始文本 |
| **Content（内容）** | LLM 合成的结构化 Markdown 分析，附带引用 |
| **Patterns（模式）** | 从证据中提炼的 3–5 条设计原则或核心机制 |
| **Confidence（置信度）** | 共识评分 \[0, 1\]，指示聚类的可靠性 |
| **Queries（查询历史）** | 贡献或复用该聚类的历史查询（FIFO，最多 5 条） |
| **Hotness（热度）** | 反映查询频率和时效性的活跃度评分 |
| **Embedding（嵌入向量）** | 由累积查询生成的 384 维向量，用于语义检索 |
#### 生命周期：从创建到进化
```
┌─────── 新查询 ───────┐
│ ▼
│ ┌───────────────────────────────┐
│ │ 阶段 0：语义复用 │──── 匹配命中 ──→ 返回缓存聚类
│ │ （余弦相似度 ≥ 0.85） │ + 更新热度/查询/嵌入
│ └──────────┬────────────────────┘
│ 未匹配
│ ▼
│ ┌───────────────────────────────┐
│ │ 阶段 1–3：完整搜索 │
│ │ （关键词 → 检索 → │
│ │ 蒙特卡洛采样 → LLM 合成） │
│ └──────────┬────────────────────┘
│ ▼
│ ┌───────────────────────────────┐
│ │ 构建新聚类 │
│ │ 确定性 ID: C{sha256} │
│ └──────────┬────────────────────┘
│ ▼
│ ┌───────────────────────────────┐
│ │ 阶段 5：持久化 │
│ │ 嵌入查询 → DuckDB → │
│ │ Parquet（原子写入同步） │
└─────└───────────────────────────────┘
```
1. **复用检查（阶段 0）：** 在任何检索开始之前，查询会被嵌入并通过余弦相似度与所有已存储聚类进行比对。若发现高置信度匹配，系统直接返回已有聚类——完全省去 LLM 推理和搜索开销。
2. **创建（阶段 1–3）：** 当无复用匹配时，完整管线运行：关键词提取、文件检索、蒙特卡洛证据采样、LLM 合成，最终生成新的 `KnowledgeCluster`。
3. **持久化（阶段 5）：** 聚类存储在内存中的 DuckDB 表中，并定期刷写为 Parquet 文件。原子写入和基于文件修改时间的重载机制确保多进程安全。
4. **复用时进化：** 每当聚类被复用时，系统会：
- 将新查询追加到聚类的查询历史中（FIFO，最多 5 条）
- 提升热度（+0.1，上限 1.0）
- 基于更新后的查询集重新计算嵌入——扩展聚类的语义覆盖范围
- 更新版本号和时间戳
#### 核心特性
- **零成本加速：** 重复或语义相似的查询直接从缓存聚类获取答案，无需任何 LLM 推理，后续搜索几乎瞬时完成。
- **查询驱动的嵌入：** 聚类嵌入基于_查询_而非内容生成，确保检索与用户的实际提问方式对齐——而非文档的书写方式。
- **语义拓展：** 随着多样化查询复用同一聚类，其嵌入会漂移以覆盖更广的语义邻域，自然提升相关未来查询的召回率。
- **轻量级持久化：** DuckDB 内存存储 + Parquet 磁盘持久化——无需外部数据库基础设施。后台守护线程同步，可配置刷写间隔，开销极小。
---
### 数据存储
所有持久化数据存储在配置的 `SIRCHMUNK_WORK_PATH`（默认：`~/.sirchmunk/`）：
```
{SIRCHMUNK_WORK_PATH}/
├── .cache/
├── history/ # 聊天会话历史（DuckDB）
│ └── chat_history.db
└── knowledge/ # 知识聚类（Parquet）
└── knowledge_clusters.parquet
```
---
## 🔗 HTTP 客户端访问（Search API）
服务器启动后（`sirchmunk serve` 或 `sirchmunk web serve`），Search API 可通过任何 HTTP 客户端访问。
API 端点
| 方法 | 端点 | 说明 |
|------|------|------|
| `POST` | `/api/v1/search` | 执行搜索查询（完成后一次性返回 JSON） |
| `POST` | `/api/v1/search/stream` | 请求体与 `/search` 相同；通过 **SSE** 流式返回运行日志及最终 `result` / `error` |
| `GET` | `/api/v1/search/status` | 检查服务器与 LLM 配置（含 `max_concurrent_searches`） |
**交互式文档：** http://localhost:8584/docs（Swagger UI）
cURL 示例
**`paths` 规则（`/search` 与 `/search/stream` 相同）：**
- **可选**。类型：**单个字符串**或**字符串数组**（`"paths": "/一个目录"` 或 `"paths": ["/a", "/b"]`）。
- **不传**、**`null`**、**`""`**、**`[]`**，或列表里全是空白项时，使用服务器环境变量 **`SIRCHMUNK_SEARCH_PATHS`**（一般在 `~/.sirchmunk/.env` 中配置，服务启动时加载）。若未设置，则回退到服务进程**当前工作目录**。
- **优先级：** 请求里非空的 `paths` → `SIRCHMUNK_SEARCH_PATHS` → cwd。
```bash
# FAST 模式（默认，贪心搜索，2 次 LLM 调用）
curl -X POST http://localhost:8584/api/v1/search \
-H "Content-Type: application/json" \
-d '{
"query": "认证是如何工作的？",
"paths": ["/path/to/project"]
}'
# 单个路径用字符串（等价于单元素数组）
curl -X POST http://localhost:8584/api/v1/search \
-H "Content-Type: application/json" \
-d '{
"query": "认证是如何工作的？",
"paths": "/path/to/project"
}'
# 省略 paths — 使用服务器上 ~/.sirchmunk/.env 中的 SIRCHMUNK_SEARCH_PATHS
curl -X POST http://localhost:8584/api/v1/search \
-H "Content-Type: application/json" \
-d '{"query": "认证是如何工作的？"}'
# DEEP 模式（蒙特卡洛证据采样全面分析）
curl -X POST http://localhost:8584/api/v1/search \
-H "Content-Type: application/json" \
-d '{
"query": "数据库连接池",
"paths": ["/path/to/project/src"],
"mode": "DEEP"
}'
# 文件名搜索（快速，无需 LLM）
curl -X POST http://localhost:8584/api/v1/search \
-H "Content-Type: application/json" \
-d '{
"query": "config",
"paths": ["/path/to/project"],
"mode": "FILENAME_ONLY"
}'
# 完整参数（详见下表「请求参数说明」）
curl -X POST http://localhost:8584/api/v1/search \
-H "Content-Type: application/json" \
-d '{
"query": "数据库连接池",
"paths": ["/path/to/project/src"],
"mode": "DEEP",
"max_depth": 10,
"top_k_files": 20,
"max_loops": 10,
"include_patterns": ["*.py", "*.java"],
"exclude_patterns": ["*test*", "*__pycache__*"],
"return_context": true
}'
# 检查服务器状态
curl http://localhost:8584/api/v1/search/status
```
Python 客户端示例
**使用 `requests`：**
```python
import requests
response = requests.post(
"http://localhost:8584/api/v1/search",
json={
"query": "认证是如何工作的？",
"paths": ["/path/to/project"],
},
timeout=60
)
data = response.json()
if data["success"]:
payload = data.get("data") or {}
print(payload.get("summary", payload))
```
**使用 `httpx`（异步）：**
```python
import httpx
import asyncio
async def search():
async with httpx.AsyncClient(timeout=300) as client:
resp = await client.post(
"http://localhost:8584/api/v1/search",
json={
"query": "查找所有 API 端点",
# 可选：省略 paths 时使用服务端 SIRCHMUNK_SEARCH_PATHS
"paths": ["/path/to/project"],
}
)
data = resp.json()
if data.get("success"):
p = data.get("data") or {}
print(p.get("summary", p))
asyncio.run(search())
```
JavaScript 客户端示例
```javascript
const response = await fetch("http://localhost:8584/api/v1/search", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
query: "认证是如何工作的？",
paths: ["/path/to/project"],
})
});
const data = await response.json();
if (data.success) {
const p = data.data || {};
console.log(p.summary ?? p);
}
```
SSE 流式搜索（/api/v1/search/stream）
需要 **实时查看搜索过程日志** 时使用本接口（检索流程与 `POST /api/v1/search` 一致）。响应类型为 **`text/event-stream`**（Server-Sent Events）。请求 JSON 与 `/api/v1/search` **完全相同**（**`paths`** 可选；可为字符串或数组，见上文 cURL 说明）。
**事件类型**
| SSE `event` | `data`（JSON） | 含义 |
|-------------|----------------|------|
| `log` | `{"level":"info",...,"message":"..."}` | 搜索流水线输出的一条日志 |
| `result` | `{"success":true,"data":{...}}` | 最终结果（`data` 与 `/search` 一致：可为 `summary`、`files` 或 `context`） |
| `error` | `{"error":"..."}` | 致命错误，流结束 |
以 `:` 开头的行是心跳/注释，可忽略。
**并发限制**
服务端通过环境变量 **`SIRCHMUNK_MAX_CONCURRENT_SEARCHES`**（默认 `3`）限制同时进行的搜索任务数，超出时新请求会排队等待。可在 `GET /api/v1/search/status` 的响应中查看 **`max_concurrent_searches`**。
**cURL（使用 `-N` / `--no-buffer` 才能实时看到分块输出）**
```bash
curl -N -X POST "http://localhost:8584/api/v1/search/stream" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"query": "认证是如何工作的？",
"paths": ["/path/to/project"],
"mode": "FAST"
}'
```
**Python — `requests`（按行流式读取）**
```python
import json
import requests
url = "http://localhost:8584/api/v1/search/stream"
payload = {
"query": "认证是如何工作的？",
"paths": ["/path/to/project"],
"mode": "FAST",
}
event_type = ""
with requests.post(
url, json=payload, stream=True, timeout=(10, 600),
headers={"Accept": "text/event-stream"},
) as resp:
resp.raise_for_status()
for raw in resp.iter_lines(decode_unicode=True):
if raw is None or raw == "":
continue
if raw.startswith(":"):
continue
if raw.startswith("event: "):
event_type = raw[7:].strip()
continue
if raw.startswith("data: "):
obj = json.loads(raw[6:])
if event_type == "log":
print(f"[{obj.get('level', 'info')}] {obj.get('message', '')}")
elif event_type == "result":
print("完成:", json.dumps(obj, indent=2, ensure_ascii=False))
elif event_type == "error":
print("错误:", obj.get("error"))
event_type = ""
```
**Python — `httpx`**
```python
import json
import httpx
url = "http://localhost:8584/api/v1/search/stream"
payload = {"query": "查找 API 路由", "paths": ["/path/to/project"], "mode": "DEEP"}
event_type = ""
with httpx.Client(timeout=httpx.Timeout(600.0, connect=10.0)) as client:
with client.stream(
"POST",
url,
json=payload,
headers={"Accept": "text/event-stream"},
) as resp:
resp.raise_for_status()
for line in resp.iter_lines():
if not line or line.startswith(":"):
continue
if line.startswith("event: "):
event_type = line[7:].strip()
continue
if line.startswith("data: "):
obj = json.loads(line[6:])
if event_type == "log":
print(obj.get("message", ""))
elif event_type == "result":
data = obj.get("data", {})
print(data.get("summary") or data)
event_type = ""
```
**JavaScript — `fetch` + ReadableStream**（`EventSource` 仅支持 GET；POST 的 SSE 需用 `fetch`）
```javascript
async function searchStream(baseUrl, body) {
const res = await fetch(`${baseUrl}/api/v1/search/stream`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "text/event-stream",
},
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(await res.text());
const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "";
let currentEvent = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
buf += dec.decode(value, { stream: true });
const parts = buf.split("\n\n");
buf = parts.pop() || "";
for (const block of parts) {
let dataLine = null;
for (const line of block.split("\n")) {
if (line.startsWith("event:")) currentEvent = line.slice(6).trim();
else if (line.startsWith("data:")) dataLine = line.slice(5).trim();
}
if (!dataLine) continue;
const obj = JSON.parse(dataLine);
if (currentEvent === "log") console.log(`[${obj.level}]`, obj.message);
if (currentEvent === "result") console.log("result", obj);
if (currentEvent === "error") console.error(obj.error);
}
}
}
await searchStream("http://localhost:8584", {
query: "认证是如何工作的？",
paths: ["/path/to/project"],
mode: "FAST",
});
```
**命令行**
`sirchmunk search --api` 在可用时会优先调用本流式端点，实时打印日志，最后输出摘要。
请求参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `string` | *必填* | 搜索查询或问题 |
| `paths` | `string` \| `string[]` | *可选* | 单路径或多路径。省略 / `null` / `""` / `[]` / 仅空白 → 使用服务端 `SIRCHMUNK_SEARCH_PATHS`（如 `~/.sirchmunk/.env`），再回退 cwd。请求中的路径优先于环境变量。 |
| `mode` | `string` | `"FAST"` | `FAST`、`DEEP` 或 `FILENAME_ONLY` |
| `enable_dir_scan` | `bool` | `true` | 是否启用目录扫描（FAST/DEEP）以发现文件 |
| `max_depth` | `int` | `null` | 最大目录深度 |
| `top_k_files` | `int` | `null` | 返回的文件数量 |
| `max_loops` | `int` | `null` | ReAct 最大迭代次数（DEEP 模式） |
| `max_token_budget` | `int` | `null` | LLM token 预算（DEEP 模式，默认 128K） |
| `include_patterns` | `string[]` | `null` | 文件 glob 匹配模式（包含） |
| `exclude_patterns` | `string[]` | `null` | 文件 glob 匹配模式（排除） |
| `return_context` | `bool` | `false` | 返回完整 SearchContext（含 KnowledgeCluster 和遥测数据） |
> **注意：** `FILENAME_ONLY` 模式无需 LLM API Key。`FAST` 和 `DEEP` 模式需要配置 LLM。
---
## ❓ FAQ
这与传统 RAG 系统有什么不同？
Sirchmunk 采用 **无索引** 方法：
1. **无预索引**：无需向量数据库，直接检索文件
2. **自进化**：知识聚类随检索模式演化
3. **多层检索**：自适应关键词粒度提升召回
4. **证据驱动**：蒙特卡洛重要性采样实现精准内容定位和抽取
支持哪些 LLM 提供商？
任何 OpenAI 兼容 API 端点，包括但不限于：
- OpenAI（GPT-5.2, ...）
- [MiniMax](https://platform.minimax.io)（MiniMax-M2.7、MiniMax-M2.7-highspeed、MiniMax-M2.5）
- DeepSeek、Moonshot、Mistral、Groq、Together AI、Cohere
- Google Gemini、智谱（GLM）、百川、零一万物、硅基流动、火山引擎
- Azure OpenAI
- 通过 Ollama、llama.cpp、vLLM、SGLang 等托管的本地模型
- 通过 API 代理接入的 Claude
使用 MiniMax 的配置示例：
```bash
LLM_BASE_URL=https://api.minimax.io/v1 # 海外版
# LLM_BASE_URL=https://api.minimaxi.com/v1 # 国内版
LLM_API_KEY=your-minimax-api-key
LLM_MODEL_NAME=MiniMax-M2.7
```
详见 [MiniMax OpenAI 兼容 API 文档](https://platform.minimax.io/docs/api-reference/text-openai-api)。
如何添加需要检索的文档？
只需在搜索请求中指定路径：
```python
result = await search.search(
query="Your question",
paths=["/path/to/folder", "/path/to/file.pdf"]
)
```
知识聚类存储在哪里？
知识聚类以 Parquet 格式持久化于：
```
{SIRCHMUNK_WORK_PATH}/.cache/knowledge/knowledge_clusters.parquet
```
你可以使用 DuckDB 或 `KnowledgeManager` API 查询。
如何监控 LLM Token 使用量？
1. **Web 面板**：访问 Monitor 页面查看实时统计
2. **API**：`GET /api/v1/monitor/llm` 返回用量指标
3. **代码**：搜索完成后访问 `search.llm_usages`
---
## 📋 Roadmap
- [x] 原始文件文本检索
- [x] 知识结构化与持久化
- [x] 基于 RAG 的实时对话
- [x] Web UI 支持
- [x] 支持多轮对话
- [ ] Web 搜索集成
- [ ] 多模态支持（图片、视频）
- [ ] 分布式跨节点检索
- [ ] 知识可视化与深度分析
- [ ] 更多文件类型支持
---
## 🤝 贡献
欢迎 [贡献](https://github.com/modelscope/sirchmunk/pulls)！
---
## 📄 许可
本项目采用 [Apache License 2.0](LICENSE)。
---
**[ModelScope](https://github.com/modelscope)** · [⭐ Star us](https://github.com/modelscope/sirchmunk/stargazers) · [🐛 反馈问题](https://github.com/modelscope/sirchmunk/issues) · [💬 Discussions](https://github.com/modelscope/sirchmunk/discussions)
*✨ Sirchmunk：原始数据到自进化智能，实时。*
❤️ 感谢访问 ✨ Sirchmunk ！
