Azure OpenAI 聊天

Azure 的 OpenAI 产品由 ChatGPT 提供支持,它超越了传统的 OpenAI 功能,提供增强型 AI 驱动的文本生成。Azure 提供了额外的 AI 安全和负责任的 AI 功能,正如其最新更新 此处所强调的。 Azure 为 Java 开发人员提供了利用 AI 全部潜力的机会,通过将其与一系列 Azure 服务集成,其中包括 Azure 上的向量存储等 AI 相关资源。

先决条件

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

Azure API 密钥和终结点

要使用 API 密钥访问模型,请从 Azure 门户上的 Azure OpenAI 服务部分获取您的 Azure OpenAI 终结点`和 `api-key

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

  1. spring.ai.azure.openai.api-key:将其设置为从 Azure 获取的 `API 密钥`的值。

  2. spring.ai.azure.openai.endpoint:将其设置为在 Azure 中预配模型时获取的终结点 URL。

您可以在 application.propertiesapplication.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 密钥。这将自动将终结点设置为 [role="bare"][role="bare"][role="bare"]https://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

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>
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。 这会自动将终结点设置为 [role="bare"][role="bare"][role="bare"]https://api.openai.com/v1。使用 api-keyopenai-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.azure.openai.chat.enabled (已移除且不再有效)

启用 Azure OpenAI 聊天模型。

true

spring.ai.model.chat

启用 Azure OpenAI 聊天模型。

azure-openai

spring.ai.azure.openai.chat.options.deployment-name

在 Azure 中使用时,这指的是您的模型的“部署名称”,您可以在 [role="bare"][role="bare"][role="bare"]https://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

用于控制生成补全的明显创造性的采样温度。值越高,输出越随机,而值越低,结果越集中和确定性。不建议为同一补全请求同时修改 temperature 和 top_p,因为这两个设置的交互难以预测。

0.7

spring.ai.azure.openai.chat.options.topP

一种替代温度采样的核采样方法。此值使模型考虑具有给定概率质量的令牌结果。

-

spring.ai.azure.openai.chat.options.logitBias

GPT 令牌 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-4oGPT-4o miniGPT-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 错误。

参数 maxTokensmaxCompletionTokens 互斥。同时设置这两个参数将导致 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 实例,通过 ChatOptions#builder() 创建。

函数调用

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

多模态

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

Azure OpenAI 可以将 base64 编码图像列表或图像 URL 与消息一起包含。 Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。 此类型包含有关消息中媒体附件的数据和详细信息,使用 Spring 的 org.springframework.util.MimeTypejava.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 图像作为输入:

multimodal.test

以及文本消息“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-keyendpoint 替换为您的 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 实现了 ChatModelStreamingChatModel,并使用了 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 门户中显示的 部署名称