Spring AI Azure OpenAI 的使用

由 ChatGPT 提供能力支撑的 Azure OpenAI 服务，超越了传统原生 OpenAI 的基础能力，可提供功能更强大的 AI 文本生成能力。Azure 还额外提供了 AI 安全管控与负责任 AI 相关特性，详情可参考官方最新更新文档。

Azure 允许 Java 开发者将 AI 能力与各类 Azure 云服务无缝集成，充分释放人工智能的全部潜力，其中就包含 Azure 向量存储等 AI 相关资源。

前置条件

Azure OpenAI 客户端提供三种连接认证方式：使用 Azure API 密钥、使用原生 OpenAI API 密钥、使用 Microsoft Entra 身份认证。

Azure API 密钥与访问端点

若要通过 API 密钥访问模型，需在 Azure 门户的 Azure OpenAI 服务页面中获取专属访问端点和 API 密钥。

Spring AI 定义了两个核心配置属性：

• spring.ai.azure.openai.api-key：填写从 Azure 获取的 API 密钥值

• spring.ai.azure.openai.endpoint：填写在 Azure 中部署模型时获取的端点 URL

你可以在 application.properties 或 application.yml 配置文件中设置这些参数：

spring.ai.azure.openai.api-key=<你的Azure API密钥>
spring.ai.azure.openai.endpoint=<你的Azure端点URL>

为提升 API 密钥等敏感信息的安全性，可通过 Spring 表达式语言（SpEL）引用自定义环境变量：

# application.yml 配置
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}

# 环境变量或 .env 文件配置
export AZURE_OPENAI_API_KEY=<你的Azure OpenAI API密钥>
export AZURE_OPENAI_ENDPOINT=<你的Azure OpenAI端点URL>

原生 OpenAI 密钥

如需直接对接原生 OpenAI 服务（非 Azure 托管），只需提供 OpenAI 官方 API 密钥，客户端会自动将访问端点设置为 api.openai.com/v1。

使用该方式时，需要通过 spring.ai.azure.openai.chat.options.deployment-name 属性指定要调用的 OpenAI 模型名称。

应用配置示例：

spring.ai.azure.openai.openai-api-key=<你的OpenAI官方密钥>
spring.ai.azure.openai.chat.options.deployment-name=<OpenAI模型名称>

结合 SpEL 引用环境变量配置：

# application.yml 配置
spring:
  ai:
    azure:
      openai:
        openai-api-key: ${AZURE_OPENAI_API_KEY}
        chat:
          options:
            deployment-name: ${AZURE_OPENAI_MODEL_NAME}

# 环境变量或 .env 文件配置
export AZURE_OPENAI_API_KEY=<你的OpenAI官方密钥>
export AZURE_OPENAI_MODEL_NAME=<OpenAI模型名称>

Microsoft Entra 身份认证

基于 Microsoft Entra ID（原 Azure Active Directory）可实现无密钥认证，只需配置 spring.ai.azure.openai.endpoint 端点属性，无需配置上述 API 密钥。

仅配置端点时，应用会自动尝试多种凭证获取方式，并通过令牌凭证创建 OpenAIClient 客户端实例。

无需手动创建 TokenCredential Bean 对象，框架会自动完成配置。

部署名称

使用 Azure AI 应用前，必须在 Azure AI 门户中创建 Azure AI 部署实例。在 Azure 中，所有客户端都必须指定部署名称才能连接 Azure OpenAI 服务。

重点注意：部署名称 与 选择的模型名称 并非同一个概念。例如命名为 MyAiDeployment 的部署，可以绑定 GPT 3.5 Turbo 或 GPT 4.0 任意模型。

快速入门可使用默认配置创建部署：

• 部署名称：gpt-4o

• 模型名称：gpt-4o

该默认配置与 Spring Boot Azure AI 启动器的自动配置完全适配。若自定义部署名称，需同步修改配置：

spring.ai.azure.openai.chat.options.deployment-name=<自定义部署名称>

由于 Azure OpenAI 与原生 OpenAI 的部署架构存在差异，Azure OpenAI 客户端库提供了 deploymentOrModelName 属性。原生 OpenAI 只有模型名称，没有部署名称的概念。

原配置属性 spring.ai.azure.openai.chat.options.model 已重命名为 spring.ai.azure.openai.chat.options.deployment-name。

若配置 openai-api-key 直连原生 OpenAI 服务，deployment-name 属性会被当作 OpenAI 模型名称使用。

直连 OpenAI 模型

可配置客户端直接调用原生 OpenAI 模型，而非 Azure 托管模型。只需配置 openai-api-key 代替 azure 的 api-key 即可。

仓库与物料依赖（BOM）

Spring AI 制品发布在 Maven 中央仓库和 Spring 快照仓库，可参考制品仓库文档将仓库地址配置到项目构建工具中。

Spring AI 提供 BOM 物料清单，用于统一管控项目中所有 Spring AI 依赖版本，可参考依赖管理文档引入 Spring AI BOM。

自动配置

Spring AI 自动配置及启动器构件名称已发生重大变更，升级可参考官方升级说明文档。

Spring AI 为 Azure OpenAI 对话客户端提供 Spring Boot 自动配置，只需在 Maven 或 Gradle 中引入以下依赖：

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

建议同步引入 Spring AI BOM 统一版本管理。

