haiku.rag

haiku.rag 是一款本地优先的智能体式 RAG（检索增强生成）工具，能够对用户自有文档进行问答，并给出带页码与章节标题的引用。它运行在嵌入式数据库上，无需搭建服务器，基于 LanceDB、Pydantic AI 与 Docling 构建，既提供命令行与 Python API，也能作为 MCP 服务器供 Claude Desktop 等 AI 助手调用。其核心目标是让个人与团队在完全本地化的前提下，对自己的文档进行可溯源的知识问答。

核心能力

• 混合检索：向量检索与全文检索并用，通过倒数排名融合（RRF）提升召回质量。
• 多模态与跨模态搜索：多模态嵌入模型把图片向量与文本放入同一空间，支持以文本查图片、以图片查图片。
• 带引用的问答：答案附带页码与章节标题等出处，便于核实。
• 视觉问答：视觉模型可同时接收图片字节与分块文本，并支持在提问中附加自有图片。
• 重排序：支持本地交叉编码器、Cohere、Zero Entropy 或 vLLM 进行结果重排。
• 代码执行：RAG 能力可在沙箱中运行 Python，对文档做聚合、计算与多文档分析。
• 证据压缩：用早前问题所引用的证据替换其检索结果，避免长对话反复重发全部检索内容。
• 引用策略：可要求每个答案声明其依据，包括声明无依据可循。
• 对话式 RAG：内置聊天 TUI 与 Web 应用，支持带会话记忆的多轮对话。
• 文档结构保留：存储完整的 DoclingDocument，支持结构感知的上下文扩展。
• 多数据库检索：可跨多个命名数据库搜索、提问与对话，并在结果中标注来源。
• 生产级摄取服务：提供持久化 SQLite 队列、带重试与死信队列的异步工作池，以及 FS/HTTP/S3/WebDAV 源适配器。

安装配置

1. 准备 Python 3.12 或更高版本。
2. 推荐安装完整包：pip install haiku.rag（包含文档处理、全部嵌入提供方与重排器）；使用 uv 时执行 uv pip install haiku.rag。
3. 需要最小依赖时可安装精简包：pip install haiku.rag-slim，再按需安装所需扩展。
4. 配置一个嵌入提供方（Ollama、OpenAI、VoyageAI、Cohere、LM Studio 或 vLLM），参考官方教程完成设置。

使用步骤

1. 索引文档：运行 haiku-rag add-src paper.pdf 将 PDF 等文档加入知识库。
2. 执行搜索：运行 haiku-rag search "attention mechanism" 做混合检索。
3. 带引用提问：运行 haiku-rag ask "What datasets were used for evaluation?" 获取带出处答案。
4. 图片问答：使用 haiku-rag ask "Does this figure match the spec in the design doc?" --image figure.png 结合图片提问。
5. 分析型任务：运行 haiku-rag ask "How many documents mention transformers?"，借助沙箱代码执行完成聚合统计。
6. 多轮对话：运行 haiku-rag chat 进入带记忆的交互式会话。
7. 接入 AI 助手：以 MCP 服务器方式暴露给 Claude Desktop 等客户端使用。

适用场景

• 研究者对大量论文做带引用的问答与跨文档分析。
• 企业团队在本地私有化部署中检索内部文档与规范。
• 需要以图搜图或图文混合检索的设计与工程团队。
• 长对话场景下需要控制上下文膨胀与检索成本的问答应用。
• 需要可视化标注原文页面分块位置的审核与校对工作。
• 构建生产级文档摄取流水线的工程团队。

适用人群

• 研究者与学术工作者。
• 需要本地知识库的企业与团队。
• AI 应用与 RAG 系统开发者。
• 对数据隐私敏感、倾向本地部署的个人用户。
• 需要文档问答能力的 Python 工程师。

工作原理

haiku.rag 以嵌入式 LanceDB 作为向量与全文索引底座，用 Docling 解析文档并保留完整结构，再由 Pydantic AI 驱动的 RAG 能力完成检索、重排与生成。检索阶段采用向量与全文的混合搜索并通过 RRF 融合，必要时调用重排序模型优化排序；问答阶段把相关分块与文档结构一并交给模型，并输出页码与章节等引用。对聚合类问题，它会在沙箱中执行 Python 代码完成计算。整个过程可完全本地运行，无需独立服务器，也可切换至 S3、GCS、Azure 或 LanceDB Cloud 等存储后端。

官方链接

• PyPI：https://pypi.org/project/haiku.rag/
• 文档：https://ggozad.github.io/haiku.rag/
• GitHub：https://github.com/ggozad/haiku.rag