14_Spring AI 干货笔记之 Azure OpenAI 对话模型

一、Azure OpenAI 对话模型

Azure 的 OpenAI 服务（基于 ChatGPT）超越了传统的 OpenAI 能力，提供了具备增强功能的 AI 驱动文本生成。正如他们最近的更新中强调的那样，Azure 提供了额外的 AI 安全和负责任 AI 功能。

Azure 为 Java 开发者提供了通过与一系列 Azure 服务（包括 AI 相关资源，例如 Azure 上的向量存储）集成来充分利用 AI 潜力的机会。

二、先决条件

Azure OpenAI 客户端提供三种连接选项：使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。

2.1 Azure API 密钥和端点

要使用 API 密钥访问模型，请从 Azure 门户的 Azure OpenAI 服务部分获取您的 Azure OpenAI 端点和 api-key。

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

spring.ai.azure.openai.api-key：将其设置为从 Azure 获取的 API 密钥的值。
spring.ai.azure.openai.endpoint：将其设置为在 Azure 中配置模型时获得的端点 URL。

您可以在 application.properties 或 application.yml 文件中设置这些配置属性：

yaml 复制代码

spring.ai.azure.openai.api-key=<your-azure-api-key>
spring.ai.azure.openai.endpoint=<your-azure-endpoint-url>

为了在处理敏感信息（如 API 密钥）时增强安全性，您可以使用 Spring 表达式语言（SpEL）来引用自定义环境变量：

yaml 复制代码

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

bash 复制代码

# 在您的环境或 .env 文件中
export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-openai-endpoint-url>

2.2 OpenAI 密钥

要使用 OpenAI 服务（非 Azure）进行身份验证，请提供 OpenAI API 密钥。这将自动将端点设置为 api.openai.com/v1。

使用此方法时，请将 spring.ai.azure.openai.chat.options.deployment-name 属性设置为要使用的 OpenAI 模型的名称。

在您的应用程序配置中：

yaml 复制代码

spring.ai.azure.openai.openai-api-key=<your-azure-openai-key>
spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>

使用带有 SpEL 的环境变量：

yaml 复制代码

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

bash 复制代码

# 在您的环境或 .env 文件中
export AZURE_OPENAI_API_KEY=<your-openai-key>
export AZURE_OPENAI_MODEL_NAME=<openai-model-name>

2.3 Microsoft Entra ID

要使用 Microsoft Entra ID（原 Azure Active Directory）进行无密钥身份验证，请仅设置 spring.ai.azure.openai.endpoint 配置属性，而不设置上述提到的 api-key 属性。

当仅找到端点属性时，您的应用程序将评估几种不同的检索凭据选项，并将使用令牌凭据创建一个 OpenAIClient 实例。

不再需要创建 TokenCredential bean；它会自动为您配置。

2.4 部署名称

要使用 Azure AI 应用程序，您需要通过 Azure AI 门户创建一个 Azure AI 部署。在 Azure 中，每个客户端都必须指定一个部署名称来连接到 Azure OpenAI 服务。需要注意的是，部署名称与您选择部署的模型不同。例如，一个名为 "MyAiDeployment" 的部署可以配置为使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。

要开始使用，请按照以下步骤创建具有默认设置的部署：

部署名称：gpt-4o

模型名称：gpt-4o

此 Azure 配置与 Spring Boot Azure AI Starter 及其自动配置功能的默认配置一致。如果使用不同的部署名称，请确保相应地更新配置属性：

yaml 复制代码

spring.ai.azure.openai.chat.options.deployment-name=<my 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 而不是 Azure OpenAI（通过设置属性 spring.ai.azure.openai.openai-api-key=），那么 spring.ai.azure.openai.chat.options.deployment-name 将被视为 OpenAI 模型名称。

访问 OpenAI 模型

您可以将客户端配置为直接使用 OpenAI，而不是 Azure OpenAI 部署的模型。为此，您需要设置 spring.ai.azure.openai.openai-api-key=，而不是 spring.ai.azure.openai.api-key=。

2.5 添加仓库和 BOM

Spring AI 构件发布在 Maven Central 和 Spring Snapshot 仓库中。请参考 "项目仓库" 部分，将这些仓库添加到您的构建系统。

为了帮助进行依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致版本的 Spring AI。请参考 "依赖管理" 部分，将 Spring AI BOM 添加到您的构建系统。

三、自动配置

Spring AI 的自动配置和启动器模块的工件名称发生了重大变化。请参阅升级说明获取更多信息。

Spring AI 为 Azure OpenAI 聊天客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

Maven

xml 复制代码

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

Gradle

xml 复制代码

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai'
}

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

Azure OpenAI 聊天客户端是使用 Azure SDK 提供的 OpenAIClientBuilder 创建的。Spring AI 允许通过提供 AzureOpenAIClientBuilderCustomizer bean 来自定义构建器。

例如，可以使用自定义器来更改默认的响应超时时间：

java 复制代码

@Configuration
public class AzureOpenAiConfig {

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

}

3.1 聊天属性

前缀 spring.ai.azure.openai 是用于配置连接到 Azure OpenAI 的属性前缀。

