Spring AI 学习文档

<properties>
    <spring-ai.version>1.1.2</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- BOM：Spring AI 全家桶的版本清单，引它之后再引具体模块就不用写版本号 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- 智谱大模型-->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-zhipuai</artifactId>
</dependency>

<!-- 文档解析（RAG 导入 pdf/docx 用） -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>

spring:
  ai:
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY:}
      chat:
        options:
          model: glm-4.5-air        # 聊天模型
          temperature: 0.7          # 发挥程度 0~1
      embedding:
        options:
          model: embedding-2        # 向量模型（RAG 用）

@Data
@ConfigurationProperties(prefix = "ai")   // 绑定 yml 里 ai.* 前缀
public class AiProperties {
    private String systemPrompt = "你是智慧能源管理系统（EMS）的智能助手..."; // 系统提示词
    private String ragSystemPrompt = "...知识库问答助手...";                // RAG 提示词
    private Integer memoryWindow = 20;   // 记忆窗口：最多记 20 条消息
    private Integer ragTopK = 4;         // RAG 检索最多取 4 个片段
    private String vectorStoreFile = "./data/ai/vector-store.json"; // 向量库落盘位置
}

@SpringBootTest
public class AiTest {

    @Test
    public void testChat(@Autowired ZhiPuAiChatModel chatModel) {
        String content = chatModel.call("你是谁");
        System.out.println(content);
    }

    @Test
    public void testStream(@Autowired ZhiPuAiChatModel chatModel) {
        Flux<String> stream = chatModel.stream("你是谁");
        stream.toIterable().forEach(System.out::print);   // 阻塞逐段输出
    }
}

ZhiPuAiChatOptions options = ZhiPuAiChatOptions.builder()
        .temperature(0.2)      // 这次要严谨
        .build();
ChatResponse res = chatModel.call(new Prompt("请写一句诗描述清晨。", options));
System.out.println(res.getResult().getOutput().getText());

spring:
  ai:
    zhipuai:
      chat:
        options:
          max-tokens: 20
          stop:
            - "\n"        # 只要一行
            - "。"        # 只要一句话
            - "政治"       # 敏感词，出现即停
            - "最后总结一下"  # AI 惯用模板词，截掉让文风更拟人

ZhipuAiChatOptions options = ZhipuAiChatOptions.builder()
                .model("glm-4.5")
                .build();
        ChatResponse res = zhipuAiChatModel.call(new Prompt("请写一句诗描述清晨。", options));
        ZhipuAiAssistantMessage msg = (ZhipuAiAssistantMessage) res.getResult().getOutput();
        String reasoning = msg.getReasoningContent(); // 思考过程（CoT）
        String content   = msg.getText();               // 最终回答

@SpringBootTest
public class ChatClientTest {
    @Test
    public void testChatClient(ChatClient.Builder builder) {
        ChatClient chatClient = builder.build();
        String content = chatClient.prompt()
                .user("Hello")
                .call()
                .content();
        System.out.println(content);
    }
}

@Test
public void testChatOptions(@Autowired ZhiPuAiChatModel chatModel) {
    ChatClient chatClient = ChatClient.builder(chatModel).build();
    String content = chatClient.prompt()
            .user("Hello")
            .call()
            .content();
    System.out.println(content);
}

@Configuration
public class MultiModelConfig {

    // 智谱推理模型，适合复杂分析
    @Bean
    public ChatClient zhipuReason() {
        ZhipuAiApi zhipuAiApi = ZhipuAiApi.builder()
                .apiKey(System.getenv("ZHIPUAI_KEY"))
                .build();
        ZhipuAiChatModel zhipuAiChatModel = ZhipuAiChatModel.builder()
                .zhipuAiApi(zhipuAiApi)
                .defaultOptions(ZhipuAiChatOptions.builder()
                        // glm-4.5 支持思维链
                        .model("glm-4.5")
                        .build())
                .build();
        return ChatClient.builder(zhipuAiChatModel).build();
    }

    // 智谱普通对话模型
    @Bean
    public ChatClient zhipuChat() {
        ZhipuAiApi zhipuAiApi = ZhipuAiApi.builder()
                .apiKey(System.getenv("ZHIPUAI_KEY"))
                .build();
        ZhipuAiChatModel zhipuAiChatModel = ZhipuAiChatModel.builder()
                .zhipuAiApi(zhipuAiApi)
                .defaultOptions(ZhipuAiChatOptions.builder()
                        // glm-4-flash 免费高速，日常对话首选
                        .model("glm-4-flash")
                        .build())
                .build();
        return ChatClient.builder(zhipuAiChatModel).build();
    }
}

