OpenAI 聊天
Spring AI 支持来自 OpenAI 的各种 AI 语言模型，OpenAI 是 ChatGPT 背后的公司，由于其创建了行业领先的文本生成模型和嵌入，该公司在激发人们对 AI 驱动的文本生成的兴趣方面发挥了重要作用。
先决条件
您需要使用 OpenAI 创建一个 API 才能访问 ChatGPT 模型。
在 OpenAI 注册页面创建一个帐户，并在 API 密钥页面上生成令牌。
Spring AI 项目定义了一个名为spring.ai.openai.api-key，您应该设置为API Key从 openai.com 获得。
导出环境变量是设置该配置属性的一种方法：
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>添加存储库和 BOM
Spring AI 工件发布在 Spring Milestone 和 Snapshot 存储库中。 请参阅 Repositories 部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致的 Spring AI 版本。请参阅依赖项管理部分，将 Spring AI BOM 添加到您的构建系统中。
自动配置
Spring AI 为 OpenAI Chat 客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven 中pom.xml或 Gradlebuild.gradlebuild 文件：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}| 请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。 |
聊天属性
重试属性
前缀spring.ai.retry用作属性前缀，允许您为 OpenAI 聊天模型配置重试机制。
| 财产 | 描述 | 违约 |
|---|---|---|
spring.ai.retry.max 次尝试 |
最大重试尝试次数。 |
10 |
spring.ai.retry.backoff.initial-interval |
指数回退策略的初始休眠持续时间。 |
2 秒 |
spring.ai.retry.backoff.multiplier |
Backoff interval 乘数。 |
5 |
spring.ai.retry.backoff.max 间隔 |
最大回退持续时间。 |
3 分钟 |
spring.ai.retry.on-client-errors |
如果为 false，则抛出 NonTransientAiException，并且不要尝试重试 |
假 |
spring.ai.retry.exclude-on-http-codes |
不应触发重试的 HTTP 状态代码列表（例如，引发 NonTransientAiException）。 |
空 |
spring.ai.retry.on-http-codes |
应触发重试的 HTTP 状态代码列表（例如，引发 TransientAiException）。 |
空 |
连接属性
前缀spring.ai.openai用作允许您连接到 OpenAI 的属性前缀。
| 财产 | 描述 | 违约 |
|---|---|---|
spring.ai.openai.base-url |
要连接到的 URL |
|
spring.ai.openai.api-key |
API 密钥 |
- |
spring.ai.openai.organization-id |
（可选）您可以指定要用于 API 请求的组织。 |
- |
spring.ai.openai.project-id |
（可选）您可以指定要用于 API 请求的项目。 |
- |
| 对于属于多个组织（或通过其旧版用户 API 密钥访问其项目）的用户，您可以选择指定用于 API 请求的组织和项目。 这些 API 请求的使用量将计为指定组织和项目的使用量。 |
配置属性
前缀spring.ai.openai.chat是允许您为 OpenAI 配置聊天模型实现的属性前缀。
| 财产 | 描述 | 违约 |
|---|---|---|
spring.ai.openai.chat.enabled |
启用 OpenAI 聊天模型。 |
真 |
spring.ai.openai.chat.base-url |
的可选覆盖 |
- |
spring.ai.openai.chat.completions-path |
要追加到基本 URL 的路径。 |
|
spring.ai.openai.chat.api-key |
的可选覆盖 |
- |
spring.ai.openai.chat.organization-id |
（可选）您可以指定要用于 API 请求的组织。 |
- |
spring.ai.openai.chat.project-id |
（可选）您可以指定要用于 API 请求的项目。 |
- |
spring.ai.openai.chat.options.model |
要使用的 OpenAI 聊天模型的名称。您可以选择以下模型： |
|
spring.ai.openai.chat.options.temperature |
要使用的采样温度，用于控制生成的完成项的明显创造性。较高的值将使输出更具随机性，而较低的值将使结果更加集中和确定。不建议修改 |
0.8 |
spring.ai.openai.chat.options.frequencyPenalty |
介于 -2.0 和 2.0 之间的数字。正值会根据新标记到目前为止在文本中的现有频率来惩罚新标记，从而降低模型逐字重复同一行的可能性。 |
0.0 英尺 |
spring.ai.openai.chat.options.logitBias |
修改指定标记出现在补全中的可能性。 |
- |
spring.ai.openai.chat.options.max代币 |
（已弃用，取而代之的是 |
- |
spring.ai.openai.chat.options.maxCompletionTokens |
可以为完成生成的标记数的上限，包括可见的输出标记和推理标记。 |
- |
spring.ai.openai.chat.options.n |
为每个输入消息生成多少个聊天完成选项。请注意，您将根据所有选项中生成的令牌数量付费。保持 |
1 |
spring.ai.openai.chat.options.output-modalities |
您希望模型为此请求生成的 Output types。大多数模型都能够生成文本，这是默认设置。
这 |
- |
spring.ai.openai.chat.options.output-audio |
音频生成的音频参数。当请求音频输出时是必需的 |
- |
spring.ai.openai.chat.options.presencePenalty |
介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止是否出现在文本中来惩罚新标记，从而增加模型讨论新主题的可能性。 |
- |
spring.ai.openai.chat.options.responseFormat.type |
兼容 |
- |
spring.ai.openai.chat.options.responseFormat.name |
响应格式架构名称。仅适用于 |
custom_schema |
spring.ai.openai.chat.options.responseFormat.schema |
响应格式 JSON 架构。仅适用于 |
- |
spring.ai.openai.chat.options.responseFormat.strict |
响应格式 JSON 架构遵守严格性。仅适用于 |
- |
spring.ai.openai.chat.options.seed |
此功能处于 Beta 阶段。如果指定，我们的系统将尽最大努力确定性地采样，以便具有相同种子和参数的重复请求应返回相同的结果。 |
- |
spring.ai.openai.chat.options.stop |
最多 4 个序列，API 将在其中停止生成更多令牌。 |
- |
spring.ai.openai.chat.options.topP |
使用温度采样的替代方法，称为核采样，其中模型考虑具有 |
- |
spring.ai.openai.chat.options.tools |
模型可以调用的工具列表。目前，仅支持将函数作为工具。使用此选项可提供模型可能为其生成 JSON 输入的函数列表。 |
- |
spring.ai.openai.chat.options.toolChoice |
控制模型调用哪个 （如果有） 函数。 |
- |
spring.ai.openai.chat.options.user |
代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。 |
- |
spring.ai.openai.chat.options.functions |
函数列表，由其名称标识，用于在单个提示请求中启用函数调用。具有这些名称的函数必须存在于 |
- |
spring.ai.openai.chat.options.stream-usage |
（仅用于流媒体）设置为添加一个额外的数据块，其中包含整个请求的令牌使用情况统计信息。这 |
假 |
spring.ai.openai.chat.options.parallel-tool-calls |
是否在工具使用过程中启用并行函数调用。 |
真 |
spring.ai.openai.chat.options.http-headers |
要添加到聊天完成请求的可选 HTTP 标头。要覆盖 |
- |
spring.ai.openai.chat.options.proxy-tool-calls |
如果为true，则 Spring AI 不会在内部处理函数调用，而是将它们代理给客户端。然后，客户端负责处理函数调用，将它们分派给适当的函数，并返回结果。如果为false（默认值），则 Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型 |
假 |
您可以覆盖常见的spring.ai.openai.base-url和spring.ai.openai.api-key对于ChatModel和EmbeddingModel实现。
这spring.ai.openai.chat.base-url和spring.ai.openai.chat.api-key属性（如果已设置）优先于公共属性。
如果您想为不同的模型和不同的模型终端节点使用不同的 OpenAI 账户，这将非常有用。 |
所有前缀为spring.ai.openai.chat.options可以通过将特定于请求的运行时选项添加到Prompt叫。 |
运行时选项
OpenAiChatOptions.java 类提供模型配置，例如要使用的模型、温度、频率损失等。
启动时，可以使用OpenAiChatModel(api, options)constructor 或spring.ai.openai.chat.options.*性能。
在运行时，您可以通过向Prompt叫。
例如，要覆盖特定请求的默认型号和温度：
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
OpenAiChatOptions.builder()
.withModel("gpt-4-o")
.withTemperature(0.4)
.build()
));| 除了特定于模型的 OpenAiChatOptions 之外，您还可以使用通过 ChatOptionsBuilder#builder（） 创建的可移植 ChatOptions 实例。 |
函数调用
您可以使用OpenAiChatModel并让 OpenAI 模型智能地选择输出包含参数的 JSON 对象，以调用一个或多个已注册的函数。
这是一种将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关 OpenAI 函数调用的更多信息。
模 态
多模态是指模型同时理解和处理来自各种来源的信息（包括文本、图像、音频和其他数据格式）的能力。 OpenAI 支持文本、视觉和音频输入模式。
视觉
提供视觉多模态支持的 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("Explain what do you see on this picture?",
new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));
ChatResponse response = chatModel.call(new Prompt(this.userMessage,
OpenAiChatOptions.builder().withModel(OpenAiApi.ChatModel.GPT_4_O.getValue()).build()));| 从 2024 年 6 月 17 日开始，GPT_4_VISION_PREVIEW 将继续仅面向此模型的现有用户提供。如果您不是现有用户，请使用 GPT_4_O 或 GPT_4_TURBO 模型。更多详情请点击这里 |
或使用gpt-4o型：
var userMessage = new UserMessage("Explain what do you see on this picture?",
new Media(MimeTypeUtils.IMAGE_PNG,
"https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png"));
ChatResponse response = chatModel.call(new Prompt(this.userMessage,
OpenAiChatOptions.builder().withModel(OpenAiApi.ChatModel.GPT_4_O.getValue()).build()));| 您也可以传递多个图像。 |
该示例显示了一个模型，将multimodal.test.png图像：
以及文本消息 “Explain what do you see on this picture？”，并生成如下响应：
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.
音频
提供输入音频多模态支持的 OpenAI 模型包括gpt-4o-audio-preview.
请参阅 音频指南 以了解更多信息。
OpenAI 用户消息 API 可以将 base64 编码的音频文件列表与消息合并。
Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和详细信息，使用 Spring 的org.springframework.util.MimeType以及org.springframework.core.io.Resource对于原始媒体数据。
目前，OpenAI 仅支持以下媒体类型：audio/mp3和audio/wav.
下面是一个摘自 OpenAiChatModelIT.java 的代码示例，说明了如何使用gpt-4o-audio-preview型。
var audioResource = new ClassPathResource("speech1.mp3");
var userMessage = new UserMessage("What is this recording about?",
List.of(new Media(MimeTypeUtils.parseMimeType("audio/mp3"), audioResource)));
ChatResponse response = chatModel.call(new Prompt(List.of(userMessage),
OpenAiChatOptions.builder().withModel(OpenAiApi.ChatModel.GPT_4_O_AUDIO_PREVIEW).build()));| 您也可以传递多个音频文件。 |
输出音频
提供输入音频多模态支持的 OpenAI 模型包括gpt-4o-audio-preview.
请参阅 音频指南 以了解更多信息。
OpenAI Assystant 消息 API 可以包含带有消息的 base64 编码音频文件列表。
Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和详细信息，使用 Spring 的org.springframework.util.MimeType以及org.springframework.core.io.Resource对于原始媒体数据。
目前 OpenAI 仅支持以下音频类型：audio/mp3和audio/wav.
下面是一个代码示例，说明了用户文本的响应以及音频字节数组，使用gpt-4o-audio-preview型：
var userMessage = new UserMessage("Tell me joke about Spring Framework");
ChatResponse response = chatModel.call(new Prompt(List.of(userMessage),
OpenAiChatOptions.builder()
.withModel(OpenAiApi.ChatModel.GPT_4_O_AUDIO_PREVIEW)
.withOutputModalities(List.of("text", "audio"))
.withOutputAudio(new AudioParameters(Voice.ALLOY, AudioResponseFormat.WAV))
.build()));
String text = response.getResult().getOutput().getContent(); // audio transcript
byte[] waveAudio = response.getResult().getOutput().getMedia().get(0).getDataAsByteArray(); // audio data您必须指定一个audiomodal 中OpenAiChatOptions以生成音频输出。
这AudioParametersclass 提供音频输出的语音和音频格式。
结构化输出
OpenAI 提供自定义结构化输出 API，确保您的模型生成的响应严格符合您提供的响应JSON Schema.
除了现有的 Spring AI 模型无关的结构化输出转换器之外，这些 API 还提供了增强的控制和精度。
| 目前，OpenAI 支持 JSON Schema 语言格式的子集。 |
配置
Spring AI 允许您使用OpenAiChatOptionsbuilder 或通过应用程序属性。
使用聊天选项生成器
您可以使用OpenAiChatOptionsbuilder 中，如下所示：
String jsonSchema = """
{
"type": "object",
"properties": {
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"explanation": { "type": "string" },
"output": { "type": "string" }
},
"required": ["explanation", "output"],
"additionalProperties": false
}
},
"final_answer": { "type": "string" }
},
"required": ["steps", "final_answer"],
"additionalProperties": false
}
""";
Prompt prompt = new Prompt("how can I solve 8x + 7 = -23",
OpenAiChatOptions.builder()
.withModel(ChatModel.GPT_4_O_MINI)
.withResponseFormat(new ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, this.jsonSchema))
.build());
ChatResponse response = this.openAiChatModel.call(this.prompt);| 遵循 JSON 架构语言格式的 OpenAI 子集。 |
与 BeanOutputConverter 实用程序集成
您可以利用现有的 BeanOutputConverter 实用程序从域对象自动生成 JSON 模式，然后将结构化响应转换为特定于域的实例：
-
Java
-
Kotlin
record MathReasoning(
@JsonProperty(required = true, value = "steps") Steps steps,
@JsonProperty(required = true, value = "final_answer") String finalAnswer) {
record Steps(
@JsonProperty(required = true, value = "items") Items[] items) {
record Items(
@JsonProperty(required = true, value = "explanation") String explanation,
@JsonProperty(required = true, value = "output") String output) {
}
}
}
var outputConverter = new BeanOutputConverter<>(MathReasoning.class);
var jsonSchema = this.outputConverter.getJsonSchema();
Prompt prompt = new Prompt("how can I solve 8x + 7 = -23",
OpenAiChatOptions.builder()
.withModel(ChatModel.GPT_4_O_MINI)
.withResponseFormat(new ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, this.jsonSchema))
.build());
ChatResponse response = this.openAiChatModel.call(this.prompt);
String content = this.response.getResult().getOutput().getContent();
MathReasoning mathReasoning = this.outputConverter.convert(this.content);data class MathReasoning(
@get:JsonProperty(required = true, value = "steps") val steps: Steps,
@get:JsonProperty(required = true, value = "final_answer") val finalAnswer: String) {
data class Steps(@get:JsonProperty(required = true, value = "items") val items: Array<Items>) {
data class Items(
@get:JsonProperty(required = true, value = "explanation") val explanation: String,
@get:JsonProperty(required = true, value = "output") val output: String)
}
}
val outputConverter = BeanOutputConverter(MathReasoning::class.java)
val jsonSchema = outputConverter.jsonSchema;
val prompt = Prompt("how can I solve 8x + 7 = -23",
OpenAiChatOptions.builder()
.withModel(ChatModel.GPT_4_O_MINI)
.withResponseFormat(ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
.build())
val response = openAiChatModel.call(prompt)
val content = response.getResult().getOutput().getContent()
val mathReasoning = outputConverter.convert(content)通过应用程序属性进行配置
或者，在使用 OpenAI 自动配置时，您可以通过以下应用程序属性配置所需的响应格式：
spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.chat.options.model=gpt-4o-mini
spring.ai.openai.chat.options.response-format.type=JSON_SCHEMA
spring.ai.openai.chat.options.response-format.name=MySchemaName
spring.ai.openai.chat.options.response-format.schema={"type":"object","properties":{"steps":{"type":"array","items":{"type":"object","properties":{"explanation":{"type":"string"},"output":{"type":"string"}},"required":["explanation","output"],"additionalProperties":false}},"final_answer":{"type":"string"}},"required":["steps","final_answer"],"additionalProperties":false}
spring.ai.openai.chat.options.response-format.strict=trueSamples控制器
创建一个新的 Spring Boot 项目并添加spring-ai-openai-spring-boot-starter添加到您的 POM（或 Gradle）依赖项中。
添加application.properties文件src/main/resources目录下，启用和配置 OpenAi 聊天模型：
spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.chat.options.model=gpt-4o
spring.ai.openai.chat.options.temperature=0.7将api-key使用您的 OpenAI 凭证。 |
这将创建一个OpenAiChatModel实现，您可以将其注入到您的类中。
下面是一个简单的示例@RestController使用 Chat 模型生成文本的类。
@RestController
public class ChatController {
private final OpenAiChatModel chatModel;
@Autowired
public ChatController(OpenAiChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map<String,String> 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);
}
}手动配置
OpenAiChatModel 实现了ChatModel和StreamingChatModel并使用 Low-level OpenAiApi Client 连接到 OpenAI 服务。
添加spring-ai-openai依赖项添加到项目的 Mavenpom.xml文件：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai</artifactId>
</dependency>或发送到您的 Gradlebuild.gradlebuild 文件。
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}| 请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。 |
接下来，创建一个OpenAiChatModel并将其用于文本生成：
var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY"));
var openAiChatOptions = OpenAiChatOptions.builder()
.withModel("gpt-3.5-turbo")
.withTemperature(0.4)
.withMaxTokens(200)
.build();
var chatModel = new OpenAiChatModel(this.openAiApi, 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."));这OpenAiChatOptions提供聊天请求的配置信息。
这OpenAiChatOptions.Builder是一个 Fluent 选项构建者。
低级 OpenAiApi 客户端
OpenAiApi 为 OpenAI Chat API OpenAI Chat API 提供了轻量级的 Java 客户端。
以下类图说明了OpenAiApi聊天界面和构建块：
下面是一个简单的代码片段，演示如何以编程方式使用 API：
OpenAiApi openAiApi =
new OpenAiApi(System.getenv("OPENAI_API_KEY"));
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("Hello world", Role.USER);
// Sync request
ResponseEntity<ChatCompletion> response = this.openAiApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), "gpt-3.5-turbo", 0.8, false));
// Streaming request
Flux<ChatCompletionChunk> streamResponse = this.openAiApi.chatCompletionStream(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), "gpt-3.5-turbo", 0.8, true));有关详细信息，请遵循 OpenAiApi.java 的 JavaDoc。
低级 API 示例
-
OpenAiApiIT.java 测试提供了一些有关如何使用轻量级库的一般示例。
-
OpenAiApiToolFunctionCallIT.java测试展示了如何使用低级 API 调用工具函数。 基于 OpenAI 函数调用教程。