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 endpoint
和 api-key
。
Spring AI 定义了两个配置属性:
-
spring.ai.azure.openai.api-key
:设置为从 Azure 获取的 API Key 值。 -
spring.ai.azure.openai.endpoint
:设置为在 Azure 中配置模型时获取的 endpoint 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 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 模型 名称。
|
添加仓库和 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 |
- |
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 |
一个包含自定义请求头的 Map,用于添加到 API 请求中。Map 中的每个条目代表一个请求头,其中 Key 是头名称,Value 是头内容 |
空 Map |
聊天自动配置的启用/禁用现在通过顶级属性
此项变更是为了支持多模型配置。 |
前缀 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 |
(仅限流式传输) 设置为 |
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 |
一个指定模型输出格式的对象。使用 |
- |
spring.ai.azure.openai.chat.options.frequencyPenalty |
一个基于已生成文本中 Token 累计出现频率来影响其后续出现概率的值。正数会随着 Token 频率增加而降低其再现概率,从而减少模型逐字重复相同表述的可能性 |
- |
spring.ai.azure.openai.chat.options.proxy-tool-calls |
若为 |
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-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);
}
}
手动配置
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("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 )。
|