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

OpenAI 聊天

Spring AI 支持来自 OpenAI 的各种 AI 语言模型，OpenAI 是 ChatGPT 背后的公司，凭借其创建的行业领先的文本生成模型和嵌入技术，在激发人们对 AI 驱动文本生成的兴趣方面发挥了重要作用。spring-doc.cadn.net.cn

前置条件

您需要创建一个 OpenAI API 以访问 ChatGPT 模型。spring-doc.cadn.net.cn

在 OpenAI 注册页面 创建账户，并在 API 密钥页面 生成Tokens。spring-doc.cadn.net.cn

Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，您应将其设置为从 openai.com 获取的 API Key 的值。spring-doc.cadn.net.cn

您可以在您的application.properties文件中设置此配置属性：spring-doc.cadn.net.cn

spring.ai.openai.api-key=<your-openai-api-key>

处理敏感信息（如API密钥）时，为了增强安全性，您可以使用Spring表达式语言（SpEL）引用自定义环境变量：spring-doc.cadn.net.cn

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>

您也可以在应用程序代码中通过编程方式设置此配置：spring-doc.cadn.net.cn

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("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自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。spring-doc.cadn.net.cn

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

<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-doc.cadn.net.cn

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

spring.ai.retry.max-attemptsspring-doc.cadn.net.cn

最大重试尝试次数。spring-doc.cadn.net.cn

10spring-doc.cadn.net.cn

spring.ai.retry.backoff.initial-intervalspring-doc.cadn.net.cn

指数退避策略的初始睡眠时长。spring-doc.cadn.net.cn

2 秒。spring-doc.cadn.net.cn

spring.ai.retry.backoff.multiplierspring-doc.cadn.net.cn

重试间隔倍数。spring-doc.cadn.net.cn

5spring-doc.cadn.net.cn

spring.ai.retry.backoff.max-intervalspring-doc.cadn.net.cn

最大退避持续时间。spring-doc.cadn.net.cn

3 min.spring-doc.cadn.net.cn

spring.ai.retry.on-client-errorsspring-doc.cadn.net.cn

如果为假，则抛出一个NonTransientAiException，并且不尝试重试4xx客户端错误代码spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.retry.exclude-on-http-codesspring-doc.cadn.net.cn

不应当触发重试的HTTP状态码列表（例如，抛出NonTransientAiException）。spring-doc.cadn.net.cn

<p>空内容</p>spring-doc.cadn.net.cn

spring.ai.retry.on-http-codesspring-doc.cadn.net.cn

应触发重试的HTTP状态码列表（例如，抛出TransientAiException）。spring-doc.cadn.net.cn

<p>空内容</p>spring-doc.cadn.net.cn

连接属性

使用前缀spring.ai.openai作为属性前缀，以便连接到OpenAI。spring-doc.cadn.net.cn

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

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

连接的URLspring-doc.cadn.net.cn

api.openai.comspring-doc.cadn.net.cn

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

API密钥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

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

-spring-doc.cadn.net.cn

spring.ai.openai.project-idspring-doc.cadn.net.cn

可选地，您可以指定用于 API 请求的项目。spring-doc.cadn.net.cn

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

User-Agent 标头

Spring AI 会自动向所有发往 OpenAI 的请求发送一个 User-Agent: spring-ai 请求头。 这有助于 OpenAI 识别源自 Spring AI 的请求，以便进行分析和提供支持。 该请求头会自动发送，Spring AI 用户无需进行任何配置。spring-doc.cadn.net.cn

如果您是构建 OpenAI 兼容服务的 API 提供商，您可以通过读取服务器上传入请求中的 User-Agent HTTP 头来跟踪 Spring AI 的使用情况。spring-doc.cadn.net.cn

配置属性

现在通过带有前缀spring.ai.model.chat的顶级属性来配置聊天自动配置的启用和禁用。spring-doc.cadn.net.cn

要启用，请设置：spring.ai.model.chat=openai（默认已启用）spring-doc.cadn.net.cn

要禁用，请设置 spring.ai.model.chat=none （或任何与 openai 匹配的值）spring-doc.cadn.net.cn

此更改是为了允许配置多个模型。spring-doc.cadn.net.cn

spring.ai.openai.chat 前缀是属性前缀，允许你配置与 OpenAI 的聊天模型实现相关的设置。spring-doc.cadn.net.cn

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

spring.ai.openai.chat.enabled (已删除且不再有效)spring-doc.cadn.net.cn

启用OpenAI聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.model.chatspring-doc.cadn.net.cn

启用OpenAI聊天模型。spring-doc.cadn.net.cn

OpenAIspring-doc.cadn.net.cn

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

可选覆盖 spring.ai.openai.base-url 属性，以提供特定于聊天的 URL。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.completions-pathspring-doc.cadn.net.cn

在基础URL后面附加的路径。spring-doc.cadn.net.cn

/v1/chat/completionsspring-doc.cadn.net.cn

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

可选覆盖 spring.ai.openai.api-key 以提供特定于聊天的 API 密钥。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

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

-spring-doc.cadn.net.cn

spring.ai.openai.chat.project-idspring-doc.cadn.net.cn

可选地，您可以指定用于 API 请求的项目。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

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

gpt-4o-minispring-doc.cadn.net.cn

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

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

0.8spring-doc.cadn.net.cn

spring.ai.openai.chat.options.frequencyPenaltyspring-doc.cadn.net.cn

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

0.0fspring-doc.cadn.net.cn

spring.ai.openai.chat.options.logitBiasspring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.maxTokensspring-doc.cadn.net.cn

聊天补全中生成的最大Tokens数。输入Tokens和生成Tokens的总长度受模型的上下文长度限制。用于非推理模型（例如，gpt-4o、gpt-3.5-turbo）。不能与推理模型一起使用（例如，o1、o3、o4-mini 系列）。与 maxCompletionTokens 互斥 - 同时设置两者将导致 API 错误。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.maxCompletionTokensspring-doc.cadn.net.cn

完成生成时可生成的Tokens数量上限，包括可见输出Tokens和推理Tokens。推理模型必需（例如 o1、o3、o4-mini 系列）。不能与非推理模型一起使用（例如 gpt-4o、gpt-3.5-turbo）。与 maxTokens 互斥——同时设置两者将导致 API 错误。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

为每个输入消息生成的聊天补全选项数量。请注意，您将根据所有选项中生成的Tokens总数被收费。将 n 保持为 1 以最小化成本。spring-doc.cadn.net.cn

1spring-doc.cadn.net.cn

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

是否存储此聊天补全请求的输出以供我们的模型使用spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

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

开发者定义的标签和值，用于在聊天补全仪表板中过滤补全结果spring-doc.cadn.net.cn

空映射spring-doc.cadn.net.cn

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

您希望模型为此请求生成的输出类型。大多数模型默认能够生成文本。 gpt-4o-audio-preview 模型还可用于生成音频。若请求该模型同时生成文本和音频响应， 可使用：text、audio。不支持流式传输。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

音频生成所需的音频参数。当请求使用 output-modalities: audio 进行音频输出时必须提供。 需要 gpt-4o-audio-preview 模型，且不支持流式补全。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.presencePenaltyspring-doc.cadn.net.cn

在-2.0到2.0之间的数字。正数值根据新词在整个文本中出现的频率来惩罚新的词汇，从而增加模型讨论新话题的可能性。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.responseFormat.typespring-doc.cadn.net.cn

兼容 GPT-4o、GPT-4o mini、GPT-4 Turbo 以及所有晚于 gpt-3.5-turbo-1106 的 GPT-3.5 Turbo 模型。JSON_OBJECT 类型启用 JSON 模式，可确保模型生成的消息是有效的 JSON。 JSON_SCHEMA 类型启用 结构化输出，可确保模型匹配您提供的 JSON 架构。JSON_SCHEMA 类型还需要设置 responseFormat.schema 属性。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.responseFormat.namespring-doc.cadn.net.cn

响应格式架构名称。仅适用于 responseFormat.type=JSON_SCHEMAspring-doc.cadn.net.cn

custom_schemaspring-doc.cadn.net.cn

spring.ai.openai.chat.options.responseFormat.schemaspring-doc.cadn.net.cn

响应格式为JSON方案。仅适用于responseFormat.type=JSON_SCHEMA。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.responseFormat.strictspring-doc.cadn.net.cn

响应格式 JSON 架构的严格遵循性。仅适用于 responseFormat.type=JSON_SCHEMAspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

此功能处于测试版。如指定，我们的系统将尽力进行确定性采样，这意味着使用相同的种子和参数重复请求应返回相同的结果。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

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

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.topPspring-doc.cadn.net.cn

一种替代温度采样的方法，称为核采样（nucleus sampling），模型仅考虑累积概率质量为 top_p 的Tokens结果。因此，0.1 表示仅考虑占据前 10% 概率质量的Tokens。我们通常建议调整此参数或 temperature，但不要同时调整两者。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.toolsspring-doc.cadn.net.cn

模型可能调用的工具列表。目前，仅支持函数作为工具。使用此选项提供模型可以生成JSON输入的函数列表。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.toolChoicespring-doc.cadn.net.cn

控制模型调用哪个（如果有的话）函数。none表示模型不会调用任何函数，而是生成一条消息。auto表示模型可以选择生成一条消息或调用一个函数。{"type: "function", "function": {"name": "my_function"}}通过指定特定的函数来强制模型调用该函数。none当没有提供函数时是默认值。auto当提供了函数时是默认值。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

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

-spring-doc.cadn.net.cn

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

(仅适用于流式传输) 设置以添加一个额外的分块，其中包含整个请求的 token 使用统计信息。此分块的 choices 字段为空数组，所有其他分块也将包含一个 usage 字段，但其值为 null。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

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

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

truespring-doc.cadn.net.cn

spring.ai.openai.chat.options.prompt-cache-keyspring-doc.cadn.net.cn

OpenAI 用于优化相似请求缓存命中率的缓存键。可降低延迟并减少成本。已取代用于缓存目的的弃用字段 user。了解更多。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.safety-identifierspring-doc.cadn.net.cn

一个稳定的标识符，用于帮助 OpenAI 检测违反使用政策的用户。应为哈希值（例如，用户名或邮箱的哈希）。此字段取代了已弃用的 user 字段，用于安全追踪。了解更多。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.http-headersspring-doc.cadn.net.cn

可选的 HTTP 请求头，用于添加到聊天补全请求中。若要覆盖 api-key，您需要使用一个 Authorization 请求头键，并且必须在该键值前加上 Bearer 前缀。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

使用名称标识的工具列表，以在单个提示请求中启用功能调用。具有这些名称的工具必须存在于ToolCallback注册表中。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

使用回调注册与ChatModel相关的工具。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

如果为假，Spring AI 将不会内部处理工具调用，而是将它们代理给客户端。然后需要由客户端负责处理这些工具调用、将其分派到适当的函数，并返回结果。如果为真（默认值），Spring AI 将会内部处理这些函数调用。仅适用于支持功能调用的聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

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

指定用于处理请求的处理类型。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.chat.options.extra-bodyspring-doc.cadn.net.cn

请求中包含的额外参数。接受任何键值对，这些键值对将被扁平化到 JSON 请求的顶层。旨在与支持超出标准 OpenAI API 参数的 OpenAI 兼容服务器（如 vLLM、Ollama 等）配合使用。官方 OpenAI API 会忽略未知参数。详见 在 OpenAI 兼容服务器上使用额外参数。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

使用GPT-5模型（如gpt-5、gpt-5-mini和gpt-5-nano），不支持temperature参数。 这些模型优化用于推理，并且不会使用温度值。 指定温度值将导致错误。 相比之下，对话模型（如gpt-5-chat）支持temperature参数。spring-doc.cadn.net.cn
您可以为 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调用添加请求特定的运行时选项来覆盖。

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.",
        OpenAiChatOptions.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: ...",
        OpenAiChatOptions.builder()
            .model("o1-preview")
            .maxCompletionTokens(1000)  // Use maxCompletionTokens for reasoning models
        .build()
    ));

