Java 通用 AI 大模型调用工具类（兼容 OpenAI、智谱、百度千帆，支持流式响应）

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; // 是否实时打印流式内容（默认开启）
    private Proxy proxy; // 代理配置（可选，访问海外平台如 OpenAI 时需配置）

    // ==================== 常用平台快捷配置方法（一键切换核心）====================

    /**
     * 自定义配置示例
     * @param apiUrl 接口地址
     * @param apiToken 个人 Token
     * @return 配置实例
     */
    public static AIClientConfig customConfig(String apiUrl, String apiToken, String modelName) {
        AIClientConfig config = new AIClientConfig();
        config.setApiUrl(apiUrl);
        config.setApiToken(apiToken);
        config.setModelName(modelName);
        return config;
    }

    /**
     * OpenAI 快捷配置（GPT-3.5/GPT-4）
     * @param apiToken OpenAI 密钥
     * @param modelName 模型名（gpt-3.5-turbo/gpt-4o 等）
     * @return 配置实例
     */
    public static AIClientConfig openAIConfig(String apiToken, String modelName) {
        AIClientConfig config = new AIClientConfig();
        config.setApiUrl("https://api.openai.com/v1/chat/completions");
        config.setApiToken(apiToken);
        config.setModelName(modelName);
        return config;
    }

    /**
     * 智谱 AI 快捷配置（GLM-4/GLM-3）
     * @param apiToken 智谱 API-Key
     * @return 配置实例
     */
    public static AIClientConfig zhipuConfig(String apiToken) {
        AIClientConfig config = new AIClientConfig();
        config.setApiUrl("https://open.bigmodel.cn/api/paas/v4/chat/completions");
        config.setApiToken(apiToken);
        config.setModelName("glm-4");
        return config;
    }

    /**
     * 百度千帆 快捷配置（文心一言 ERNIE）
     * @param apiToken 百度千帆 AccessToken
     * @return 配置实例
     */
    public static AIClientConfig baiduConfig(String apiToken) {
        AIClientConfig config = new AIClientConfig();
        config.setApiUrl("https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions");
        config.setApiToken(apiToken);
        config.setModelName("ernie-4.0-turbo");
        return config;
    }

    // ==================== 可选配置方法 ====================

    /**
     * 设置代理（适配海外平台访问）
     * @param host 代理地址（如 127.0.0.1）
     * @param port 代理端口（如 7890）
     */
    public void setProxy(String host, int port) {
        this.proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(host, port));
    }

    // 所有参数的 Getter & Setter（IDE 可一键生成，此处省略冗余代码）
    public String getApiUrl() { return apiUrl; }
    public void setApiUrl(String apiUrl) { this.apiUrl = apiUrl; }
    public String getApiToken() { return apiToken; }
    public void setApiToken(String apiToken) { this.apiToken = apiToken; }
    public String getModelName() { return modelName; }
    public void setModelName(String modelName) { this.modelName = modelName; }
    public int getReadTimeout() { return readTimeout; }
    public void setReadTimeout(int readTimeout) { this.readTimeout = readTimeout; }
    public int getConnectTimeout() { return connectTimeout; }
    public void setConnectTimeout(int connectTimeout) { this.connectTimeout = connectTimeout; }
    public boolean isStream() { return stream; }
    public void setStream(boolean stream) { this.stream = stream; }
    public double getTemperature() { return temperature; }
    public void setTemperature(double temperature) { this.temperature = temperature; }
    public int getMaxTokens() { return maxTokens; }
    public void setMaxTokens(int maxTokens) { this.maxTokens = maxTokens; }
    public boolean isPrintRealTime() { return printRealTime; }
    public void setPrintRealTime(boolean printRealTime) { this.printRealTime = printRealTime; }
    public Proxy getProxy() { return proxy; }
    public void setProxy(Proxy proxy) { this.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);
        } catch (Exception e) {
            throw new AIInvokeException("响应解析异常：" + e.getMessage(), e);
        }
    }

    /**
     * 校验核心配置（接口地址、密钥、模型名不能为空）
     */
    private void validateConfig() {
        if (config.getApiUrl() == null || config.getApiUrl().isEmpty()) {
            throw new AIInvokeException("API 地址不能为空");
        }
        if (config.getApiToken() == null || config.getApiToken().isEmpty()) {
            throw new AIInvokeException("API 密钥不能为空");
        }
        if (config.getModelName() == null || config.getModelName().isEmpty()) {
            throw new AIInvokeException("模型名称不能为空");
        }
    }

    /**
     * 构建 OkHttp 客户端（支持超时、代理）
     * @return OkHttp 客户端实例
     */
    private OkHttpClient buildOkHttpClient() {
        OkHttpClient.Builder builder = new OkHttpClient.Builder()
                .readTimeout(config.getReadTimeout(), TimeUnit.SECONDS)
                .connectTimeout(config.getConnectTimeout(), TimeUnit.SECONDS)
                .writeTimeout(30, TimeUnit.SECONDS);
        if (config.getProxy() != null) {
            builder.proxy(config.getProxy());
        }
        return builder.build();
    }

    /**
     * 构造请求体（JSON 格式，符合 OpenAI 规范）
     * @param prompt 用户提问
     * @return RequestBody 实例
     */
    private RequestBody buildRequestBody(String prompt) {
        JSONObject requestJson = new JSONObject();
        requestJson.put("model", config.getModelName());
        requestJson.put("temperature", config.getTemperature());
        requestJson.put("max_tokens", config.getMaxTokens());
        requestJson.put("stream", config.isStream());

        JSONArray messages = new JSONArray();
        JSONObject userMsg = new JSONObject();
        userMsg.put("role", "user");
        userMsg.put("content", prompt);
        messages.put(userMsg);
        requestJson.put("messages", messages);

        MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
        return RequestBody.create(requestJson.toString(), mediaType);
    }

    /**
     * 构造 HTTP 请求（设置请求头、URL、请求方法）
     * @param requestBody 请求体
     * @return Request 实例
     */
    private Request buildRequest(RequestBody requestBody) {
        return new Request.Builder()
                .url(config.getApiUrl())
                .post(requestBody)
                .addHeader("Content-Type", "application/json; charset=utf-8")
                .addHeader("Accept", config.isStream() ? "text/event-stream" : "application/json")
                .addHeader("Authorization", "Bearer " + config.getApiToken())
                .build();
    }

    /**
     * 处理响应状态码：非 200 则抛出异常
     * @param response 响应对象
     */
    private void handleResponseStatus(Response response) {
        if (!response.isSuccessful()) {
            String errorMsg = String.format("请求失败：状态码=%d，原因=%s", response.code(), response.message());
            throw new AIInvokeException(errorMsg, response.code());
        }
        if (response.body() == null) {
            throw new AIInvokeException("响应体为空");
        }
    }

    /**
     * 处理流式响应（核心逻辑：逐行读取、解析 delta.content、拼接完整回复）
     * 流式响应格式：data:{"choices":[{"delta":{"content":"xxx"}}]} + data:[DONE]
     * @param response 响应对象
     * @return 完整回复字符串
     * @throws IOException 读取流异常
     */
    private String handleStreamResponse(Response response) throws IOException {
        StringBuilder fullReply = new StringBuilder();
        BufferedSource source = response.body().source();
        while (!source.exhausted()) {
            String line = source.readUtf8Line();
            if (line == null || line.isEmpty()) {
                continue;
            }
            if (line.startsWith("data:")) {
                String jsonPart = line.substring(5).trim();
                if (jsonPart.equals("[DONE]")) {
                    break;
                }
                try {
                    JSONObject json = new JSONObject(jsonPart);
                    String content = json.getJSONArray("choices").getJSONObject(0)
                            .getJSONObject("delta").getString("content");
                    if (!content.isEmpty()) {
                        fullReply.append(content);
                        if (config.isPrintRealTime()) {
                            System.out.print(content);
                        }
                    }
                } catch (Exception e) {
                    continue;
                }
            }
        }
        if (config.isPrintRealTime() && fullReply.length() > 0) {
            System.out.println();
        }
        return fullReply.toString();
    }

    /**
     * 处理非流式响应（备用：一次性获取完整回复）
     * @param response 响应对象
     * @return 完整回复字符串
     * @throws IOException 读取响应体异常
     */
    private String handleNonStreamResponse(Response response) throws IOException {
        String responseStr = response.body().string();
        JSONObject json = new JSONObject(responseStr);
        return json.getJSONArray("choices").getJSONObject(0)
                .getJSONObject("message").getString("content");
    }
}

