Java大模型集成攻略

程序员NEO

发布于 2026-04-29 19:00:47

1310

本文将介绍在 Java 项目中集成各种大模型的方法，并以阿里巴巴 DashScope SDK 为例进行重点讲解。项目环境：SpringBoot 3.4.4，JDK 21，Maven 3.8.4。

SDK 接入

SDK（软件开发工具包）是官方提供的集成工具，通常包含完善的类型定义和错误处理机制，让集成更便捷。

下面以阿里巴巴 DashScope SDK 为例，演示如何在 Java 项目中集成。

1. 安装 DashScope SDK
- • 首先，参考官方文档安装 SDK：安装 SDK 官方指南
- • 选择 SDK 版本时，建议前往 Maven 中央仓库确认最新版本号：Maven中央仓库版本信息
- • 在项目的 pom.xml 文件中添加以下依赖：

<!-- https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.19.1</version>
</dependency>

2. 在阿里云百炼平台申请 API Key。请务必妥善保管，防止泄露：

https://bailian.console.aliyun.com/?tab=app#/app-center

3. 在项目中创建一个名为 demo.invoke 的包，用于存放调用大模型的示例代码。

详细代码示例请参考官方文档：通过 API 调用通义千问，如下图所示：

为了安全地管理 API 密钥，可以创建一个接口来存储它。注意：在生产环境中，强烈建议使用配置文件或环境变量管理 API Key，避免将其硬编码到代码中。

public interface TestApiKey {
    // 请将下方的 "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 替换为您的真实有效 API Key
    String API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; 
}

以下是使用 SDK 调用模型的完整 Java 示例代码：

// 建议 DashScope SDK 版本 >= 2.12.0
// 导入所需的Java标准库类
import java.util.Arrays;
import java.lang.System;

// 导入阿里云灵积 DashScope SDK 相关类
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

/**
 * 阿里云灵积 AI SDK 调用示例。
 * <p>
 * 本类演示了如何使用 DashScope SDK 调用阿里云灵积大模型进行对话，
 * 包括消息构建、参数设置、API 调用及异常处理。
 */
public class SdkAiInvoke {
    /**
     * 调用阿里云灵积大模型生成接口，传入对话消息，并返回生成结果。
     *
     * @return GenerationResult 生成结果对象，包含模型回复等信息。
     * @throws ApiException           API 调用异常。
     * @throws NoApiKeyException      未配置 API Key 异常。
     * @throws InputRequiredException 输入参数缺失异常。
     */
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // 创建 Generation 实例，用于发起生成请求
        Generation gen = new Generation();

        // 构建系统消息，设定 AI 助手的角色和行为
        // Role.SYSTEM 代表系统角色，用于设定 AI 的行为或身份。
        // content 字段为系统提示内容，用以指导 AI 如何回复。
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();

        // 构建用户消息，模拟用户输入
        // Role.USER 代表用户角色，content 字段为用户输入内容。
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("你是谁？")
                .build();

        // 构建生成参数，包括 API Key、模型名称、消息列表、返回格式等
        // GenerationParam 用于封装所有请求参数。
        GenerationParam param = GenerationParam.builder()
                // 设置 API Key。TestApiKey.API_KEY 从接口获取。
                // 生产环境建议通过环境变量配置，或直接使用 .apiKey("sk-您的真实APIKey") 替换此行。
                .apiKey(TestApiKey.API_KEY) 
                // 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models
                .model("qwen-plus")
                // .messages() 传入对话消息列表，通常顺序为系统消息、用户消息。
                .messages(Arrays.asList(systemMsg, userMsg))
                // .resultFormat() 设置返回结果的格式为消息格式。
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();

