跳到主要内容

OpenAI SDK 聊天（官方）

Deepseek 3.2 中英对照 OpenAI SDK (Official) OpenAI SDK Chat (Official)

Spring AI通过OpenAI Java SDK支持OpenAI的语言模型，提供了与OpenAI服务（包括Microsoft Foundry和GitHub Models）的强大且官方维护的集成。

备注

该实现使用的是 OpenAI 官方的 OpenAI Java SDK。关于 Spring AI 的替代实现，请参阅 OpenAI Chat。

OpenAI SDK 模块会根据您提供的基础 URL 自动检测服务提供商（OpenAI、Microsoft Foundry 或 GitHub Models）。

身份验证​

认证通过基础URL和API密钥完成。该实现通过Spring Boot属性或环境变量提供灵活的配置选项。

使用 OpenAI​

如果您直接使用OpenAI，请在OpenAI注册页面创建账户，并在API密钥页面生成API密钥。

基础URL无需设置，其默认值为 [api.openai.com/v1](https://api.openai.com/v1)：

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

或者使用环境变量：

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

使用 Microsoft Foundry​

使用 Microsoft Foundry URL 时，系统会自动检测 Microsoft Foundry。您可以使用以下属性进行配置：

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>

或者使用环境变量：

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

无密码身份验证（推荐用于 Azure）：

Microsoft Foundry 支持无需提供 API 密钥的无密码身份验证，这在 Azure 上运行时更为安全。

要启用无密码身份验证，需添加 com.azure:azure-identity 依赖项：

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

然后配置时不使用 API 密钥：

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 在使用 GitHub Models 基础 URL 时会自动检测。您需要创建一个具有 models:read 范围的 GitHub 个人访问令牌 (PAT)。

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

或者使用环境变量：

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}

添加代码仓库与物料清单​

Spring AI的构件发布在Maven中央仓库和Spring快照仓库中。请参考构件仓库章节，将这些仓库添加到您的构建系统中。

为便于管理依赖，Spring AI 提供了物料清单（BOM），以确保在整个项目中使用一致的 Spring AI 版本。请参考依赖管理章节，将 Spring AI BOM 添加到您的构建系统中。

自动配置​

Spring AI 为 OpenAI SDK 聊天客户端提供了 Spring Boot 自动配置功能。要启用此功能，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>
提示

请参考 依赖管理 章节，将 Spring AI BOM 添加到你的构建文件中。

配置属性​

连接属性​

前缀 spring.ai.openai-sdk 用作属性前缀，允许你配置 OpenAI SDK 客户端。

属性描述默认值
spring.ai.openai-sdk.base-url连接到的 URL。如果未设置，则从 OPENAI_BASE_URL 环境变量自动检测。api.openai.com/v1
spring.ai.openai-sdk.api-keyAPI 密钥。如果未设置，则从 OPENAI_API_KEY 环境变量自动检测。-
spring.ai.openai-sdk.organization-id可选地指定用于 API 请求的组织。-
spring.ai.openai-sdk.timeout请求超时时长。-
spring.ai.openai-sdk.max-retries失败请求的最大重试次数。-
spring.ai.openai-sdk.proxyOpenAI 客户端的代理设置（Java Proxy 对象）。-
spring.ai.openai-sdk.custom-headers要在请求中包含的自定义 HTTP 头。头部名称到头部值的映射。-

Microsoft Foundry (Azure OpenAI) 属性​

OpenAI SDK 实现为 Microsoft Foundry (Azure OpenAI) 提供了原生支持，并具备自动配置功能：

属性描述默认值
spring.ai.openai-sdk.microsoft-foundry启用 Microsoft Foundry 模式。如果基础 URL 包含 openai.azure.com、cognitiveservices.azure.com 或 .openai.microsoftFoundry.com 则自动检测。false
spring.ai.openai-sdk.microsoft-deployment-nameMicrosoft Foundry 部署名称。如果未指定，将使用模型名称。也可通过别名 deployment-name 访问。-
spring.ai.openai-sdk.microsoft-foundry-service-versionMicrosoft Foundry API 服务版本。-
spring.ai.openai-sdk.credential用于无密码身份验证的凭据对象（需要 com.azure:azure-identity 依赖项）。-
提示

Microsoft Foundry 支持无密码身份验证。添加 com.azure:azure-identity 依赖项，当未提供 API 密钥时，实现将自动尝试使用来自环境的 Azure 凭据。

GitHub 模型属性​

对GitHub模型的原生支持现已可用：

属性描述默认值
spring.ai.openai-sdk.github-models启用 GitHub Models 模式。如果基础 URL 包含 models.github.ai 或 models.inference.ai.azure.com 则自动检测。false

:::提示
GitHub Models 需要使用具有 models:read 范围的个人访问令牌。可以通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性进行设置。
:::

聊天模型属性​

前缀 spring.ai.openai-sdk.chat 是用于配置聊天模型实现的属性前缀：

