Java 通用 AI 大模型调用工具类（兼容 OpenAI/智谱/百度千帆，支持流式响应）
引言
当前 AI 大模型生态中，OpenAI、智谱、百度千帆等平台层出不穷，但各平台接口规范不统一、调用逻辑重复开发、异常处理繁琐等问题，给 Java 开发者带来了诸多困扰。
本文分享一套「通用 AI 大模型调用工具类」，核心优势：
- 一键切换平台/模型（兼容主流 OpenAI 规范平台）
- 完整异常处理（401 密钥无效、429 限流、网络异常等全覆盖）
- 支持流式/非流式响应（适配对话场景实时交互）
- 灵活配置（超时、代理、实时打印等可自定义）
- 开箱即用，可直接导入项目生产环境
一、工具类设计思路
采用「配置分离 + 核心逻辑封装」的设计模式，结构如下：
- 自定义异常类：统一封装 AI 调用全流程异常，便于上层捕获处理
- 配置类：聚合所有可配置参数，提供常用平台快捷配置方法，实现一键切换
- 核心工具类：封装 OkHttp 请求、流式/非流式响应处理、JSON 解析等核心逻辑
整体架构解耦，配置与业务逻辑分离，后续扩展新平台只需新增配置，无需修改核心调用逻辑。
二、核心代码实现
2.1 自定义异常类（AIInvokeException.java）
统一异常格式，包含错误信息和 HTTP 状态码，方便定位问题：
package com.ai.client;
/**
* AI 调用通用异常类
* 包含错误信息和响应状态码，便于上层统一处理
*/
public class AIInvokeException extends RuntimeException {
// 存储 HTTP 响应状态码（如 401/403/429 等）
private Integer code;
// 构造方法重载，适配不同异常场景
public AIInvokeException(String message) {
super(message);
}
public AIInvokeException(String message, Integer code) {
super(message);
this.code = code;
}
public AIInvokeException(String message, Throwable cause) {
super(message, cause);
}
// Getter & Setter
public Integer getCode() {
return code;
}
public void setCode(Integer code) {
this.code = code;
}
}
2.2 配置类（AIClientConfig.java）
核心配置聚合，提供常用平台快捷创建方法，支持代理、超时等灵活配置：
package com.ai.client;
import java.net.InetSocketAddress;
import java.net.Proxy;
/**
* AI 客户端配置类：一键切换平台/模型的核心
* 包含核心配置（接口地址、密钥、模型名）和可选配置（超时、流式开关等）
*/
public class AIClientConfig {
// 核心配置（必传，不同平台唯一差异点）
private String apiUrl; // 平台接口地址（后缀统一为 /v1/chat/completions）
private String apiToken; // 平台 API 密钥/Token
private String modelName; // 模型名称（如 deepseek-v3.1、glm-4、gpt-3.5-turbo）
// 可选配置（默认值适配大部分场景，可按需修改）
private int readTimeout = 60; // 读取超时（秒），流式响应建议≥60
private int connectTimeout = 10; // 连接超时（秒）
private boolean stream = true; // 是否开启流式返回（默认开启，实时交互更友好）
private double temperature = 0.6; // 温度系数（0-2，值越大回复越随机）
private int maxTokens = 4096; // 最大生成 Token 数（控制回复长度）
private boolean printRealTime = true; // 是否实时打印流式内容（默认开启）
Proxy proxy;
AIClientConfig {
();
config.setApiUrl(apiUrl);
config.setApiToken(apiToken);
config.setModelName(modelName);
config;
}
AIClientConfig {
();
config.setApiUrl();
config.setApiToken(apiToken);
config.setModelName(modelName);
config;
}
AIClientConfig {
();
config.setApiUrl();
config.setApiToken(apiToken);
config.setModelName();
config;
}
AIClientConfig {
();
config.setApiUrl();
config.setApiToken(apiToken);
config.setModelName();
config;
}
{
.proxy = (Proxy.Type.HTTP, (host, port));
}
String { apiUrl; }
{ .apiUrl = apiUrl; }
String { apiToken; }
{ .apiToken = apiToken; }
String { modelName; }
{ .modelName = modelName; }
{ readTimeout; }
{ .readTimeout = readTimeout; }
{ connectTimeout; }
{ .connectTimeout = connectTimeout; }
{ stream; }
{ .stream = stream; }
{ temperature; }
{ .temperature = temperature; }
{ maxTokens; }
{ .maxTokens = maxTokens; }
{ printRealTime; }
{ .printRealTime = printRealTime; }
Proxy { proxy; }
{ .proxy = proxy; }
}
2.3 核心工具类（AIGeneralClient.java）
封装所有调用逻辑，包含请求构造、流式/非流式响应处理、异常捕获，是工具类的核心：
package com.ai.client;
import okhttp3.*;
import okio.BufferedSource;
import org.json.JSONArray;
import org.json.JSONObject;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
/**
* 通用 AI 大模型客户端核心类
* 兼容所有 OpenAI 规范的 AI 平台，封装请求发送、响应处理、异常处理全流程
*/
public class AIGeneralClient {
private final AIClientConfig config;
private final OkHttpClient client;
/**
* 构造方法：传入配置，初始化 OkHttp 客户端
* @param config 平台配置实例
*/
public AIGeneralClient(AIClientConfig config) {
this.config = config;
validateConfig();
this.client = buildOkHttpClient();
}
/**
* 核心调用方法：发送用户提问，获取 AI 回复
* @param prompt 用户提问内容
* @return 完整的 AI 回复字符串
*/
public String sendMessage(String prompt) {
RequestBody requestBody = buildRequestBody(prompt);
Request request = buildRequest(requestBody);
try (Response response = client.newCall(request).execute()) {
handleResponseStatus(response);
return config.isStream() ? handleStreamResponse(response) : handleNonStreamResponse(response);
} catch (IOException e) {
throw new AIInvokeException( + e.getMessage(), e);
} (Exception e) {
( + e.getMessage(), e);
}
}
{
(config.getApiUrl() == || config.getApiUrl().isEmpty()) {
();
}
(config.getApiToken() == || config.getApiToken().isEmpty()) {
();
}
(config.getModelName() == || config.getModelName().isEmpty()) {
();
}
}
OkHttpClient {
OkHttpClient. .Builder()
.readTimeout(config.getReadTimeout(), TimeUnit.SECONDS)
.connectTimeout(config.getConnectTimeout(), TimeUnit.SECONDS)
.writeTimeout(, TimeUnit.SECONDS);
(config.getProxy() != ) {
builder.proxy(config.getProxy());
}
builder.build();
}
RequestBody {
();
requestJson.put(, config.getModelName());
requestJson.put(, config.getTemperature());
requestJson.put(, config.getMaxTokens());
requestJson.put(, config.isStream());
();
();
userMsg.put(, );
userMsg.put(, prompt);
messages.put(userMsg);
requestJson.put(, messages);
MediaType.parse();
RequestBody.create(requestJson.toString(), mediaType);
}
Request {
.Builder()
.url(config.getApiUrl())
.post(requestBody)
.addHeader(, )
.addHeader(, config.isStream() ? : )
.addHeader(, + config.getApiToken())
.build();
}
{
(!response.isSuccessful()) {
String.format(, response.code(), response.message());
(errorMsg, response.code());
}
(response.body() == ) {
();
}
}
String IOException {
();
response.body().source();
(!source.exhausted()) {
source.readUtf8Line();
(line == || line.isEmpty()) {
;
}
(line.startsWith()) {
line.substring().trim();
(jsonPart.equals()) {
;
}
{
(jsonPart);
json.getJSONArray().getJSONObject()
.getJSONObject().getString();
(!content.isEmpty()) {
fullReply.append(content);
(config.isPrintRealTime()) {
System.out.print(content);
}
}
} (Exception e) {
;
}
}
}
(config.isPrintRealTime() && fullReply.length() > ) {
System.out.println();
}
fullReply.toString();
}
String IOException {
response.body().string();
(responseStr);
json.getJSONArray().getJSONObject()
.getJSONObject().getString();
}
}
三、快速使用示例
以下示例演示如何一键切换 OpenAI、智谱平台，包含异常处理和配置自定义：
package com.ai.client;
/**
* 通用 AI 客户端测试类：一键切换不同平台/模型
*/
public class AIClientTest {
public static void main(String[] args) {
String prompt = "你现在是我女朋友，早上刚刚睡起向我问好";
try {
// ========== 1. 自定义配置示例 ==========
AIClientConfig customConfig = AIClientConfig.customConfig(
"https://your-api-url.com/v1/chat/completions",
"Your-Token",
"your-model-name"
);
AIGeneralClient customClient = new AIGeneralClient(customConfig);
System.out.println("=== Custom AI Response ===");
String customReply = customClient.sendMessage(prompt);
System.out.println("完整回复：" + customReply + "\n");
// ========== 2. 一键切换到智谱 AI（GLM-4）==========
AIClientConfig zhipuConfig = AIClientConfig.zhipuConfig("你的智谱 API-Key");
AIGeneralClient zhipuClient = new AIGeneralClient(zhipuConfig);
System.out.println("=== 智谱 AI（GLM-4）回复 ===");
String zhipuReply zhipuClient.sendMessage(prompt);
System.out.println( + zhipuReply + );
AIClientConfig.openAIConfig(, );
openAIConfig.setProxy(, );
(openAIConfig);
System.out.println();
openAIClient.sendMessage(prompt);
System.out.println( + openAIReply);
} (AIInvokeException e) {
System.err.println( + e.getMessage());
(e.getCode() != ) {
(e.getCode()) {
: System.err.println(); ;
: System.err.println(); ;
: System.err.println(); ;
: System.err.println(); ;
}
}
e.printStackTrace();
}
}
}
四、关键特性说明
4.1 一键切换平台
通过配置类的快捷方法（如 customConfig()、zhipuConfig()），只需传入对应平台的 Token，即可完成切换，核心调用逻辑完全不变。
4.2 完整异常处理
所有异常统一封装为 AIInvokeException，包含：
- 配置校验异常（空 API 地址/密钥）
- 网络异常（连接超时、IO 异常）
- HTTP 状态码异常（401/429/404/500 等）
- JSON 解析异常（响应格式错误）
上层可通过捕获异常，根据状态码快速定位问题（如 401=密钥无效，429=限流）。
4.3 灵活配置项
| 配置项 | 作用 | 默认值 |
|---|---|---|
| readTimeout | 读取超时时间（流式响应需设长） | 60 秒 |
| connectTimeout | 连接超时时间 | 10 秒 |
| stream | 是否开启流式响应 | true（开启） |
| printRealTime | 是否实时打印流式内容 | true（开启） |
| proxy | 代理配置（海外平台访问） | 无（默认不配置） |
| temperature | 回复随机性（0-2） | 0.6 |
4.4 通用兼容性
兼容所有遵循 OpenAI 接口规范的平台，包括但不限于：
- 海外：OpenAI（GPT-3.5/GPT-4）、Claude（兼容模式）
- 国内：智谱 AI、百度千帆、火山方舟、阿里云通义
五、依赖配置
工具类依赖 OkHttp（HTTP 客户端）和 JSON（解析响应），需在 pom.xml 中引入以下依赖（Maven 项目）：
<!-- OkHttp：HTTP 请求客户端 -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>4.12.0</version>
</dependency>
<!-- JSON 解析：处理请求体和响应体 -->
<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20240303</version>
</dependency>
如果是 Gradle 项目，对应依赖：
implementation 'com.squareup.okhttp3:okhttp:4.12.0'
implementation 'org.json:json:20240303'
六、扩展与适配
6.1 新增其他平台支持
如需支持火山方舟、阿里云通义等平台，只需在 AIClientConfig 中新增快捷配置方法，示例（火山方舟 - 豆包）：
/**
* 火山方舟 快捷配置（豆包模型）
* @param apiToken 火山方舟 Token
* @return 配置实例
*/
public static AIClientConfig volcConfig(String apiToken) {
AIClientConfig config = new AIClientConfig();
config.setApiUrl("https://ark.cn-beijing.volces.com/api/v3/chat/completions");
config.setApiToken(apiToken);
config.setModelName("doubao-pro");
return config;
}
6.2 非兼容平台适配
极少数小众平台不遵循 OpenAI 规范，只需微调 2 处即可适配：
- 请求体格式不同：修改
buildRequestBody()方法，按平台文档构造请求体； - 流式响应格式不同：修改
handleStreamResponse()方法，适配平台的流式数据格式（如去掉特定前缀、调整 JSON 解析路径）。
七、总结
本文分享的通用 AI 调用工具类，通过「配置分离 + 核心逻辑封装」的设计，解决了多平台接口不统一、重复开发、异常处理繁琐等问题。
核心优势：
- 开箱即用：3 个核心文件 + 依赖配置，直接导入项目即可使用；
- 灵活切换：一键切换多平台/模型，无需修改核心代码；
- 稳定可靠：完整异常处理 + 超时/代理配置，适配生产环境；
- 易于扩展：新增平台只需新增配置，非兼容平台少量微调即可适配。
该工具类可广泛应用于 Java 后端的 AI 对话、智能问答等场景，大幅提升开发效率。
附录：常见问题排查
- Q：401 异常？A：检查 API 密钥是否正确、是否过期，鉴权头格式是否为「Bearer + 空格 + Token」；
- Q：流式响应无内容？A：检查 stream 参数是否设为 true，请求头 Accept 是否为「text/event-stream」；
- Q：OpenAI 调用失败？A：需配置代理，确保代理地址/端口正确，网络可访问海外；
- Q：JSON 解析异常？A：升级 org.json 依赖到最新版，避免旧版本不兼容 emoji 等特殊字符。
