此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

OpenAI SDK 聊天(官方)

Spring AI通过OpenAI Java SDK支持OpenAI的语言模型,提供了与OpenAI服务包括Microsoft Foundry和GitHub Models的稳健且官方维护的集成。spring-doc.cadn.net.cn

此实现使用了官方的OpenAI Java SDK。对于替代的Spring AI实现,请参见OpenAI聊天

The OpenAI SDK模块会根据您提供的基础URL自动检测服务提供商(OpenAI、Microsoft Foundry或GitHub Models)。spring-doc.cadn.net.cn

身份验证

使用基础URL和API密钥进行身份验证。实现通过Spring Boot属性或环境变量提供灵活的配置选项。spring-doc.cadn.net.cn

使用 OpenAI

如果您直接使用 OpenAI,请在 OpenAI 注册页面 创建账户,并在 API 密钥页面 生成 API 密钥。spring-doc.cadn.net.cn

基URL不需要设置,因为它默认为api.openai.com/v1:spring-doc.cadn.net.cn

spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url is optional, defaults to https://api.openai.com/v1

使用环境变量:spring-doc.cadn.net.cn

export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL is optional, defaults to https://api.openai.com/v1

使用 Microsoft Foundry

当使用微软Foundry网址时,会自动检测到它。您可以使用属性进行配置:spring-doc.cadn.net.cn

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>

使用环境变量:spring-doc.cadn.net.cn

export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>

无密码身份验证(推荐用于Azure):spring-doc.cadn.net.cn

Microsoft Foundry 支持无需提供 API 密钥的密码less身份验证,这在运行于 Azure 时更加安全。spring-doc.cadn.net.cn

要启用无密码认证,请添加以下依赖:
com.azure:azure-identityspring-doc.cadn.net.cn

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

然后无需 API 密钥进行配置:spring-doc.cadn.net.cn

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# No api-key needed - will use Azure credentials from environment

使用 GitHub 模型

当使用 GitHub Models 基础 URL 时,GitHub Models 会自动检测。您需要创建一个具有 models:read 权限范围的 GitHub Personal Access Token (PAT)。spring-doc.cadn.net.cn

spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX

使用环境变量:spring-doc.cadn.net.cn

export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX
在处理敏感信息(如API密钥)时,为了增强安全性,您可以使用Spring表达语言(SpEL)在属性中进行处理:
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}

添加仓库和BOM

Spring AI 构件发布在 Maven 中央仓库和 Spring Snapshot 仓库中。 请参阅 构件仓库 部分,将这些仓库添加到您的构建系统中。spring-doc.cadn.net.cn

为了帮助进行依赖管理,Spring AI 提供了一个 BOM(物料清单),以确保整个项目中使用的是相同的 Spring AI 版本。请参阅 依赖管理 部分,将 Spring AI BOM 添加到您的构建系统中。spring-doc.cadn.net.cn

Auto-configuration

Spring AI 提供了 Spring Boot 自动配置功能来支持 OpenAI SDK 聊天客户端。 要启用此功能,请在项目中的 Maven pom.xml 或 Gradle build.gradle 构建文件中添加以下依赖项:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'
}
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。

配置属性

连接属性

使用前缀spring.ai.openai-sdk作为属性前缀,以便配置OpenAI SDK客户端。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.base-urlspring-doc.cadn.net.cn

连接的URL。如果没有设置,则自动检测从OPENAI_BASE_URL环境变量。spring-doc.cadn.net.cn

api.openai.com/v1spring-doc.cadn.net.cn

spring.ai.openai-sdk.api-keyspring-doc.cadn.net.cn

The API密钥。如果未设置,则从OPENAI_API_KEY环境变量中自动检测。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.organization-idspring-doc.cadn.net.cn

可选地指定用于API请求的组织。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.timeoutspring-doc.cadn.net.cn

请求超时时间。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.max-retriesspring-doc.cadn.net.cn

失败请求的最大重试次数。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.proxyspring-doc.cadn.net.cn

OpenAI客户端(Java Proxy对象)的代理设置。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.custom-headersspring-doc.cadn.net.cn

包含在请求中的自定义HTTP标头。键值对映射,键为标头名称,值为标头值。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

Microsoft Foundry (Azure OpenAI) 属性

OpenAI SDK 实现提供了对 Microsoft Foundry(Azure OpenAI)的原生支持,并自动进行配置:spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.microsoft-foundryspring-doc.cadn.net.cn

