《Spring AI 实战系列 入门篇》第 1 篇

亦暖筑序
105 阅读6分钟

Spring AI 入门指南：从零开始构建你的第一个 AI 应用

系列说明：本文为《Spring AI 实战系列 入门篇》第 1 篇，聚焦核心概念与快速上手

学习目标：掌握 Spring AI 核心概念（Model、Prompt、Embedding），并创建你的第一个 AI 项目

预计阅读时间：15 分钟

📚《Spring AI 实战系列》完整目录

🔗 学习不迷路！系列持续更新中，点击链接直达各篇 👇

📖 入门篇（已完结 · 建议按顺序学习）

篇目标题核心内容
第 1 篇 ✅核心概念与快速上手Model / Prompt / Embedding + 第一个项目
第 2 篇 ✅Tool Calling：让 AI 调用外部函数@Tool 声明式 + 编程式工具定义
第 3 篇 ✅VectorStore + RAG：构建私有知识库向量数据库集成 + 文档检索
第 4 篇 ✅结构化输出：AI 结果映射为 POJOBeanOutputConverter
第 5 篇 ✅Advisors：自定义 AI 中间件拦截器链 + 对话记忆
第 6 篇 ✅国产模型集成指南通义千问 / 文心一言 / 智谱 GLM

🚀 进阶篇（更新中）

篇目标题核心内容
进 1 ✅智能客服系统多轮对话 + 工具调用 + 人工兜底
进 2 ✅企业知识库 RAG 管线多格式 ETL + 混合检索（RRF）
进 3 🔜AI Agent 自主规划ReAct 模式 + 多工具编排

🗺️ 学习路径建议

Week 1-3  【入门篇】第1篇 → 第2篇 → 第3篇 → 第4篇 → 第5篇 → 第6篇
          └→ 掌握 Spring AI 核心能力

Week 4-6  【进阶篇】智能客服 → 企业RAG →  AI Agent
          └→ 实战企业级 AI 应用

💡 先说痛点

你是不是也遇到过这些问题？

  • ❌ 每个AI模型API都不一样，OpenAI一套、Claude一套、通义千问又一套……
  • ❌ 切换模型要改一堆代码，测试一遍又一遍
  • ❌ 向量数据库选型头大，Milvus、Pinecone、PGVector到底用哪个？
  • ❌ Spring生态这么好，AI开发却要自己造轮子

看完这篇，你将收获：

  • ✅ 15分钟跑通第一个Spring AI项目
  • ✅ 一行配置切换模型：OpenAI ↔ 通义千问 ↔ 智谱GLM
  • ✅ 理解Model、Prompt、Embedding三大核心概念
  • ✅ 掌握20+向量数据库、10+AI提供商的统一用法

一、Spring AI 是什么？

Spring AI 是 Spring 官方推出的 AI 集成框架，简化 AI 应用开发。

核心理念

连接企业数据与 APIs 与 AI 模型

解决什么问题？

开发 AI 应用时，每个模型、每个向量数据库都有不同的 API。Spring AI 提供了统一抽象层：

┌─────────────────────────────────────────────┐
│              你的应用代码                     │
├─────────────────────────────────────────────┤
│        Spring AI 统一 API                    │
│  ChatClient │ Embedding │ VectorStore │ Tools │
├─────────────────────────────────────────────┤
│        具体实现                              │
│ OpenAI │ Anthropic │ 阿里 │ 百度 │ ...      │
└─────────────────────────────────────────────┘

核心优势

  • ✅ 零改动切换模型 —— OpenAI ↔ Claude ↔ 通义千问，改配置即可
  • ✅ Spring 生态完美融合 —— 自动配置、依赖注入、starter 组件
  • ✅ 开箱即用 —— 20+ 向量数据库、10+ AI 提供商

二、核心概念速览

💡 提示：理解这三个概念，是掌握 Spring AI 的基础。

2.1 AI Model：AI 的大脑

定义：AI 模型是经过训练的算法，能根据输入生成输出。

类比：厨师 需要学习菜谱才能做菜，AI 模型 需要训练才能变得智能。

