本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

Azure OpenAI Chat

Deepseek 3.2 中英对照 Azure OpenAI Azure OpenAI Chat

Azure的OpenAI服务基于ChatGPT驱动，其功能超越了传统OpenAI的能力，提供具备增强功能的AI驱动文本生成。Azure还提供额外的AI安全性和负责任AI功能，其近期更新中对此有所强调此处。

Azure为Java开发者提供了利用AI全部潜力的机会，通过将AI与一系列Azure服务集成，其中包括Azure上的矢量存储等AI相关资源。

前提条件

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

Azure API 密钥和终结点

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

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

spring.ai.azure.openai.api-key：将其设置为从 Azure 获取的 API 密钥 值。
spring.ai.azure.openai.endpoint：将其设置为在 Azure 中预配模型时获取的终结点 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 属性。

仅根据端点属性，您的应用程序将评估多种不同的凭据检索方案，并使用令牌凭据创建 OpenAIClient 实例。

备注

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

部署名称

要使用 Azure AI 应用程序，你需要通过 Azure AI 门户创建一个 Azure AI 部署。在 Azure 中，每个客户端都必须指定一个 Deployment Name 来连接到 Azure OpenAI 服务。需要注意的是，Deployment Name 与你选择部署的模型是不同的。例如，一个名为 '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.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），以确保在整个项目中使用的 Spring AI 版本保持一致。请参考依赖管理部分，将 Spring AI BOM 添加到您的构建系统中。

自动配置

备注

Spring AI 的自动配置和 starter 模块的 artifact 名称发生了重大变化。更多信息请参阅升级说明。

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 Chat Client 使用由 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-key` 或 `openai-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 聊天模型。	真
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。	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.type	兼容 `GPT-4o`、`GPT-4o mini`、`GPT-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 将在内部处理函数调用。仅适用于支持函数调用的聊天模型。	正确

:::提示
所有以 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 错误。

:::重要
参数 maxTokens 和 maxCompletionTokens 是互斥的。同时设置这两个参数将导致 Azure OpenAI API 返回错误。Spring AI Azure OpenAI 客户端会在您设置另一个参数时自动清除先前设置的参数，并伴随一条警告信息。
:::

var options = AzureOpenAiChatOptions.builder()
    .deploymentName("o1-preview")
    .maxCompletionTokens(500)  // Required for reasoning models
    .build();

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 实例，该实例可以通过 ChatOptions#builder() 创建。

函数调用

你可以向 AzureOpenAiChatModel 注册自定义的 Java 函数，并让模型智能地选择输出一个 JSON 对象，该对象包含调用一个或多个已注册函数所需的参数。这是一种强大的技术，可以将大语言模型的能力与外部工具及 API 连接起来。了解更多关于工具调用的信息。

多模态

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

Azure OpenAI 可以将一系列 base64 编码的图像或图像 URL 与消息结合使用。Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 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();

示例控制器

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

在 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-key 和 endpoint 替换为你的 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 实现了 ChatModel 和 StreamingChatModel 接口，并使用 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'
}

:::提示
请参考依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。
:::

:::提示
spring-ai-azure-openai 依赖也提供了对 AzureOpenAiChatModel 的访问权限。有关 AzureOpenAiChatModel 的更多信息，请参阅 Azure OpenAI Chat 部分。
:::

接下来，创建一个 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 门户中显示的 部署名称。

前提条件​

Azure API 密钥和终结点​

OpenAI 密钥​

Microsoft Entra ID​

部署名称​

访问 OpenAI 模型​

添加存储库和 BOM​

自动配置​

聊天属性​

令牌限制参数：模型特定使用说明​

运行时选项​

函数调用​

多模态​

示例控制器​

手动配置​