Databricks Vector Store 节点
使用 Databricks Vector Store 节点,在工作流中处理 Databricks Vector Search 索引。您可以在索引上运行相似度搜索、向 Direct Access 索引插入文档、将索引提供给连接至 chain[^1] 的 retriever,或将索引作为 tool[^3] 连接到 AI agent[^2]。索引位于 Unity Catalog 中,因此节点只能看到凭据身份有权访问的数据。
本页面介绍先决条件、节点支持的索引类型、节点参数和选项,并提供完整示例。如果您从 n8n-nodes-databricks 社区包迁移,请参阅从社区包迁移。
提示
Credentials 凭据
有关设置身份验证的指南,请参阅 Databricks 凭据。此节点仅接受使用服务主体或用户登录的 Databricks OAuth2 API 凭据,不接受个人访问令牌。
提示
Parameter resolution in sub-nodes 子节点参数解析
使用表达式处理多个项目时,子节点的行为与其他节点不同。
大多数节点,包括根节点,接受任意数量的项目作为输入,处理这些项目,并输出结果。您可以使用表达式引用输入项目,节点会依次为每个项目解析表达式。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 会依次解析为每个名称。
在子节点中,表达式始终解析为第一项。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 始终解析为名字。
先决条件
- Databricks 工作区,其中包含 Vector Search endpoint 和至少一个索引。请参阅 Databricks 文档中的创建和查询 Vector Search 索引。
- n8n 中使用服务主体或用户登录的 Databricks OAuth2 凭据。
- 连接到节点 Embedding 嵌入输入的 Embeddings Databricks 节点。每种操作模式都需要此输入,即使索引由 Databricks 自行计算 embeddings 也是如此。请参阅索引类型和嵌入。
- 凭据所认证的身份需要以下权限:
- 索引所在 catalog 的 USE CATALOG 和 schema 的 USE SCHEMA。
- 索引的 SELECT。Insert Documents 插入文档还需要索引的 MODIFY。
- 对同步所有列的 Delta Sync 索引源表拥有 SELECT,这样节点才能在 Content Column 内容列和 Metadata Columns 元数据列中列出各列。没有此权限时,Metadata Columns 元数据列为空,Content Column 内容列仅提供 embedding source column,返回的文档也只有内容。
- Embeddings Databricks 节点所用 embeddings 模型服务所在 catalog 和 schema 的 USE CATALOG 与 USE SCHEMA,以及该服务的 EXECUTE。默认情况下,Databricks 向所有用户授予
system.ai服务的 EXECUTE 权限。 - 如果使用 Metadata Filter 元数据筛选器,还需拥有提供索引的 Vector Search endpoint 的读取权限。节点每次执行时读取一次 endpoint 类型,以检查筛选器是否适用。工作区用户默认具有此权限。
服务主体必须是工作区成员,并具有 Workspace access 权利。只存在于账户级别的服务主体会从工作区 token endpoint 收到 invalid_client,看起来像 client secret 错误。完整列表请参阅所需 Databricks 权限。
索引类型和嵌入
Databricks 索引的两个属性决定节点能执行哪些操作:数据行如何进入索引,以及由谁计算 embeddings。节点每次执行时读取一次索引说明,并自动适配二者。您无需选择查询模式。
Delta Sync 和 Direct Access 索引
| 索引类型 | 数据行来源 | Insert Documents 插入文档 |
|---|---|---|
| Delta Sync | Databricks 持续与索引同步的 Delta table | 不支持。请改为向源表添加数据行。节点会在写入前失败并显示 Index <name> syncs from its source table. Use a Direct Access index to insert documents。 |
| Direct Access | 通过 Vector Search API 写入的数据行 | 支持。在 Insert Documents 插入文档模式下,Index 索引列表仅显示 Direct Access 索引。 |
三种搜索模式都可用于这两种索引类型。Insert Documents 插入文档仅可用于 Direct Access 索引。
托管和自管理嵌入
| 嵌入 | 文本嵌入方 | 节点发送的内容 | Embeddings Databricks 节点 |
|---|---|---|---|
| 托管:使用 Databricks 嵌入模型的 Delta Sync 索引 | Databricks,根据索引的 embedding source column 生成 | 以 query_text 发送搜索文本 |
已连接,但不会调用 |
| 自管理:Direct Access 索引,或具有自身 vector column 的 Delta Sync 索引 | 已连接的 Embeddings Databricks 节点 | 以 query_vector 发送嵌入后的搜索文本 |
每次搜索和插入每个文档时调用 |
由上表可得 Embeddings Databricks 节点的规则:
- 所有模式都必须连接 Embeddings Databricks 节点。缺少该节点时会拒绝运行,并显示
A Embedding sub-node must be connected and enabled。 - 对于托管索引,不会调用 Embeddings 节点。Databricks 自行嵌入查询。
- 对于自管理索引,Embeddings 节点会嵌入查询和插入的文档,因此请选择生成索引 vector 时使用的相同模型和维度。不同模型会导致搜索显示
query vector dimension <n> does not match index vector dimension <m>,或插入显示Databricks rejected the upsert into <index>. Failed primary keys: ...。
设置节点
- 将节点添加到工作流。对于 Retrieve Documents (As Tool for AI Agent) 检索文档(作为 AI Agent 工具),请选择 AI Agent 或 Databricks AI Agent 节点 Tool 工具连接器上的 +。对于 Retrieve Documents (As Vector Store for Chain/Tool) 检索文档(作为 Chain/Tool 的 Vector Store),请选择 Vector Store Retriever 或 Vector Store Question Answer Tool 节点 Vector Store 向量存储连接器上的 +。
- 在 Credential to connect with 要连接的凭据下,选择 Databricks OAuth2 凭据或新建凭据。
- 设置 Operation Mode 操作模式。各模式的字段请参阅节点参数。
- 在 Index 索引中选择索引:
- From List 从列表中选择:节点列出凭据可见的所有 Vector Search endpoint 上的每个索引,并标记为
DELTA_SYNC - <endpoint>或DIRECT_ACCESS - <endpoint>。输入文本可按名称筛选。在 Insert Documents 插入文档模式下,列表仅显示 Direct Access 索引。 - Name 名称:输入完整 Unity Catalog 名称
catalog.schema.index。节点会拒绝其他格式,编辑器中显示Use the full name: catalog.schema.index;表达式在运行时生成无效名称时显示Invalid Databricks index "<name>": use catalog.schema.index。
- From List 从列表中选择:节点列出凭据可见的所有 Vector Search endpoint 上的每个索引,并标记为
- 在 Content Column 内容列中,选择要作为文档文本(
pageContent)的列。列表会显示除 primary key 和 vector column 外的索引列。对于托管索引,embedding source column 排在最前,并标记为Embedding source column;可将字段留空来使用该列。对于自管理索引,必须选择一列:留空会失败并显示Index <name> uses self-managed embeddings. Select a content column。 - 选择 Embedding 嵌入连接器上的 +,然后添加 Embeddings Databricks 节点。
- 填写操作模式所需字段及所需的选项。
节点使用模式
您可以通过以下模式使用 Databricks Vector Store 节点。
作为普通节点插入和检索文档
您可以将 Databricks Vector Store 节点用作普通节点来插入或获取文档。此模式将节点放在普通连接流中,不使用 agent:使用 Insert Documents 插入文档从 document loader 加载 Direct Access 索引,使用 Get Many 获取多个根据 prompt 运行搜索,并在工作流其余部分处理中结果。
作为工具直接连接到 AI agent
您可以将 Databricks Vector Store 节点直接连接到 AI Agent 或 Databricks AI Agent 节点的 tool 连接器,使 agent 在回答问题时将该索引用作知识源。agent 会自行编写搜索查询,工具返回匹配文档。
连接方式为:AI agent(tools 连接器)-> Databricks Vector Store 节点。请参阅示例:使用 AI agent 从 Databricks 索引回答问题。
使用 retriever 获取文档
您可以将 Vector Store Retriever 节点与 Databricks Vector Store 节点搭配使用,从索引中获取文档。这通常与 Question and Answer Chain 节点一起使用,以获取 Vector Store 中与指定 chat input 匹配的文档。
连接流为:Question and Answer Chain(Retriever 连接器)-> Vector Store Retriever(Vector Store 连接器)-> Databricks Vector Store。
使用 Vector Store Question Answer Tool 回答问题
另一种模式使用 Vector Store Question Answer Tool 汇总结果,并根据 Databricks Vector Store 节点回答问题。此模式不直接将 Databricks Vector Store 连接为工具,而是使用专为汇总 Vector Store 数据设计的工具。
连接流为:AI agent(tools 连接器)-> Vector Store Question Answer Tool(Vector Store 连接器)-> Databricks Vector Store。
节点参数
此 Vector Store 节点有四种模式:Get Many 获取多个、Insert Documents 插入文档、Retrieve Documents (As Vector Store for Chain/Tool) 检索文档(作为 Chain/Tool 的 Vector Store) 和 Retrieve Documents (As Tool for AI Agent) 检索文档(作为 AI Agent 工具)。你选择的模式决定了可以用该节点执行哪些操作,以及可用的输入和输出。
节点不提供 Update Documents 更新文档模式。每种模式都使用设置节点中说明的 Index 索引和 Content Column 内容列字段,以及以下字段。
Rerank Results 重排结果
启用重排序。如果启用此选项,必须将重排序节点(例如 Reranker Cohere)连接到 Vector Store。然后该节点将对查询结果重新排序。您可以将此选项与 Get Many、Retrieve Documents (As Vector Store for Chain/Tool) 和 Retrieve Documents (As Tool for AI Agent) 模式结合使用。
Get Many 获取多个参数
- Prompt 提示:输入搜索文本。对于托管索引,节点以
query_text发送;对于自管理索引,Embeddings Databricks 节点会先生成嵌入。 - Limit 限制:输入要返回的结果数。默认为
4。这是控制结果数量的唯一方式;请参阅不提供分数阈值。 - Include Metadata 包含元数据:是否在输出中包含文档 metadata。默认启用。
每个输出项都包含文档及其分数,格式为 { "document": { "pageContent": "...", "metadata": { ... } }, "score": 0.73 }。不同索引或搜索模式的分数不可比较。
Insert Documents 插入文档参数
- Index 索引:Direct Access 索引。列表仅显示此类索引。按名称输入 Delta Sync 索引时,会在任何写入前失败。
- Content Column 内容列:接收文档文本的列。该列必须存在于索引中,且不能是 primary key 或 vector column。节点会在写入前报告错误选择,例如
Column id is the primary key of <index>. Select another Content Column或Index <name> has no column <column>. Select a Content Column from: text, source。 - Embedding Batch Size 嵌入批量大小:节点在一次请求中交给 Embeddings Databricks 节点进行嵌入的文档数。默认为
200。
将 Default Data Loader 等 document loader 连接到 Document 文档输入。节点使用已连接的 Embeddings Databricks 节点为文档生成嵌入,每个文档写入一行,并输出已插入的文档。数据行会在数秒内可供搜索。
节点按以下方式填充数据行:
- Primary key 使用随机 UUID。内置 document loader 不会设置 document ID,因此重复运行相同插入会重复添加文档,而不是更新文档。请在上游移除重复项,或在 Databricks 中删除旧数据行。带有自身
id的文档(例如来自 LangChain Code 节点)会以该 key 写入,并替换具有相同 key 的数据行。 - 与索引列匹配的 loader metadata key 会写入对应列。节点会丢弃没有匹配列的 key,也会丢弃与 primary key、content column 或 vector column 同名的 key。丢弃 key 时不会显示警告,输出项中仍会显示这些 key。
- 取消执行会停止插入。节点已写入的数据行仍会留在索引中。
Retrieve Documents (As Vector Store for Chain/Tool) 检索文档(作为 Chain/Tool 的 Vector Store)参数
除 Index 索引和 Content Column 内容列外,此模式没有其他字段。连接的 retriever 或 tool 控制获取的文档数量:请在 Vector Store Retriever 或 Vector Store Question Answer Tool 节点上设置 Limit 限制。此处设置的节点选项适用于这些节点运行的每次搜索。
Retrieve Documents (As Tool for AI Agent) 检索文档(作为 AI Agent 工具)参数
- Description 描述:向 agent 说明索引包含什么,以及何时应搜索。具体描述(如
Company handbook. Use it for any question about internal policies and processes.)能让工具调用更可靠。agent 看到的工具名称为节点名称。 - Limit 限制:输入每次工具调用返回的文档数。默认为
4。 - Include Metadata 包含元数据:是否在工具结果中包含文档 metadata。默认启用。
节点选项
这些选项适用于三种搜索模式:Get Many 获取多个、Retrieve Documents (As Vector Store for Chain/Tool) 检索文档(作为 Chain/Tool 的 Vector Store)和 Retrieve Documents (As Tool for AI Agent) 检索文档(作为 AI Agent 工具)。
Metadata Columns 元数据列
要在文档 metadata 中返回的列。默认情况下,节点返回索引中除 primary key、content column 和 vector column 外的每一列。选择子集可以减少 agent 读取的 payload。列表不提供 primary key 或 vector column。
Search Mode 搜索模式
- Vector 向量(默认):完全按语义相似度对结果排序。作为
query_typeANN发送。 - Hybrid 混合:在搜索文本上添加关键词匹配,让包含产品代码等精确术语的文档排在最前。作为
query_typeHYBRID发送。对于自管理索引,节点会同时发送 vector 和文本。混合搜索每次查询最多返回 200 个结果。
Metadata Filter 元数据筛选器
一个 JSON 对象,用于将结果限制为索引中符合条件的数据行。节点将其作为 filters_json 发送。同一对象中的 key 以 AND 组合。除相等条件外,key 还包含列名和运算符:
| 条件 | Metadata Filter |
|---|---|
| 等于某个值 | {"source": "handbook"} |
| 不等于 | {"source NOT": "draft"} |
比较(<、<=、>、>=) |
{"year >=": 2025} |
| 单列范围 | {"price >=": 30000, "price <=": 55000} |
| 多个值中的任意一个 | {"source": ["handbook", "faq"]} |
Token 匹配(不支持 % 通配符) |
{"title LIKE": "pricing"} |
| 多列(AND) | {"source": "handbook", "year >=": 2025} |
注意事项:
- 筛选器仅适用于 Standard Vector Search endpoint。Storage Optimized endpoint 要求节点目前不支持的 SQL filter 字符串。设置筛选器后,节点每次执行时读取一次 endpoint 类型;如果 endpoint 不是 Standard,会在查询前失败并显示
Index <name> runs on endpoint <endpoint> of type STORAGE_OPTIMIZED. The Metadata Filter works on STANDARD endpoints only.未设置筛选器的查询可用于所有 endpoint 类型。 - 严格筛选器返回的数据行数可能少于 Limit 限制。Databricks 会先获取最近邻候选项,再进行筛选,因此需要更多匹配项时请提高 Limit 限制。
- 筛选器无匹配结果时返回零个数据项,不会报错。格式错误的 JSON 会在任何请求前失败,并显示指出 Metadata Filter 元数据筛选器字段的验证错误。
- 不支持
BETWEEN、LIKE中的通配符,以及对 JSON 列中嵌套值执行数值比较。完整语法请参阅 Databricks 筛选指南。
已知限制
- 始终需要 Embeddings 输入:每种模式都需要 Embeddings Databricks 节点,包括 Databricks 负责嵌入查询且不会调用该节点的托管索引。
- 只能向 Direct Access 索引插入文档:节点只能读取 Delta Sync 索引。插入操作会拒绝将 primary key 或 vector column 用作 Content Column 内容列。
- 插入的数据行使用随机 key,除非文档自带
id。内置 document loader 不会设置 ID,因此重新运行会产生重复数据行,而不是更新数据行。 - Metadata Filter 仅适用于 Standard endpoint:Storage Optimized endpoint 使用节点目前不支持的 SQL filter 字符串。在此类 endpoint 上执行带筛选器的查询会在运行前失败。
- 混合搜索每次查询最多返回 200 个结果。
- 严格筛选器返回的行数可能少于 Limit,因为 Databricks 会先获取最近邻候选项,再进行筛选。
- 按 token 付费服务的速率限制:一次为大量文档生成嵌入可能触发 embeddings 模型服务的工作区速率限制。规避方法请参阅 Embeddings Databricks 页面的速率限制。
不提供分数阈值
节点有意不提供 score threshold 字段。Vector 和 Hybrid 搜索使用不同的分数尺度:自管理索引的 similarity score 可能约为 0.003,而 Hybrid 搜索会将精确关键词匹配排为 1.0。单一阈值无法同时适用于二者,错误阈值还会无声地丢弃所有结果。请使用 Limit 限制控制结果数量;如果需要针对特定索引的阈值,可在后续节点中根据 score 字段筛选。
示例:使用 AI agent 从 Databricks 索引回答问题
此工作流根据一个使用 Databricks 计算 embeddings 的 Delta Sync 索引,回答公司手册相关的聊天问题。请将索引和模型名称替换为您自己的名称。
- 在 Databricks 中,基于手册表创建 Delta Sync 索引,例如
main.docs.handbook_index,以content列作为 embedding source,以source列记录文档来源。请参阅创建和查询 Vector Search 索引。 - 添加 Chat Trigger 节点。
- 在其后添加 Databricks AI Agent 节点。不需要导出 trace 时,AI Agent 节点也以相同方式工作。在 Options 选项中,将 System Message 系统消息设为类似
Answer questions about the company handbook with the handbook tool. Say so when the handbook doesn't cover a question.的内容。 - 选择 agent Chat Model 聊天模型连接器上的 +,添加 Databricks Chat Model 节点。选择 Databricks 凭据和支持聊天的模型服务,例如
system.ai.meta-llama-3-3-70b-instruct。 - 选择 Memory 记忆连接器上的 +,添加 Simple Memory 节点,让后续问题保留上下文。
- 选择 Tool 工具连接器上的 +,添加 Databricks Vector Store 节点。将节点命名为
handbook。将 Operation Mode 操作模式设为 Retrieve Documents (As Tool for AI Agent) 检索文档(作为 AI Agent 工具),在 Index 索引中选择main.docs.handbook_index,将 Content Column 内容列留空以使用 embedding source column,将 Description 描述设为Company handbook. Use it for any question about internal policies and processes.,并将 Limit 限制保留为4。 - 选择 Vector Store Embedding 嵌入连接器上的 +,添加 Embeddings Databricks 节点,使用相同凭据和 embeddings 模型服务,例如
system.ai.gte-large-en。该索引为托管索引,所以 Databricks 会嵌入查询,绝不会调用此节点,但仍必须连接该节点。 - 可选:在 agent 节点中选择 Databricks 凭据并启用 Export Traces to MLflow 导出跟踪到 MLflow,即可在 MLflow Tracing 中查看每次运行,包括对手册的搜索。
- 打开聊天,提出手册能够回答的问题。执行记录会显示对
handbook工具的一次调用,其中包含 agent 的搜索查询和返回的文档。
要改为搜索自管理索引,请在 Vector Store 节点上设置 Content Column 内容列,并在 Embeddings Databricks 节点中选择生成索引 vector 的模型。要将 agent 限制在索引的一部分,请向 Vector Store 节点选项添加类似 {"source": "handbook"} 的 Metadata Filter 元数据筛选器。
相关资源
- 从社区包迁移
- Databricks 凭据
- Embeddings Databricks
- Databricks AI Agent
- Databricks Chat Model
- Databricks 节点:用于创建和列出索引等 Vector Search 索引操作
- Vector Store Retriever 和 Vector Store Question Answer Tool
- Databricks 文档中的 Databricks Vector Search、Query index API 和筛选指南
查看 n8n 的 Advanced AI 高级 AI 文档。
提示
Parameter resolution in sub-nodes 子节点参数解析
使用表达式处理多个项目时,子节点的行为与其他节点不同。
大多数节点,包括根节点,接受任意数量的项目作为输入,处理这些项目,并输出结果。您可以使用表达式引用输入项目,节点会依次为每个项目解析表达式。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 会依次解析为每个名称。
在子节点中,表达式始终解析为第一项。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 始终解析为名字。
常见问题
必须连接并启用 Embedding 子节点
节点的 Embedding 嵌入输入未连接 Embeddings Databricks 节点。请在所有模式下连接该节点,即使使用永远不会调用此节点的托管索引也是如此。
索引使用自管理嵌入
错误 Index <name> uses self-managed embeddings. Select a content column 表示索引自带 vector,因此节点无法推断哪个列包含文本。请在 Content Column 内容列中选择相应列。
索引与其源表同步
Insert Documents 插入文档以 Delta Sync 索引为目标,节点报告 Index <name> syncs from its source table. Use a Direct Access index to insert documents。Databricks 从源表填充 Delta Sync 索引,因此请向该表添加数据行,或改为向 Direct Access 索引插入。
UC 实体权限不足
Databricks Vector Search request failed (403): Insufficient permissions for UC entity <index> 表示凭据身份缺少索引的 SELECT,或插入所需的 MODIFY。请在 Unity Catalog 中授予相应权限,并同时授予 USE CATALOG 和 USE SCHEMA。
Unity Catalog 实体不存在
Databricks Vector Search request failed (404): Unity Catalog entity <name> does not exist 表示 Index 索引名称与该身份可见的索引不匹配。请检查三段式名称,或使用 From List 从列表中选择来选择索引。
查询向量维度与索引不匹配
错误 query vector dimension <n> does not match index vector dimension <m> 表示 Embeddings Databricks 节点使用的模型维度与索引不同。请选择生成索引 vector 的模型。插入时,同样的不匹配会显示为 Databricks rejected the upsert into <index>. Failed primary keys: ...,且节点不会写入任何内容。
获取 Databricks access token 失败
凭据无法从工作区获取 token。对于服务主体,invalid_client 表示主体尚未分配给工作区:请为其添加 Workspace access 权利。如果错误说明显示 HTML,则凭据的 Host 主机不是 Databricks 工作区 URL。
Host 必须使用 HTTPS
由于凭据的 Host 主机不是 https:// URL(例如以 http:// 开头或没有 scheme),节点会失败并显示 Databricks host must use https。每个请求都携带 token,因此节点拒绝明文 HTTP。请输入以 https:// 开头的完整工作区 URL。
插入期间达到速率限制
Embeddings 模型服务以 REQUEST_LIMIT_EXCEEDED 拒绝某个批次。节点不会写入触发限制的块,但此前已写入的块仍留在索引中,因此重试前请检查索引。请参阅 Embeddings Databricks 页面上的速率限制。
Metadata Filter 仅适用于 STANDARD endpoint
已设置 Metadata Filter 元数据筛选器,但索引运行在 Storage Optimized endpoint 上;该 endpoint 接受节点尚不支持的 SQL filter 字符串。请移除筛选器,或将索引迁移到 Standard endpoint。如果消息以 Could not read the type of the endpoint 开头,则凭据身份无法读取 Vector Search endpoint:请授予其 endpoint 读取权限,或移除筛选器。
[^1]: AI chain 让您通过一系列组件调用与大语言模型(LLM)及其他资源交互。n8n 中的 AI chain 不使用持久 memory,因此不能用来引用先前上下文(这种情况请使用 AI agent)。 [^2]: AI agent 是能够响应请求、做出决策并代表用户执行现实任务的人工智能系统。它使用大语言模型(LLM)解释用户输入,并根据可用的信息和资源决定处理请求的最佳方式。 [^3]: 在 AI 场景中,工具是一种附加资源,AI 在响应请求时可利用它获取特定信息或功能。AI 模型可以使用工具与外部系统交互,或完成具体且专注的任务。