        // 调用生成接口，获取模型回复
        // gen.call(param) 方法向阿里云灵积大模型服务发起请求。
        // 返回 GenerationResult 对象，其中包含模型回复、Token 用量等信息。
        return gen.call(param);
    }

    /**
     * 主方法，程序入口。
     *
     * @param args 命令行参数
     */
    public static void main(String[] args) {
        try {
            // 调用 callWithMessage() 方法，获取 AI 回复结果。
            // GenerationResult 对象中包含了模型回复内容、Token 用量等详细信息。
            GenerationResult result = callWithMessage();

            // 将结果对象转为 JSON 字符串并打印
            // JsonUtils.toJson(result) 方法将 Java 对象序列化为 JSON 字符串，方便查看完整的响应结构。
            System.out.println(JsonUtils.toJson(result));

            // 示例输出结构如下（已注释）：
            // {
            //     "requestId": "...", // 请求唯一标识
            //     "usage": {
            //         "input_tokens": ..., // 输入token数
            //         "output_tokens": ..., // 输出token数
            //         "total_tokens": ...  // 总token数
            //     },
            //     "output": {
            //         "choices": [
            //             {
            //                 "finish_reason": "stop", // 结束原因
            //                 "message": {
            //                     "role": "assistant", // 回复角色
            //                     "content": "..."      // AI回复内容
            //                 }
            //             }
            //         ]
            //     }
            // }
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 捕获并处理调用生成服务时可能发生的异常。
            // ApiException：API 调用异常，可能由网络问题、服务端错误等引起。
            // NoApiKeyException：未配置 API Key 时抛出的异常。
            // InputRequiredException：必要输入参数缺失时抛出的异常。
            // 此处直接打印到标准错误输出。在实际项目中，建议使用日志框架记录异常，以便追踪和排查问题。
            System.err.println("调用生成服务时发生错误: " + e.getMessage());
        }
        // 程序执行完毕，正常退出。
        System.exit(0);
    }
}

4. 运行项目后，可以看到 AI 的回复：

HTTP 接入

如果 SDK 不支持您的编程语言，或者您需要更灵活地控制请求，可以直接通过 HTTP 请求调用 AI 大模型的 API。

💡 建议：如果官方提供了 SDK，优先使用 SDK。仅当 SDK 不支持或不适用时，才考虑直接通过 HTTP 调用。

HTTP 调用的详细说明请参考官方文档：通过 API 调用通义千问

您可以让 AI 将上述 CURL 命令转换为使用 Java Hutool 工具类的网络请求代码。示例 Prompt 如下：

将上述请求转换为 Hutool 工具类的请求代码

AI 生成的代码如下（可根据实际需求调整）：

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.json.JSONObject;

import java.util.HashMap;
import java.util.Map;

/**
 * 本类演示了如何通过 HTTP 请求调用阿里云通义千问大模型接口进行文本生成，
 * 并使用 Hutool 工具库简化 HTTP 请求和 JSON 构建。
 */
public class HttpAiInvoke {
    public static void main(String[] args) {
        // 定义接口请求的 URL，替换为实际的 API 地址
        String url = "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation";

        // 创建请求头的 Map，用于存放 HTTP 请求头信息
        Map<String, String> headers = new HashMap<>();
        // 设置 Authorization 头，使用 Bearer 方式携带 API 密钥
        headers.put("Authorization", "Bearer " + TestApiKey.API_KEY);
        // 设置 Content-Type 头，指定请求体为 JSON 格式
        headers.put("Content-Type", "application/json");

        // 构建请求体的 JSON 对象
        JSONObject requestBody = new JSONObject();
        // 指定使用的模型名称
        requestBody.put("model", "qwen-plus");

        // 创建 input 字段的 JSON 对象
        JSONObject input = new JSONObject();
        // 创建消息数组，包含 system 和 user 两种角色的消息
        JSONObject[] messages = new JSONObject[2];

        // 构建 system 消息，指定 AI 助手的身份和行为
        JSONObject systemMessage = new JSONObject();
        systemMessage.put("role", "system");
        systemMessage.put("content", "You are a helpful assistant.");
        messages[0] = systemMessage;

        // 构建 user 消息，指定用户输入的内容
        JSONObject userMessage = new JSONObject();
        userMessage.put("role", "user");
        userMessage.put("content", "你是谁？");
        messages[1] = userMessage;

        // 将消息数组放入 input 对象
        input.put("messages", messages);
        // 将 input 对象放入请求体
        requestBody.put("input", input);

        // 构建参数对象，设置返回结果格式为 message
        JSONObject parameters = new JSONObject();
        parameters.put("result_format", "message");
        // 将参数对象放入请求体
        requestBody.put("parameters", parameters);

        // 发送 HTTP POST 请求，携带请求头和请求体
        HttpResponse response = HttpRequest.post(url)
                .addHeaders(headers)
                .body(requestBody.toString())
                .execute();

        // 判断响应是否成功
        if (response.isOk()) {
            // 请求成功时输出响应内容
            System.out.println("请求成功，响应内容：");
            System.out.println(response.body());
        } else {
            // 请求失败时输出状态码和响应内容
            System.out.println("请求失败，状态码：" + response.getStatus());
            System.out.println("响应内容：" + response.body());
        }
    }
}

