Fidx：纯本地单文件语义检索工具，无需查询时调用大模型

Fidx 是一款面向本地场景的混合语义检索工具，主打「不依赖云端 GPU、不在查询路径中调用大模型」的设计思路。项目把所有文档、BM25 索引与向量索引统一存放在一个 SQLite 文件中，可直接作为命令行工具、私有 RAG 检索器，或智能体背后的记忆层使用。

核心设计思路

传统本地语义检索工具往往用「查询时调用大模型做查询扩展或重排」来换取召回率，但在纯 CPU 环境下单次查询可能耗时约 10 秒。Fidx 选择了不同取舍：

• 混合召回：FTS5 BM25 负责精确名称与标识符；768 维向量负责语义匹配；两者通过倒数秩融合（RRF）合并。
• 极轻模型开销：整个查询路径中唯一的模型调用是 ONNX 嵌入模型对查询本身的一次编码。
• 毫秒级响应：常驻守护进程在 2k–19k 篇文档规模下，热查询 p50 约 18–49 毫秒（单 ONNX 线程）；冷启动 CLI 调用也在 1 秒以内。

单文件与集合化

文档、BM25 索引与向量均落在同一个 SQLite 数据库中（启用 FTS5 与 sqlite-vec 扩展），便于复制、备份与删除。Fidx 支持将不同来源组织成命名集合（collection），例如 notes、emails、code、docs，搜索时可限定到特定集合。

平台与安装

Fidx 要求 Python 3.11 或 3.12，且 SQLite 内置支持 loadable extensions 与 FTS5。官方提供预编译 wheel，无需本地编译器：

• Linux x86_64：通过 CI 与 Docker 验证。
• macOS arm64（Apple Silicon）：通过 CI 验证，建议使用 Homebrew Python。
• Windows x86_64：通过 CI 验证，可使用 python.org 或 uv 管理的 Python。
• macOS Intel、Linux/Windows arm64：尽力支持，依赖上游 wheel 可用性。

由于 PyPI 上 fidx 名称已被占用，项目以 fmdidx（fast markdown index）发布，安装后命令仍为 fidx。推荐使用 uv tool install fmdidx 或 pipx install fmdidx。macOS 上需借助 Homebrew Python，因为 uv 自带与 python.org 安装的 SQLite 均未启用 loadable extensions。

智能体与 RAG 集成

Fidx 本身不构成智能体框架，其集成面就是 CLI：注册本地文件、建立索引、保持守护进程常驻，再让智能体或工作流调用 fidx search --json 与 fidx get。典型场景包括：

• 智能体记忆检索：fidx search "..." -c memory --json -n 5，返回带片段、路径、docid 与得分的结构化结果。
• 本地 RAG 检索：先 search 选取候选文档，再用 fidx get --head "#docid" 取回原文供模型使用。
• 代码上下文注入：fidx search "..." -c code --files -n 20，仅返回匹配路径供后续读取。

针对 MCP 服务器、LangChain/LangGraph 工具、LlamaIndex 检索器或基于 Shell 的编程智能体，同样的 JSON 契约通常足够对接。

验证与基准

安装后可通过 fidx doctor 检查宿主机能力（退出码 0 表示就绪）。项目附带 scripts/e2e_smoke.py，可在约 1,000 篇文档的语料上做端到端检索基准并校验召回；scripts/verify-install.sh 则在干净的 Docker 容器中复现完整安装流程，作为跨机器验证手段。