在应用中接入 seekdb：向量+全文混合检索速成

你将帮用户在 Node.js 项目里用 seekdb 实现本地向量+全文混合检索。seekdb 兼容 MySQL 协议，可嵌入式运行（无需单独部署数据库），也可连服务端。

1. 安装

npm install seekdb mysql2

注意两点：

仓库根目录放 .npmrc 写入 legacy-peer-deps=true（发布版的 @seekdb/default-embed peer 依赖带 workspace 协议，会导致默认安装失败）。
嵌入式模式首次使用时自动下载原生运行时（win32-x64 约 90MB / linux-x64 约 55MB）到 ~/.seekdb/bindings/，需外网可达；Linux 上若报 libaio.so.1 缺失，安装 libaio1(t64)；若报 "static TLS block"，用 LD_PRELOAD=<缓存目录>/linux-x64/libseekdb.so 启动。

2. 连接（两种模式）

import { SeekdbClient } from "seekdb";

// 嵌入式（本地目录，无需部署）
const client = new SeekdbClient({ path: "./mydata.db", database: "test" });

// 或服务端模式（seekdb / OceanBase，MySQL 协议）
// const client = new SeekdbClient({ host: "127.0.0.1", port: 2881, user: "root", password: "", database: "test" });

嵌入式用内置 test 库即可；自定义库名需先 createDatabase，部分版本在库不存在时直接连接会报 database is null/1049。

3. 建集合（ik 全文 + HNSW 向量）

import { Schema, FulltextIndexConfig, VectorIndexConfig } from "seekdb";

const schema = new Schema({
  fulltextIndex: new FulltextIndexConfig("ik", { ik_mode: "smart" }), // 中英文全文
  vectorIndex: new VectorIndexConfig({
    hnsw: { dimension: 384, distance: "cosine" },
    embeddingFunction: null,  // 向量自己算（端侧/外部模型）时设 null；否则装 @seekdb/default-embed 自动算
  }),
});
const col = await client.getOrCreateCollection({ name: "docs", schema });

4. 写入与检索

// 写入（向量自算时随 embedding 传入）
await col.add({ ids: ["1"], documents: ["文本"], metadatas: [{ src: "x" }], embeddings: [[...384维...]] });

// 混合检索：全文与向量两路 + RRF 融合，全部在 seekdb 内完成
const r = await col.hybridSearch({
  query: { whereDocument: { $contains: "关键词" }, nResults: 20 },
  knn: { queryEmbeddings: [[...查询向量...]], nResults: 20 },
  rank: { rrf: {} },
  nResults: 8,
});
// 纯向量：col.query({ queryEmbeddings: [[...]], nResults: 8, approximate: false })

5. 常见坑

写入后立即向量检索为空：增量 HNSW 索引异步构建，通常 1–2 秒后可查；需要"写完即查"的场景等待或重试。
listCollections 为空：嵌入式引擎的目录视图可能滞后，自己维护一个 collections.json 注册表更稳。
仅 knn 的 hybridSearch 在部分版本返回空：给 query 分支也传条件，或纯向量时用 query({approximate: false})。
关闭进程前 await client.close()，避免数据未落盘。

6. 相关链接

seekdb 仓库：https://github.com/oceanbase/seekdb
seekdb-js SDK：https://github.com/oceanbase/seekdb-js
文档：https://docs.seekdb.ai/