一条查询，掌控一切

| 文档 | 博客 | Discord |

---

Korvus 是一个搜索 SDK，它将整个 RAG 流程统一到一条数据库查询中。Korvus 构建在 Postgres 之上，并提供了 Python、JavaScript 和 Rust 的绑定，能够在几乎无需考虑基础设施的情况下，提供高性能且可定制的搜索功能。

📕 目录

• 🦅 Korvus 是什么？
• 🔠 支持的语言
• 🏆 为什么选择 Korvus？
• ⚡ 核心特性
• 🧩 系统架构
• 🚀 开始使用
• 🔍 SQL 的力量
• 📘 文档
• 🌐 社区
• 🤝 贡献

https://github.com/postgresml/korvus/assets/19626586/2b697dc6-8c38-41a7-8c8e-ef158dacb29b

🦅 Korvus 是什么？

Korvus 是一个为 Postgres 打造的一体化开源 RAG（检索增强生成）管道。它将 LLM、向量存储、嵌入生成、重排序、摘要生成以及自定义模型整合到一条查询中，从而最大化性能并简化您的搜索架构。

🔠 支持的语言

Korvus 提供多语言 SDK 支持，使您能够无缝集成到现有的技术栈中：

• Python：PyPI 包
• JavaScript：npm 包
• Rust：Crates.io 包
• C：从源码构建

🏆 为什么选择 Korvus？

Korvus 凭借其充分利用 Postgres 功能进行 RAG 操作的能力而脱颖而出：

1. 原生 Postgres RAG：Korvus 充分利用 Postgres 强大的功能，让您直接在数据库内执行复杂的 RAG 操作。这种方法无需外部服务和 API 调用，从而显著降低延迟并大幅简化架构。

2. 单条查询高效性：借助 Korvus，您的整个 RAG 流程——从嵌入生成到文本生成——都可以通过一条 SQL 查询完成。“一条查询，掌控一切”的方式简化了架构并提升了性能。

3. 可扩展性和高性能：基于 Postgres 构建的 Korvus 继承了其出色的可扩展性和性能特点。随着数据的增长，Korvus 也能随之扩展，即使在大规模数据集上仍能保持高性能。

⚡ 核心特性

• 简化架构：用一条强大的查询取代复杂的服务导向架构。
• 高性能：消除 API 调用和数据移动，实现更快的处理速度和更高的可靠性。
• 开源：通过开源软件和可在 Docker 中本地运行的模型，提升开发体验。
• 多语言支持：您可以使用 Python、JavaScript 和 Rust 来操作 Korvus。如需其他语言支持，请提交议题投票。
• 统一流程：将嵌入生成、向量搜索、重排序和文本生成整合到同一条查询中。
• Postgres 驱动：Korvus 的底层操作由经过时间考验的数据库平台上高效的 SQL 查询驱动。

🧩 系统架构

Korvus 利用 PostgresML 的 pgml 扩展和 pgvector 扩展，将整个 RAG 流程压缩到 Postgres 数据库内部。

🚀 开始使用

📋 前提条件

要使用 Korvus，您需要一个已安装 pgml 和 pgvector 的 Postgres 数据库。您有两种选择：

1. 自托管：自行搭建包含 pgml 和 pgvector 的数据库。

   • 有关说明，请参阅我们的自托管指南。

2. 托管服务：使用我们预装了 pgml 和 pgvector 的托管 Postgres 服务。

   • 注册 PostgresML Cloud。

🏁 快速入门

1. 安装 Korvus：

pip install korvus

2. 设置 KORVUS_DATABASE_URL 环境变量：

export KORVUS_DATABASE_URL="{YOUR DATABASE CONNECTION STRING}"

3. 初始化集合和管道：

from korvus import Collection, Pipeline
import asyncio

collection = Collection("korvus-demo-v0")
pipeline = Pipeline(
    "v1",
    {
        "text": {
            "splitter": {"model": "recursive_character"},
            "semantic_search": {"model": "Alibaba-NLP/gte-base-en-v1.5"},
        }
    },
)

async def add_pipeline():
    await collection.add_pipeline(pipeline)

asyncio.run(add_pipeline())

4. 插入文档：

async def upsert_documents():
    documents = [
        {"id": "1", "text": "Korvus 非常快速且易于使用。"},
        {"id": "2", "text": "番茄放在汉堡上非常美味。"},
    ]
    await collection.upsert_documents(documents)

asyncio.run(upsert_documents())

5. 执行 RAG：