属性描述默认
spring.ai.openai-sdk.chat.options.model要使用的 OpenAI 聊天模型的名称。您可以选择以下模型：gpt-5-mini、gpt-4o、gpt-4o-mini、gpt-4-turbo、o1、o3-mini 等。更多信息请参阅 models 页面。gpt-5-mini
spring.ai.openai-sdk.chat.options.temperature采样温度（temperature）用于控制生成内容的表观创造性。较高的数值会使输出更具随机性，而较低的数值则会使结果更加集中和确定。不建议在同一个补全请求中同时修改 temperature 和 top_p 参数，因为这两个设置之间的交互作用难以预测。1.0
spring.ai.openai-sdk.chat.options.frequency-penalty介于-2.0到2.0之间的数值。正值会根据新标记在文本中已出现的频率对其进行惩罚，从而降低模型逐字重复相同内容的可能性。0.0
spring.ai.openai-sdk.chat.options.logit-bias修改指定令牌在完成中出现的可能性。-
spring.ai.openai-sdk.chat.options.logprobs是否返回输出词元的对数概率。假
spring.ai.openai-sdk.chat.options.top-logprobs一个介于0到5之间的整数，指定在每个令牌位置返回最可能令牌的数量。需要将 logprobs 设置为 true。-
spring.ai.openai-sdk.chat.options.max-tokens生成的最大令牌数。适用于非推理模型（例如，gpt-4o、gpt-3.5-turbo）。不能用于推理模型（例如，o1、o3、o4-mini 系列）。与 maxCompletionTokens 互斥。-
spring.ai.openai-sdk.chat.options.max-completion-tokens完成生成所能产生的令牌数量上限，包括可见输出令牌和推理令牌。推理模型必须设置此参数（例如 o1、o3、o4-mini 系列）。不可与非推理模型一起使用。与 maxTokens 参数互斥。-
spring.ai.openai-sdk.chat.options.n为每条输入消息生成多少个聊天完成选项。1
spring.ai.openai-sdk.chat.options.output-modalities输出模态列表。可包含“文本”和“音频”。-
spring.ai.openai-sdk.chat.options.output-audio音频输出参数。使用 AudioParameters，需指定语音（ALLOY、ASH、BALLAD、CORAL、ECHO、FABLE、ONYX、NOVA、SAGE、SHIMMER）和格式（MP3、FLAC、OPUS、PCM16、WAV、AAC）。-
spring.ai.openai-sdk.chat.options.presence-penalty数值介于 -2.0 到 2.0 之间。正值会根据新标记是否已在当前文本中出现来对其进行惩罚。0.0
spring.ai.openai-sdk.chat.options.response-format.type响应格式类型：TEXT、JSON_OBJECT 或 JSON_SCHEMA。文本
spring.ai.openai-sdk.chat.options.response-format.json-schema当类型为 JSON_SCHEMA 时结构化输出的 JSON 模式。-
spring.ai.openai-sdk.chat.options.seed若指定此参数，系统将尽最大努力进行确定性采样，以确保结果的可重现性。-
spring.ai.openai-sdk.chat.options.stop最多 4 个序列，API 将在这些序列处停止生成更多 token。-
spring.ai.openai-sdk.chat.options.top-p另一种替代温度采样的方法是核采样。-
spring.ai.openai-sdk.chat.options.user一个代表您终端用户的唯一标识符，可帮助OpenAI监控和检测滥用行为。-
spring.ai.openai-sdk.chat.options.parallel-tool-calls是否在工具使用期间启用并行函数调用。真
spring.ai.openai-sdk.chat.options.reasoning-effort限制推理模型在推理上的努力程度：低、中或高。-
spring.ai.openai-sdk.chat.options.verbosity控制模型响应的详细程度。-
spring.ai.openai-sdk.chat.options.store是否存储此聊天完成请求的输出，以便用于OpenAI的模型蒸馏或评估产品。false
spring.ai.openai-sdk.chat.options.metadata开发者定义的标签和值，用于在仪表板中筛选完成项。-
spring.ai.openai-sdk.chat.options.service-tier指定要使用的延迟层级：auto、default、flex 或 priority。-
spring.ai.openai-sdk.chat.options.stream-options.include-usage是否在流式响应中包含使用统计信息。false
spring.ai.openai-sdk.chat.options.stream-options.include-obfuscation是否在流式响应中包含混淆处理。false
spring.ai.openai-sdk.chat.options.tool-choice控制模型调用哪个（如果有）函数。-
spring.ai.openai-sdk.chat.options.internal-tool-execution-enabled若为 false，Spring AI 会将工具调用代理至客户端进行手动处理。若为 true（默认值），Spring AI 将在内部处理函数调用。真

:::注意
在使用 GPT-5 模型（例如 gpt-5、gpt-5-mini 和 gpt-5-nano）时，不支持 temperature 参数。这些模型针对推理任务进行了优化，不使用温度参数。指定温度值将导致错误。相比之下，对话模型（例如 gpt-5-chat）支持 temperature 参数。
:::

提示

所有以 spring.ai.openai-sdk.chat.options 为前缀的属性，都可以通过在 Prompt 调用中添加请求特定的运行时选项来在运行时被覆盖。

