SpringAI与LangChain4j的智能应用-(理论篇3)

使用SpringAI的核心机制，核心是掌握其“标准化抽象层+Spring生态融合”的设计逻辑，从「环境搭建→核心接口使用→生态融合→高级特性」逐步落地，以下是可直接实操的步骤指南，覆盖80%的核心使用场景：

一、基础准备：环境搭建与核心依赖

1. 版本适配（关键）

• Spring Boot版本：建议3.2.x及以上（SpringAI 1.0.x系列适配Spring Boot 3.2+）；
• Java版本：17及以上；
• 依赖管理：通过Maven/Gradle引入SpringAI核心依赖，优先使用Starter简化配置。

2. 核心依赖引入（Maven pom.xml）

以接入OpenAI和Ollama（开源本地模型）为例，引入最常用的Starter：

<dependencies>
    <!-- SpringAI核心依赖 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-core</artifactId>
        <version>1.0.0-M1</version> <!-- 最新版本可查Maven中央仓库 -->
    </dependency>
    <!-- OpenAI Starter（自动配置） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        <version>1.0.0-M1</version>
    </dependency>
    <!-- Ollama Starter（本地开源模型） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
        <version>1.0.0-M1</version>
    </dependency>
    <!-- Spring Boot基础依赖（web/actuator等） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId> <!-- 监控AI调用 -->
    </dependency>
</dependencies>

<!-- 仓库配置（SpringAI Milestone版本需添加） -->
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

3. 核心配置（application.yml）

通过配置外部化管理模型参数，体现SpringAI“约定优于配置”的核心机制：

spring:
  # AI核心配置
  ai:
    # OpenAI配置
    openai:
      api-key: ${OPENAI_API_KEY} # 环境变量注入，避免硬编码
      chat:
        model: gpt-4o # 模型名称
        temperature: 0.3 # 随机性
        max-tokens: 2000 # 最大生成token
    # Ollama配置（本地部署的Llama3/Phi3等）
    ollama:
      base-url: http://localhost:11434 # Ollama服务地址
      chat:
        model: llama3 # 本地模型名称
        temperature: 0.5
  # 监控配置（暴露AI调用指标）
  boot:
    actuator:
      endpoints:
        web:
          exposure:
            include: ai,metrics,health # 暴露AI相关监控端点

# 日志配置（便于调试AI调用）
logging:
  level:
    org.springframework.ai: DEBUG # 打印AI调用的请求/响应日志

二、核心机制1：使用标准化抽象层（统一AI调用）

SpringAI最核心的机制是通过标准化接口屏蔽不同模型的差异，以下是核心接口的使用示例：

1. 基础：ChatClient（聊天/对话型AI）

ChatClient是SpringAI最常用的接口，适配所有对话型模型（OpenAI/GPT-4o、Ollama/Llama3、百度文心等），使用方式完全统一。

（1）简单调用（注入即使用）

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/ai/chat")
public class ChatController {
    // 注入SpringAI自动配置的ChatClient（默认使用OpenAI，可通过配置切换）
    @Autowired
    private ChatClient chatClient;

    // 基础对话接口
    @GetMapping("/simple")
    public String simpleChat(@RequestParam String message) {
        // 方式1：极简调用（适合快速测试）
        // return chatClient.call(message);

        // 方式2：标准化Prompt调用（推荐，支持上下文、参数定制）
        Prompt prompt = Prompt.of(message);
        ChatResponse response = chatClient.call(prompt);
        // 提取响应内容
        return response.getResult().getOutput().getContent();
    }
}

（2）多模型切换（通过@Qualifier指定）

若同时配置了OpenAI和Ollama，可通过@Qualifier指定使用的模型：

@RestController
@RequestMapping("/ai/chat")
public class MultiModelChatController {
    // 注入OpenAI的ChatClient
    @Autowired
    @Qualifier("openAiChatClient")
    private ChatClient openAiChatClient;

    // 注入Ollama的ChatClient
    @Autowired
    @Qualifier("ollamaChatClient")
    private ChatClient ollamaChatClient;

    // 使用OpenAI
    @GetMapping("/openai")
    public String chatWithOpenAI(@RequestParam String message) {
        return openAiChatClient.call(message);
    }

    // 使用Ollama（本地模型）
    @GetMapping("/ollama")
    public String chatWithOllama(@RequestParam String message) {
        return ollamaChatClient.call(message);
    }
}

