seekdb 快速上手与 SQL 助手

seekdb 是 OceanBase 开源的 AI 原生数据库：MySQL 兼容、完整 ACID，支持嵌入式和服务器两种模式，一条 SQL 即可完成向量 + 全文 + 标量的混合检索，并提供写时复制（COW）的 FORK DATABASE 沙箱。

使用说明

功能：根据用户需求给出可直接运行的 seekdb 安装命令、连接方式、建表语句、混合检索 SQL 和 pyseekdb 代码，并解释每一步的作用。
输入：用户的场景描述（如"做一个文档问答知识库"）、数据字段、向量维度、过滤条件、运行环境（Python / Docker / Linux / macOS）。
输出：分步骤的命令和 SQL/Python 代码块，附注意事项与排错建议。

工作流程

确认场景与环境：问清是嵌入式（进程内，适合原型和端侧）还是服务器模式（多客户端访问）；向量维度多少；是否需要中文全文检索。
安装与连接（按环境选一种）：
- Python（推荐）：pip install -U pyseekdb，嵌入式模式 pyseekdb.Client(path="./my.db")，无需单独起服务。
- Docker：
```
docker run -d --name seekdb -p 2881:2881 -p 2886:2886 \
  -v ./data:/var/lib/oceanbase oceanbase/seekdb:latest
```
- Linux 一键安装或 macOS brew tap oceanbase/seekdb && brew install seekdb；DEB/RPM 离线安装见官方部署文档。
- 服务器模式默认 SQL 端口 2881，用任意 MySQL 客户端连接：mysql -h127.0.0.1 -P2881 -uroot。
建表：向量列用 VECTOR(维度)；中文全文索引用 WITH PARSER ik；向量索引用 HNSW。
写查询：向量距离用 l2_distance（或 cosine_distance、inner_product），近似检索在 ORDER BY ... APPROXIMATE LIMIT k；全文条件用 MATCH ... AGAINST；标量过滤直接写在 WHERE 中，三者在同一执行计划内下推。
检查与调优：用 EXPLAIN 确认走了向量索引；维度必须与建表一致；距离类型要与索引的 DISTANCE 一致。

示例

1. RAG 知识库建表

CREATE TABLE articles (
  id        INT PRIMARY KEY,
  title     TEXT,
  content   TEXT,
  author_id INT,
  created_at DATETIME,
  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;

2. 一条 SQL 的混合检索

SELECT id, title, l2_distance(embedding, '[0.12, 0.34, ...]') AS dist
FROM articles
WHERE MATCH(content) AGAINST('季度报告')
  AND author_id = 42
  AND created_at > '2026-01-01'
ORDER BY dist APPROXIMATE
LIMIT 10;

3. pyseekdb 做 Agent 记忆（自动生成 Embedding）

import pyseekdb

client = pyseekdb.Client(path="./agent_state.db")   # 嵌入式模式
memory = client.get_or_create_collection(name="episodic")

memory.upsert(ids=["obs-1"], documents=["用户喜欢用 Python 写数据处理脚本"])
hits = memory.query(query_texts="用户常用什么语言？", n_results=5)
print(hits)

4. FORK 沙箱：放心试验，满意再合并

FORK DATABASE agent_state TO agent_sandbox_42;      -- 秒级快照，零数据拷贝
USE agent_sandbox_42;
-- 在沙箱里随意读写、改表结构……
MERGE TABLE agent_sandbox_42.memory INTO agent_state.memory STRATEGY THEIRS;  -- 合并回主线（FAIL / THEIRS / OURS）
DROP DATABASE agent_sandbox_42;                     -- 或直接丢弃

常见问题

向量维度不匹配：插入的向量长度必须等于 VECTOR(n) 中的 n。
中文搜不到：全文索引要用 WITH PARSER ik，默认分词器对中文效果差。
近似检索没生效：确认写了 APPROXIMATE，且 ORDER BY 的距离函数与索引 DISTANCE 一致。
Windows 路径含中文时启动失败：把数据目录放在纯英文路径下。

参考

源码与文档：https://github.com/oceanbase/seekdb
官方文档：https://docs.seekdb.ai/
Python SDK：https://github.com/oceanbase/pyseekdb