justsearch

# JustSearch **您的人工智能代理的私有检索后端 - 以及具有引文的本地 AI 助手，用于您自己的文件。云级混合搜索（BM25 + 密集向量 + 学习稀疏 + 重排序）以及基于事实的问答、摘要和提取 - 100% 在您的机器上，支持 70+ 种语言。** [](LICENSE) <!-- badges: <<build status>> · <<latest release>> · <<nDCG benchmark badge>> --> JustSearch 索引您的本地文档 - PDF、电子邮件、Office 和数百种格式 - 并回答问题，提供引文段落，**无需任何数据离开您的机器。** 它结合了三种检索范式（关键词、密集向量、学习稀疏）与交叉编码器重排序，并通过 **模型上下文协议（MCP）** 公开检索，以便任何 AI 代理 - 本地或云端 - 都可以将其用作 **私有检索后端**：您的文件保留在您的设备上；只有模型的答案会离开您的代理。 ## 使用方式 **作为 AI 代理的私有 MCP 检索后端** *(开发者快速通道)* JustSearch 通过 `POST /mcp` 在 MCP 上公开检索 - **进程内可流式 HTTP** 在环回 API 上（无需单独进程，无需 Node.js）。端口在应用程序中显示（或 `GET /api/health`）。连接您的代理： - **Claude 代码：** `claude mcp add justsearch --transport http http://127.0.0.1:<PORT>/mcp` - **Cursor / VS 代码** （直接接受 HTTP `url` 的客户端 - 例如 `.cursor/mcp.json`）： ```json { "mcpServers": { "justsearch": { "url": "http://127.0.0.1:<PORT>/mcp" } } } ``` - **Claude 桌面版** - 将其添加为 **连接器** （设置 → 连接器 → 添加自定义连接器 → 上述 URL），或使用 `claude_desktop_config.json` 中的 `mcp-remote` 桥接 stdio→HTTP： ```json { "mcpServers": { "justsearch": { "command": "npx", "args": ["mcp-remote", "http://127.0.0.1:<PORT>/mcp"] } } } ``` 五个工具：`justsearch_answer` （RAG，主要）、`justsearch_search`、`justsearch_browse`、`justsearch_ingest`、`justsearch_status`。您的文档永远不会离开机器 - 只有代理的答案会离开。 一个可复制的代理实用程序基准测试 - JustSearch 的检索工具在任务性能方面比通用文件工具有多大的改进 - *正在开发中；可复制的图表将在项目基准测试方法论发布时公布* （在达到基准测试标准之前，不会发布任何百分比）。 **作为桌面应用程序** *(非开发者)* 下载安装程序，指向一个文件夹，然后搜索。→ **https://github.com/eliasjustus/justsearch/releases/latest**（Windows；alpha；目前未签名 - 参见 [状态](#status)）。 ## 为什么选择 JustSearch 本地文件搜索要么 **快速但字面** （Everything、Recoll - 私有，但词汇有限）要么 **智能但云端** （NotebookLM、Copilot - 功能强大，但您的文件会离开机器）。JustSearch 是缺失的部分：**语义且完全离线。** 没有被调查的替代方案能够同时满足 **{真正的混合检索 × 完全离线 × 多语言 × OCR}**。 - **混合检索，而非单一模型 RAG** - BM25 + 密集向量 + SPLADE 学习稀疏，融合并由交叉编码器重排序。大部分本地 RAG 工具使用一个嵌入模型和基本分块。 - **完全离线且可证明** - UI 被 CSP 硬锁定到 `127.0.0.1`；没有遥测导出。唯一的外联请求是一次性的模型下载。（[如何验证](#privacy).） - **从构建开始就支持多语言** - 一个语言环境不变的管道（ICU + 多语言模型堆栈），无需每种语言的调优。德语和法语的 nDCG 竞争力不输英语。 - **视觉 OCR** - 从扫描的 PDF 和图像中提取文本，使它们也可搜索。 - **自带 LLM** - 通过 llama.cpp 运行您自己的本地模型；无需 API 密钥，无需按 token 计费。 ## 基准测试 检索质量（nDCG@10）来自一次可复制的发布运行（`scripts/jseval/release.v1.json`，RTX 4070，约 300 查询/语料库；在 2026-06-21 发布树中测量）。数字是 **默认 `hybrid` 配置** 除非另有说明： | 语料库 | nDCG@10 | 备注 | |---|---|---| | BEIR / SciFact | **0.751** | 在已发布的单一模型检索器范围内（ColBERTv2 0.693，SPLADE++ 0.71）- 但将其视为 *系统 vs. 组件*：我们的系统是完整的混合 + 重排序管道，而他们的是单一模型 | | Enron-QA | 0.740 | | | MIRACL-de（德语） | 0.725 | 多语言 - 无需每种语言的调优 | | MIRACL-fr（法语） | 0.701 | | | CourtListener（法律） | 0.62 | 默认混合；法律在 `full` 模式下升至 **0.97** （所有检索器 + 重排序） | 外部基准数据引用自已发布的论文（SIGIR/NAACL；来源 + 分割免责声明在 `release.v1.json` 中）- **不是** 由我们重新运行，并且不是直接的苹果对苹果比较：混合 + 重排序 *系统* 预计将超过单一模型 *组件*，而 MIRACL 基准测试是不同的（开发）分割。诚实的阅读是“可复制的离线混合系统达到强大的已发布检索器的范围”，而不是“我们击败他们” - 完整的比较类别注释在 [方法论](docs/reference/benchmarks/methodology.md#how-to-read-the-comparison-system-vs-component) 中。每个语料库的 nDCG@10 基线从此发布中预测，并在 CI 中进行回归门控。 从 `scripts/jseval` 复制：`python -m jseval run --start-backend --dataset beir/scifact --modes hybrid` 然后 `python -m jseval relevance-gate --dataset beir/scifact`。别名：`beir/scifact`、`mixed/enron-qa`、`mixed/courtlistener-200`、`mixed/miracl-de-2k`、`mixed/miracl-fr-2k`。完整的方法论、比较类别免责声明和复制：[`docs/reference/benchmarks/methodology.md`](docs/reference/benchmarks/methodology.md)。上表是从 `scripts/jseval/release.v1.json`（2026-06-21发布的规范）预测的，而不是手动转录的。 ## 快速入门（从源代码构建） > **构建 + 测试** 的先决条件：**JDK 25** （Gradle 工具链自动解析）和 **Node.js** （用于 `modules/ui-web` 前端）- 除此之外无其他要求。构建/贡献不需要 **GPU、Rust 工具链和模型下载**；以下约 9 GB 模型仅在运行时需要（在应用程序首次 *运行时* 下载）。 ```bash git clone https://github.com/eliasjustus/justsearch && cd justsearch ./gradlew.bat build # 构建（Windows；使用 ./gradlew on *nix 一次跨平台） ``` 要 **运行** 完整的桌面应用程序，简单的路径是上面的 [安装程序](#two-ways-to-use-it)；从源代码运行三个进程堆栈是开发人员工作流程 - 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。首次运行下载模型（**~9 GB** - 约 5.9 GB 的本地聊天模型占主导地位；从 GitHub Releases + HuggingFace 获取），然后完全离线运行。 ## 架构 三个本地进程，隔离以确保可靠性，因此 UI **永远不会触及索引**： - **Head** - Tauri 桌面外壳 + 环回 API 网关（Lit/web 组件前端）。 - **Worker** - 拥有 Lucene 索引 + 检索管道（BM25/密集/SPLADE/重排序）+ OCR。 - **Inference** - 用于聊天/RAG 的本地 `llama-server`。 它们通过 `127.0.0.1` 上的 gRPC 进行通信。更多信息：[`docs/explanation/`](docs/explanation/)。 ## 隐私 没有任何数据离开您的机器，您可以检查： - Webview 的 Content-Security-Policy 将网络访问锁定到 `127.0.0.1` - 它 *无法* 访问公共互联网。 - 代码中不存在分析/遥测导出器。 - 唯一的外联请求是一次性的模型下载（从 GitHub Releases + HuggingFace）；之后，运行网络监视器并观察它保持沉默。威胁模型：[`docs/reference/security/threat-model.md`](docs/reference/security/threat-model.md)。 ## 状态 **Alpha** (`0.1.0`)，**仅限 Windows** （macOS/Linux 不在当前范围内）。安装程序当前 **未签名**，因此 Windows SmartScreen 在首次运行时会显示“未知发布者”警告 - 签名正在进行中。自 2025 年以来处于积极开发中；于 2026 年发布。借助大量 AI 代理协助在开放环境中构建 - 开发工具、治理/纪律门控和设计历史记录（`docs/tempdocs/`）都存在于此仓库中，并且提交记录由共同作者维护。 ## 贡献 欢迎贡献 - 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)（DCO 签署；无 CLA）。请先阅读 [`NON-GOALS.md`](NON-GOALS.md)，以确保变更符合项目范围。安全：[`SECURITY.md`](SECURITY.md)。您 **不需要** 任何代理/治理机制即可贡献 - 它作为透明度公开（[`MAINTAINING.md`](MAINTAINING.md)），而非必需路径。 ## 许可证 [Apache-2.0](LICENSE)。捆绑的模型和依赖许可证：[`NOTICE`](NOTICE) / [`THIRD_PARTY_NOTICES`](THIRD_PARTY_NOTICES)。