Spring AI 保姆级部署教程：给 Java / Spring Boot 应用接入 AI 智能体

Spring AI（仓库 spring-projects/spring-ai，最近提交 2026-10-29）是 Spring 官方出品的 AI 应用框架，把 ChatClient、工具调用、RAG、向量库、MCP 全部做成 Spring Boot Starter。Java 后端团队不用再羡慕 Python 生态——加一个依赖、配一个 Key，就能在 Spring Boot 里调 OpenAI、Anthropic、Ollama、DeepSeek、Bedrock，还能让模型主动调用你的 Java 函数。

本文严格对照官方 README 给出版本兼容、start.spring.io 选依赖、Maven 构建与运行方式。

一、项目介绍与适用场景

Spring AI 的目标：把 Spring 生态的设计原则（可移植、模块化、强类型）搬到 AI 领域，核心是"把企业数据与 API 接到大模型上"。

适用场景：

• Java/Spring 团队：在现有 Spring Boot 微服务里加 AI 聊天、知识库问答；
• 企业内网：用 Ollama 跑本地模型，Spring AI 统一抽象，未来换模型不改业务代码；
• 工具调用 Agent：让大模型直接调用你写好的 Java @Tool 函数。

二、核心功能逐条拆解

1. 多模型支持：Anthropic、OpenAI、Bedrock、Google、Ollama、Mistral、DeepSeek 等；
2. ChatClient API：流式 API，类似 WebClient/RestClient 的 fluent 风格；
3. 结构化输出：把模型返回直接映射成 POJO；
4. 工具调用（Tool Calling）：模型请求执行你客户端的 Java 函数；
5. RAG advisors：内置问答/摘要/自定义 advisor，可插拔；
6. 向量库抽象：Chroma、PGVector、Milvus、Redis、Weaviate、Neo4j 等二十多种；
7. MCP 一等支持：通过 Boot Starter 与注解，既能当 MCP client 也能把 Spring 服务暴露成 MCP server；
8. 聊天记忆：可插拔 JDBC / Cassandra / MongoDB / Neo4j / Redis 持久化；
9. 可观测性：对接 Micrometer/Tracing；
10. ETL 文档处理：文档注入管道，解析 PDF/Markdown/HTML。

三、全套官方链接

四、硬件与环境前置要求

官方 README 明确版本兼容：

• Spring AI 2.x.x（main 分支）→ Spring Boot 4.x；
• Spring AI 1.1.x（1.1.x 分支）→ Spring Boot 3.5.x。

其他：

• JDK 17+（Spring Boot 3.x 要求）；
• Maven 3.6+ 或 Gradle；
• 一个模型 Key（OpenAI 等）或本地 Ollama；
• 内存 2 GB 起步。

五、多平台部署步骤

5.1 用 start.spring.io 生成工程（官方推荐）

官方 README 明确："use start.spring.io to select the Model or Vector Store of choice"。

步骤：

1. 浏览器打开 https://start.spring.io/ ；
2. 选 Spring Boot 版本（与 Spring AI 版本对应：Boot 4.x 配 Spring AI 2.x，Boot 3.5.x 配 Spring AI 1.1.x）；
3. 在 Dependencies 搜索 "Spring OpenAI" 或 "Spring Ollama"，勾选对应 Starter；
4. 点 GENERATE 下载 zip；
5. 解压后导入 IDE。

5.2 手动加 Maven 依赖

以 OpenAI 为例（参考官方 Maven Central org.springframework.ai:spring-ai-model）：

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

具体 artifactId 随版本变化，以 https://docs.spring.io/spring-ai/reference/api/chatmodel.html 与 start.spring.io 生成的 pom 为准。

5.3 配置模型 Key

在 src/main/resources/application.yml：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o

5.4 写一个 ChatClient 接口

官方文档标准用法：

@RestController
class ChatController {
    private final ChatClient chatClient;

    ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/chat")
    String chat(String q) {
        return chatClient.prompt().user(q).call().content();
    }
}

5.5 工具调用

在你的 Bean 方法上加 @Tool：

@Component
class MyTools {
    @Tool(description = "获取当前天气")
    String weather(String city) {
        return city + " 晴 25℃";
    }
}

然后在 ChatClient 里 defaultTools(myTools) 注册，模型会主动调用。

5.6 本地 Ollama 模式

把 starter 换成 Ollama，application.yml 改：

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5

5.7 构建与运行

官方 README 给出从源码构建：

./mvnw clean install

普通用户运行自己的工程：

./mvnw spring-boot:run

预期：Spring Boot 启动，默认 http://localhost:8080 ，访问 /chat?q=你好 拿到模型回答。

5.8 Docker 部署

官方 README 未提供独立镜像；Spring Boot 应用自带 BootBuildImage：

