4.3 Azure OpenAI Chat

吴祖贤
52 阅读12分钟

Azure OpenAI Chat

Spring AI 参考文档 - Azure OpenAI Chat 模型集成指南

概述

Azure 的 OpenAI 服务基于 ChatGPT 提供强大功能，超越了传统 OpenAI 的能力，提供具有增强功能的 AI 驱动文本生成。Azure 提供了额外的 AI 安全性和负责任 AI 功能，如他们在最近更新中所述。

Azure 为 Java 开发者提供了通过将 AI 与一系列 Azure 服务集成的机会来利用 AI 全部潜力的机会，这些服务包括 Azure 上的向量存储等 AI 相关资源。

先决条件

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

Azure API 密钥和端点

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

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

  1. spring.ai.azure.openai.api-key：将其设置为从 Azure 获得的 API Key 的值
  2. 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=<您的Azure 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 ID

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

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

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

部署名称

要使用 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 及其自动配置功能的默认配置一致。 如果您使用不同的部署名称，请确保相应地更新配置属性：

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

访问 OpenAI 模型

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

添加存储库和 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

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

Gradle

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

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

Azure OpenAI 聊天客户端是使用 Azure SDK 提供的 OpenAIClientBuilder 创建的。Spring AI 允许通过提供 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.azure.openai.api-key来自 Azure AI OpenAI 的 密钥和端点 部分的密钥，位于 资源管理 下-
spring.ai.azure.openai.endpoint来自 Azure AI OpenAI 的 密钥和端点 部分的端点，位于 资源管理 下-
spring.ai.azure.openai.openai-api-key（非 Azure）OpenAI API 密钥。用于向 OpenAI 服务而不是 Azure OpenAI 进行身份验证。这会自动将端点设置为 api.openai.com/v1。使用 api-key 或 openai-api-key 属性之一。使用此配置时，spring.ai.azure.openai.chat.options.deployment-name 被视为 OpenAI 模型 名称。-
spring.ai.azure.openai.custom-headers要包含在 API 请求中的自定义头部映射。映射中的每个条目代表一个头部，其中键是头部名称，值是头部值。空映射

注意：聊天自动配置的启用和禁用现在通过前缀为 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.model.chat启用 Azure OpenAI 聊天模型azure-openai
spring.ai.azure.openai.chat.options.deployment-name与 Azure 一起使用时，这指的是您模型的"部署名称"，您可以在 oai.azure.com/portal 找到。重要的是要注意，在 Azure OpenAI 部署中，"部署名称"与模型本身是不同的。围绕这些术语的混淆源于使 Azure OpenAI 客户端库与原始 OpenAI 端点兼容的意图。Azure OpenAI 和 Sam Altman 的 OpenAI 提供的部署结构差异显著。部署模型名称作为此完成请求的一部分提供。gpt-4o
spring.ai.azure.openai.chat.options.maxTokens在聊天完成中生成的最大令牌数。输入令牌和生成令牌的总长度受模型的上下文长度限制。用于非推理模型（例如，gpt-4o, gpt-3.5-turbo）。不能与 maxCompletionTokens 一起使用。-
spring.ai.azure.openai.chat.options.maxCompletionTokens可以为完成生成的令牌数的上限，包括可见输出令牌和推理令牌。推理模型（例如，o1, o3, o4-mini 系列）必需。不能与 maxTokens 一起使用。-
spring.ai.azure.openai.chat.options.temperature使用的采样温度，控制生成完成的明显创造性。较高的值将使输出更随机，而较低的值将使结果更聚焦和确定性。不建议同时修改温度和 top_p 的相同完成请求，因为这两个设置的相互作用难以预测。0.7
spring.ai.azure.openai.chat.options.topP称为核采样的温度采样的替代方法。此值使模型考虑具有所提供概率质量的令牌结果。-
spring.ai.azure.openai.chat.options.logitBiasGPT 令牌 ID 与偏差分数之间的映射，影响特定令牌出现在完成响应中的概率。令牌 ID 通过外部标记器工具计算，而偏差分数位于 -100 到 100 范围内，最小值和最大值分别对应令牌的完全禁止或独占选择。给定偏差分数的确切行为因模型而异。-
spring.ai.azure.openai.chat.options.user操作的调用者或最终用户的标识符。可用于跟踪或速率限制目的。-
spring.ai.azure.openai.chat.options.stream-usage（仅用于流式传输）设置为添加包含整个请求的令牌使用统计的额外块。此块的 choices 字段是空数组，所有其他块也将包含 usage 字段，但值为 null。false
spring.ai.azure.openai.chat.options.n应为聊天完成响应生成的聊天完成选择数量。-
spring.ai.azure.openai.chat.options.stop将结束完成生成的文本序列集合。-
spring.ai.azure.openai.chat.options.presencePenalty基于生成令牌在生成文本中的现有存在情况影响其出现概率的值。正值将使令牌在已存在时更不可能出现，并增加模型输出新主题的可能性。-
spring.ai.azure.openai.chat.options.responseFormat.type与 GPT-4o、GPT-4o mini、GPT-4 Turbo 和所有比 gpt-3.5-turbo-1106 更新的 GPT-3.5 Turbo 模型兼容。JSON_OBJECT 类型启用 JSON 模式，保证模型生成的消息是有效的 JSON。JSON_SCHEMA 类型启用结构化输出，保证模型将匹配您提供的 JSON 模式。JSON_SCHEMA 类型还需要设置 responseFormat.schema 属性。-
spring.ai.azure.openai.chat.options.responseFormat.schema响应格式 JSON 模式。仅适用于 responseFormat.type=JSON_SCHEMA-
spring.ai.azure.openai.chat.options.frequencyPenalty基于生成令牌在生成文本中的累积频率影响其出现概率的值。正值将使令牌在其频率增加时更不可能出现，并减少模型逐字重复相同语句的可能性。-
spring.ai.azure.openai.chat.options.proxy-tool-calls如果为 true，Spring AI 将不会内部处理函数调用，而是将它们代理给客户端。然后是客户端的责任来处理函数调用，将它们分派给适当的函数，并返回结果。如果为 false（默认值），Spring AI 将内部处理函数调用。仅适用于支持函数调用的聊天模型false

提示：所有以 spring.ai.azure.openai.chat.options 为前缀的属性都可以通过向 Prompt 调用添加请求特定的运行时选项在运行时覆盖。

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

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

模型系列必需参数注意事项
推理模型
（o1, o3, o4-mini 系列）		maxCompletionTokens这些模型只接受 maxCompletionTokens。使用 maxTokens 将导致 API 错误。
非推理模型
（gpt-4o, gpt-3.5-turbo 等）		maxTokens传统模型使用 maxTokens 进行输出限制。使用 maxCompletionTokens 可能导致 API 错误。

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

示例：为推理模型使用 maxCompletionTokens

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

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

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

运行时选项

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

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

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

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

提示：除了模型特定的 AzureOpenAiChatOptions.java 外，您还可以使用通过 ChatOptions#builder() 创建的可移植 ChatOptions 实例。

函数调用

您可以使用 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 模型将用户文本与图像融合。

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，如下例所示：

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）依赖项中。

在 src/main/resources 目录下添加 application.properties 文件，以启用和配置 OpenAI 聊天模型：

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 类示例。

@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 文件中：

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

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

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

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

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

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

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

相关资源

avatar
文章
阅读
粉丝