Azure OpenAI Chat

  • 提供了自动配置和手动配置 AzureOpenAiChatClient 的选项，该选项支持模型配置和强大的函数调用功能。

Azure 的 OpenAI 产品由 ChatGPT 提供支持，它的功能超越了传统 OpenAI 的能力，提供具有增强功能的 AI 驱动的文本生成。Azure 提供了额外的 AI 安全和负责任的 AI 功能，如其最近的更新 here 中所强调的那样。 Azure 为 Java 开发人员提供了将人工智能与其一系列 Azure 服务（包括 Azure 上的 Vector Store 等与人工智能相关的资源）集成在一起，从而充分利用人工智能潜力的机会。

Prerequisites

从 Azure Portal 上的 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。导出环境变量是设置这些配置属性的一种方法：

export SPRING_AI_AZURE_OPENAI_API_KEY=<INSERT KEY HERE>
export SPRING_AI_AZURE_OPENAI_ENDPOINT=<INSERT ENDPOINT URL HERE>

Deployment Name

若要使用运行 Azure AI 应用程序，请通过 [Azure AI 门户]([role="bare"][role="bare"]https://oai.azure.com/portal) 创建一个 Azure AI 部署。

在 Azure 中，每个客户端必须指定一个 Deployment Name 才能连接到 Azure OpenAI 服务。

了解 Deployment Name 与您选择部署的模型不同非常重要。

例如，名为 MyAiDeployment 的部署可以配置为使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。

现在，为了简化起见，您可以使用以下设置创建部署：

Deployment Name: gpt-35-turbo Model Name: gpt-35-turbo

此 Azure 配置将与 Spring Boot Azure AI Starter 及其自动配置功能的默认配置保持一致。

如果您使用不同的部署名称，请相应地更新配置属性：

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

Azure OpenAI 和 OpenAI 不同的部署结构导致 Azure OpenAI 客户端库中的一个属性名为 deploymentOrModelName。这是因为在 OpenAI 中没有“部署名称”，只有“模型名称”。

Spring AI 将在后续版本中将属性 spring.ai.azure.openai.chat.options.model 重命名为 spring.ai.azure.openai.chat.options.deployment-name 以避免混淆。

Add Repositories and BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 存储库中。有关将这些存储库添加到你的构建系统的说明，请参阅 Repositories 部分。

为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。有关将 Spring AI BOM 添加到你的构建系统的说明，请参阅 Dependency Management 部分。

Auto-configuration

Spring AI 为 Azure OpenAI Chat 客户端提供 Spring Boot 自动配置。若要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：

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

或添加到 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai-spring-boot-starter'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Chat Properties

前缀 spring.ai.azure.openai 是用于配置与 Azure OpenAI 连接的属性前缀。

Property Description Default

spring.ai.azure.openai.api-key

Azure AI OpenAI 下 Keys and Endpoint 部分中的密钥 Resource Management

-

spring.ai.azure.openai.endpoint

Azure AI OpenAI 下 Keys and Endpoint 部分中的端点 Resource Management

-

前缀 spring.ai.azure.openai.chat 是配置适用于 Azure OpenAI 的 ChatClient 实现的属性前缀。

Property Description Default

spring.ai.azure.openai.chat.enabled

启用 Azure OpenAI 聊天客户端。

true

spring.ai.azure.openai.chat.options.deployment-name

* 在与 Azure 配合使用时，这指代模型的“部署名称”，可在 [role="bare"][role="bare"]https://oai.azure.com/portal中找到它。请务必注意，在 Azure OpenAI 部署中，“部署名称”不同于模型本身。围绕这些术语的混淆源于让 Azure OpenAI 客户端库与原始 OpenAI 端点兼容的意图。Azure OpenAI 和 Sam Altman 的 OpenAI 提供的部署结构差异很大。作为此完成功能一部分提供的部署模型名称。

gpt-35-turbo

spring.ai.azure.openai.chat.options.maxTokens

要生成的令牌数最大值。

-

spring.ai.azure.openai.chat.options.temperature

用于控制生成完成内容的明显创造力的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中，更确定。不建议为同一个补全请求修改 temperature and 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.n

应该为聊天完成响应生成的聊天完成选择的数量。

-

spring.ai.azure.openai.chat.options.stop

一系列文本序列，它将结束完成生成。

-

spring.ai.azure.openai.chat.options.presencePenalty

一个值，基于已生成文本中的现有内容，影响已生成标记出现的概率。正值将使标记在已经存在的情况下不太可能出现，并增加模型输出新主题的可能性。

-

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

一个值，基于已生成文本中累积频率，影响已生成标记出现的概率。正值会随着标记频率的增加而使标记不太可能出现，并降低模型逐字重复相同语句的可能性。

-

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

Chat Options

AzureOpenAiChatOptions.java 提供模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可以使用 AzureOpenAiChatClient(api, options) 构造函数或 spring.ai.azure.openai.chat.options.* 属性配置默认选项。

在运行时，可以通过向 Prompt 调用添加新的请求特定选项来覆盖默认选项。例如，覆盖特定请求的默认模型和温度：

ChatResponse response = chatClient.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        AzureOpenAiChatOptions.builder()
            .withModel("gpt-4-32k")
            .withTemperature(0.4)
        .build()
    ));

  1. 除了模型特定的 AzureOpenAiChatOptions.java 之外，你还可以使用用 ChatOptionsBuilder#builder() 创建的便携式 ChatOptions 实例。

