OpenAI SDK 聊天(官方版)
Spring AI通过OpenAI的Java SDK支持OpenAI的语言模型,提供了一个稳健且官方维护的与OpenAI服务的集成,包括微软Foundry和GitHub模型。
该实现使用了官方的OpenAI Java SDK。要查看替代的Spring AI实现,请参见OpenAI Chat。 |
该 OpenAI SDK 模块会根据你提供的基地址自动检测服务提供者(OpenAI、Microsoft Foundry 或 GitHub Models)。
身份验证
认证过程使用了一个基数URL和一个API密钥。实现部分通过Spring Boot配置属性或环境变量提供了灵活的配置选项。
使用OpenAI
If you are using OpenAI directly, create an account at OpenAI注册页面 and generate an API key on the API密钥页面.
基URL不需要手动设置,系统会默认为0:
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
使用微软Foundry
当使用微软Foundry URL时,微软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):
微软Foundry支持无密钥的密码less认证,无需提供API密钥,这在Azure上运行时更加安全。
为了实现无密码认证,添加 零 依赖项:
<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时自动检测到。您还需要使用0代码范围创建GitHub个人访问Tokens(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)在属性中使用: ```java // 示例代码 System.setProperty("myAppspringId", "unique-value-for-my-app"); ``` |
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}
自动配置
Spring AI提供针对OpenAI SDK聊天客户端的Spring Boot自动配置功能。
要启用此功能,请在项目Maven pom.xml或Gradle build.gradle的构建文件中添加以下依赖项:
-
Maven
-
Gradle
<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到你的构建文件中。 |
配置属性
连接属性
The prefix spring.ai.openai-sdk is used as the property prefix that lets you configure the OpenAI SDK client.
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.base-url |
连接到的URL。如果未设置,则自动从 |
|
spring.ai.openai-sdk.api-key |
API密钥。如果不设置,会从 |
- |
spring.ai.openai-sdk.organization-id |
可选地指定用于API请求的组织。 |
- |
spring.ai.openai-sdk.timeout |
请求超时持续时间。 |
- |
spring.ai.openai-sdk.max-retries |
失败请求的最大重试次数。 |
- |
spring.ai.openai-sdk.proxy |
Proxy设置为OpenAI客户端(Java 0对象)。 |
- |
spring.ai.openai-sdk.custom-headers |
需要将以下英文文本翻译成中文简体: Custom HTTP headers to include in requests. Map of header name to header value. 翻译结果如下: 在请求中包含自定义HTTP头。头名称与头值的映射关系。 |
- |
微软飞天(Azure OpenAI)特性
OpenAI SDK实现提供针对微软Foundry(Azure OpenAI)的原生支持,带有自动配置功能:
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.microsoft-foundry |
启用 Microsoft Foundry 模式。如果基体 URL 包含 |
false |
spring.ai.openai-sdk.microsoft-deployment-name |
微软Foundry的部署名称。如果未指定,则使用模型名。此外,还可以通过别名 |
- |
spring.ai.openai-sdk.microsoft-foundry-service-version |
微软Foundry API服务版本 |
- |
spring.ai.openai-sdk.credential |
凭证对象用于无密码认证(需要 |
- |
微软Foundry支持无密钥认证。添加com.azure:azure-identity依赖项,实现将自动尝试从环境变量中使用Azure凭证(而非API密钥)。 |
GitHub 模型属性
GitHub Models的原生支持已推出:
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.github-models |
启用GitHub模型模式。如果基础URL包含 |
false |
| GitHub Models需要一个个人访问Tokens,具有0的权限范围。通过以下方式设置:1环境变量或2属性。 |
聊天模型属性
The prefix spring.ai.openai-sdk.chat是配置聊天模型实现的属性前缀:
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.chat.options.model |
使用OpenAI聊天模型的名称。您可以选择以下模型之一: |
|
spring.ai.openai-sdk.chat.options.temperature |
用于控制生成内容的表面创新性的采样温度。较高的值会使输出更加随机,而较低的值会使结果更加集中和确定性。不建议在同一完成请求中修改 |
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 |
是否返回输出Tokens的对数概率? |
false |
spring.ai.openai-sdk.chat.options.top-logprobs |
一个介于0到5之间的整数,指定每个位置上最可能返回的Tokens数量。要求0要为true。 |
- |
spring.ai.openai-sdk.chat.options.max-tokens |
The maximum number of tokens to generate. 生成的Tokens数量 建议用于非推理模型,例如gpt-4o、gpt-3.5-turbo。 不能与推理模型一起使用,例如o1、o3、o4系列中的模型。 与最大完成Tokens数互斥。 |
- |
spring.ai.openai-sdk.chat.options.max-completion-tokens |
一个生成完成时(completion)所需的最大Tokens数量的上限,包括可见输出Tokens和推理Tokens。仅用于推理模型(例如 o1、o3、o4 系列)。不能与非推理模型一起使用。与 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 |
音频输出参数设置。使用 |
- |
spring.ai.openai-sdk.chat.options.presence-penalty |
数字介于-2.0到2.0之间。正数值会惩罚新增的单词,根据它们在当前文本中出现的情况。负数值不会惩罚新增的单词。 |
0.0 |
spring.ai.openai-sdk.chat.options.response-format.type |
响应格式类型:代码:0、1、2。 |
TEXT |
spring.ai.openai-sdk.chat.options.response-format.json-schema |
JSON方案用于结构化输出,当类型为0时。 |
- |
spring.ai.openai-sdk.chat.options.seed |
如果指定,则该系统将尽力做出最佳努力,以进行确定性采样,以确保结果的可重复性。 |
- |
spring.ai.openai-sdk.chat.options.stop |
最多4个序列,到达这些序列后API将停止生成更多Tokens。 |
- |
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 |
是否在工具使用过程中启用并行函数调用? |
true |
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 |
指定要使用的延迟层级: |
- |
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 会 internally 处理功能调用。 |
true |
|
GPT-5 模型,例如 |
所有以spring.ai.openai-sdk.chat.options为前缀的属性都可以通过向Prompt调用中添加请求特定的运行时选项在运行时覆盖。 |
Tokens限制参数:模型特定使用
OpenAI为控制生成Tokens的限制提供了两个互斥参数:
| 参数 | 使用案例 | 兼容性模型 |
|---|---|---|
|
非推理型模型 |
gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo |
|
推理模型 |
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()
));
运行时选项
The OpenAI SDK Chat Options类提供诸如要使用的模型、温度、频率惩罚等模型配置。
On start-up, the default options can be configured with the OpenAiSdkChatModel(options) constructor or the spring.ai.openai-sdk.chat.options.* properties.
在运行时,您可以通过向 Prompt 调用添加新的、特定于请求的选项来覆盖默认选项。
例如,要为特定请求覆盖默认模型和温度:
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
OpenAiSdkChatOptions.builder()
.model("gpt-4o")
.temperature(0.4)
.build()
));
| 除了模型特定的 OpenAI SDK chat options,你还可以使用一个便携的 聊天选项实例,使用 ChatOptions#builder() 方法创建。 |
工具调用
你可以注册自定义的Java函数或方法,并使OpenAI模型智能地选择输出一个包含调用注册函数/工具所需参数的JSON对象。 这是将大语言模型(LLM)能力与外部工具和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。
请参考视觉文档获取更多信息。
以下是展示用户文本与图片融合的代码示例:
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。
参考[{"Item1":"href","Item2":"https://platform.openai.com/docs/guides/audio"}]指导以获取更多信息。
Spring AI 支持对基64编码的音频文件进行处理。
目前,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()));
输出音频
The 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().getText(); // 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().getText());
示例控制器
创建一个新的Spring Boot项目,并将spring-boot-starter-web添加到您的pom(或gradle)依赖中。
向1号目录下添加一个文件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);
}
}
手动配置
The OpenAI SDK聊天模型实现了 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 = 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."));
微软foundry配置Microsoft Foundry Configuration
对于 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 = OpenAiSdkChatModel.builder()
.options(chatOptions)
.build();
Microsoft Foundry支持无密码认证。在项目中添加com.azure:azure-identity依赖项。如果未提供密钥,则实现将自动尝试从环境中使用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 = OpenAiSdkChatModel.builder()
.options(chatOptions)
.build();
Spring与Spring AI OpenAI的主要区别
这种实现与Spring AI OpenAI模型的实现存在多处差异:
| 面向切面编程 | 官方OpenAI SDK | 现有的OpenAI |
|---|---|---|
HTTP 客户端 |
OkHttp框架(通过官方SDK) |
Spring RESTful客户端/Web客户端 |
API 更新 |
通过SDK更新自动 |
手动维护 |
Azure 支持 |
本地应用支持无密码认证 |
手动URL构建 |
GitHub 模型 |
原生支持 Native support |
不支持 |
Audio/Moderation |
尚未支持 |
完全支持的 |
重试逻辑 |
SDK管理的指数型回退策略 |
Spring 重试(可配置) |
依赖项 |
官方OpenAI SDK |
Spring WebFlux |
在什么情况下使用 OpenAI SDK:
-
你正在开始一个新项目
-
你主要使用微软 Foundry 或 GitHub 模型。
-
你希望从 OpenAI 获取自动更新的 API
-
你不需要音频转录或调整功能
-
你更倾向于官方SDK支持
何时使用 Spring AI 和 OpenAI:
-
你有一个现有的项目使用它
-
您需要音频转录或Moderation features功能
-
你需要细粒度的HTTP控制
-
你希望获得原生的Spring响应式支持
-
你需要自定义重试策略