seekdb 实战手册

本手册来自 2026 OceanBase 数据库大赛的真实部署与开发过程，覆盖从零部署到混合检索的完整路径。

1. Docker 部署

seekdb 推荐用 Docker 单容器部署，数据落在本地挂载目录：

docker run -d \
  --name seekdb \
  -p 2881:2881 \
  -v $(pwd)/seekdb-data:/var/lib/seekdb \
  oceanbase/seekdb:latest

要点：

首次启动会初始化系统表，等待 30-60 秒再用健康检查确认。
容器必须保持运行：竞赛类遥测验证要求部署持续在线，重启容器不影响已上报的部署身份，但删容器重建会换 UUID。

2. 部署验证

部署成功的判据（按顺序检查）：

docker ps 里容器状态为 Up，端口映射正确；
健康检查接口返回正常（容器内 curl localhost:2881/healthz 或等价端点）；
需要平台侧确认部署时，使用部署产物中的部署 UUID 在对应平台提交核验，数据同步可能延迟，隔一段时间重提同一 UUID 即可。

3. pyseekdb 嵌入式客户端

pyseekdb 提供 Chroma 风格的嵌入式 API，本地一个文件就是一个库，适合 Agent 状态存储：

import pyseekdb

client = pyseekdb.Client(path="./agent_state.db")
memory = client.get_or_create_collection(name="episodic")

# 写入后 refresh_index 立即可查
memory.upsert(
    ids=["1", "2", "3"],
    documents=["user prefers dark mode", "user speaks English and Chinese"],
)
memory.refresh_index()

results = memory.query(query_texts="ui preferences?", n_results=2)

要点：

写入后必须 refresh_index()，否则新数据对查询不可见；
upsert 按 id 幂等，重复写入不会产生重复记录；
集合命名只能用 [a-zA-Z0-9_]，不能带连字符。

4. 混合检索：一条 SQL 同时拿全文与向量候选

seekdb 兼容 MySQL 语法，全文用 MATCH ... AGAINST，向量用 l2_distance ... APPROXIMATE，两者可以放进同一条语句的两个子查询再用 UNION ALL 合并，让数据库一次返回两路候选：

SELECT * FROM (
    SELECT 'fts' AS channel, id, text,
           MATCH(searchable_text) AGAINST (:query IN NATURAL LANGUAGE MODE) AS score
    FROM documents
    WHERE scope_id = :scope_id
    ORDER BY score DESC
    LIMIT :k
) a
UNION ALL
SELECT * FROM (
    SELECT 'vector' AS channel, id, text,
           l2_distance(embedding, :query_vector) AS distance
    FROM doc_vectors
    WHERE scope_id = :scope_id
    ORDER BY l2_distance(embedding, :query_vector) APPROXIMATE
    LIMIT :k
) b

验证索引真实生效：在语句前加 EXPLAIN，执行计划应同时出现 TEXT RETRIEVAL SCAN 与 VECTOR INDEX；如果出现全表扫描说明索引没建或没走到。

5. 常见坑

重建后 UUID 变化：部署身份与容器/数据目录绑定，删容器重建前先记录旧 UUID。
APPROXIMATE 与附加过滤：向量近似检索叠加额外 WHERE 条件时，部分版本会退化为精确距离计算，过滤条件多时去掉 APPROXIMATE 更稳。
UNION 中的 NULL 列类型：UNION ALL 两路的同名列类型取自第一路，占位列（如 NULL AS distance）注意下游对类型的假设。
游标语义：消费型任务的"已处理水位"要按持久化的 journal 位置计算，重复输入靠身份去重，不要按条数估。