seekdb 向量检索

这个 Skill 用于在 seekdb 中搭建可复用的向量检索流程。它覆盖表结构设计、向量写入、相似度搜索和检索结果校验，适合问答、文档检索和推荐等场景。

适用场景

• 为文档或商品记录保存 embedding 向量。
• 使用余弦相似度、内积或欧氏距离查找近邻。
• 在 SQL 中组合结构化条件、排序和向量相似度。
• 为检索链路准备最小可复现的验证数据。

工作流程

1. 确认向量规格：记录 embedding 模型、维度、距离度量和归一化方式；查询与写入必须使用同一规格。
2. 设计数据表：保留业务主键、原文或摘要、metadata，以及固定维度的向量列。为经常过滤的 metadata 建立合适的普通索引。
3. 写入向量：批量写入文本与向量，检查向量长度、数值类型和空值，失败批次要可重试。
4. 执行检索：把查询文本编码为向量，在 SQL 中计算相似度并按距离排序，使用 LIMIT 控制候选数量。
5. 组合过滤：先用租户、时间、类别等条件缩小候选集，再进行相似度排序，避免跨业务范围返回结果。
6. 验证质量：用已知查询检查 top-k 命中率、重复结果和边界输入；记录模型版本与参数，便于复现。

SQL 示例

下面的示例展示了流程结构，实际向量维度和函数名应以当前 seekdb 版本文档为准：

CREATE TABLE documents (
  id BIGINT PRIMARY KEY,
  title VARCHAR(256),
  body TEXT,
  category VARCHAR(64),
  embedding VECTOR(1536)
);

INSERT INTO documents (id, title, body, category, embedding)
VALUES (?, ?, ?, ?, ?);

SELECT id, title, body,
       1 - VECTOR_COSINE_DISTANCE(embedding, ?) AS score
FROM documents
WHERE category = ?
ORDER BY score DESC
LIMIT 10;

注意事项

• 不要混用不同 embedding 模型或不同维度的向量。
• 生产环境中对输入向量做长度和有限值校验，避免 NaN 或无穷值污染索引。
• top-k 应结合召回率、延迟和后续重排成本调节；不要默认返回过大的候选集。
• 涉及多租户数据时，过滤条件必须与相似度查询同时生效。
• 记录 SQL、模型版本、距离度量和索引配置，便于定位质量变化。

<!-- OB-S:0o56ONLH5nWkuGiB_54_4g -->