Azure OpenAI 聊天
Azure 的 OpenAI 服务由 ChatGPT 提供支持,它超越了传统的 OpenAI 功能,提供具有增强功能的 AI 驱动的文本生成。Azure 提供了额外的 AI 安全性和负责任的 AI 功能,如他们在最近的更新 这里所强调的。
Azure 为 Java 开发者提供了通过将其与一系列 Azure 服务集成来充分利用 AI 潜力的机会,其中包括 AI 相关资源,如 Azure 上的向量存储。
前提条件
Azure OpenAI 客户端提供三种连接选项:使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。
Azure API 密钥和端点
要使用 API 密钥访问模型,请从 Azure 门户的 Azure OpenAI 服务部分获取你的 Azure OpenAI endpoint
和 api-key
。
Spring AI 定义了两个配置属性:
-
spring.ai.azure.openai.api-key
:设置为从 Azure 获取的API Key
值。 -
spring.ai.azure.openai.endpoint
:设置为在 Azure 中配置模型时获取的端点 URL。
你可以在 application.properties
或 application.yml
文件中设置这些配置属性:
spring.ai.azure.openai.api-key=<your-azure-api-key>
spring.ai.azure.openai.endpoint=<your-azure-endpoint-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=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-openai-endpoint-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=<your-azure-openai-key>
spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>
使用 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=<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 属性。
仅找到端点属性时,你的应用程序将评估几个不同的选项来检索凭据,并将使用令牌凭据创建 OpenAIClient
实例。
注意:不再需要创建 TokenCredential
bean;它会自动为你配置。
部署名称
要使用 Azure AI 应用程序,你需要通过 Azure AI 门户创建 Azure AI 部署。
在 Azure 中,每个客户端必须指定一个 Deployment Name
来连接到 Azure OpenAI 服务。
重要的是要注意 Deployment Name
与你选择部署的模型不同。
例如,名为 '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=<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=<Your OpenAI Key>
属性连接到 OpenAI
而不是 Azure OpenAI
,
那么 spring.ai.azure.openai.chat.options.deployment-name
将被视为 OpenAI 模型名称。
自动配置
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。
这会自动将端点设置为 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 |
生成的最大令牌数。 |
- |
spring.ai.azure.openai.chat.options.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 |
(仅用于流式传输)设置为添加一个额外的块,其中包含整个请求的令牌使用统计信息。此块的 |
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 |
指定模型必须输出的格式的对象。使用 |
- |
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
调用中添加请求特定的 运行时选项 在运行时被覆盖。
运行时选项
AzureOpenAiChatOptions.java 提供模型配置,如要使用的模型、温度、频率惩罚等。
在启动时,默认选项可以通过 AzureOpenAiChatModel(api, options)
构造函数或 spring.ai.azure.openai.chat.options.*
属性进行配置。
在运行时,你可以通过在 Prompt
调用中添加新的、请求特定的选项来覆盖默认选项。
例如,要覆盖特定请求的默认模型和温度:
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
AzureOpenAiChatOptions.builder()
.deploymentName("gpt-4o")
.temperature(0.4)
.build()
));
提示:除了模型特定的 AzureOpenAiChatOptions 外,你还可以使用可移植的 ChatOptions 实例,该实例使用 ChatOptionsBuilder#builder() 创建。
函数调用
你可以向 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("解释你在这张图片上看到了什么?").media(MimeTypeUtils.IMAGE_PNG, this.url))
.call()
.content();
提示:你也可以传递多个图像。
它接收 multimodal.test.png
图像作为输入:

以及文本消息"解释你在这张图片上看到了什么?",并生成类似这样的响应:
这是一张水果篮的图片,设计简单。篮子由金属制成,带有弯曲的金属丝边缘, 形成一个开放的结构,使水果可以从各个角度看到。篮子里有两个 黄色的香蕉放在一个红色苹果上面。香蕉有点过熟,这可以从 香蕉皮上的棕色斑点看出。篮子在顶部有一个金属环,可能是用来 提篮子的把手。篮子放在一个平面上,背景是中性的,可以清晰地 看到里面的水果。
你也可以传入一个类路径资源而不是 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("解释你在这张图片上看到了什么?")
.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 = "给我讲个笑话") String message) {
return Map.of("generation", this.chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") 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 聊天部分。
接下来,创建 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("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux<ChatResponse> streamingResponses = chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
注意:gpt-4o
实际上是 Azure AI 门户中显示的 Deployment Name
。