|
获取最新的快照版本,请使用 Spring AI 1.1.3! |
Azure OpenAI 聊天
Azure 的 OpenAI 服务由 ChatGPT 提供支持,超越了传统的 OpenAI 功能,提供具备增强功能的 AI 驱动文本生成。Azure 还提供额外的 AI 安全性和负责任 AI 功能,如其最近的更新中此处所述。
Azure 为 Java 开发人员提供了通过将其与一系列 Azure 服务集成来充分利用 AI 潜力的机会,其中包括 Azure 上的向量存储等与 AI 相关的资源。
前提条件
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)来引用自定义环境变量:
# 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 配置属性,而不要设置上面提到的 api-key 属性。
仅找到端点属性时,您的应用程序将评估多种不同的选项来检索凭据,并将使用Tokens凭据创建一个 OpenAIClient 实例。
不再需要创建 TokenCredential bean;它会自动为您配置。 |
部署名称
要使用 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。 |
如果通过设置 spring.ai.azure.openai.openai-api-key=<Your OpenAI Key> 属性来决定连接到 OpenAI 而不是 Azure OpenAI,
那么 spring.ai.azure.openai.chat.options.deployment-name 将被视为一个 OpenAI 模型 名称。 |
自动配置
|
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。 |
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 |
聊天补全中生成的最大标记数。输入标记与生成标记的总长度受模型上下文长度限制。用于非推理模型(例如 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 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.presencePenalty |
一个值,它会根据生成文本中已有标记的存在情况,影响生成标记出现的概率。正值会使标记在已存在时更不容易出现,并提高模型输出新主题的可能性。 |
- |
spring.ai.azure.openai.chat.options.responseFormat.type |
兼容 |
- |
spring.ai.azure.openai.chat.options.responseFormat.schema |
响应格式JSON schemas。仅适用于 |
- |
spring.ai.azure.openai.chat.options.frequencyPenalty |
一个基于生成文本中标记的累积频率来影响其出现概率的值。正值会使标记随着频率的增加而更不容易出现,并降低模型逐字重复相同语句的可能性。 |
- |
spring.ai.azure.openai.chat.options.proxy-tool-calls |
如果为真,Spring AI 将不会在内部处理函数调用,而是将其代理给客户端。此时,由客户端负责处理函数调用、将其分发到相应的函数并返回结果。如果为假(默认值),Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型。 |
false |
所有以spring.ai.azure.openai.chat.options为前缀的属性都可以通过向Prompt调用中添加特定于请求的运行时选项在运行时覆盖。 |
Tokens限制参数:模型特定使用
Azure OpenAI 对于模型特定的标记限制参数有要求:
| 模型家族 | 必填参数 | 注意事项 |
|---|---|---|
推理模型 |
|
这些模型仅接受 |
非推理模型 |
|
传统模型使用 |
参数 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();
运行时选项
The AzureOpenAiChatOptions.java provides model configurations, such as the model to use, the temperature, the frequency penalty, etc.
On start-up, the default options can be configured with the AzureOpenAiChatModel(api, options) constructor or the spring.ai.azure.openai.chat.options.* properties.
在运行时,您可以通过向 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 图像作为输入:

以及文本消息“解释一下你在这张图片中看到了什么?”,并生成如下回复:
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();
示例控制器
创建一个新的Spring Boot项目,并将spring-boot-starter-web添加到您的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 implements the ChatModel and StreamingChatModel and uses the 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 构建脚本文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-azure-openai'
}
| 参考以下依赖管理部分,添加Spring AI BOM到你的构建文件中。 |
The spring-ai-azure-openai dependency also provide the access to the AzureOpenAiChatModel. For more information about the AzureOpenAiChatModel refer to the Azure OpenAI Chat section. |
接下来,创建一个 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 实际上是在Azure AI门户中展示的 Deployment Name。 |