Piragi和传统RAG框架哪个更好用？（附核心特性对比）

The best RAG interface yet. 只需几行代码，即可从本地文件、云存储或网站构建一个功能齐全的检索增强生成（RAG）知识库。Piragi 内置向量存储、嵌入模型、智能引用和自动更新功能，默认免费且本地运行。

from piragi import Ragi

kb = Ragi(["./docs", "s3://bucket/data/**/*.pdf", "https://api.example.com/docs"])
answer = kb.ask("How do I deploy this?")

核心特性

Piragi 旨在简化 RAG 应用的构建流程，提供开箱即用的强大功能。其核心优势在于将复杂的文档处理、向量化、检索和生成流程封装在一个简洁的 API 之下。

快速开始

安装

通过 pip 安装 Piragi 核心库。如需使用本地大语言模型，可安装 Ollama。

pip install piragi

# 可选：安装 Ollama 以使用本地 LLM
# Optional: Install Ollama for local LLM
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2

Piragi 采用模块化设计，可按需安装可选组件以扩展功能。

# 可选扩展组件
# Optional extras
pip install piragi[s3]       # S3 支持 / S3 support
pip install piragi[gcs]      # Google Cloud Storage 支持 / Google Cloud Storage support
pip install piragi[azure]    # Azure Blob Storage 支持 / Azure Blob Storage support
pip install piragi[crawler]  # 递归网络爬虫 / Recursive web crawling
pip install piragi[graph]    # 知识图谱 / Knowledge graph
pip install piragi[postgres] # PostgreSQL/pgvector 支持 / PostgreSQL/pgvector support
pip install piragi[pinecone] # Pinecone 支持 / Pinecone support
pip install piragi[supabase] # Supabase 支持 / Supabase support
pip install piragi[all]      # 安装所有组件 / Install everything

基础用法

以下代码展示了 Piragi 最基础的用法：从本地文件夹创建知识库并进行提问。

from piragi import Ragi

# 从本地文件创建知识库
# Create a knowledge base from local files
kb = Ragi("./docs")

# 从多个数据源创建（支持通配符）
# Create from multiple sources (supports glob patterns)
kb = Ragi(["./docs/*.pdf", "https://api.docs.com", "./code/**/*.py"])

# 提问并获取答案
# Ask a question and get an answer
answer = kb.ask("What is the API rate limit?")
print(answer.text)

# 查看答案的引用来源
# View the citations for the answer
for cite in answer.citations:
    print(f"{cite.source}: {cite.score:.0%}")

高级功能详解

远程文件系统与网络爬取

Piragi 的强大之处在于能够无缝集成多种数据源。

远程文件系统：您可以直接从云存储中读取文件，无需预先下载到本地。

# 从 Amazon S3 读取
# Read from Amazon S3
kb = Ragi("s3://my-bucket/docs/**/*.pdf")

# 从 Google Cloud Storage 读取
# Read from Google Cloud Storage
kb = Ragi("gs://my-bucket/reports/*.md")

# 混合本地与远程源
# Mix local and remote sources
kb = Ragi([
    "./local-docs",
    "s3://bucket/remote-docs/**/*.pdf",
    "https://example.com/api-docs"
])

