遇到 Cursor 接不上 Azure OpenAI 的时候,我会先请对方把 Azure 控制台里的资源名、部署名和密钥发过来核对。这一步看着简单,但很多人一上来就改 Base URL,改完还是 404,浪费不少时间。
要在 Cursor 中正确接入 Azure OpenAI,关键在于识别它和原生 OpenAI 接口的三个差异。Azure 的 API 端点不是 api.openai.com,而是资源专属的 https://.openai.azure.com;模型参数不再使用 gpt-4 这类名称,而是使用你在 Azure 控制台创建的部署名;同时必须携带 api-version 查询参数,否则请求直接失败。配置前先确认你手里是否握有“资源名、部署名、API 密钥”三件套,而不是常规的模型名和 Base URL。
如果你发现手里没有这三样,先去 Azure 控制台找到资源、创建部署、生成密钥,再来往下配。而且这三样必须对应同一个资源组,不能拿 A 资源的密钥配 B 资源的端点。
容易误判的路径与模型名
很多用户把 Azure 和 OpenAI 的差异只当成域名不同,其实路径格式也有隐藏规则。Cursor 在发出请求时会默认拼接 OpenAI 的路径,如果你只改了 host,没有改模型名和 api-version,请求就会落在 Azure 根路径上。下面这段是常见的判断参考:
最常见的坑是 Cursor 会把自己内置的模型名称映射到用户配置上,甚至强行覆盖 openai.Config 中的默认参数。比如你设置了 base_url 为 Azure 端点,但模型名没有改成部署名,请求就会落到 Azure 根路径,返回 404。还有用户会在 api-version 后面多写 /v1/,导致路径重复。事实上,Azure 的请求路径中不需要 /v1/,因为 /openai/deployments 本身就是版本标识。配置初期不要启用任何自定义代理或负载均衡,保持直连,成功率更高。
这里的关键是,模型名必须与 Azure 中的部署名一致,且 api-version 是必填查询参数。你可以先用一个简单请求测试,确认路径格式,再回到 Cursor 里改。
在 Cursor 中实际要改的参数
确认了三件套和路径规则之后,回到 Cursor 的设置界面,需要改的是基础 URL 和模型名称。以我处理过的配置为例,通常按下面这个方式填:
在 Cursor 的设置界面,需要把基础 URL 改为 https://.openai.azure.com/openai/deployments/?api-version=,并将模型名称改成与部署名完全一致。特别留意 Cursor 可能默认在模型 ID 后追加后缀,或自动拼接 /chat/completions,这时要手动核对请求路径。最稳妥的做法是打开 Cursor 的日志或挂上本地代理,拦截实际发出的请求,确认 URL 格式是否为 /openai/deployments/{deployment}/chat/completions?api-version={版本},发现多出的 /v1 之类立刻修正。
具体来说,基础 URL 中的第一个占位符是你的资源名,问号后要带具体的 api-version 值,比如 2023-05-15 或 2024-10-21,取决于你的 Azure 区域支持哪些版本。模型名称则填入部署名,而不是底层模型型号,两者可能看起来很像,但必须严格区分。
用独立请求验证接口
填好配置之后,不要急着在 Cursor 里发消息,先在外部把接口打通。我一般会用 cURL 或 Postman 做一次独立验证,这样可以排除 Cursor 本身的前置逻辑。
配置完成后,先用 cURL 或 Postman 做一次独立的接口验证,能极大缩小排查范围。以 cURL 为例,向 https://.openai.azure.com/openai/deployments//chat/completions?api-version=2023-05-15 发送 POST 请求,并在请求头中携带 api-key。如果返回 200,说明端点、密钥和部署名都正确;如果返回 404 或 400,优先检查部署名和 API 版本;返回 401,则密钥或资源名有误。这一步通过后再回到 Cursor 里测试,避免在配置界面和 Azure 控制台之间来回折腾。
这里的占位符只是示意,实际要替换成你的资源名和部署名。另外,请求头用 api-key 而不是 Authorization: Bearer,除非你走的是 Azure AD 认证。
风险边界和回滚方式
在配置时还要留意几个边界,尤其是密钥和认证方式。下面这段是容易忽略的地方:
配置时容易忽略的边界条件是:API 密钥绝不能暴露在公开仓库或截图里,Azure 的密钥分 KEY1 和 KEY2,两者功能相同,任选一个即可。如果你用的是企业 AAD 认证,认证方式不再是 api-key,而是需要一段临时有效的 Bearer Token,并且要同步调整 Cursor 的 Authorization 头。另外,Azure 的部署名一般由小写字母和数字组成,严格按控制台显示填写,不要顺手加空格、斜杠或大写字母,否则请求会因资源定位错误而失败。
如果配置失败想回滚,把 Cursor 里的 Base URL 恢复成官方地址,模型名恢复成原来的 gpt-4 或 gpt-3.5-turbo,再保存即可。建议在动手前把原本的配置截图或记下来,尤其是自定义代理环境。