启用Microsoft Foundry模式。如果基础URL包含openai.azure.comcognitiveservices.azure.com.openai.microsoftFoundry.com,则自动检测。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.openai-sdk.microsoft-deployment-namespring-doc.cadn.net.cn

Microsoft Foundry 部署名称。如果没有指定,将使用模型名称。也可通过别名 deployment-name 访问。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.microsoft-foundry-service-versionspring-doc.cadn.net.cn

Microsoft Foundry API 服务版本。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.credentialspring-doc.cadn.net.cn

Credential对象用于无密码认证(需要com.azure:azure-identity依赖)。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

Microsoft Foundry 支持密码less认证。添加 com.azure:azure-identity 依赖后,当未提供API密钥时,实现将自动尝试使用环境中的 Azure凭据。

GitHub 模型属性

GitHub 模型的本地支持现已可用:spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.github-modelsspring-doc.cadn.net.cn

启用GitHub模型模式。如果基础URL包含models.github.aimodels.inference.ai.azure.com,将自动检测。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

GitHub Models 需要一个带有 models:read 范围的个人访问Tokens。请通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性设置它。

聊天模型属性

spring.ai.openai-sdk.chat 前缀是配置聊天模型实现的属性前缀:spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.chat.options.modelspring-doc.cadn.net.cn

使用哪种OpenAI聊天模型。您可以选择以下模型之一:gpt-5-minigpt-4ogpt-4o-minigpt-4-turboo1o3-mini,以及其他更多模型。如需更多信息,请参阅模型页面。spring-doc.cadn.net.cn

gpt-5-minispring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.temperaturespring-doc.cadn.net.cn

使用以控制生成完成体的似乎创造力的采样温度。较高值会使输出更具随机性,而较低值会使结果更加集中和确定。不建议在同一完成体请求中修改temperaturetop_p,因为这两个设置之间的交互难以预测。spring-doc.cadn.net.cn

1.0spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.frequency-penaltyspring-doc.cadn.net.cn

在-2.0到2.0之间的数字。正数值根据文本中现有内容中新词的频率对新词进行惩罚,从而降低模型逐字重复相同行的可能性。spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.logit-biasspring-doc.cadn.net.cn

修改指定Tokens在完成时出现的可能性。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.logprobsspring-doc.cadn.net.cn

是否返回输出词元的概率对数。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.top-logprobsspring-doc.cadn.net.cn

指定在每个标记位置上返回的最有可能的标记数量,范围为0到5。要求logprobs为真。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.max-tokensspring-doc.cadn.net.cn

生成的最大 tokens 数量。仅用于非推理模型(例如,gpt-4o、gpt-3.5-turbo)。不能与推理模型(例如,o1、o3、o4-mini 系列)一起使用。与 maxCompletionTokens 互斥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.max-completion-tokensspring-doc.cadn.net.cn

生成完成内容时可以生成的最大Tokens数,包括可见输出Tokens和推理Tokens。对于推理模型(例如o1、o3、o4-迷你系列)而言是必需的。不能与非推理模型一起使用与maxTokens互斥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.nspring-doc.cadn.net.cn

每条输入消息生成多少个聊天补全选项。spring-doc.cadn.net.cn

1spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.output-modalitiesspring-doc.cadn.net.cn

列表输出模态。可以包括"文本"和"音频"。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.output-audiospring-doc.cadn.net.cn

音频输出参数。使用AudioParameters与语音(ALLOY, ASH, BALLAD, CORAL, ECHO, FABLE, ONYX, NOVA, SAGE, SHIMMER)和格式(MP3, FLAC, OPUS, PCM16, WAV, AAC)配合使用。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.presence-penaltyspring-doc.cadn.net.cn

-2.0到2.0之间的数字。正数值根据新词是否出现在当前文本中来惩罚新的tokens。spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.response-format.typespring-doc.cadn.net.cn

响应格式类型: TEXT, JSON_OBJECT, 或 JSON_SCHEMAspring-doc.cadn.net.cn

textspring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.response-format.json-schemaspring-doc.cadn.net.cn

当类型为JSON_SCHEMA时的结构化输出的 JSON 模式。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.seedspring-doc.cadn.net.cn

如果指定,系统将尽力以确定性方式采样以获得可重复的结果。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.stopspring-doc.cadn.net.cn

API将在生成更多Tokens之前停止生成至多4个序列。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.top-pspring-doc.cadn.net.cn

