跳到主要内容

通过 Python SDK 体验嵌入式

本示例演示如何通过 pyseekdb（OceanBase 提供的 Python 客户端）快速体验嵌入式 seekdb。

背景信息​

pyseekdb​

pyseekdb 是 OceanBase 提供的 Python 客户端。实现了基于一套 API 接口，提供三种数据库连接模式，支持连接到嵌入式模式的 seekdb、服务器模式的 seekdb 和 OceanBase 数据库。

安装此客户端，会同时安装嵌入式模式的 seekdb，使您可以直接连接到嵌入式 seekdb 执行创建数据库等操作。或者选择远程连接到已经部署好的服务器模式的 seekdb 或者 OceanBase 数据库。

seekdb 部署模式​

seekdb 提供了多种灵活的部署模式，从快速原型开发到支撑海量用户，全面满足您的应用需求。

  • 嵌入式模式

    seekdb 以轻量级库的形式嵌入您的应用，支持 pip 一键安装。适用于个人学习、快速原型开发，并可高效运行于多种端侧设备。

  • 服务器模式

    推荐用于测试及生产环境的部署模式，轻量易用，适合稳定高效地提供服务。

    有关服务器模式的使用方式，参见 体验服务器模式 seekdb。

安装 pyseekdb​

前提条件​

请确保您的环境需要满足以下要求：

  • 操作系统：Linux（glibc >= 2.28）
  • Python 版本：Python 3.11 及之后版本
  • 系统架构：x86_64，aarch64

安装​

使用 pip 安装，会自动识别默认的 Python 版本和平台。

pip install pyseekdb

如果您的 pip 版本比较低，请先升级 pip 后再安装。

pip install --upgrade pip

通过 Python SDK 体验 seekdb​

以下示例以嵌入式模式的 seekdb 为例，演示了 Embedding Functions 的基础操作，以帮助您快速了解如何使用 seekdb。

  1. 连接 seekdb。
  2. 创建带有 Embedding Functions 的 collection。
  3. 使用 documents 添加数据（会自动生成 vectors）。
  4. 使用 texts 进行查询（会自动生成 vectors）。
  5. 打印查询结果。
import pyseekdb

# ==================== Step 1: Create Client Connection ====================
# You can use embedded mode, server mode, or OceanBase mode
# For this example, we'll use server mode (you can change to embedded or OceanBase)

# Embedded mode (local SeekDB)
client = pyseekdb.Client()
# Alternative: Server mode (connecting to remote SeekDB server)
# client = pyseekdb.Client(
#     host="127.0.0.1",
#     port=2881,
#     database="test",
#     user="root",
#     password=""
# )

# Alternative: Remote server mode (OceanBase Server)
# client = pyseekdb.Client(
#     host="127.0.0.1",
#     port=2881,
#     tenant="test",  # OceanBase default tenant
#     database="test",
#     user="root",
#     password=""
# )

# ==================== Step 2: Create a Collection with Embedding Function ====================
# A collection is like a table that stores documents with vector embeddings
collection_name = "my_simple_collection"

# Create collection with default embedding function
# The embedding function will automatically convert documents to embeddings
collection = client.create_collection(
    name=collection_name,
)

print(f"Created collection '{collection_name}' with dimension: {collection.dimension}")
print(f"Embedding function: {collection.embedding_function}")

# ==================== Step 3: Add Data to Collection ====================
# With embedding function, you can add documents directly without providing embeddings
# The embedding function will automatically generate embeddings from 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}
    ]
)

print(f"\nAdded {len(documents)} documents to collection")
print("Note: Embeddings were automatically generated from documents using the embedding function")

# ==================== Step 4: Query the Collection ====================
# With embedding function, you can query using text directly
# The embedding function will automatically convert query text to query vector

# Query using text - query vector will be auto-generated by embedding function
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")

# ==================== Step 5: Print Query Results ====================
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]}")

# ==================== Step 6: Cleanup ====================
# Delete the collection
client.delete_collection(collection_name)
print(f"\nDeleted collection '{collection_name}'")

更多信息​

  • 有关 pyseekdb 更详细的介绍和使用介绍，参见 pyseekdb。

  • 有关更多 pyseekdb 的使用示例参见：

  • 除了 Python SDK 之外，seekdb 也支持通过 SQL 进行操作，有关 SQL 的使用方法，参见 体验服务器模式 seekdb。

Contents

编辑此页