Azure OpenAI Chat
Azure 提供的基于 ChatGPT 的 OpenAI 服务超越了传统的 OpenAI 功能,提供了增强的 AI 驱动文本生成能力。Azure 提供了额外的 AI 安全和负责任的 AI 功能,正如他们在 此处 的最新更新中强调的那样。
Azure 为 Java 开发者提供了利用 AI 全部潜力的机会,通过将其与各种 Azure 服务集成,其中包括 Azure 上的向量存储 (Vector Stores) 等 AI 相关资源。
先决条件
Azure OpenAI 客户端提供了三种连接选项:使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。
Azure API 密钥与终结点
从 Azure 门户 的 Azure OpenAI Service 部分获取您的 Azure OpenAI endpoint
和 api-key
。
Spring AI 定义了两个配置属性
-
spring.ai.azure.openai.api-key
: 将此属性设置为从 Azure 获取的API Key
值。 -
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>
OpenAI Key
要使用 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>
Microsoft Entra ID
要使用 Microsoft Entra ID(以前称为 Azure Active Directory)进行身份验证,请在您的配置中创建一个 TokenCredential
bean。如果此 bean 可用,将使用令牌凭据创建一个 OpenAIClient
实例。bd === 部署名称
要使用 Azure AI 应用程序,您需要通过 Azure AI 门户 创建一个 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>
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=<Your OpenAI Key> 属性,则 spring.ai.azure.openai.chat.options.deployment-name 将被视为一个 OpenAI 模型 名称。 |
自动配置
Spring AI 自动配置、starter 模块的 artifact 名称发生了重大变化。有关更多信息,请参阅升级说明。 |
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 'spring-ai-starter-model-azure-openai'
}
请参阅 依赖管理 部分将 Spring AI BOM 添加到您的构建文件。 |
Azure OpenAI Chat Client 是使用 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 的“资源管理”下的“密钥和终结点”部分获取的 Key |
- |
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。使用 |
- |
spring.ai.azure.openai.custom-headers |
包含在 API 请求中的自定义请求头映射。映射中的每个条目代表一个请求头,其中键是请求头名称,值是请求头值。 |
空映射 |
聊天自动配置的启用和禁用现在通过前缀为 要启用,设置 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 中使用时,这指的是您的模型的“部署名称”,您可以在 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 |
一种替代温度采样的核采样方法。此值导致模型考虑具有给定概率质量的 token 的结果。 |
- |
spring.ai.azure.openai.chat.options.logitBias |
GPT token ID 和偏差分数之间的映射,影响特定 token 出现在补全响应中的概率。token ID 通过外部分词工具计算,而偏差分数的范围在 -100 到 100 之间,最小值和最大值分别对应于完全禁止或独占选择一个 token。给定偏差分数的具体行为因模型而异。 |
- |
spring.ai.azure.openai.chat.options.user |
操作的调用方或终端用户的标识符。这可用于跟踪或速率限制目的。 |
- |
spring.ai.azure.openai.chat.options.stream-usage |
(仅用于流式传输) 设置此项可添加一个额外的块,其中包含整个请求的 token 用量统计信息。此块的 |
false |
spring.ai.azure.openai.chat.options.n |
应为聊天补全响应生成的聊天补全选项数量。 |
- |
spring.ai.azure.openai.chat.options.stop |
将结束补全生成的文本序列集合。 |
- |
spring.ai.azure.openai.chat.options.presencePenalty |
根据生成文本中现有 token 的出现频率影响生成 token 概率的值。正值会降低 token 在已存在时再次出现的可能性,并增加模型输出新主题的可能性。 |
- |
spring.ai.azure.openai.chat.options.responseFormat |
指定模型必须输出的格式的对象。使用 |
- |
spring.ai.azure.openai.chat.options.frequencyPenalty |
根据生成文本中 token 的累积频率影响生成 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 调用添加请求特定的运行时选项来覆盖。 |
运行时选项
The 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,您还可以使用通过 ChatOptionsBuilder#builder() 创建的可移植 ChatOptions 实例。 |
函数调用
您可以将自定义 Java 函数注册到 AzureOpenAiChatModel 中,并让模型智能地选择输出一个包含参数的 JSON 对象,以调用一个或多个已注册的函数。这是一种将 LLM 能力与外部工具和 API 连接起来的强大技术。阅读更多关于Azure OpenAI 函数调用的信息。
多模态
多模态是指模型同时理解和处理来自各种来源(包括文本、图像、音频和其他数据格式)信息的能力。目前,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.springjava.cn/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.
您也可以传递类路径资源,而不是 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-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);
}
}
手动配置
The 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>
或添加到您的 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-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 。 |