OceanBase seekdb 快速上手与混合检索速查

队伍：豆丁｜主页：https://github.com/hechuan1023/ ｜赛题仓库：https://github.com/hechuan1023/OB-2026-seekdb

适用场景

在 seekdb 上完成这类任务时使用：

新人第一次接触 seekdb，需要跑通"起实例 → 连上去 → 建表 → 灌数据 → 查到结果"
需要把「向量语义召回 + 全文关键词召回 + 标量过滤」组合成一条检索链路
检索结果不符合预期，需要按症状定位原因（召回不全 / 排序乱 / 变慢 / 查不到）
需要为 RAG / 知识库 / 商品搜索准备数据模型与查询模板

不适用：需要实现数据库内核（存储引擎、事务、SQL 解析器）的场景；需要训练或微调 embedding 模型的场景。

环境准备

起一个实例

docker run -d --name seekdb -p 2881:2881 oceanbase/seekdb:latest

seekdb 兼容 MySQL 协议，默认端口 2881，可直接用任何 MySQL 客户端连接。

客户端（按需选一种）

pip install pyseekdb              # Python SDK
pip install seekdb-cli             # 命令行客户端
pip install seekdb-agent-skills    # 官方 Agent Skills 集合
pip install pymysql               # 通用 MySQL 驱动

连接串

export SEEKDB_HOST=127.0.0.1
export SEEKDB_PORT=2881
export SEEKDB_USER=root
export SEEKDB_PASSWORD=
export SEEKDB_DB=test

密码只走环境变量或客户端配置文件，不要写进代码或提交到仓库。

第一个查询（5 分钟路径）

-- 1. 确认连通与版本
SELECT VERSION();
SHOW TABLES;

-- 2. 看一张表的真实结构（**以这个为准，不要凭记忆写 DDL**）
SHOW CREATE TABLE <表名>;

-- 3. 看索引类型
SHOW INDEX FROM <表名>;

这是本 Skill 最重要的一条原则：seekdb 不同版本对向量/全文索引的 DDL 与检索语法有差异。先 SHOW CREATE TABLE 看现有表怎么建的，再照抄结构，永远比凭记忆写要快也更准。

建表与索引

CREATE TABLE docs (
  id          BIGINT PRIMARY KEY,
  tenant_id   INT NOT NULL,
  category    VARCHAR(32) NOT NULL,
  title       VARCHAR(256) NOT NULL,
  body        TEXT NOT NULL,
  embedding   VECTOR(768) NOT NULL
);

三类索引分别服务三条检索路径，缺一不可：

| 索引类型 | 服务的能力 | 建之前必须确认 | |---|---|---| | 向量索引（ANN） | 语义近邻召回 | 维度与距离度量必须与 embedding 实际分布一致 | | 全文索引（倒排） | 关键词精确召回 | 分词器与语言；中文是否受支持 | | 标量索引 | 过滤下推 | 高基数列与低基数列的收益差异很大 |

标量过滤列单独成列，不要塞进 JSON 里再过滤——那样索引失效，过滤退化成全表扫描。

三种检索方式

向量检索（语义）

SELECT id, title, l2_distance(embedding, '[0.1,0.2,...]') AS d
FROM docs
WHERE embedding IS NOT NULL
ORDER BY d
LIMIT 10;

距离函数常见为 l2_distance / inner_product / cosine_distance。 必须与 embedding 生成时的度量一致——用内积索引去查已 L2 归一化的向量，是最常见的静默错误。

全文检索（关键词）

SELECT id, title
FROM docs
WHERE MATCH(title, body) AGAINST ('固件 升级' IN NATURAL LANGUAGE MODE)
LIMIT 10;

标量过滤

SELECT id FROM docs WHERE tenant_id = 42 AND category = 'sensor';

混合检索（向量 + 全文 + 过滤）

SELECT id, title
FROM docs
WHERE MATCH(title, body) AGAINST ('固件 升级' IN NATURAL LANGUAGE MODE)
  AND tenant_id = 42
ORDER BY 0.3 * (1 - l2_distance(embedding, '[0.1,0.2,...]'))
       + 0.7 * MATCH(title, body) AGAINST ('固件 升级' IN NATURAL LANGUAGE MODE)
LIMIT 10;

要点：

两个分量必须先归一化再加权。 距离越小越好、BM25 越大越好，量纲不同，直接相加会让权重失去意义。
0.3 / 0.7 只是起点。按同一套评测集做网格搜索确定，且一次只改一个变量。
过滤写在哪里，差别很大：写在 WHERE 里由引擎下推，与先召回再在应用层过滤，是两种策略。后者在候选被过滤掉后无法补位，召回常常不升反降。
候选规模 N（进融合的条数）太小 → 真答案进不了候选；太大 → 融合分数被稀释且延迟上升。

排查清单（按症状查）

| 症状 | 优先排查 | |---|---| | 向量检索返回空 | 维度不一致；向量列为 NULL；距离函数用错 | | 向量结果"能看但排序怪" | 距离度量与 embedding 归一化方式不匹配 | | 全文检索返回空 | 分词器/语言设置；索引是否真的建成；是否误用了 LIKE | | 混合结果不如单路 | 未归一化直接加权；过滤后置导致候选塌陷；候选 N 过小 | | 加了过滤后变慢 | 过滤未下推，引擎仍在扫描全量候选 | | 写入时报维度错误 | 建表维度与实际生成向量维度不一致 |

与其他赛题方向的区别

初赛三个主要方向容易混淆，先确认自己在做哪块：

| 方向 | 做什么 | 核心能力 | |---|---|---| | seekdb | 用现成的 AI 原生混合搜索数据库解决检索问题 | 建模型、写查询、调效果与性能 | | PowerContext | OceanBase 的上下文工程框架：采集/解码/组织/检索/压缩/记忆/注入 | 上下文生命周期管理 | | MiniOB | 从零实现一个数据库内核（存储引擎、查询引擎、事务引擎） | C++ 内核实现，Linux 环境编译 |

三者不通用：一个会写 SQL 解决不了 MiniOB，一个调通检索也替代不了上下文工程。

参考资源

官方资源

| 资源 | 地址 | |---|---| | 官方 Agent Skills 集合 | github.com/oceanbase/seekdb-ecology-plugins → agent-skills/ | | 公开 Skill 样例 | d0.seekdb.ai/SKILL.md | | seekdb 镜像 | docker pull oceanbase/seekdb:latest | | OceanBase 官方文档 | OceanBase 官网文档中心 → AI 搜索 / seekdb 章节 | | 魔搭 Skills 中心 | modelscope.cn/skills |

豆丁团队

| 资源 | 地址 | |---|---| | 团队主页 | github.com/hechuan1023 | | seekdb 赛题仓库 | github.com/hechuan1023/OB-2026-seekdb | | PowerContext 赛题仓库 | github.com/hechuan1023/OB-2026-PowerContext | | seekdb 源码基线 | github.com/hechuan1023/seekdb |

约束

不要凭记忆写 seekdb 的 DDL 或检索语法。 先 SHOW CREATE TABLE 看实例上的真实结构，再照抄。
不确定的语法先跑最小用例，不要一次写一整套再调试。
任何性能或召回结论都必须实测得到，未测的项写"未测"。
不修改生产环境的既有索引，除非用户明确要求；诊断阶段只读。
密码一律走环境变量，不出现在代码、示例或报告里。