（3）带上下文的对话（多轮交互）

SpringAI支持通过Prompt的SystemMessage和UserMessage构建上下文：

@GetMapping("/context")
public String contextChat(@RequestParam String question) {
    // 构建多轮上下文
    Prompt prompt = Prompt.builder()
            // 系统提示（定义AI角色）
            .add("system", "你是一个电商客服，仅回答订单相关问题，其他问题请拒绝")
            // 历史对话（模拟）
            .add("user", "我的订单号是10086，什么时候发货？")
            .add("assistant", "订单10086正在备货，预计24小时内发货")
            // 最新问题
            .add("user", question)
            .build();
    return chatClient.call(prompt);
}

2. 进阶：Prompt模板化（复用Prompt）

SpringAI的Prompt模板机制解决硬编码问题，支持动态参数填充（基于Mustache语法）：

（1）定义Prompt模板（Bean方式）

import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PromptConfig {
    // 定义订单分析的Prompt模板
    @Bean
    public PromptTemplate orderAnalysisPromptTemplate() {
        String template = """
                分析用户{{userId}}的订单数据：{{orderList}}
                要求：
                1. 输出消费偏好（仅列商品类别）；
                2. 输出最近30天消费金额；
                3. 语言简洁，不超过100字。
                """;
        return PromptTemplate.of(template);
    }
}

（2）使用模板调用AI

@RestController
@RequestMapping("/ai/order")
public class OrderAnalysisController {
    @Autowired
    private ChatClient chatClient;
    @Autowired
    private PromptTemplate orderAnalysisPromptTemplate;

    @GetMapping("/analyze")
    public String analyzeOrder(
            @RequestParam String userId,
            @RequestParam String orderList) {
        // 填充模板参数
        Prompt prompt = orderAnalysisPromptTemplate.create(Map.of(
                "userId", userId,
                "orderList", orderList
        ));
        return chatClient.call(prompt);
    }
}

3. 高级：流式响应（实时交互）

SpringAI支持流式响应（如ChatGPT的逐字输出），适配Spring WebFlux：

import org.springframework.ai.chat.streaming.ChatStreamingClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("/ai/stream")
public class StreamChatController {
    // 注入流式ChatClient（自动适配OpenAI/Ollama的流式接口）
    @Autowired
    private ChatStreamingClient chatStreamingClient;

    // 流式对话接口（返回Flux<String>，前端可实时接收）
    @GetMapping("/chat")
    public Flux<String> streamChat(@RequestParam String message) {
        return chatStreamingClient.stream(message)
                .map(response -> response.getOutput().getContent());
    }
}

三、核心机制2：融合Spring生态（企业级特性）

SpringAI的核心价值在于将AI能力融入Spring的企业级生态，以下是关键场景的使用示例：

1. 事务管理：AI调用纳入Spring事务

确保AI调用与数据库操作的原子性（如金融风控、订单分析）：

import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class RiskAssessmentService {
    @Autowired
    private ChatClient chatClient;
    @Autowired
    private RiskResultRepository riskRepo; // Spring Data JPA Repository

    // AI评分+入库，纳入Spring事务
    @Transactional(rollbackFor = Exception.class)
    public String assessRisk(String userId) {
        // Step1：AI生成风险评分（SpringAI调用）
        String scorePrompt = "评估用户" + userId + "的贷款风险，仅输出0-100的数字评分";
        String riskScore = chatClient.call(scorePrompt);

        // Step2：评分入库（Spring Data JPA）
        RiskResult result = new RiskResult(userId, Integer.parseInt(riskScore));
        riskRepo.save(result);

        // 若入库失败，整个事务回滚（包括AI调用的日志记录等）
        return riskScore;
    }
}

2. 权限管控：Spring Security集成

通过Spring Security管控AI接口的调用权限：

import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/ai/medical")
public class MedicalAIController {
    @Autowired
    private ChatClient medicalChatClient;

    // 仅ROLE_DOCTOR角色可调用影像分析接口
    @PostMapping("/analyze-image")
    @PreAuthorize("hasRole('DOCTOR')")
    public String analyzeMedicalImage(@RequestParam String imageInfo) {
        String prompt = "分析医疗影像信息：" + imageInfo + "，输出诊断建议（仅供参考）";
        return medicalChatClient.call(prompt);
    }
}

3. 配置外部化：动态调整AI参数