网络爬取：通过简单的 /** 后缀语法，即可递归抓取整个网站或特定部分的内容。

# 爬取整个网站
# Crawl entire site
kb = Ragi("https://docs.example.com/**")

# 爬取特定 API 文档部分
# Crawl specific API docs section
kb = Ragi("https://docs.example.com/api/**")

可插拔的向量存储后端

Piragi 支持多种向量数据库，您可以根据性能、持久化和部署环境需求进行选择。

智能分块与高级检索策略

为了提高检索质量，Piragi 提供了多种分块和检索增强策略。

分块策略：不同的文档类型和查询需求适合不同的分块方式。

# 语义分块 - 在主题边界处分割
# Semantic - splits at topic boundaries
kb = Ragi("./docs", config={"chunk": {"strategy": "semantic"}})

# 分层分块 - 创建父-子块以兼顾上下文与精度
# Hierarchical - parent-child for context + precision
kb = Ragi("./docs", config={"chunk": {"strategy": "hierarchical"}})

# 上下文分块 - 为每个块生成 LLM 摘要作为上下文
# Contextual - LLM-generated context per chunk
kb = Ragi("./docs", config={"chunk": {"strategy": "contextual"}})

高级检索：通过组合多种技术来显著提升答案的相关性。

kb = Ragi("./docs", config={
    "retrieval": {
        "use_hyde": True,           # 假设文档嵌入（提升模糊查询）
        "use_hybrid_search": True,  # BM25 + 向量混合搜索
        "use_cross_encoder": True,  # 神经重排序（精排）
    }
})

知识图谱集成

对于包含大量实体和关系的文档（如公司文档、技术手册），启用知识图谱可以极大改善对“关系类”问题的回答能力。

# 通过一个标志启用
# Enable with a single flag
kb = Ragi("./docs", graph=True)

# 系统会在文档摄取时自动提取实体和关系，并用其增强检索
# The system automatically extracts entities and relationships during ingestion and uses them to augment retrieval
answer = kb.ask("Who reports to Alice?")

# 直接访问图谱数据
# Direct graph access
kb.graph.entities()           # 获取所有实体 / Get all entities
kb.graph.neighbors("alice")   # 获取“alice”的邻居节点 / Get neighbors of "alice"
kb.graph.triples()            # 获取所有（主体，关系，客体）三元组 / Get all (subject, relation, object) triples

配置与异步支持

详细配置

Piragi 的所有行为都可以通过一个统一的配置字典进行精细控制。

config = {
    "llm": { # 大语言模型配置 / Large Language Model configuration
        "model": "llama3.2",
        "base_url": "http://localhost:11434/v1"
    },
    "embedding": { # 嵌入模型配置 / Embedding model configuration
        "model": "all-mpnet-base-v2",
        "batch_size": 32
    },
    "chunk": { # 分块配置 / Chunking configuration
        "strategy": "fixed",
        "size": 512,
        "overlap": 50
    },
    "retrieval": { # 检索策略配置 / Retrieval strategy configuration
        "use_hyde": False,
        "use_hybrid_search": False,
        "use_cross_encoder": False
    },
    "auto_update": { # 自动更新配置 / Auto-update configuration
        "enabled": True,
        "interval": 300 # 每300秒检查一次更新 / Check for updates every 300 seconds
    }
}

异步 API

为了在现代 Web 框架（如 FastAPI）中实现非阻塞操作，Piragi 提供了功能完整的异步接口 AsyncRagi。

from piragi import AsyncRagi

kb = AsyncRagi("./docs")

# 简单调用
# Simple await
await kb.add("./more-docs")
answer = await kb.ask("What is X?")

# 与 FastAPI 集成示例
# Integration example with FastAPI
@app.post("/ingest")
async def ingest(files: list[str]):
    await kb.add(files)
    return {"status": "done"}

所有核心方法（add(), ask(), retrieve(), refresh(), count(), clear()）都提供了异步版本。

总结

Piragi 通过其极简的 API 设计、强大的多源集成能力和可扩展的模块化架构，显著降低了构建生产级 RAG 应用的门槛。它将复杂的文档处理流水线、向量检索优化和 LLM 交互封装起来，让开发者能够专注于业务逻辑而非底层基础设施。

无论是快速构建一个本地文档问答工具，还是开发一个集成多种企业数据源的知识中台，Piragi 都提供了一个高效、灵活的起点。其 MIT 许可证也确保了可以在商业项目中自由使用。

项目资源：

• PyPI: pip install piragi
• 完整文档: https://pypi.org/project/piragi/

常见问题（FAQ）

Piragi如何确保答案的可信度？

Piragi内置智能引用功能，每个生成的答案都会自动附带其来源引用，明确标注信息出处，从而增强答案的可信度与可追溯性。

Piragi支持从哪些地方获取数据？

Piragi支持多种数据源，包括本地文件（如PDF、Word）、远程存储（如S3、GCS）以及直接通过URL进行网络爬取，实现统一的多模态数据处理。

使用Piragi需要复杂的配置吗？

不需要。Piragi是零配置框架，默认使用免费的本地模型（如通过Ollama），开箱即用，无需API密钥或复杂设置即可快速构建RAG应用。