Azure OpenAI 上传图片失败？客户端选择与网关转发方案

不少团队把模型调用迁到 Azure OpenAI，是出于合规、数据驻留和统一账单的考虑。但迁移之后常遇到一个落差：同一个客户端，填官方 OpenAI 的 key 时图片上传一切正常，换成 Azure 的 endpoint 和密钥，图片按钮就形同虚设——要么点了没反应，要么图传上去了，模型却回答「我看不到图片」。

这不是模型能力的问题。同样是 GPT-4o 一类的多模态模型，Azure 侧完全支持图像输入，差别在于客户端有没有按 Azure 的方式去调用。下面把原因拆开，给出三条可落地的路径，最后附一份排查清单。

为什么官方 OpenAI 能传图，Azure 就不行

接口地址与鉴权方式不同

官方接口是 https://api.openai.com/v1/chat/completions，用 Authorization: Bearer <key>。Azure 则是：

https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<version>

鉴权头换成 api-key: <key>，路径里带部署名，还多一个必填的 api-version。一些客户端在「OpenAI 兼容」模式下只会把 base URL 拼上 /v1/chat/completions，根本走不到 Azure 的路径；另一些虽然支持填 Azure 参数，但在发送多模态消息的分支里写死了官方地址，图就只发文本部分。

部署名撞上客户端的模型白名单

很多客户端判断「这个模型能不能收图」的方式很粗暴：看模型名里有没有 gpt-4o、vision 之类的关键字。而 Azure 里请求参数填的是部署名，团队常常起成 prod-gpt4o、chat-prod、aoai-main 这种名字。名字对不上白名单，客户端就自动降级成纯文本请求，图片被静默丢弃。

api-version 决定消息格式能否被接受

图像输入依赖 content 数组里的 image_url 类型。较早的 api-version 不认识这种结构，会直接报参数错误，或者把数组当成字符串处理。不同部署可用的版本不一样，具体以 Azure 官方文档和控制台里该资源实际可用的版本为准，不要照抄网上某篇文章里的固定值。

图片本身的传法

本地图片通常要转成 data:image/png;base64,... 形式内联发送，公网图片才用 URL。如果客户端只支持传 URL、或只对官方域名做图片抓取，也会失败。另外服务端对图片体积、格式都有上限，大图建议先压缩。

第一步：先用 curl 确认部署本身能读图

在怀疑客户端之前，先绕开它。准备一个 body.json：

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "描述这张图片的内容" },
        { "type": "image_url", "image_url": { "url": "data:image/png;base64,<粘贴base64>" } }
      ]
    }
  ],
  "max_tokens": 300
}

然后调用：

curl -X POST "https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<你的api-version>" \
  -H "api-key: $AZURE_OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

判定很直接：

• 能返回图片描述：部署和模型没问题，问题在客户端或中间的网关，往下看方案一、方案二。
• 报 400 参数错误：多半是 api-version 太旧或消息结构不对，换版本、核对字段。
• 报 401/403：key 或资源地址错，先修通鉴权。
• 报内容过滤相关错误：这是 Azure 侧的策略拦截，换一张图验证，再去看资源的内容过滤配置。

方案一：换一个明确支持 Azure 视觉的客户端

选型时注意两点：一是确认填的是「Azure OpenAI」而不是「OpenAI 兼容」模式；二是装完先拿一张小图做冒烟测试，别等接进工作流才发现问题。走自部署的客户端还有个附带好处：密钥留在自己的服务器上，不用交给第三方。

方案二：加一层 OpenAI 兼容网关（最通用）

如果换客户端解决不了，或者在多个工具间来回切换太麻烦，就在中间放一个协议转换层：客户端统一按官方 OpenAI 的格式说话，网关负责翻译成 Azure 的路径和鉴权。one-api、new-api 这类项目都能干这件事。

大致步骤：

1. 部署网关。用 Docker 起一个实例，把数据目录挂出来持久化，具体镜像名和端口以项目文档为准。
2. 添加渠道。类型选 Azure OpenAI，填资源 endpoint、密钥、api-version，模型处填部署名。
3. 做模型映射。让客户端请求 gpt-4o，网关把它转发到你的部署名上。这样客户端里的模型白名单判断也能通过。
4. 生成令牌。在网关里创建一个 API Key，这就是之后填给客户端的东西。
5. 改客户端配置。Base URL 指向网关的 /v1，API Key 填上一步的令牌，模型填映射后的名字，其余保持默认。

实践中的经验：用 GPT-4o、GPT-4o-mini 走这条链路读图基本稳定；有反馈称部分 GPT-4-turbo 部署在图片理解上表现异常，如果一定要用，先单独验证。另外网关本身要长期在线，机器不稳定会变成新的故障点，放在一台常开的机器上更省心。

方案三：脚本里直接按 Azure 格式调用

如果只是自己跑批处理，不必绕客户端。官方 SDK 提供了 Azure 客户端，把 endpoint、key、api-version 传进去，消息体里放 image_url 即可：

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://<resource>.openai.azure.com",
    api_key="<key>",
    api_version="<api-version>",
)

resp = client.chat.completions.create(
    model="<部署名>",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "这张图里有什么"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}},
    ]}],
)

注意 model 填的是部署名，不是模型家族名，这是最容易踩的坑。

排查清单

小结

这类问题的本质是「协议方言」：Azure OpenAI 在路径、鉴权、版本参数、部署命名上都和官方有差异，而很多客户端只实现了官方那一套。稳妥的处理顺序是：先用 curl 把部署本身验证通，再换一个明确支持 Azure 的客户端做冒烟测试；如果工具链复杂、想统一入口，就在中间加一层网关做协议转换。无论走哪条路，都记得把 model 当成部署名来填，并定期核对 Azure 官方文档中可用的 api-version 与图像输入限制，这类信息更新较快。