通过Spring Boot的配置体系，动态调整模型参数（支持环境变量、配置中心）：

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/ai/config")
public class ConfigurableChatController {
    @Autowired
    private ChatClient chatClient;

    // 从配置文件/环境变量读取温度参数
    @Value("${spring.ai.openai.chat.temperature:0.5}")
    private float temperature;

    @GetMapping("/custom")
    public String customChat(@RequestParam String message) {
        Prompt prompt = Prompt.builder()
                .content(message)
                .temperature(temperature) // 动态参数
                .build();
        return chatClient.call(prompt);
    }
}

四、核心机制3：向量嵌入与向量数据库（EmbeddingModel）

SpringAI的EmbeddingModel接口统一文本嵌入能力，可无缝集成向量数据库（如Milvus、PgVector），适用于RAG（检索增强生成）场景：

1. 文本嵌入生成

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.embedding.EmbeddingResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/ai/embedding")
public class EmbeddingController {
    @Autowired
    private EmbeddingModel embeddingModel; // 自动配置的OpenAI Embedding模型

    @GetMapping("/generate")
    public String generateEmbedding(@RequestParam String text) {
        // 生成文本嵌入向量
        EmbeddingResponse response = embeddingModel.embed(text);
        // 提取向量（返回维度：OpenAI text-embedding-3-small为1536维）
        return response.getEmbeddings().get(0).getEmbedding().toString();
    }
}

2. 向量数据库集成（以PgVector为例）

import org.springframework.ai.vectorstore.PgVectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class RAGService {
    @Autowired
    private PgVectorStore vectorStore; // 自动配置的PgVector存储

    // 检索相似文本（RAG前置步骤）
    public String searchSimilar(String query) {
        // 检索Top3相似文本
        var results = vectorStore.similaritySearch(SearchRequest.query(query).topK(3));
        // 拼接检索结果
        return results.stream()
                .map(result -> result.getContent())
                .reduce("", (a, b) -> a + "\n" + b);
    }
}

五、核心机制4：监控与可观测性

SpringAI集成Spring Boot Actuator，可实时监控AI调用的指标（次数、耗时、失败率）：

1. 访问http://localhost:8080/actuator/ai：查看AI模型的配置信息；
2. 访问http://localhost:8080/actuator/metrics/spring.ai.chat.client.calls：查看ChatClient的调用次数；
3. 访问http://localhost:8080/actuator/metrics/spring.ai.chat.client.duration：查看ChatClient的调用耗时。

六、核心使用原则与最佳实践

1. 优先使用Starter：通过Starter引入依赖，利用自动配置减少手动编码；
2. 依赖注入而非手动创建：所有AI组件（ChatClient、EmbeddingModel）均为Spring Bean，通过@Autowired注入；
3. 模板化Prompt：避免硬编码Prompt，通过PromptTemplate提高复用性；
4. 配置外部化：敏感参数（API Key）通过环境变量注入，模型参数（temperature）通过配置文件管理；
5. 生态融合优先：AI调用尽量结合Spring事务、安全、监控等特性，而非单独使用；
6. 多模型适配：通过@Qualifier或条件配置实现多模型切换，降低技术绑定风险。

总结

使用SpringAI的核心机制，本质是**“用Spring的方式使用AI”**：

• 基础层：通过ChatClient/EmbeddingModel等标准化接口统一AI调用，屏蔽模型差异；
• 生态层：将AI调用融入Spring事务、安全、配置、监控等企业级特性；
• 进阶层：结合Prompt模板、流式响应、向量数据库实现复杂场景。

遵循“配置先行→接口注入→生态融合”的步骤，可快速将AI能力集成到Spring应用中，同时保证企业级应用的稳定性和可维护性。

在Spring Boot项目中使用SpringAI的核心机制，核心是依托Spring Boot的自动配置、依赖注入特性，结合SpringAI的标准化AI接口和生态融合能力，实现低侵入、企业级的AI能力集成。以下是从「环境搭建→核心接口使用→生态融合→高级场景」的完整实操指南，覆盖90%的主流使用场景：

一、前置准备：环境与依赖配置

1. 版本适配（关键）

组件	推荐版本
Spring Boot	3.2.x 及以上
Java	17 及以上
SpringAI	1.0.0-M1 及以上（Milestone版本）

2. Maven依赖配置（pom.xml）