替代采样温度的方法,称为核采样。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.userspring-doc.cadn.net.cn

代表您最终用户的唯一标识符,这有助于OpenAI监控和检测滥用行为。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.parallel-tool-callsspring-doc.cadn.net.cn

是否在工具使用过程中启用并行函数调用。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.reasoning-effortspring-doc.cadn.net.cn

约束推理模型的推理努力:lowmedium,或highspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.verbosityspring-doc.cadn.net.cn

控制模型响应的详细程度。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.storespring-doc.cadn.net.cn

是否存储本次聊天补全请求的输出,以便在OpenAI的产品模型蒸馏或evals中使用。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.metadataspring-doc.cadn.net.cn

来自Java开发中Spring AI框架文档网站的开发者定义的标签和值,用于筛选仪表盘中的完成项。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.service-tierspring-doc.cadn.net.cn

指定要使用的延迟层级:autodefaultflexpriorityspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.stream-options.include-usagespring-doc.cadn.net.cn

是否在流式响应中包含使用统计信息。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.stream-options.include-obfuscationspring-doc.cadn.net.cn

是否在流式响应中包含混淆。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.tool-choicespring-doc.cadn.net.cn

控制模型调用哪个(如果有的话)功能。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.chat.options.internal-tool-execution-enabledspring-doc.cadn.net.cn

如果为false,则Spring AI将代理工具调用至客户端进行手动处理。如果为true(默认值),Spring AI将内部处理函数调用。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

使用GPT-5模型(如gpt-5gpt-5-minigpt-5-nano),不支持temperature参数。 这些模型优化用于推理,并且不会使用温度值。 指定温度值将导致错误。 相比之下,对话模型(如gpt-5-chat)支持temperature参数。spring-doc.cadn.net.cn

所有以spring.ai.openai-sdk.chat.options开头的属性可以在运行时通过向Prompt调用添加请求特定的运行时选项来覆盖。

Token 限制 参数:模型特定用法

OpenAI 提供了两个互斥参数以控制Tokens生成限制:spring-doc.cadn.net.cn

参数 用例 兼容模型

maxTokensspring-doc.cadn.net.cn

非推理模型spring-doc.cadn.net.cn

gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbospring-doc.cadn.net.cn

maxCompletionTokensspring-doc.cadn.net.cn

推理模型spring-doc.cadn.net.cn

o1, o1-mini, o1-preview, o3, o4-mini系列spring-doc.cadn.net.cn

这些参数是互斥的。同时设置这两个参数会导致从OpenAI返回API错误。

使用示例

非推理模型(gpt-4o,gpt-3.5-turbo):spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Explain quantum computing in simple terms.",
        OpenAiSdkChatOptions.builder()
            .model("gpt-4o")
            .maxTokens(150)  // Use maxTokens for non-reasoning models
        .build()
    ));

对于推理模型(o1、o3系列):spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Solve this complex math problem step by step: ...",
        OpenAiSdkChatOptions.builder()
            .model("o1-preview")
            .maxCompletionTokens(1000)  // Use maxCompletionTokens for reasoning models
        .build()
    ));

运行时选项

The OpenAiSdkChatOptions.java 类提供了模型配置,例如要使用的模型、温度、频率惩罚等。spring-doc.cadn.net.cn

启动时,可以使用OpenAiSdkChatModel(options)构造函数或spring.ai.openai-sdk.chat.options.*属性来配置默认选项。spring-doc.cadn.net.cn

在运行时,您可以通过向Prompt调用添加新的、针对请求的选项来覆盖默认选项。 例如,要为特定请求覆盖默认模型和温度设置:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OpenAiSdkChatOptions.builder()
            .model("gpt-4o")
            .temperature(0.4)
        .build()
    ));
除了特定模型的OpenAiSdkChatOptions之外,您还可以使用一个便携式的ChatOptions实例,该实例通过ChatOptions#builder()创建。

工具调用

您可以将自定义的Java函数或方法注册到OpenAiSdkChatModel,并让OpenAI模型智能地选择输出一个包含调用一个或多个已注册函数/工具参数的JSON对象。 这是一种强大的技术,可以将LLM的能力与外部工具和API连接起来。 要了解更多信息,请参阅工具调用.spring-doc.cadn.net.cn

示例用法:spring-doc.cadn.net.cn

var chatOptions = OpenAiSdkChatOptions.builder()
    .toolCallbacks(List.of(
        FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
            .description("Get the weather in location")
            .inputType(WeatherService.Request.class)
            .build()))
    .build();

