Spring AI 支持 OpenAI 的 AI 语言模型 ChatGPT。ChatGPT 在激发人们对 AI 驱动的文本生成的兴趣方面发挥了重要作用,这要归功于它创建的业界领先的文本生成模型和嵌入。
先决条件
你需要创建一个与OpenAI的API来访问ChatGPT模型。在[OpenAI注册页面](API密钥页面(https://platform.openai.com/account/api-keys)生成令牌。Spring AI项目定义了一个名为`spring.ai.openai.api-key`的配置属性,你应将其设置为从openai.com获得的`API Key`的值。导出一个环境变量是设置该配置属性的一种方式:
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
自动配置
Spring AI为OpenAI聊天客户端提供了Spring Boot自动配置。要启用它,请将以下依赖项添加到项目的Maven `pom.xml`文件中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
或者添加到你的Gradle build.gradle
构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}
Tip
|
参考依赖管理部分,在您的构建文件中添加Spring AI BOM。 |
聊天属性
重试属性
前缀`spring.ai.retry`被用作属性前缀,允许您为OpenAI Chat客户端配置重试机制。
属性 | 描述 | 默认值 |
---|---|---|
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,并且不为`4xx`客户端错误码尝试重试 |
false |
|
spring.ai.retry.exclude-on-http-codes |
不应触发重试的HTTP状态码列表(例如,抛出NonTransientAiException)。 |
空 |
连接属性
前缀 spring.ai.openai
被用作属性前缀,使你能够连接到OpenAI。
Property |
Description |
Default |
--------------------------------- |
----------------------- |
|
----------------------------- |
spring.ai.openai.base-url |
|
连接的URL |
||
spring.ai.openai.api-key |
API密钥 |
- |
配置属性
前缀 spring.ai.openai.chat
是允许您配置 OpenAI 聊天客户端实现的属性前缀。
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.openai.chat.enabled |
启用OpenAI聊天客户端。 |
|
true |
spring.ai.openai.chat.base-url |
|
可选,覆盖spring.ai.openai.base-url以提供特定于聊天的url |
- |
|
spring.ai.openai.chat.api-key |
可选,覆盖spring.ai.openai.api-key以提供特定于聊天的api-key |
- |
spring.ai.openai.chat.options.model |
要使用的OpenAI聊天模型 |
|
|
spring.ai.openai.chat.options.temperature |
|
控制生成完成项的表面创造性的采样温度。较高的值会使输出更随机,而较低的值会使结果更加专注和确定。不建议同时修改温度和top_p,因为这两个设置的互动很难预测。 |
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.n |
为每个输入消息生成多少个聊天完成选项。请注意,您将根据所有选项中生成的令牌数量收费。将n设为1以最小化成本。 |
1 |
spring.ai.openai.chat.options.presencePenalty |
在-2.0到2.0之间的数字。正值根据它们是否出现在迄今为止的文本中对新令牌进行惩罚,增加模型谈论新话题的可能性。 |
|
- |
spring.ai.openai.chat.options.responseFormat |
|
指定模型必须输出的格式的对象。设置为`{ "type": "json_object" }`启用JSON模式,这保证模型生成的消息是有效的JSON。 |
- |
|
spring.ai.openai.chat.options.seed |
此功能处于Beta测试阶段。如果指定,我们的系统将尽最大努力确定性采样,这样重复的请求与相同的种子和参数应该返回相同的结果。 |
- |
spring.ai.openai.chat.options.stop |
API将停止生成更多令牌的最多4个序列。 |
|
- |
spring.ai.openai.chat.options.topP |
|
采样温度的替代方法,称为核采样,其中模型考虑具有top_p概率质量的令牌的结果。所以0.1意味着只考虑组成顶部10%概率质量的令牌。我们通常建议修改这个或温度,但不是两者。 |
- |
|
spring.ai.openai.chat.options.tools |
模型可能调用的工具列表。目前,仅支持将函数作为工具。使用此提供一个模型可能为其生成JSON输入的函数列表。 |
- |
spring.ai.openai.chat.options.toolChoice |
控制模型调用哪个(如果有的话)函数。none意味着模型不会调用函数而是生成消息。auto意味着模型可以在生成消息或调用函数之间选择。通过`{"type: "function", "function": {"name": "my_function"}}`指定特定函数强制模型调用该函数。如果没有函数,none是默认值。如果存在函数,auto是默认值。 |
Note
|
您可以覆盖`ChatClient`和`EmbeddingClient`实现的通用`spring.ai.openai.base-url`和`spring.ai.openai.api-key`配置。如果设置了`spring.ai.openai.chat.base-url`和`spring.ai.openai.chat.api-key`属性,则这些属性将优先于通用属性。如果您希望使用不同的OpenAI账户针对不同的模型和不同的模型端点,这将非常有用。 |
Tip
|
所有以 spring.ai.openai.chat.options 为前缀的属性可以在运行时被覆盖,方法是在 Prompt 调用中添加特定于请求的 运行时选项。
|
运行时选项
'''The OpenAiChatOptions.java provides model configurations, such as the model to use, the temperature, the frequency penalty, etc.''' 提供了模型配置,例如要使用的模型、温度、频率惩罚等。
在启动时,可以通过 OpenAiChatClient(api, options)
构造函数或者 spring.ai.openai.chat.options.*
属性来配置默认选项。
在运行时,你可以通过向`Prompt`调用添加新的、特定于请求的选项来覆盖默认选项。例如,为了覆盖特定请求的默认模型和温度:
ChatResponse response = chatClient.call(
new Prompt(
"Generate the names of 5 famous pirates.",
OpenAiChatOptions.builder()
.withModel("gpt-4-32k")
.withTemperature(0.4)
.build()
));
函数调用
您可以使用OpenAiChatClient注册自定义Java函数,并让OpenAI模型智能地选择输出一个包含调用一个或多个已注册函数的参数的JSON对象。这是一种将LLM能力与外部工具和APIs连接起来的强大技术。阅读更多关于OpenAI函数调用。
样本控制器
在 https://start.spring.io/ [创建] 一个新的Spring Boot项目,并将 spring-ai-openai-spring-boot-starter
添加到pom(或gradle)依赖中。
在`src/main/resources`目录下添加一个`application.properties`文件,以启用并配置OpenAi Chat客户端:
spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.chat.options.model=gpt-3.5-turbo
spring.ai.openai.chat.options.temperature=0.7
Tip
|
将 api-key 替换为您的 OpenAI 凭证。
|
这将创建一个`OpenAiChatClient`实现,您可以将其注入到您的类中。这里有一个简单的`@Controller`类的例子,它使用聊天客户端进行文本生成。
@RestController
public class ChatController {
private final OpenAiChatClient chatClient;
@Autowired
public ChatController(OpenAiChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", chatClient.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 chatClient.stream(prompt);
}
}
手动配置
The OpenAiChatClient 实现了 ChatClient
和 StreamingChatClient
,并使用 [low-level-api] 连接到 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'
}
Tip
|
参考依赖管理部分,在您的构建文件中添加Spring AI BOM。 |
接下来,创建一个`OpenAiChatClient`并使用它进行文本生成:
var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY"));
var chatClient = new OpenAiChatClient(openAiApi)
.withDefaultOptions(OpenAiChatOptions.builder()
.withModel("gpt-3.5-turbo")
.withTemperature(0.4)
.withMaxTokens(200)
.build());
ChatResponse response = chatClient.call(
new Prompt("Generate the names of 5 famous pirates."));
// 或者通过流式响应
Flux<ChatResponse> response = chatClient.stream(
new Prompt("生成5位著名海盗的名字。"));
OpenAiChatOptions`提供了聊天请求的配置信息。`OpenAiChatOptions.Builder`是流畅的选项构建器。
低级OpenAiApi客户端
The 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 = openAiApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(chatCompletionMessage), "gpt-3.5-turbo", 0.8f, false));
// Streaming request
Flux<ChatCompletionChunk> streamResponse = openAiApi.chatCompletionStream(
new ChatCompletionRequest(List.of(chatCompletionMessage), "gpt-3.5-turbo", 0.8f, true));
请遵循 OpenAiApi.java 的 JavaDoc 以获取更多信息。
低级别 API 示例
-
链接:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/api/OpenAiApiIT.java [OpenAiApiIT.java] 测试提供了一些使用这个轻量级库的一般例子。
-
链接:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/api/tool/OpenAiApiToolFunctionCallIT.java[OpenAiApiToolFunctionCallIT.java] 测试展示了如何使用底层API来调用工具函数。基于链接:https://platform.openai.com/docs/guides/function-calling/parallel-function-calling[OpenAI函数调用]教程。