引入SpringAI核心Starter和Spring Boot基础依赖，以接入OpenAI（商用模型）和Ollama（本地开源模型）为例：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springai-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springai-demo</name>

    <dependencies>
        <!-- SpringAI核心依赖 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-core</artifactId>
            <version>1.0.0-M1</version>
        </dependency>
        <!-- OpenAI自动配置Starter -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
            <version>1.0.0-M1</version>
        </dependency>
        <!-- Ollama（本地模型）自动配置Starter -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
            <version>1.0.0-M1</version>
        </dependency>

        <!-- Spring Boot基础依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId> <!-- 权限管控 -->
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId> <!-- 数据库操作 -->
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId> <!-- 监控AI调用 -->
        </dependency>

        <!-- 测试依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- SpringAI Milestone仓库配置（必加） -->
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>
</project>

3. 核心配置（application.yml）

通过Spring Boot配置体系管理AI模型参数，体现“配置外部化”核心机制：

spring:
  # 1. AI模型配置（核心）
  ai:
    # OpenAI配置
    openai:
      api-key: ${OPENAI_API_KEY} # 环境变量注入，避免硬编码
      chat:
        model: gpt-4o
        temperature: 0.3 # 随机性，0-1
        max-tokens: 2000 # 最大生成token数
    # Ollama配置（本地部署Llama3/Phi3等模型）
    ollama:
      base-url: http://localhost:11434 # Ollama服务地址（本地启动Ollama后默认）
      chat:
        model: llama3
        temperature: 0.5

  # 2. 数据库配置（示例：结合事务使用）
  datasource:
    url: jdbc:mysql://localhost:3306/springai_demo?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC
    username: root
    password: root123
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true

  # 3. Spring Security配置（权限管控）
  security:
    user:
      name: admin
      password: admin123
      roles: ADMIN

  # 4. Actuator监控配置（暴露AI指标）
  boot:
    actuator:
      endpoints:
        web:
          exposure:
            include: ai,metrics,health,info # 暴露AI相关监控端点

# 日志配置（调试AI调用）
logging:
  level:
    org.springframework.ai: DEBUG # 打印AI请求/响应日志
    org.springframework.transaction: DEBUG # 事务日志

二、核心机制1：标准化AI接口使用（ChatClient/EmbeddingModel）

SpringAI的核心是通过标准化接口屏蔽不同AI模型的差异，以下是最常用的ChatClient（对话AI）和EmbeddingModel（文本嵌入）的使用示例。

1. 基础：ChatClient（对话/文本生成）

ChatClient是SpringAI最核心的接口，适配所有对话型模型，Spring Boot会自动配置Bean，直接注入即可使用。

（1）极简调用（快速接入）

package com.example.springai.demo.controller;

import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 基础对话接口示例
 */
@RestController
@RequestMapping("/ai/chat")
public class BasicChatController {

    // 注入SpringAI自动配置的ChatClient（默认使用OpenAI，可通过配置切换）
    @Autowired
    private ChatClient chatClient;

    /**
     * 简单对话接口
     * 访问示例：http://localhost:8080/ai/chat/simple?message=介绍SpringAI
     */
    @GetMapping("/simple")
    public String simpleChat(@RequestParam String message) {
        // 极简调用：一行代码完成AI请求
        return chatClient.call(message);
    }
}

（2）多模型切换（@Qualifier指定）

若同时配置了OpenAI和Ollama，通过@Qualifier指定具体模型：

@RestController
@RequestMapping("/ai/chat")
public class MultiModelChatController {

    // 注入OpenAI的ChatClient
    @Autowired
    @Qualifier("openAiChatClient")
    private ChatClient openAiChatClient;

    // 注入Ollama的ChatClient
    @Autowired
    @Qualifier("ollamaChatClient")
    private ChatClient ollamaChatClient;

    /**
     * 使用OpenAI对话
     */
    @GetMapping("/openai")
    public String chatWithOpenAI(@RequestParam String message) {
        return openAiChatClient.call(message);
    }

    /**
     * 使用本地Ollama模型对话
     */
    @GetMapping("/ollama")
    public String chatWithOllama(@RequestParam String message) {
        return ollamaChatClient.call(message);
    }
}

（3）Prompt模板化（复用+动态参数）

解决Prompt硬编码问题，支持Mustache语法动态填充参数：

package com.example.springai.demo.controller;

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

/**
 * Prompt模板化示例（订单分析场景）
 */
@RestController
@RequestMapping("/ai/order")
public class OrderAnalysisController {