三、快速使用示例

以下示例演示如何一键切换 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 + "\n");

            // ========== 3. 一键切换到 OpenAI（GPT-3.5）==========
            AIClientConfig openAIConfig = AIClientConfig.openAIConfig("你的 OpenAI Token", "gpt-3.5-turbo");
            // 可选配置代理（访问 OpenAI 必须）
            openAIConfig.setProxy("127.0.0.1", 7890);
            AIGeneralClient openAIClient = new AIGeneralClient(openAIConfig);
            System.out.println("=== OpenAI（GPT-3.5）回复 ===");
            String openAIReply = openAIClient.sendMessage(prompt);
            System.out.println("完整回复：" + openAIReply);
        } catch (AIInvokeException e) {
            System.err.println("调用失败：" + e.getMessage());
            if (e.getCode() != null) {
                switch (e.getCode()) {
                    case 401: System.err.println("错误原因：API 密钥无效或已过期"); break;
                    case 429: System.err.println("错误原因：请求过于频繁，触发限流"); break;
                    case 404: System.err.println("错误原因：API 地址错误或模型不存在"); break;
                    case 500: System.err.println("错误原因：平台服务异常，请稍后重试"); break;
                }
            }
            e.printStackTrace();
        }
    }
}

四、关键特性说明

4.1 一键切换平台

通过配置类的快捷方法（如 customConfig()、zhipuConfig()），只需传入对应平台的 Token，即可完成切换，核心调用逻辑完全不变。

4.2 完整异常处理

所有异常统一封装为 AIInvokeException，包含：

• 配置校验异常（空 API 地址/密钥）
• 网络异常（连接超时、IO 异常）
• HTTP 状态码异常（401/429/404/500 等）
• JSON 解析异常（响应格式错误）

上层可通过捕获异常，根据状态码快速定位问题（如 401=密钥无效，429=限流）。

4.3 灵活配置项

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 处即可适配：

1. 请求体格式不同：修改 buildRequestBody() 方法，按平台文档构造请求体；
2. 流式响应格式不同：修改 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 等特殊字符。