Bug: AI Assistant “Connect a model” fails with “The service returned an unexpected response” on custom OpenAI-compatible Base URLs

该报错通常出现在自托管 n8n 的 Settings > AI Assistant > "Connect a model" 中,使用自定义 OpenAI-compatible Base URL(如 OmniRoute、LiteLLM、vLLM 等网关/代理)时连接验证失败。请优先查看服务端日志中的验

快速结论:该报错通常出现在自托管 n8n 的 Settings > AI Assistant > “Connect a model” 中,使用自定义 OpenAI-compatible Base URL(如 OmniRoute、LiteLLM、vLLM 等网关/代理)时连接验证失败。请优先查看服务端日志中的验证失败分类(unauthorized / forbidden / quota_exceeded / rate_limited / timeout / unreachable / invalid_response / provider_error)以及经过脱敏的 provider 错误,据此判断是请求未到达网关,还是网关返回的响应结构被拒绝。

适用环境:Issue 中已确认:n8n 1.x / 2.x,Docker / Docker Compose 自托管(Linux),数据库 PostgreSQL 或 SQLite,Node.js 20.x+。涉及的自定义网关包括 OmniRoute、vLLM(含经 LiteLLM 的情况),模型包括 gemini-2.0-flash、gpt-4o-mini、GLM、Gemma。

最快修复方案:暂无确认的一步修复方案。Issue 中提到的修复只有 Gateway 侧的兼容处理(见 kaovilai/copilot-api PR #9 及相关仓库说明),并非 n8n 内置的已验证修复。

注意事项:连接对话框只显示笼统的 “The service returned an unexpected response”,详细原因仅记录在服务端日志中,需要具备日志访问权限。Issue 中另有参与者在后续评论中更正:PR #37156 实际只修改了 `.github/actions/setup-nodejs/action.yml`,与模型连接路径无关,因此不能作为该问题已修复的证据。

问题场景

在自托管 n8n 中进入 Settings > AI Assistant > “Connect a model”,Provider 选择 OpenAI (custom / compatible),填入自定义 Base URL(例如 http://<internal-proxy-host>:20128/v1 或 HTTPS 反向代理地址)、API Key 和模型名(如 gemini-2.0-flash、gpt-4o-mini),点击 Connect 后连接测试失败。该端点通过 curl 能正常完成标准 chat completions 和 tool-calling 校验。另有用户在使用自托管 OmniRoute 实例时遇到相同现象,尝试模型别名后结果不变。

报错原文

The service returned an unexpected response. Check that the URL points to the supported API and try again.

部分网关侧还会出现以下日志:

Unsupported input item type: item_reference (gemma)
KeyError: 'role' (GLM - unhandled error path in vLLM PR #53380 stateless responses handler)

原因分析

根据 Issue 讨论,同一个笼统错误可能由两类彼此独立的问题引起(可能原因):

  • n8n 将 UI 上选择的 custom OpenAI-compatible provider 折叠为标准的 openai 后端 provider,改为依赖 base-URL 启发式判断,而不是保留显式的 provider 类型。
  • 部分本应兼容的网关无法通过严格的 @ai-sdk/openai schema 校验,例如响应中省略了 choices[].index,此时 n8n 只报告 “Invalid JSON response” 之类的信息。
  • 另有一类路径:连接保存在某些情况下会发送 POST /v1/responses,请求体包含 {"type":"item_reference","id":"..."} 输入;使用 vLLM Responses API handler(vLLM 本身或经 LiteLLM 接入 GLM、Gemma 等模型)的后端无法解析这类引用,返回 400 或 500,n8n 最终表现为 “unexpected response”。

Issue 中给出的定位线索:自定义端点校验在 packages/cli/src/modules/instance-ai/instance-ai-verification.service.ts 中执行(以提交 4169b55bf3b3 阅读)。它发送一次最小探测请求(generateText,内容 “Reply with OK.”,最大输出 16 tokens,30 秒超时中断),并把失败归入 unauthorized / forbidden / quota_exceeded / rate_limited / timeout / unreachable / invalid_response / provider_error 分类。该分类可以区分“请求从未到达网关”和“请求已到达但响应结构被拒绝”,分类结果与脱敏后的 provider 错误都会写入服务端日志(logVerificationFailure)。

环境排查

  • 确认 n8n 版本与部署方式:n8n 1.x / 2.x,Docker / Docker Compose 自托管,Node.js 20.x+。
  • 确认数据库类型:PostgreSQL 或 SQLite(Issue 中两类均有出现,未指向特定数据库问题)。
  • 确认所用网关类型及版本:OmniRoute、vLLM、LiteLLM 等,并确认其 Responses API 是否支持 item_reference 输入项。
  • 确认 Base URL 是否可被 n8n 容器访问(内网主机名、端口 20128 或反向代理地址、TLS 证书是否有效)。
  • 确认所选模型的响应结构是否符合 OpenAI schema,重点检查 choices[].index 等字段是否缺失。

解决步骤

  1. 先打开 n8n 服务端日志,在点击 Connect 失败后查找 logVerificationFailure 相关记录,记录失败分类(unauthorized / forbidden / quota_exceeded / rate_limited / timeout / unreachable / invalid_response / provider_error)和脱敏后的 provider 错误。
  2. 若分类为 timeout / unreachable,检查 Base URL 在 n8n 容器内是否可达(内网 DNS、端口、反向代理、证书),必要时在容器内用 curl 复测同一路径。
  3. 若分类为 unauthorized / forbidden / quota_exceeded / rate_limited,按网关侧要求检查 API Key 权限、配额与限流设置。
  4. 若分类为 invalid_response / provider_error,对照网关实际返回的 JSON 检查是否符合 OpenAI schema(如 choices[].index),并在网关侧修复响应格式。
  5. 若网关是 vLLM / LiteLLM 系且日志出现 item_reference 或 KeyError: 'role',属于网关对 Responses API 输入项兼容性问题,需在网关侧处理(可参考 kaovilai/copilot-api PR #9 及相关仓库中作者的兼容性修复说明),而不是在 n8n 中修改连接参数。
  6. 可优先尝试:在网关侧启用/配置严格的 OpenAI 兼容响应(补齐 schema 必需字段、支持或拒绝 Responses API 的 item_reference),再重新 Connect。此步骤为 Issue 中用户反馈的修复路径,n8n 侧的一步修复尚未得到验证。

验证方法

在网关侧修复后,回到 Settings > AI Assistant > “Connect a model” 重新点击 Connect;同时观察服务端日志中新的验证记录,确认不再出现同类失败分类、provider 错误为空或不再是 invalid_response / provider_error,连接对话框显示成功。最终以 Issue 是否被正式关闭和发布说明为准,Issue 讨论中也强调应避免基于不相关的 PR 提前关闭。

参考来源

n8n-io/n8n #36873
kaovilai/copilot-api PR #9

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36045

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注