此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

Azure OpenAI 聊天

Azure 的 OpenAI 服务,由 ChatGPT 提供支持,超越了传统的 OpenAI 功能,提供了增强的 AI 驱动文本生成能力。Azure 还提供了额外的 AI 安全和负责任 AI 特性,如他们最近更新的内容 这里spring-doc.cadn.net.cn

Azure 为Java开发人员提供了利用AI全部潜力的机会,通过将其与一系列Azure服务集成,包括Azure相关的AI资源,如Azure向量存储。spring-doc.cadn.net.cn

前置条件

Azure OpenAI客户端提供了三种连接选项:使用Azure API密钥、使用OpenAI API密钥或使用Microsoft Entra ID。spring-doc.cadn.net.cn

Azure API密钥与端点

要通过 API 密钥访问模型,请从 Azure 开发门户的 Azure OpenAI 服务部分获得 Azure OpenAI endpointapi-keyspring-doc.cadn.net.cn

Azure Portalspring-doc.cadn.net.cn

spring-doc.cadn.net.cn

Spring AI 定义了两个配置属性:spring-doc.cadn.net.cn

  1. spring.ai.azure.openai.api-key: 将其设置为从Azure获得的API Key的值。spring-doc.cadn.net.cn

  2. spring.ai.azure.openai.endpoint: 将此设置为您在Azure中部署模型时获得的端点URL。spring-doc.cadn.net.cn

您可以在您的application.propertiesapplication.yml文件中设置这些配置属性:spring-doc.cadn.net.cn

spring.ai.azure.openai.api-key=<your-azure-api-key>
spring.ai.azure.openai.endpoint=<your-azure-endpoint-url>

当处理如API密钥等敏感信息时,为了增强安全性,您可以使用Spring表达式语言(SpEL)引用自定义环境变量:spring-doc.cadn.net.cn

# 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/v1spring-doc.cadn.net.cn

使用此方法时,请将spring.ai.azure.openai.chat.options.deployment-name属性设置为您希望使用的OpenAI模型的名称。spring-doc.cadn.net.cn

在您的应用程序配置中:spring-doc.cadn.net.cn

spring.ai.azure.openai.openai-api-key=<your-azure-openai-key>
spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>

使用环境变量与SpEL:spring-doc.cadn.net.cn

# 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)进行无密钥身份验证时,请仅设置 配置属性 0不要 设置上述提到的 api-key 属性。spring-doc.cadn.net.cn

找到仅端点属性,您的应用程序将评估几种不同的凭据检索选项,并使用Tokens凭据创建一个OpenAIClient实例。spring-doc.cadn.net.cn

不再需要创建一个TokenCredential bean;它会为你自动配置。

部署名称

要使用 Azure AI 应用程序,您需要通过 Azure AI门户 创建一个 Azure AI 部署。 在 Azure 中,每个客户端必须指定一个 Deployment Name 以连接到 Azure OpenAI 服务。 请注意,Deployment Name 与您选择部署的模型不同。 例如,名为 'MyAiDeployment' 的部署可以配置为使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。spring-doc.cadn.net.cn

要开始,请按照以下步骤创建具有默认设置的部署:spring-doc.cadn.net.cn

Deployment Name: `gpt-4o`
Model Name: `gpt-4o`

此Azure配置与Spring Boot Azure AI Starter的默认配置及其自动配置功能对齐。 如果您使用不同的部署名称,请确保相应地更新配置属性:spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.deployment-name=<my deployment name>

Azure OpenAI 和 OpenAI 的不同部署结构导致了 Azure OpenAI 客户端库中存在一个名为 deploymentOrModelName 的属性。 这是因为,在 OpenAI 中不存在 Deployment Name,只有 Model Namespring-doc.cadn.net.cn

属性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模型名称。

访问OpenAI模型

您可以配置客户端直接使用OpenAI而不是部署的Azure OpenAI模型。 为此,您需要将spring.ai.azure.openai.openai-api-key=<Your OpenAI Key>设置为替代spring.ai.azure.openai.api-key=<Your Azure OpenAi Key>spring-doc.cadn.net.cn

