haiku.rag

haiku.rag

面向 Agent 的 RAG，可通过页码和章节标题引用来源，回答关于您自己文档的问题。默认通过 Ollama 使用开放模型，并基于嵌入式 LanceDB 数据库运行，因此无需服务端或 API 密钥。Pydantic AI 支持的任何提供方都可以替代它们，同一个数据库也可以存放在 S3、GCS、Azure 或 LanceDB Cloud 上。

基于 LanceDB、Pydantic AI 和 Docling 构建。文档：ggozad.github.io/haiku.rag。

功能

• 摄取 PDF、办公文档、HTML、Markdown 和图像，可使用 Docling 在进程内处理，也可使用 docling-serve。存储的 DoclingDocument 会保留标题、表格、图片和页面来源信息。
• 搜索支持向量与全文混合检索、可选的重排（cross-encoder、Jina、Cohere、Zero Entropy、vLLM、OpenRouter）、基于章节的上下文扩展，以及使用多模态嵌入器进行图像搜索（vLLM、OpenRouter、VoyageAI、Cohere）。可同时搜索多个命名数据库。
• 回答具备 RAG 能力：搜索文档、运行沙盒化 Python 进行计数和聚合，并引用页码和标题。视觉模型可接收图表。可选能力可在长对话中压缩先前证据，并要求每个回答声明其依据。
• 核验引用：在页面图像上绘制对应片段，可通过命令行、聊天 TUI 或 Python 操作。
• 集成提供 Python API、原生 Pydantic AI 能力、可观察文档写入和转换搜索的插件钩子、供 Claude Code、Codex 和 Claude Desktop 使用的 MCP 服务，以及参考 Web 应用。
• 运维支持 haiku-ingester 服务（文件系统、HTTP、S3 和 WebDAV 来源；带重试功能的 SQLite 或 Postgres 作业队列；控制平面和仪表板）、标签与回滚、清理，以及 haiku-rag doctor 健康检查。

安装

需要 Python 3.12 或更高版本。

pip install haiku.rag        # Docling, the VoyageAI and Cohere embedders, every reranker, the TUI
pip install haiku.rag-slim   # the core, with extras chosen by you

ingester、S3 访问，以及 Ollama 和 OpenAI 兼容端点以外的模型提供方均为额外组件。请参阅安装。

快速入门

默认配置使用 Ollama 进行嵌入和回答。快速入门指南介绍了需要拉取的模型以及如何改用 OpenAI。

haiku-rag init                                  # create the database
haiku-rag add-src paper.pdf                     # index a file, URL or directory
haiku-rag search "attention mechanism"
haiku-rag ask "What datasets were used for evaluation?"
haiku-rag ask "How many documents mention transformers?"
haiku-rag ask "Does this figure match the spec?" --image figure.png
haiku-rag chat                                  # multi-turn chat in the terminal

使用已配置来源进行持续摄取时，需要单独运行服务，并安装 ingester extra（pip install 'haiku.rag[ingester]'）：

haiku-ingester serve

Python API

from haiku.rag.client import HaikuRAG

async with HaikuRAG("knowledge.lancedb", create=True) as rag:
    await rag.create_document_from_source("paper.pdf")
    await rag.create_document_from_source("https://arxiv.org/pdf/1706.03762")

    results = await rag.search("self-attention")
    for result in results:
        print(f"{result.score:.2f} | p.{result.page_numbers} | {result.content[:100]}")

    answer, citations = await rag.ask("What is the complexity of self-attention?")
    print(answer)
    for cite in citations:
        print(f"  [{cite.chunk_id}] p.{cite.page_numbers}: {cite.content[:80]}")

如需组合自己的 Agent，请参阅能力。

MCP 服务

haiku-rag mcp --stdio

该服务为助手提供文档搜索、阅读和 Python 沙盒功能。在 Claude Code 中，插件会通过一项技能注册该服务：

claude plugin marketplace add ggozad/haiku.rag
claude plugin install haiku-rag

Codex 和 Claude Desktop 的配置说明见 MCP 文档。

示例

• Docker 配置：docling-serve、ingester 和 MCP 服务
• Web 应用：在浏览器中使用聊天、摄取、检查器和 doctor

文档

• 快速入门：安装、索引、聊天
• 安装：软件包和额外组件
• 架构：文档如何变成带引用的答案
• CLI和聊天与检查器
• 功能：原生 Pydantic AI 功能
• 配置：所有设置，以及调优
• 摄取器、MCP和远程处理
• Python API和自定义管道
• 基准测试和更新日志

许可证

MIT。

mcp-name: io.github.ggozad/haiku-rag