Spring Boot3 集成 Spring AI 实现 Advisor 增强机制的完整流程_Java

1、简述

spring ai 的 advisor api 是一种声明式的拦截机制，借鉴了 spring aop 的设计理念，允许开发者在 ai 交互的生命周期关键节点插入自定义逻辑。

2、实现原理

2.1 核心概念

advisor（顾问）本质上是围绕 ai 模型调用的拦截器，在用户发送问题之后、调用大模型之前执行一系列增强操作。

┌─────────────────────────────────────────────────────────────────┐
│                      advisor chain 执行流程                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  用户请求 ──→ advisor 1 ──→ advisor 2 ──→ ... ──→ llm          │
│                │              │                     │            │
│                ↓              ↓                     ↓            │
│            请求预处理      请求预处理           模型调用         │
│                                                                  │
│  用户响应 ←── advisor 1 ←── advisor 2 ←── ... ←── llm          │
│                │              │                     │            │
│                ↓              ↓                     ↓            │
│            响应后处理      响应后处理           原始响应         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

2.2 核心价值

优势	说明
非侵入式增强	无需修改核心业务代码即可添加功能
关注点分离	将横切关注点（日志、安全、缓存）与业务逻辑解耦
可复用性	同一 advisor 可在不同 chatclient 间复用
组合性	多个 advisor 可灵活组合形成拦截链

2.3 执行顺序控制

advisor 链的执行顺序通过 getorder() 方法控制，值越小优先级越高（越先执行）：

public interface ordered {
    int highest_precedence = integer.min_value;  // 最高优先级
    int lowest_precedence = integer.max_value;   // 最低优先级
    int getorder();
}

关键理解：由于 advisor 链的堆栈特性，优先级最高的 advisor 最先处理请求，最后处理响应。

3、环境准备

3.1 maven 依赖

<dependencies>
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-web</artifactid>
    </dependency>
    <!-- spring ai openai starter -->
    <dependency>
        <groupid>org.springframework.ai</groupid>
        <artifactid>spring-ai-starter-model-openai</artifactid>
    </dependency>
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-actuator</artifactid>
    </dependency>
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-devtools</artifactid>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupid>org.projectlombok</groupid>
        <artifactid>lombok</artifactid>
        <optional>true</optional>
    </dependency>
    <!-- 添加jackson支持json处理 -->
    <dependency>
        <groupid>com.fasterxml.jackson.core</groupid>
        <artifactid>jackson-databind</artifactid>
    </dependency>
    <dependency>
        <groupid>com.fasterxml.jackson.core</groupid>
        <artifactid>jackson-annotations</artifactid>
    </dependency>
</dependencies>
<dependencymanagement>
    <dependencies>
        <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>

3.2 基础配置

spring:
  application:
    name: lm-advisor
  # deepseek api 配置 (兼容 openai api)
  ai:
    openai:
      # deepseek api base url
      base-url: https://api.deepseek.com
      # deepseek api key (请替换为你的实际api key)
      api-key: ${deepseek_api_key:you-key}
      # 使用的模型
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7
          max-tokens: 2000

3.3 chatclient 配置

package com.example.demo.config;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
@configuration
public class aiconfig {
    public static string conversation_id = "conversation_id";
    @bean
    public chatclient chatclient(chatclient.builder builder) {
        // 可在此配置默认系统提示词
        return builder
                .defaultsystem("你是一个专业的ai助手，请用中文回答用户问题。")
                .build();
    }
}

4、内置 advisor 详解

spring ai 1.0.0 提供了多个开箱即用的内置 advisor。

4.1 对话记忆 advisor

messagechatmemoryadvisor

将历史消息直接添加到请求的 messages 列表中，适用于支持结构化消息的 chat 模型（如 openai gpt 系列）。

