Spring AI 入门教程：核心功能完全指南

Spring AI 是一个专注于 AI 工程的应用框架，本教程将通过核心组件解析→快速上手→进阶配置的三段式框架，帮助初中级开发者掌握 Spring AI 的目录结构、配置文件解析和启动流程。无论你是 AI 开发新手还是希望扩展技能栈的 Java 开发者，都能通过本文快速掌握 Spring AI 的核心使用方法。

1 核心组件解析

🌱 学习目标：理解 Spring AI 项目的目录组织结构，掌握关键文件的作用，识别核心 API 组件及其关系。

1.1 梳理项目目录结构

Spring AI 采用模块化架构设计，主要目录结构如下：

spring-ai/
├── advisors/                 # AI 交互顾问模块
├── auto-configurations/      # 自动配置模块
├── document-readers/         # 文档读取器组件
├── models/                   # AI 模型实现
├── spring-ai-commons/        # 通用工具类
├── spring-ai-core/           # 核心 API
├── spring-ai-docs/           # 项目文档
├── vector-stores/            # 向量存储实现
├── pom.xml                   # 项目构建配置
└── README.md                 # 项目说明文档

1.2 对比关键文件作用

文件路径	作用描述	重要性
pom.xml	Maven 项目构建配置文件，定义依赖关系和构建生命周期	⭐⭐⭐⭐⭐
src/main/java/	主源代码目录，包含核心业务逻辑	⭐⭐⭐⭐⭐
src/test/java/	测试代码目录，包含单元测试和集成测试	⭐⭐⭐⭐
src/main/resources/	资源文件目录，存放配置文件和静态资源	⭐⭐⭐⭐
mvnw/mvnw.cmd	Maven 包装器(Maven Wrapper，用于统一构建环境)	⭐⭐⭐
settings.xml	Maven 构建系统的全局配置	⭐⭐

1.3 解析核心 API 组件

Spring AI 提供了丰富的 API 组件，以下是主要类图展示：

核心组件说明：

• ChatClientRequest/ChatClientResponse：封装 AI 对话的请求和响应数据
• Advisor：AI 交互顾问接口，提供 CallAdvisor 和 StreamAdvisor 两种实现
• Ordered：定义组件执行顺序的接口

💡 实践小贴士：通过 spring-ai-core 模块的源代码可以深入了解这些核心组件的具体实现，建议重点关注 Advisor 接口的不同实现类。

2 快速上手

🌱 学习目标：掌握 Spring AI 项目的克隆与构建方法，理解启动类结构，能够排查常见启动问题。

2.1 克隆并构建项目

首先通过 Git 克隆项目仓库：

git clone https://gitcode.com/GitHub_Trending/spr/spring-ai
cd spring-ai

使用 Maven 包装器构建项目：

# Linux/Mac 系统
./mvnw clean package -DskipTests

# Windows 系统
mvnw.cmd clean package -DskipTests

2.2 创建基础启动类

创建一个简单的 Spring AI 应用启动类：

package com.example.ai;

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

@SpringBootApplication // 核心注解：自动配置Spring上下文
public class AiApplication {
    public static void main(String[] args) {
        // 启动Spring应用上下文
        SpringApplication.run(AiApplication.class, args);
    }
}

2.3 排查常见启动异常

异常类型	可能原因	解决方法
NoClassDefFoundError	依赖未正确引入	检查 pom.xml 依赖配置，确保版本兼容
PortInUseException	端口被占用	修改 server.port 配置或关闭占用端口的进程
BeanCreationException	依赖注入失败	检查 @Autowired 注解的 bean 是否存在
IllegalArgumentException	配置参数错误	检查配置文件中的参数格式和取值范围

💡 实践小贴士：启动时添加 --debug 参数可以查看自动配置报告，帮助定位配置问题：java -jar app.jar --debug

3 进阶配置

🌱 学习目标：掌握 YAML 格式配置文件的使用，理解不同配置格式的优缺点，学会配置 AI 模型和向量存储。

3.1 编写 YAML 配置文件

在 src/main/resources/ 目录下创建 application.yml 文件：

# AI 模型配置
spring:
  ai:
    openai:
      api-key: "your-api-key"  # OpenAI API密钥
      chat:
        model: "gpt-3.5-turbo" # 聊天模型名称
        temperature: 0.7       # 生成文本的随机性(0-1)
      embedding:
        model: "text-embedding-ada-002" # 嵌入模型名称

# 服务器配置
server:
  port: 8080                   # 应用端口号
  servlet:
    context-path: "/ai-app"    # 应用上下文路径

3.2 对比 YAML 与 Properties 格式

特性	YAML 格式	Properties 格式
语法结构	缩进式层级结构，更易读	扁平键值对，层次通过点分隔
数据类型支持	原生支持列表、对象等复杂类型	需要特殊语法表示复杂类型
注释支持	支持 # 单行注释	支持 # 单行注释
配置继承	支持锚点和引用，减少重复	不支持，需重复配置
流行度	Spring Boot 推荐格式	传统格式，兼容性好

3.3 配置向量存储服务

以 PostgreSQL 的 pgvector 扩展为例，配置向量存储：

spring:
  datasource:
    url: "jdbc:postgresql://localhost:5432/ai_db"
    username: "postgres"
    password: "password"
  ai:
    vectorstore:
      pgvector:
        enabled: true
        table-name: "vectors"  # 存储向量的表名
        dimensions: 1536       # 向量维度，需与嵌入模型匹配

3.4 配置 AI 函数调用

Spring AI 支持函数调用功能，以下是基本配置：

spring:
  ai:
    function:
      scan-packages: "com.example.ai.functions"  # 扫描函数的包路径
      timeout: 5000                              # 函数执行超时时间(毫秒)

💡 实践小贴士：配置敏感信息（如 API 密钥）时，建议使用环境变量或配置服务器，避免直接写在配置文件中。可以使用 spring.ai.openai.api-key=${OPENAI_API_KEY} 引用环境变量。

4 核心功能实践

🌱 学习目标：了解 Spring AI 的嵌入模型 API，掌握基本的文本嵌入和向量存储操作。

4.1 使用嵌入模型 API

Spring AI 提供了统一的嵌入模型 API，支持多种 AI 模型：

以下是使用嵌入模型的示例代码：

@Service
public class EmbeddingService {
    
    private final EmbeddingModel embeddingModel;
    
    // 注入嵌入模型
    public EmbeddingService(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }
    
    // 生成文本嵌入向量
    public List<Double> embedText(String text) {
        // 创建嵌入请求
        EmbeddingRequest request = new EmbeddingRequest(List.of(text));
        // 调用嵌入模型
        EmbeddingResponse response = embeddingModel.embed(request);
        // 返回第一个嵌入向量
        return response.getEmbeddings().get(0).getEmbedding();
    }
}

💡 实践小贴士：不同嵌入模型生成的向量维度不同，使用向量存储时需确保维度匹配。例如 OpenAI 的 text-embedding-ada-002 生成 1536 维向量。

通过本文的学习，你已经掌握了 Spring AI 的核心组件、快速启动方法和进阶配置技巧。接下来可以尝试开发简单的 AI 应用，如聊天机器人、文本嵌入服务等，逐步探索 Spring AI 的更多高级特性。