n8n 中文文档

Embeddings Databricks 节点

使用 Embeddings Databricks 节点,通过 Databricks 工作区提供的嵌入模型为文本生成嵌入[^1]。该节点查询 Unity AI Gateway 模型服务,即 Databricks Chat Model 节点所使用的同一网关。它主要用于搭配 Databricks Vector Store 节点;后者在每种操作模式下都需要 embeddings 连接。

本页面介绍先决条件、设置步骤、搭配规则、节点参数和 Embeddings Databricks 节点的已知问题。

提示

Credentials 凭据

有关设置身份验证的指南,请参阅 Databricks 凭据。此节点仅接受使用服务主体或用户登录的 Databricks OAuth2 API 凭据,不接受个人访问令牌。

提示

Parameter resolution in sub-nodes 子节点参数解析

使用表达式处理多个项目时,子节点的行为与其他节点不同。

大多数节点,包括根节点,接受任意数量的项目作为输入,处理这些项目,并输出结果。您可以使用表达式引用输入项目,节点会依次为每个项目解析表达式。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 会依次解析为每个名称。

在子节点中,表达式始终解析为第一项。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 始终解析为名字。

先决条件

  • 已启用 Unity AI Gateway 的 Databricks 工作区。
  • n8n 中使用服务主体或用户登录的 Databricks OAuth2 凭据。
  • 凭据所认证的身份需要对模型服务所在的 catalog 和 schema 分别拥有 USE CATALOG 和 USE SCHEMA 权限,并对模型服务拥有 EXECUTE 权限。默认情况下,Databricks 向所有工作区用户授予 system.ai 模型服务的 EXECUTE 权限。请参阅所需 Databricks 权限。

设置节点

  1. 将 Databricks Vector Store 节点或其他接受 embeddings 子节点的节点添加到工作流。
  2. 选择节点 Embedding 嵌入连接器上的 +,然后选择 Embeddings Databricks。
  3. 在 Credential to connect with 要连接的凭据下,选择现有 Databricks OAuth2 凭据或新建凭据。
  4. 打开 Model 模型列表并选择模型服务。n8n 会加载凭据有权访问且支持 embeddings 的模型服务,并排除 chat model。输入文本可筛选列表。要使用列表中未显示的服务,请切换到 ID 并输入其全名,例如 system.ai.gte-large-en。

将节点与 Databricks 索引搭配使用

应选择哪个模型取决于 Databricks Vector Store 节点使用的索引:

  • Managed index 托管索引(使用 Databricks 嵌入模型的 Delta Sync 索引):Databricks 使用索引自身的模型嵌入查询。必须连接 Embeddings Databricks 节点,但系统不会调用它,因此任意模型服务都可以。
  • Self-managed index 自管理索引(Direct Access 索引,或具有自身 vector column 的 Delta Sync 索引):Embeddings Databricks 节点会嵌入每个搜索查询;对于 Direct Access 索引,它还会嵌入每个插入的文档。请选择构建索引时所用的模型和维度。使用 databricks-gte-large-en 构建的索引具有 1024 个维度,需要 system.ai.gte-large-en 模型服务。使用其他模型时,搜索会失败并显示 query vector dimension <n> does not match index vector dimension <m>,插入会失败并显示 Databricks rejected the upsert into <index>. Failed primary keys: ...。

有关 Vector Store 节点如何决定发送哪种查询形式,请参阅 Databricks Vector Store 页面上的索引类型和嵌入。

此节点是标准 embeddings 子节点,因此也可与 n8n 中的其他 Vector Store 节点搭配使用,例如 Simple Vector Store。

节点参数

  • Model 模型:生成嵌入的 Unity AI Gateway 模型服务,名称格式为 catalog.schema.service。
    • From List 从列表中选择:从凭据有权访问且支持 embeddings 的模型服务中选择。
    • ID:直接输入模型服务的全名。如果某个服务支持 embeddings,但未标记为支持 embeddings,请使用此方式。

节点选项

  • Batch Size 批量大小:一次请求中发送的最大文档数。默认为 512,最大为 2048。降低该值前请参阅速率限制。
  • Strip New Lines 移除换行符:是否在生成嵌入前移除输入文本中的换行符。默认启用。
  • Timeout 超时:请求可用的最长时间(毫秒)。默认为 360000(六分钟)。请求超时时会失败并显示 Request timed out.
  • Max Retries 最大重试次数:失败请求的重试次数。默认为 2。

速率限制

按 token 付费的模型服务会按工作区实施速率限制。Databricks Vector Store 节点插入文档时,会根据自身的 Embedding Batch Size 嵌入批量大小(默认为 200)将文档分块,再根据此节点的 Batch Size 批量大小将每个块拆成并行发出的请求。较小的 Batch Size 批量大小会把一个块变成多个并发请求,从而可能超出模型服务的工作区限制。节点会使用退避策略重试被拒绝的请求,最多重试 Max Retries 最大重试次数;随后插入会失败并显示 Databricks rate limit reached for <service>: REQUEST_LIMIT_EXCEEDED: Exceeded workspace QPS rate limit。节点不会写入触发限制的那个块,但此前已完成嵌入和写入的块仍会留在索引中,因此重试前请检查索引。

为避免触发限制,请将 Batch Size 批量大小保留为默认值,使一个块通过一次请求发出;减少并发插入;或为模型使用预置吞吐量端点。

相关资源

查看 n8n 的 Advanced AI 高级 AI 文档。

常见问题

未找到模型服务

模型列表为空,且节点报告 No model services found。工作区未启用 Unity AI Gateway,或者凭据身份无权访问任何模型服务。请检查工作区设置,然后对至少一个模型服务授予 USE CATALOG、USE SCHEMA 和 EXECUTE 权限。

未找到支持 embeddings 的模型服务

凭据可以看到模型服务,但其中没有服务标记为支持 embeddings。请将 Model 模型切换到 ID,然后直接输入服务名称。此节点不能使用仅支持聊天的服务。

找不到模型服务

节点失败并显示 The resource you are requesting could not be found,错误说明中会指出缺少的服务。工作区中不存在 Model 模型所指定的名称。请检查三段式名称,或使用 From List 从列表中选择来选择服务。

查询向量维度与索引不匹配

模型与 Databricks Vector Store 节点搜索的索引不匹配。请参阅将节点与 Databricks 索引搭配使用。

达到速率限制

执行失败并显示 Databricks rate limit reached for <service> 和 429 状态。请参阅速率限制。

Host 必须使用 HTTPS

由于凭据的 Host 主机不是 https:// URL(例如以 http:// 开头或没有 scheme),节点会失败并显示 Databricks host must use https。每个请求都携带 token,因此节点拒绝明文 HTTP。请输入以 https:// 开头的完整工作区 URL。

连接错误

节点报告 Connection error.,但没有 Databricks 消息。凭据的 Host 主机没有指向 Databricks 工作区,或者您的 n8n 实例无法访问该工作区。请检查 host URL 和网络路径。

[^1]: 嵌入是使用向量对数据进行的数值表示。AI 通过在多个维度上映射值,利用嵌入解释复杂数据及其关系。向量数据库(即 Vector Store)是专为存储和访问嵌入而设计的数据库。

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。