构建器模式验证： OpenAI ChatOptions 构建器自动通过“最后设置优先”的方式强制执行互斥性：spring-doc.cadn.net.cn

// This will automatically clear maxTokens and use maxCompletionTokens
OpenAiChatOptions options = OpenAiChatOptions.builder()
    .maxTokens(100)           // Set first
    .maxCompletionTokens(200) // This clears maxTokens and logs a warning
    .build();

// Result: maxTokens = null, maxCompletionTokens = 200

运行时选项

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

启动时，可以使用OpenAiChatModel(api, options)构造函数或spring.ai.openai.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.",
        OpenAiChatOptions.builder()
            .model("gpt-4o")
            .temperature(0.4)
        .build()
    ));
除了模型特定的 OpenAiChatOptions 之外，您还可以使用通过 ChatOptions#builder() 创建的可移植 ChatOptions 实例。

函数调用

您可以使用 OpenAiChatModel 注册自定义 Java 函数，并让 OpenAI 模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。 这是一种将大语言模型（LLM）能力与外部工具和 API 连接起来的强大技术。 阅读更多关于 工具调用 的信息。spring-doc.cadn.net.cn

多模态

多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。 OpenAI 支持文本、视觉和音频输入模态。spring-doc.cadn.net.cn

视觉

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