支持的模型类型
类型输入 → 输出场景
Chat文本 → 文本对话、问答
Embedding文本 → 向量语义搜索、RAG
Image文本 → 图片AI 绘画
Audio音频 → 文本语音转写
支持的 AI 提供商

🌍 国外主流：

提供商代表模型特点
OpenAIGPT-4, GPT-3.5行业标杆
AnthropicClaude 3安全性强
GoogleGemini, PaLM谷歌生态
MetaLlama 3开源免费
MistralMistral, Mixtral欧洲最强

🇨🇳 国内热门：

提供商代表模型特点
阿里云通义千问 (Qwen)、Qwen2中文强、开源可本地部署
百度文心一言 (ERNIE Bot)中文理解强、企业友好
智谱 AIGLM-4 (ChatGLM)国产开源、性能优秀
腾讯混元 (Hunyuan)腾讯生态集成
字节跳动豆包 (Doubao)性价比高
月之暗面Kimi (Moonshot)长上下文支持

📱 本地运行：

工具说明
Ollama主流本地 LLM 运行工具
vLLM高性能推理引擎
Spring AI 配置示例

OpenAI (GPT-4)：

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4

通义千问 (阿里云)：

spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}
spring.ai.dashscope.chat.options.model=qwen-turbo

智谱 GLM：

spring.ai.zhipu.api-key=${ZHIPU_API_KEY}
spring.ai.zhipu.chat.options.model=glm-4

Ollama (本地)：

spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=llama3
模型关键参数
public class ChatOptions {
    String model;              // 模型名称
    Float temperature;         // 随机性：0.0-2.0
    Integer maxTokens;         // 最大输出长度
}
参数作用推荐值
temperature控制创意性：低=确定，高=创意0.7（通用）/ 0.2（精确）/ 1.5+（创意）
maxTokens限制输出长度按需设置

2.2 Prompt：与 AI 沟通的语言

Prompt = 你对 AI 说的话，但它是种沟通协议，不是普通文字。

对比传统编程 vs AI 编程
传统编程：指令 → 计算机执行
AI 编程：Prompt → AI 理解 → 生成回应
Prompt 的结构
Prompt prompt = new Prompt(
    List.of(
        new SystemMessage("你是一个专业律师"),  // 角色设定
        new UserMessage("什么是合同？")          // 用户问题
    ),
    ChatOptions.builder()
        .temperature(0.7)
        .build()
);

消息类型：

角色作用示例
SYSTEM定义 AI 身份"你是一个友好的客服"
USER用户输入"我想退货"
ASSISTANTAI 回复"请问订单号是？"
TOOL工具结果"当前温度：25°C"
Prompt Template（模板）

使用 {变量} 定义模板，运行时替换：

// Spring AI 中使用
chatClient.prompt()
    .user(u -> u
        .text("写一首关于 {theme} 的诗")
        .param("theme", "春天"))
    .call()
    .content();
Prompt Engineering（提示工程）

研究表明，好的 Prompt 能大幅提升效果：

❌ 低效："写一首诗"
✅ 高效："请用七言绝句，写一首关于春天的诗，押韵工整"

🔑 技巧："Take a deep breath and work on this step by step."

2.3 Embedding：让机器读懂语义

Embedding = 将文本转为数字向量

"猫"     → [0.23, -0.45, 0.89, ...]   (1536维)
"狗"     → [0.25, -0.42, 0.85, ...]   (相似！)
"汽车"   → [-0.78, 0.34, -0.12, ...]  (不同)

核心洞察：语义相似的文本 → 向量距离近

搜索对比
方式原理效果
关键词搜索匹配"苹果"手机/水果混淆
Embedding 搜索语义理解"水果"能找到"苹果"
在 RAG 中的应用
用户问题 → Embedding → 向量数据库检索 → 构建提示词 → AI 生成回答

// Spring AI 中的 Embedding
float[] vector = embeddingModel.embed("Hello world");
int dimensions = embeddingModel.dimensions();  // 如 1536

三、创建第一个 Spring AI 项目

3.1 环境要求

要求版本
Java17+
Spring Boot3.4.x 或 3.5.x
Maven3.8+

