从 404 到通:Spring AI 调智谱 GLM 全过程实录,新人必看的 3 个坑

Java转AI
16 阅读4分钟

2026 年,AI 应用已经不是 Python 程序员的专属。

我是个写了 5 年 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,复制保存。

image.png 2. 开发环境

项版本/要求
JDK17 或以上(必须)
Spring Boot3.3.x
Spring AI1.0.0
智谱模型glm-4.7 / glm-4-flash
IDEAIntelliJ 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.5
  • Java 17
  • 依赖先勾 Spring Web 和 Spring Boot DevTools

2.2 添加 Spring AI 依赖

在 pom.xml 中加入:

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.0.0</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

💡 Spring AI 1.0 还在 milestone 阶段,所以需要加 Spring Milestones 仓库。

image-1.png

三、核心代码

3.1 启动类

@SpringBootApplication
public class HelloAiApplication {
    public static void main(String[] args) {
        SpringApplication.run(HelloAiApplication.class, args);
    }
}

3.2 AI 接口 Controller

@RestController
@RequestMapping("/ai")
public class HelloAIController {

    private final ChatClient chatClient;

    public HelloAIController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultSystem("你是一个友好的助手,回答简洁清晰。")
                .build();
    }

    @GetMapping("/hello")
    public String hello(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }

    @GetMapping("/ping")
    public String ping() {
        return "pong";
    }
}

image-2.png

3.3 配置文件 application.yml

spring:
  application:
    name: hello-ai
  ai:
    openai:
      api-key: ${ZHIPU_API_KEY}
      base-url: https://open.bigmodel.cn/api/paas/v4
      chat:
        completions-path: /chat/completions   # 关键配置,见坑 3
        options:
          model: glm-4.7
          temperature: 0.7

server:
  port: 8080

image-3.png

四、踩坑全过程(本文核心)

接下来这段是本文最有价值的部分。我把整个过程踩的 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:

image-9.png This application has no explicit mapping for /error, so you are seeing this as a fallback. type=Not Found, status=404 path: /ai/hello

第一反应:Controller 没扫描到?

我开始怀疑包路径、注解、启动类配置……改了一通,没用。

冷静下来后,我加了一个纯测试接口 /ai/ping,只返回字符串,不调用 AI:

@GetMapping("/ping")
public String ping() {
    return "pong";
}

重启后访问 http://localhost:8080/ai/ping,返回 pong。

image-5.png

这一下定位就清晰了:

  • ping 能通 → Controller 注册成功,Spring MVC 没问题
  • hello 不通 → 问题在 AI 调用,不在 Controller

这就是经典的二分法排查。当问题可能在多个环节时,用一个最小化的测试,把范围切两半。这步省了我至少 30 分钟瞎试。

🕳️ 坑 3:HTTP 404 path=/v4/v1/chat/completions(本文核心)

ping 通了之后,我立刻访问 hello,这次终于看到了真正的错误:

AI 服务调用失败:HTTP 404 -
{
  "timestamp": "2026-06-26T08:25:21.471+00:00",
  "status": 404,
  "error": "Not Found",
  "path": "/v4/v1/chat/completions"
}

image-6.png

看到 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/v4
      chat:
        completions-path: /chat/completions   # ← 关键这一行
        options:
          model: glm-4.7
          temperature: 0.7

重启,接口终于跑通。

image-7.png

💡 这个坑是 Spring AI + 国产大模型对接的经典坑。OpenAI 标准路径是 /v1/chat/completions,但智谱、通义、Kimi 等国产模型的路径各有不同,几乎都会踩这个雷。如果你也在试别的国产模型,先查它的 OpenAI 兼容路径,然后用 completions-path 覆盖默认值。

五、最终效果

跑通后,我试了几个不同的 prompt,效果都不错:

提问回复
你好,介绍下自己你好!我是智谱 GLM 训练的大语言模型...
用 Java 写一个冒泡排序public void bubbleSort(int[] arr) { ... }
把这句话翻译成英文:今天天气真好The weather is nice today.

image-8.png

image-11.png

image-10.png

最让我意外的是响应速度——glm-4.7 平均 2-3 秒返回,体验已经很接近 ChatGPT 了。

六、我学到了什么

这一小时踩坑,我学到的远不止"怎么调通一个 API"。总结下:

  1. Spring AI 让 Java 后端转 AI 没有门槛——会写 Spring Boot 就能写 AI 应用
  2. AI 应用的 90% 是工程问题——业务逻辑、API 对接、错误处理,后端天天干
  3. 国产大模型的 OpenAI 兼容性各有差异——completions-path 配置是通用解决方案
  4. 二分法排查是最强调试技巧——加一个 ping 接口比看 100 行堆栈快
  5. API Key 安全比功能更重要——别偷懒,养成习惯

最大的体会是:写代码不难,难的是出问题时知道往哪儿看。这一小时踩出来的方法论,比单纯跑通 demo 价值大得多。

七、下一步 + 引导关注

下一篇我会写:

《Spring AI 进阶:1 小时实现"上传 PDF → 自动问答"》

把 RAG(检索增强生成)讲清楚,做一个能上传文档自动问答的小工具,这是企业 AI 落地最主流的形态。

写在最后:

我是一名 8年 Java 后端,正在转型 AI 应用开发。后面会持续分享 Spring AI、RAG、Agent 等实战内容。

如果你也在转型 AI,欢迎关注我,一起进步。有问题评论区聊,我会逐条回复。

如果这篇文章帮到了你,点个赞就是对我最大的鼓励 ❤️

avatar
文章
阅读
粉丝