Spring AI接入Azure OpenAI教程：endpoint、api-key、部署名配置详解

本节目标：学会用 Spring AI 接入 Azure OpenAI。理解 endpoint、api-key、deployment-name 三要素的含义，掌握 2.0 推荐接入方式，并知道旧版 azure-openai starter 的用法。

16.1 Azure OpenAI 与 OpenAI 的区别

Azure OpenAI 是微软云上的 OpenAI 服务。模型本身和 OpenAI 同源，但部署方式完全不同。

OpenAI 直接给你一个模型名，填 Key 就能用。Azure 则要先创建一个”部署”（Deployment），拿到一个专属的 endpoint URL。请求打到你自己的部署上，而不是 OpenAI 的公共接口。

对企业来说，Azure 的优势在于数据合规、网络隔离和微软的企业支持。很多公司选它，是因为模型能部署在自家云环境里。

16.2 三要素：endpoint、api-key、deployment-name

接入 Azure OpenAI 需要三个信息，缺一不可。

endpoint 是部署的访问地址，形如 https://your-resource.openai.azure.com。在 Azure 门户的 Azure OpenAI 服务里，打开”Keys and Endpoint”页面就能看到。

api-key 是访问密钥，也在同一个页面。分 Key 1 和 Key 2，两个都有效，可以轮换使用。

deployment-name 是部署名称。Azure 里模型必须通过部署来调用，每个部署有独立的名称。部署名和模型名是两回事：一个叫 MyAiDeployment 的部署，背后可以是 GPT-4o，也可以是别的模型。

16.3 准备工作：创建部署

拿到三个信息之前，先在 Azure 上建好资源。步骤如下：

在 Azure 门户创建 Azure OpenAI 资源，记下资源名称和区域。
打开 Azure AI 门户，进入你的资源。
在 Deployments 页面点击创建部署，Deployment Name 填 gpt-4o，Model 选 gpt-4o。
回到 Azure 门户，打开”Keys and Endpoint”，复制 endpoint 和任意一个 Key。

按这套默认设置走，后续配置可以直接抄。部署名不一样的话，记得同步改配置里的模型属性。

Note

部署名称在 Azure AI 门户创建。创建部署时，Deployment Name 和 Model Name 可以都填 gpt-4o，这是最省事的默认配置。

16.4 2.0 的推荐接入方式

Spring AI 从 2.0.0-M5 起，官方文档建议直接用 OpenAI 客户端访问 Azure 上部署的模型。原因很直接：Azure 暴露的是 OpenAI 兼容接口，没必要维护两套客户端。

做法分两步。依赖照旧用 OpenAI starter：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

配置里把 base-url 指向你的 Azure 端点，api-key 换成 Azure 密钥，model 填部署名：

spring.ai.openai.api-key=${AZURE_OPENAI_API_KEY}
spring.ai.openai.base-url=https://your-resource.openai.azure.com/openai/v1
spring.ai.openai.chat.model=gpt-4o
spring.ai.openai.chat.temperature=0.7

注意 model 属性填的是 Azure 里的部署名，不是 OpenAI 的模型名。如果你的部署叫 my-gpt4-deploy，这里就填 my-gpt4-deploy。

调用代码和其他厂商完全一样，用 ChatClient：

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/ai/generate")
    public Map<String, String> generate(@RequestParam(defaultValue = "讲个笑话") String message) {
        return Map.of("generation", chatClient.prompt(message).call().content());
    }
}

Tip

密钥不要直接写进配置文件。用环境变量加 SpEL 引用，例如 spring.ai.openai.api-key=${AZURE_OPENAI_API_KEY}。这样密钥留在部署环境里，不进代码仓库。

16.5 旧版 azure-openai starter

1.x 时代有专门的 spring-ai-starter-model-azure-openai，配置前缀是 spring.ai.azure.openai。如果你在维护老项目，会看到这样的写法：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>

spring.ai.azure.openai.api-key=YOUR_AZURE_API_KEY
spring.ai.azure.openai.endpoint=https://your-resource.openai.azure.com
spring.ai.azure.openai.chat.options.deployment-name=gpt-4o
spring.ai.azure.openai.chat.options.temperature=0.7

这套属性有三处容易踩坑：

连接属性用 api-key 和 endpoint，模型属性用 chat.options.deployment-name。
老版本里 chat.options.model 已改名为 chat.options.deployment-name，用旧的会失效。
想直连 OpenAI（不走 Azure），要设置 openai-api-key 而不是 api-key。设置后 endpoint 自动指向 api.openai.com/v1，deployment-name 被当作 OpenAI 模型名。

新建项目建议直接走 2.0 的 OpenAI 方式。老项目迁移也很简单：换依赖、把 spring.ai.azure.openai.* 属性映射成 spring.ai.openai.*，注意 endpoint 要补上 /openai/v1 路径。

16.6 三种认证方式

旧版 starter 支持三种认证，理解它们有助于排查问题。