3.2 快速创建

方式一：start.spring.io
  1. 访问 start.spring.io/
  2. 选择 Maven、Java 21、Spring Boot 3.4+
  3. 添加依赖：Spring Web、Spring AI
  4. 下载并解压
方式二：手动创建

1. 创建目录结构：

demo/
├── pom.xml
└── src/main/
    ├── java/com/example/demo/
    │   └── DemoApplication.java
    └── resources/
        └── application.properties

2. pom.xml：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.0</version>
    </parent>
    
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    
    <!-- Spring AI BOM -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>1.1.3</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- OpenAI 模型 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>
    </dependencies>
</project>

3. application.properties：

# OpenAI（美国）
spring.ai.openai.api-key=${OPENAI_API_KEY}

# 或使用通义千问（国内）
# spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}

spring.ai.openai.chat.options.model=gpt-4o-mini
spring.ai.openai.chat.options.temperature=0.7

4. 启动类：

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

四、实战代码

4.1 AI 控制器

创建 controller/AIController.java：

package com.example.demo.controller;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/ai")
public class AIController {
    
    private final ChatClient chatClient;
    
    public AIController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }
    
    /** 基础对话 */
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
            .user(message)
            .call()
            .content();
    }
    
    /** 带角色设定 */
    @GetMapping("/expert")
    public String expert(@RequestParam String message) {
        return chatClient.prompt()
            .system("你是一位资深 Java 架构师")
            .user(message)
            .call()
            .content();
    }
    
    /** 模板参数 */
    @GetMapping("/poem")
    public String poem(@RequestParam String theme) {
        return chatClient.prompt()
            .user(u -> u
                .text("请用七言绝句，写一首关于 {theme} 的诗")
                .param("theme", theme))
            .call()
            .content();
    }
}

4.2 启动与测试

# 设置 API Key
set OPENAI_API_KEY=sk-your-key-here

# 启动项目
mvn spring-boot:run

测试接口：

curl "http://localhost:8080/ai/chat?message=你好"
curl "http://localhost:8080/ai/poem?theme=春天"

五、常见问题

Q1: 报 "ApiKey is missing"

# 设置环境变量
export OPENAI_API_KEY=sk-xxxxx

Q2: 依赖下载慢

在 pom.xml 添加国内镜像：

<repositories>
    <repository>
        <id>aliyun</id>
        <url>https://maven.aliyun.com/repository/public</url>
    </repository>
</repositories>

Q3: 国内模型推荐

模型获取地址免费额度
通义千问qwen.cloud.alibaba.com/有免费额度
智谱 GLMopen.bigmodel.cn/有免费额度
百度文心console.bce.baidu.com/企业版

六、系列预告

🔥 好消息！ 入门篇全部 6 篇已完结，进阶篇持续更新中 👇

入门篇完结 🎉 —— 恭喜你已完成第 1 篇，接下来推荐学习路径：

第1篇（本文✅）→ 第2篇（Tool Calling）→ 第3篇（RAG）→ 第6篇（国产模型）

七、参考资料

官方文档

  1. Spring AI Official Reference

  2. Spring AI GitHub

  3. Spring Initializr

国内模型文档

  1. 阿里云通义千问 (DashScope)

  2. 智谱 AI (GLM)

  3. 百度文心一言 (ERNIE)

  4. Ollama (本地模型)

学习资源

  1. Spring AI Samples

  2. OpenAI API Documentation

  3. Prompt Engineering Guide

📌 引用说明：本文核心概念与技术描述参考自 Spring AI 官方文档（docs.spring.io/spring-ai/r…

🎯 收藏+关注，持续更新

如果觉得有帮助，请：

  1. ⭐ 收藏本文 —— 方便后续查阅，随时回顾核心概念
  2. 📱 关注公众号「AI日撰」 —— 点击菜单「获取源码」获取完整代码（Gitee 仓库）
  3. 🔗 分享给同事 —— 一起学习 Spring AI，少走弯路

系列更新不迷路，下篇推荐：第 2 篇 · Tool Calling：让 AI 调用外部函数

avatar
文章
阅读
粉丝