【Spring AI & LangChain4j 基础篇】Spring AI + LangChain4j环境搭建避坑指南：从依赖配置到大模型接入一步到位

摘要：本文提供Spring AI + LangChain4j的Java开发环境搭建指南，5分钟快速初始化，支持本地Ollama及国内大模型接入。关键步骤包括：版本适配：JDK 17+、Spring Boot 3.2.x、Spring AI 0.8.1与LangChain4j 0.24.0组合；项目初始化：IDEA创建Spring Boot项目，Maven配置依赖；模型接入：本地Ollama

小可爱awo

354人浏览 · 2026-02-26 21:41:42

小可爱awo · 2026-02-26 21:41:42 发布

在这里插入图片描述

🍃 予枫：个人主页
📚 个人专栏: 《Java 从入门到起飞》《读研码农的干货日常》

💻 Debug 这个世界，Return 更好的自己！

引言

大模型开发热潮下，Spring AI + LangChain4j成为Java开发者快速落地大模型应用的热门组合，但环境搭建时的版本兼容、依赖冲突、API配置等问题，让很多新手望而却步。本文整理保姆级实操步骤，5分钟搞定环境初始化，覆盖本地Ollama部署与国内主流大模型接入，附常见踩坑解决方案，新手也能直接上手！

文章目录

引言
一、环境前置要求（必看）
- 1.1 基础环境要求
- 1.2 依赖版本对应关系（关键）
二、零基础初始化Spring Boot项目（实操步骤）
- 2.1 新建Spring Boot项目（IDEA操作）
- 2.2 集成Spring AI + LangChain4j依赖（Maven配置）
三、大模型接入准备（本地+云端）
- 3.1 本地Ollama部署（零成本，新手首选）
- 3.2 国内主流大模型API接入（进阶）
四、常见环境踩坑避坑指南（重点）
五、结尾总结

一、环境前置要求（必看）

环境搭建的核心是「版本适配」，选对版本能避开80%的坑，建议直接按以下配置准备，无需自行摸索版本组合~ 😊

1.1 基础环境要求

JDK版本：必须JDK 17及以上（Spring Boot 3.x和Spring AI的最低要求，低于17会直接报错）
Spring Boot版本：3.2.x（稳定版，亲测适配Spring AI 0.8.1和LangChain4j 0.24.0，避免使用3.3.x及以上预览版）
构建工具：Maven 3.8.x 或 Gradle 8.0+（推荐Maven，配置更简洁，新手友好）
开发工具：IntelliJ IDEA（推荐2022.3及以上版本，支持Spring Boot 3.x和大模型插件，提升开发效率）

1.2 依赖版本对应关系（关键）

重点提醒：Spring AI与LangChain4j的版本绑定较严格， mismatch会导致依赖冲突，建议直接沿用以下组合：

Spring AI：0.8.1（稳定版，支持Ollama、通义千问、文心一言等主流大模型）
LangChain4j：0.24.0（与Spring AI 0.8.1完美兼容，无依赖冲突）

二、零基础初始化Spring Boot项目（实操步骤）

这一步全程可视化操作，新手跟着做就能完成，建议收藏本文，后续搭建可直接参考~ 👍

2.1 新建Spring Boot项目（IDEA操作）

打开IDEA，点击「New Project」，选择「Spring Initializr」，点击「Next」；
填写项目基本信息：
- Group：自定义（如com.yufeng）
- Artifact：自定义（如spring-ai-langchain4j-demo）
- Package：自动生成（可修改，如com.yufeng.demo）
- Java Version：选择17
- Spring Boot Version：选择3.2.5（稳定版）
点击「Next」，无需勾选默认依赖（后续手动添加，避免冗余）；
选择项目保存路径，点击「Finish」，等待项目初始化完成（首次初始化会下载依赖，耐心等待）。

2.2 集成Spring AI + LangChain4j依赖（Maven配置）

打开项目的pom.xml文件，添加以下依赖，复制粘贴即可，无需修改（已适配版本）：

<!-- Spring Boot 父依赖 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
    <relativePath/>
</parent>

<dependencies>
    <!-- Spring Boot Web依赖（用于后续接口开发，可选） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI 核心依赖 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-core</artifactId>
        <version>0.8.1</version>
    </dependency>

    <!-- Spring AI 大模型通用依赖（支持Ollama、通义千问等） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-llm</artifactId>
        <version>0.8.1</version>
    </dependency>

    <!-- LangChain4j 核心依赖 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-core</artifactId>
        <version>0.24.0</version>
    </dependency>

    <!-- LangChain4j 与 Spring AI 集成依赖（关键，实现两者联动） -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-spring-ai</artifactId>
        <version>0.24.0</version>
    </dependency>

    <!-- 测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<!-- 配置Spring AI仓库（必加，否则无法下载依赖） -->
<repositories>
    <repository><id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

添加完成后，点击IDEA右侧「Maven」->「Reload All Maven Projects」，等待依赖下载完成（若下载缓慢，可配置国内镜像，文末附解决方案）。