OpenAI 的 用户消息 API 可以在消息中整合经过 base64 编码的图片列表或图片 URL。 Spring AI 的 Message 接口通过引入 Media 类型，为多模态 AI 模型提供了支持。 该类型涵盖了消息中媒体附件的数据和详细信息，利用了 Spring 的 org.springframework.util.MimeType 和用于原始媒体数据的 org.springframework.core.io.Resource。spring-doc.cadn.net.cn

以下是从OpenAiChatModelIT.java摘取的一段代码示例，展示了使用gpt-4o模型将用户文本与图像融合的过程。spring-doc.cadn.net.cn

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：spring-doc.cadn.net.cn

var userMessage = new UserMessage("Explain what do you see on this picture?",
        new Media(MimeTypeUtils.IMAGE_PNG,
                URI.create("https://docs.spring.io/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图像：spring-doc.cadn.net.cn

Multimodal Test Image

<p> along with the text message &quot;请解释你在图片上看到了什么？&quot;, 并生成类似这样的响应：</p>spring-doc.cadn.net.cn

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。 请参阅 音频 指南以获取更多信息。spring-doc.cadn.net.cn

OpenAI 的 用户消息 API 可以在消息中包含一组 base64 编码的音频文件。 Spring AI 的 Message 接口通过引入 Media 类型，为多模态 AI 模型提供了支持。 该类型涵盖了消息中媒体附件的数据和详细信息，利用了 Spring 的 org.springframework.util.MimeType 和用于原始媒体数据的 org.springframework.core.io.Resource。 目前，OpenAI 仅支持以下媒体类型：audio/mp3 和 audio/wav。spring-doc.cadn.net.cn

以下是从 OpenAiChatModelIT.java 中摘录的代码示例，展示了如何使用 gpt-4o-audio-preview 模型将用户文本与音频文件融合。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(List.of(userMessage),
        OpenAiChatOptions.builder().model(OpenAiApi.ChatModel.GPT_4_O_AUDIO_PREVIEW).build()));
您也可以传递多个音频文件。

输出音频

提供输入音频多模态支持的 OpenAI 模型包括 gpt-4o-audio-preview。 请参阅 音频 指南以获取更多信息。spring-doc.cadn.net.cn

OpenAI 的 助手消息 API 可以在消息中包含一个经过 base64 编码的音频文件列表。 Spring AI 的 Message 接口通过引入 Media 类型，为多模态 AI 模型提供了支持。 该类型涵盖了消息中媒体附件的数据和详细信息，利用了 Spring 的 org.springframework.util.MimeType 以及用于原始媒体数据的 org.springframework.core.io.Resource。 目前，OpenAI 仅支持以下音频类型：audio/mp3 和 audio/wav。spring-doc.cadn.net.cn

下面是一个代码示例，展示了使用 gpt-4o-audio-preview 模型时用户文本及音频字节数组的响应：spring-doc.cadn.net.cn

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().getText(); // audio transcript

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

您必须在 OpenAiChatOptions 中指定一个 audio 模态以生成音频输出。 AudioParameters 类为音频输出提供语音和音频格式。spring-doc.cadn.net.cn

结构化输出

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

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

配置

Spring AI 允许您通过编程方式使用 OpenAiChatOptions 构建器，或通过应用程序属性来配置您的响应格式。spring-doc.cadn.net.cn

使用聊天选项构建器

您可以使用 OpenAiChatOptions 构建器以编程方式设置响应格式，如下所示：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",
        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 方案，并稍后将结构化的响应转换为特定于领域的实例：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);

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

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().getText()

val mathReasoning = outputConverter.convert(content)
尽管对于 JSON Schema 而言这是可选的，但 OpenAI 强制要求结构化响应必须包含必填字段才能正常运行。Kotlin 反射会根据类型的可空性和参数的默认值来推断哪些属性是必填的，因此在大多数用例中@get:JsonProperty(required = true)并非必需。@get:JsonProperty(value = "custom_name")可用于自定义属性名称。请确保使用此@get:语法在相关的 getter 方法上生成注解，详见相关文档。

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

或者，当使用 OpenAI 自动配置时，您可以通过以下应用程序属性配置所需的响应格式：spring-doc.cadn.net.cn

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项目，并在pom（或gradle）依赖中添加spring-ai-starter-model-openai。spring-doc.cadn.net.cn

在 src/main/resources 目录下添加一个 application.properties 文件，以启用并配置 OpenAi 聊天模型：spring-doc.cadn.net.cn

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类的示例，该类使用聊天模型进行文本生成。spring-doc.cadn.net.cn

@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-doc.cadn.net.cn

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

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

请将以下内容添加到您的Gradle build.gradle 构建文件中。spring-doc.cadn.net.cn

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

接下来，创建一个 OpenAiChatModel 并将其用于文本生成：spring-doc.cadn.net.cn

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 客户端和聊天配置的流程式选项构建器。spring-doc.cadn.net.cn

低级 OpenAiApi 客户端

OpenAiApi 提供了用于 OpenAI 聊天 API OpenAI Chat API 的轻量级 Java 客户端。spring-doc.cadn.net.cn

以下类图说明了OpenAiApi聊天接口和构建块：spring-doc.cadn.net.cn

OpenAiApi Chat API Diagram

这里是一个简单的示例，展示了如何通过编程方式使用API：spring-doc.cadn.net.cn

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 以获取更多信息。spring-doc.cadn.net.cn

低级API示例

底层 OpenAiFileApi 客户端

OpenAiFileApi 提供了一个轻量级的 Java 客户端，用于访问 OpenAI 文件 API，支持上传、列出、检索、删除文件以及访问文件内容等文件管理操作。OpenAI 文件 APIspring-doc.cadn.net.cn

这里是一个简单的示例，展示了如何通过编程方式使用API：spring-doc.cadn.net.cn

OpenAiFileApi openAiFileApi = OpenAiFileApi.builder()
			.apiKey(new SimpleApiKey(System.getenv("OPENAI_API_KEY")))
			.build();

// Upload a file
byte[] fileBytes = Files.readAllBytes(Paths.get("evals.jsonl"));
OpenAiFileApi.UploadFileRequest uploadRequest = OpenAiFileApi.UploadFileRequest.builder()
			.file(fileBytes)
			.fileName("evals-data.jsonl")
			.purpose(OpenAiFileApi.Purpose.EVALS)
			.build();
ResponseEntity<OpenAiFileApi.FileObject> uploadResponse = openAiFileApi.uploadFile(uploadRequest);

// List files
OpenAiFileApi.ListFileRequest listRequest = OpenAiFileApi.ListFileRequest.builder()
			.purpose(OpenAiFileApi.Purpose.EVALS)
			.build();
ResponseEntity<OpenAiFileApi.FileObjectResponse> listResponse = openAiFileApi.listFiles(listRequest);

// Retrieve file information
ResponseEntity<OpenAiFileApi.FileObject> fileInfo = openAiFileApi.retrieveFile("file-id");

// Delete a file
ResponseEntity<OpenAiFileApi.DeleteFileResponse> deleteResponse = openAiFileApi.deleteFile("file-id");

// Retrieve file content
ResponseEntity<String> fileContent = openAiFileApi.retrieveFileContent("file-id");

低级文件 API 示例

API 密钥管理

Spring AI 通过 ApiKey 接口及其实现提供灵活的 API 密钥管理。默认实现 SimpleApiKey 适用于大多数使用场景，但您也可以为更复杂的场景创建自定义实现。spring-doc.cadn.net.cn

默认配置

默认情况下，Spring Boot 自动配置会使用 spring.ai.openai.api-key 属性创建一个 API 密钥 bean：spring-doc.cadn.net.cn

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

自定义 API 密钥配置

您可以使用构建器模式，通过您自己的 ApiKey 实现创建 OpenAiApi 的自定义实例：spring-doc.cadn.net.cn

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 model with the custom OpenAiApi instance
OpenAiChatModel chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .build();
// Build the ChatClient using the custom chat model
ChatClient openAiChatClient = ChatClient.builder(chatModel).build();

这在以下情况下非常有用：spring-doc.cadn.net.cn

在兼容 OpenAI 的服务器上使用额外参数

像 vLLM、Ollama 等与 OpenAI 兼容的推理服务器，通常支持超出 OpenAI 标准 API 定义之外的额外参数。 例如，这些服务器可能接受诸如 top_k、repetition_penalty 或其他采样控制参数，而官方的 OpenAI API 并不识别这些参数。spring-doc.cadn.net.cn

extraBody 选项允许您向这些服务器传递任意参数。 在 extraBody 中提供的任何键值对都将包含在 JSON 请求的顶层，使您在使用 Spring AI 的 OpenAI 客户端时能够利用特定于服务器的功能。spring-doc.cadn.net.cn

extraBody 参数旨在用于兼容 OpenAI 的服务器，而非官方 OpenAI API。 虽然官方 OpenAI API 会忽略未知参数，但这些参数在其中并无实际用途。 请务必查阅您所使用特定服务器的文档，以确定支持哪些参数。spring-doc.cadn.net.cn

使用属性进行配置

您可以使用 Spring Boot 属性配置额外参数。 spring.ai.openai.chat.options.extra-body 下的每个属性都会成为请求中的顶级参数：spring-doc.cadn.net.cn

spring.ai.openai.base-url=http://localhost:8000
spring.ai.openai.chat.options.model=meta-llama/Llama-3-8B-Instruct
spring.ai.openai.chat.options.temperature=0.7
spring.ai.openai.chat.options.extra-body.top_k=50
spring.ai.openai.chat.options.extra-body.repetition_penalty=1.1

此配置将生成如下 JSON 请求：spring-doc.cadn.net.cn

{
  "model": "meta-llama/Llama-3-8B-Instruct",
  "temperature": 0.7,
  "top_k": 50,
  "repetition_penalty": 1.1,
  "messages": [...]
}

使用构建器进行运行时配置

您还可以在运行时使用选项构建器指定额外参数：spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Tell me a creative story",
        OpenAiChatOptions.builder()
            .model("meta-llama/Llama-3-8B-Instruct")
            .temperature(0.7)
            .extraBody(Map.of(
                "top_k", 50,
                "repetition_penalty", 1.1,
                "frequency_penalty", 0.5
            ))
            .build()
    ));

