说实话，刚接触 Spring AI 的时候，那种兴奋劲儿简直没法形容。kan着官方文档里几行代码就Neng跑起一个大模型，心里想的是：“哇，这也太丝滑了吧！”结果呢？真到自己动手搭项目的时候，那叫一个步步惊心。这哪是写代码啊，简直是在玩“扫雷”，每走一步dou可Neng踩到一个让人抓狂的报错。

这几天折腾 Spring AI Alibaba，我算是把Neng踩的坑dou踩了个遍。从依赖拉不下来到 JDK 版本不对劲，再到那个让人摸不着头脑的 ChatMemory 失忆问题，每一个dou够我喝一壶的。今天我就把这些血泪史整理出来不是为了吐槽，纯粹是想给后来者提个醒，别再像我一样在同一个坑里摔好几次跟头。

一、依赖拉取失败：Maven 仓库的“迷魂阵”

这绝对是新手遇到的第一个拦路虎。你照着文档把 pom.xml 写得漂漂亮亮，结果一运行 mvn compile，控制台直接给你甩一脸红：Could not find artifact...。

这事儿吧，真不怪你。Spring AI 的相关包目前还没正式进驻 Maven 中央仓库，它们大多还在 Spring 的 Milestone仓库里待着呢。Ru果你只配置了默认的中央仓库，Maven 自然是两眼一抹黑，找不到你要的 jar 包。

1. 仓库配置没加全

hen多人只加了 Spring 的仓库，却忘了 Sonatype 的快照仓库。虽然 Milestone 比较稳定，但有时候你想尝鲜Zui新的 Snapshot 版本，没配这个仓库也是白搭。

这里有个标准的配置姿势，建议直接抄作业：

    
        spring-milestones
        Spring Milestones
        https://repo.spring.io/milestone
        
            false
        
    
    
        sonatype-snapshots
        Sonatype Snapshot Repository
        https://oss.sonatype.org/content/repositories/snapshots
        
            false
        
        
            true
        
    

2. 阿里云镜像的“误伤”

在国内开发，为了加速依赖下载，大家通常dou会配置阿里云的 Maven 镜像。这本来是好事，但有时候好心办坏事。Ru果你的镜像配置里用了 *，那就意味着所有请求dou会被拦截到阿里云去。

问题来了阿里云镜像有时候同步 Milestone 或者 Snapshot 仓库没那么及时。结果就是：你明明配置了 Spring 的仓库，但被镜像覆盖了根本没去那儿找，Zui后还是报错找不到依赖。

解决办法就是精准打击，别用通配符 *。改成这样，只镜像中央仓库和 Spring Milestones，放过 Sonatype：

    aliyunmaven
    spring-milestones,central
    Aliyun Maven
    https://maven.aliyun.com/repository/public

二、环境版本不兼容：JDK 的“傲娇”

好不容易把依赖拉下来了兴冲冲地启动项目，结果直接崩给你kan。报错信息里Zui扎心的莫过于这句：java.lang.UnsupportedClassVersionError。

这通常后面跟着一串提示，大概意思是 class file version 不匹配。这事儿吧，得怪 Spring Boot 3.x 太“激进”了。Spring AI 是基于 Spring Boot 3.x 构建的，而 Spring Boot 3.x 底层要求 JDK 必须是 17 及以上版本。

Ru果你电脑上还装着 JDK 8 或者 JDK 11，那肯定跑不起来。我就吃过这亏，明明代码写得没错，怎么跑dou是错，Zui后一kan环境变量，好家伙，还是 JDK 11。

别犹豫了赶紧去下载个 JDK 17 或者 21。推荐用 Alibaba Dragonwell 或者 Adoptium 的发行版，稳得hen。装好之后记得在 IDE 里把 Project SDK 改过来别光改了环境变量，IDE 里用的还是旧的。

# 确认一下版本，别骗自己
java -version

三、API Key 与模型配置：Zui基础的“低级错误”

有时候项目启动成功了接口也Neng调，但就是返回 401 或者 403。这时候十有八九是 Key 的问题。

1. Key 没生效或者写错了

这听起来hen弱智，但真的hen容易发生。比如你在 application.yml 里写了 Key，但名字写错了或者没被 Spring 正确加载。

还有一种情况，你用了环境变量，但在 IDE 里没配置好，导致读取的是空值。你Ke以试着在代码里打印一下或者用命令行kankan：

# Windows PowerShell
echo $env:ZHIPUAI_API_KEY
# macOS / Linux
echo $ZHIPUAI_API_KEY

Ru果输出是空的，那就别怪模型不理你了赶紧去环境变量里补上。另外配置文件里Zui好给个默认值占位，防止启动报错：

spring:
  ai:
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY:your-api-key-here}

2. 模型名称拼写错误

这坑我踩过当时差点把键盘砸了。报错信息大概是 model not found。我反复检查 Key，没问题啊！网络也没问题啊！

Zui后仔细一kan，模型名称大小写搞错了或者多打了一个横杠。智谱和通义千问的模型命名dou挺严格的，glm-4-flash 就是 glm-4-flash，你写成 GLM-4-FLASH 或者 glm4flash dou不行。这种细节，文档里有时候不会特意强调，全靠你自己试错。

四、Bean 冲突：选择困难症

随着项目深入，你可Neng想同时接入多个模型，比如既想用智谱，又想试试通义千问。于是你大笔一挥，把两个 Starter dou引进来了：

    org.springframework.ai
    spring-ai-starter-model-zhipuai


    com.alibaba.cloud.ai
    spring-ai-alibaba-starter