@RestController
public class MultiModelsController {

    @Autowired
    private Map<String, ChatClient> chatClientMap;  // key = Bean 名

    @GetMapping("/chat")
    String generation(@RequestParam String message,
                      @RequestParam String model) {
        ChatClient chatClient = chatClientMap.get(model);
        return chatClient.prompt().user(message).call().content();
    }
}

@RestController
public class ChatController {

    private final ChatClient chatClient;

    // 注入 Builder，构建后可多次复用同一个 client
    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    // 普通单轮对话
    @GetMapping("/chat")
    public String chat(@RequestParam("message") String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }

    // SSE 流式输出（逐 token 返回）
    @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestParam("message") String message) {
        return chatClient.prompt()
                .user(message)
                .stream()
                .content()
                .doOnNext(chunk -> System.out.println("chunk===[" + chunk + "]"))
                .concatWithValues("[DONE]");
    }
//使用stream()方法，也可以不指定produces = text/event-stream，这样它就不是SSE流式输出了。后端内部是分片（大模型），HTTP 对外不是分片推送。即Spring Web 会把整个 Flux 收集完毕，把所有 chunk 拼接，HTTP 一次性返回完整字符串给前端。

}

第 1 轮   用户：「我叫张三」      → 模型回答「你好张三」（记忆存下 user + assistant 两条）
第 2 轮   用户：「我叫什么？」    → 请求携带：第1轮user + 第1轮assistant + 第2轮user
                                    模型回答「你叫张三」    （再存下这一轮 assistant）
第 3 轮   用户：「帮我写邮件」    → 请求携带：前面所有历史 + 第3轮user

// 逻辑层：滑动窗口记忆，最多保留最近 10 条消息
 ChatMemory chatMemory = MessageWindowChatMemory.builder()
          .maxMessages(10) 
          .build(); 
// 挂载 Advisor，自动「读历史 → 调模型 → 存本轮」 
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
        .build();

@GetMapping("/chat")
public String chat(@RequestParam("userId") String userId, @RequestParam("message") String message) {
    return chatClient.prompt()
            .user(message)
            .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, bo.getConversationId())))  // 按conversationId隔离
            .call()
            .content();
}

        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
        </dependency>

        <!--jdbc-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        <!--mysql驱动-->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>

spring.ai.chat.memory.repository.jdbc.initialize-schema=always
spring.ai.chat.memory.repository.jdbc.schema=classpath:/schema-mysql.sql

//application.yml
spring:
  datasource:
    username: root
    password: 123456
    url: jdbc:mysql://localhost:3306/springai?characterEncoding=utf8&useSSL=false&serverTimezone=UTC&
    driver-class-name: com.mysql.cj.jdbc.Driver

@Configuration
public class ChatMemoryConfig {


    @Bean
    ChatMemory chatMemory(JdbcChatMemoryRepository chatMemoryRepository) {
        return MessageWindowChatMemory
        .builder()
        .maxMessages(1)
        .chatMemoryRepository(chatMemoryRepository).build();
    }

}

@Bean
    public RedisChatMemoryRepository redisChatMemoryRepository() {
        return RedisChatMemoryRepository._builder_()
                .host(redisHost)
                .port(redisPort)
                .password(redisPassword)
                .timeout(redisTimeout)
                .build();
    }

// 手动预置上下文（对话开始前注入业务背景）
chatMemory.add(conversationId, List.of(new UserMessage("对方是储能用户，请在其储能专业的角度回答")));

// 读取历史
List<Message> history = chatMemory.get(conversationId);

// 清空会话（「开始新对话」按钮）
chatMemory.clear(conversationId);

// 用模型生成摘要
String summary = chatClient.prompt()
        .system("把下面的对话历史总结成 200 字以内的摘要，保留关键信息：")
        .user(historyText)   // historyText = 拼接后的历史对话
        .call()
        .content();

ChatClient.builder(chatModel)
    .defaultSystem("你是智慧能源管理系统（EMS）的智能助手，请用中文简洁、专业地回答用户问题。")

String answer = ChatClient.create(chatModel).prompt()
    .user(u -> u
            .text("列出5个{domain}行业常见风险点，并简单说明。")
            .param("domain", "电化学储能电站"))
    .call()
    .content();

String systemText = """
  你是一个友好的 AI 助手，帮助人们寻找信息。
  你的名字是 {name}。
  你应该以 {voice} 的风格回复用户。
  """;
SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemText);
Message systemMessage = systemPromptTemplate.createMessage(Map.of("name", "小助手", "voice", "专业"));

Prompt prompt = new Prompt(List.of(userMessage, systemMessage));
List<Generation> response = chatModel.call(prompt).getResults();

// ChatClient 写法：指定 templateRenderer
String answer = ChatClient.create(chatModel).prompt()
    .user(u -> u
            .text("告诉我5部<composer>的电影")
            .param("composer", "John Williams"))
    .templateRenderer(StTemplateRenderer.builder()
            .startDelimiterToken('<')
            .endDelimiterToken('>')
            .build())
    .call()
    .content();

// ChatModel 写法：PromptTemplate.builder() 指定 renderer
PromptTemplate promptTemplate = PromptTemplate.builder()
    .renderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
    .template("告诉我5部<composer>的电影.")
    .build();
String prompt = promptTemplate.render(Map.of("composer", "John Williams"));

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>

// 1. 读取（支持 PDF/Word/HTML 等，底层用 Apache Tika）
var reader = new TikaDocumentReader("file:./docs/handbook.pdf");

// 2. 切分（按 token 分块，避免单块过长）
TokenTextSplitter splitter = new TokenTextSplitter(800, 350, 5, 10000, true);

// 3. 写入向量库（自动 embedding）
List<Document> chunks = splitter.apply(reader.get());
vectorStore.add(chunks);

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-advisors-vector-store</artifactId>
</dependency>

QuestionAnswerAdvisor qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder()
                .topK(5)
                .similarityThreshold(0.45)
                .build())
        .build();

ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(qaAdvisor)
        .build();

// 提问时会自动检索并注入上下文
String answer = chatClient.prompt()
        .user("我们的产品支持哪些支付方式？")
        .call()
        .content();

Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        // 查（相当于 QuestionAnswerAdvisor 的检索部分）
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .vectorStore(vectorStore)
                .similarityThreshold(0.5)
                .build())
        // 可选：检索为空时自定义兜底话术（默认直接把问题原样发给模型）
        .queryAugmenter(ContextualQueryAugmenter.builder()
                .allowEmptyContext(false)
                .emptyContextPromptTemplate(PromptTemplate.builder()
                        .template("用户查询位于知识库之外，请礼貌告知无法回答").build())
                .build())
        // 可选：查询重写——用户表述模糊时，先让大模型改写成更适合检索的查询
        .queryTransformers(RewriteQueryTransformer.builder()
                .chatClientBuilder(ChatClient.builder(chatModel))
                .targetSearchSystem("能源管理知识库助手")
                .build())
        // 可选：检索后处理——拿到文档后还可以过滤、打日志、重排序
        .documentPostProcessors((query, documents) -> {
            return documents;
        })
        .build();

String answer = chatClient.prompt()
        .user("策略的政策是什么？")
        .advisors(a -> a.param(
                QuestionAnswerAdvisor.FILTER_EXPRESSION, "source == 'policy.md'"))
        .call()
        .content();

// 示例：给每个块生成前/中/后三段摘要
SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel,
        List.of(SummaryMetadataEnricher.SummaryType.PREVIOUS,
                SummaryMetadataEnricher.SummaryType.CURRENT,
                SummaryMetadataEnricher.SummaryType.NEXT));
chunks = enricher.apply(chunks);

请求（Prompt） ──► [ Advisor 链 ] ──► 调用大模型 ──► 响应（ChatResponse）
                     ▲                                │
                     └──── 响应再反向经过 Advisor ◄────┘

chatClient = ChatClient
        .builder(chatModel)
        .defaultAdvisors(new SimpleLoggerAdvisor())
        .build();

ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(
                MessageChatMemoryAdvisor.builder(chatMemory).order(10).build(), // 1. 先注入历史
                qaAdvisor,                                                       // 2. 再检索注入
                new SimpleLoggerAdvisor())                                       // 3. 最后打印日志
        .build();

public class AppendSuffixAdvisor implements BaseAdvisor {

    @Override
    public ChatClientRequest before(ChatClientRequest request, AdvisorChain chain) {
        // 给用户消息追加后缀（ChatClientRequest 不可变，用 mutate 生成新对象）
        return request.mutate()
                .prompt(request.prompt().augmentUserMessage("\n\n请用中文回答。"))
                .build();
    }

    @Override
    public ChatClientResponse after(ChatClientResponse response, AdvisorChain chain) {
        // 响应阶段可在此记录日志、改写输出等
        return response;
    }

    @Override
    public int getOrder() {
        return 0;
    }
}