嵌入式转换

行为
配置
- 通用配置选项
模型提供商配置

为了让内容能够用于大型语言模型或进行通用的自然语言处理，一个重要的预处理任务是将文本转换为数值表示，也称为文本向量化。实现此转换的一种方法是通过所谓的文本嵌入，这个过程是将文本转换为高维数值向量。将文本表示为向量，使得计算机能够执行语义相似性搜索和其他高级操作。

Debezium 提供了一个内置功能，可以将指定的文本字段转换为数值嵌入向量，并将生成的嵌入添加到事件记录中。嵌入推理根据配置的提供商提供的嵌入模型进行。Debezium 提供多种嵌入模型提供商。

Debezium 可以使用单个消息转换 (SMT) 来生成嵌入。为了与不同的嵌入提供商进行交互，此 Embeddings 转换使用了langchain4j 框架。

Embeddings 转换需要 Java 21 或更高版本。

行为

Embeddings 转换以原始事件记录中的特定字段作为输入，并将这些字段的文本内容传递给配置的嵌入模型进行推理。也就是说，SMT 从指定字段中包含的文本创建嵌入。生成的嵌入将被追加到记录中。原始源字段也会保留在记录中。

源字段必须是字符串字段。嵌入字段的值是 32 位浮点数向量。向量的大小取决于所选模型。为了提供嵌入的内部表示，Debezium 使用FloatVector 数据类型。记录中嵌入字段的模式类型为 io.debezium.data.FloatVector。

源字段和嵌入字段的规范都支持嵌套结构，例如 after.product_description_embedding。

配置

要配置连接器使用 embeddings 转换，请在连接器配置中添加以下行

transforms=embeddings,
transforms.embeddings.type=io.debezium.ai.embeddings.FieldToEmbedding

您必须至少指定一个字段用作嵌入的输入。嵌入将放置的目标字段不是必需的。如果未指定，消息值将只包含嵌入本身。但是，建议指定嵌入目标字段，例如

transforms.embeddings.field.source=after.product
transforms.embeddings.field.embedding=after.product_embedding

最后，您必须将模型提供商的 JAR 文件放在连接器的类路径中，并配置该提供商。例如，对于 Ollama 提供商，将 debezium-ai-embeddings-ollama-$VERSION.jar 添加到您的连接器类路径中，并将 Ollama URL 和模型名称添加到连接器配置中，如以下示例所示

transforms.embeddings.ollama.url=https://:11434
transforms.embeddings.ollama.model.name=all-minilm

以下示例显示了 Ollama 提供商的完整配置可能是什么样的

transforms=embeddings,
transforms.embeddings.type=io.debezium.ai.embeddings.FieldToEmbedding
transforms.embeddings.field.source=after.product
transforms.embeddings.field.embedding=after.product_embedding
transforms.embeddings.ollama.url=https://:11434
transforms.embeddings.ollama.model.name=all-minilm

通用配置选项

表 1. 嵌入 SMT 配置选项说明
Option	Default (默认值)	描述
`embeddings.field.source`	无默认值	指定源记录中用作嵌入输入的字段。指定字段的数据类型必须是 `string`。
`embeddings.field.embedding`	无默认值	指定 SMT 添加到记录以包含文本嵌入的字段名称。如果未指定值，则生成的记录仅包含嵌入值。

模型提供商配置

Hugging Face

由 Hugging Face 提供的模型提供的嵌入。

表 2. Hugging Face 嵌入配置选项
Option	Default (默认值)	描述
`embeddings.huggingface.access.token`	无默认值	Hugging Face 访问令牌。
`embeddings.huggingface.model.name`	无默认值	嵌入模型的名称。使用 REST API 获取可用模型列表。在 REST 调用中指定提供商，例如，Hugging Face 推理提供商。
`embeddings.huggingface.baseUrl`	https://api-inference.huggingface.co/	Hugging Face 推理 API 的基础 URL。
`embeddings.huggingface.operation.timeout.ms`	15000 (15 秒)	等待嵌入回复的最大时间（以毫秒为单位）。

Hugging Face 已开始支持不同的嵌入推理提供商，包括外部提供商。但是，LangChain4j 框架尚不支持外部提供商。因此，目前可用于 Debezium 的唯一推理提供商是 Hugging Face 提供商。

Ollama

支持 Ollama 服务器提供的任何模型。

表 3. Ollama 嵌入配置选项
Option	Default (默认值)	描述
`embeddings.ollama.url`	无默认值	Ollama 服务器的 URL，包括端口号，例如 `https://:11434`。
`embeddings.ollama.model.name`	无默认值	嵌入模型的名称。
`embeddings.ollama.operation.timeout.ms`	15000 (15 秒)	等待嵌入回复的最大时间（以毫秒为单位）。

ONNX MiniLM

提供 ONNX in-process all-minilm-l6-v2 模型，该模型直接包含在 jar 文件中。除通用配置外，无需其他配置。

此模型特别适用于原型设计和测试，因为它不依赖任何外部基础架构或远程请求。

Voyage AI

由 Voyage AI 模型提供的嵌入。

表 4. Voyage AI 嵌入配置选项
Option	Default (默认值)	描述
`embeddings.voyageai.access.token`	无默认值	Voyage AI 访问令牌。
`embeddings.voyageai.model.name`	无默认值	嵌入模型的名称。Voyage AI 模型列表可以在Voyage AI Text Embeddings 文档中找到。
`embeddings.voyageai.baseUrl`	https://api.voyageai.com/v1/	Voyage AI API 服务器基础地址。
`embeddings.voyageai.operation.timeout.ms`	15000 (15 秒)	等待嵌入回复的最大时间（以毫秒为单位）。