package com.example.demo.service;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.messagechatmemoryadvisor;
import org.springframework.ai.chat.memory.chatmemory;
import org.springframework.ai.chat.memory.messagewindowchatmemory;
import org.springframework.stereotype.service;
@service
public class memoryconversationservice {
    private final string conversation_id = "conversation_id";
    private final chatclient chatclient;
    public memoryconversationservice(chatclient.builder builder) {
        // 创建聊天记忆存储（内存窗口模式，保留最近20条消息）
        chatmemory chatmemory = messagewindowchatmemory.builder()
                .maxmessages(20)
                .build();
        // 创建 messagechatmemoryadvisor
        messagechatmemoryadvisor memoryadvisor = messagechatmemoryadvisor.builder(chatmemory)
                .conversationid("default-session")
                .build();
        this.chatclient = builder
                .defaultadvisors(memoryadvisor)
                .build();
    }
    /**
     * 多轮对话 - 自动保持上下文
     * @param conversationid 会话id（首次调用可传null）
     * @param message 用户消息
     */
    public string chatwithmemory(string conversationid, string message) {
        string convid = conversationid != null ? conversationid : "default-session";
        return chatclient.prompt()
                .user(message)
                .advisors(advisor -> advisor
                        .param(conversation_id, convid))
                .call()
                .content();
    }
}

promptchatmemoryadvisor

将历史消息嵌入到系统提示词（system prompt）中，适用于不支持结构化消息的文本模型（如本地部署的 llama、bloom 等）。

import com.lm.advisor.config.aiconfig;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.promptchatmemoryadvisor;
import org.springframework.ai.chat.memory.chatmemory;
import org.springframework.ai.chat.memory.messagewindowchatmemory;
import org.springframework.stereotype.service;
@service
public class promptmemoryconversationservice {
    private final chatclient chatclient;
    public promptmemoryconversationservice(chatclient.builder builder) {
        chatmemory chatmemory = messagewindowchatmemory.builder()
                .maxmessages(20)
                .build();
        // 创建 promptchatmemoryadvisor
        promptchatmemoryadvisor memoryadvisor = promptchatmemoryadvisor.builder(chatmemory)
                .conversationid("default-session")
                .build();
        this.chatclient = builder
                .defaultadvisors(memoryadvisor)
                .build();
    }
    public string chatwithmemory(string conversationid, string message) {
        string convid = conversationid != null ? conversationid : "default-session";
        return chatclient.prompt()
                .user(message)
                .advisors(advisor -> advisor
                        .param(aiconfig.conversation_id, convid))
                .call()
                .content();
    }
}

4.2 敏感词过滤 advisor（safeguardadvisor）

在用户输入中检测敏感词，发现敏感词时阻止调用模型并返回预设响应。

package com.example.demo.service;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.safeguardadvisor;
import org.springframework.stereotype.service;
import java.util.list;
@service
public class safeguardservice {
    private final chatclient chatclient;
    public safeguardservice(chatclient.builder builder) {
        // 配置敏感词列表
        list<string> sensitivewords = list.of(
                "机密", "绝密", "内部资料",
                "confidential", "secret", "classified"
        );
        // 创建 safeguardadvisor
        safeguardadvisor safeguardadvisor = safeguardadvisor.builder()
                .sensitivewords(sensitivewords)
                .failureresponse("检测到敏感词，请修改您的输入后重试")
                .build();
        this.chatclient = builder
                .defaultadvisors(safeguardadvisor)
                .build();
    }
    public string safechat(string usermessage) {
        return chatclient.prompt()
                .user(usermessage)
                .call()
                .content();
    }
}

4.3 rag advisor（questionansweradvisor）

从向量数据库中检索相关文档，增强上下文后传递给 llm。

package com.example.demo.service;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.vectorstore.questionansweradvisor;
import org.springframework.ai.vectorstore.searchrequest;
import org.springframework.ai.vectorstore.vectorstore;
import org.springframework.stereotype.service;
@service
public class ragservice {
    private final chatclient chatclient;
    public ragservice(chatclient.builder builder, vectorstore vectorstore) {
        // 配置 rag advisor
        questionansweradvisor ragadvisor = questionansweradvisor.builder(vectorstore)
                .searchrequest(searchrequest.builder()
                        .similaritythreshold(0.75)  // 相似度阈值
                        .topk(5)                    // 返回文档数量
                        .build())
                .build();
        this.chatclient = builder
                .defaultadvisors(ragadvisor)
                .build();
    }
    /**
     * 基于知识库的问答
     */
    public string askwithrag(string question) {
        return chatclient.prompt()
                .user(question)
                .call()
                .content();
    }
    /**
     * 动态过滤表达式 - 只检索特定类型的文档
     */
    public string askwithfilter(string question, string filterexpression) {
        return chatclient.prompt()
                .user(question)
                .advisors(advisor -> advisor
                        .param(questionansweradvisor.filter_expression, filterexpression))
                .call()
                .content();
    }
}