    @Autowired
    private ChatClient chatClient;

    // 定义Prompt模板（也可配置在yml中）
    private final PromptTemplate orderTemplate = PromptTemplate.of("""
            分析用户{{userId}}的订单数据：{{orderList}}
            要求：
            1. 输出消费偏好（仅列商品类别）；
            2. 输出最近30天消费金额；
            3. 语言简洁，不超过100字。
            """);

    /**
     * 订单分析接口
     * 访问示例：http://localhost:8080/ai/order/analyze?userId=1001&orderList=[{"商品":"手机","金额":5000},{"商品":"耳机","金额":500}]
     */
    @GetMapping("/analyze")
    public String analyzeOrder(@RequestParam String userId, @RequestParam String orderList) {
        // 填充模板参数
        Prompt prompt = orderTemplate.create(Map.of(
                "userId", userId,
                "orderList", orderList
        ));
        // 调用AI并返回结果
        return chatClient.call(prompt);
    }
}

（4）流式响应（实时交互）

适配Spring WebFlux，实现AI响应逐字输出（如ChatGPT的实时打字效果）：

package com.example.springai.demo.controller;

import org.springframework.ai.chat.streaming.ChatStreamingClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

/**
 * 流式响应示例
 */
@RestController
@RequestMapping("/ai/stream")
public class StreamChatController {

    // 注入流式ChatClient
    @Autowired
    private ChatStreamingClient chatStreamingClient;

    /**
     * 流式对话接口（前端可实时接收）
     */
    @GetMapping("/chat")
    public Flux<String> streamChat(@RequestParam String message) {
        // 流式调用，返回Flux<String>
        return chatStreamingClient.stream(message)
                .map(response -> response.getOutput().getContent());
    }
}

2. 进阶：EmbeddingModel（文本嵌入，RAG场景）

EmbeddingModel统一文本嵌入能力，用于生成向量数据，适配向量数据库（如PgVector、Milvus）：

package com.example.springai.demo.controller;

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.embedding.EmbeddingResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 文本嵌入（向量生成）示例
 */
@RestController
@RequestMapping("/ai/embedding")
public class EmbeddingController {

    @Autowired
    private EmbeddingModel embeddingModel; // 自动配置的OpenAI Embedding模型

    /**
     * 生成文本嵌入向量
     * 访问示例：http://localhost:8080/ai/embedding/generate?text=SpringAI是Spring生态的AI框架
     */
    @GetMapping("/generate")
    public String generateEmbedding(@RequestParam String text) {
        // 生成嵌入向量
        EmbeddingResponse response = embeddingModel.embed(text);
        // 提取向量（OpenAI text-embedding-3-small为1536维）
        return response.getEmbeddings().get(0).getEmbedding().toString();
    }
}

三、核心机制2：融合Spring Boot生态（事务/安全/监控）

SpringAI的核心价值是将AI能力融入Spring Boot的企业级特性，以下是事务、安全、监控的集成示例。

1. 事务管理：AI调用+数据库操作原子性

确保AI生成结果与数据库操作要么都成功，要么都回滚（如金融风控场景）：

package com.example.springai.demo.service;

import com.example.springai.demo.entity.RiskResult;
import com.example.springai.demo.repository.RiskResultRepository;
import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

/**
 * 风险评估服务（AI调用+事务管理）
 */
@Service
public class RiskAssessmentService {

    @Autowired
    private ChatClient chatClient;

    @Autowired
    private RiskResultRepository riskResultRepository; // Spring Data JPA Repository

    /**
     * 风险评估（AI评分+入库，事务管控）
     */
    @Transactional(rollbackFor = Exception.class)
    public String assessRisk(String userId) {
        // Step1：AI生成风险评分
        String prompt = "评估用户" + userId + "的贷款风险，仅输出0-100的数字评分";
        String riskScore = chatClient.call(prompt);

        // Step2：评分入库（若入库失败，整个事务回滚）
        RiskResult result = new RiskResult();
        result.setUserId(userId);
        result.setRiskScore(Integer.parseInt(riskScore));
        riskResultRepository.save(result);

        return riskScore;
    }
}

配套实体和Repository：

// 风险评估结果实体
package com.example.springai.demo.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import lombok.Data;

@Entity
@Data
public class RiskResult {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String userId;
    private Integer riskScore;
}

// Repository
package com.example.springai.demo.repository;