Function Calling

您可以使用 AzureOpenAiChatClient 注册自定义 Java 函数，并让模型智能地选择输出一个 JSON 对象，其中包含调用其中一个或多个已注册函数的参数。这是一种将 LLM 能力与外部工具和 API 相连接的强大技术。阅读有关 Azure OpenAI Function Calling 的更多信息。

Sample Controller (Auto-configuration)

Create 一个新的 Spring Boot 项目，并将 spring-ai-azure-openai-spring-boot-starter 添加到你的 pom（或 gradle）依赖项。

在 src/main/resources 目录下添加一个 application.properties 文件，以启用和配置 OpenAI Chat 客户端：

spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.openai.chat.options.model=gpt-35-turbo
spring.ai.azure.openai.chat.options.temperature=0.7

将 api-key 和 endpoint 替换为您的 Azure OpenAI 凭据。

这样会创建可以注入到类中的 AzureOpenAiChatClient 实现。这是一个简单的 @Controller 类示例，它将聊天客户端用于文本生成。

@RestController
public class ChatController {

    private final AzureOpenAiChatClient chatClient;

    @Autowired
    public ChatController(AzureOpenAiChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", chatClient.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 chatClient.stream(prompt);
    }
}

Manual Configuration

AzureOpenAiChatClient 实现 ChatClient 和 StreamingChatClient，并使用 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 build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

  1. spring-ai-azure-openai 依赖还提供了对 AzureOpenAiChatClient 的访问。有关 AzureOpenAiChatClient 的更多信息，请参阅 Azure OpenAI Chat 部分。

接下来，创建一个 AzureOpenAiChatClient 实例并使用它生成文本响应：

var openAIClient = OpenAIClientBuilder()
        .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
		.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
		.buildClient();

var chatClient = new AzureOpenAiChatClient(openAIClient).withDefaultOptions(
		AzureOpenAiChatOptions.builder()
            .withModel("gpt-35-turbo")
            .withTemperature(0.4)
            .withMaxTokens(200)
        .build());

ChatResponse response = chatClient.call(
    new Prompt("Generate the names of 5 famous pirates."));

// Or with streaming responses
Flux<ChatResponse> response = chatClient.stream(
    new Prompt("Generate the names of 5 famous pirates."));

gpt-35-turbo 实际上是 Deployment Name，正如 Azure AI 门户中显示的那样。