OpenAI 聊天
Spring AI 支持来自 OpenAI 的各种 AI 语言模型,OpenAI 是 ChatGPT 背后的公司,由于其创建了业界领先的文本生成模型和嵌入,它在推动人们对 AI 驱动的文本生成感兴趣方面发挥了重要作用。
先决条件
您需要创建一个 OpenAI API 才能访问 ChatGPT 模型。在 OpenAI 注册页面 创建帐户,并在 API 密钥页面 生成令牌。Spring AI 项目定义了一个名为 spring.ai.openai.api-key
的配置属性,您应该将其设置为从 openai.com 获取的 API 密钥
的值。导出环境变量是设置该配置属性的一种方法。
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
自动配置
Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。要启用它,请将以下依赖项添加到您项目的 Maven pom.xml
或 Gradle build.gradle
构建文件中。
-
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'
}
请参考 依赖项管理 部分,将 Spring AI BOM 添加到您的构建文件中。 |
聊天属性
重试属性
前缀 spring.ai.retry
用作属性前缀,允许您配置 OpenAI 聊天模型的重试机制。
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.retry.max-attempts |
最大重试次数。 |
10 |
spring.ai.retry.backoff.initial-interval |
指数退避策略的初始休眠持续时间。 |
2 秒。 |
spring.ai.retry.backoff.multiplier |
退避间隔乘数。 |
5 |
spring.ai.retry.backoff.max-interval |
最大退避持续时间。 |
3 分钟。 |
spring.ai.retry.on-client-errors |
如果为 false,则抛出 NonTransientAiException,并且不尝试重试 |
false |
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 聊天模型。 |
true |
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.0f |
spring.ai.openai.chat.options.logitBias |
修改指定词元出现在补全结果中的可能性。 |
- |
spring.ai.openai.chat.options.maxTokens |
(已弃用,推荐使用 |
- |
spring.ai.openai.chat.options.maxCompletionTokens |
可以为补全生成的词元数量的上限,包括可见的输出词元和推理词元。 |
- |
spring.ai.openai.chat.options.n |
为每个输入消息生成多少个聊天补全选项。请注意,您将根据所有选项中生成的词元数量付费。将 |
1 |
spring.ai.openai.chat.options.presencePenalty |
-2.0 到 2.0 之间的数字。正值会根据新词元是否出现在当前文本中对其进行惩罚,从而增加模型讨论新主题的可能性。 |
- |
spring.ai.openai.chat.options.responseFormat.type |
兼容 |
- |
spring.ai.openai.chat.options.responseFormat.name |
响应格式 schema 名称。仅适用于 |
custom_schema |
spring.ai.openai.chat.options.responseFormat.schema |
响应格式 JSON schema。仅适用于 |
- |
spring.ai.openai.chat.options.responseFormat.strict |
响应格式 JSON schema 遵循严格性。仅适用于 |
- |
spring.ai.openai.chat.options.seed |
此功能处于测试阶段。如果指定,我们的系统将尽力进行确定性采样,以便使用相同的 seed 和参数重复请求应返回相同的结果。 |
- |
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 |
(仅限流式传输) 设置为添加一个包含整个请求的词元使用情况统计信息的额外块。此块的 |
false |
spring.ai.openai.chat.options.parallel-tool-calls |
是否启用 并行函数调用 。 |
true |
spring.ai.openai.chat.options.http-headers |
要添加到聊天补全请求中的可选 HTTP 头。要覆盖 |
- |
spring.ai.openai.chat.options.proxy-tool-calls |
如果为 true,Spring AI 将不会在内部处理函数调用,而是将其代理到客户端。然后,客户端负责处理函数调用,将它们分派到相应的函数并返回结果。如果为 false(默认值),Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型。 |
false |
您可以为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 调用添加请求特定的 运行时选项 来覆盖。 |
运行时选项
OpenAiChatOptions.java 类提供模型配置,例如要使用的模型、温度、频率惩罚等。
启动时,可以使用OpenAiChatModel(api, options)
构造函数或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 之外,您还可以使用可移植的 ChatOptions 实例,该实例使用 ChatOptionsBuilder#builder() 创建。 |
函数调用
您可以使用OpenAiChatModel
注册自定义 Java 函数,并让 OpenAI 模型智能地选择输出包含要调用一个或多个已注册函数的参数的 JSON 对象。这是一种强大的技术,可以将 LLM 功能与外部工具和 API 连接起来。阅读更多关于 OpenAI 函数调用 的信息。
多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力,包括文本、图像、音频和其他数据格式。提供多模态支持的 OpenAI 模型包括gpt-4
、gpt-4o
和gpt-4o-mini
。有关更多信息,请参阅 Vision 指南。
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
模型的图像 URL 等效项
var userMessage = new UserMessage("Explain what do you see on this picture?",
new Media(MimeTypeUtils.IMAGE_PNG,
"https://docs.springframework.org.cn/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
图像作为输入
以及文本消息“解释你在这张图片上看到了什么?”,并生成如下响应
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 提供自定义的 结构化输出 API,确保您的模型生成的响应严格符合您提供的JSON Schema
。除了现有的 Spring AI 与模型无关的 结构化输出转换器 之外,这些 API 还提供了增强的控制和精度。
目前,OpenAI 支持 JSON Schema 语言格式的子集。 |
配置
Spring AI 允许您使用OpenAiChatOptions
构建器或通过应用程序属性以编程方式配置响应格式。
使用聊天选项构建器
您可以使用如下所示的OpenAiChatOptions
构建器以编程方式设置响应格式
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);
遵循 OpenAI JSON Schema 语言格式的子集。 |
与 BeanOutputConverter 实用程序集成
您可以利用现有的 BeanOutputConverter 工具自动从您的领域对象生成 JSON Schema,然后将结构化响应转换为特定于领域的实例。
-
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=true
示例控制器
创建一个新的 Spring Boot 项目,并将spring-ai-openai-spring-boot-starter
添加到您的 pom (或 gradle) 依赖项中。
在src/main/resources
目录下添加一个application.properties
文件以启用和配置 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
类的示例。
@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
,并使用低级 OpenAiApi 客户端连接到 OpenAI 服务。
将spring-ai-openai
依赖项添加到您项目的 Maven pom.xml
文件中
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai</artifactId>
</dependency>
或添加到您的 Gradle build.gradle
构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}
请参考 依赖项管理 部分,将 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
是一个流畅的选项构建器。
低级 OpenAiApi 客户端
该OpenAiApi提供了一个轻量级的 Java 客户端,用于 OpenAI 聊天 API OpenAI 聊天 API。
下面的类图说明了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 函数调用 教程。