示例：vLLM 服务器

在运行带有 Llama 模型的 vLLM 时，您可能希望使用专用于 vLLM 的采样参数：spring-doc.cadn.net.cn

spring.ai.openai.base-url=http://localhost:8000
spring.ai.openai.chat.options.model=meta-llama/Llama-3-70B-Instruct
spring.ai.openai.chat.options.extra-body.top_k=40
spring.ai.openai.chat.options.extra-body.top_p=0.95
spring.ai.openai.chat.options.extra-body.repetition_penalty=1.05
spring.ai.openai.chat.options.extra-body.min_p=0.05

请参阅 vLLM 文档 以获取支持的采样参数完整列表。spring-doc.cadn.net.cn

示例：Ollama 服务器

当通过兼容 OpenAI 的端点使用 Ollama 时，您可以传递 Ollama 特有的参数：spring-doc.cadn.net.cn

OpenAiChatOptions options = OpenAiChatOptions.builder()
    .model("llama3.2")
    .extraBody(Map.of(
        "num_predict", 100,
        "top_k", 40,
        "repeat_penalty", 1.1
    ))
    .build();

ChatResponse response = chatModel.call(new Prompt("Generate text", options));

请参阅 Ollama API 文档 以了解可用参数。spring-doc.cadn.net.cn

