跳到主要内容
版本：V1.1.0

使用 seekdb 快速构建 RAG

本教程将引导您把 Markdown 文档导入 seekdb，通过 SDK 构建混合检索知识库并通过 Streamlit 启动 RAG 界面。

前提条件​

  • 已安装嵌入式 seekdb。有关 seekdb 的安装，请参见 嵌入式模式。

  • 已安装 Python 3.11 或以上版本。

  • 已安装 uv。如果没有安装，可参考如下命令进行安装：

    curl -LsSf https://astral.sh/uv/install.sh | sh

    # 或者通过 pip 安装
    pip install uv

步骤一：获取 LLM API 密钥​

提示

开通阿里云百炼大模型服务需要您跳转至第三方平台完成。此操作将遵循第三方平台的收费规则，并可能产生相应费用。请在继续前，访问其官网或查阅相关文档，确认并接受其收费标准。如不同意，请勿继续操作。

注册阿里云百炼账号，开通模型服务并获取 API 密钥。

点击开通模型服务

确认开通模型服务

阿里云百炼

获取阿里云百炼 API Key

步骤二：拉取代码​

git clone https://github.com/oceanbase/pyseekdb.git

步骤三：安装依赖​

  1. 进入 pyseekdb/demo/rag 目录。

    cd pyseekdb/demo/rag

  2. 安装依赖

    • 基础安装（适用于 default 或 api embedding 类型）：

      uv sync

    • 包含本地模型支持（适用于 local embedding 类型）：

      uv sync --extra local
    信息

    • local 额外依赖包含 sentence-transformers 及相关依赖（约 2-3GB）。

    • 如果您在中国大陆，可以使用国内镜像源加速下载：

      基础安装（清华源）：uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple 基础安装（阿里源）：uv sync --index-url https://mirrors.aliyun.com/pypi/simple 本地模型（清华源）：uv sync --extra local --index-url https://pypi.tuna.tsinghua.edu.cn/simple 本地模型（阿里源）：uv sync --extra local --index-url https://mirrors.aliyun.com/pypi/simple

步骤四：设置环境变量​

  1. 复制环境变量模板

    cp .env.example .env

  2. 编辑 .env 文件，设置环境变量

    本系统支持三种 Embedding 函数类型，您可以根据需求选择：

    • default（默认，推荐新手使用）

      • 使用 pyseekdb 自带的 DefaultEmbeddingFunction （基于ONNX）。
      • 首次使用会自动下载模型，无需配置 API Key。
      • 适合本地开发和测试。

    • local（本地模型）

      • 使用自定义的 sentence-transformers 模型。
      • 需要安装 sentence-transformers 库。
      • 可配置模型名称和设备（CPU/GPU）。

    • api（API 服务）

      • 使用 OpenAI 兼容的 Embedding API（如 DashScope、OpenAI 等）。
      • 需要配置 API Key 和模型名称。
      • 适合生产环境。

以下使用通义千问作为示例（使用 api 类型）：

# Embedding Function 类型：api, local, default
EMBEDDING_FUNCTION_TYPE=api

# LLM 配置（用于生成答案）
OPENAI_API_KEY=sk-your-dashscope-key
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL_NAME=qwen-plus

# Embedding API 配置（仅在 EMBEDDING_FUNCTION_TYPE=api 时需要）
EMBEDDING_API_KEY=sk-your-dashscope-key
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_MODEL_NAME=text-embedding-v4

# 本地模型配置（仅在 EMBEDDING_FUNCTION_TYPE=local 时需要）
SENTENCE_TRANSFORMERS_MODEL_NAME=all-mpnet-base-v2
SENTENCE_TRANSFORMERS_DEVICE=cpu

# seekdb 配置
SEEKDB_DIR=./data/seekdb_rag
SEEKDB_NAME=test
COLLECTION_NAME=embeddings

参数说明：

变量名说明默认值/示例值必需条件
EMBEDDING_FUNCTION_TYPEEmbedding 函数类型default（可选：api, local, default）必须设置
OPENAI_API_KEYLLM API Key（支持 OpenAI、通义千问等兼容服务）-必须设置（用于生成答案）
OPENAI_BASE_URLLLM API 基础 URLhttps://dashscope.aliyuncs.com/compatible-mode/v1可选
OPENAI_MODEL_NAME语言模型名称qwen-plus可选
EMBEDDING_API_KEYEmbedding API Key-EMBEDDING_FUNCTION_TYPE=api 时必需
EMBEDDING_API_BASE_URLEmbedding API 基础 URLhttps://dashscope.aliyuncs.com/compatible-mode/v1EMBEDDING_FUNCTION_TYPE=api 时必需
EMBEDDING_MODEL_NAMEEmbedding 模型名称text-embedding-v4EMBEDDING_FUNCTION_TYPE=api 时必需
SENTENCE_TRANSFORMERS_MODEL_NAME本地模型名称all-mpnet-base-v2EMBEDDING_FUNCTION_TYPE=local 时必需
SENTENCE_TRANSFORMERS_DEVICE运行设备cpuEMBEDDING_FUNCTION_TYPE=local 时必需
SEEKDB_DIRseekdb 数据库目录./data/seekdb_rag可选
SEEKDB_NAME数据库名称test可选
COLLECTION_NAME嵌入表名称embeddings可选
提示
  • 如果使用 default 类型，只需配置 EMBEDDING_FUNCTION_TYPE=default 和 LLM 相关配置即可。
  • 如果使用 api 类型，需要额外配置 Embedding API 相关变量。
  • 如果使用 local 类型，需要安装 sentence-transformers 库，并可选择配置模型名称。

步骤五：导入数据​

我们使用 pyseekdb 的 SDK 文档作为示例，您也可以使用自己的 Markdown 文档或者目录。

运行数据导入脚本：

# 导入单个文件
uv run python seekdb_insert.py ../../README.md

# 或导入目录下的所有 Markdown 文件
uv run python seekdb_insert.py path/to/your_dir

导入说明：

在此步骤中，系统会执行如下操作：

  • 读取指定的 Markdown 文件或目录下的所有 Markdown 文件。
  • 将文档按标题分割成文本块（使用 # 分隔符）。
  • 根据 .env 中配置的 EMBEDDING_FUNCTION_TYPE 选择相应的 embedding 函数：
    • default: 使用 pyseekdb 自带的 DefaultEmbeddingFunction（首次使用会自动下载模型）。
    • local: 使用自定义的 sentence-transformers 模型。
    • api: 使用配置的 Embedding API 服务。
  • 自动生成文本嵌入向量。
  • 将嵌入向量存储到 seekdb 数据库。
  • 自动跳过失败的文档块，确保批量处理的稳定性。

步骤六：构建 RAG​

通过 Streamlit 启动应用：

uv run streamlit run seekdb_app.py

返回如下：


Collecting usage statistics. To deactivate, set browser.gatherUsageStats to false.


  You can now view your Streamlit app in your browser.

  Local URL: http://localhost:8501
  Network URL: http://xxx.xxx.xxx.19:8501
  External URL: http://xxx.xxx.xxx.143:8501

启动后，您可以在浏览器中访问 RAG 界面，查询您要检索的数据了。

提示

使用 uv 包管理器，请使用 uv run 前缀来运行命令，以确保使用正确的 Python 环境和依赖。

RAG 界面

Contents

编辑此页