Azure OpenAI

Azure OpenAI Chat

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

Azure 为 Java 开发人员提供了通过将 AI 与一系列 Azure 服务集成来充分发挥 AI 潜力的机会，其中包括与 AI 相关的资源，例如 Azure 上的 Vector Stores。

前提条件（Prerequisites）

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

Azure API Key & EndpointAzure API

若要使用 API 密钥访问模型，请从 Azure 门户 上的 Azure OpenAI 服务 获取你的 Azure OpenAI endpoint 和 api-key 。

Spring AI 定义了两个配置属性：

• spring.ai.azure.openai.api-key: 将其设置为从 Azure 获取的 API Key 的值。
• spring.ai.azure.openai.endpoint: 将此设置为在 Azure 中预配模型时获得的 endpoint URL。

可以在 application.properties 或 application.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 属性。

只找到 endpoint 属性，应用程序将评估几个不同的凭据检索选项，并使用令牌凭据创建 OpenAIClient 实例。

部署名称

要运行 Azure AI 应用程序, 需要通过 Azure AI Portal 创建一个 Azure AI Deployment .

要使用 Azure AI 应用程序，需要通过 Azure AI 门户创建 Azure AI 部署。在 Azure 中，每个客户端必须指定一个Deployment Name 来连接 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 中没有Deployment Name，只有 Model Name.

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

访问 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 添加到您的构建系统。

自动配置（Auto-configuration）

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

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

或者，在你的 Gradle 构建文件 build.gradle 中添加：

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

Azure OpenAI 聊天客户端是使用 Azure SDK 提供的 OpenAIClientBuilder 创建的。Spring AI 允许通过提供 AzureOpenAIClientBuilderCustomer Bean 来自定义构建器。

例如，可以使用自定义程序来更改默认响应超时：

@Configuration
public class AzureOpenAiConfig {

    @Bean
    public AzureOpenAIClientBuilderCustomizer responseTimeoutCustomizer() {
        return openAiClientBuilder -> {
            HttpClientOptions clientOptions = new HttpClientOptions()
                    .setResponseTimeout(Duration.ofMinutes(5));
            openAiClientBuilder.httpClient(HttpClient.createDefault(clientOptions));
        };
    }

}

聊天属性（Chat Properties）

连接属性（Connection Properties）

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

配置属性（Configuration Properties）

前缀 spring.ai.azure.openai.chat 是为 Azure OpenAI 配置 ChatModel 实现的属性前缀。

*提示: *所有 spring.ai.azure.openai.chat.options 前缀的属性， 可以在运行期间通过添加特定请求参数到 Prompt 调用 实现覆盖.

运行时选项（Runtime Options ）

Azureopenaichatoptions.java 提供模型配置，例如要使用的 temperature、maxToken、topP 等。

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

在启动时，可以使用 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()
    ));

工具 / 功能调用（Tool/Function Calling）

您可以使用 AzureOpenAiChatModel 注册自定义 Java 工具，并让 Anthropic Claude 模型智能地选择输出一个包含参数的 JSON 对象来调用一个或多个注册的函数。这是一种强大的技术，可以将 LLM 功能与外部工具和 API 连接起来。详细了解工具调用。

多模态（Multimodal ）

多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。目前，Azure OpenAI gpt-4o 模型提供多模态支持。

Azure OpenAI 可以将 base64 编码的图像或图像 URL 列表 与消息结合起来。Spring AI 的消息接口通过引入媒体类型来促进多模态 AI 模型。这种类型利用 Spring 的 org.springframework.util.MimeType 和 java.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("Explain what do you see on this picture?").media(MimeTypeUtils.IMAGE_PNG, this.url))
        .call()
        .content();

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

伴随着 “解释一下你在这张照片上看到了什么？” 的文本信息，并产生类似以下内容的回复：

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

Sample Controller

创建 一个新的 Spring Boot 项目并将其添加 spring-ai-starter-model-azure-openai 到您的 pom（或 gradle）依赖项中。

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

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-key为您的 Azure OpenAI 凭据。

这将创建一个可以注入到您的类中的 AzureOpenAiChatModel 实现。下面是一个@Controller使用聊天客户端生成文本的简单类的示例。

@RestController
public class ChatController {

    private final AzureOpenAiChatModel chatModel;
    private final StreamingChatModel streamingChatModel;

    @Autowired
    public ChatController(AzureOpenAiChatModel chatModel, StreamingChatModel streamingChatModel) {
        this.chatModel = chatModel;
        this.streamingChatModel = streamingChatModel;
    }

    @GetMapping("/ai/generate")
    @Operation(summary = "文本生成")
    public Map<String, Object> generate(@RequestParam(value = "message", defaultValue = "你好！") String message) {
        try {
            String response = chatModel.call(message);
            return Map.of(
                "success", true,
                "generation", response,
                "message", "Generated successfully"
            );
        } catch (Exception e) {
            return Map.of(
                "success", false,
                "error", e.getMessage(),
                "message", "Generation failed"
            );
        }
    }

    @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);
    }

}

手动配置（Manual Configuration）

要启用它，添加 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'
}

接下来，创建一个 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("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 门户中的 Deployment Name.