./mvnw spring-boot:build-image

生成的镜像可直接 docker run -p 8080:8080 -e OPENAI_API_KEY=... 启动。

六、配置文件全部参数解释

七、启动、后台常驻与开机自启

7.1 前台启动

./mvnw spring-boot:run

7.2 打 Jar 后常驻

./mvnw clean package -DskipTests
java -jar target/demo-0.0.1.jar

systemd：

[Unit]
Description=Spring AI App
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/demo
Environment="OPENAI_API_KEY=sk-..."
ExecStart=/usr/bin/java -jar /home/ubuntu/demo/target/demo-0.0.1.jar
Restart=on-failure

[Install]
WantedBy=multi-user.target

7.3 开机自启

sudo systemctl daemon-reload && sudo systemctl enable --now springai

7.4 修改端口

application.yml 加 server.port: 8081，重启后访问 http://localhost:8081 验证。

八、功能实操教程

第 1 步：去 start.spring.io 选 Spring Boot 3.5.x + Spring OpenAI Starter，下载工程。 第 2 步：写 application.yml 填 OPENAI_API_KEY。 第 3 步：按 5.4 写 ChatController。 第 4 步：./mvnw spring-boot:run，浏览器访问 http://localhost:8080/chat?q=用一句话解释Spring AI。 第 5 步：按 5.5 加 @Tool 方法，再问"北京天气怎么样"，观察模型自动调用 Java 函数。 第 6 步：（可选）按 5.6 切 Ollama，本地跑 qwen 模型。

九、全套报错故障排查

1. 报错：NoSuchMethodError / ClassNotFound。 原因：Spring Boot 与 Spring AI 版本不匹配。 解决：严格按 README 兼容表——Boot 4.x 配 Spring AI 2.x，Boot 3.5.x 配 Spring AI 1.1.x。

2. 报错：401 Incorrect API key。 原因：spring.ai.openai.api-key 没读到。 解决：确认环境变量在 systemd 里也传了；用 @Value 打印一下。

3. 报错：Ollama 连不上。 原因：Ollama 没起或 base-url 错。 解决：curl http://localhost:11434/api/tags 验证；确认 Ollama 允许跨域（OLLAMA_ORIGINS）。

4. 报错：@Tool 方法没被调用。 原因：没在 ChatClient 里注册 tools。 解决：用 .defaultTools(myTools) 或 .tools(myTools) 显式注册。

5. 报错：./mvnw clean install 编译失败。 原因：JDK 版本太低。 解决：java -version 确认 17+。

十、升级、回滚与卸载

• 升级：改 pom 里 Spring AI BOM 版本号，./mvnw clean package。
• 回滚：BOM 版本号改回旧版。
• 卸载：删工程目录即可。

十二、进阶：RAG 知识库、MCP 与可观测性

给 Spring 应用加 RAG：把 PDF / Markdown 文档用 Spring AI 的 ETL Pipeline 切分、embedding，写进 PGVector 或 Redis，然后在 ChatClient 里加 QuestionAnswerAdvisor，自动检索相关片段拼进提示词。整个过程是 Spring Bean 配置，不需要写胶水代码。

聊天记忆持久化：默认记忆在内存里，重启即丢。官方支持 JDBC / Redis / Neo4j 等持久化后端，换个 Bean 配置就能让用户跨天继续聊。

MCP 双向能力：Spring AI 既能当 MCP client 调外部 MCP server（接 Claude Desktop 的工具生态），也能把你已有的 Spring 服务（比如订单查询、库存查询）通过 MCP 暴露给 AI 客户端。用 Boot Starter 加依赖即可，不用手写协议。

可观测性：对接 Micrometer + Observation，每次 LLM 调用的 token 数、延迟、成本都能在 Grafana 里看到，企业上生产必备。

本地模型全栈：开发时用 Ollama 跑 qwen，生产切 OpenAI，业务代码零改动——这就是 Spring AI 抽象的价值。

十一、商用许可与合规风险提示

Spring AI 采用 Apache-2.0（Spring 官方项目），商用友好。

注意：

1. 版本兼容性：Spring AI 还在快速迭代，2.x 与 1.1.x 不互通，生产环境锁定小版本。
2. 模型费用：框架免费，OpenAI/Bedrock 按 token 计费；本地 Ollama 模型权重各有协议。
3. 企业支持：Spring 官方商业支持通过 VMware/Tanzu，OSS 版无 SLA。

参考链接

• 官方 README：https://github.com/spring-projects/spring-ai
• 参考文档：https://docs.spring.io/spring-ai/reference/
• Getting Started：https://docs.spring.io/spring-ai/reference/getting-started.html
• 示例工程：https://github.com/spring-projects/spring-ai-examples