结果启动时报了个 NoUniqueBeanDefinitionException。这错误信息翻译过来就是：“Spring 容器里发现了好几个 ChatClient.Builder，我不知道该用哪一个给你注入。”

每个 Starter dou会自动装配自己的 Builder，你一股脑全引进来Spring 自然就懵了。这时候你有两个选择：

方案一：Zuo减法。 暂时只用哪个模型，就保留哪个 Starter，其他的先注释掉。简单粗暴，但有效。

方案二：手动指定。 在配置类里显式地定义你要用的 Bean，告诉 Spring：“别管其他的，我就要这个。”

@Configuration
public class ChatClientConfig {
    @Bean
    public ChatClient zhipuChatClient {
        return builder.defaultSystem.build;
    }
}

五、ChatMemory 失忆：上下文去哪了？

这绝对是Zuo对话类应用Zui头疼的问题。你明明配置了 MessageChatMemoryAdvisor，结果上一句问“我叫张三”，下一句问“我叫什么”，模型一脸懵逼地回“我不知道啊”。

1. 作用域搞错了

hen多人一开始会这么写：

public String chat {
    ChatMemory memory = new MessageWindowChatMemory.builder.maxMessages.build;
    return ChatClient.builder
            .defaultAdvisors)
            .build
            .prompt
            .call
            .content;
}

这kan起来没毛病，但实际上是个大坑。因为 ChatMemory 是在方法内部创建的局部变量，方法执行完它就销毁了。每次请求dou是一个新的内存，模型当然记不住上一句说了啥。

正确的Zuo法是把 ChatMemory 提升为类成员变量，或者直接注册成一个 Bean，让它的生命周期变长。

private final ChatMemory chatMemory = MessageWindowChatMemory.builder
        .maxMessages
        .build;
public ChatController {
    this.chatClient = chatClientBuilder
            .defaultAdvisors.build)
            .build;
}

2. 多实例部署的坑

Ru果你的服务是单机玩的，上面那招就够了。但Ru果你用了多实例部署，比如起了两个 Pod，那问题又来了。

用户第一次请求打到了 A 实例，A 记住了“张三”。第二次请求被负载均衡转发到了 B 实例，B 的内存里是一片空白，自然就回答不上来。

这时候就得祭出 Redis 了。你需要引入一个基于 Redis 的 ChatMemory 实现，把对话上下文持久化到外部存储里。这样不管请求打到哪个实例，douNeng从 Redis 里把之前的聊天记录捞出来。这算是分布式架构下的额外开销，没办法，谁让咱们要搞高可用呢。

六、编码与网络：隐形的杀手

除了逻辑上的坑，还有一些物理层面的坑，比如字符编码和网络代理。

1. 中文乱码问题

有时候你用 Postman 调接口没问题，用浏览器地址栏直接传中文参数就乱码。返回的结果也是牛头不对马嘴。

这通常是 URL 编码的问题。Tomcat 默认对 URL 参数的编码处理有时候不太给力，虽然 Spring Boot 2.x 之后改成了 UTF-8，但在某些特定配置下还是会抽风。

Zui稳妥的办法是别用 GET 传参，直接用 POST + JSON。JSON 的编码标准统一，基本不会出问题。

@PostMapping
public String simpleChat {
    String query = request.get;
    return chatClient.prompt.call.content;
}

Ru果你非要用 GET，记得在 application.yml 里强制指定编码：

server:
  servlet:
    encoding:
      charset: UTF-8
      enabled: true
      force: true

2. 网络超时与代理

在国内用智谱或者通义千问，网络一般dou挺顺畅。但Ru果你公司网络限制严格，或者你非要连 OpenAI，那可Neng会遇到请求一直 pending，Zui后超时的情况。

先试试Neng不Neng ping 通目标域名：

ping open.bigmodel.cn
curl -v https://open.bigmodel.cn/api/paas/v4

另外千万别在代码里设全局代理。这玩意儿一旦设了你请求头里的 API Key 可Neng会被代理转发到奇怪的地方去，轻则报错，重则泄露 Key，风险极大。

七、版本迭代太快：API 变脸比翻书还快

Zui后吐槽一下版本问题。Spring AI 和 Spring AI Alibaba 现在dou还在快速迭代期，版本之间的 API 兼容性真的没保证。

我之前从 1.0.0-M5 升级到 1.0.0-M6，结果发现好多类名dou变了方法签名也变了之前的代码直接跑不起来。这种体验真的hen崩溃，感觉就像刚学会怎么用，人家就改规则了。

所以建议你在生产环境里锁定版本，别动不动就追新。除非你有大把的时间去改代码适配新 API。在 pom.xml 里显式指定版本号，别用 BOM 里默认的，免得哪天突然升级了给你来个措手不及。

写在Zui后

这一路踩坑过来虽然过程挺折磨人的，但kan到Zui后程序跑通，模型Neng流利地回答问题，那种成就感也是实打实的。Spring AI Alibaba 这个方向肯定是对的，它把大模型开发的门槛降到了普通 Java 开发者也Neng摸得着的程度。

只是现在毕竟还处于早期阶段，各种文档缺失、兼容性问题在所难免。希望我记录的这些“惨痛教训”，Neng帮你省下几个熬夜修 Bug 的夜晚。遇到问题别慌，多kan日志，多查源码，实在不行就去社区里吼一嗓子，毕竟咱们dou不是一个人在战斗。

---