嵌入式转换

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

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

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

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

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

行为

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

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

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

配置

要配置连接器以使用嵌入转换，请将以下行添加到您的连接器配置中

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 文本嵌入文档中找到。
`embeddings.voyageai.baseUrl`	https://api.voyageai.com/v1/	Voyage AI API 的基础服务器。
`embeddings.voyageai.operation.timeout.ms`	15000（15 秒）	等待嵌入响应的最大时间（以毫秒为单位）。