4.4 日志记录 advisor（simpleloggeradvisor）

打印请求和响应信息，默认 json 格式化输出。

import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.simpleloggeradvisor;
import org.springframework.stereotype.service;
@service
public class loggingservice {
    private final chatclient chatclient;
    public loggingservice(chatclient.builder builder) {
        // 使用内置的 simpleloggeradvisor
        this.chatclient = builder
                .defaultadvisors(new simpleloggeradvisor())
                .build();
    }
    public string chat(string message) {
        return chatclient.prompt()
                .user(message)
                .call()
                .content();
    }
}

5、自定义 advisor 开发

5.1 继承 baseadvisor（推荐方式）

spring ai 1.0.0 推荐继承 baseadvisor 抽象类，只需实现 before() 和 after() 方法。

package com.example.demo.advisor;
import lombok.extern.slf4j.slf4j;
import org.springframework.ai.chat.client.chatclientrequest;
import org.springframework.ai.chat.client.chatclientresponse;
import org.springframework.ai.chat.client.advisor.api.*;
import org.springframework.core.ordered;
@slf4j
public class performanceloggingadvisor implements baseadvisor, ordered {
    @override
    public chatclientrequest before(chatclientrequest request, advisorchain chain) {
        // 请求前处理：记录开始时间
        long starttime = system.currenttimemillis();
        // 将开始时间存入上下文，供 after 方法使用
        request.context().put("starttime", starttime);
        log.info("=== ai 请求开始 ===");
        log.info("用户消息: {}", request.prompt().getusermessage().gettext());
        log.info("系统消息: {}", request.prompt().getsystemmessage().gettext());
        return request;
    }
    @override
    public chatclientresponse after(chatclientresponse response, advisorchain chain) {
        // 响应后处理：计算耗时
        long starttime = (long) response.context().getordefault("starttime", system.currenttimemillis());
        long duration = system.currenttimemillis() - starttime;
        string content = response.chatresponse().getresult().getoutput().gettext();
        log.info("=== ai 响应完成 ===");
        log.info("响应内容: {}", content != null && content.length() > 100
                ? content.substring(0, 100) + "..." : content);
        log.info("耗时: {}ms", duration);
        return response;
    }
    @override
    public int getorder() {
        return ordered.highest_precedence + 100;
    }
}

5.2 敏感词拦截 advisor（拦截式）

继承 baseadvisor 并重写 before()，在检测到敏感词时提前终止链调用。

package com.example.demo.advisor;
import org.springframework.ai.chat.client.chatclientrequest;
import org.springframework.ai.chat.client.chatclientresponse;
import org.springframework.ai.chat.client.advisor.api.*;
import org.springframework.ai.chat.messages.assistantmessage;
import org.springframework.ai.chat.model.chatresponse;
import org.springframework.ai.chat.model.generation;
import org.springframework.core.ordered;
import java.util.list;
public class sensitivewordinterceptoradvisor implements baseadvisor, ordered {
    private final list<string> sensitivewords;
    private final string blockmessage;
    public sensitivewordinterceptoradvisor(list<string> sensitivewords) {
        this(sensitivewords, "您的输入包含敏感词，请修改后重试");
    }
    public sensitivewordinterceptoradvisor(list<string> sensitivewords, string blockmessage) {
        this.sensitivewords = sensitivewords;
        this.blockmessage = blockmessage;
    }
    @override
    public chatclientrequest before(chatclientrequest request, advisorchain chain) {
        string usertext = request.prompt().getusermessage().gettext();
        string detectedword = detectsensitiveword(usertext);
        if (detectedword != null) {
            // 检测到敏感词，设置阻断标记
            request.context().put("blocked", true);
            request.context().put("blockreason", "敏感词: " + detectedword);
        }
        return request;
    }
    @override
    public chatclientresponse after(chatclientresponse response, advisorchain chain) {
        // 检查是否被阻断
        if (boolean.true.equals(response.context().get("blocked"))) {
            // 返回预设的阻断响应
            list<generation> generations = new java.util.arraylist<>();
            generations.add(new generation(new assistantmessage(blockmessage)));
            chatresponse blockresponse = new chatresponse(generations);
            return new chatclientresponse(blockresponse, response.context());
        }
        return response;
    }
    private string detectsensitiveword(string text) {
        if (text == null) return null;
        for (string word : sensitivewords) {
            if (text.contains(word)) {
                return word;
            }
        }
        return null;
    }
    @override
    public int getorder() {
        return ordered.highest_precedence + 50;
    }
}

