通过 SDK 快速体验向量搜索
本示例以 Linux 环境为例演示如何通过 pyseekdb（OceanBase 提供的 Python 客户端）的嵌入式 seekdb 快速体验向量搜索。
除了 Linux 系统之外，也支持在 macOS 和 Windows 系统下使用 pyseekdb。但当前 Windows 系统仅支持使用服务器模式 seekdb。有关 macOS 和 Windows 系统下的使用介绍，参见 pyseekdb 快速开始。
在本示例中，我们将进行以下操作：
- 部署 pyseekdb 和 嵌入式 seekdb。
- 连接 seekdb 并创建数据库。
- 连接到数据库并创建带有 Embedding Functions 的 collection。
- 使用 documents 添加数据（会自动生成 vectors）。
- 执行向量搜索（会自动生成 vectors）并打印查询结果。
- 清理环境。
背景信息
pyseekdb
pyseekdb 是 OceanBase 提供的 Python 客户 端。实现了基于一套 API 接口，提供三种数据库连接模式，支持连接到嵌入式模式的 seekdb、服务器模式的 seekdb 和 OceanBase 数据库。
安装此客户端，会同时安装嵌入式模式的 seekdb，使您可以直接连接到嵌入式 seekdb 执行创建数据库等操作。或者选择远程连接到已经部署好的服务器模式的 seekdb 或者 OceanBase 数据库。
seekdb 部署模式
seekdb 提供了多种灵活的部署模式，从快速原型开发到支撑海量用户，全面满足您的应用需求。
-
嵌入式模式
seekdb 以轻量级库的形式嵌入您的应用，支持 pip 一键安装。适用于个人学习、快速原型开发，并可高效运行于多种端侧设备。
-
服务器模式
推荐用于测试及生产环境的部署模式，轻量易用，适合稳定高效地提供服务。
有关服务器模式的使用方式，参见 通过 SQL 快速体验服务器模式 seekdb。
步骤一：安装 pyseekdb 并部署嵌入式 seekdb
前提条件
请确保您的环境需要满足以下要求：
- 操作系统：Linux（glibc >= 2.28）
- Python 版本：Python 3.11 及之后版本
- 系统架构：x86_64，aarch64
安装
使用 pip 安装，会自动识别默认的 Python 版本和平台。
pip install -U pyseekdb
如果您的 pip 版本比较低，请先升级 pip 后再安装。
pip install --upgrade pip
安装 pyseekdb 的同时也会安装嵌入式模式的 seekdb，使您可以直接连接到嵌入式 seekdb 执行创建数据库等操作。
步骤二：连接 seekdb 并创建数据库
使用 Admin Client 连接到 seekdb 并创建名为 query_test 的数据库。
-
关于 Admin Client 的详细介绍，参见 Admin Client。
-
关于创建数据库的详细介绍，参见 create_database - 创建数据库。
import pyseekdb
# Create embedded admin client
admin = pyseekdb.AdminClient(path="./seekdb.db")
# Create database
admin.create_database("query_test")
步骤三：连接数据库并创建带有 Embedding Functions 的 collection
使用 Client 连接到 query_test 数据库并创建 collection。
- 关于 Client 的详细介绍，参见 Client。
- 关于创建 collection 的详细介绍，参见 create_collection - 创建 Collection。
import pyseekdb
# Create embedded client
client = pyseekdb.Client(path="./seekdb.db", database="query_test")
# Create collection
collection = client.create_collection(
name="query_demo"
)
步骤四：插入数据
使用 add 方法向 collection 中插入数据。
关于插入数据的详细介绍，参见 add - 插入数据。
import pyseekdb
# Create embedded client
client = pyseekdb.Client(path="./seekdb.db", database="query_test")
# get collection
collection = client.get_collection("query_demo")
# Define documents
documents = [
"Machine learning is a subset of artificial intelligence",
"Python is a popular programming language",
"Vector databases enable semantic search",
"Neural networks are inspired by the human brain",
"Natural language processing helps computers understand text"
]
ids = ["id1", "id2", "id3", "id4", "id5"]
# Add data with documents only - embeddings will be auto-generated by embedding function
collection.add(
ids=ids,
documents=documents, # embeddings will be automatically generated
metadatas=[
{"category": "AI", "index": 0},
{"category": "Programming", "index": 1},
{"category": "Database", "index": 2},
{"category": "AI", "index": 3},
{"category": "NLP", "index": 4}
]
)
步骤五：执行向量搜索并打印查询结果
使用 query 方法进行向量搜索查询，并打印查询结果。
关于向量检索的详细介绍，参见 query - 向量搜索。
import pyseekdb
# Create embedded client
client = pyseekdb.Client(path="./seekdb.db", database="query_test")
# get collection
collection = client.get_collection("query_demo")
# Perform query
query_text = "artificial intelligence and machine learning"
results = collection.query(
query_texts=query_text, # Query text - will be embedded automatically
n_results=3 # Return top 3 most similar documents
)
print(f"\nQuery: '{query_text}'")
print(f"Query results: {len(results['ids'][0])} items found")
for i in range(len(results['ids'][0])):
print(f"\nResult {i+1}:")
print(f" ID: {results['ids'][0][i]}")
print(f" Distance: {results['distances'][0][i]:.4f}")
if results.get('documents'):
print(f" Document: {results['documents'][0][i]}")
if results.get('metadatas'):
print(f" Metadata: {results['metadatas'][0][i]}")
步骤六：清理环境
如果您不再需要使用上述示例数据库和 collection，可以使用 delete_collection 方法删除 collection 以及使用 delete_database 方法删除数据库。
-
关于删除 collection 的详细介绍，参见 delete_collection - 删除 Collection。
-
关于删除数据库的详细介绍，参见 delete_database - 删除数据库。
import pyseekdb
# Create embedded client
admin = pyseekdb.AdminClient(path="./seekdb.db")
client = pyseekdb.Client(path="./seekdb.db", database="query_test")
# Delete collection
client.delete_collection("query_demo")
print(f"\nDeleted collection")
# Delete database
admin.delete_database("query_test")
print(f"\nDeleted database")
完整示例
import pyseekdb
#==================== Create Database ====================
# Create embedded admin client
admin = pyseekdb.AdminClient(path="./seekdb.db")
# Create database
admin.create_database("query_test")
# ==================== Create Collection ====================
# Create embedded client
client = pyseekdb.Client(path="./seekdb.db", database="query_test")
# Create collection
collection = client.create_collection(
name="query_demo"
)
# ==================== Add Data to Collection ====================
# Define documents
documents = [
"Machine learning is a subset of artificial intelligence",
"Python is a popular programming language",
"Vector databases enable semantic search",
"Neural networks are inspired by the human brain",
"Natural language processing helps computers understand text"
]
ids = ["id1", "id2", "id3", "id4", "id5"]
# Add data with documents only - embeddings will be auto-generated by embedding function
collection.add(
ids=ids,
documents=documents, # embeddings will be automatically generated
metadatas=[
{"category": "AI", "index": 0},
{"category": "Programming", "index": 1},
{"category": "Database", "index": 2},
{"category": "AI", "index": 3},
{"category": "NLP", "index": 4}
]
)
# ==================== Perform Query ====================
# Perform Query
query_text = "artificial intelligence and machine learning"
results = collection.query(
query_texts=query_text, # Query text - will be embedded automatically
n_results=3 # Return top 3 most similar documents
)
print(f"\nQuery: '{query_text}'")
print(f"Query results: {len(results['ids'][0])} items found")
for i in range(len(results['ids'][0])):
print(f"\nResult {i+1}:")
print(f" ID: {results['ids'][0][i]}")
print(f" Distance: {results['distances'][0][i]:.4f}")
if results.get('documents'):
print(f" Document: {results['documents'][0][i]}")
if results.get('metadatas'):
print(f" Metadata: {results['metadatas'][0][i]}")
# ==================== Cleanup ====================
# Delete collection
client.delete_collection("query_demo")
print(f"\nDeleted collection")
# Delete database
admin.delete_database("query_test")
print(f"\nDeleted database")
更多信息
-
有关 pyseekdb 更详细的介绍和使用介绍，参见 pyseekdb。
-
有关更多 pyseekdb 的使用示例参见：
-
Simple 示例：演示了 pyseekdb 的向量搜索能力。
-
Complete 示例：演示了当前 pyseekdb 支持的全量能力。
-
混合搜索示例：演示了 seekdb 混合搜索的使用，同时与向量检索的能力对比。
-
除了 Python SDK 之外，seekdb 也支持通过 SQL 进行操作，有关 SQL 的使用方法，参见 通过 SQL 快速体验向量搜索 和 通过 SQL 快速体验混合搜索 。