SpringAI 接入

关于 Spring AI 的基础知识，可以参考我之前的文章：Spring AI 搭建本地 AI。

Spring AI 默认并不支持所有大模型（特别是国产模型），它主要支持与 OpenAI API 兼容的大模型集成（详见官方模型对比）。因此，要调用阿里系大模型（如通义千问），推荐使用阿里封装的 Spring AI Alibaba 框架。该框架能便捷地集成阿里系大模型，并与标准 Spring AI 兼容。

您可以参考以下官方文档来完成大模型的调用流程：

• 灵积模型接入指南
• 通义千问接入指南

1. 引入依赖：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter</artifactId>
    <version>1.0.0-M6.1</version>
</dependency>

官方提示：由于部分 spring-ai 相关依赖包尚未发布到 Maven 中央仓库，如果遇到 spring-ai-core 等依赖解析问题，请在项目的 pom.xml 文件的 <repositories> 配置中添加以下仓库：

<repositories>
  <repository>
    <id>spring-milestones</id>
    <name>Spring Milestones</name>
    <url>https://repo.spring.io/milestone</url>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

2. 编写配置：

spring:
  application:
    name: spring-ai-alibaba-qwq-chat-client-example
  ai:
    dashscope:
      # 请替换为您的 API Key 或通过环境变量设置
      api-key: ${AI_DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-plus

3. 编写示例代码 (注意注入 dashscopeChatModel)：

import jakarta.annotation.Resource;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component; // 确保导入 Component 注解

@Component // 将此类声明为 Spring 组件
public class SpringAiAiInvoke implements CommandLineRunner {

    /**
     * 注入 ChatModel 实例，代表一个可用的 AI 聊天模型。
     * 通过 @Resource 注解自动装配，bean 名称为 dashscopeChatModel。
     */
    @Resource
    private ChatModel dashscopeChatModel;

    /**
     * 应用启动时自动调用的方法。
     * 该方法向 AI 聊天模型发送问候语，并打印 AI 的回复。
     *
     * @param args 启动参数
     * @throws Exception 可能抛出的异常
     */
    @Override
    public void run(String... args) throws Exception {
        // 创建一个新的 Prompt 实例，内容为“你好，我是 NEO”
         Prompt prompt = new Prompt("你好，我是 NEO");

        // 调用 dashscopeChatModel 的 call 方法，传入 prompt，获取 AI 回复
        AssistantMessage assistantMessage = dashscopeChatModel.call(prompt)
                .getResult() // 获取调用结果对象
                .getOutput(); // 获取 AI 输出的消息对象

        // 打印 AI 助手的回复文本到控制台
        System.out.println("Assistant Response: " + assistantMessage.getText());
    }
}

上述代码实现了 CommandLineRunner 接口。启动 Spring Boot 项目时，会自动注入大模型 ChatModel 依赖，并执行一次该类的 run 方法，用于测试。

💡 上述代码通过 ChatModel 对象调用大模型，适合简单对话场景。Spring AI 还提供了 ChatClient 调用方式，支持会话记忆等高级功能，更适合复杂场景，后续会有详细介绍。

LangChain4j

与 Spring AI 类似，LangChain4j 是一个用于构建基于大语言模型（LLM）应用的 Java 框架。作为知名 AI 框架 LangChain 的 Java 版，它提供了丰富的工具和抽象，简化了与 LLM 的交互及应用开发。

LangChain 官方目前未直接支持阿里系大模型，但可以使用社区版整合的大模型包。

支持的模型列表可在其官方文档中查询：LangChain4j模型集成

要接入阿里云灵积模型，可参考官方文档：DashScope模型集成，其中包含依赖和示例代码。

1. 引入依赖：

<!-- https://mvnrepository.com/artifact/dev.langchain4j/langchain4j-community-dashscope -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-dashscope</artifactId>
    <version>1.0.0-beta2</version> <!-- 请检查并使用最新稳定版 -->
</dependency>

值得注意的是，LangChain4j 也提供了 Spring Boot Starter，方便在 Spring 项目中使用（最新版本号可在 Maven 中央仓库查询）。本示例仅为演示，且已引入 Spring AI Starter，故不再引入 LangChain Starter，以避免潜在冲突。

2. 编写示例代码：参考官方文档创建一个 ChatModel 并调用，其用法与 Spring AI 类似。

import dev.langchain4j.community.model.dashscope.QwenChatModel;

public class LangChainAiInvoke {
    /**
     * 程序主入口。
     * 运行后会向 Qwen Max 模型发送消息，并输出模型回复。
     * 
     * @param args 命令行参数（本示例未使用）
     */
    public static void main(String[] args) {
        // 创建 QwenChatModel 的构建器，用于配置模型参数
        QwenChatModel qwenChatModel = QwenChatModel.builder()
                // 设置 API Key，用于身份认证，必须替换为你自己的有效 Key
                .apiKey(TestApiKey.API_KEY) // 确保 TestApiKey.API_KEY 已正确配置
                // 指定要使用的模型名称，这里选择 "qwen-max"
                .modelName("qwen-max") // 可根据需求选择其他模型，如 qwen-plus, qwen-turbo 等
                // 构建出 QwenChatModel 实例，后续可以用它与大模型对话
                .build();

        // 向 Qwen Max 发送一条消息，chat 方法会返回模型的回复内容
        String response = qwenChatModel.chat("你好，Qwen Max！请问你能帮我做什么？");

        // 将模型的回答输出到控制台，方便查看结果
        System.out.println("Qwen Max的回答: " + response);
    }
}

最后，直接运行 main 方法即可测试。

接入方式对比

以下是四种 AI 大模型接入方式的优缺点对比：

接入方式	优点	缺点	适用场景
SDK 接入	• 类型安全，编译时检查• 完善的错误处理• 通常有详细文档• 性能较优	• 依赖特定版本• 可能增加项目体积• 受限于特定编程语言	• 需要深度集成• 针对单一模型提供商• 对性能要求高的场景
HTTP 接入	• 无编程语言限制• 不增加额外依赖• 灵活性高	• 需手动处理错误• 序列化/反序列化处理繁琐• 代码可能较冗长	• SDK 不支持的编程语言• 简单原型验证• 临时或轻量级集成
Spring AI	• 统一的抽象接口• 易于切换模型提供商• 与 Spring 生态完美融合• 提供高级功能（如多模态、函数调用）	• 存在额外抽象层• 可能无法支持特定模型的全部特性• 版本迭代快，需关注兼容性	• Spring 应用• 需支持多种模型或平滑切换• 需要高级 AI 功能的场景
LangChain4j	• 提供完整的 AI 应用工具链• 支持复杂工作流编排• 拥有丰富的组件和工具• 适合构建 AI 代理（Agent）等复杂应用	• 学习曲线较陡峭• 部分社区模块文档可能不完善• 抽象层可能引入性能开销	• 构建复杂 AI 应用• 需要链式操作和工作流• RAG（检索增强生成）应用开发