5.3 re-reading 增强 advisor

基于 re-reading（re2）技术，通过重复阅读问题来提升理解准确率。

package com.example.demo.advisor;
import org.springframework.ai.chat.client.chatclientrequest;
import org.springframework.ai.chat.client.chatclientresponse;
import org.springframework.ai.chat.client.advisor.api.*;
import org.springframework.core.ordered;
import java.util.hashmap;
import java.util.map;
/**
 * re-reading 增强 advisor
 * 通过让模型重复阅读问题来提升理解准确率
 * 基于 re2 技术：https://arxiv.org/abs/2309.06275
 */
public class rereadingadvisor implements baseadvisor, ordered {
    private static final string re_read_template = """
            {re2_input_query}
            read the question again: {re2_input_query}
            """;
    @override
    public chatclientrequest before(chatclientrequest request, advisorchain chain) {
        // 获取原始用户消息
        string inputquery = request.prompt().getusermessage().gettext();
        // 构建增强后的用户消息参数
        map<string, object> params = new hashmap<>(request.prompt().getusermessage().getmetadata());
        params.put("re2_input_query", inputquery);
        // 创建增强后的请求
        return  request.copy()
                .mutate()
                .context(params)
                .build();
    }
    @override
    public chatclientresponse after(chatclientresponse chatclientresponse, advisorchain advisorchain) {
        return null;
    }
    @override
    public int getorder() {
        return ordered.lowest_precedence - 100;
    }
}

6、advisor 链配置与组合

6.1 组合多个 advisor

package com.example.demo.config;
import com.lm.advisor.advisor.performanceloggingadvisor;
import com.lm.advisor.advisor.rereadingadvisor;
import com.lm.advisor.advisor.sensitivewordinterceptoradvisor;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.messagechatmemoryadvisor;
import org.springframework.ai.chat.client.advisor.vectorstore.questionansweradvisor;
import org.springframework.ai.chat.memory.messagewindowchatmemory;
import org.springframework.ai.embedding.embeddingmodel;
import org.springframework.ai.vectorstore.simplevectorstore;
import org.springframework.ai.vectorstore.vectorstore;
import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
import java.util.list;
@configuration
public class advisorchainconfig {
    @bean
    public chatclient chatclientwithadvisors(
            chatclient.builder builder,
            vectorstore vectorstore) {
        // 创建各个 advisor
        sensitivewordinterceptoradvisor sensitivewordadvisor =
                new sensitivewordinterceptoradvisor(list.of("敏感词1", "敏感词2"));
        performanceloggingadvisor loggingadvisor = new performanceloggingadvisor();
        messagechatmemoryadvisor memoryadvisor = messagechatmemoryadvisor.builder(
                        messagewindowchatmemory.builder().maxmessages(20).build())
                .conversationid("default")
                .build();
        questionansweradvisor ragadvisor = questionansweradvisor.builder(vectorstore)
                .build();
        rereadingadvisor rereadingadvisor = new rereadingadvisor();
        // 按顺序配置 advisor 链
        // 执行顺序：敏感词过滤 -> 日志记录 -> 对话记忆 -> rag -> re-reading
        return builder
                .defaultadvisors(
                        sensitivewordadvisor,
                        loggingadvisor,
                        memoryadvisor,
                        ragadvisor,
                        rereadingadvisor
                )
                .defaultsystem("你是一个乐于助人的 ai 助手，请用中文回答用户问题。")
                .build();
    }
    @bean
    public vectorstore vectorstore(embeddingmodel embeddingmodel) {
        // 使用内存向量存储，适合开发和测试环境
        return simplevectorstore.builder(embeddingmodel)
                .build();
    }
}

