此版本仍在开发中,尚不被认为是稳定的。对于最新的快照版本,请使用 Spring AI 1.0.1! |
Azure OpenAI 聊天
Azure 的 OpenAI 产品由 ChatGPT 提供支持,超越了传统的 OpenAI 功能,提供具有增强功能的人工智能驱动的文本生成。Azure 提供了额外的 AI 安全和负责任的 AI 功能,正如他们最近的更新中所强调的那样 点击此处.
Azure 为 Java 开发人员提供了通过将 AI 与一系列 Azure 服务(包括 Azure 上的向量存储)集成来充分利用 AI 潜力的机会。
前提条件
Azure OpenAI 客户端提供三个连接选项:使用 Azure API 密钥或使用 OpenAI API 密钥,或使用 Microsoft Entra ID。
Azure API 密钥和终结点
若要使用 API 密钥访问模型,请获取 Azure OpenAIendpoint
和api-key
从 Azure 门户上的 Azure OpenAI 服务部分。
Spring AI 定义了两个配置属性:
-
spring.ai.azure.openai.api-key
:将此值设置为API Key
从 Azure 获得。 -
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) 来引用自定义环境变量:
# 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 密钥
若要使用 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 一起使用:
# 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
configuration 属性,而不是上面提到的 api-key 属性。
仅查找端点属性,您的应用程序将评估几个不同的选项来检索凭据和OpenAIClient
将使用Tokens凭据创建实例。
不再需要创建TokenCredential 豆;它会自动为您配置。 |
部署名称
若要使用 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 及其自动配置功能的默认配置一致。 如果使用不同的部署名称,请确保相应地更新配置属性:
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 模型名称。 |
添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。 请参阅 Artifact Repositories 部分,将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理,Spring AI 提供了 BOM(物料清单),以确保在整个项目中使用一致的 Spring AI 版本。请参阅依赖项管理部分,将 Spring AI BOM 添加到您的构建系统中。
自动配置
Spring AI 自动配置、入门模块的工件名称发生了重大变化。 有关更多信息,请参阅升级说明。 |
Spring AI 为 Azure OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它,请将以下依赖项添加到项目的 Mavenpom.xml
或 Gradlebuild.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
是配置ChatModel
Azure OpenAI 的实现。
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.azure.openai.chat.enabled(已删除且不再有效) |
启用 Azure OpenAI 聊天模型。 |
true |
spring.ai.model.聊天 |
启用 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 |
聊天补全时要生成的最大Tokens数。输入标记和生成标记的总长度受模型上下文长度的限制。用于非推理模型(例如,gpt-4o、gpt-3.5-turbo)。不能与 maxCompletionTokens 一起使用。 |
- |
spring.ai.azure.openai.chat.options.maxCompletionTokens |
可以为完成生成的标记数的上限,包括可见输出标记和推理标记。推理模型(例如 o1、o3、o4-mini 系列)所必需的。不能与 maxToken 一起使用。 |
- |
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 Tokens ID 和偏差分数之间的映射,影响特定Tokens出现在完成响应中的概率。Tokens ID 通过外部分词器工具计算,而偏差分数位于 -100 到 100 的范围内,最小值和最大值分别对应于完全禁止或独家选择Tokens。给定偏差分数的确切行为因模型而异。 |
- |
spring.ai.azure.openai.chat.options.user |
作的调用方或最终用户的标识符。这可用于跟踪或速率限制目的。 |
- |
spring.ai.azure.openai.chat.options.stream-usage |
(仅适用于流媒体)设置为添加一个额外的块,其中包含整个请求的Tokens使用情况统计信息。这 |
false |
spring.ai.azure.openai.chat.options.n |
应为聊天补全响应生成的聊天补全选项数。 |
- |
spring.ai.azure.openai.chat.options.stop |
将结束补全生成的文本序列的集合。 |
- |
spring.ai.azure.openai.chat.options.presence罚款 |
一个值,根据生成的Tokens在生成的文本中的现有存在,影响生成的Tokens出现的概率。正值将使标记在已经存在时不太可能出现,并增加模型输出新主题的可能性。 |
- |
spring.ai.azure.openai.chat.options.responseFormat.type |
兼容 |
- |
spring.ai.azure.openai.chat.options.responseFormat.schema |
响应格式 JSON 架构。仅适用于 |
- |
spring.ai.azure.openai.chat.options.frequency罚款 |
一个值,根据生成的标记在生成文本中的累积频率影响生成标记出现的概率。正值将使标记随着频率的增加而不太可能出现,并降低模型逐字重复相同陈述的可能性。 |
- |
spring.ai.azure.openai.chat.options.proxy-tool-calls |
如果为 true,则 Spring AI 不会在内部处理函数调用,而是将它们代理到客户端。然后,客户端负责处理函数调用,将它们分派到适当的函数,并返回结果。如果为 false(默认值),则 Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型 |
false |
所有以spring.ai.azure.openai.chat.options 可以通过将特定于请求的运行时选项添加到Prompt 叫。 |
Tokens限制参数:特定于模型的用法
Azure OpenAI 对Tokens限制参数具有特定于模型的要求:
型号系列 | 必填参数 | 笔记 |
---|---|---|
推理模型 |
|
这些型号仅接受 |
非推理模型 |
|
传统模型使用 |
参数maxTokens 和maxCompletionTokens 是相互排斥的。同时设置这两个参数将导致 Azure OpenAI 出现 API 错误。当您设置另一个参数时,Spring AI Azure OpenAI 客户端将自动清除之前设置的参数,并显示警告消息。 |
var options = AzureOpenAiChatOptions.builder()
.deploymentName("o1-preview")
.maxCompletionTokens(500) // Required for reasoning models
.build();
var options = AzureOpenAiChatOptions.builder()
.deploymentName("gpt-4o")
.maxTokens(500) // Required for non-reasoning models
.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#builder() 创建的可移植 ChatOptions 实例。 |
函数调用
可以向 AzureOpenAiChatModel 注册自定义 Java 函数,并让模型智能地选择输出包含参数的 JSON 对象,以调用一个或多个已注册的函数。 这是一种将 LLM 功能与外部工具和 API 连接起来的强大技术。 阅读有关工具调用的更多信息。
模 态
多模态是指模型同时理解和处理来自各种来源的信息的能力,包括文本、图像、音频和其他数据格式。
目前,Azure OpenAIgpt-4o
模型提供多模式支持。
Azure OpenAI 可以将 base64 编码的图像或图像 URL 列表与消息合并。
Spring AI 的消息界面通过引入媒体类型促进了多模态 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
图像:

以及短信“解释你在这张图片上看到了什么?”,并生成如下响应:
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();
Samples控制器
创建一个新的 Spring Boot 项目,并将spring-ai-starter-model-azure-openai
到你的 pom(或 gradle)依赖项。
添加一个application.properties
文件,在src/main/resources
目录,以启用和配置 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>
或 Gradlebuild.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-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."));
// Or with streaming responses
Flux<ChatResponse> streamingResponses = chatModel.stream(
new Prompt("Generate the names of 5 famous pirates."));
这gpt-4o 实际上是Deployment Name 如 Azure AI 门户中所示。 |