三、大模型接入准备（本地+云端）

环境搭建完成后，需要接入大模型才能进行开发，这里提供两种方案，新手推荐先从本地Ollama入手（无需API密钥，零成本测试），进阶用户可接入国内主流大模型。

3.1 本地Ollama部署（零成本，新手首选）

Ollama是一款轻量级大模型部署工具，支持本地运行Llama 3、Qwen等模型，无需复杂配置，步骤如下：

下载Ollama：访问Ollama官方网站，根据自己的系统（Windows/Mac/Linux）下载对应安装包，一键安装；
启动Ollama：安装完成后，打开终端（Windows打开CMD，Mac打开终端），输入命令启动服务：
```
# 启动Ollama服务（默认端口11434）
ollama serve
```
拉取模型：新终端输入命令，拉取轻量级模型（推荐Qwen 7B，占用内存小，运行流畅）：
```
# 拉取Qwen 7B模型（约4GB，根据网络速度调整）
ollama pull qwen:7b
```
测试连接：拉取完成后，输入命令测试模型是否可用：
```
ollama run qwen:7b
```
输入问题（如“Spring AI是什么”），能正常返回结果即部署成功。

3.2 国内主流大模型API接入（进阶）

若需要使用通义千问、文心一言、智谱AI等国内大模型，需先获取API密钥，再配置到项目中，以通义千问为例：

获取API密钥：
- 访问通义千问开放平台，注册并登录账号；
- 进入「控制台」->「AccessKey管理」，创建并复制AccessKey ID和AccessKey Secret（妥善保存，不要泄露）。

项目配置（application.yml）：
在src/main/resources目录下，新建application.yml文件，添加以下配置：

spring:
  ai:
    tongyi:
      api-key: 你的AccessKey ID
      secret-key: 你的AccessKey Secret
      model: qwen-max  # 模型名称，可根据需求更换（如qwen-plus、qwen-turbo）

其他大模型配置类似，只需替换对应的配置项即可，例如文心一言需配置spring.ai.baidu.api-key，智谱AI配置spring.ai.zhipu.api-key，具体参数可参考官方文档。

四、常见环境踩坑避坑指南（重点）

这部分整理了开发者搭建环境时最常遇到的问题，每个问题都附解决方案，建议点赞收藏，遇到问题直接对照查找~ ✨

4.1 依赖冲突问题（最常见）

问题现象：

启动项目时出现「NoClassDefFoundError」「ClassNotFoundException」，或Maven报错「Dependency convergence error」。

解决方案：

严格沿用本文推荐的版本组合（Spring Boot 3.2.x + Spring AI 0.8.1 + LangChain4j 0.24.0），不要随意升级或降级；

若必须修改版本，使用Maven的「dependency:tree」命令查看依赖树，排除冲突的依赖，例如：

<!-- 排除冲突的依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>0.8.1</version>
    <exclusions>
        <exclusion>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

4.2 JDK版本不兼容问题

问题现象：

项目启动报错「UnsupportedClassVersionError」，提示“major version 61 is required”（JDK 17对应版本61）。

解决方案：

检查IDEA的JDK配置：File -> Project Structure -> Project SDK，选择JDK 17；

检查pom.xml中的java.version配置，确保为17：

<properties>
    <java.version>17</java.version>
</properties>

重启IDEA，重新加载Maven依赖。

4.3 依赖下载失败问题

问题现象：

Maven拉取Spring AI依赖时，出现「Could not find artifact」或下载缓慢。

解决方案：

确认pom.xml中已添加Spring Milestones仓库（本文2.2节已配置）；

配置国内Maven镜像（阿里云镜像），修改本地Maven的settings.xml文件：

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>central</mirrorOf>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
    <mirror>
        <id>spring-milestones</id>
        <mirrorOf>spring-milestones</mirrorOf>
       <url>https://maven.aliyun.com/repository/spring-milestones</url>
    </mirror>
</mirrors>

重启IDEA，重新加载Maven依赖。

4.4 大模型API调用失败问题

问题现象：

调用大模型时，出现「API key is invalid」「Connection timed out」等错误。

解决方案：

检查API密钥是否正确，是否泄露或过期（国内大模型API密钥有有效期，需定期更新）；
检查网络连接，国内大模型API需确保网络能正常访问官方服务器，若使用代理，需配置代理信息；
检查模型名称是否正确，不同大模型的模型名称不同，需参考官方文档配置。

五、结尾总结

本文从环境前置要求、项目初始化、大模型接入（本地Ollama+云端API）、常见踩坑四个方面，详细讲解了Spring AI + LangChain4j开发环境的搭建流程，全程保姆级实操，新手也能快速上手。核心是把握「版本适配」原则，避开依赖冲突和JDK版本问题，再根据需求选择本地或云端大模型接入，即可快速开启大模型开发之旅。

✨ 创作不易，若本文对你有帮助，麻烦点赞+收藏，关注博主「予枫」，后续将持续更新Spring AI、LangChain4j相关实战教程，带你快速落地大模型应用！

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