extraBody 参数接受任何 Map<String, Object>，允许您传递目标服务器支持的任何参数。 Spring AI 不会验证这些参数——它们会直接传递给服务器。 这种设计为使用各种兼容 OpenAI 的实现提供了最大的灵活性。spring-doc.cadn.net.cn

来自推理模型的推理内容

一些支持推理模型（如 DeepSeek R1、带有推理解析器的 vLLM）的 OpenAI 兼容服务器，会通过其 API 响应中的 reasoning_content 字段暴露模型的内部思维链。 该字段包含了模型为得出最终答案所采用的逐步推理过程。spring-doc.cadn.net.cn

Spring AI 将此字段从 JSON 响应映射到 AssistantMessage 元数据中的 reasoningContent 键。spring-doc.cadn.net.cn

关于 reasoning_content 可用性的重要区别：spring-doc.cadn.net.cn

  • 兼容 OpenAI 的服务器（DeepSeek、vLLM）：在 Chat Completions API 响应中暴露 reasoning_content ✅spring-doc.cadn.net.cn

  • 官方 OpenAI 模型（GPT-5、o1、o3）：切勿在 Chat Completions API 响应中暴露推理文本 ❌spring-doc.cadn.net.cn

官方的 OpenAI 推理模型在使用 Chat Completions API 时会隐藏思维链内容。 它们仅在用量统计中暴露 reasoning_tokens 次计数。 若要访问官方 OpenAI 模型的实际推理文本，您必须使用 OpenAI 的 Responses API（这是一个单独的端点，当前此客户端尚不支持）。spring-doc.cadn.net.cn