import com.example.springai.demo.entity.RiskResult;
import org.springframework.data.jpa.repository.JpaRepository;

public interface RiskResultRepository extends JpaRepository<RiskResult, Long> {
}

控制器（暴露接口）：

@RestController
@RequestMapping("/ai/risk")
public class RiskAssessmentController {

    @Autowired
    private RiskAssessmentService riskAssessmentService;

    @GetMapping("/assess")
    public String assess(@RequestParam String userId) {
        return riskAssessmentService.assessRisk(userId);
    }
}

2. 权限管控：Spring Security集成

通过@PreAuthorize管控AI接口的调用权限（如仅管理员可调用风险评估）：

@RestController
@RequestMapping("/ai/risk")
public class RiskAssessmentController {

    @Autowired
    private RiskAssessmentService riskAssessmentService;

    /**
     * 仅ADMIN角色可调用
     */
    @GetMapping("/assess")
    @PreAuthorize("hasRole('ADMIN')")
    public String assess(@RequestParam String userId) {
        return riskAssessmentService.assessRisk(userId);
    }
}

3. 监控与可观测性：Actuator集成

SpringAI内置了AI调用的监控指标，通过Actuator可直接访问：

• 查看AI模型配置：http://localhost:8080/actuator/ai
• 查看ChatClient调用次数：http://localhost:8080/actuator/metrics/spring.ai.chat.client.calls
• 查看ChatClient调用耗时：http://localhost:8080/actuator/metrics/spring.ai.chat.client.duration
• 查看健康状态：http://localhost:8080/actuator/health

四、核心机制3：自定义配置与扩展

若默认自动配置无法满足需求，可自定义SpringAI的Bean（如自定义ChatClient参数）：

package com.example.springai.demo.config;

import org.springframework.ai.openai.OpenAiChatClient;
import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.ai.openai.api.OpenAiApi;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 自定义SpringAI配置
 */
@Configuration
public class SpringAiConfig {

    @Value("${spring.ai.openai.api-key}")
    private String openAiApiKey;

    /**
     * 自定义OpenAI ChatClient（覆盖自动配置）
     */
    @Bean
    public OpenAiChatClient customOpenAiChatClient() {
        // 自定义API客户端
        OpenAiApi openAiApi = new OpenAiApi(openAiApiKey);
        // 自定义配置（如更高的temperature）
        OpenAiChatOptions options = OpenAiChatOptions.builder()
                .model("gpt-4o")
                .temperature(0.8)
                .maxTokens(3000)
                .build();
        // 创建自定义ChatClient
        return new OpenAiChatClient(openAiApi, options);
    }
}

五、启动与测试

1. 启动Ollama（本地模型，可选）

若使用Ollama，先本地启动Ollama服务，并拉取模型：

# 启动Ollama（需先安装Ollama）
ollama serve

# 拉取Llama3模型
ollama pull llama3

2. 启动Spring Boot项目

• 配置环境变量OPENAI_API_KEY（你的OpenAI API Key）；
• 启动项目（Main类）：

package com.example.springai.demo;

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

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

3. 测试接口

• 简单对话：http://localhost:8080/ai/chat/simple?message=介绍SpringAI
• 多模型切换：http://localhost:8080/ai/chat/ollama?message=介绍LangChain4j
• 订单分析：http://localhost:8080/ai/order/analyze?userId=1001&orderList=[{"商品":"手机","金额":5000},{"商品":"耳机","金额":500}]
• 风险评估（需ADMIN权限，访问时输入账号密码admin/admin123）：http://localhost:8080/ai/risk/assess?userId=1001

六、最佳实践总结

1. 依赖优先用Starter：利用Spring Boot自动配置，减少手动编码；
2. 配置外部化：敏感参数（API Key）用环境变量，模型参数用application.yml；
3. 接口注入使用：所有AI组件（ChatClient/EmbeddingModel）通过@Autowired注入，不手动new；
4. 生态融合优先：AI调用结合Spring事务、安全、监控，而非单独使用；
5. Prompt模板化：避免硬编码，提高复用性和可维护性；
6. 多模型适配：通过@Qualifier或自定义Bean实现模型切换，降低技术绑定。

通过以上步骤，你可以在Spring Boot项目中完整使用SpringAI的核心机制，既享受标准化AI调用的便捷，又复用Spring生态的企业级特性，实现AI能力的低侵入、高可靠集成。