Spring AI 实战教程：用 Spring Boot 的方式开发 AI 应用#

1
用户提问 → 向量数据库检索相关文档 → 将文档 + 原始问题一起发给 LLM → 模型生成答案

1
<dependencyManagement>
2
  <dependencies>
3
    <dependency>
4
      <groupId>org.springframework.ai</groupId>
5
      <artifactId>spring-ai-bom</artifactId>
6
      <version>1.0.0</version>
7
      <type>pom</type>
8
      <scope>import</scope>
9
    </dependency>
10
  </dependencies>
11
</dependencyManagement>
12

13
<dependencies>
14
  <!-- Spring Web（已选） -->
15
  <dependency>
16
    <groupId>org.springframework.boot</groupId>
17
    <artifactId>spring-boot-starter-web</artifactId>
18
  </dependency>
19

20
  <!-- OpenAI 支持（可替换为其他提供商） -->
21
  <dependency>
22
    <groupId>org.springframework.ai</groupId>
23
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
24
  </dependency>
25
</dependencies>

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

1
@RestController
2
@RequestMapping("/ai")
3
public class ChatController {
4

5
    private final ChatClient chatClient;
6

7
    // Spring AI 自动配置了 ChatClient.Builder，直接注入即可
8
    public ChatController(ChatClient.Builder builder) {
9
        this.chatClient = builder.build();
10
    }
11

12
    @GetMapping("/chat")
13
    public String chat(@RequestParam String message) {
14
        return chatClient.prompt()
15
                .user(message)          // 用户消息
16
                .call()                 // 发送请求
17
                .content();             // 获取文本响应
18
    }
19
}

1
GET http://localhost:8080/ai/chat?message=你好，请介绍一下Spring框架

1
@GetMapping("/customer-service")
2
public String customerService(@RequestParam String question) {
3
    return chatClient.prompt()
4
            .system("你是一名专业的 Spring 框架技术支持工程师，"
5
                  + "只回答与 Spring 相关的技术问题，"
6
                  + "回答要简洁专业，使用中文。")
7
            .user(question)
8
            .call()
9
            .content();
10
}

1
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
2
public Flux<String> streamChat(@RequestParam String message) {
3
    return chatClient.prompt()
4
            .user(message)
5
            .stream()           // 切换为流式模式
6
            .content();         // 返回 Flux<String>
7
}

1
// 定义数据结构
2
record MovieRecommendation(
3
    String title,
4
    String director,
5
    int year,
6
    String reason
7
) {}
8

9
@GetMapping("/recommend-movie")
10
public List<MovieRecommendation> recommendMovies(@RequestParam String genre) {
11
    return chatClient.prompt()
12
            .user("推荐3部" + genre + "类型的经典电影，说明推荐理由")
13
            .call()
14
            .entity(new ParameterizedTypeReference<List<MovieRecommendation>>() {});
15
}

1
@Service
2
public class CodeReviewService {
3

4
    private final ChatClient chatClient;
5

6
    public CodeReviewService(ChatClient.Builder builder) {
7
        this.chatClient = builder.build();
8
    }
9

10
    public String reviewCode(String language, String code) {
11
        String template = """
12
                请对以下 {language} 代码进行 Code Review：
13

14
                ```{language}
15
                {code}
16
                ```
17

18
                请从以下角度分析：
19
                1. 代码质量与可读性
20
                2. 潜在的 Bug 或安全问题
21
                3. 性能优化建议
22

23
                请用中文回答。
24
                """;
25

26
        return chatClient.prompt()
27
                .user(u -> u.text(template)
28
                            .param("language", language)
29
                            .param("code", code))
30
                .call()
31
                .content();
32
    }
33
}

1
@Configuration
2
public class AiConfig {
3

4
    @Bean
5
    public ChatClient chatClientWithMemory(ChatClient.Builder builder) {
6
        return builder
7
                // 使用内存存储对话历史（生产环境可换成 Redis、数据库）
8
                .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
9
                .build();
10
    }
11
}

1
@RestController
2
@RequestMapping("/ai")
3
public class ConversationController {
4

5
    private final ChatClient chatClient;
6

7
    public ConversationController(ChatClient chatClient) {
8
        this.chatClient = chatClient;
9
    }
10

11
    @GetMapping("/conversation")
12
    public String conversation(
13
            @RequestParam String message,
14
            @RequestParam(defaultValue = "default") String sessionId) {
15
        return chatClient.prompt()
16
                .user(message)
17
                .advisors(a -> a.param(AbstractChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, sessionId))
18
                .call()
19
                .content();
20
    }
21
}

