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>

添加存储库和BOM

Spring AI 成品在 Spring Milestone 和 Snapshot 仓库中发布。请参阅 仓库部分,将这些仓库添加到您的构建系统中。

为了帮助依赖管理,Spring AI提供了一个BOM(物料清单),以确保整个项目中使用的Spring AI版本保持一致。请参考依赖管理部分,将Spring AI BOM添加到您的构建系统中。

自动配置

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

https://api.openai.com

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聊天模型

gpt-3.5-turbogpt-3.5-turbo、`gpt-4`和`gpt-4-32k`指向最新的模型版本)

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 实现了 ChatClientStreamingChatClient,并使用 [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`聊天接口和构建模块:

OpenAiApi聊天API图解

这是一个简单的代码片段,展示了如何以编程方式使用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函数调用]教程。