Azure OpenAI Chat

Azure 的 OpenAI 产品,由 ChatGPT 提供支持,超越了传统的 OpenAI 功能,提供了具有增强功能的 AI 驱动的文本生成。Azure 提供了额外的 AI 安全和负责任的 AI 功能,如其最近的更新中所强调 此处

Azure 为 Java 开发人员提供了将 AI 与一系列 Azure 服务集成以充分发挥其潜力的机会,其中包括 AI 相关资源,例如 Azure 上的向量存储。

先决条件

Azure OpenAI 客户端提供了三种连接选项:使用 Azure API 密钥或使用 OpenAI API 密钥,或使用 Microsoft Entra ID。

Azure API 密钥和端点

Azure 门户 上的 Azure OpenAI 服务部分获取您的 Azure OpenAI endpointapi-key

Spring AI 定义了两个配置属性

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

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

您可以通过导出环境变量来设置这些配置属性

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

OpenAI 密钥

要使用 OpenAI 服务(而非 Azure)进行身份验证,请提供 OpenAI API 密钥。这会自动将端点设置为 api.openai.com/v1

使用此方法时,请将 spring.ai.azure.openai.chat.options.deployment-name 属性设置为要使用的 OpenAI 模型 的名称。

export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY=<INSERT OPENAI KEY HERE>

Microsoft Entra ID

要使用 Microsoft Entra ID(以前称为 Azure Active Directory)进行身份验证,请在您的配置中创建一个 TokenCredential bean。如果此 bean 可用,则将使用令牌凭据创建 OpenAIClient 实例。bd === 部署名称

要使用 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 启动器及其自动配置功能的默认配置一致。如果您使用不同的部署名称,请确保相应地更新配置属性

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=<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>

添加存储库和 BOM

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

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

自动配置

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

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai-spring-boot-starter'
}
请参阅依赖项管理部分,将 Spring AI BOM 添加到您的构建文件中。

聊天属性

前缀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.azure.openai.chat是配置 Azure OpenAI 的ChatModel实现的属性前缀。

属性 描述 默认值

spring.ai.azure.openai.chat.enabled

启用 Azure OpenAI 聊天模型。

true

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

要生成的令牌的最大数量。

-

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.n

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

-

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

将结束完成生成的文本序列集合。

-

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

一个值,它会根据生成的文本中令牌的现有存在情况来影响生成的令牌出现的概率。正值将使令牌在已存在时不太可能出现,并增加模型输出新主题的可能性。

-

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

指定模型必须输出的格式的对象。使用AzureOpenAiResponseFormat.JSON启用 JSON 模式,这保证了模型生成的邮件是有效的 JSON。使用 AzureOpenAiResponseFormat.TEXT 启用 TEXT 模式。

-

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

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

-

spring.ai.azure.openai.chat.options.proxy-tool-calls

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

false

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

运行时选项

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()
            .withDeploymentName("gpt-4o")
            .withTemperature(0.4)
        .build()
    ));
除了特定于模型的AzureOpenAiChatOptions.java之外,您还可以使用可移植的ChatOptions实例,使用ChatOptionsBuilder#builder()创建。

函数调用

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

多模态

多模态是指模型同时理解和处理来自各种来源的信息的能力,包括文本、图像、音频和其他数据格式。目前,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().withDeploymentName("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

以及文本消息“解释你在这张图片上看到了什么?”,并生成如下响应

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()
    .withDeploymentName("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-azure-openai-spring-boot-starter添加到您的 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 openAIClient = new OpenAIClientBuilder()
  .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
  .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
  .buildClient();

var openAIChatOptions = AzureOpenAiChatOptions.builder()
  .withDeploymentName("gpt-4o")
  .withTemperature(0.4)
  .withMaxTokens(200)
  .build();

var chatModel = new AzureOpenAiChatModel(this.openAIClient, this.openAIChatOptions);

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

// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
  new Prompt("Generate the names of 5 famous pirates."));
gpt-4o实际上是 Azure AI 门户中显示的“部署名称”。