跳到主要内容

Azure OpenAI 聊天

DeepSeek V3 中英对照 Azure OpenAI Azure OpenAI Chat

Azure 的 OpenAI 服务，由 ChatGPT 驱动，超越了传统的 OpenAI 功能，提供了增强功能的 AI 驱动的文本生成。Azure 还提供了额外的 AI 安全和负责任的 AI 功能，正如他们最近的更新中所强调的 这里。

Azure 为 Java 开发者提供了通过将 AI 与一系列 Azure 服务集成来充分发挥 AI 潜力的机会，其中包括与 AI 相关的资源，例如 Azure 上的 Vector Stores。

先决条件​

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

Azure 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。

你可以通过导出环境变量来设置这些配置属性：

export SPRING_AI_AZURE_OPENAI_API_KEY=<INSERT AZURE KEY HERE>
export SPRING_AI_AZURE_OPENAI_ENDPOINT=<INSERT ENDPOINT URL HERE>
shell

OpenAI 密钥​

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

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

export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY=<INSERT OPENAI KEY HERE>
shell

Microsoft Entra ID​

要使用 Microsoft Entra ID（前身为 Azure Active Directory）进行身份验证，请在配置中创建一个 TokenCredential bean。如果该 bean 可用，将使用令牌凭据创建一个 OpenAIClient 实例。bd === 部署名称

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

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

Deployment Name: `gpt-4o`
Model Name: `gpt-4o`

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

spring.ai.azure.openai.chat.options.deployment-name=<my deployment name>
none

Azure OpenAI 和 OpenAI 的不同部署结构导致了 Azure OpenAI 客户端库中有一个名为 deploymentOrModelName 的属性。这是因为在 OpenAI 中没有 Deployment Name，只有 Model Name。

备注

属性 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=<Your OpenAI Key>，而不是 spring.ai.azure.openai.api-key=<Your Azure OpenAi Key>。

添加仓库和 BOM​

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

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

自动配置​

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

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

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

Azure OpenAI Chat Client 是通过 Azure SDK 提供的 OpenAIClientBuilder 创建的。Spring AI 允许通过提供 AzureOpenAIClientBuilderCustomizer 的 bean 来自定义构建器。

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

@Configuration
public class AzureOpenAiConfig {

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

}
java

聊天属性​

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.azure.openai.chat 是用于配置 Azure OpenAI 的 ChatModel 实现的属性前缀。

属性描述默认值
spring.ai.azure.openai.chat.enabled启用 Azure OpenAI 聊天模型。true
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生成的最大 token 数量。-
spring.ai.azure.openai.chat.options.temperature用于控制生成完成内容的明显创造性的采样温度。较高的值将使输出更加随机，而较低的值将使结果更加集中和确定性。不建议在同一完成请求中同时修改 temperature 和 top_p，因为这两个设置的交互难以预测。0.7
spring.ai.azure.openai.chat.options.topP一种称为核采样的替代 temperature 采样的方法。此值使模型考虑具有提供概率质量的 token 结果。-
spring.ai.azure.openai.chat.options.logitBiasGPT token ID 和偏差分数之间的映射，影响特定 token 出现在完成响应中的概率。Token ID 通过外部 tokenizer 工具计算，而偏差分数范围在 -100 到 100 之间，最小值和最大值分别对应完全禁止或独占选择某个 token。给定偏差分数的确切行为因模型而异。-
spring.ai.azure.openai.chat.options.user操作调用者或最终用户的标识符。可用于跟踪或限速目的。-
spring.ai.azure.openai.chat.options.n应为聊天完成响应生成的聊天完成选项的数量。-
spring.ai.azure.openai.chat.options.stop一组文本序列，将结束生成完成内容。-
spring.ai.azure.openai.chat.options.presencePenalty一个值，影响生成 token 出现在生成文本中的概率，基于它们在生成文本中的现有存在。正值将使 token 在已经存在时不太可能出现，并增加模型输出新主题的可能性。-
spring.ai.azure.openai.chat.options.responseFormat一个对象，指定模型必须输出的格式。使用 AzureOpenAiResponseFormat.JSON 启用 JSON 模式，保证模型生成的消息是有效的 JSON。使用 AzureOpenAiResponseFormat.TEXT 启用 TEXT 模式。-
spring.ai.azure.openai.chat.options.frequencyPenalty一个值，影响生成 token 出现在生成文本中的概率，基于它们在生成文本中的累积频率。正值将使 token 随着其频率增加而更不可能出现，并减少模型逐字重复相同陈述的可能性。-
spring.ai.azure.openai.chat.options.proxy-tool-calls如果为 true，Spring AI 不会在内部处理函数调用，而是将它们代理给客户端。然后由客户端负责处理函数调用，将其分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型。false
提示

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

运行时选项​

AzureOpenAiChatOptions.java 提供了模型的配置选项，例如使用的模型、温度（temperature）、频率惩罚（frequency penalty）等。

在启动时，默认选项可以通过 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()
    ));
java
提示

除了特定于模型的 AzureOpenAiChatOptions.java 之外，你还可以使用一个可移植的 ChatOptions 实例，该实例通过 ChatOptionsBuilder#builder() 创建。

函数调用​

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

多模态​

多模态（Multimodality）指的是模型能够同时理解和处理来自多种来源的信息，包括文本、图像、音频和其他数据格式。目前，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();
java
提示

你也可以传递多张图片。

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

多模态测试图像

连同文本信息“解释一下你在这张图片上看到了什么？”，并生成如下响应：

This is an image of a fruit bowl with a simple design. The bowl is made of metal with curved wire edges that
create an open structure, allowing the fruit to be visible from all angles. Inside the bowl, there are two
yellow bananas resting on top of what appears to be a red apple. The bananas are slightly overripe, as
indicated by the brown spots on their peels. The bowl has a metal ring at the top, likely to serve as a handle
for carrying. The bowl is placed on a flat surface with a neutral-colored background that provides a clear
view of the fruit inside.

你也可以传入一个 classpath 资源而不是 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();
java

示例控制器​

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

在 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
application.properties

:::提示
将 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);
    }
}
java

手动配置​

AzureOpenAiChatModel 实现了 ChatModel 和 StreamingChatModel 接口，并使用 Azure OpenAI Java Client。

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

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

或者到你的 Gradle build.gradle 构建文件中。

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

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

提示

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

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

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

var openAIChatOptions = AzureOpenAiChatOptions.builder()
  .deploymentName("gpt-4o")
  .temperature(0.4)
  .maxTokens(200)
  .build();

var chatModel = new AzureOpenAiChatModel(this.openAIClient, this.openAIChatOptions);

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

// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
  new Prompt("Generate the names of 5 famous pirates."));
java
备注

gpt-4o 实际上是 Azure AI 门户中显示的 Deployment Name。

章节摘要​