OpenAI 聊天

Spring AI 支持 OpenAI 的各种 AI 语言模型。OpenAI 是 ChatGPT 背后的公司，它创建了业界领先的文本生成模型和嵌入，极大地激发了人们对 AI 驱动的文本生成的兴趣。

先决条件

您需要使用 OpenAI 创建一个 API 来访问 ChatGPT 模型。请在 OpenAI 注册页面 创建账户，并在 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 构建产物发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅 仓库 部分，将这些仓库添加到您的构建系统中。

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

自动配置

Spring AI 自动配置、Starter 模块的构件名称发生了重大变化。有关更多信息，请参阅升级注意事项。

Spring AI 为 OpenAI Chat Client 提供了 Spring Boot 自动配置。要启用它，请将以下依赖添加到您项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
请参阅依赖管理部分，将 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 Key

-

spring.ai.openai.organization-id

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

-

spring.ai.openai.project-id

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

-
对于属于多个组织（或通过其旧用户 API 密钥访问其项目）的用户，您可以选择指定用于 API 请求的组织和项目。这些 API 请求的使用量将计入指定的组织和项目的使用量中。

配置属性

聊天自动配置的启用和禁用现在通过前缀为 spring.ai.model.chat 的顶级属性进行配置。

要启用，设置 spring.ai.model.chat=openai（默认已启用）

要禁用，设置 spring.ai.model.chat=none（或任何不匹配 openai 的值）

进行此更改是为了支持配置多个模型。

前缀 spring.ai.openai.chat 用作属性前缀，您可以通过它配置 OpenAI 的聊天模型实现。

属性 描述 默认值

spring.ai.openai.chat.enabled (已移除且不再有效)

启用 OpenAI 聊天模型。

true

spring.ai.model.chat

启用 OpenAI 聊天模型。

openai

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 Key。

-

spring.ai.openai.chat.organization-id

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

-

spring.ai.openai.chat.project-id

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

-

spring.ai.openai.chat.options.model

要使用的 OpenAI 聊天模型的名称。您可以选择的模型包括：gpt-4o、gpt-4o-mini、gpt-4-turbo、gpt-3.5-turbo 等。有关更多信息，请参阅模型页面。

gpt-4o-mini

spring.ai.openai.chat.options.temperature

用于控制生成完成结果的显式创造性的采样温度。值越高会使输出更随机，而值越低会使结果更集中和确定。不建议在同一个完成请求中同时修改 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

(已弃用，推荐使用 maxCompletionTokens) 在聊天完成中生成的最大令牌数。输入令牌和生成令牌的总长度受模型的上下文长度限制。

-

spring.ai.openai.chat.options.maxCompletionTokens

完成结果可生成的令牌数的上限，包括可见输出令牌和推理令牌。

-

spring.ai.openai.chat.options.n

为每个输入消息生成多少个聊天完成选项。请注意，您将根据所有选项中生成的令牌总数进行计费。将 n 设置为 1 以最小化成本。

1

spring.ai.openai.chat.options.store

是否存储此聊天完成请求的输出，供我们的模型使用

false

spring.ai.openai.chat.options.metadata

开发者定义的标签和值，用于在聊天完成仪表板中过滤完成结果

空 map

spring.ai.openai.chat.options.output-modalities

您希望模型为此请求生成的输出类型。大多数模型能够生成文本，这是默认类型。gpt-4o-audio-preview 模型也可用于生成音频。要请求此模型生成文本和音频响应，您可以使用：text, audio。不支持流式传输。

-

spring.ai.openai.chat.options.output-audio

音频生成的音频参数。当通过 output-modalities 请求音频输出时必需，值为 audio。需要 gpt-4o-audio-preview 模型，并且不支持流式完成。

-

spring.ai.openai.chat.options.presencePenalty

介于 -2.0 和 2.0 之间的数值。正值会根据新令牌是否迄今为止出现在文本中来惩罚新令牌，从而增加模型讨论新主题的可能性。

-

spring.ai.openai.chat.options.responseFormat.type

兼容 GPT-4o、GPT-4o mini、GPT-4 Turbo 以及所有比 gpt-3.5-turbo-1106 新的 GPT-3.5 Turbo 模型。JSON_OBJECT 类型启用 JSON 模式，确保模型生成的消息是有效的 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

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

-

spring.ai.openai.chat.options.stop

API 将停止生成更多令牌的序列列表，最多 4 个。

-

spring.ai.openai.chat.options.topP

采样温度的替代方法，称为核采样 (nucleus sampling)，模型考虑概率质量为 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

函数列表，按其名称标识，用于在单个 Prompt 请求中启用函数调用。具有这些名称的函数必须存在于 functionCallbacks 注册表中。

-

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

(仅用于流式传输) 设置后将添加一个额外的 chunk，其中包含整个请求的 token 使用统计信息。此 chunk 的 choices 字段是一个空数组，所有其他 chunk 也将包含一个 usage 字段，但值为 null。

false

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

在使用工具时是否启用并行函数调用。

true

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

要添加到聊天完成请求的可选 HTTP header。要覆盖 api-key，您需要使用 Authorization header 键，并且需要在键值前加上 Bearer 前缀。

