seekdb SQL 问题诊断助手

Overview

seekdb 是 OceanBase 开源的 MySQL 兼容 AI 数据库，支持向量 + 全文 + 标量混合检索和 FORK/MERGE 写时复制沙箱。本 Skill 提供一套按顺序执行的诊断管线：先确认部署形态和连通性，再定位 SQL 层问题，最后给出最小复现。适用于把 seekdb 用作 Agent 状态存储、RAG 检索后端的开发和比赛场景。

官方资源：github.com/oceanbase/seekdb · docs.seekdb.ai · Python SDK pyseekdb

第 1 步：确认部署形态

三种形态的连接方式完全不同，先问清楚/探测清楚再诊断：

| 形态 | 特征 | 连接方式 | |------|------|----------| | 嵌入式 (pyseekdb) | 无服务端进程，pyseekdb.Client(path="./xx.db") | 进程内直连，无端口 | | 单机服务 / Docker | 监听 2881（SQL）和 2886 | mysql -h127.0.0.1 -P2881 -uroot（默认 root 空密码） | | 源码开发部署 | 端口常见为 10000 | mysql -h127.0.0.1 -P10000 -uroot，或仓库自带 obclient |

Docker 形态快速核验：

docker ps --format '{{.Names}} {{.Image}} {{.Ports}} {{.Status}}' | grep -i seekdb
# 期望：oceanbase/seekdb 镜像在运行，2881 已映射
mysql -h127.0.0.1 -P2881 -uroot -e "SELECT version();"

连不上时按顺序排查：

端口被占/未映射：docker logs seekdb --tail 50 看启动是否完成（observer 首次启动需初始化，端口未就绪不代表失败，等启动完成再试）。
密码：standalone/Docker 默认 root 空密码，不要加 -p 交互输密码；若自行设置过密码则以实际为准。
多实例冲突：本机同时跑过 OceanBase 和 seekdb 时 2881 会撞端口，把 seekdb 映射到别的宿主端口（如 -p 13307:2881）并同步改连接命令。

第 2 步：向量检索问题定位

建表参考（维度、索引参数都在 DDL 里显式声明）：

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;

常见症状与原因：

写入报维度不匹配：插入的向量长度 ≠ DDL 里 VECTOR(n) 的 n。换 embedding 模型（如 384 维换 768 维）后必须重建表或新加列，向量维度不可原地修改。
ORDER BY ... APPROXIMATE 报错或退化为精确扫描：APPROXIMATE 近似排序要求排序表达式是 距离函数(带向量索引的列, 常量向量) 形态，且距离函数要与索引的 DISTANCE 参数一致（l2 索引用 l2_distance）。
刚写入的数据检索不到/分数异常：seekdb 索引由异步管线（Change Stream）构建，正常情况写入后毫秒级可查（增量 HNSW 立即可搜）；若长时间查不到，确认没有把 seekdb 与需要手动重建索引的其他向量库行为混淆，并检查服务端日志。
JSON 数组格式：向量字面量是字符串形式的 JSON 数组，如 '[0.12,0.34,...]'，注意引号包裹。

混合检索（向量 + 全文 + 标量过滤）应在一条 SQL 内完成，避免客户端合并：

SELECT id, title, l2_distance(embedding, '[0.12,0.34]') AS dist
FROM articles
WHERE MATCH(content) AGAINST('关键词')
  AND created_at > '2026-01-01'
ORDER BY dist APPROXIMATE
LIMIT 10;

第 3 步：FORK/MERGE 沙箱问题

FORK DATABASE agent_state TO agent_sandbox_42;   -- 秒级快照，无数据拷贝
USE agent_sandbox_42;
-- ...自由读写实验...
MERGE TABLE agent_sandbox_42.memory INTO agent_state.memory STRATEGY THEIRS;
-- 或整体丢弃：
DROP DATABASE agent_sandbox_42;

排查要点：

MERGE 冲突策略必须显式选择：FAIL（冲突即失败）/ THEIRS（沙箱覆盖主线）/ OURS（主线保留）。语义拿不准时先用 FAIL 试探冲突面。
FORK 出来的库用完即 DROP，避免沙箱库堆积占用元数据。
语法细节以仓库内测试为准：tools/deploy/mysql_test/test_suite/fork_table/ 目录下的用例就是权威行为契约。

第 4 步：通用排查工具

权威行为契约在测试里：tools/deploy/mysql_test/test_suite/ 下每个特性目录（向量、全文、fork 等）的 .test/.result 文件定义了确切语法和期望输出，比任何二手教程可靠。
看执行计划：EXPLAIN / EXPLAIN EXTENDED 确认是否命中向量索引、过滤是否下推。
服务端日志：Docker 形态 docker logs seekdb；源码部署看 log/observer.log，报错行附近的 [ERROR]/[WARN] 通常直接给出根因。
MySQL 生态工具直连：seekdb 走 MySQL 协议，mysql 客户端、Navicat、pymysql 均可直接用于诊断。

输出结论的格式

诊断完成后按三段汇报，不要只贴原始输出：

根因：一句话说明问题出在部署/连接/DDL/查询语法哪一层。
修复动作：给出可直接执行的命令或 SQL。
最小复现：一段能独立验证修复生效的最短脚本（3-5 条语句以内）。

Resources

scripts/doctor.sh — 一键体检脚本：探测 Docker 容器、端口连通性、seekdb 版本与向量特性可用性。