内容
# 混合检索
[](LICENSE)
一个本地、自托管的检索栈，通过模型上下文协议（MCP）暴露。它为大型语言模型（LLM）提供了四种工具：
- **`sqlite`** - 对您摄入的文档 corpus 进行混合搜索（FTS5 关键词 + 语义嵌入，使用 Reciprocal Rank Fusion 融合）。
- **`retrieve`** - 跨知识图谱、记忆和文档的统一搜索，带有知识图谱驱动的查询扩展和 RRF 融合。
- **`memory`** - 用于跨会话笔记的语义键值存储（存储 / 追加 / 替换部分 / 搜索 / 获取 / 列出）。
- **`kg`** - 具有混合搜索的实体关系知识图谱。
所有操作都在您的机器上运行。唯一的外部依赖是 OpenAI 兼容的嵌入服务器（一个小型 `llama-server` 进程）和可选的重新排序器。不会向第三方发送任何数据。
## 它如何组合
```
MCP 客户端（Claude Desktop 等）
| 标准输入输出（JSON-RPC）
v
server.py -> sqlite / retrieve / memory / kg 工具
| | |
| | +--> 记忆守护进程（TCP :8767）
| +--> knowledge_graph.jsonl
+--> docs.db（FTS5 + 2560-d 嵌入）+ embed_cache（mmap）
|
v
嵌入服务器（llama-server :8000, Qwen3-Embedding-4B）
```
文档 corpus、记忆和知识图谱都通过相同的模型嵌入，因此单个 `llama-server` 涵盖整个栈。
## 要求
- Python 3.10+
- [llama.cpp](https://github.com/ggml-org/llama.cpp) (`llama-server` 在您的 PATH 上）
- 建议为嵌入模型使用 GPU（它也可以在 CPU 上运行，但速度较慢）
## 快速入门
```bash
# 1. 安装 Python 依赖
pip install -r requirements.txt
# 2. 下载嵌入模型到 ./models （参见 models/README.md）
huggingface-cli download Qwen/Qwen3-Embedding-4B-GGUF \
Qwen3-Embedding-4B-Q8_0.gguf --local-dir ./models
# 3. 启动嵌入服务器（在单独的终端中运行）
scripts/start_embeddings.sh # Windows: scripts\start_embeddings.bat
# 4. 启动记忆守护进程（需要用于记忆 + 检索工具）
scripts/start_memory.sh # Windows: scripts\start_memory.bat
# 5. 创建空文档数据库
python init_databases.py
# 6. 摄入您的文档（markdown, html, json, 文本, 代码）
python scripts/ingest_docs.py --source ./corpus # ./corpus 有示例文档
# 7. 嵌入块（与步骤 3 中的嵌入服务器通信）
python scripts/embed_docs.py
# 8. （可选）为即时搜索预建 mmap 向量缓存
python scripts/rebuild_mmap_cache.py
```
然后将您的 MCP 客户端指向 `server.py`（参见 `example_config.json`）：
```json
{
"mcpServers": {
"hybrid-recall": {
"command": "python",
"args": ["/absolute/path/to/hybrid-recall/server.py"]
}
}
}
```
## 配置
所有设置都有合理的 localhost 默认值；您可以使用环境变量或 `.env` 文件（参见 `.env.example`）覆盖它们。重要的设置：
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `EMBED_SERVER_URL` | `http://127.0.0.1:8000/v1/embeddings` | 嵌入端点 |
| `RERANKER_URL` | `http://127.0.0.1:8001/v1/rerank` | 重新排序器（可选） |
| `MEMORY_SERVICE_PORT` | `8767` | 记忆守护进程端口 |
| `KNOWLEDGE_GRAPH_PATH` | `./data/knowledge_graph.jsonl` | 知识图谱存储 |
| `DOCS_DB_PATH` | `./data/docs.db` | 文档 corpus 数据库 |
要在不同的机器上运行模型，请将 `EMBED_SERVER_URL` / `RERANKER_URL` 指向该主机。工具不关心服务器的位置。
## 重新排序
重新排序是可选的，默认情况下是关闭的。每个搜索都可以在没有它的情况下工作，如果重新排序器没有运行，则会退回到双编码器顺序。要启用它，请启动重新排序器（`scripts/start_reranker`）并在调用时传递 `rerank=true`。
## 注意
- 文档 corpus、记忆存储和知识图谱都是从您自己的数据中构建的。新的克隆仓库会启动为空。
- 索引时间和查询时间的嵌入必须来自同一个模型。如果您切换嵌入模型，请重新嵌入 corpus。
- 记忆工具是一个小型 TCP 守护进程（`scripts/start_memory`）；文档和知识图谱工具在 MCP 服务器内部运行。
## 基准测试
这里的设计选择（Qwen3-4B 双编码器，默认关闭交叉编码器重新排序，RRF 融合，BGE-reranker-v2-m3）得到了实际测量的支持：召回套件、10 策略融合 A/B 测试、重新排序器和嵌入模型对比测试，以及延迟配置文件。参见 [`benchmark.md`](benchmark.md)。简而言之：实际嵌入 + 重新排序将检索 MRR 从 0.36 提升到 0.77，适用于 32 查询套件，而纯重新排序优于尝试的每个花哨融合方案。
## License
MIT. 参见 `LICENSE`。