Token Limit Parameters: Model-Specific Usage​

OpenAI提供了两个互斥参数用于控制token生成限制：

参数使用场景兼容模型
maxTokens非推理模型gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
maxCompletionTokens推理模型o1, o1-mini, o1-preview, o3, o4-mini 系列

:::重要
这些参数互斥。同时设置两者将导致来自OpenAI的API错误。
:::

使用示例​

对于非推理模型（gpt-4o、gpt-3.5-turbo）：

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系列）：

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

运行时选项​

OpenAiSdkChatOptions.java 类提供了模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可以通过 OpenAiSdkChatModel(options) 构造函数或 spring.ai.openai-sdk.chat.options.* 属性来配置默认选项。

在运行时，你可以通过向 Prompt 调用添加新的、特定于请求的选项来覆盖默认选项。例如，要为特定请求覆盖默认模型和温度参数：

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() 创建。

工具调用​

您可以为OpenAiSdkChatModel注册自定义的Java函数或方法，并让OpenAI模型智能地选择输出一个JSON对象，该对象包含调用一个或多个已注册函数/工具所需的参数。这是一种将大语言模型能力与外部工具及API连接起来的强大技术。了解更多关于工具调用的信息。

示例用法：

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

多模态​

多模态是指模型同时理解和处理来自不同来源信息的能力，这些信息包括文本、图像、音频以及其他数据格式。

愿景​

具备视觉多模态支持的 OpenAI 模型包括 gpt-4、gpt-4o 和 gpt-4o-mini。更多信息请参阅 Vision 指南。

Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 AI 模型。

以下是一个将用户文本与图像融合的代码示例：

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：

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

您也可以传入多张图片。

音频​

提供音频输入支持的OpenAI模型包括 gpt-4o-audio-preview。更多信息请参阅音频指南。

Spring AI 支持在消息中附带 base64 编码的音频文件。目前，OpenAI 支持以下媒体类型：audio/mp3 和 audio/wav。

音频输入示例：

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 模型能够生成音频响应。

生成音频输出的示例：

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().getContent(); // audio transcript
byte[] waveAudio = response.getResult().getOutput().getMedia().get(0).getDataAsByteArray(); // audio data

结构化输出​

OpenAI 提供定制化的结构化输出 API，确保您的模型生成严格遵守所提供 JSON Schema 的响应。

配置​

你可以通过OpenAiSdkChatOptions构建器以编程方式设置响应格式：

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 工具：

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().getContent());

示例控制器​

创建一个新的Spring Boot项目，并在你的pom（或gradle）依赖中添加 spring-ai-openai-sdk。

在 src/main/resources 目录下添加一个 application.properties 文件来配置 OpenAI SDK 聊天模型：

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 类的示例，它使用该聊天模型进行文本生成。

@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-ai-openai-sdk 依赖添加到你的项目的 Maven pom.xml 文件中：

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

或者添加到你的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-sdk'
}
提示

请参考依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

接下来，创建一个 OpenAiSdkChatModel 并使用它进行文本生成：

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

var chatModel = new OpenAiSdkChatModel(chatOptions);

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：

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 = new OpenAiSdkChatModel(chatOptions);
提示

Microsoft Foundry 支持无密码身份验证。将 com.azure:azure-identity 依赖项添加到你的项目中。如果你不提供 API 密钥，实现将自动尝试使用你环境中的 Azure 凭据。

GitHub 模型配置​

对于 GitHub 模型：

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

var chatModel = new OpenAiSdkChatModel(chatOptions);

与 Spring AI OpenAI 的主要区别​

此实现与 Spring AI OpenAI 实现存在以下差异：

维度官方 OpenAI SDK现有 OpenAI 实现
HTTP 客户端OkHttp (通过官方 SDK)Spring RestClient/WebClient
API 更新通过 SDK 更新自动获取手动维护
Azure 支持原生支持无密码认证手动构建 URL
GitHub Models原生支持不支持
音频/内容审核暂不支持完全支持
重试逻辑SDK 管理 (指数退避)Spring Retry (可定制)
依赖项官方 OpenAI SDKSpring WebFlux

何时使用 OpenAI SDK：

  • 你正在启动一个新项目

  • 你主要使用 Microsoft Foundry 或 GitHub Models

  • 你希望获得来自 OpenAI 的自动 API 更新

  • 你不需要音频转录或内容审核功能

  • 你更倾向于官方的 SDK 支持

何时使用 Spring AI OpenAI：

  • 你已有使用该项目的现有项目

  • 你需要音频转录或审核功能

  • 你需要细粒度的 HTTP 控制

  • 你想要原生的 Spring 响应式支持

  • 你需要自定义的重试策略

可观测性​

OpenAI SDK 实现通过 Micrometer 支持 Spring AI 的可观测性功能。所有聊天模型操作都进行了监测和追踪的仪表化配置。

局限性​

OpenAI SDK 实现中暂不支持以下功能：

  • 音频语音生成（TTS）

  • 音频转录

  • 审核 API

  • 文件 API 操作

这些特性已在 Spring AI OpenAI 实现中提供。

附加资源​