Databricks Chat Model 聊天模型节点
使用 Databricks Chat Model 聊天模型节点,可以在 Databricks 工作区所提供的模型上运行 AI 智能体和链。此节点会查询 Unity AI Gateway 模型服务,因此既适用于 Databricks 托管的基础模型,也适用于通过该网关路由的外部提供商。
本页面介绍使用 Databricks Chat Model 聊天模型节点所需的先决条件、设置步骤、节点参数和已知限制。
提示
Credentials 凭据
有关设置身份验证的指南,请参阅 Databricks 凭据。
提示
Parameter resolution in sub-nodes 子节点参数解析
使用表达式处理多个项目时,子节点的行为与其他节点不同。
大多数节点,包括根节点,接受任意数量的项目作为输入,处理这些项目,并输出结果。您可以使用表达式引用输入项目,节点会依次为每个项目解析表达式。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 会依次解析为每个名称。
在子节点中,表达式始终解析为第一项。例如,给定五个 name 值的输入,表达式 {{ $json.name }} 始终解析为名字。
先决条件
- 已启用 Unity AI Gateway 的 Databricks 工作区。
- n8n 中的 Databricks OAuth2 凭据,可使用服务主体或用户登录。此节点不支持个人访问令牌。
- 凭据所认证的身份需要对模型服务所在的目录和架构拥有 USE CATALOG 和 USE SCHEMA 权限,并对模型服务拥有 EXECUTE 权限。默认情况下,Databricks 会向所有工作区用户授予
system.ai模型服务的 EXECUTE 权限。
设置节点
- 向工作流添加 AI Agent 智能体节点(或其他接收聊天模型的根节点)。
- 选择节点 Chat Model 聊天模型连接器上的 +,然后选择 Databricks Chat Model。
- 在 Credential to connect with 用于连接的凭据下,选择现有的 Databricks OAuth2 凭据或创建新凭据。根据身份验证类型按照以下步骤操作。
- 打开 Model 模型列表并选择模型服务。n8n 会加载凭据有权访问且支持聊天补全的模型服务。要使用未列出的服务,请切换到 ID 并输入其全名,例如
system.ai.databricks-meta-llama-3-3-70b-instruct。
使用服务主体设置
对于定时运行或由 Webhook 触发的智能体等无人值守工作流,请使用服务主体。
- 请 Databricks 管理员创建服务主体和 OAuth 密钥,并为其授予要使用的模型服务的 EXECUTE 权限。
- 在 n8n 凭据中,将工作区 URL 输入为 Host 主机,将 Grant Type 授权类型保留为 Client Credentials (Service Principal),然后输入 Client ID 客户端 ID和 Client Secret 客户端密钥。
- 保存凭据并在节点中选择它。
使用用户登录设置
当智能体应使用你自己的 Databricks 权限运行,并以你的身份出现在 Databricks 审计日志中时,请使用用户登录。
- 请 Databricks 账户管理员创建自定义 OAuth 应用连接,并与你共享其客户端 ID 和密钥。
- 在 n8n 凭据中,将工作区 URL 输入为 Host 主机,将 Grant Type 授权类型设置为 Authorization Code (User),然后输入 Client ID 客户端 ID和 Client Secret 客户端密钥。
- 选择 Connect 连接并登录 Databricks。
- 在节点中选择该凭据。n8n 会在长时间执行期间刷新访问令牌,因此智能体可以运行超过一小时的令牌有效期。
Parameters 参数
- Model 模型:生成补全内容的 Unity AI Gateway 模型服务,名称格式为
catalog.schema.service。- From List 从列表中选择:从凭据有权访问且支持聊天补全的模型服务中选择。
system.ai中 Databricks 托管的基础模型和外部提供商路由都会显示。 - ID:直接输入模型服务的全名。对于支持聊天但未声明聊天功能的服务,请使用此选项。
- From List 从列表中选择:从凭据有权访问且支持聊天补全的模型服务中选择。
Options 选项
- Frequency Penalty 频率惩罚:根据新 token 在文本中已经出现的频率进行惩罚,以减少逐字重复。范围为
-2到2,默认值为0。 - Maximum Number of Tokens 最大 token 数:补全内容最多生成的 token 数。默认值为
-1(n8n 不设限制)。 - Response Format 响应格式:选择 Text 文本(默认)或 JSON。JSON 模式要求提示词中包含
json一词,并且模型服务支持 JSON 模式。 - Presence Penalty 存在惩罚:根据新 token 是否已在当前文本中出现进行惩罚,以鼓励引入新主题。范围为
-2到2,默认值为0。 - Sampling Temperature 采样温度:控制随机性。值越低,补全结果越确定。范围为 0 到 2,默认值为 0.7。
- Timeout 超时:请求允许花费的最长时间(毫秒)。默认值为 360000(六分钟)。
- Max Retries 最大重试次数:请求失败后的重试次数。默认值为 2。
- Top P:核采样。调整此项或 Sampling Temperature 采样温度,不要同时调整两者。范围为 0 到 1,默认值为 1。
为智能体选择模型
并非每个模型服务都适合通过此节点用作智能体的工具调用模型。模型必须支持工具调用,而且有些声称支持工具调用的端点并不会返回 AI Agent 智能体可以执行的工具调用。根据 n8n 的测试:
- Llama 3.3 70B 和 Qwen 3.5 能可靠地调用工具,适合作为 Databricks Genie One MCP 服务器和其他工具的默认模型。
- gpt-oss 和 Llama 4 Maverick 端点不会返回 AI Agent 智能体可以执行的工具调用。使用它们的智能体会循环,直到达到 Max Iterations 最大迭代次数,但不会调用任何工具。
你的工作区可能会列出其他模型服务。要测试某个模型,请向智能体提出必须调用工具才能回答的问题,然后检查执行日志。无法正常工作的模型会表现出相同症状:智能体用完所有迭代次数,却没有调用一次工具。
按 token 计费的模型服务在每个工作区中都有速率限制。三个并发的智能体运行就足以触发限制,而节点会在几秒内用完默认的两次重试。对于演示、试点和生产智能体,请使用预置吞吐量端点,或降低智能体并发量。
相关资源
- Databricks 凭据
- 用于 SQL、Unity Catalog 和 Genie Agent REST 操作的 Databricks 节点
- 用于让智能体访问 Genie One 的 Databricks Genie One MCP 服务器
- 使用 Databricks Vector Store 和 Embeddings Databricks,让 agent 搜索 Databricks Vector Search 索引
- 使用 Databricks AI Agent,将 agent 运行导出到 MLflow Tracing
- Databricks 文档中的 Unity AI Gateway 模型服务
查看 n8n 的 Advanced AI 高级 AI 文档。
常见问题
未找到模型服务
模型列表为空,并且节点报告 No model services found。工作区未启用 Unity AI Gateway,或者凭据所认证的身份无法访问任何模型服务。请检查工作区设置,然后为该身份授予至少一个模型服务的 USE CATALOG、USE SCHEMA 和 EXECUTE 权限。
未找到支持聊天的模型服务
凭据可以看到模型服务,但没有服务声明支持聊天补全。将 Model 模型切换为 ID,然后直接输入服务名称。此节点不支持仅提供嵌入功能的服务。
达到速率限制
执行失败并显示 Rate limit reached 或 429 状态。由于请求超过按 token 计费端点的工作区速率限制,Databricks 以 REQUEST_LIMIT_EXCEEDED 拒绝请求。请减少并发的智能体运行,或使用预置吞吐量端点。错误文本会提到 OpenAI,因为此节点使用兼容 OpenAI 的客户端来调用网关。
Host 必须使用 HTTPS
由于凭据的 Host 主机以 http:// 开头,节点失败并显示 Databricks host must use https。每个请求都会携带 token,因此节点拒绝使用明文 HTTP。请将主机更改为 https://。
凭据曾经有效,但请求开始返回 403
对于使用用户登录的凭据,刷新令牌或 OAuth 应用的绝对会话生命周期已经过期。在 n8n 中打开凭据,选择 Switch account 切换账户,然后重新登录。为避免定时工作流遇到此问题,请使用服务主体,或请管理员延长令牌生命周期。