Spring AI官网文档中如何配置Azure OpenAI客户端？

Question

在基于 Spring AI 集成 Azure OpenAI 时，一个常见问题是：**如何正确配置 Azure OpenAI 客户端以避免 `401 Unauthorized` 或 `404 Resource Not Found` 错误？** 开发者常误将 Azure 的 `endpoint`（如 `https://.openai.azure.com/`）与 OpenAI 官方 API 地址混淆，或错误使用 `api-key` 而未指定 `api-version`（必需参数，如 `2024-02-01`）；更常见的是混淆了模型部署名（Deployment Name）与基础模型名（如 `gpt-4o`），导致请求路径 `/openai/deployments/{deployment-name}/chat/completions` 失败。此外，Spring AI 1.0+ 要求显式声明 `spring.ai.azure.openai.deployment-name` 和 `spring.ai.azure.openai.api-version`，若仅配置 `api-key` 和 `endpoint` 而遗漏这些属性，客户端初始化即失败。官网文档虽列出了配置项，但未强调 Azure 独有的“部署级”抽象与版本强约束，易致初学者配置后调用始终返回空响应或认证异常。

Answer 1

一、认知层：理解 Azure OpenAI 与 OpenAI 官方 API 的本质差异

Azure OpenAI 并非 OpenAI 官方 API 的简单代理或镜像，而是微软在 Azure 云平台中托管的合规、隔离、可治理的企业级 AI 服务。其核心抽象是“部署（Deployment）”——即你在 Azure 门户中为某个基础模型（如 gpt-4o、gpt-35-turbo）手动创建的、带命名和版本绑定的服务实例。这意味着：你调用的不是模型名，而是你亲手部署并命名的 endpoint 实例。官方 OpenAI 使用 https://api.openai.com/v1/chat/completions，而 Azure 必须使用形如 https://{your-resource}.openai.azure.com/openai/deployments/{your-deployment-name}/chat/completions?api-version=2024-02-01 的路径。混淆二者是 404 和 401 的首要根源。

二、配置层：Spring AI 1.0+ 的强制属性与语义约束

Spring AI 自 1.0 起采用“显式优先（explicit-by-default）”设计哲学，尤其对 Azure OpenAI 进行了深度适配。以下为不可省略的四项核心配置项（缺一不可）：

• spring.ai.azure.openai.endpoint：必须为完整 HTTPS URL，含资源名，如 https://my-ai-service.openai.azure.com/（末尾斜杠必需）
• spring.ai.azure.openai.api-key：从 Azure 门户 → “密钥和终结点”页获取的 Key 1 或 Key 2（非连接字符串）
• spring.ai.azure.openai.deployment-name：你在 Azure 中创建部署时填写的名称（如 gpt4o-prod），区分大小写且不可包含空格或特殊字符
• spring.ai.azure.openai.api-version：严格匹配 Azure REST API 版本，当前推荐 2024-02-01（官方版本矩阵需定期核查）

三、验证层：分阶段诊断工具链与典型错误映射表

以下表格归纳高频错误码、触发场景与定位方法：

HTTP 状态码	典型日志片段	根本原因	验证命令（curl）
401 Unauthorized	Failed to authenticate request. Invalid API key.	API Key 过期 / 复制含空格 / 使用了“连接字符串”而非 Key	curl -H "api-key: $KEY" "$ENDPOINT/openai/deployments/$DEP/chat/completions?api-version=2024-02-01" -d '{"messages":[{"role":"user","content":"test"}]}' -H "Content-Type: application/json"
404 Not Found	The requested resource does not exist.	deployment-name 错误 / endpoint 域名拼写错误 / api-version 不匹配	curl -I -H "api-key: $KEY" "$ENDPOINT/openai/deployments/$DEP/chat/completions?api-version=2024-02-01"（仅检查头）

四、架构层：Spring Boot 配置驱动的客户端生命周期图

下图展示 Spring AI Azure 客户端在 ApplicationContext 中的初始化依赖关系与失败传播路径：

graph TD
    A[application.yml] --> B[spring.ai.azure.openai.* properties]
    B --> C[AzureOpenAiChatClientBuilder]
    C --> D{Required Properties Present?}
    D -- Yes --> E[Build AzureOpenAiChatClient]
    D -- No --> F[BeanCreationException: Missing required property]
    E --> G[Auto-configured ChatClient Bean]
    G --> H[Controller / Service Injection]
    H --> I[HTTP Request Execution]
    I --> J{Response Status}
    J -- 2xx --> K[Success]
    J -- 401/404 --> L[Traceable Exception with Property Context]

五、实践层：生产就绪的最小可行配置示例

以下为经过 Azure 中国东部2区实测的 application.yml 片段（敏感字段已脱敏）：

spring:
  ai:
    azure:
      openai:
        endpoint: https://prod-ai-chinaeast2.openai.azure.com/
        api-key: 8Xz...QmF  # ← 注意：此处为真实 Key，非占位符
        deployment-name: gpt4o-standard-v1
        api-version: 2024-02-01
        # ⚠️ 关键补充：启用请求日志（仅开发/测试环境）
        client-options:
          connect-timeout: 10s
          read-timeout: 60s
logging:
  level:
    org.springframework.ai.azure.openai: DEBUG  # 查看实际构造的 URL 与 Header

六、演进层：从 Spring AI 0.x 到 1.x 的配置迁移陷阱

旧版（0.8.x）允许通过 spring.ai.openai.api-key + spring.ai.openai.base-url “降级兼容” Azure，但该方式在 1.0+ 中已被完全移除。Spring AI 团队明确声明：Azure OpenAI 必须使用专属命名空间 spring.ai.azure.openai.*，否则将静默忽略配置并抛出 No qualifying bean of type 'ChatClient'。此变更并非 bug，而是为强化云厂商抽象边界所作的架构收敛。

七、治理层：多环境部署的配置管理最佳实践

建议采用 Spring Profiles + Azure Key Vault 集成实现安全配置分离：

• 开发环境：使用 application-dev.yml + 本地 vault 模拟器
• 预发/生产：通过 spring.cloud.azure.keyvault.secret.property-sources[0].credential.client-id 绑定托管标识（Managed Identity）
• 禁止在 Git 中硬编码 api-key；若必须调试，使用 spring.config.import=optional:azure-key-vault:

八、可观测层：如何捕获并解析失败请求的原始上下文

启用 logging.level.org.springframework.ai.azure.openai=DEBUG 后，日志将输出如下关键信息：

[DEBUG] AzureOpenAiChatClient - Building request to: https://prod-ai-chinaeast2.openai.azure.com/openai/deployments/gpt4o-standard-v1/chat/completions?api-version=2024-02-01
[DEBUG] AzureOpenAiChatClient - Headers: {api-key=[REDACTED], Content-Type=[application/json]}

该日志可直接用于 curl 复现，避免“Java 层配置正确但网络层失败”的归因偏差。