Azure API Key：设置 api-key 和 endpoint，走 Azure 部署。

OpenAI Key：设置 openai-api-key，绕过 Azure，直连 OpenAI 官方接口。

Microsoft Entra ID：只设置 endpoint，不设任何 Key。客户端会用 Entra ID（原 Azure Active Directory）自动获取 Token 凭证。这适合企业内部的免密认证，不用再手动创建 TokenCredential Bean。

三种方式选哪种，看你的安全和合规要求。个人项目用 Azure API Key 最省事；企业里如果已经在用 Entra ID 做统一身份，走免密认证少维护一套密钥。

16.7 多模型共存

一个应用里同时接 Azure 和 OpenAI 官方，用 2.0 的多模型开关可以共存。spring.ai.model.chat 控制聊天模型启用哪个，默认值是 openai。

# 默认只启用 openai 聊天模型
spring.ai.model.chat=openai

想彻底关掉自动装配，设成 none。这个属性在嵌入、图像、音频、审核模型上同样存在，前缀换成 spring.ai.model.embedding、spring.ai.model.image 等。多模型同时存在时，注入处要加 @Qualifier 区分具体的模型 Bean。

16.8 多模态

Azure 上的 gpt-4o 支持图片输入。用法和 OpenAI 完全一致，把图片作为 Media 挂到用户消息上：

String response = ChatClient.create(chatModel).prompt()
    .user(u -> u.text("这张图里有什么？")
        .media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("multimodal.test.png")))
    .call()
    .content();

也可以传图片 URL。多张图片同时传也没问题。

16.9 运行时覆盖参数

旧版 starter 支持按请求覆盖默认选项：

ChatResponse response = chatModel.call(
    new Prompt("列举 5 个常用的 Spring 注解",
        AzureOpenAiChatOptions.builder()
            .deploymentName("gpt-4o")
            .temperature(0.4)
            .build()));

2.0 的 OpenAI 方式则用 OpenAiChatOptions.builder().model(...)，语义相同。记住一条原则：默认参数写在 properties，临时调整放在请求里。

工具调用同样支持。定义一个 @Tool 方法，通过 chatClient.prompt(...).tools(new WeatherService()) 传入，模型会在需要时自动调用。ToolCallingAdvisor 自动注册，不需要额外配置。

16.10 流式响应

长回答建议用流式。改造上面的 Controller：

@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(@RequestParam(defaultValue = "讲个笑话") String message) {
    return chatClient.prompt(message).stream().chatResponse();
}

前端拿到 Flux 后逐块渲染，体验和 ChatGPT 一样。2.0 里 ChatClient 的流式是一等公民，同步和异步的调用结构完全对称。

16.11 自定义 HTTP 客户端

旧版 azure-openai 模块通过 AzureOpenAIClientBuilderCustomizer 定制底层客户端。比如把响应超时从默认值改成 5 分钟，应对长回答：

@Configuration
public class AzureOpenAiConfig {

    @Bean
    public AzureOpenAIClientBuilderCustomizer responseTimeoutCustomizer() {
        return openAiClientBuilder -> {
            HttpClientOptions clientOptions = new HttpClientOptions()
                    .setResponseTimeout(Duration.ofMinutes(5));
            openAiClientBuilder.httpClient(HttpClient.createDefault(clientOptions));
        };
    }
}

2.0 的 OpenAI 方式对应的是 OpenAiHttpClientBuilderCustomizer，接口名字不同，思路一样：注册一个自定义 Bean，拦截 SDK 的客户端构建过程。

16.12 重试机制

网络请求总会失败，Spring AI 内置了重试策略，用 spring.ai.retry 前缀配置：

spring.ai.retry.max-attempts=10
spring.ai.retry.backoff.initial-interval=2s
spring.ai.retry.backoff.multiplier=5
spring.ai.retry.backoff.max-interval=3m

默认最多重试 10 次，指数退避。4xx 客户端错误默认不重试，5xx 和网络错误才重试。生产环境建议把 max-attempts 调小一点，避免限流时反复打接口。

16.13 常见问题

连接超时或 404。 多半是 endpoint 写错了。Azure 门户里复制的是 https://your-resource.openai.azure.com，走 2.0 OpenAI 方式要在后面补 /openai/v1。

401 未授权。 api-key 填错了，或者 Key 已轮换。去 Azure 门户核对。

404 模型不存在。 model 属性填的是部署名，不是模型名。回到 Azure AI 门户看部署列表，复制准确的 Deployment Name。

直连 OpenAI 报错。 确认用的是 openai-api-key 而不是 api-key，两个属性指向不同的服务。

16.14 小结

Azure OpenAI 的接入核心就三个词：endpoint、api-key、deployment-name。2.0 之后官方推荐用 OpenAI starter 指向 Azure 端点，配置更少、代码更统一；老项目里的 spring.ai.azure.openai.* 属性仍有效，但新项目别再用了。