1
# 第一轮
2
GET /ai/conversation?message=我叫李明&sessionId=user123
3
→ "你好，李明！..."
4

5
# 第二轮（模型记得你叫什么）
6
GET /ai/conversation?message=你还记得我的名字吗&sessionId=user123
7
→ "当然，你叫李明！..."

1
@Component
2
public class OrderTools {
3

4
    @Autowired
5
    private OrderRepository orderRepository;
6

7
    @Tool(description = "根据订单ID查询订单状态和详情")
8
    public OrderInfo getOrderById(String orderId) {
9
        return orderRepository.findById(orderId)
10
                .map(order -> new OrderInfo(
11
                    order.getId(),
12
                    order.getStatus(),
13
                    order.getTotalAmount(),
14
                    order.getCreatedAt()))
15
                .orElse(null);
16
    }
17

18
    @Tool(description = "查询指定用户最近N笔订单")
19
    public List<OrderInfo> getRecentOrders(String userId, int limit) {
20
        return orderRepository.findByUserIdOrderByCreatedAtDesc(userId, PageRequest.of(0, limit))
21
                .stream()
22
                .map(o -> new OrderInfo(o.getId(), o.getStatus(), o.getTotalAmount(), o.getCreatedAt()))
23
                .toList();
24
    }
25

26
    record OrderInfo(String orderId, String status, BigDecimal amount, LocalDateTime createdAt) {}
27
}

1
@RestController
2
@RequestMapping("/ai")
3
public class CustomerServiceController {
4

5
    private final ChatClient chatClient;
6
    private final OrderTools orderTools;
7

8
    public CustomerServiceController(ChatClient.Builder builder, OrderTools orderTools) {
9
        this.orderTools = orderTools;
10
        this.chatClient = builder
11
                .defaultSystem("你是一名专业的电商客服，帮助用户查询订单信息。"
12
                             + "如果需要查询订单，请使用提供的工具获取准确数据，不要编造信息。")
13
                .build();
14
    }
15

16
    @GetMapping("/customer-service")
17
    public String handleCustomerQuery(
18
            @RequestParam String message,
19
            @RequestParam String userId) {
20
        return chatClient.prompt()
21
                .user(message)
22
                .tools(orderTools)          // 注册工具
23
                .call()
24
                .content();
25
    }
26
}

1
用户：我的订单 ORD-2025-001 现在什么状态了？
2
AI：查询您的订单 ORD-2025-001... 该订单当前状态为"已发货"，
3
    下单金额 299.00 元，预计明天送达。有其他问题需要帮助吗？

1
用户消息 + 工具定义
2
    ↓
3
LLM 决定调用哪个工具（返回 ToolCall 请求）
4
    ↓
5
Spring AI 自动执行对应 Java 方法
6
    ↓
7
将工具执行结果返回给 LLM
8
    ↓
9
LLM 生成最终回答

1
<!-- 向量存储：PGVector -->
2
<dependency>
3
    <groupId>org.springframework.ai</groupId>
4
    <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
5
</dependency>
6

7
<!-- PDF 文档读取 -->
8
<dependency>
9
    <groupId>org.springframework.ai</groupId>
10
    <artifactId>spring-ai-pdf-document-reader</artifactId>
11
</dependency>

1
<dependency>
2
    <groupId>org.springframework.ai</groupId>
3
    <artifactId>spring-ai-simple-vector-store</artifactId>
4
</dependency>

1
spring:
2
  datasource:
3
    url: jdbc:postgresql://localhost:5432/aidb
4
    username: postgres
5
    password: postgres
6
  ai:
7
    vectorstore:
8
      pgvector:
9
        initialize-schema: true   # 自动建表
10
        dimensions: 1536          # OpenAI text-embedding-ada-002 的维度

1
@Service
2
public class DocumentIngestionService {
3

4
    private final VectorStore vectorStore;
5
    private final TokenTextSplitter textSplitter;
6

7
    public DocumentIngestionService(VectorStore vectorStore) {
8
        this.vectorStore = vectorStore;
9
        this.textSplitter = new TokenTextSplitter();
10
    }
11

12
    /**
13
     * 导入 PDF 文档到向量数据库
14
     */
15
    public void ingestPdfDocument(String filePath) {
16
        // 1. 读取 PDF
17
        var reader = new PagePdfDocumentReader(filePath);
18
        List<Document> documents = reader.get();
19

20
        // 2. 分块（将大文档切成小片段）
21
        List<Document> chunks = textSplitter.apply(documents);
22

23
        // 3. 向量化并存入数据库（Spring AI 自动调用 Embedding API）
24
        vectorStore.add(chunks);
25

26
        System.out.println("成功导入 " + chunks.size() + " 个文档片段");
27
    }
28

29
    /**
30
     * 导入纯文本内容
31
     */
32
    public void ingestText(String content, Map<String, Object> metadata) {
33
        var document = new Document(content, metadata);
34
        List<Document> chunks = textSplitter.apply(List.of(document));
35
        vectorStore.add(chunks);
36
    }
37
}

