Azure OpenAI

本站(springdoc.cn)中的内容来源于 spring.io ,原始版权归属于 spring.io。由 springdoc.cn 进行翻译,整理。可供个人学习、研究,未经许可,不得进行任何转载、商用或与之相关的行为。 商标声明:Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Azure 基于 ChatGPT 的 OpenAI 服务超越了传统 OpenAI 能力,提供具备增强功能的 AI 驱动文本生成。如 近期更新所述,Azure 还额外提供 AI 安全性和负责任 AI 特性。

Azure 为 Java 开发者提供通过整合各类 Azure 服务(包括 AI 相关资源如 Azure 上的向量存储)来充分释放 AI 潜力的机会。

先决条件

Azure OpenAI 客户端提供三种连接方式:使用 Azure API Key、OpenAI API Key 或 Microsoft Entra ID。

Azure API Key 和 Endpoint

要通过 API Key 访问模型,请从 Azure 门户 的 Azure OpenAI 服务部分获取你的 Azure OpenAI endpointapi-key

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

  1. spring.ai.azure.openai.api-key:设置为从 Azure 获取的 API Key 值。

  2. spring.ai.azure.openai.endpoint:设置为在 Azure 中配置模型时获取的 endpoint URL。

你可以在 application.propertiesapplication.yml 文件中设置这些配置属性:

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

为增强处理敏感信息(如 API Key)时的安全性,你可以使用 Spring 表达式语言(SpEL)引用自定义环境变量:

# In application.yml
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}
# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-openai-endpoint-url>

OpenAI Key

要认证 OpenAI 服务(非 Azure),需提供 OpenAI API Key。这将自动将终端点设置为 api.openai.com/v1

采用此方式时,需将 spring.ai.azure.openai.chat.options.deployment-name 属性设置为希望使用的 OpenAI 模型 名称。

在你的应用配置中:

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

使用 SpEL 引用环境变量:

# In application.yml
spring:
  ai:
    azure:
      openai:
        openai-api-key: ${AZURE_OPENAI_API_KEY}
        chat:
          options:
            deployment-name: ${AZURE_OPENAI_MODEL_NAME}
# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-openai-key>
export AZURE_OPENAI_MODEL_NAME=<openai-model-name>

Microsoft Entra ID

要实现使用 Microsoft Entra ID(原 Azure Active Directory)的无密钥认证,只需设置 spring.ai.azure.openai.endpoint 配置属性,无需设置上述 api-key 属性。

当仅配置 endpoint 属性时,你的应用将尝试通过多种方式获取凭证,最终使用 Token 凭证创建 OpenAIClient 实例。

不再需要手动创建 TokenCredential Bean,系统会自动完成该配置。

部署名称

要使用 Azure AI 应用,需通过 Azure AI 门户 创建 Azure AI 部署。在 Azure 中,每个客户端必须指定部署名称(Deployment Name)来连接 Azure OpenAI 服务。需注意部署名称不同于所选部署的模型名称,例如名为 'MyAiDeployment' 的部署可配置为使用 GPT 3.5 Turbo 或 GPT 4.0 模型。

请按以下步骤使用默认设置创建部署:

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

该 Azure 配置与 Spring Boot Azure AI Starter 及其自动配置功能的默认设置一致。若使用不同部署名称,请相应更新以下配置属性:

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

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
若通过设置属性 spring.ai.azure.openai.openai-api-key=<你的OpenAI密钥> 连接至 OpenAI(而非 Azure 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 中央仓库和 Spring Snapshot 仓库。参阅 Artifact 仓库 章节将这些仓库添加到你的构建系统。

为简化依赖管理,Spring AI 提供了 BOM 来确保整个项目使用统一版本的 Spring AI。参阅 依赖管理 章节将 Spring AI BOM 添加到你的构建系统。

自动配置

Spring AI 自动配置和 Starter 模块的构件名称已发生重大变更。更多信息请参阅 升级说明

Spring AI 为 Azure OpenAI Chat Client 提供了 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 Chat Client 通过 Azure SDK 提供的 OpenAIClientBuilder 创建。Spring AI 支持通过注册 AzureOpenAIClientBuilderCustomizer 类型的 Bean 来自定义 Builder。

例如,可通过 Customizer 修改默认响应超时时间:

@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 Resource ManagementKeys and Endpoint 部分的 Key

-

spring.ai.azure.openai.endpoint

Azure AI OpenAI Resource ManagementKeys and Endpoint 部分的终端点

-

spring.ai.azure.openai.openai-api-key

(非 Azure)OpenAI API 密钥。用于直接认证 OpenAI 服务(而非 Azure OpenAI),该配置会自动将终端点设为 api.openai.com/v1 。可选择使用 api-keyopenai-api-key 属性。在此配置下,spring.ai.azure.openai.chat.options.deployment-name 将被视为 OpenAI 模型 名称

-

spring.ai.azure.openai.custom-headers

一个包含自定义请求头的 Map,用于添加到 API 请求中。Map 中的每个条目代表一个请求头,其中 Key 是头名称,Value 是头内容

空 Map

聊天自动配置的启用/禁用现在通过顶级属性 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 环境中使用时,此参数指模型的 “部署名称”(Deployment Name),可在 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

作为温度采样的替代方案,核采样(nucleus sampling)使模型仅考虑累计概率达到指定阈值(top_p)值的 Token 候选集

-

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

一个 Map,包含 GPT token ID 与偏置分数的对应关系,用于影响特定 Token 在补全响应中出现的概率。Token ID 需通过外部 Tokenizer 工具计算,偏置分数范围 -100 至 100,最小值表示完全禁止该 Token,最大值表示强制选择该 Token。具体偏置效果因模型而异

-

spring.ai.azure.openai.chat.options.user

用于标识操作调用方或终端用户的 ID。该参数可用于追踪或限流目的

-

spring.ai.azure.openai.chat.options.stream-usage

(仅限流式传输) 设置为 true 时,将在流式响应末尾添加一个包含整个请求 Token 使用统计的额外数据块。该数据块的 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

一个基于已生成文本中 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()
    ));
除了特定于模型的 AzureOpenAiChatOptions.java 之外,你还可以使用通过 ChatOptionsBuilder#builder() 创建的可移植 ChatOptions 实例。

函数调用

你可以将自定义的 Java 函数注册到 AzureOpenAiChatModel 中,让模型智能地选择输出一个包含调用一个或多个已注册函数所需参数的 JSON 对象。这是一种将大语言模型(LLM)能力与外部工具和 API 相连接的强大技术。了解更多关于 工具调用(Tool Calling) 的内容。

多模态

多模态是指模型同时理解和处理来自多种来源的信息的能力,包括文本、图像、音频和其他数据格式。目前,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?”,并生成类似如下的响应:

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 Resource),而不是 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();

示例 Controller

创建 一个新的 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 聊天 部分。

接下来,创建一个 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-4o")
  .temperature(0.4)
  .maxTokens(200)
  .build();

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

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

// Or with streaming responses
Flux<ChatResponse> streamingResponses = chatModel.stream(
  new Prompt("Generate the names of 5 famous pirates."));
gpt-4o 实际上是在 Azure AI 门户中显示的部署名称(Deployment Name)。