SeekDB / pyseekdb 快速上手

帮助 Agent 快速写出可运行的 pyseekdb 示例，并避开常见 API 踩坑。

何时使用

用户要本地/嵌入式向量库 demo
用户问 pyseekdb 怎么建库、插入、检索
用户把 search 当检索 API、忘了 refresh_index、embeddings 维度对不上

安装

pip install pyseekdb

两种用法（先选模式）

| 模式 | 适用 | 关键点 | |------|------|--------| | A. 自动 embedding | 直接塞文本做语义检索 | create_collection 用默认 embedding；add(documents=...)；query(query_texts=...) | | B. 手动向量 | 已有向量、要控维度/距离 | HNSWConfiguration(dimension=..., distance=...)；embedding_function=None；add(embeddings=...)；query(query_embeddings=...) |

完整可运行示例见：

examples/auto_embedding.py — 模式 A
examples/manual_vectors.py — 模式 B

连接方式速查

import pyseekdb

# 嵌入式（本地）
client = pyseekdb.Client()

# 指定库
client = pyseekdb.Client(database="test_db")

# 远程 / OceanBase（按环境改）
# client = pyseekdb.Client(host="127.0.0.1", port=2881, tenant="test",
#                          database="test", user="root", password="")

需要先建库时：

admin = pyseekdb.AdminClient()
try:
    admin.create_database("test_db")
except Exception:
    pass  # 已存在可忽略

模式 A：文档 + 自动 embedding

import pyseekdb

client = pyseekdb.Client()
coll = client.create_collection(name="my_simple_collection")

coll.add(
    ids=["id1", "id2"],
    documents=[
        "Machine learning is a subset of artificial intelligence",
        "Vector databases enable semantic search",
    ],
    metadatas=[{"category": "AI"}, {"category": "Database"}],
)

results = coll.query(query_texts="artificial intelligence", n_results=2)
# results["ids"][0], results["distances"][0], results.get("documents")

模式 B：手动向量（无内置 embedding）

import pyseekdb
from pyseekdb import HNSWConfiguration
import numpy as np

client = pyseekdb.Client(database="test_db")
config = HNSWConfiguration(dimension=4, distance="cosine")
coll = client.get_or_create_collection(
    name="test_coll",
    configuration=config,
    embedding_function=None,
)

vecs = np.array([
    [0.1, 0.2, 0.3, 0.4],
    [0.2, 0.3, 0.4, 0.5],
], dtype=np.float32).tolist()  # 必须是 Python list

coll.add(ids=["1", "2"], embeddings=vecs)
coll.refresh_index()  # 异步索引刷新后再查

res = coll.query(
    query_embeddings=[0.15, 0.25, 0.35, 0.45],
    n_results=2,
)
print(res["ids"][0], res["distances"][0])

必守规则（踩坑清单）

检索 API 是 query，不是 search。
手动向量写入后先 refresh_index()，再 query。
embeddings 用 list（.tolist()），不要直接塞未转换的 numpy 对象（按 SDK 签名）。
ids 用字符串。
手动模式维度必须与 HNSWConfiguration(dimension=...) 一致；查询向量维度同理。
手动模式务必 embedding_function=None，并走 embeddings / query_embeddings。
集合脏了就删再建： has_collection → delete_collection → get_or_create_collection。

结果读取约定

query 返回字典，批量维在外层：

results["ids"][0] — 本条查询的命中 id 列表
results["distances"][0] — 对应距离
results.get("documents") / results.get("metadatas") — 有则取 [0][i]

Agent 输出要求

生成代码时：

先问清模式 A 还是 B（用户没说则默认 A 做语义检索 demo）。
给出完整可运行脚本，含 import 与打印结果。
模式 B 必须包含 refresh_index()。
注释里点明「用 query 不是 search」。
需要清理时调用 delete_collection。

最小自检

[ ] pip install pyseekdb 后脚本可运行
[ ] 模式正确（documents/query_texts 或 embeddings/query_embeddings）
[ ] 手动向量路径含 refresh_index
[ ] 打印了 ids 与 distances