|
此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3! |
OpenAI SDK 聊天(官方)
Spring AI通过OpenAI Java SDK支持OpenAI的语言模型,提供了与OpenAI服务包括Microsoft Foundry和GitHub Models的稳健且官方维护的集成。
| 此实现使用了官方的OpenAI Java SDK。对于替代的Spring AI实现,请参见OpenAI聊天。 |
The OpenAI SDK模块会根据您提供的基础URL自动检测服务提供商(OpenAI、Microsoft Foundry或GitHub Models)。
身份验证
使用基础URL和API密钥进行身份验证。实现通过Spring Boot属性或环境变量提供灵活的配置选项。
使用 OpenAI
如果您直接使用 OpenAI,请在 OpenAI 注册页面 创建账户,并在 API 密钥页面 生成 API 密钥。
基URL不需要设置,因为它默认为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
当使用微软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 密钥的密码less身份验证,这在运行于 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 基础 URL 时,GitHub Models 会自动检测。您需要创建一个具有 models:read 权限范围的 GitHub Personal Access Token (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}
Auto-configuration
Spring AI 提供了 Spring Boot 自动配置功能来支持 OpenAI SDK 聊天客户端。
要启用此功能,请在项目中的 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添加到您的构建文件中。 |
配置属性
连接属性
使用前缀spring.ai.openai-sdk作为属性前缀,以便配置OpenAI SDK客户端。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.base-url |
连接的URL。如果没有设置,则自动检测从 |
|
spring.ai.openai-sdk.api-key |
The API密钥。如果未设置,则从 |
- |
spring.ai.openai-sdk.organization-id |
可选地指定用于API请求的组织。 |
- |
spring.ai.openai-sdk.timeout |
请求超时时间。 |
- |
spring.ai.openai-sdk.max-retries |
失败请求的最大重试次数。 |
- |
spring.ai.openai-sdk.proxy |
OpenAI客户端(Java |
- |
spring.ai.openai-sdk.custom-headers |
包含在请求中的自定义HTTP标头。键值对映射,键为标头名称,值为标头值。 |
- |
Microsoft Foundry (Azure OpenAI) 属性
OpenAI SDK 实现提供了对 Microsoft Foundry(Azure OpenAI)的原生支持,并自动进行配置:
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.microsoft-foundry |
启用Microsoft Foundry模式。如果基础URL包含 |
false |
spring.ai.openai-sdk.microsoft-deployment-name |
Microsoft Foundry 部署名称。如果没有指定,将使用模型名称。也可通过别名 |
- |
spring.ai.openai-sdk.microsoft-foundry-service-version |
Microsoft Foundry API 服务版本。 |
- |
spring.ai.openai-sdk.credential |
Credential对象用于无密码认证(需要 |
- |
Microsoft Foundry 支持密码less认证。添加 com.azure:azure-identity 依赖后,当未提供API密钥时,实现将自动尝试使用环境中的 Azure凭据。 |
GitHub 模型属性
GitHub 模型的本地支持现已可用:
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.github-models |
启用GitHub模型模式。如果基础URL包含 |
false |
GitHub Models 需要一个带有 models:read 范围的个人访问Tokens。请通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性设置它。 |
聊天模型属性
spring.ai.openai-sdk.chat 前缀是配置聊天模型实现的属性前缀:
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
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 |
修改指定Tokens在完成时出现的可能性。 |
- |
spring.ai.openai-sdk.chat.options.logprobs |
是否返回输出词元的概率对数。 |
false |
spring.ai.openai-sdk.chat.options.top-logprobs |
指定在每个标记位置上返回的最有可能的标记数量,范围为0到5。要求 |
- |
spring.ai.openai-sdk.chat.options.max-tokens |
生成的最大 tokens 数量。仅用于非推理模型(例如,gpt-4o、gpt-3.5-turbo)。不能与推理模型(例如,o1、o3、o4-mini 系列)一起使用。与 maxCompletionTokens 互斥。 |
- |
spring.ai.openai-sdk.chat.options.max-completion-tokens |
生成完成内容时可以生成的最大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之间的数字。正数值根据新词是否出现在当前文本中来惩罚新的tokens。 |
0.0 |
spring.ai.openai-sdk.chat.options.response-format.type |
响应格式类型: |
text |
spring.ai.openai-sdk.chat.options.response-format.json-schema |
当类型为 |
- |
spring.ai.openai-sdk.chat.options.seed |
如果指定,系统将尽力以确定性方式采样以获得可重复的结果。 |
- |
spring.ai.openai-sdk.chat.options.stop |
API将在生成更多Tokens之前停止生成至多4个序列。 |
- |
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的产品模型蒸馏或evals中使用。 |
false |
spring.ai.openai-sdk.chat.options.metadata |
来自Java开发中Spring AI框架文档网站的开发者定义的标签和值,用于筛选仪表盘中的完成项。 |
- |
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将内部处理函数调用。 |
true |
|
使用GPT-5模型(如 |
所有以spring.ai.openai-sdk.chat.options开头的属性可以在运行时通过向Prompt调用添加请求特定的运行时选项来覆盖。 |
Token 限制 参数:模型特定用法
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 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()创建。 |
工具调用
您可以将自定义的Java函数或方法注册到OpenAiSdkChatModel,并让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。
请参阅 视觉 指南以获取更多信息。
<p>以下是一个代码示例,展示了用户文本与图像的融合:</p>
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));
| 您可以传递多张图片。 |
音频
Spring AI框架文档中支持音频输入的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().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项目,并在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 = 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:
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 凭证。 |
与 Spring AI OpenAI 的主要区别
此实现与 Spring AI OpenAI 实现在以下几个方面有所不同:
| 切面 | OpenAI 官方 SDK | 现有的 OpenAI |
|---|---|---|
httpclient |
OkHttp(通过官方 SDK) |
Spring RestClient/WebClient |
API 更新 |
通过 SDK 自动更新 |
手动维护 |
Azure 支持 |
原生支持无密码认证 |
手动构建 URL |
GitHub 模型 |
原生支持 |
不支持 |
音频/审核 |
尚未支持 |
完全支持 |
重试逻辑 |
SDK 管理(指数退避) |
Spring Retry(可自定义) |
依赖项 |
OpenAI 官方 SDK |
Spring WebFlux |
何时使用 OpenAI SDK:
-
您正在启动一个新项目
-
您主要使用 Microsoft Foundry 或 GitHub Models
-
您希望获取来自 OpenAI 的自动 API 更新
-
您不需要音频转录或审核功能
-
您倾向于官方 SDK 支持
何时使用 Spring AI OpenAI:
-
您有一个使用它的现有项目
-
您需要音频转录或内容审核功能
-
您需要细粒度的 HTTP 控制
-
您想要原生的 Spring 响应式支持
-
您需要自定义重试策略