Haiku.rag

🚀 俳句检索增强生成（Haiku RAG）

俳句检索增强生成（Haiku RAG）是一个基于 LanceDB、Pydantic AI 和 Docling 构建的智能检索增强生成系统。它具备多种强大功能，能有效处理文档、实现高效搜索和问答，为研究和信息处理提供有力支持。

✨ 主要特性

• 混合搜索 — 结合向量搜索与全文搜索，并采用互反排名融合算法。
• 重排序 — 支持 MxBAI、Cohere、零熵或 vLLM 等重排序方法。
• 问答功能 — 问答代理可提供引用信息（页码、章节标题）。
• 研究代理 — 通过 pydantic - graph 实现多代理工作流：规划、搜索、评估、合成。
• 文档结构处理 — 存储完整的 DoclingDocument，支持基于结构的上下文扩展。
• 视觉定位 — 在原始页面图像上高亮显示文本块。
• 时间回溯 — 使用 --before 参数可查询数据库在任意历史时间点的状态。
• 多供应商支持 — 嵌入模型：Ollama、OpenAI、VoyageAI、LM Studio、vLLM。问答/研究：支持 Pydantic AI 所支持的任何模型。
• 本地优先 — 嵌入 LanceDB，无需服务器。也支持 S3、GCS、Azure 和 LanceDB Cloud。
• MCP 服务器 — 可作为工具供 AI 助手（如 Claude Desktop）使用。
• 文件监控 — 监控目录，文件变更时自动索引。
• 检查器 — 提供文本用户界面（TUI），用于浏览文档、文本块和搜索结果。
• 命令行界面（CLI）与 Python API — 可通过命令行或代码实现全部功能。

📦 安装指南

需要 Python 3.12 或更高版本

完整包（推荐）

uv pip install haiku.rag

包含所有功能：文档处理、所有嵌入模型供应商和重排序器。

精简包（最小依赖）

uv pip install haiku.rag - slim

仅安装所需的扩展。可用选项请参阅 安装文档。

🚀 快速开始

# 索引 PDF 文件
haiku - rag add - src paper.pdf

# 搜索
haiku - rag search "attention mechanism"

# 带引用的问答
haiku - rag ask "What datasets were used for evaluation?" --cite

# 深度问答 — 将复杂问题分解为子查询
haiku - rag ask "How does the proposed method compare to the baseline on MMLU?" --deep

# 研究模式 — 迭代规划和搜索
haiku - rag research "What are the limitations of the approach?" --verbose

# 交互式研究 — 人工介入决策点
haiku - rag research "Compare the approaches discussed" --interactive

# 监控目录变更
haiku - rag serve --monitor

自定义选项请参阅 配置文档。

💻 使用示例

基础用法

from haiku.rag.client import HaikuRAG

async with HaikuRAG("research.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]}")

关于研究代理和使用 AG - UI 进行流式处理，请参阅 代理文档。

MCP 服务器

可与 Claude Desktop 等 AI 助手配合使用：

haiku - rag serve --mcp --stdio

添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "haiku - rag": {
      "command": "haiku - rag",
      "args": ["serve", "--mcp", "--stdio"]
    }
  }
}

可直接在 AI 助手中提供文档管理、搜索、问答和研究工具。

🔍 示例

工作示例请参阅 示例目录：

• [交互式研究助手](examples/ag - ui - research/) - 基于 Pydantic AI 和 AG - UI 的全栈研究助手，支持人工介入审批和实时状态同步。
• Docker 部署 - 完整的 Docker 部署方案，包含文件监控和 MCP 服务器。
• [A2A 服务器](examples/a2a - server/) - 自包含的 A2A 协议服务器包，带有对话代理界面。

📚 详细文档

完整文档请访问：https://ggozad.github.io/haiku.rag/

• 安装 - 供应商设置
• 配置 - YAML 配置
• 命令行界面 - 命令参考
• Python API - 完整的 API 文档
• 代理 - 问答代理和多代理研究
• 服务器 - 文件监控、MCP 和 AG - UI
• MCP - 模型上下文协议集成
• 检查器 - 数据库浏览器 TUI
• 基准测试 - 性能基准
• 更新日志 - 版本历史

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