回退行为：当服务器未提供 reasoning_content（例如，官方 OpenAI Chat Completions）时，reasoningContent 元数据字段将为空字符串。spring-doc.cadn.net.cn

访问推理内容

当使用兼容的服务器时，您可以从响应元数据中访问推理内容。spring-doc.cadn.net.cn

直接使用 ChatModel：spring-doc.cadn.net.cn

// Configure to use DeepSeek R1 or vLLM with a reasoning model
ChatResponse response = chatModel.call(
    new Prompt("Which number is larger: 9.11 or 9.8?")
);

// Get the assistant message
AssistantMessage message = response.getResult().getOutput();

// Access the reasoning content from metadata
String reasoning = message.getMetadata().get("reasoningContent");
if (reasoning != null && !reasoning.isEmpty()) {
    System.out.println("Model's reasoning process:");
    System.out.println(reasoning);
}

// The final answer is in the regular content
System.out.println("\nFinal answer:");
System.out.println(message.getContent());

使用 ChatClient：spring-doc.cadn.net.cn

ChatClient chatClient = ChatClient.create(chatModel);

String result = chatClient.prompt()
    .user("Which number is larger: 9.11 or 9.8?")
    .call()
    .chatResponse()
    .getResult()
    .getOutput()
    .getContent();

// To access reasoning content with ChatClient, retrieve the full response
ChatResponse response = chatClient.prompt()
    .user("Which number is larger: 9.11 or 9.8?")
    .call()
    .chatResponse();

