跳到主要内容
版本：V1.1.0

嵌入函数概述

在 seekdb 中，嵌入函数（Embedding Functions，简称 EF） 用于将文本等输入转换为向量，以支持语义搜索（向量相似性检索）等能力。seekdb 提供了对多种主流平台/模型的嵌入函数封装，您可以直接使用内置实现，也可以按接口规范实现自定义嵌入函数。

工作方式​

您可以在创建或获取 Collection 时通过 embeddingFunction 参数绑定 EF。绑定后，Collection 的写入与查询会按以下规则自动生成向量：

  • 写入：调用 add / update / upsert 等接口时，如果传入的是 documents（而不是 embeddings），则使用 EF 将文本转换为向量并写入。
  • 查询：调用 query 接口时，如果传入的是 queryTexts（而不是 queryEmbeddings），则使用 EF 将查询文本转换为查询向量并执行检索。
提示

当您显式传入 embeddings / queryEmbeddings 时，seekdb 会直接使用您提供的向量，并忽略 Collection 绑定的 EF。

支持的平台​

当前 seekdb 已支持以下平台的嵌入函数：

典型用法（与 Collection 绑定）​

下面示例展示了 EF 与 Collection 的典型绑定方式。其中 ef 可替换为任一平台的嵌入函数实例；client 为已创建的 SeekdbClient 实例。

import { SeekdbClient } from "seekdb";
import { OpenAIEmbeddingFunction } from "@seekdb/openai";

const client = new SeekdbClient({
  host: "127.0.0.1",
  port: 2881,
  user: "root",
  password: "",
  database: "test",
});

// 1. 初始化嵌入函数
const ef = new OpenAIEmbeddingFunction({
  modelName: "text-embedding-3-small",
});

// 2. 创建 Collection 时绑定嵌入函数
const collection = await client.createCollection({
  name: "my_collection",
  embeddingFunction: ef,
});

// 3. 写入 documents：自动生成向量并存储
await collection.add({
  ids: ["1", "2"],
  documents: ["Hello world", "How are you?"],
  metadatas: [{ id: 1 }, { id: 2 }],
});

// 4. 使用 queryTexts 查询：自动生成查询向量并检索
const results = await collection.query({
  queryTexts: "How are you?",
  nResults: 1,
});
console.log(results);

默认嵌入函数：DefaultEmbeddingFunction（all-MiniLM-L6-v2）​

如果在创建 Collection 时未指定 embeddingFunction，seekdb 会使用默认的嵌入逻辑（基于本地模型 Xenova/all-MiniLM-L6-v2，维度 384）。该模型在本地运行，无需 API 密钥；首次进行向量化时会自动下载模型文件。

// 不传入 embeddingFunction 时，使用默认嵌入逻辑
const collection = await client.createCollection({
  name: "default_collection",
});

若需显式使用默认嵌入函数（例如统一通过 embeddingFunction 参数传入），可安装 @seekdb/default-embed 并传入其实例：

import { DefaultEmbeddingFunction } from "@seekdb/default-embed";

const defaultEmbed = new DefaultEmbeddingFunction({
  // 若下载异常可尝试设置 region: 'intl'
});

const collection = await client.createCollection({
  name: "local_embed_collection",
  embeddingFunction: defaultEmbed,
});

更多说明请参考 默认嵌入函数。

自定义嵌入函数​

若内置嵌入函数无法满足需求，您可以实现 EmbeddingFunction 接口创建自定义 EF。自定义 EF 需满足以下约束：

  • 实现 generate 方法：接受 string[]，返回 Promise<number[][]>。
  • 实现 name 属性：返回该嵌入函数的唯一名称。
  • 实现 getConfig 方法：返回当前实例的配置对象（用于序列化/复原）。
  • 实现静态方法 buildFromConfig：根据配置对象构造新实例。
  • （推荐）提供 dimension：返回向量维度，便于创建 Collection 时进行一致性校验。

实现自定义嵌入函数之后，您需要使用 registerEmbeddingFunction 注册自定义嵌入函数，用于实现序列化/复原。下面是一个最小示例：

import type { EmbeddingFunction } from "seekdb";
import { registerEmbeddingFunction } from "seekdb";

class MyCustomEmbeddingFunction implements EmbeddingFunction {
  readonly name = "my_custom_embedding";
  dimension = 3;

  async generate(texts: string[]) {
    // 在此实现您的向量化逻辑（例如调用内部模型服务）
    return texts.map(() => [0.1, 0.2, 0.3]);
  }
  getConfig() {
    return {};
  }
  static buildFromConfig() {
    return new MyCustomEmbeddingFunction();
  }
}

// 注册您的自定义函数
registerEmbeddingFunction("my_custom_embedding", MyCustomEmbeddingFunction);

更多规范与示例请参考：

Contents

编辑此页