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 终结点api-key

Spring AI 定义了两个配置属性

  1. spring.ai.azure.openai.api-key:将其设置为从 Azure 获取的API 密钥的值。

  2. spring.ai.azure.openai.endpoint:将其设置为在 Azure 中预配模型时获取的终结点 URL。

您可以在application.propertiesapplication.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实例。

不再需要创建TokenCredential bean;它已为您自动配置。

部署名称

要使用 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 中没有部署名称,只有模型名称

属性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=<您的 OpenAI 密钥>属性,那么spring.ai.azure.openai.chat.options.deployment-name将被视为 OpenAI 模型名称。

访问 OpenAI 模型

您可以配置客户端直接使用OpenAI而不是Azure OpenAI部署的模型。为此,您需要设置spring.ai.azure.openai.openai-api-key=<您的 OpenAI 密钥>,而不是spring.ai.azure.openai.api-key=<您的 Azure OpenAi 密钥>

添加存储库和 BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。请参阅 工件存储库 部分,将这些存储库添加到您的构建系统。

为了帮助管理依赖项,Spring AI 提供了一个 BOM(物料清单),以确保在整个项目中使用的 Spring AI 版本一致。请参阅 依赖项管理 部分,将 Spring AI BOM 添加到您的构建系统。

自动配置

Spring AI 自动配置、启动模块的工件名称发生了重大变化。请参阅 升级说明 以获取更多信息。

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。使用api-keyopenai-api-key属性。在此配置下,spring.ai.azure.openai.chat.options.deployment-name被视为 OpenAI 模型名称。

-

spring.ai.azure.openai.custom-headers

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

空映射

聊天自动配置的启用和禁用现在通过以spring.ai.model.chat为前缀的顶级属性进行配置。

要启用,请设置 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

用于控制生成完成的明显创造性的采样温度。较高的值将使输出更随机,而较低的值将使结果更集中和确定。不建议在同一完成请求中修改温度和 top_p,因为这两个设置的相互作用难以预测。

0.7

spring.ai.azure.openai.chat.options.topP

一种替代温度采样的核采样方法。此值使模型考虑具有所提供概率质量的令牌结果。

-

spring.ai.azure.openai.chat.options.logitBias

GPT 令牌 ID 和偏差分数之间的映射,它影响特定令牌出现在完成响应中的概率。令牌 ID 通过外部分词工具计算,而偏差分数介于 -100 到 100 之间,最小值和最大值分别对应于完全禁止或独占选择令牌。给定偏差分数的精确行为因模型而异。

-

spring.ai.azure.openai.chat.options.user

操作的调用者或最终用户的标识符。这可能用于跟踪或速率限制目的。

-

spring.ai.azure.openai.chat.options.stream-usage

(仅限流式传输)设置为添加一个额外的块,其中包含整个请求的令牌使用统计信息。此块的choices字段是一个空数组,所有其他块也将包含一个 usage 字段,但值为 null。

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

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

-

spring.ai.azure.openai.chat.options.responseFormat.schema

响应格式 JSON 模式。仅适用于responseFormat.type=JSON_SCHEMA

-

spring.ai.azure.openai.chat.options.frequencyPenalty

一个值,根据生成文本中生成令牌的累积频率来影响其出现的概率。正值会使令牌在频率增加时更不可能出现,并降低模型重复相同语句的可能性。

-

spring.ai.azure.openai.chat.options.tool-names

工具列表,通过其名称标识,用于在单个提示请求中启用函数调用。具有这些名称的工具必须存在于 ToolCallback 注册表中。

-

spring.ai.azure.openai.chat.options.tool-callbacks

要注册到 ChatModel 的工具回调。

-

spring.ai.azure.openai.chat.options.internal-tool-execution-enabled

如果为 false,Spring AI 将不会在内部处理工具调用,而是将其代理到客户端。然后,客户端负责处理工具调用,将其分派到适当的函数,并返回结果。如果为 true(默认),Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型

true

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

令牌限制参数:模型特定用法

Azure OpenAI 对令牌限制参数有模型特定的要求

模型家族 所需参数 备注

推理模型
(o1, o3, o4-mini 系列)

maxCompletionTokens

这些模型只接受maxCompletionTokens。使用maxTokens将导致 API 错误。

非推理模型
(gpt-4o, gpt-3.5-turbo 等)

maxTokens

传统模型使用maxTokens进行输出限制。使用maxCompletionTokens可能会导致 API 错误。

参数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 提供了模型配置,例如要使用的模型、温度、频率惩罚等。

在启动时,可以使用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 OpenAI 的gpt-4o模型提供多模态支持。

Azure OpenAI 可以将 base64 编码图像或图像 URL 列表与消息一起包含。Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。此类型包含消息中媒体附件的数据和详细信息,使用 Spring 的org.springframework.util.MimeTypejava.lang.Object作为原始媒体数据。

下面是摘自 OpenAiChatModelIT.java 的代码示例,展示了使用GPT_4_O模型将用户文本与图像融合。

URL url = new URL("https://docs.springframework.org.cn/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图像作为输入

Multimodal Test Image

以及文本消息“Explain what do you see on this picture?”,并生成如下响应

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)依赖项中。

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-keyendpoint替换为您的 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 实现了ChatModelStreamingChatModel,并使用 Azure OpenAI Java 客户端

要启用它,请将spring-ai-azure-openai依赖项添加到您的项目的 Maven pom.xml 文件中

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

或添加到您的 Gradle build.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实际上是 Azure AI 门户中显示的部署名称
© . This site is unofficial and not affiliated with VMware.