seekdb 实战手册

seekdb 是 OceanBase 团队开源的 AI 原生数据库（Apache-2.0）：MySQL 协议兼容，单引擎同时支持向量、全文、结构化三类检索，并提供 FORK DATABASE 的写时复制沙箱。

什么时候用这个技能

要给 RAG / Agent 应用搭一个「能存能查」的数据底座，不想再拼「向量库 + 搜索引擎 + MySQL」
要在一条 SQL 里同时做语义相似度和关键词过滤
要让 Agent 在数据库里大胆试错（改表、写脏数据），又能一键回滚
装 seekdb 时卡在启动、连接、驱动兼容问题上

一、跑起来（三选一）

1. Docker（最快验证）

docker run -d --name seekdb \
  -p 2881:2881 \
  -p 2886:2886 \
  -v ./data:/var/lib/oceanbase \
  oceanbase/seekdb:latest

2881：MySQL 协议端口
2886：Web 控制台
首次启动要建数据目录，属正常慢启动；用 docker logs -f seekdb 看进度

2. Python 嵌入式（无需部署服务）

python3 -m pip install -U pylibseekdb pymysql

from contextlib import closing
import pylibseekdb, pymysql

with closing(pylibseekdb.open("./seekdb.db")) as db:
    options = db.connection_options()          # host/port/user/password/socket
    with pymysql.connect(database="test", autocommit=True,
                         cursorclass=pymysql.cursors.DictCursor, **options) as conn:
        with conn.cursor() as cur:
            cur.execute("SELECT 1")
            print(cur.fetchone())

要求 Python ≥ 3.11；数据落在本地目录，重开进程数据还在。

3. 高层 SDK

pip install -U pyseekdb            # Python：Collection API，自带 embedding + 混合检索
npm install @oceanbase/seekdb-node mysql2

二、建表：一张表同时有三种索引

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

要点：

VECTOR(384) 的维度必须和你的 embedding 模型输出一致（bge-small 是 384，bge-m3 是 1024）
DISTANCE 可选 l2 / cosine / ip，要和训练时用的度量一致
全文解析器 ik 适合中文；纯英文可以不写 WITH PARSER
不写 ORGANIZATION = HEAP 时按默认组织方式建表

三、混合检索：一条 SQL 搞定

-- 向量相似度 + 全文关键词，一次查询
SELECT id, title,
       l2_distance(embedding, '[0.12, 0.34, ...]') AS dist
FROM articles
WHERE MATCH(content) AGAINST('quarterly report')
ORDER BY dist APPROXIMATE
LIMIT 10;

-- 再加标量过滤（业务条件直接 AND 上去）
SELECT id, title, category
FROM articles
WHERE MATCH(content) AGAINST('财报')
  AND category = 'finance'
  AND publish_date >= '2026-01-01'
ORDER BY l2_distance(embedding, '[0.12, 0.34, ...]') APPROXIMATE
LIMIT 10;

APPROXIMATE 走 HNSW 近似检索，要精确结果就去掉它（会退化成精确扫描，慢）
过滤条件尽量写成能在执行计划里下推的形式，别在 SQL 里对列做函数运算
写入的向量当场可查：增量 HNSW 不需要等后台重建索引

四、FORK DATABASE：Agent 的安全沙箱

-- 秒级克隆整个库，底层是写时复制，不复制数据
FORK DATABASE agent_state TO agent_sandbox_42;

-- 在沙箱里随便折腾
INSERT INTO agent_sandbox_42.memory (session_id, embedding, content)
VALUES ('s1', '[0.1, 0.2, ...]', 'hello');

-- 实验成功：把结果并回主库
MERGE TABLE agent_sandbox_42.memory INTO agent_state.memory STRATEGY THEIRS;

-- 实验失败：直接丢弃
DROP DATABASE agent_sandbox_42;

适合：Agent 试错、灰度数据、评测跑批、给每个用户开一份独立副本。

五、常见坑

| 现象 | 原因 / 处理 | |---|---| | 冷启动偶发 OB_TIMEOUT (-4012)（Windows 尤其明显） | 冷缓存下元数据 I/O 慢，单条 SQL 吃满默认超时。升级到包含 bootstrap 超时修复的版本，或调大 rpc_timeout | | Malformed packet / 驱动连不上 | MySQL 驱动版本过新。mysql-connector-python 用 9.4 左右、pymysql 直接可用；必要时加 use_pure=True | | docker 里连 2881 被拒 | 确认端口映射，以及 Windows 侧 WSL/Docker 的网络模式（networkingMode=mirrored 才能用 127.0.0.1 直连） | | VECTOR(n) 报维度不匹配 | n 必须等于 embedding 输出维度 | | 全文检索命中中文很差 | 建索引时加上 WITH PARSER ik | | 想连 BI / ORM 工具 | 用 MySQL 协议即可：host、port 2881、库名照填，SQLAlchemy 用 mysql+pymysql:// |

六、参考

仓库：https://github.com/oceanbase/seekdb
文档：https://docs.seekdb.ai/
Docker 镜像说明：https://github.com/oceanbase/docker-images/blob/main/seekdb/README.md