聊天自动配置的启用和禁用现在通过前缀为 spring.ai.model.chat 的顶层属性进行配置。

要启用，设置 spring.ai.model.chat=azure-openai（默认已启用）。

要禁用，设置 spring.ai.model.chat=none（或任何不匹配 azure-openai 的值）。

此更改是为了允许配置多个模型。

前缀 spring.ai.azure.openai.chat 是用于配置 Azure OpenAI 的 ChatModel 实现的属性前缀。

所有以 spring.ai.azure.openai.chat.options 为前缀的属性都可以通过在 Prompt

调用中添加特定于请求的运行时选项在运行时被覆盖。

3.2 令牌限制参数：模型特定用法

Azure OpenAI 对令牌限制参数有模型特定的要求：

参数 maxTokens 和 maxCompletionTokens 是互斥的。同时设置这两个参数将导致 Azure OpenAI 返回 API 错误。Spring AI Azure OpenAI 客户端将在您设置另一个参数时自动清除先前设置的参数，并显示警告信息。

示例：为推理模型使用 maxCompletionTokens

java 复制代码

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

示例：为非推理模型使用 maxTokens

java 复制代码

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

四、运行时选项

AzureOpenAiChatOptions 提供了模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可以通过 AzureOpenAiChatModel(api, options) 构造函数或 spring.ai.azure.openai.chat.options.* 属性来配置默认选项。

在运行时，您可以通过向 Prompt 调用添加新的、特定于请求的选项来覆盖默认选项。例如，要为特定请求覆盖默认模型和温度：

java 复制代码

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        AzureOpenAiChatOptions.builder()
            .deploymentName("gpt-4o")
            .temperature(0.4)
        .build()
    ));

除了模型特定的 AzureOpenAiChatOptions 之外，您还可以使用可移植的 ChatOptions 实例，该实例是通过 ChatOptions#builder() 创建的。

五、函数调用

您可以向 AzureOpenAiChatModel 注册自定义 Java 函数，并让模型智能地选择输出一个包含参数的 JSON 对象来调用一个或多个已注册的函数。这是一种将 LLM 功能与外部工具和 API 连接起来的强大技术。阅读更多关于工具调用的信息。

六、多模态

多模态是指模型同时理解和处理来自不同来源信息的能力，包括文本、图像、音频和其他数据格式。目前，Azure OpenAI 的 gpt-4o 模型提供多模态支持。

Azure OpenAI 可以在消息中包含 base64 编码的图像或图像 URL 列表。Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 AI 模型。此类型包含消息中媒体附件的数据和信息，使用 Spring 的 org.springframework.util.MimeType 和用于原始媒体数据的 java.lang.Object。

以下是一个从 OpenAiChatModelIT.java 中提取的代码示例，说明了如何使用 GPT_4_O 模型将用户文本与图像结合。

java 复制代码

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("Explain what do you see on this picture?").media(MimeTypeUtils.IMAGE_PNG, this.url))
        .call()
        .content();

您也可以传递多个图像。

它以 multimodal.test.png 图像作为输入：

以及文本消息 "Explain what do you see on this picture?"，并生成类似以下的响应：

这是一个带有简单设计的水果碗图片。碗由金属制成，带有弯曲的金属丝边缘，形成了一个开放结构，使得水果从各个角度都可见。碗内有两根黄色的香蕉，放在一个似乎是红苹果的上面。香蕉略微过熟，果皮上的棕色斑点表明了这一点。碗的顶部有一个金属环，可能用作提手。碗放置在一个平坦的表面上，背景为中性色，清晰地展示了碗内的水果。

您也可以传入一个类路径资源而不是 URL，如下例所示：

java 复制代码

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("Explain what do you see on this picture?")
    .media(MimeTypeUtils.IMAGE_PNG, this.resource))
    .call()
    .content();

七、示例控制器

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-azure-openai 添加到您的 pom（或 gradle）依赖项中。

添加一个 application.properties 文件，位于 src/main/resources 目录下，以启用和配置 OpenAi 聊天模型：

yaml 复制代码

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

将 api-key 和 endpoint 替换为您的 Azure OpenAI 凭据。

这将创建一个 AzureOpenAiChatModel 实现，您可以将其注入到您的类中。以下是一个简单的 @Controller 类示例，该类使用聊天模型进行文本生成。

java 复制代码

@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 this.chatModel.stream(prompt);
    }
}

八、手动配置

AzureOpenAiChatModel 实现了 ChatModel 和 StreamingChatModel，并使用 Azure OpenAI Java 客户端。

要启用它，请将 spring-ai-azure-openai 依赖项添加到您项目的 Maven pom.xml 文件中：

xml 复制代码

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

或添加到您的 Gradle build.gradle 构建文件中。

xml 复制代码

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

spring-ai-azure-openai 依赖项还提供了对 AzureOpenAiChatModel 的访问。有关 AzureOpenAiChatModel 的更多信息，请参阅 Azure OpenAI 聊天部分。

接下来，创建一个 AzureOpenAiChatModel 实例并使用它来生成文本响应：

java 复制代码

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 门户中显示的部署名称。