async def rag():
    query = "Korvus 快吗？"
    print(f"正在查询关于：{query} 的回答")
    results = await collection.rag(
        {
            "CONTEXT": {
                "vector_search": {
                    "query": {
                        "fields": {"text": {"query": query}},
                    },
                    "document": {"keys": ["id"]},
                    "limit": 1,
                },
                "aggregate": {"join": "\n"},
            },
            "chat": {
                "model": "meta-llama/Meta-Llama-3-8B-Instruct",
                "messages": [
                    {
                        "role": "system",
                        "content": "你是一个友好且乐于助人的聊天机器人",
                    },
                    {
                        "role": "user",
                        "content": f"根据以下上下文\n:{{CONTEXT}}\n请回答问题：{query}",
                    },
                ],
                "max_tokens": 100,
            },
        },
        pipeline,
    )
    print(results)

asyncio.run(rag())

🔍 SQL 的强大之处

尽管 Korvus 提供了多种编程语言的高级接口，但其核心操作却是基于优化后的 SQL 查询构建的。这种方法带来了多项优势：

• 透明性：高级用户可以查看并理解底层查询。
• 可定制性：通过修改或扩展其 SQL 操作，进一步增强 Korvus 的功能。
• 性能：充分利用 PostgreSQL 先进的查询优化能力。

即使您不是 SQL 专家也不用担心——Korvus 直观的 API 抽象掉了复杂性，同时仍能让您充分发挥基于 SQL 操作的强大能力。

📘 文档

如需全面的文档，包括 API 参考、教程和最佳实践，请访问我们的官方文档。

🌐 社区

加入我们的社区，获取帮助、分享想法并参与贡献：

• Discord
• Twitter

🤝 贡献

我们欢迎对 Korvus 的贡献！在提交拉取请求之前，请先阅读我们的贡献指南。

---

Korvus 由 PostgresML 维护。如需企业级支持与咨询服务，请联系我们。

Korvus 快速上手指南

Korvus 是一个基于 PostgreSQL 构建的开源 RAG（检索增强生成）SDK。它能够将嵌入生成、向量搜索、重排序和文本生成等整个 RAG 流程统一在单个数据库查询中完成，从而极大简化架构并提升性能。

环境准备

在使用 Korvus 之前，你需要一个安装了 pgml 和 pgvector 扩展的 PostgreSQL 数据库。你可以选择以下两种方式之一：

1. 自托管（Self-hosted）

   • 自行部署带有必要扩展的数据库。
   • 参考官方 Docker 快速启动指南：Self-hosting Guide

2. 托管服务（Hosted Service）

   • 直接使用预装好扩展的 PostgresML Cloud 服务。
   • 注册地址：PostgresML Cloud

前置依赖：

• Python 3.8+
• 可用的 PostgreSQL 连接字符串

安装步骤

使用 pip 安装 Korvus Python SDK：

pip install korvus

提示：如果下载速度较慢，可以使用国内镜像源加速安装：

pip install korvus -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，设置数据库连接环境变量：

export KORVUS_DATABASE_URL="{YOUR DATABASE CONNECTION STRING}"

(请将 {YOUR DATABASE CONNECTION STRING} 替换为你实际的数据库连接地址)

基本使用

以下示例展示了如何初始化集合与管道、插入文档以及执行 RAG 查询的最简流程。

1. 初始化集合与管道

from korvus import Collection, Pipeline
import asyncio

collection = Collection("korvus-demo-v0")
pipeline = Pipeline(
    "v1",
    {
        "text": {
            "splitter": {"model": "recursive_character"},
            "semantic_search": {"model": "Alibaba-NLP/gte-base-en-v1.5"},
        }
    },
)

async def add_pipeline():
    await collection.add_pipeline(pipeline)

asyncio.run(add_pipeline())

2. 插入文档

async def upsert_documents():
    documents = [
        {"id": "1", "text": "Korvus is incredibly fast and easy to use."},
        {"id": "2", "text": "Tomatoes are incredible on burgers."},
    ]
    await collection.upsert_documents(documents)

asyncio.run(upsert_documents())

3. 执行 RAG 查询

async def rag():
    query = "Is Korvus fast?"
    print(f"Querying for response to: {query}")
    results = await collection.rag(
        {
            "CONTEXT": {
                "vector_search": {
                    "query": {
                        "fields": {"text": {"query": query}},
                    },
                    "document": {"keys": ["id"]},
                    "limit": 1,
                },
                "aggregate": {"join": "\n"},
            },
            "chat": {
                "model": "meta-llama/Meta-Llama-3-8B-Instruct",
                "messages": [
                    {
                        "role": "system",
                        "content": "You are a friendly and helpful chatbot",
                    },
                    {
                        "role": "user",
                        "content": f"Given the context\n:{{CONTEXT}}\nAnswer the question: {query}",
                    },
                ],
                "max_tokens": 100,
            },
        },
        pipeline,
    )
    print(results)

asyncio.run(rag())

运行上述代码后，Korvus 将在数据库内部完成从向量检索到 LLM 生成的全过程，并返回最终结果。