添加仓库和BOM

Spring AI 构件发布在 Maven 中央仓库和 Spring Snapshot 仓库中。 请参阅 构件仓库 部分,将这些仓库添加到您的构建系统中。spring-doc.cadn.net.cn

为了帮助进行依赖管理,Spring AI 提供了一个 BOM(物料清单),以确保整个项目中使用的是相同的 Spring AI 版本。请参阅 依赖管理 部分,将 Spring AI BOM 添加到您的构建系统中。spring-doc.cadn.net.cn

Auto-configuration

Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。spring-doc.cadn.net.cn

Spring AI 提供了对 Azure OpenAI 聊天客户端的 Spring Boot 自动配置。 要启用它,请在项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中添加以下依赖项:spring-doc.cadn.net.cn

<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添加到您的构建文件中。

The Azure OpenAI Chat Client 是使用由 Azure SDK 提供的 OpenAIClientBuilder 创建的。Spring AI 允许通过提供 AzureOpenAIClientBuilderCustomizer 颗粒来自定义构建器。spring-doc.cadn.net.cn

一个自定义设置可以用来修改默认响应超时时间,例如:spring-doc.cadn.net.cn

@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-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.azure.openai.api-keyspring-doc.cadn.net.cn

Azure AI OpenAI 的 Key 从 Keys and Endpoint 部分下的 Resource Managementspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.endpointspring-doc.cadn.net.cn

来自Azure AI OpenAI Keys and Endpoint 部分下的 Resource Management 的端点spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.openai-api-keyspring-doc.cadn.net.cn

(non Azure) OpenAI API密钥。用于向OpenAI服务进行身份验证,而不是Azure OpenAI。 这会自动将端点设置为 api.openai.com/v1。可以使用属性api-keyopenai-api-key 中的一个。 在此配置中,spring.ai.azure.openai.chat.options.deployment-name 被视为一个 OpenAi模型名称。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.custom-headersspring-doc.cadn.net.cn

在API请求中包含的自定义标头映射。映射中的每个条目代表一个标头,其中键是标头名称,值是标头值。spring-doc.cadn.net.cn

空映射spring-doc.cadn.net.cn

现在通过带有前缀spring.ai.model.chat的顶级属性来配置聊天自动配置的启用和禁用。spring-doc.cadn.net.cn

要启用,请设置:spring.ai.model.chat=azure-openai(默认已启用)spring-doc.cadn.net.cn

要禁用,请设置spring.ai.model.chat=none(或任何不匹配azure-openai的值)spring-doc.cadn.net.cn

此更改是为了允许配置多个模型。spring-doc.cadn.net.cn

spring.ai.azure.openai.chat 前缀是配置 Azure OpenAI 实现的属性前缀。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.azure.openai.chat.enabled (已移除且不再有效)spring-doc.cadn.net.cn

启用 Azure OpenAI 对话模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.model.chatspring-doc.cadn.net.cn

启用 Azure OpenAI 对话模型。spring-doc.cadn.net.cn

azure-openaispring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.deployment-namespring-doc.cadn.net.cn

在与Azure配合使用时,这指的是您的模型的"部署名称",您可以在oai.azure.com/portal找到它。 需要注意的是,在Azure OpenAI部署中,"部署名称"与模型本身是不同的。 这些术语之间的混淆源于希望使Azure OpenAI客户端库与原始OpenAI端点兼容。 Azure OpenAI和Sam Altman的OpenAI提供的部署结构差异很大。 在此次完成请求时需要提供作为部署名称的模型名称。spring-doc.cadn.net.cn

gpt-4ospring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.maxTokensspring-doc.cadn.net.cn

聊天补全时生成的最大Tokens数。输入Tokens和生成Tokens的总长度受限于模型的上下文长度。仅用于非推理模型(例如,gpt-4o、gpt-3.5-turbo)。不能与maxCompletionTokens一起使用。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.maxCompletionTokensspring-doc.cadn.net.cn

