很多人拿到 Azure 账号后卡在同一处：控制台里建好了资源，却不知道「部署名」和「模型名」不是一回事，端点拼出来直接 404 或 401。这篇按操作顺序把开通、部署、取密钥、拼请求、验证连通讲一遍，每一步都给出核对点和常见错法，方便你照着走完并把请求发通。
很多人拿到 Azure 账号后卡在同一个地方：控制台里资源建好了，模型也选好了，可代码一跑就报 404 或者 401。问题基本都不在代码上，而是「部署名」和「模型名」被当成了同一个东西，端点又和 OpenAI 官方的 base 地址混着用。这篇按实际操作顺序把开通、部署、取密钥、拼请求、验证连通走一遍，每一步给出核对点和常见错法，照着走完基本能把第一个请求发通。
先说明适用范围：这篇讲的是通过 Azure 提供的 OpenAI 模型服务做部署和调用，不涉及其他云厂商的同类产品，也不讨论自建推理。如果你只是想本地跑个模型验证想法，Azure 这条链路的重心在配额、部署命名和鉴权归属，和本地跑完全是两套关注点。
动手前先确认三件事
别急着点创建资源。先花五分钟把账号侧、配额侧、成本侧各确认一遍，这三件事任一没落实，后面每一步都会变成无效重试。尤其是区域和配额，很多人反复改代码，其实问题在订阅根本没有对应模型的可用额度。
- 账号与订阅：确认订阅状态正常，且目标区域支持你要用的那类模型；区域不支持就换区，而不是在同一区域反复重试
- 配额与限速：先看清该订阅下这类模型的每分钟请求数、每分钟 token 上限，配额不足会在部署或调用阶段直接被拒
- 成本口径：按量计费和预留容量是两套账，单价与折算方式到 /official-api/providers/azure 核对当时数字，用量不确定就别先买预留
建资源、下模型、记住部署名
Azure 这里有两层概念要先分清楚：资源是容器，模型要靠「部署」放进去。一个资源里可以放多个部署，每个部署各自独立命名。这一步最容易踩的坑，就是把部署名和底层模型名当成一回事。
- 资源（Resource）
- 承载部署的容器，端点和密钥都挂在它下面
- 部署（Deployment）
- 把一个具体模型放进资源后得到的东西，名字由你自己起
- 部署名
- 请求里 model 字段要传的值，和底层模型 ID 无关
- 创建资源并选定区域在控制台建资源时就把区域定下来，后面端点域名会带上这个区域信息；区域选错后面很难原地改。
- 建一个模型部署并起名部署名用自己能认出来的规则，比如用途加环境，别用一串随机字符；这个名字后面要写进代码的 model 字段。
- 记录资源名和部署名把资源名、部署名、区域三项抄到配置里，别只留在浏览器标签页上，切环境时容易对不上。
一个常见的错法：部署名起了个自定义名字，代码里却填了模型 ID，结果请求直接 404。记住，model 字段传的是部署名。这条记住了，后面大部分 404 都能自己排掉。
端点、版本与鉴权参数怎么填
这一步是全篇最容易出错的地方，因为 Azure 的端点和官方 OpenAI 的 base 地址长得不一样，鉴权方式也不一样。把两套东西混用，结果就是 401 或者 404 轮着来。
| 参数项 | 正确填法 | 填错的典型后果 |
|---|---|---|
| 端点 | https://.openai.azure.com | 把官方 base 地址贴进来，直接连不上或 404 |
| 鉴权 | 走 api-key 请求头 | 用 Authorization Bearer，返回 401 |
| 路径 | 带 deployments/ 这一段 | 漏掉这段，接口找不到资源，404 |
| api-version | 作为查询参数带上 | 版本选错，报参数不支持或不识别该模型 |
还有一点：密钥和端点必须来自同一个 Azure 资源。跨资源混搭，哪怕两边都有效，也会 401。至于 api-version 具体该填哪个值，别照抄别人的示例，到 /official-api/providers/azure 看当时可用的版本说明，选一个和你模型匹配的。
curl -X POST "https://<资源名>.openai.azure.com/openai/deployments/<部署名>/chat/completions?api-version=<版本>" -H "api-key: <你的Key>" -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"你好"}],"max_tokens":32}'跑通第一发请求并验证
别一上来就测流式、工具调用、结构化输出，先发一条最朴素的非流式单轮请求，几十个 token 就够。能返回内容，说明端点、部署名、鉴权、api-version 这一整条链路都对了，再往上叠功能。
- 最小验证：非流式、单轮、输出限制在几十 token，先确认能返回文本
- 分层判断：能不能到域名、鉴权过不过、模型有没有按预期回，三层分开看
- 看错误码：401 是鉴权或密钥归属问题，404 是路径或部署名问题，429 是配额或限速问题
- 固化配置：把成功的请求参数写成一份配置，切部署或换区时只改这一处
延迟和稳定性的基线可以先到 /tools/speed-test 量一遍，再用业务侧真实 prompt 复测。区域远、跨网转发都会让首字变慢，这个差异不测是看不出来的。量完的记录留着，后面换区或换部署时能直接对比。
报错排查顺序与不适用情形
排错讲顺序，别东一榔头西一棒子。前一层的没确认过，就不要去动后面的，否则你改了五处也不知道是哪处起作用。
- 先看端点域名确认域名拼的是自己的资源名，而不是官方 base 地址，域名不对后面全白搭。
- 再核对部署名拿代码里的 model 字段和部署名逐字符对一遍，大小写和连字符都要一致。
- 再查 api-version对照站内说明确认版本值可用，别用过期示例里的旧版本。
- 再验密钥归属确认 Key 来自当前这个资源，不是另一个资源里复制的。
- 最后看区域配额前面都对了还报 429，再去查该区域该模型的额度是不是被打满了。
有些场景本来就不适合走这条路。比如要求数据不出境、或者对单次调用延迟极其敏感，先回到 /official-api/providers/azure 看清前提再决定要不要换方案，别硬扛。另外多环境建议拆成不同资源或至少不同部署名，开发测试的流量污染线上额度和监控，排查起来很费劲。
下一步把各家的接入方式、配额和计费口径放在一起对照，比单看一家更容易做决定；站内资料库会持续更新当时的数字和可用区域。→常见问题
部署名和模型名到底填哪个？
代码里 model 字段填的是你在 Azure 上给自己这次部署起的名字，不是模型厂商的型号名。填错会直接返回找不到部署。反过来说，同一个模型建两个不同部署名，代码里只改这一处就能做灰度或分流。
为什么地址明明对，还是 401？
绝大多数是把 Key 和端点配错了对，或者照抄了 OpenAI 官方的 Bearer 写法。Azure 这边用 api-key 请求头，并且 Key 必须来自端点对应的那个资源。先把 Key 重新从该资源里复制一遍，再检查请求头名字。
调不通时先怀疑网络还是参数？
先用一条最小非流式请求试，看返回的是连接错误还是带状态码的错误。连接层报错多半是域名、DNS 或代理问题；能拿到 401、404、429 这类状态码，说明网络是通的，问题在鉴权和参数上，按排查顺序逐层往下走。