Azure OpenAI 对话客户端基于 Azure SDK 提供的 OpenAIClientBuilder 创建，可通过自定义 AzureOpenAIClientBuilderCustomizer Bean 对构建器进行定制。

示例：自定义修改默认响应超时时间

@Configuration
public class AzureOpenAiConfig {

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

}

对话配置属性

前缀 spring.ai.azure.openai 用于配置 Azure OpenAI 基础连接信息。

对话模型启停配置统一使用 spring.ai.model.chat 前缀：

• 启用：spring.ai.model.chat=azure-openai（默认启用）

• 禁用：spring.ai.model.chat=none

该设计支持项目同时配置多个 AI 模型。

前缀 spring.ai.azure.openai.chat 用于配置 Azure OpenAI 对话模型实现类。

所有以 spring.ai.azure.openai.chat.options 为前缀的配置，均可在运行时通过请求级别的动态配置进行覆盖。

令牌限制参数：模型专属规则

Azure OpenAI 不同模型对令牌限制参数有强制要求：

maxTokens 与 maxCompletionTokens 互斥，不可同时配置，否则 Azure 接口会返回错误。Spring AI 客户端自动互斥清理配置并输出警告日志。

推理模型配置示例：

var options = AzureOpenAiChatOptions.builder()
    .deploymentName("o1-preview")
    .maxCompletionTokens(500)  // 推理模型专用
    .build();

非推理模型配置示例：

var options = AzureOpenAiChatOptions.builder()
    .deploymentName("gpt-4o")
    .maxTokens(500)  // 非推理模型专用
    .build();

运行时动态配置

AzureOpenAiChatOptions 类用于定义模型参数（模型名称、温度、频率惩罚等）。

项目启动时可通过构造方法或配置文件设置默认参数；运行时可在 Prompt 请求中单独指定配置，覆盖全局默认值。

运行时覆盖配置示例：

ChatResponse response = chatModel.call(
    new Prompt(
        "生成5位著名海盗的名字",
        AzureOpenAiChatOptions.builder()
            .deploymentName("gpt-4o")
            .temperature(0.4)
        .build()
    ));

除模型专属配置类外，也可使用通用 ChatOptions 构建器创建配置实例。

函数调用

可向 AzureOpenAiChatModel 注册自定义 Java 函数，模型会智能生成 JSON 格式参数，自动调用已注册的函数。该能力可将大模型与外部工具、业务接口无缝联动，更多详情可参考工具调用文档。

多模态能力

多模态指模型可同时理解文本、图片、音频等多种格式数据，目前 Azure OpenAI 的 gpt-4o 模型支持多模态交互。

Azure OpenAI 支持传入 Base64 编码图片或图片URL，Spring AI 通过 Media 类型封装消息中的媒体资源，结合 MimeType 与原始媒体数据实现多模态传输。

图文对话代码示例：

URL url = new URL("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png");
String response = ChatClient.create(chatModel).prompt()
        .options(AzureOpenAiChatOptions.builder().deploymentName("gpt-4o").build())
        .user(u -> u.text("描述这张图片内容").media(MimeTypeUtils.IMAGE_PNG, this.url))
        .call()
        .content();

支持同时传入多张图片。示例图片为水果碗静物图，模型可识别碗具、香蕉、苹果等细节并生成自然语言描述。

也可读取项目类路径资源文件替代网络URL：

Resource resource = new ClassPathResource("multimodality/multimodal.test.png");

String response = ChatClient.create(chatModel).prompt()
    .options(AzureOpenAiChatOptions.builder()
    .deploymentName("gpt-4o").build())
    .user(u -> u.text("描述这张图片内容")
    .media(MimeTypeUtils.IMAGE_PNG, this.resource))
    .call()
    .content();

示例控制器

新建 Spring Boot 项目，引入 spring-ai-starter-model-azure-openai 依赖，在 resources 下配置 application.properties：

spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.openai.chat.options.deployment-name=gpt-4o
spring.ai.azure.openai.chat.options.temperature=0.7

替换为自己的 Azure OpenAI 密钥和端点后，框架自动注入 AzureOpenAiChatModel，可直接在控制器中使用：

@RestController
public class ChatController {

    private final AzureOpenAiChatModel chatModel;

    @Autowired
    public ChatController(AzureOpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return chatModel.stream(prompt);
    }
}

手动编码配置

AzureOpenAiChatModel 实现了 ChatModel 和流式对话接口，底层依赖 Azure OpenAI Java 客户端。

手动引入依赖：

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

// Gradle 依赖
dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}

手动创建客户端与模型实例代码：

var openAIClientBuilder = new OpenAIClientBuilder()
  .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
  .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"));

var openAIChatOptions = AzureOpenAiChatOptions.builder()
  .deploymentName("gpt-5")
  .temperature(0.4)
  .maxCompletionTokens(200)
  .build();

var chatModel = AzureOpenAiChatModel.builder()
				.openAIClientBuilder(openAIClientBuilder)
				.defaultOptions(openAIChatOptions)
				.build();

ChatResponse response = chatModel.call(
  new Prompt("Generate the names of 5 famous pirates."));

// 流式响应调用
Flux<ChatResponse> streamingResponses = chatModel.stream(
  new Prompt("Generate the names of 5 famous pirates."));

注意：配置中的 gpt-4o 实际指代 Azure AI 门户中创建的部署名称。