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 定义了两个配置属性:
-
spring.ai.azure.openai.api-key
:将其设置为从 Azure 获取的 `API 密钥`的值。 -
spring.ai.azure.openai.endpoint
:将其设置为在 Azure 中预配模型时获取的终结点 URL。
您可以在 application.properties
或 application.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
实例。
不再需要创建 |
部署名称
要使用 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 自动配置、启动器模块的工件名称发生了重大变化。 有关更多信息,请参阅 升级说明。 |
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。使用 |
- |
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.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 |
(仅适用于流式传输)设置为添加一个额外的块,其中包含整个请求的令牌使用统计信息。此块的 |
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 |
与 |
- |
spring.ai.azure.openai.chat.options.responseFormat.schema |
响应格式 JSON 模式。仅适用于 |
- |
spring.ai.azure.openai.chat.options.frequencyPenalty |
一个值,根据生成文本中生成令牌的累积频率来影响其出现的概率。正值将使令牌随着频率增加而更不可能出现,并降低模型逐字重复相同语句的可能性。 |
- |
spring.ai.azure.openai.chat.options.proxy-tool-calls |
如果为 true,Spring AI 将不会在内部处理函数调用,而是将它们代理到客户端。然后,客户端负责处理函数调用,将它们分派到适当的函数,并返回结果。如果为 false(默认值),Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型 |
false |
所有以 |
令牌限制参数:模型特定用法
Azure OpenAI 对令牌限制参数有模型特定的要求:
模型系列 | 必需参数 | 注意事项 |
---|---|---|
推理模型 (o1, o3, o4-mini 系列) |
|
这些模型只接受 |
非推理模型 (gpt-4o, gpt-3.5-turbo 等) |
|
传统模型使用 |
参数 maxTokens
和 maxCompletionTokens
互斥。同时设置这两个参数将导致 Azure OpenAI 返回 API 错误。当您设置其中一个参数时,Spring AI Azure OpenAI 客户端将自动清除先前设置的参数,并发出警告消息。
var options = AzureOpenAiChatOptions.builder()
.deploymentName("o1-preview")
.maxCompletionTokens(500) // 推理模型必需
.build();
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.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?”,并生成如下响应:
这是一个带有简单设计的果盘图像。碗由金属制成,带有弯曲的铁丝边缘, 形成开放式结构,使水果可以从各个角度看到。碗内有两根 黄色香蕉,放在一个红苹果上面。香蕉略微过熟, 其果皮上的棕色斑点表明了这一点。碗顶部有一个金属环,可能用作 提手。碗放置在一个中性色背景的平面上,提供了 碗内水果的清晰视图。
您还可以传入类路径资源而不是 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
将 |
这将创建一个 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 实现了 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 添加到您的构建文件。 |
|
接下来,创建 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."));
|