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>

添加存储库和 BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 存储库中。请参考 存储库 部分,将这些存储库添加到您的构建系统。

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

自动配置

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,并且不尝试重试 4xx 客户端错误代码。

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

api.openai.com

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.base-url 属性的可选覆盖,用于提供特定于聊天的 URL。

-

spring.ai.openai.chat.completions-path

要附加到基本 URL 的路径。

/v1/chat/completions

spring.ai.openai.chat.api-key

spring.ai.openai.api-key 的可选覆盖,用于提供特定于聊天的 API 密钥。

-

spring.ai.openai.chat.organization-id

可选地,您可以指定要用于 API 请求的组织。

-

spring.ai.openai.chat.project-id

可选地,您可以指定要用于 API 请求的项目。

-

spring.ai.openai.chat.options.model

要使用的 OpenAI 聊天模型的名称。您可以选择模型,例如:gpt-4ogpt-4o-minigpt-4-turbogpt-3.5-turbo 等。有关更多信息,请参见 模型 页面。

gpt-4o

spring.ai.openai.chat.options.temperature

用于控制生成文本创作性的采样温度。较高的值将使输出更随机,而较低的值将使结果更集中和确定性。不建议为同一个补全请求同时修改temperaturetop_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

(已弃用,推荐使用maxCompletionTokens) 在聊天补全中生成的词元最大数量。输入词元和生成的词元的总长度受模型上下文长度限制。

-

spring.ai.openai.chat.options.maxCompletionTokens

可以为补全生成的词元数量的上限,包括可见的输出词元和推理词元。

-

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

兼容GPT-4oGPT-4o miniGPT-4 Turbo 和所有版本高于gpt-3.5-turbo-1106GPT-3.5 Turbo 模型。JSON_OBJECT 类型启用 JSON 模式,确保模型生成的 message 是有效的 JSON。JSON_SCHEMA 类型启用 结构化输出,确保模型将与您提供的 JSON schema 匹配。JSON_SCHEMA 类型还需要设置responseFormat.schema 属性。

-

spring.ai.openai.chat.options.responseFormat.name

响应格式 schema 名称。仅适用于responseFormat.type=JSON_SCHEMA

custom_schema

spring.ai.openai.chat.options.responseFormat.schema

响应格式 JSON schema。仅适用于responseFormat.type=JSON_SCHEMA

-

spring.ai.openai.chat.options.responseFormat.strict

响应格式 JSON schema 遵循严格性。仅适用于responseFormat.type=JSON_SCHEMA

-

spring.ai.openai.chat.options.seed

此功能处于测试阶段。如果指定,我们的系统将尽力进行确定性采样,以便使用相同的 seed 和参数重复请求应返回相同的结果。

-

spring.ai.openai.chat.options.stop

最多 4 个序列,API 将在此处停止生成更多词元。

-

spring.ai.openai.chat.options.topP

一种替代温度采样的方法,称为核采样,其中模型考虑具有top_p概率质量的词元的输出结果。因此,0.1 表示只考虑包含前 10% 概率质量的词元。我们通常建议更改此设置或temperature,但不要同时更改两者。

-

spring.ai.openai.chat.options.tools

模型可以调用的工具列表。目前,只支持函数作为工具。使用此选项提供模型可以为其生成 JSON 输入的函数列表。

-

spring.ai.openai.chat.options.toolChoice

控制模型调用哪个(如果有)函数。none 表示模型不会调用函数,而是生成消息。auto 表示模型可以在生成消息或调用函数之间进行选择。通过指定特定函数{"type: "function", "function": {"name": "my_function"}}强制模型调用该函数。如果没有函数,则默认值为none。如果存在函数,则默认为auto

-

spring.ai.openai.chat.options.user

代表您的最终用户的唯一标识符,这可以帮助 OpenAI 监控和检测滥用行为。

-

spring.ai.openai.chat.options.functions

函数列表,通过其名称标识,以便在单个提示请求中启用函数调用。这些名称的函数必须存在于functionCallbacks注册表中。

-

spring.ai.openai.chat.options.stream-usage

(仅限流式传输) 设置为添加一个包含整个请求的词元使用情况统计信息的额外块。此块的choices字段为空数组,所有其他块也将包含一个 usage 字段,但值为 null。

false

spring.ai.openai.chat.options.parallel-tool-calls

是否启用 并行函数调用

true

spring.ai.openai.chat.options.http-headers

要添加到聊天补全请求中的可选 HTTP 头。要覆盖api-key,您需要使用Authorization头键,并且必须在键值前添加`Bearer`前缀。

-

spring.ai.openai.chat.options.proxy-tool-calls

如果为 true,Spring AI 将不会在内部处理函数调用,而是将其代理到客户端。然后,客户端负责处理函数调用,将它们分派到相应的函数并返回结果。如果为 false(默认值),Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型。

false

您可以为ChatModelEmbeddingModel实现覆盖通用的spring.ai.openai.base-urlspring.ai.openai.api-key。如果设置了spring.ai.openai.chat.base-urlspring.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-4gpt-4ogpt-4o-mini。有关更多信息,请参阅 Vision 指南。

OpenAI 的 用户消息 API 可以将 base64 编码的图像或图像 URL 列表与消息结合使用。Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。此类型包含有关消息中媒体附件的数据和详细信息,使用 Spring 的org.springframework.util.MimeTypeorg.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图像作为输入

Multimodal Test Image

以及文本消息“解释你在这张图片上看到了什么?”,并生成如下响应

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);

与 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)
确保您使用@JsonProperty(required = true,…​) 注解(Kotlin 中使用@get:JsonProperty(required = true,…​) 以在相关的 getter 上生成注解,参见相关文档)。这对于生成准确标记字段为required 的 Schema 至关重要。虽然这对于 JSON Schema 是可选的,但 OpenAI 要求 结构化响应正常工作必须如此。

通过应用程序属性配置

或者,当使用 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实现了ChatModelStreamingChatModel,并使用低级 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 聊天接口和构建块。

OpenAiApi Chat API Diagram

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