28_Spring AI 干货笔记之 OpenAI 聊天功能 - 详解

一、OpenAI 聊天功能

Spring AI 支持来自 OpenAI（ChatGPT 背后的公司）的各种 AI 语言模型。OpenAI 通过创建行业领先的文本生成模型和嵌入技术，极大地推动了人们对 AI 驱动文本生成的兴趣。

二、先决条件

您需要在 OpenAI 创建一个 API 来访问 ChatGPT 模型。

在 OpenAI 注册页面创建账户。
在 API 密钥页面生成令牌。

Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，您应将其设置为从 openai.com 获取的 API 密钥值。

您可以在 application.properties 文件中设置此配置属性：

spring.ai.openai.api-key=<your-openai-api-key>

为了在处理敏感信息（如 API 密钥）时增强安全性，您可以使用 Spring 表达式语言（SpEL）来引用自定义环境变量：

# 在 application.yml 中
spring:
ai:
openai:
api-key: ${
OPENAI_API_KEY}

# 在您的环境或 .env 文件中
export OPENAI_API_KEY=<your-openai-api-key>

您也可以在应用程序代码中以编程方式设置此配置：

// 从安全源或环境变量检索 API 密钥
String apiKey = System.getenv("OPENAI_API_KEY");

2.1 添加仓库和 BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅工件仓库部分，将这些仓库添加到您的构建系统中。

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

三、自动配置

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

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

Maven

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

Gradle

dependencies {

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

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

3.1 聊天属性

3.1.1 重试属性

前缀 spring.ai.retry 用作属性前缀，用于配置 OpenAI 聊天模型的重试机制。
在这里插入图片描述

3.1.2 连接属性

前缀 spring.ai.openai 用作属性前缀，用于连接到 OpenAI。
在这里插入图片描述

对于属于多个组织的用户（或通过其旧版用户 API 密钥访问其项目），您可以有选择地指定哪个组织和项目用于 API 请求。来自这些 API 请求的使用量将计入指定组织和项目的使用量。

3.1.3 User-Agent 头

Spring AI 会自动向 OpenAI 的所有请求发送 User-Agent: spring-ai 头。这有助于 OpenAI 识别来自 Spring AI 的请求，以进行分析和支持。此头会自动发送，Spring AI 用户无需配置。

如果您是构建 OpenAI 兼容服务的 API 提供商，可以通过读取服务器上传入请求的 User-Agent HTTP 头来跟踪 Spring AI 的使用情况。

3.1.4 配置属性

聊天自动配置的启用和禁用现在通过顶级属性 spring.ai.model.chat 前缀进行配置。
要启用：spring.ai.model.chat=openai（默认启用）
要禁用：spring.ai.model.chat=none（或任何与 openai 不匹配的值）
进行此更改是为了允许配置多个模型。

前缀 spring.ai.openai.chat 是用于配置 OpenAI 聊天模型实现的属性前缀。
在这里插入图片描述

当使用 GPT-5 模型（如 gpt-5、gpt-5-mini 和 gpt-5-nano）时，不支持 temperature 参数。这些模型为推理进行了优化，不使用温度。指定温度值将导致错误。相比之下，对话模型如 gpt-5-chat 支持 temperature 参数。

您可以为 ChatModel 和 EmbeddingModel 实现覆盖通用的 spring.ai.openai.base-url 和 spring.ai.openai.api-key。如果设置了 spring.ai.openai.chat.base-url 和 spring.ai.openai.chat.api-key 属性，则它们优先于通用属性。如果您想为不同模型和不同模型端点使用不同的 OpenAI 账户，这会很有用。

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

3.2 标记限制参数：特定于模型的用法

OpenAI 提供了两个互斥的参数来控制标记生成限制：
在这里插入图片描述

这些参数是互斥的。同时设置两者将导致来自 OpenAI 的 API 错误。

3.2.1 使用示例

对于非推理模型（gpt-4o、gpt-3.5-turbo）：

ChatResponse response = chatModel.call(
new Prompt(
"用简单的术语解释量子计算。",
OpenAiChatOptions.builder()
.model("gpt-4o")
.maxTokens(150)  // 对于非推理模型使用 maxTokens
.build()
));

对于推理模型（o1、o3 系列）：

ChatResponse response = chatModel.call(
new Prompt(
"逐步解决这个复杂的数学问题：...",
OpenAiChatOptions.builder()
.model("o1-preview")
.maxCompletionTokens(1000)  // 对于推理模型使用 maxCompletionTokens
.build()
));

构建器模式验证： OpenAI ChatOptions 构建器自动通过“最后设置优先”的方法强制执行互斥性：

// 这将自动清除 maxTokens 并使用 maxCompletionTokens
OpenAiChatOptions options = OpenAiChatOptions.builder()
.maxTokens(100)           // 先设置
.maxCompletionTokens(200) // 这将清除 maxTokens 并记录警告
.build();
// 结果：maxTokens = null, maxCompletionTokens = 200

四、运行时选项

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

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

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

ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OpenAiChatOptions.builder()
.model("gpt-4o")
.temperature(0.4)
.build()
));

除了特定于模型的 OpenAiChatOptions，您还可以使用可移植的 ChatOptions 实例，通过 ChatOptions#builder() 创建。

五、函数调用

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

六、多模态

多模态性是指模型能够同时理解和处理来自各种来源的信息，包括文本、图像、音频和其他数据格式。OpenAI 支持文本、视觉和音频输入模态。

6.1 视觉

支持视觉多模态的 OpenAI 模型包括 gpt-4、gpt-4o 和 gpt-4o-mini。更多信息请参阅视觉指南。

OpenAI 用户消息 API 可以在消息中包含 base64 编码的图像或图像 URL 列表。Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型的使用。此类型包含消息中媒体附件的数据和详细信息，利用 Spring 的 org.springframework.util.MimeType 和 org.springframework.core.io.Resource 来处理原始媒体数据。

以下是摘录自 OpenAiChatModelIT.java 的代码示例，说明了用户文本与图像的融合，使用 gpt-4o 模型：

var imageResource = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage("解释一下你在这张图片上看到了什么？",
new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));
ChatResponse response = chatModel.call(new Prompt(this.userMessage,
OpenAiChatOptions.builder().model(OpenAiApi.ChatModel.GPT_4_O.getValue()).build()));

GPT_4_VISION_PREVIEW 将从 2024 年 6 月 17 日起仅继续向该模型的现有用户提供。如果您不是现有用户，请使用 GPT_4_O 或 GPT_4_TURBO 模型。更多细节

或使用图像 URL 的等效方式，使用 gpt-4o 模型：

var userMessage = new UserMessage("解释一下你在这张图片上看到了什么？",
new Media(MimeTypeUtils.IMAGE_PNG,
URI.create("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png")));
ChatResponse response = chatModel.call(new

posted @ 2026-01-07 13:17 clnchanpin 阅读(51) 评论(0) 收藏举报

刷新页面返回顶部