seekdb 快速上手技能

本技能提供从零上手 OceanBase seekdb 的标准流程与可直接复用的代码模板。seekdb 是 AI 原生的状态存储：MySQL 兼容、嵌入式/服务器双模式、支持向量 + 全文 + 标量的混合检索，并提供 FORK/MERGE 的 COW 沙箱能力。

何时使用本技能

为 AI Agent 搭建记忆/状态存储（持续写入 + 毫秒级检索）
构建 RAG 知识检索（向量 + 全文 + 标量过滤一条 SQL 完成）
需要在沙箱中安全实验、随时回滚数据（FORK DATABASE / MERGE / DROP）
在本地/边缘环境以嵌入式方式运行数据库，或通过 Docker 部署服务器模式

1. 安装

# Python SDK（嵌入式模式，进程内运行，无需服务器）
pip install -U pyseekdb

其他方式：

# Docker 服务器模式
docker run -d --name seekdb -p 2881:2881 -p 2886:2886 \
  -v ./data:/var/lib/oceanbase oceanbase/seekdb:latest

# Linux 一键安装 / macOS Homebrew
curl -fsSL https://obportal.s3.ap-southeast-1.amazonaws.com/download-center/opensource/seekdb/seekdb_install.sh | bash
brew tap oceanbase/seekdb && brew install seekdb

2. 嵌入式模式快速开始（Python）

import pyseekdb

# 嵌入式：数据保存在本地文件，进程内直接读写
client = pyseekdb.Client(path="./agent_state.db")

# 获取或创建集合（类似表；无需预先定义 schema）
memory = client.get_or_create_collection(name="episodic")

# 写入/更新（自动生成 embedding）
memory.upsert(
    ids=["step-1", "step-2"],
    documents=["用户偏好：中文回答", "任务：整理季度报表"],
)

# 向量检索（语义相似）
res = memory.query(query_texts="季度报表怎么整理", n_results=3)
print(res)

Agent 记忆循环模式：

for step in agent_run():
    memory.upsert(ids=[step.id], documents=[step.observation])
    relevant = memory.query(query_texts=step.next_query, n_results=5)
    agent.act(relevant)

3. SQL 混合检索（向量 + 全文 + 标量）

-- 建表：向量列 + 全文索引 + HNSW 向量索引
CREATE TABLE articles (
  id        INT PRIMARY KEY,
  title     TEXT,
  content   TEXT,
  author_id INT,
  embedding VECTOR(384),
  FULLTEXT INDEX idx_fts (content) WITH PARSER ik,
  VECTOR   INDEX idx_vec (embedding) WITH (DISTANCE=l2, TYPE=hnsw, LIB=vsag)
) ORGANIZATION = HEAP;

-- 一条 SQL 完成混合搜索：全文匹配 + 向量排序
SELECT id, title,
       l2_distance(embedding, '[0.12, 0.34, ...]') AS dist
FROM articles
WHERE MATCH(content) AGAINST('quarterly report')
  AND author_id = 42
ORDER BY dist APPROXIMATE
LIMIT 10;

Python 侧可用 SQLAlchemy 或任意 MySQL 驱动连接（服务器模式默认端口 2881）。

4. COW 沙箱（Fork / Merge / Drop）

-- 秒级整库快照（写时复制，无数据拷贝）
FORK DATABASE agent_state TO agent_sandbox_42;

-- 在沙箱中随意实验：写入、改表、甚至破坏结构
USE agent_sandbox_42;
INSERT INTO memory (session_id, embedding, content) VALUES (...);

-- 接受成果：迁移回主线（策略：FAIL / THEIRS / OURS）
MERGE TABLE agent_sandbox_42.memory INTO agent_state.memory STRATEGY THEIRS;

-- 或者直接丢弃整个沙箱
DROP DATABASE agent_sandbox_42;

适合场景：Agent 执行高风险操作前先 FORK，出错回滚，成功合并。

5. 常见问题

写入后马上能查到吗？ 能。异步索引流水线（Change Stream + 增量 HNSW）让新写入立即可搜索，写入提交即返回。
需要自己配 Embedding 服务吗？ 不需要，嵌入式模式内置默认 embedding；也可按需接入自定义模型。
和 Milvus/Elasticsearch 的区别？ seekdb 一条 SQL 同时支持向量、全文、标量过滤，并自带 SQL/ACID/MySQL 协议，无需多套系统拼接。
要装 OceanBase 吗？ 嵌入式模式不需要；分布式场景可对接 OceanBase。

6. 参考

seekdb 文档：https://docs.seekdb.ai/
seekdb 源码：https://github.com/oceanbase/seekdb
pyseekdb 指南：https://github.com/oceanbase/pyseekdb