ChatResponse response = chatModel.call(
    new Prompt("What's the weather like in San Francisco?", chatOptions));

多模态

多模态指的是模型同时理解和处理来自多种来源的信息的能力,包括文本、图像、音频以及其他数据格式。spring-doc.cadn.net.cn

视觉

OpenAI 模型中提供视觉多模态支持的包括 gpt-4gpt-4ogpt-4o-mini。 请参阅 视觉 指南以获取更多信息。spring-doc.cadn.net.cn

Spring AI的Message接口通过引入Media类型来促进多模态AI模型。spring-doc.cadn.net.cn

<p>以下是一个代码示例,展示了用户文本与图像的融合:</p>spring-doc.cadn.net.cn

var imageResource = new ClassPathResource("/multimodal.test.png");

var userMessage = new UserMessage(
    "Explain what do you see on this picture?",
    List.of(new Media(MimeTypeUtils.IMAGE_PNG, imageResource)));

ChatResponse response = chatModel.call(
    new Prompt(userMessage,
        OpenAiSdkChatOptions.builder()
            .model("gpt-4o")
            .build()));

使用图像URL:spring-doc.cadn.net.cn

var userMessage = new UserMessage(
    "Explain what do you see on this picture?",
    List.of(Media.builder()
        .mimeType(MimeTypeUtils.IMAGE_PNG)
        .data(URI.create("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png"))
        .build()));

ChatResponse response = chatModel.call(new Prompt(userMessage));
您可以传递多张图片。

音频

Spring AI框架文档中支持音频输入的OpenAI模型包括gpt-4o-audio-preview。 参见音频指南以获取更多信息。spring-doc.cadn.net.cn

Spring AI 支持以 base64 编码的音频文件。 目前,OpenAI 支持以下媒体类型:audio/mp3audio/wav.spring-doc.cadn.net.cn

示例音频输入:spring-doc.cadn.net.cn

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(userMessage,
        OpenAiSdkChatOptions.builder()
            .model("gpt-4o-audio-preview")
            .build()));

输出音频

gpt-4o-audio-preview 模型可以生成音频响应。spring-doc.cadn.net.cn

生成音频输出的示例:spring-doc.cadn.net.cn

var userMessage = new UserMessage("Tell me a joke about Spring Framework");

ChatResponse response = chatModel.call(
    new Prompt(userMessage,
        OpenAiSdkChatOptions.builder()
            .model("gpt-4o-audio-preview")
            .outputModalities(List.of("text", "audio"))
            .outputAudio(new AudioParameters(Voice.ALLOY, AudioResponseFormat.WAV))
            .build()));

String text = response.getResult().getOutput().getText(); // audio transcript
byte[] waveAudio = response.getResult().getOutput().getMedia().get(0).getDataAsByteArray(); // audio data

结构化输出

OpenAI 提供自定义的 结构化输出 API,确保您的模型生成的响应严格符合您提供的 JSON Schemaspring-doc.cadn.net.cn

配置

您可以使用OpenAiSdkChatOptions构建器编程设置响应格式:spring-doc.cadn.net.cn

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",
    OpenAiSdkChatOptions.builder()
        .model("gpt-4o-mini")
        .responseFormat(ResponseFormat.builder()
            .type(ResponseFormat.Type.JSON_SCHEMA)
            .jsonSchema(jsonSchema)
            .build())
        .build());

ChatResponse response = chatModel.call(prompt);

与 BeanOutputConverter 集成

您可以利用现有的 BeanOutputConverter 工具:spring-doc.cadn.net.cn

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);
String jsonSchema = outputConverter.getJsonSchema();

Prompt prompt = new Prompt(
    "how can I solve 8x + 7 = -23",
    OpenAiSdkChatOptions.builder()
        .model("gpt-4o-mini")
        .responseFormat(ResponseFormat.builder()
            .type(ResponseFormat.Type.JSON_SCHEMA)
            .jsonSchema(jsonSchema)
            .build())
        .build());

ChatResponse response = chatModel.call(prompt);
MathReasoning mathReasoning = outputConverter.convert(
    response.getResult().getOutput().getText());

样本控制器

创建一个新的Spring Boot项目,并在pom(或gradle)依赖中添加spring-ai-openai-sdkspring-doc.cadn.net.cn

src/main/resources 目录下添加一个 application.properties 文件,以配置 OpenAI SDK 聊天模型:spring-doc.cadn.net.cn

spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.chat.options.model=gpt-5-mini
spring.ai.openai-sdk.chat.options.temperature=0.7
替换api-key为您自己的OpenAI凭据。

这将创建一个OpenAiSdkChatModel实现,您可以将其注入到您的类中。 以下是一个简单的@RestController类的示例,该类使用聊天模型进行文本生成。spring-doc.cadn.net.cn

@RestController
public class ChatController {

    private final OpenAiSdkChatModel chatModel;

    @Autowired
    public ChatController(OpenAiSdkChatModel 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", 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 chatModel.stream(prompt);
    }
}

手动配置

OpenAiSdkChatModel 实现了 ChatModel,并使用官方的 OpenAI Java SDK 连接到 OpenAI 服务。spring-doc.cadn.net.cn

将如下的spring-ai-openai-sdk依赖添加到项目中Maven的pom.xml文件中:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-sdk</artifactId>
</dependency>

或添加到您的 Gradle build.gradle 构建文件中:spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-sdk'
}
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。

接下来,创建一个 OpenAiSdkChatModel 并将其用于文本生成:spring-doc.cadn.net.cn

var chatOptions = OpenAiSdkChatOptions.builder()
    .model("gpt-4o")
    .temperature(0.7)
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var chatModel = OpenAiSdkChatModel.builder()
    .options(chatOptions)
    .build();

ChatResponse response = chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

// Or with streaming responses
Flux<ChatResponse> response = chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

Microsoft Foundry 配置

对于 Microsoft Foundry:spring-doc.cadn.net.cn

var chatOptions = OpenAiSdkChatOptions.builder()
    .baseUrl("https://your-resource.openai.azure.com")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .deploymentName("gpt-4")
    .azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
    .azure(true)  // Enables Microsoft Foundry mode
    .build();

var chatModel = OpenAiSdkChatModel.builder()
    .options(chatOptions)
    .build();
Microsoft Foundry 支持无密码认证。请将 com.azure:azure-identity 依赖项添加到您的项目中。如果您未提供 API 密钥,实现将自动尝试使用您环境中的 Azure 凭证。

GitHub 模型配置

对于 GitHub 模型:spring-doc.cadn.net.cn

var chatOptions = OpenAiSdkChatOptions.builder()
    .baseUrl("https://models.inference.ai.azure.com")
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .model("gpt-4o")
    .githubModels(true)
    .build();

var chatModel = OpenAiSdkChatModel.builder()
    .options(chatOptions)
    .build();

与 Spring AI OpenAI 的主要区别

此实现与 Spring AI OpenAI 实现在以下几个方面有所不同:spring-doc.cadn.net.cn

切面 OpenAI 官方 SDK 现有的 OpenAI

httpclientspring-doc.cadn.net.cn

OkHttp(通过官方 SDK)spring-doc.cadn.net.cn

Spring RestClient/WebClientspring-doc.cadn.net.cn

API 更新spring-doc.cadn.net.cn

通过 SDK 自动更新spring-doc.cadn.net.cn

手动维护spring-doc.cadn.net.cn

Azure 支持spring-doc.cadn.net.cn

原生支持无密码认证spring-doc.cadn.net.cn

手动构建 URLspring-doc.cadn.net.cn

GitHub 模型spring-doc.cadn.net.cn

原生支持spring-doc.cadn.net.cn

不支持spring-doc.cadn.net.cn

音频/审核spring-doc.cadn.net.cn

尚未支持spring-doc.cadn.net.cn

完全支持spring-doc.cadn.net.cn

重试逻辑spring-doc.cadn.net.cn

SDK 管理(指数退避)spring-doc.cadn.net.cn

Spring Retry(可自定义)spring-doc.cadn.net.cn

依赖项spring-doc.cadn.net.cn

OpenAI 官方 SDKspring-doc.cadn.net.cn

Spring WebFluxspring-doc.cadn.net.cn

何时使用 OpenAI SDK:spring-doc.cadn.net.cn

何时使用 Spring AI OpenAI:spring-doc.cadn.net.cn

可观测性

OpenAI SDK 实现通过 Micrometer 支持 Spring AI 的可观测性功能。 所有聊天模型操作均已植入监控和追踪功能。spring-doc.cadn.net.cn

限制

OpenAI SDK 实现中尚不支持以下功能:spring-doc.cadn.net.cn

这些功能可在 Spring AI OpenAI 实现中使用。spring-doc.cadn.net.cn