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

Azure 为 Java 开发人员提供了通过将其与一系列 Azure 服务(包括 Azure 上的向量存储等 AI 相关资源)集成来充分利用 AI 潜力的机会。

前提条件

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

Azure API 密钥和终结点

要使用 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。

你可以在 application.propertiesapplication.yml 文件中设置这些配置属性:

spring.ai.azure.openai.api-key=<你的-azure-api-密钥>
spring.ai.azure.openai.endpoint=<你的-azure-终结点-url>

OpenAI 密钥

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

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

在你的应用程序配置中:

spring.ai.azure.openai.openai-api-key=<你的-azure-openai-密钥>
spring.ai.azure.openai.chat.options.deployment-name=<openai-模型名称>

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 中,每个客户端都必须指定一个 Deployment Name 才能连接到 Azure OpenAI 服务。 需要注意的是,Deployment Name 与你选择部署的模型不同。 例如,名为”MyAiDeployment”的部署可以配置为使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。

要开始使用,请按照以下步骤使用默认设置创建部署:

部署名称:gpt-4o 模型名称:gpt-4o

此 Azure 配置与 Spring Boot Azure AI Starter 及其自动配置功能的默认配置一致。 如果你使用不同的部署名称,请确保相应地更新配置属性:

spring.ai.azure.openai.chat.options.deployment-name=<我的部署名称>

Azure OpenAI 和 OpenAI 的不同部署结构导致 Azure OpenAI 客户端库中有一个名为 deploymentOrModelName 的属性。 这是因为在 OpenAI 中没有 Deployment Name,只有 Model Name

属性 spring.ai.azure.openai.chat.options.model 已重命名为 spring.ai.azure.openai.chat.options.deployment-name

如果你决定通过设置 spring.ai.azure.openai.openai-api-key=<你的 OpenAI 密钥> 属性来连接到 OpenAI 而不是 Azure 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 (bill of materials),以确保在整个项目中使用一致版本的 Spring AI。请参阅依赖管理部分,将 Spring AI BOM 添加到你的构建系统中。

自动配置

Spring AI 自动配置、启动器模块的构件名称发生了重大变化。 有关更多信息,请参阅升级说明

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

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

请参阅依赖管理部分,将 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-keyAzure AI OpenAI 密钥和终结点 部分(在 资源管理 下)中的密钥-
spring.ai.azure.openai.endpointAzure AI OpenAI 密钥和终结点 部分(在 资源管理 下)中的终结点-
spring.ai.azure.openai.openai-api-key(非 Azure)OpenAI API 密钥。用于向 OpenAI 服务(而非 Azure OpenAI)进行身份验证。这会自动将终结点设置为 https://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 中使用时,这指的是模型的”部署名称”,你可以在 https://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.logitBiasGPT 令牌 ID 和偏差分数之间的映射,影响特定令牌出现在补全响应中的概率。令牌 ID 通过外部令牌化工具计算,而偏差分数在 -100 到 100 的范围内,最小值和最大值分别对应于完全禁止或独占选择令牌。给定偏差分数的具体行为因模型而异。-
spring.ai.azure.openai.chat.options.user操作的调用方或最终用户的标识符。这可用于跟踪或速率限制目的。-
spring.ai.azure.openai.chat.options.stream-usage(仅限流式传输)设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 choices 字段是一个空数组,所有其他块也将包含一个 usage 字段,但其值为 null。false
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(
        "生成 5 个著名海盗的名字。",
        AzureOpenAiChatOptions.builder()
            .deploymentName("gpt-4o")
            .temperature(0.4)
        .build()
    ));

除了特定于模型的 AzureOpenAiChatOptions之外,你还可以使用通过 ChatOptionsBuilder#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.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("解释一下你在这张图片上看到了什么?").media(MimeTypeUtils.IMAGE_PNG, this.url))
        .call()
        .content();

你也可以传递多个图像。

它将 multimodal.test.png 图像作为输入:

多模态测试图像

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

这是一张水果盘的图片,设计简单。碗由金属制成,带有弯曲的金属丝边缘,
形成开放式结构,可以从各个角度看到水果。碗里,两根香蕉放在一个看起来像是红苹果的水果上面。
香蕉有点过熟,表皮上有褐色的斑点。碗的顶部有一个金属环,可能是用来提携的。
碗放在一个平坦的表面上,背景颜色中性,可以清楚地看到里面的水果。

你也可以传入类路径资源而不是 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("解释一下你在这张图片上看到了什么?")
    .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=你的API密钥
spring.ai.azure.openai.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 = "给我讲个笑话") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") 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-4o")
  .temperature(0.4)
  .maxTokens(200)
  .build();

var chatModel = AzureOpenAiChatModel.builder()
                .openAIClientBuilder(openAIClientBuilder)
                .defaultOptions(openAIChatOptions)
                .build();

ChatResponse response = chatModel.call(
  new Prompt("生成 5 个著名海盗的名字。"));

// 或使用流式响应
Flux<ChatResponse> streamingResponses = chatModel.stream(
  new Prompt("生成 5 个著名海盗的名字。"));

gpt-4o 实际上是 Azure AI 门户中显示的部署名称

文档有误?请协助编辑

发现文档问题?点击此处直接在 GitHub 上编辑并提交 PR,帮助我们改进文档!