Azure OpenAI Chat

Azure的OpenAI产品由ChatGPT驱动,超越了传统OpenAI能力,提供增强功能的AI文本生成。Azure 提供了额外的 AI 安全和负责任的 AI 功能,正如他们最近的更新中所强调的。spring-doc.cadn.net.cn

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

前提条件

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

Azure API Key & Endpoint

要使用API密钥访问模型,请获取您的Azure OpenAI端点API密钥来自Azure Portal的Azure OpenAI服务部分。spring-doc.cadn.net.cn

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

  1. Spring.ai.Azure.Openai.API-Key:将此设为API 密钥摘自Azure。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)进行无密钥认证,Spring.ai.azure.openai.endpoint配置属性,而不是上述提到的API-key属性。spring-doc.cadn.net.cn

仅找到端点属性后,你的应用程序将评估多种获取凭证和OpenAIClient实例将使用Tokens凭证创建。spring-doc.cadn.net.cn

不再需要创建一个Tokens凭证豆;它是自动为你配置的。

部署名称

要使用 Azure AI 应用,你需要通过 Azure AI 门户创建一个 Azure AI 部署。 在Azure中,每个客户端必须指定一个部署名称连接 Azure OpenAI 服务。 需要注意的是部署名称与你选择部署的模型不同。 例如,名为“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中没有部署名称,仅为a型号名称.spring-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

添加仓库和物料清单

Spring AI 产物发布于 Maven Central 和 Spring Snapshot 仓库中。 请参阅神器仓库部分,将这些仓库添加到你的构建系统中。spring-doc.cadn.net.cn

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

自动配置

春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明spring-doc.cadn.net.cn

Spring AI 为 Azure OpenAI 聊天客户端提供 Spring Boot 自动配置。 要启用它,请在项目的Maven中添加以下依赖pom.xml或者Gradlebuild.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的物料清单添加到你的构建文件中。

Azure OpenAI 聊天客户端是使用 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

属性 描述 默认值

Spring.ai.Azure.Openai.API-Keyspring-doc.cadn.net.cn

Azure AI OpenAI 的密钥密钥与端点部分资源管理spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

Azure AI OpenAI 的端点密钥与端点部分资源管理spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

(非青色)OpenAI API 密钥。用来通过OpenAI服务认证,而不是Azure OpenAI。 这会自动将端点设置为 api.openai.com/v1。使用任一API密钥OpenAI-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

属性 描述 默认值

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

采样温度决定了生成完备的显得创造力。值越高,输出越随机,值越低,结果越聚焦且确定性强。不建议对相同的完井请求调整温度和top_p,因为这两种设置的相互作用难以预测。spring-doc.cadn.net.cn

0.7spring-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

一个将GPTTokensID与偏见评分之间的映射,影响完成回复中特定Tokens出现的概率。TokensID通过外部标记工具计算,而偏差分数则在-100到100之间,最低和最大分别对应完全禁用或独占选择某个Tokens。给定偏差分数的具体行为因模型而异。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

(仅限流媒体)设置为为整个请求添加一个包含Tokens使用统计的额外区块。 这选择该块的字段是空数组,其他块也会包含使用字段,但为空值。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-4o,GPT-4o 迷你版,GPT-4 涡轮以及所有GPT-3.5 涡轮GPT-3.5-涡轮-1106. 这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

这是一个根据生成词在生成文本中累计频率影响生成词出现概率的数值。正值会使词符出现的可能性降低,随着词语频率增加,模型重复相同陈述的可能性降低。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

工具回调以注册到聊天模型。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

如果为 false,Spring AI 不会在内部处理工具调用,而是代理到客户端。然后由客户端负责处理工具调用,将其派遣到相应函数,并返回结果。如果为真(默认为真),Spring AI 会在内部处理函数调用。仅适用于支持函数调用的聊天模型spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

所有以spring.ai.azure.openai.chat.options可以通过在运行时为 在提示叫。

Tokens限制参数:特定型号使用情况

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();

运行时选项

AzureOpenAiChatOptions.java提供模型配置,如所用模型、温度、频率惩罚等。spring-doc.cadn.net.cn

启动时,默认选项可以配置为AzureOpenAiChatModel(api, options)构造者或spring.ai.azure.openai.chat.options.*性能。spring-doc.cadn.net.cn

运行时,你可以通过添加新的、针对请求的选项来覆盖默认选项提示叫。 例如,针对特定请求覆盖默认型号和温度: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#builder()创建的便携式ChatOptions实例。

函数调用

你可以用 AzureOpenAiChatModel 注册自定义 Java 函数,并让模型智能地选择输出包含参数的 JSON 对象,调用一个或多个注册函数。 这是一种强大的技术,将LLM功能与外部工具和API连接起来。 阅读更多关于工具调用的信息。spring-doc.cadn.net.cn

模 态

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

Azure OpenAI 可以包含包含 base64 编码的图片或图片 URL 列表。 Spring AI 的 Message 界面通过引入媒体类型,促进了多模态 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

多模态测试图像

并附上短信“请解释你在这张图片上看到了什么?”,并生成如下回复: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 项目并添加Spring-ai-starter-model-azure-openai对你的POM(或Gradle)依赖。spring-doc.cadn.net.cn

添加一个application.properties文件,在src/主/资源目录,用于启用和配置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密钥端点用你的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);
    }
}

手动配置

AzureOpenAiChatModel 实现了聊天模型StreamingChatModel并使用 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>

或者去你的Gradlebuild.gradle构建文件。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}
请参考依赖管理部分,将Spring AI的物料清单添加到你的构建文件中。
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."));
GPT-4O实际上是部署名称如Azure AI门户所示。