使用Open WebUI对接Azure OpenAI模型时502错误分析：API版本与鉴权头处理

Open WebUI 对接 Azure OpenAI 出现 502，先要明确“502 发生在哪一段”。浏览器能打开 Open WebUI，说明 Open WebUI 自身服务正常；模型调用时返回 502，通常发生在 Open WebUI 后端向 Azure 发起请求的环节。Azure 返回 400/401/403/404 时，Open WebUI 可能把它包装成 502 展示给前端，所以不能只凭状态码断定 Azure 不可达。

502 大概率在 Open WebUI 与 Azure OpenAI 之间。先隔离网络层：在运行 Open WebUI 的机器上直接 curl Azure 端点；若成功，再检查 Base URL 是否包含完整部署路径、请求是否带 api-version，以及鉴权头是 api-key 还是 Bearer。核心是先用最小请求确认 Azure 侧，再逐层修正 Open WebUI 的请求构造。

下面按“先验证 Azure、再检查配置、最后处理请求头”的顺序排查。每一步都有可执行命令，建议保留 curl 输出以便判断。

先确认 Azure 端点在当前网络下是否直接可用

在运行 Open WebUI 的主机或容器内，用 curl 发起一个最小的聊天补全请求。需要把 {resource}、{deployment}、{key} 和 api-version 换成实际值。api-version 以 Azure 控制台当前可用的版本为准，不要使用未开通或已停用的版本。

使用Open WebUI对接Azure OpenAI模型时502错误分析：API版本与鉴权头处理

curl -i -X POST "https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-06-01" \
  -H "api-key: {key}" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"ping"}]}'

如果这个请求返回 200，说明 Azure 服务、网络和密钥都正常。如果返回 401/403，密钥或鉴权头有问题；如果返回 404，部署名或路径拼写有误；如果连接超时或 502/503，则网络到 Azure 不通。这个直接请求的结果，是后面所有判断的基线。

检查 Open WebUI 的 Base URL 与 api-version

Azure OpenAI 的完整路径是 /openai/deployments/{deployment}/chat/completions，并且依赖 api-version 查询参数。Open WebUI 若按标准 OpenAI 接口配置，通常需要把 Base URL 设置为 https://{resource}.openai.azure.com/openai/deployments/{deployment}，而不是裸域名或 /v1。

有些 Open WebUI 版本允许单独指定 OPENAI_API_VERSION；如果没有这个配置项，客户端可能不会自动带 api-version，导致 Azure 返回错误并被 Open WebUI 渲染为 502。需要结合你当前使用的 Open WebUI 启动参数或环境变量确认。

建议先看 Open WebUI 日志，找到实际发往 Azure 的 URL 和状态码。通常日志里会记录 upstream 的响应体，比如 InvalidApiVersion 或 ResourceNotFound，这些信息能直接指明是版本问题还是路径问题。

鉴权头：api-key 与 Authorization Bearer 的区别

Azure OpenAI 接受 api-key 头直接传密钥，也支持 Authorization: Bearer 传 Azure AD 令牌。Open WebUI 很多实现使用 OpenAI 官方 SDK，默认发送 Authorization: Bearer。把 Azure api-key 填到 Open WebUI 的 API Key 输入框后，若客户端仍发送 Bearer 头，Azure 侧会认为是无效令牌，返回 401，最终在 Open WebUI 处表现为 502。

要确认实际发送的请求头，可以临时在 Open WebUI 前面加一层反向代理或抓包，也可以添加一个调试接口打印请求头。如果确认头不匹配，有两种处理方向：一是使用支持自定义请求头的中间层，把 Authorization: Bearer 转换为 api-key；二是改用 Azure AD 身份认证，让 Bearer 中携带有效的令牌。前者实现成本低，适合先验证连通性。

验证清单

在 Open WebUI 所在机器上直接 curl Azure 端点，确认返回 200。
确认部署名称与配置的模型名称一致，Open WebUI 里的“模型”通常必须等于 Azure 部署名。
检查 Open WebUI 日志，定位上游 HTTP 状态码和错误体。
确认实际请求的 URL 包含 /openai/deployments/{deployment} 和 api-version。
确认请求头中传递的是 api-key 还是 Authorization: Bearer，并与密钥类型匹配。
如果 Open WebUI 与服务端之间有代理，检查代理是否改写了 Host 或路径。

边界与临时方案

在 Open WebUI 内绕过鉴权头的自定义方案只适合本地调试。若要长期使用，建议优先考虑使用 Azure 官方支持的认证方式，或者用一个专门的 API 网关统一处理 Azure 的部署路径、api-version 和鉴权头。api-version 不要随意选择，应以当前环境实际支持且能正常返回的版本为准。若 Azure 侧网络不通，需要检查防火墙、出网 IP 白名单和 SSL 证书，而不是继续调整 Open WebUI 配置。