6.2 运行时动态添加 advisor

import com.lm.advisor.config.aiconfig;
import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.chat.client.advisor.messagechatmemoryadvisor;
import org.springframework.ai.chat.client.advisor.vectorstore.questionansweradvisor;
import org.springframework.stereotype.service;
@service
public class dynamicadvisorservice {
    private final chatclient chatclient;
    public dynamicadvisorservice(chatclient.builder builder) {
        // 基础配置，不预设 advisor
        this.chatclient = builder.build();
    }
    /**
     * 运行时根据场景动态添加 advisor
     */
    public string chatwithruntimeadvisors(string question, string conversationid) {
        return chatclient.prompt()
                .user(question)
                // 动态添加对话记忆 advisor
                .advisors(advisor -> advisor
                        .param(aiconfig.conversation_id, conversationid))
                // 动态添加 rag advisor
                .advisors(advisor -> advisor
                        .param(questionansweradvisor.filter_expression, "type == 'knowledge'"))
                .call()
                .content();
    }
}

7、常见问题与最佳实践

7.1 messagechatmemoryadvisor 与 promptchatmemoryadvisor 的区别

特性	messagechatmemoryadvisor	promptchatmemoryadvisor
消息存储方式	直接添加到 `messages` 列表	嵌入到系统提示词
适用模型	openai gpt 等 chat 模型	llama、bloom 等文本模型
优点	精确控制消息类型（用户、系统、助手）	通用性更强，不依赖模型能力
缺点	依赖模型支持 messages 参数	可能增加 token 消耗

7.2 为什么需要覆盖 advisestream 方法

在流式响应场景中，多个流式响应块需要合并成一个完整的响应对象后，再调用 after() 方法，确保只保留完整的模型输出，避免部分信息写入 memory 导致数据混乱。

7.3 性能优化建议

// 1. 避免在 advisor 中进行重量级操作
public class lightweightadvisor extends baseadvisor {
    @override
    public chatclientrequest before(chatclientrequest request, advisorchain chain) {
        // 快速检查，避免阻塞
        if (skipcondition()) {
            return request;
        }
        // 异步处理非关键逻辑
        completablefuture.runasync(() -> asyncprocess(request));
        return request;
    }
}
// 2. 合理设置执行顺序
// 敏感词过滤应最先执行（优先级最高）
// 日志记录应在中间执行
// re-reading 应在最后执行

7.4 注意事项

注意事项	说明
会话 id 管理	必须妥善维护 `chat_memory_conversation_id`，避免每次默认生成新 id 导致垃圾数据
敏感数据	启用 prompt/completion 日志记录时，存在暴露敏感信息的风险
流式处理线程	baseadvisor 默认使用 `schedulers.boundedelastic()` 进行流式处理线程调度
顺序敏感	部分 advisor（如 safeguardadvisor）需要放在链的最前面，才能在早期拦截请求

8、总结

本文全面介绍了 spring boot 集成 spring ai 1.0.0 实现 advisor 增强机制的完整流程，涵盖以下核心内容：

章节	核心知识点
基础概念	advisor 拦截机制、核心接口、执行顺序
环境配置	maven 依赖、配置文件设置
内置 advisor	对话记忆（两种实现）、敏感词过滤、rag、日志记录
自定义开发	继承 baseadvisor、性能日志、敏感词拦截、re-reading 增强
链式组合	多 advisor 组合、运行时动态添加
可观测性	micrometer 指标、opentelemetry 追踪
最佳实践	性能优化、注意事项、常见问题

spring ai 1.0.0 的 advisor 机制为构建生产级 ai 应用提供了强大的扩展能力。通过合理设计和组合 advisor，可以实现：

非侵入式增强：无需修改核心业务代码即可添加功能
关注点分离：将横切关注点（日志、安全、缓存）与业务逻辑解耦
可复用性：同一 advisor 可在不同 chatclient 间复用
可观测性：完整的指标收集和链路追踪能力

到此这篇关于spring boot3 集成 spring ai 实现 advisor 增强机制的完整流程的文章就介绍到这了,更多相关spring boot 集成 spring ai advisor 增强内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

Spring Boot3 集成 Spring AI 实现 Advisor 增强机制的完整流程

2026年03月30日 • Java •我要评论