生成完成内容时可产生的标记数量的上限,包括可见输出标记和推理标记。对于推理模型(例如o1、o3、o4-mini系列)必选;不能与maxTokens同时使用。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.temperaturespring-doc.cadn.net.cn

使用以控制生成完成内容的看似创造力的采样温度。较高值会使输出更具随机性,而较低值会使结果更集中和确定。不建议在同一完成请求中同时修改温度和top_p,因为这两个设置之间的交互难以预测。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.topPspring-doc.cadn.net.cn

替代采样温度的方法称为核采样。此值使模型考虑所提供概率质量的标记结果。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.logitBiasspring-doc.cadn.net.cn

一个将GPT_token IDs与影响特定token在完成响应中出现概率的偏置分数建立映射的关系。Token IDs通过外部分词工具计算得出,而偏置分数则位于-100到100之间,最小值和最大值分别对应于完全禁止或独家选择某个token的行为。每个给定的偏置分数的具体行为会因模型不同而异。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.userspring-doc.cadn.net.cn

操作的调用者或最终用户的标识符。这可能用于跟踪或速率限制的目的。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.stream-usagespring-doc.cadn.net.cn

(仅适用于流式传输) 设置以添加一个额外的分块,其中包含整个请求的 token 使用统计信息。此分块的 choices 字段为空数组,所有其他分块也将包含一个 usage 字段,但其值为 null。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.nspring-doc.cadn.net.cn

应为聊天补全响应生成的聊天补全选项的数量。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.stopspring-doc.cadn.net.cn

一个文本序列集合,用于结束完成生成。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.presencePenaltyspring-doc.cadn.net.cn

基于生成文本中已存在情况影响生成词元出现概率的值。正值会使已存在的词元出现的概率降低,并增加模型输出新话题的可能性。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.responseFormat.typespring-doc.cadn.net.cn

兼容 GPT-4oGPT-4o miniGPT-4 Turbo 以及所有新于 gpt-3.5-turbo-1106GPT-3.5 Turbo 模型。 JSON_OBJECT 类型启用 JSON 模式,可保证模型生成的消息是有效的 JSON。 JSON_SCHEMA 类型启用结构化输出,可保证模型将匹配您提供的 JSON 架构。JSON_SCHEMA 类型还需要设置 responseFormat.schema 属性。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.responseFormat.schemaspring-doc.cadn.net.cn

响应格式为JSON方案。仅适用于responseFormat.type=JSON_SCHEMAspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.frequencyPenaltyspring-doc.cadn.net.cn

基于生成文本中累积频率影响生成Tokens出现概率的值。正数值会使得频率越高的Tokens不太可能出现,并且减少模型重复相同语句的可能性。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.tool-namesspring-doc.cadn.net.cn

使用名称标识的工具列表,以在单个提示请求中启用功能调用。具有这些名称的工具必须存在于ToolCallback注册表中。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.tool-callbacksspring-doc.cadn.net.cn

使用回调注册与ChatModel相关的工具。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.azure.openai.chat.options.internal-tool-execution-enabledspring-doc.cadn.net.cn

如果为假,Spring AI 将不会内部处理工具调用,而是将它们代理给客户端。然后需要由客户端负责处理这些工具调用、将其分派到适当的函数,并返回结果。如果为真(默认值),Spring AI 将会内部处理这些函数调用。仅适用于支持功能调用的聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

所有以spring.ai.azure.openai.chat.options开头的属性可以在运行时通过向Prompt调用添加请求特定的运行时选项来覆盖。

Token 限制 参数:模型特定用法

Azure OpenAI 对于不同的模型有特定的Tokens限制参数要求:spring-doc.cadn.net.cn

模型家族 所需参数 注释

推理模型
(o1, o3, o4-mini系列)spring-doc.cadn.net.cn

maxCompletionTokensspring-doc.cadn.net.cn

这些模型只接受maxCompletionTokens。使用maxTokens将导致API错误。spring-doc.cadn.net.cn