1
@Configuration
2
public class RagConfig {
3

4
    @Bean
5
    public ChatClient ragChatClient(ChatClient.Builder builder, VectorStore vectorStore) {
6
        return builder
7
                .defaultSystem("""
8
                        你是一个专业的技术文档助手。
9
                        请基于提供的上下文信息回答问题。
10
                        如果上下文中没有相关信息，请直接说"文档中没有找到相关信息"，不要编造答案。
11
                        请用中文回答。
12
                        """)
13
                .defaultAdvisors(
14
                    // 核心：注入 RAG Advisor，自动进行文档检索和上下文注入
15
                    QuestionAnswerAdvisor.builder(vectorStore)
16
                        .searchRequest(SearchRequest.builder()
17
                            .topK(5)               // 检索最相关的5个片段
18
                            .similarityThreshold(0.7) // 相似度阈值
19
                            .build())
20
                        .build()
21
                )
22
                .build();
23
    }
24
}

1
@RestController
2
@RequestMapping("/ai/rag")
3
public class RagController {
4

5
    private final ChatClient ragChatClient;
6

7
    public RagController(ChatClient ragChatClient) {
8
        this.ragChatClient = ragChatClient;
9
    }
10

11
    @GetMapping("/ask")
12
    public String askWithContext(@RequestParam String question) {
13
        return ragChatClient.prompt()
14
                .user(question)
15
                .call()
16
                .content();
17
    }
18
}

1
用户问题："Spring Boot 如何配置数据源？"
2
         ↓
3
  Embedding 模型将问题向量化
4
         ↓
5
  在向量数据库中查找语义最相似的5个文档片段
6
         ↓
7
  将原始问题 + 检索到的文档片段组合成 Prompt：
8
  ┌─────────────────────────────────────┐
9
  │ 上下文：                            │
10
  │ [文档片段1] Spring Boot 数据源配置…  │
11
  │ [文档片段2] spring.datasource.url…  │
12
  │ ...                                 │
13
  │                                     │
14
  │ 用户问题：Spring Boot 如何配置数据源？│
15
  └─────────────────────────────────────┘
16
         ↓
17
  LLM 基于上下文生成精准回答

1
<!-- 删除这个 -->
2
<!-- <dependency>
3
    <groupId>org.springframework.ai</groupId>
4
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
5
</dependency> -->
6

7
<!-- 添加这个 -->
8
<dependency>
9
    <groupId>org.springframework.ai</groupId>
10
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
11
</dependency>

1
spring.ai.ollama.base-url=http://localhost:11434
2
spring.ai.ollama.chat.options.model=deepseek-r1:1.5b
3

4
# 可选：模型不存在时自动拉取
5
spring.ai.ollama.init.pull-model-strategy=when_missing

1
@Service
2
public class RobustChatService {
3

4
    private final ChatClient chatClient;
5

6
    public RobustChatService(ChatClient.Builder builder) {
7
        this.chatClient = builder.build();
8
    }
9

10
    public String chatWithRetry(String message) {
11
        try {
12
            return chatClient.prompt()
13
                    .user(message)
14
                    .call()
15
                    .content();
16
        } catch (RateLimitException e) {
17
            // API 限流，等待后重试
18
            log.warn("AI API 限流，请稍后重试");
19
            throw new ServiceException("服务繁忙，请稍后重试");
20
        } catch (OpenAiApiException e) {
21
            log.error("AI API 调用失败: {}", e.getMessage());
22
            throw new ServiceException("AI 服务暂时不可用");
23
        }
24
    }
25
}

1
// 在 ChatClient.Builder 中设置最大 Token 限制
2
ChatClient chatClient = builder
3
        .defaultOptions(OpenAiChatOptions.builder()
4
            .model("gpt-4o-mini")
5
            .maxTokens(500)       // 限制响应最大 Token 数
6
            .temperature(0.7)     // 温度：0=确定性，1=创造性
7
            .build())
8
        .build();

1
<dependency>
2
    <groupId>org.springframework.boot</groupId>
3
    <artifactId>spring-boot-starter-actuator</artifactId>
4
</dependency>
5
<dependency>
6
    <groupId>io.micrometer</groupId>
7
    <artifactId>micrometer-registry-prometheus</artifactId>
8
</dependency>