korvus

环境要求

• Python 环境（可通过 pip 安装包）
• 一个可用的 Postgres 数据库连接串（Korvus 基于 Postgres 运行）
• pip 包管理工具
• 能访问嵌入模型与 LLM 服务的网络环境

安装与启动步骤

1. 1安装 Korvus SDK

   使用 pip 从 PyPI 安装 korvus，同时获得 Python 绑定。建议在虚拟环境中执行。

   pip install korvus

   复制

2. 2配置数据库连接

   把 KORVUS_DATABASE_URL 设为你的 Postgres 连接串，README 要求用该环境变量传入。

   export KORVUS_DATABASE_URL="postgres://user:password@host:5432/dbname"

   复制

3. 3初始化集合与流水线

   创建 Collection 并定义 Pipeline，指定文本切分器与语义检索模型，然后异步注册流水线。

   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. 4写入文档

   用 upsert_documents 批量插入带 id 与 text 的文档，SDK 会自动完成切分与向量化。

   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())

   复制

5. 5执行 RAG 查询

   调用 collection.rag()，一次查询内完成向量检索与 LLM 生成，返回最终回答。

   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())

   复制

关键配置

如何确认成功

运行最后一段 RAG 脚本，终端能打印出查询与 results（模型基于检索上下文生成的回答），即表示流程跑通。

常见问题

注意事项

• README 只提供 pip 安装方式，未提供 Docker、源码编译或 Rust/JS 绑定的安装命令，请勿自行臆造。
• 所有示例都是异步接口，脚本中必须用 asyncio.run 驱动。
• Pipeline 的嵌入模型与 chat 的 LLM 首次调用可能需要下载或联网，注意网络与耗时。
• 更多用法见官方文档 https://postgresml.org/docs/open-source/korvus/