-

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()
            .model("gpt-4o")
            .temperature(0.4)
        .build()
    ));
除了模型特定的 OpenAiChatOptions 外，您还可以使用一个可移植的 ChatOptions 实例，通过 ChatOptionsBuilder#builder() 创建。

函数调用

您可以向 OpenAiChatModel 注册自定义 Java 函数，并让 OpenAI 模型智能地选择输出一个包含调用一个或多个已注册函数所需参数的 JSON 对象。这是一种将大型语言模型能力与外部工具和 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().model(OpenAiApi.ChatModel.GPT_4_O.getValue()).build()));
GPT_4_VISION_PREVIEW 模型将从 2024 年 6 月 17 日起仅对现有用户开放。如果您不是现有用户，请使用 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,
                URI.create("https://docs.springjava.cn/spring-ai/reference/_images/multimodal.test.png")));

ChatResponse response = chatModel.call(new Prompt(this.userMessage,
        OpenAiChatOptions.builder().model(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 模型包括 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().model(OpenAiApi.ChatModel.GPT_4_O_AUDIO_PREVIEW).build()));
您也可以传递多个音频文件。

输出音频

支持输入音频多模态的 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。

下面是一个代码示例，演示了使用 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()
            .model(OpenAiApi.ChatModel.GPT_4_O_AUDIO_PREVIEW)
            .outputModalities(List.of("text", "audio"))
            .outputAudio(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

您必须在 OpenAiChatOptions 中指定 audio 模态才能生成音频输出。AudioParameters 类提供音频输出的语音和音频格式。

结构化输出

OpenAI 提供自定义的结构化输出 API，确保您的模型生成严格符合您提供的 JSON Schema 的响应。除了现有的与 Spring AI 模型无关的结构化输出转换器之外，这些 API 还提供了增强的控制和精度。

目前，OpenAI 支持 JSON Schema 语言格式的子集。

配置

Spring AI 允许您使用 OpenAiChatOptions 构建器以编程方式配置响应格式，或通过应用程序属性进行配置。

使用 Chat Options 构建器

您可以使用 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()
            .model(ChatModel.GPT_4_O_MINI)
            .responseFormat(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()
            .model(ChatModel.GPT_4_O_MINI)
            .responseFormat(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(
	val steps: Steps,
	@get:JsonProperty(value = "final_answer") val finalAnswer: String) {

	data class Steps(val items: Array<Items>) {

		data class Items(
			val explanation: String,
			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()
		.model(ChatModel.GPT_4_O_MINI)
		.responseFormat(ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
		.build())

val response = openAiChatModel.call(prompt)
val content = response.getResult().getOutput().getContent()

val mathReasoning = outputConverter.convert(content)
虽然这对于 JSON Schema 是可选的，但 OpenAI 要求结构化响应必须包含必需字段才能正常工作。Kotlin 反射用于根据类型的可空性和参数的默认值来推断哪些属性是必需的或不是，因此对于大多数用例来说，不需要 @get:JsonProperty(required = true)。@get:JsonProperty(value = "custom_name") 可以用于自定义属性名称。请确保使用此 @get: 语法在相关的 getter 上生成注解，请参阅相关文档。

通过应用程序属性进行配置

或者，当使用 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-starter-model-openai 添加到您的 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 = OpenAiApi.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .build();
var openAiChatOptions = OpenAiChatOptions.builder()
            .model("gpt-3.5-turbo")
            .temperature(0.4)
            .maxTokens(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 提供了聊天请求的配置信息。OpenAiApi.Builder 和 OpenAiChatOptions.Builder 分别是用于 API 客户端和聊天配置的流畅选项构建器。

底层 OpenAiApi 客户端

OpenAiApi 提供了一个轻量级的 Java 客户端，用于调用 OpenAI 聊天 API。

下图展示了 OpenAiApi 聊天接口和构建块的类图

OpenAiApi Chat API Diagram

这是一个简单的代码片段，展示了如何以编程方式使用 API

OpenAiApi openAiApi = OpenAiApi.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .build();

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 示例

API Key 管理

Spring AI 通过 ApiKey 接口及其实现提供了灵活的 API Key 管理。默认实现 SimpleApiKey 适用于大多数用例，但您也可以创建自定义实现来应对更复杂的场景。

默认配置

默认情况下，Spring Boot 自动配置将使用 spring.ai.openai.api-key 属性创建一个 API Key Bean

spring.ai.openai.api-key=your-api-key-here

自定义 API Key 配置

您可以使用构建器模式，通过您自己的 ApiKey 实现创建一个自定义的 OpenAiApi 实例

ApiKey customApiKey = new ApiKey() {
    @Override
    public String getValue() {
        // Custom logic to retrieve API key
        return "your-api-key-here";
    }
};

OpenAiApi openAiApi = OpenAiApi.builder()
    .apiKey(customApiKey)
    .build();

// Create a chat client with the custom OpenAiApi instance
OpenAiChatClient chatClient = new OpenAiChatClient(openAiApi);

当您需要以下情况时，这很有用：

  • 从安全密钥库中检索 API Key

  • 动态轮换 API Key

  • 实现自定义 API Key 选择逻辑