非推理模型
(gpt-4o, gpt-3.5-turbo, 等等)spring-doc.cadn.net.cn

maxTokensspring-doc.cadn.net.cn

传统模型使用 maxTokens 进行输出限制。使用 maxCompletionTokens 可能会导致API错误。spring-doc.cadn.net.cn

参数 maxTokensmaxCompletionTokens互斥的。同时设置这两个参数将导致 Azure OpenAI API 报错。Spring AI Azure OpenAI 客户端会在你设置另一个参数时自动清除之前设置的参数,并伴有警告消息。
示例:使用maxCompletionTokens 用于推理模型
var options = AzureOpenAiChatOptions.builder()
    .deploymentName("o1-preview")
    .maxCompletionTokens(500)  // Required for reasoning models
    .build();
示例:使用maxTokens非推理模型
var options = AzureOpenAiChatOptions.builder()
    .deploymentName("gpt-4o")
    .maxTokens(500)  // Required for non-reasoning models
    .build();

运行时选项

The AzureOpenAiChatOptions.java 提供了模型配置,例如要使用的模型、温度、频率惩罚等。spring-doc.cadn.net.cn

启动时,可以使用AzureOpenAiChatModel(api, options)构造函数或spring.ai.azure.openai.chat.options.*属性来配置默认选项。spring-doc.cadn.net.cn

在运行时,您可以通过向Prompt调用添加新的、针对请求的选项来覆盖默认选项。 例如,要为特定请求覆盖默认模型和温度:spring-doc.cadn.net.cn

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连接起来。 有关工具调用的更多信息,请继续阅读。spring-doc.cadn.net.cn

多模态

多模态指的是模型同时理解和处理来自各种来源的信息的能力,包括文本、图像、音频和其他数据格式。 目前,Azure OpenAI gpt-4o 模型提供了多模态支持。spring-doc.cadn.net.cn

Azure OpenAI 可以将 base64 编码的图像列表或图片 URL 与消息一起使用。 Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 AI 模型。 此类型包含了消息中媒体附件的数据和细节,并利用了 Spring 的 org.springframework.util.MimeType 以及一个 java.lang.Object 来处理原始的媒体数据。spring-doc.cadn.net.cn

以下是从OpenAiChatModelIT.java摘取的一段代码示例,展示了使用GPT_4_O模型将用户文本与图像融合的过程。spring-doc.cadn.net.cn

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图像:spring-doc.cadn.net.cn

Multimodal Test Image

<p>along with the text message &quot;Explain what do you see on this picture?&quot;, and generates a response like this:</p>spring-doc.cadn.net.cn

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,如下例所示。spring-doc.cadn.net.cn

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项目,并在pom(或gradle)依赖中添加spring-ai-starter-model-azure-openaispring-doc.cadn.net.cn

src/main/resources目录下添加一个application.properties文件,以启用并配置OpenAI聊天模型:spring-doc.cadn.net.cn

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-keyendpoint替换为您的Azure OpenAI凭据。

这将创建一个AzureOpenAiChatModel实现,你可以在你的类中注入。 以下是一个使用聊天模型进行文本生成的简单@Controller类示例。spring-doc.cadn.net.cn

@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 实现了 ChatModelStreamingChatModel,并使用了 Azure OpenAI Java 客户端spring-doc.cadn.net.cn

要启用它,请将以下spring-ai-azure-openai依赖添加到项目中的Maven pom.xml文件中:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-openai</artifactId>
</dependency>

请将以下内容添加到您的Gradle build.gradle 构建文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。
The spring-ai-azure-openai 依赖也提供了对 AzureOpenAiChatModel 的访问。如需了解有关 AzureOpenAiChatModel 的更多信息,请参阅 Azure OpenAI 聊天 部分。

接下来,创建一个AzureOpenAiChatModel实例,并使用它来生成文本响应:spring-doc.cadn.net.cn

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."));
the gpt-4o 是实际上的 Deployment Name,如在 Azure AI Portal 中所展示。