1. 项目概述如果你是一名Java开发者最近想在自己的应用里集成ChatGPT的能力比如做个智能客服、代码助手或者搞点AI创意应用那你大概率会面临一个选择是直接去啃OpenAI官方的API文档自己从零开始封装HTTP请求、处理JSON、管理连接池还是找一个现成的SDK来快速上手我猜只要项目时间不是特别宽裕大部分人都会选后者。毕竟重复造轮子不仅耗时还容易在细节上踩坑。今天要聊的这个chatgpt-java就是一个在Java社区里口碑相当不错的非官方OpenAI SDK。它不是OpenAI官方出的而是由社区开发者Grt1228维护的一个开源项目。我用它做过几个内部工具和演示项目整体感觉是封装得足够全面设计上考虑了生产环境的需求而且社区活跃问题响应快。对于想快速把ChatGPT、GPT-4、DALL-E 3、Whisper这些AI能力集成到Java项目里的朋友来说这绝对是个能让你省下大量前期调研和编码时间的利器。简单来说这个SDK帮你干了这么几件核心的事全接口覆盖OpenAI官方放出的Chat Completion、Image Generation、Speech to Text (Whisper)、Fine-tuning、Assistants API等它基本都封装好了对应的Java对象和方法。两种调用模式支持普通的同步阻塞调用OpenAiClient也支持服务端推送SSE或WebSocket的流式输出OpenAiStreamClient后者对于需要实时显示AI生成内容比如一个字一个字往外蹦的场景至关重要。生产级特性内置了多API Key轮询策略、自定义HTTP客户端方便你配置代理、超时、日志、Token计算TikToken、Key异常告警钩子等这些都不是玩具项目会考虑的东西。降低集成成本你不需要关心HTTP请求的构建、认证头的添加、JSON的序列化与反序列化、错误码的处理甚至流式数据的解析。SDK提供了一套流畅的Builder API让你用几行代码就能完成对话。接下来我会结合自己的使用经验从为什么选它、怎么快速用起来、到深入一些的高级特性和实际踩过的坑为你完整拆解这个工具库。无论你是刚接触AI接口的新手还是正在为现有项目寻找稳定集成方案的老鸟相信都能找到有价值的信息。2. 核心设计思路与项目定位在深入代码之前我们先聊聊这个SDK在设计上的一些考量。理解这些能帮助你在后续使用中做出更合适的选择和配置。2.1 为什么是“非官方”却值得信赖首先得明确chatgpt-java是一个社区维护的项目。这意味着一开始你可能会有点顾虑稳定性如何会不会突然不更新了安全吗根据我的观察和实际使用这个项目在社区中能站稳脚跟主要靠以下几点跟得紧OpenAI的API更新比较频繁比如从GPT-3.5到GPT-4再到后来的GPT-4 Turbo、带视觉能力的模型、Assistants API等。这个SDK的维护者Grt1228跟进速度很快通常在新特性发布后不久对应的版本更新就来了。项目README里的更新日志就是证明从1.0.0支持全部基础API到1.1.x版本支持图片理解、Function Calling、Assistants流式输出迭代非常清晰。设计务实它没有过度设计而是紧紧围绕OpenAI的REST API做了一层薄薄的、类型安全的封装。所有的请求参数、响应对象都定义成了Java Bean并且使用了Lombok来减少样板代码。这让代码看起来非常清爽也符合Java开发者的习惯。生产意识这是我觉得它区别于很多“玩具型”封装的关键。比如它很早就支持了多API Key管理。如果你只有一个Key偶尔请求失败可能只是运气不好但如果你在做的是一个有一定用户量的服务API调用频率上去后单个Key的速率限制RPM/TPM很快就会成为瓶颈甚至可能因超额使用被封。SDK内置的KeyRandomStrategy随机选择和FirstKeyStrategy顺序使用等策略让你可以轻松配置一组Key由SDK帮你做负载均衡和故障转移。可扩展性强它把OkHttpClient的创建完全暴露给了使用者。这意味着你可以注入任何自定义的拦截器Interceptor、配置代理、调整超时时间、添加日志、甚至实现自定义的认证逻辑。这种设计把网络层的控制权交还给了开发者非常灵活。所以虽然它“非官方”但其代码质量、维护活跃度以及为生产环境所做的考虑让它成为了Java生态中集成OpenAI服务的一个事实上的标准选择之一。2.2 核心架构两个客户端与事件驱动SDK的核心是两个客户端类OpenAiClient和OpenAiStreamClient。理解它们的区别是正确使用的第一步。OpenAiClient同步/阻塞式客户端。你调用一个方法比如chatCompletion它会发送HTTP请求然后等待OpenAI服务器处理完毕并返回完整的响应后一次性给你一个ChatCompletionResponse对象。这种方式简单直观适用于不需要实时反馈、或者AI响应内容较短的场景。缺点是如果生成一篇长文用户需要等待全部生成完成后才能看到结果体验不够流畅。OpenAiStreamClient流式/事件驱动客户端。这是为了改善用户体验而生的。当你调用streamChatCompletion方法时它会建立一个Server-Sent Events (SSE) 连接。OpenAI服务器会一边生成文本一边以数据流的形式分片发送回来。SDK通过一个EventSourceListener监听器来接收这些数据块。你可以在监听器的onEvent方法里实时处理每一个到来的文本片段比如立即显示在网页、控制台或App的UI上。这对于打造类似ChatGPT官网那种“逐字打印”的效果至关重要。这里有个重要的实践细节流式输出在Java后端服务中如何传递给前端SDK作者提供了另一个参考项目chatgpt-steam-output里面演示了如何结合Spring Boot将SSE流通过HTTP响应流式地推送给浏览器或客户端。这解决了后端服务架构中的关键集成问题。选择建议做命令行工具、后台异步任务比如批量生成文章摘要时用OpenAiClient更简单。做需要实时交互的Web应用、聊天机器人界面、代码补全提示时必须用OpenAiStreamClient。2.3 依赖管理与版本选择项目使用Maven进行依赖管理。在快速开始的例子里它引用了1.0.14-beta1版本。但我强烈建议你在使用时去项目的GitHub Release页面或Maven中央仓库查看最新稳定版。dependency groupIdcom.unfbx/groupId artifactIdchatgpt-java/artifactId version最新版本号/version !-- 例如 1.1.6 -- /dependency版本号背后的含义1.0.x系列基础功能稳定覆盖了早期的Chat、Completion、Image、Embedding等核心接口。1.1.x系列开始加入更多高级特性比如Function Calling函数调用、带视觉的Chat Completion、Assistants API、TTS等。如果你需要这些新功能就应该选择1.1.x或更高版本。一个踩坑点不同版本间某些类的包路径或方法签名可能会有细微调整。比如Message类的构造方式或者一些枚举值的名称。因此在升级版本时最好先仔细阅读一下项目的更新日志CHANGELOG并做好本地测试。3. 从零开始环境搭建与基础使用理论说再多不如跑通一行代码。我们从一个最简单的“Hello AI”例子开始确保你的开发环境一切就绪。3.1 前期准备获取API Key使用任何OpenAI API服务的前提是你得有一个API Key。这个Key就像一把钥匙SDK会用它来向OpenAI证明你的身份和计费权限。访问 OpenAI平台 并登录。点击右上角个人头像选择 “View API keys”。点击 “Create new secret key”为你的项目创建一个新的Key。请务必妥善保存这个Key因为它只显示一次。如果丢失需要重新生成。安全警告API Key是高度敏感的凭证直接关联你的账单。绝对不要将它硬编码在客户端代码如前端、移动端或提交到公开的Git仓库。正确的做法是放在服务器的环境变量、配置中心或安全的密钥管理服务中。3.2 基础依赖与客户端初始化假设我们创建一个简单的Maven项目。在pom.xml中引入依赖后就可以开始写代码了。我们先使用最简化的配置创建一个同步客户端import com.unfbx.chatgpt.OpenAiClient; import com.unfbx.chatgpt.entity.chat.ChatCompletion; import com.unfbx.chatgpt.entity.chat.Message; import java.util.Arrays; public class QuickStart { public static void main(String[] args) { // 1. 构建客户端。在实际项目中API Key应从环境变量或配置文件中读取。 OpenAiClient client OpenAiClient.builder() .apiKey(Arrays.asList(sk-your-api-key-here)) // 替换成你的真实Key .build(); // 2. 构建对话消息。这里我们模拟一个用户提问。 Message userMessage Message.builder() .role(Message.Role.USER) // 角色是用户 .content(用Java写一个Hello World程序。) // 用户的问题 .build(); // 3. 构建对话请求。指定使用的模型和消息列表。 ChatCompletion chatCompletion ChatCompletion.builder() .model(ChatCompletion.Model.GPT_3_5_TURBO.getName()) // 使用GPT-3.5-Turbo模型 .messages(Arrays.asList(userMessage)) // 将用户消息放入列表 .build(); // 4. 发送请求并获取响应 ChatCompletionResponse response client.chatCompletion(chatCompletion); // 5. 处理响应 if (response ! null response.getChoices() ! null !response.getChoices().isEmpty()) { // 通常一次请求只返回一个choice我们取第一个 Message assistantMessage response.getChoices().get(0).getMessage(); System.out.println(AI回复: assistantMessage.getContent()); } else { System.out.println(未收到有效回复。); } } }运行这段代码如果网络通畅且API Key有效你应该会在控制台看到AI生成的Java Hello World代码。这里解释几个关键对象Message代表对话中的一条消息。role可以是SYSTEM系统指令、USER用户、ASSISTANTAI助手。对话历史就是由一系列Message对象组成的列表。ChatCompletion对话补全请求的构建器。除了model和messages它还可以设置temperature创造性0-2、max_tokens最大生成长度等众多参数。ChatCompletionResponse对话补全的响应。其choices列表包含了AI返回的候选回复通常只有一个。每个Choice里包含了message和finish_reason结束原因如stop或length等信息。3.3 实现连续对话上面的例子是单轮对话。要实现多轮连续对话让AI记住上下文关键在于在每次请求时把历史对话记录也一起发送过去。import java.util.ArrayList; import java.util.List; public class ContinuousChat { public static void main(String[] args) { OpenAiClient client OpenAiClient.builder() .apiKey(Arrays.asList(sk-your-key)) .build(); // 用一个List来维护整个对话历史 ListMessage messageList new ArrayList(); // 第一轮用户提问 messageList.add(Message.builder().role(Message.Role.USER).content(鲁迅和周树人是什么关系).build()); ChatCompletionResponse resp1 client.chatCompletion(ChatCompletion.builder().messages(messageList).build()); Message aiReply1 resp1.getChoices().get(0).getMessage(); System.out.println(AI第一轮回复: aiReply1.getContent()); // 将AI的回复也加入历史 messageList.add(aiReply1); // 第二轮基于上一轮上下文继续提问 messageList.add(Message.builder().role(Message.Role.USER).content(你确定吗再仔细想想。).build()); ChatCompletionResponse resp2 client.chatCompletion(ChatCompletion.builder().messages(messageList).build()); Message aiReply2 resp2.getChoices().get(0).getMessage(); System.out.println(AI第二轮回复: aiReply2.getContent()); // 再次加入历史... messageList.add(aiReply2); // 如此往复即可实现连续对话。 } }重要提醒OpenAI的API是按Token计费的而Token数量与发送的文本总量包括你发送的历史消息和AI的回复直接相关。随着对话轮数增加messageList会越来越长每次请求的Token消耗和费用也会增长。在实际产品中通常需要设计一个上下文窗口管理策略例如只保留最近N轮对话或者当总Token数超过某个阈值如模型的最大上下文长度时选择性遗忘最早的对话。4. 进阶实战流式输出与生产环境配置基础对话跑通后我们来点更实用的。流式输出能极大提升用户体验而生产环境的配置则关乎服务的稳定性和可维护性。4.1 流式输出客户端详解流式输出的核心是OpenAiStreamClient和EventSourceListener。下面是一个完整的控制台流式打印示例import com.unfbx.chatgpt.OpenAiStreamClient; import com.unfbx.chatgpt.entity.chat.ChatCompletion; import com.unfbx.chatgpt.entity.chat.Message; import com.unfbx.chatgpt.sse.ConsoleEventSourceListener; import java.util.Arrays; import java.util.concurrent.CountDownLatch; public class StreamChatDemo { public static void main(String[] args) throws InterruptedException { // 1. 构建流式客户端 OpenAiStreamClient streamClient OpenAiStreamClient.builder() .apiKey(Arrays.asList(sk-your-key)) .build(); // 2. 创建一个控制台监听器这是SDK自带的仅用于演示 ConsoleEventSourceListener listener new ConsoleEventSourceListener(); // 3. 构建对话请求 Message message Message.builder().role(Message.Role.USER).content(给我讲一个关于编程的冷笑话。).build(); ChatCompletion chatCompletion ChatCompletion.builder() .model(ChatCompletion.Model.GPT_3_5_TURBO.getName()) .messages(Arrays.asList(message)) .build(); // 4. 发起流式请求 streamClient.streamChatCompletion(chatCompletion, listener); // 5. 等待流式输出完成因为流式是异步的需要主线程等待 // 在实际Web应用中这里应该是非阻塞的通过回调或响应流来处理。 CountDownLatch latch new CountDownLatch(1); latch.await(); // 这里会阻塞直到手动中断或监听器收到结束信号。 // 注意ConsoleEventSourceListener 在收到结束事件时会调用 latch.countDown()。 // 但上面的简单例子没有设置所以会一直等待。生产环境需要更完善的事件处理。 } }ConsoleEventSourceListener是SDK提供的一个简单实现它会把收到的每个数据块Delta打印到控制台。在生产环境中你需要继承EventSourceListener类实现自己的业务逻辑。自定义监听器示例import com.unfbx.chatgpt.sse.EventSourceListener; import okhttp3.sse.EventSource; import org.jetbrains.annotations.Nullable; public class MyStreamListener extends EventSourceListener { private StringBuilder fullMessage new StringBuilder(); Override public void onEvent(EventSource eventSource, Nullable String id, Nullable String type, String data) { // data 是服务器推送过来的原始JSON字符串 if ([DONE].equals(data)) { // 流式输出结束 System.out.println(\n--- 生成完毕 ---); System.out.println(完整消息: fullMessage.toString()); onClosed(eventSource); // 可以触发一些关闭逻辑 return; } // 这里需要解析data提取出文本内容。SDK的ConsoleEventSourceListener里有解析逻辑。 // 简单起见我们假设data是包含text字段的JSON。实际解析更复杂。 // 解析并追加到 fullMessage // System.out.print(parsedText); // 实时打印 } Override public void onClosed(EventSource eventSource) { System.out.println(连接已关闭); // 可以在这里释放资源或通知前端完成 } Override public void onFailure(EventSource eventSource, Nullable Throwable t, Nullable okhttp3.Response response) { System.err.println(流式请求失败: t.getMessage()); // 处理错误如重试或通知用户 } }4.2 生产环境关键配置直接使用默认配置在本地玩玩可以但上生产环境以下几项配置必须仔细考量。4.2.1 自定义OkHttpClient代理、超时与日志国内网络环境直接访问OpenAI API通常需要代理。同时合理的超时设置和日志记录对于排查问题至关重要。import okhttp3.OkHttpClient; import okhttp3.logging.HttpLoggingInterceptor; import java.net.InetSocketAddress; import java.net.Proxy; import java.util.concurrent.TimeUnit; public class ProductionConfig { public static OkHttpClient createOkHttpClient() { // 1. 配置代理根据你的网络情况 Proxy proxy new Proxy(Proxy.Type.HTTP, new InetSocketAddress(你的代理主机, 你的代理端口)); // 2. 配置日志拦截器非常重要但生产环境要小心级别 HttpLoggingInterceptor loggingInterceptor new HttpLoggingInterceptor(); // 日志级别NONE, BASIC, HEADERS, BODY // 生产环境千万不要用 BODY 级别会打印出请求和响应的完整Body包括你的API Key和对话内容 // 建议在测试环境用 HEADERS 或 BASIC生产环境用 NONE 或 BASIC。 loggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS); // 3. 构建OkHttpClient return new OkHttpClient.Builder() .proxy(proxy) // 设置代理 .addInterceptor(loggingInterceptor) // 添加日志 .connectTimeout(30, TimeUnit.SECONDS) // 连接超时 .writeTimeout(60, TimeUnit.SECONDS) // 写入超时上传文件、长文本时可能需要更久 .readTimeout(60, TimeUnit.SECONDS) // 读取超时等待AI生成回复流式场景下这个时间可能很长 .build(); } public static OpenAiClient createOpenAiClient() { OkHttpClient okHttpClient createOkHttpClient(); return OpenAiClient.builder() .apiKey(Arrays.asList(sk-key1, sk-key2)) // 多Key配置 .okHttpClient(okHttpClient) // 注入自定义的Http客户端 .build(); } }关于超时设置的实践经验connectTimeout建立TCP连接的超时一般10-30秒足够。writeTimeout发送请求体的超时。如果你要上传大文件进行语音识别或微调这个值要设大。readTimeout这是最容易出问题的地方。对于普通的同步请求它表示从发送请求到接收完整响应的总时间。对于AI生成长文本这个时间可能超过1分钟。对于流式请求它表示从连接建立到连接关闭的总时间。如果AI生成内容非常慢或者网络不稳定很容易触发读超时。建议根据你的业务场景将这个值设置为一个较大的值如120秒或更长或者对于流式场景考虑使用无限超时0然后由应用层逻辑来控制中断。4.2.2 多API Key与负载均衡策略使用多个API Key有两个主要目的突破速率限制和提高可用性。SDK通过KeyStrategy接口来抽象Key的选择策略。import com.unfbx.chatgpt.OpenAiClient; import com.unfbx.chatgpt.interceptor.KeyRandomStrategy; import com.unfbx.chatgpt.interceptor.FirstKeyStrategy; import java.util.Arrays; public class MultiKeyDemo { public static void main(String[] args) { ListString apiKeys Arrays.asList(sk-key-1, sk-key-2, sk-key-3); // 策略1随机选择默认策略。有助于将负载均匀分布到多个Key上。 OpenAiClient client1 OpenAiClient.builder() .apiKey(apiKeys) .keyStrategy(new KeyRandomStrategy()) .build(); // 策略2顺序使用FirstKeyStrategy。总是使用第一个可用的Key只有当前Key失败时才尝试下一个。 // 这种策略适合你有不同额度或优先级的Key时。 OpenAiClient client2 OpenAiClient.builder() .apiKey(apiKeys) .keyStrategy(new FirstKeyStrategy()) .build(); // 你甚至可以自定义策略例如根据Key的剩余额度、调用次数来动态选择。 } }关键机制失败重试与Key切换SDK内置的OpenAiAuthInterceptor认证拦截器会与KeyStrategy配合工作。当一个请求因为API Key失效、过期、达到限额等原因被OpenAI返回401或429等错误时拦截器会捕获到这个错误并调用KeyStrategy的onError方法。在默认的KeyRandomStrategy或FirstKeyStrategy中它们会尝试切换到列表中的下一个Key进行重试。这在一定程度上实现了自动故障转移。4.2.3 异常处理与监控告警生产环境中API调用失败是常态而不是异常。除了Key失效还可能是网络波动、OpenAI服务暂时不可用等。SDK提供了扩展点让你能捕获这些异常并做出反应。查看源码中的DynamicKeyOpenAiAuthInterceptor它展示了如何自定义一个拦截器在Key失效时不仅切换Key还能发送告警如钉钉、邮件、企业微信。一个简化的自定义异常处理思路实现一个自定义的OpenAiResponseInterceptor在afterCompletion方法中检查响应状态码。如果状态码是401认证失败很可能Key失效了。记录日志并触发你的告警系统。如果状态码是429请求过多可能是速率限制。这时除了告警你的应用逻辑可能需要加入延迟重试exponential backoff。将这些自定义的拦截器添加到你的OkHttpClient中。public class CustomResponseInterceptor implements Interceptor { Override public Response intercept(Chain chain) throws IOException { Request request chain.request(); Response response chain.proceed(request); if (!response.isSuccessful()) { int code response.code(); String body response.body() ! null ? response.body().string() : ; // 记录错误日志 log.error(OpenAI API请求失败状态码: {}, 响应体: {}, code, body); // 根据状态码触发不同的告警或处理逻辑 if (code 401) { alertService.send(OpenAI API Key可能已失效); } else if (code 429) { alertService.send(触发OpenAI速率限制请检查调用频率。); } // 注意response.body()只能读取一次这里读取后需要重新构建response供后续使用 // 实际实现更复杂此处仅为示意。 } return response; } }5. 深入核心功能与高级特性掌握了基础使用和生产配置后我们来看看这个SDK还封装了哪些强大的功能。5.1 Tokens计算与成本控制OpenAI API按Token计费。Token可以粗略理解为单词或字词的一部分。准确估算你发送和接收的文本消耗了多少Token对于成本控制和避免超出模型上下文长度限制至关重要。SDK集成了jtokkit库来计算Token数。它支持GPT-2、GPT-3/3.5/4、Codex等模型的编码器。import com.unfbx.chatgpt.utils.TikTokensUtil; public class TokenCalculationDemo { public static void main(String[] args) { String text Hello, how are you today?; String modelName ChatCompletion.Model.GPT_3_5_TURBO.getName(); // 计算一段文本的Token数 int tokens TikTokensUtil.tokens(modelName, text); System.out.println(文本 \ text \ 的Token数估算: tokens); // 更常见的场景计算整个消息列表的Token数 ListMessage messages Arrays.asList( Message.builder().role(Message.Role.SYSTEM).content(你是一个有帮助的助手。).build(), Message.builder().role(Message.Role.USER).content(今天的天气怎么样).build() ); // 注意消息在传输时会有额外的格式Token估算值可能与API返回的usage有细微差异。 int messageTokens TikTokensUtil.tokens(modelName, messages); System.out.println(消息列表的总Token数估算: messageTokens); } }使用建议在发送请求前对messages进行Token计数。如果超过模型的最大上下文限制如gpt-3.5-turbo是16385个Token就需要裁剪历史消息。实现一个简单的“上下文窗口”管理器只保留最近N条消息或者当总Token数接近上限时逐步移除最早的消息。定期检查API返回的usage字段ChatCompletionResponse中包含与实际估算值对比校准你的计算逻辑。5.2 Function Calling函数调用与插件模式这是让AI与外部工具或你的业务系统交互的核心能力。简单说你可以向AI描述一些函数工具AI在认为需要时会请求你调用这些函数并将函数的结果返回给它它再基于结果生成最终回复。SDK在1.1.1版本后引入了更简洁的“插件模式”。我们来看一个例子让AI查询实时天气。首先定义一个“天气查询”函数插件import com.unfbx.chatgpt.plugin.PluginAbstract; // 继承PluginAbstract泛型是函数的参数类型 public class WeatherPlugin extends PluginAbstractWeatherParam { Override public String getName() { return get_current_weather; // 函数名AI通过这个名字来调用 } Override public String getDescription() { return 获取指定城市的当前天气情况; // 函数描述AI通过这个理解函数用途 } Override public Parameters getParameters() { // 定义函数参数的结构使用JSON Schema描述 return Parameters.builder() .type(object) .addProperty(Property.builder().name(location).type(string).description(城市名称例如北京).build()) .addProperty(Property.builder().name(unit).type(string).enumSet(Arrays.asList(celsius, fahrenheit)).description(温度单位).build()) .required(Arrays.asList(location)) .build(); } Override public Object run(WeatherParam weatherParam) { // 这里是真正的业务逻辑根据参数调用外部天气API String location weatherParam.getLocation(); String unit weatherParam.getUnit() ! null ? weatherParam.getUnit() : celsius; // 模拟返回天气数据 return Map.of( location, location, temperature, 22, unit, unit, description, 晴朗 ); } // 参数类 Data // 使用Lombok Builder public static class WeatherParam { private String location; private String unit; } }然后在对话中使用这个插件public class PluginDemo { public static void main(String[] args) { OpenAiClient client OpenAiClient.builder().apiKey(Arrays.asList(sk-key)).build(); // 1. 创建插件实例 WeatherPlugin weatherPlugin new WeatherPlugin(); // 2. 构建插件请求 PluginReq pluginReq PluginReq.builder() .model(ChatCompletion.Model.GPT_3_5_TURBO_0613.getName()) // 需要使用支持function calling的模型 .messages(Arrays.asList(Message.builder().role(Message.Role.USER).content(北京今天天气怎么样).build())) .plugin(weatherPlugin) // 传入插件 .build(); // 3. 执行插件对话 PluginResp pluginResp client.pluginCompletion(pluginReq); // 4. 处理响应 // 如果AI直接回答了pluginResp.getContent()会有值。 // 如果AI决定调用函数pluginResp.getFunctionCall()会有值并且run()方法会被自动调用结果会喂回给AI。 // SDK内部处理了多轮“AI思考 - 请求调用函数 - 执行函数 - 返回结果给AI”的循环直到AI给出最终回答。 System.out.println(最终回答: pluginResp.getContent()); } }这个模式将复杂的Function Calling流程封装得非常简洁你只需要关注插件本身的定义和业务逻辑实现。5.3 其他重要API速览除了最常用的Chat CompletionSDK还封装了大量其他接口图像生成 (DALL-E)根据文字描述生成图片。Image image Image.builder() .prompt(A cute baby sea otter) .model(Image.Model.DALL_E_3) .size(Image.Size._1024x1024) .quality(Image.Quality.HD) .build(); ImageResponse imageResponse openAiClient.genImages(image); String imageUrl imageResponse.getData().get(0).getUrl();语音转文字 (Whisper)将音频文件转换为文本支持多国语言和翻译。File audioFile new File(path/to/audio.mp3); Transcription transcription Transcription.builder() .model(Transcription.Model.WHISPER_1.getName()) .file(audioFile) .responseFormat(Transcription.ResponseFormat.JSON) .language(zh) // 可选指定音频语言以提高准确性 .build(); TranscriptionResponse response openAiClient.speechToTextTranscription(transcription); String text response.getText();文本审核 (Moderation)判断一段文本是否包含敏感或有害内容。Moderation moderation Moderation.builder().input(I want to hurt someone.).build(); ModerationResponse response openAiClient.moderation(moderation); boolean isFlagged response.getResults().get(0).isFlagged(); // true余额查询查询当前API Key对应的账户余额和额度。CreditGrantsResponse creditGrants openAiClient.creditGrants(); System.out.println(总额度: creditGrants.getTotalGranted()); System.out.println(已使用: creditGrants.getTotalUsed()); System.out.println(剩余: creditGrants.getTotalAvailable());Assistants API(v1.1.3): 创建具有持久化线程和自定义指令的AI助手适合构建复杂的多轮交互应用。// 创建助手 Assistant assistant Assistant.builder() .model(ChatCompletion.Model.GPT_4_1106_PREVIEW.getName()) .name(Math Tutor) .instructions(You are a personal math tutor.) .build(); Assistant createdAssistant openAiClient.createAssistant(assistant); // 创建线程 Thread thread openAiClient.createThread(Thread.builder().build()); // 向线程添加消息 Message threadMessage Message.builder() .role(Message.Role.USER) .content(I need to solve the equation 3x 11 14. Can you help me?) .build(); openAiClient.createMessage(thread.getId(), threadMessage); // 运行助手 Run run Run.builder() .assistantId(createdAssistant.getId()) .build(); Run createdRun openAiClient.createRun(thread.getId(), run); // 可以轮询或流式获取运行结果6. 常见问题、排查技巧与性能优化在实际集成和运维过程中你肯定会遇到各种各样的问题。这里我整理了一些常见坑点和解决思路。6.1 网络与连接问题问题现象连接超时、读写超时、SSL握手失败。排查步骤确认代理如果你在国内99%的问题出在代理上。确保OkHttpClient中配置的代理地址和端口是正确的并且代理服务本身是通畅的可以试试curl通过代理访问api.openai.com。检查防火墙公司网络或服务器安全组可能屏蔽了对外部API的访问。调整超时时间如4.2.1节所述适当增大readTimeout特别是对于长文本生成或流式请求。查看完整日志将HttpLoggingInterceptor的级别设为HEADERS或BASIC观察HTTP请求是否成功发出以及响应的状态码。6.2 API Key与认证错误问题现象返回401 Unauthorized错误。排查步骤检查Key格式确保API Key以sk-开头没有多余的空格或换行。检查Key状态登录OpenAI平台确认该Key是否被禁用、删除或已过期。检查额度免费试用额度可能已用完或者付费账户余额不足。多Key配置如果你配置了多个Key确保至少有一个是有效的。检查KeyStrategy的逻辑看是否所有Key都失效了。IP限制某些OpenAI账户可能限制了调用API的IP地区。确保你的代理服务器或出口IP在允许的地区内。6.3 速率限制 (Rate Limit)问题现象返回429 Too Many Requests错误响应头中通常有x-ratelimit-*字段。理解限制OpenAI对不同的模型和账户类型有不同的速率限制分为RPM(Requests per minute) 和TPM(Tokens per minute)。解决策略降低频率在客户端代码中加入请求间隔例如每秒钟不超过N次请求。使用多Key轮询这是最有效的方法之一将流量分散到多个Key上。实现退避重试当收到429错误时不要立即重试。读取响应头中的retry-after字段如果提供或者采用指数退避算法如等待1秒、2秒、4秒...进行重试。监控用量定期调用creditGrants接口注意这个接口本身也有频率限制或者通过OpenAI控制台监控TPM/RPM的使用情况提前预警。6.4 流式输出中断或不完整问题现象流式输出到一半突然停止或者前端收不到完整消息。排查步骤检查网络稳定性流式连接对网络抖动更敏感。确保客户端与服务器、服务器与OpenAI之间的网络连接稳定。调整服务器配置如果你是在Web后端使用流式输出推送给前端确保你的应用服务器如Tomcat、Undertow和反向代理如Nginx没有过早关闭空闲连接。可能需要调整keepalive_timeout、proxy_read_timeout等配置。正确处理SSE协议Server-Sent Events有特定的格式data: ...\n\n。确保你的后端在转发OpenAI的流式响应时没有破坏这个格式。参考SDK作者提供的chatgpt-steam-output项目。前端监听正确事件前端使用EventSource或fetch读取流时要监听onmessage事件并正确解析event.data。6.5 性能优化建议客户端复用OpenAiClient和OpenAiStreamClient是线程安全的且内部封装了连接池。务必在应用生命周期内将其作为单例复用避免为每个请求都创建新的客户端和OkHttpClient实例这能极大减少TCP连接建立的开销。合理使用连接池OkHttpClient默认的连接池配置对于大多数场景是够用的。但如果你的应用并发量极高可以适当调整OkHttpClient.Builder中的connectionPool参数。异步与非阻塞对于高并发服务同步的OpenAiClient.chatCompletion()调用可能会阻塞业务线程。考虑将其包装在CompletableFuture中或使用Spring的Async注解将其改为异步调用避免线程被长时间占用。结果缓存对于一些重复性较高、实时性要求不高的查询例如“解释什么是Java多态”可以考虑在应用层加入缓存如Redis将AI的回复缓存一段时间避免重复调用API产生不必要的费用。批量处理如果业务允许可以将多个独立的文本生成任务合并通过一次API调用完成注意上下文长度限制这比多次单独调用更高效。7. 项目生态与扩展chatgpt-java本身是一个核心SDK围绕它已经形成了一些扩展项目和最佳实践。chatgpt-steam-output这是同一个作者提供的Spring Boot集成示例项目。它清晰地展示了如何在后端使用OpenAiStreamClient并通过Spring MVC的SseEmitter将流式结果实时推送给前端网页。这是将流式对话集成到Web应用中的必读参考。社区案例在项目的GitHub Issues中有一个“ 案例征集 ”的帖子很多开发者分享了自己基于此SDK开发的应用包括微信机器人、知识库问答、代码生成工具等。遇到问题时在这里搜索或提问往往能得到社区的经验分享。与其他Java生态整合你可以很容易地将它集成到Spring Boot、Quarkus、Micronaut等现代Java框架中。通常的做法是通过Configuration配置一个Bean来创建并注入OpenAiClient或OpenAiStreamClient的单例实例。最后一点个人体会技术选型时社区活跃度是一个非常重要的指标。chatgpt-java项目持续的更新、详细的文档、活跃的Issue讨论区和不断增长的Star数都给了使用者很大的信心。当然任何开源项目都可能存在未知的Bug或与官方API的同步延迟。对于核心业务建议在充分测试的基础上同时关注OpenAI官方的API变更日志以便在SDK更新前就能预知潜在的影响。