2026 年,AI 应用已经不是 Python 程序员的专属。我是个写了 8 年 Java 的后端,一直想搞 AI 但被两件事劝退:一是不会 Python,二是搞不懂那些复杂的模型原理。直到我发现了 Spring AI——一个 Spring 官方的 AI 框架。让我用最熟悉的 Spring Boot,1 小时跑通了第一个 AI 接口。但过程中踩了 3 个坑,任何一个都能让新手放弃。这篇文章就把全过程记录下来,从环境搭建到 404 排错,最后跑通一个你好,介绍下自己的 AI 接口。如果你也是 Java 后端想入门 AI,这篇能帮你少走至少半天弯路。一、准备工作1. 申请智谱 API Key打开 open.bigmodel.cn → 注册 → 控制台 → API Keys → 添加新 Key,复制保存。2. 开发环境项版本/要求JDK17 或以上(必须)Spring Boot3.3.xSpring AI1.0.0智谱模型glm-4.7 / glm-4-flashIDEAIntelliJ IDEA(Community 也可)3. 项目结构最终的项目结构长这样:hello-ai/ ├── pom.xml └── src/main/ ├── java/com/fuqiang/helloai/ │ ├── HelloAiApplication.java │ └── HelloAIController.java └── resources/ └── application.yml二、项目搭建2.1 创建 Spring Boot 项目用 Spring Initializr 生成,或者直接手动创建 Maven 项目。关键配置:Spring Boot 3.3.5Java 17依赖先勾 Spring Web 和 Spring Boot DevTools2.2 添加 Spring AI 依赖在pom.xml中加入:propertiesjava.version17/java.versionspring-ai.version1.0.0/spring-ai.version/propertiesdependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependenciesdependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependencydependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency/dependenciesrepositoriesrepositoryidspring-milestones/idurlhttps://repo.spring.io/milestone/url/repository/repositories Spring AI 1.0 还在 milestone 阶段,所以需要加 Spring Milestones 仓库。三、核心代码3.1 启动类SpringBootApplicationpublicclassHelloAiApplication{publicstaticvoidmain(String[]args){SpringApplication.run(HelloAiApplication.class,args);}}3.2 AI 接口 ControllerRestControllerRequestMapping(/ai)publicclassHelloAIController{privatefinalChatClientchatClient;publicHelloAIController(ChatClient.Builderbuilder){this.chatClientbuilder.defaultSystem(你是一个友好的助手,回答简洁清晰。).build();}GetMapping(/hello)publicStringhello(RequestParamStringmessage){returnchatClient.prompt().user(message).call().content();}GetMapping(/ping)publicStringping(){returnpong;}}3.3 配置文件 application.ymlspring:application:name:hello-aiai:openai:api-key:${ZHIPU_API_KEY}base-url:https://open.bigmodel.cn/api/paas/v4chat:completions-path:/chat/completions# 关键配置,见坑 3options:model:glm-4.7temperature:0.7server:port:8080四、踩坑全过程(本文核心)接下来这段是本文最有价值的部分。我把整个过程踩的 3 个坑详细记录下来,每个都让我头大了一阵才搞定。️ 坑 1:API Key 写在 yml 里(安全警告)第一个坑其实是未来坑——我自己没立刻踩到,但写出来给后来者一个警钟。一开始我直接把智谱的 API Key 硬编码在application.yml里:spring:ai:openai:api-key:85ebdd025863405eb710e581bd7b9558.wjGSnutWV1Ar0jup跑是能跑,但这种写法一旦 git commit 推到 GitHub,Key 就公开了。轻则被刷额度,重则被恶意滥用——智谱的 token 是真金白银。正确做法:application.yml里用占位符,真实 key 放环境变量:api-key:${ZHIPU_API_KEY}然后在 IDEA 的 Run → Edit Configurations → Environment Variables 里配置ZHIPU_API_KEY真实key。教训:别因为是练手项目就偷懒。习惯养成了,接客户的单时这就是事故。️ 坑 2:Whitelabel Error Page,404 接口不存在跑通配置后,我满怀期待地访问:http://localhost:8080/ai/hello?message你好结果浏览器甩给我一个白底黑字的 Whitelabel Error Page:This application has no explicit mapping for /error,so you are seeing this as a fallback.typeNot Found, status404path: /ai/hello第一反应:Controller 没扫描到?我开始怀疑包路径、注解、启动类配置……改了一通,没用。冷静下来后,我加了一个纯测试接口/ai/ping,只返回字符串,不调用 AI:GetMapping(/ping)publicStringping(){returnpong;}重启后访问http://localhost:8080/ai/ping,返回pong。这一下定位就清晰了:ping能通 → Controller 注册成功,Spring MVC 没问题hello不通 → 问题在 AI 调用,不在 Controller这就是经典的二分法排查。当问题可能在多个环节时,用一个最小化的测试,把范围切两半。这步省了我至少 30 分钟瞎试。️ 坑 3:HTTP 404 path/v4/v1/chat/completions(本文核心)ping通了之后,我立刻访问hello,这次终于看到了真正的错误:AI服务调用失败:HTTP404-{timestamp:2026-06-26T08:25:21.47100:00,status:404,error:Not Found,path:/v4/v1/chat/completions}看到 path 我就懂了:Spring AI 把请求拼成了/v4/v1/chat/completions,但智谱 v4 API 的正确路径是/v4/chat/completions,多了一个/v1。根因:Spring AI 的 OpenAI 客户端默认会在base-url后拼接/v1/chat/completions(OpenAI 标准路径)。但智谱 v4 API 已经自带/v4版本前缀,不需要再/v1。我的配置: base-url https://open.bigmodel.cn/api/paas/v4 Spring AI 拼接: /v1/chat/completions 实际请求: https://open.bigmodel.cn/api/paas/v4/v1/chat/completions ❌ 正确请求: https://open.bigmodel.cn/api/paas/v4/chat/completions ✅解决:加一行配置覆盖默认的 completions-path:spring:ai:openai:api-key:${ZHIPU_API_KEY}base-url:https://open.bigmodel.cn/api/paas/v4chat:completions-path:/chat/completions# ← 关键这一行options:model:glm-4.7temperature:0.7重启,接口终于跑通。这个坑是 Spring AI 国产大模型对接的经典坑。OpenAI 标准路径是/v1/chat/completions,但智谱、通义、Kimi 等国产模型的路径各有不同,几乎都会踩这个雷。如果你也在试别的国产模型,先查它的 OpenAI 兼容路径,然后用completions-path覆盖默认值。五、最终效果跑通后,我试了几个不同的 prompt,效果都不错:提问回复你好,介绍下自己你好!我是智谱 GLM 训练的大语言模型…用 Java 写一个冒泡排序public void bubbleSort(int[] arr) { … }把这句话翻译成英文:今天天气真好The weather is nice today.最让我意外的是响应速度——glm-4.7 平均 2-3 秒返回,体验已经很接近 ChatGPT 了。六、我学到了什么这一小时踩坑,我学到的远不止怎么调通一个 API。总结下:Spring AI 让 Java 后端转 AI 没有门槛——会写 Spring Boot 就能写 AI 应用AI 应用的 90% 是工程问题——业务逻辑、API 对接、错误处理,后端天天干国产大模型的 OpenAI 兼容性各有差异——completions-path配置是通用解决方案二分法排查是最强调试技巧——加一个 ping 接口比看 100 行堆栈快API Key 安全比功能更重要——别偷懒,养成习惯最大的体会是:写代码不难,难的是出问题时知道往哪儿看。这一小时踩出来的方法论,比单纯跑通 demo 价值大得多。七、下一步 引导关注下一篇我会写:《Spring AI 进阶:1 小时实现上传 PDF → 自动问答》把 RAG(检索增强生成)讲清楚,做一个能上传文档自动问答的小工具,这是企业 AI 落地最主流的形态。写在最后:我是一名 8年 Java 后端,正在转型 AI 应用开发。后面会持续分享 Spring AI、RAG、Agent 等实战内容。如果你也在转型 AI,欢迎关注我,一起进步。有问题评论区聊,我会逐条回复。如果这篇文章帮到了你,点个赞就是对我最大的鼓励❤️
