|
最新快照版本请使用Spring AI 1.1.0! |
Azure OpenAI Chat
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 Key & Endpoint
要使用API密钥访问模型,请获取您的Azure OpenAI端点和API密钥来自Azure Portal的Azure OpenAI服务部分。
Spring AI 定义了两个配置属性:
-
Spring.ai.Azure.Openai.API-Key:将此设为API 密钥摘自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配置属性,而不是上述提到的API-key属性。
仅找到端点属性后,你的应用程序将评估多种获取凭证和OpenAIClient实例将使用Tokens凭证创建。
不再需要创建一个Tokens凭证豆;它是自动为你配置的。 |
部署名称
要使用 Azure AI 应用,你需要通过 Azure AI 门户创建一个 Azure AI 部署。
在Azure中,每个客户端必须指定一个部署名称连接 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中没有部署名称,仅为a型号名称.
该物业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模型名称。 |
自动配置
|
春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明。 |
Spring AI 为 Azure OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它,请在项目的Maven中添加以下依赖pom.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的物料清单添加到你的构建文件中。 |
Azure OpenAI 聊天客户端是使用 Azure SDK 提供的 OpenAIClientBuilder 创建的。Spring AI 允许通过提供 AzureOpenAIClientBuilderCustomizer 豆来定制构建器。
例如,可以使用自定义器来更改默认的响应超时:
@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 |
(非青色)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 的实现。
| 属性 | 描述 | 默认值 |
|---|---|---|
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 |
聊天补全时最多可生成的Tokens数。输入标记和生成标记的总长度受模型上下文长度限制。用于非推理模型(例如,GPT-40,GPT-3.5-turbo)。不能与 maxCompletionTokens 一起使用。 |
- |
spring.ai.azure.openai.chat.options.maxCompletionTokens |
完成化可生成的Tokens数量的上限,包括可见的输出Tokens和推理Tokens。推理模型(例如 o1、o3、o4-mini 系列)必备。不能和maxTokens一起使用。 |
- |
spring.ai.azure.openai.chat.options.temperature. |
采样温度决定了生成完备的显得创造力。值越高,输出越随机,值越低,结果越聚焦且确定性强。不建议对相同的完井请求调整温度和top_p,因为这两种设置的相互作用难以预测。 |
0.7 |
spring.ai.azure.openai.chat.options.topP |
一种温度采样的替代方案称为核采样。该值使模型考虑具有该概率质量的Tokens的结果。 |
- |
spring.ai.azure.openai.chat.options.logitBias |
一个介于GPTTokensID与偏差分数之间的映射,影响特定Tokens出现在完成回复中的概率。TokensID通过外部Tokens工具计算,偏差分数在-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 |
这是一个影响生成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.frequencyPenalty |
这是一个根据生成词在生成文本中累计频率影响生成Tokens出现概率的值。正值会使标记出现的可能性降低,因为符号频率增加,并降低模型逐字重复相同陈述的可能性。 |
- |
Spring.ai.azure.openai.chat.options.proxy-tool-calls |
如果属实,Spring AI不会在内部处理函数调用,而是会代理给客户端。那么,客户端负责处理函数调用,将其派遣到相应的函数,并返回结果。如果 false(默认),Spring AI 会在内部处理函数调用。仅适用于支持函数调用的聊天模型 |
false |
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.*性能。
运行时,你可以通过添加新的、针对请求的选项来覆盖默认选项提示叫。
例如,针对特定请求覆盖默认型号和温度:
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 的 Message 界面通过引入媒体类型,促进了多模态 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-ai-starter-model-azure-openai对你的POM(或Gradle)依赖。
添加一个application.properties文件,在src/主/资源目录,用于启用和配置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密钥和端点用你的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 实现了聊天模型和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的物料清单添加到你的构建文件中。 |
这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实际上是部署名称如Azure AI门户所示。 |