AssistantMessage message = response.getResult().getOutput();
String reasoning = message.getMetadata().get("reasoningContent");

流式推理内容

在使用流式响应时，推理内容会像常规消息内容一样跨块累积：spring-doc.cadn.net.cn

Flux<ChatResponse> responseFlux = chatModel.stream(
    new Prompt("Solve this logic puzzle...")
);

StringBuilder reasoning = new StringBuilder();
StringBuilder answer = new StringBuilder();

responseFlux.subscribe(chunk -> {
    AssistantMessage message = chunk.getResult().getOutput();

    // Accumulate reasoning if present
    String reasoningChunk = message.getMetadata().get("reasoningContent");
    if (reasoningChunk != null) {
        reasoning.append(reasoningChunk);
    }

    // Accumulate the final answer
    if (message.getContent() != null) {
        answer.append(message.getContent());
    }
});

示例：DeepSeek R1

DeepSeek R1 是一个推理模型，能够展示其内部推理过程：spring-doc.cadn.net.cn

spring.ai.openai.api-key=${DEEPSEEK_API_KEY}
spring.ai.openai.base-url=https://api.deepseek.com
spring.ai.openai.chat.options.model=deepseek-reasoner

当您向 DeepSeek R1 发送请求时，响应将同时包含推理内容（模型的思考过程）和最终答案。spring-doc.cadn.net.cn

有关推理模型的更多详细信息，请参阅 DeepSeek API 文档。spring-doc.cadn.net.cn

示例：带推理解析器的 vLLM

vLLM 在配置了推理解析器时支持推理模型：spring-doc.cadn.net.cn

vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
    --enable-reasoning \
    --reasoning-parser deepseek_r1
spring.ai.openai.base-url=http://localhost:8000
spring.ai.openai.chat.options.model=deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B

请参阅 vLLM 推理输出文档，了解支持的推理模型和解析器。spring-doc.cadn.net.cn

reasoning_content 的可用性完全取决于您使用的推理服务器。 并非所有兼容 OpenAI 的服务器都会暴露推理内容，即使使用的是具备推理能力的模型。 请务必参考您的服务器 API 文档，以了解响应中可用的字段。spring-doc.cadn.net.cn