spring-ai之Advisors API

1、

Spring AI Advisors API 提供了一种灵活而强大的方法来拦截、
修改和增强 Spring 应用程序中的 AI 驱动的交互。 
通过利用 Advisors API，开发人员可以创建更复杂、可重用和可维护的 AI 组件。

主要优势包括封装重复的生成式 AI 模式、转换发送到大型语言模型 （LLM）
 和从大型语言模型 （LLM） 发送的数据，以及提供跨各种模型和用例的可移植性。

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        new MessageChatMemoryAdvisor(chatMemory), // chat-memory advisor
        new QuestionAnswerAdvisor(vectorStore)    // RAG advisor
    )
    .build();

String response = this.chatClient.prompt()
    // Set advisor parameters at runtime
    .advisors(advisor -> advisor.param("chat_memory_conversation_id", "678")
            .param("chat_memory_response_size", 100))
    .user(userText)
    .call()
	.content();

2、 

Advisors API 包括CallAroundAdvisor和CallAroundAdvisorChain
对于非流式处理方案，以及StreamAroundAdvisor和
StreamAroundAdvisorChain用于流式处理方案。 它还包括AdvisedRequest
来表示未封装的 Prompt 请求，AdvisedResponse以获取 Chat Completion 
响应。两者都持有advise-context在 advisor chain 中共享状态。

nextAroundCall()和nextAroundStream()是关键的 advisor 方法，
通常执行诸如检查未密封的 Prompt 数据、自定义和扩充 Prompt 数据、调用
 advisor chain 中的下一个实体、选择性地阻止请求、检查聊天完成响应以及
引发异常以指示处理错误等作。此外，getOrder() method 确定链中的 
advisor 顺序，而getName()提供唯一的 advisor 名称。由 Spring AI 
框架创建的 Advisor 链允许按顺序调用多个 advisor，这些 advisor 
按其getOrder()值。 首先执行较低的值。 自动添加的最后一个 advisor 将请求发送到 LLM。

下图说明了 advisor chain和聊天模型之间的交互

1、The Spring AI framework creates an AdvisedRequest from user’s 
Prompt along with an empty AdvisorContext object.

2、Each advisor in the chain processes the request, 
potentially modifying it. Alternatively, it can choose 
to block the request by not making the call to invoke 
the next entity. In the latter case, the advisor is 
responsible for filling out the response.

3、The final advisor, provided by the framework, 
sends the request to the Chat Model.

4、The Chat Model’s response is then passed back through 
the advisor chain and converted into AdvisedResponse. 
Later includes the shared AdvisorContext instance.

5、Each advisor can process or modify the response.

6、The final AdvisedResponse is returned to the client
 by extracting the ChatCompletion.

1、Spring AI 创建了一个AdvisedRequest从用户的Prompt
以及一个空的AdvisorContext对象。

2、advisor  chain 中的每个 advisor 都会处理请求，
并可能对其进行修改。或者，它也可以选择通过不调用下一个实体来阻止请求。
在后一种情况下，advisor 负责填写回复。

3、spring-ai自身提供的 final advisor 则会将请求发送到Chat Model.

4、然后，聊天模型的响应通过 advisor 链传回并转换为AdvisedResponse.later 
包括共享的AdvisorContext实例。

5、每个advisor 都可以处理或修改响应。

6、final AdvisedResponse通过提取ChatCompletion.

 

Advisor Order
The execution order of advisors in the chain is determined 
by the getOrder() method. Key points to understand:

Advisors with lower order values are executed first.

The advisor chain operates as a stack:

The first advisor in the chain is the first to process the request.

It is also the last to process the response.

To control execution order:

Set the order close to Ordered.HIGHEST_PRECEDENCE to ensure 
an advisor is executed first in the chain (first for request 
processing, last for response processing).

Set the order close to Ordered.LOWEST_PRECEDENCE to ensure 
an advisor is executed last in the chain 
(last for request processing, first for response processing).

Higher values are interpreted as lower priority.

If multiple advisors have the same order value, 
their execution order is not guaranteed.

链中 advisor 的执行顺序由getOrder()方法。需要了解的要点：

首先执行 order值较低的Advisors。

advisor 链以 stack的形式运行（后进先出（LIFO））：

链中的第一个 advisor 是第一个处理请求的人。

链中的第一个 advisor 也是最后一个处理响应的服务器。

要控制执行顺序：

将order设置为 Ordered.HIGHEST_PRECEDENCE确保 advisor 首先在链中执行 
（first for request processing， last for response processing）。

将order设置为 Ordered.LOWEST_PRECEDENCE确保 advisor 在链中最后执行 
（last for request processing， first for response processing）。

较高的值被解释为较低的优先级。

如果多个 advisor 具有相同的order值，则不能保证他们的执行顺序。

Spring AI Built-in Advisors
Spring AI framework provides several built-in advisors to enhance 
your AI interactions. Here’s an overview of the available advisors:

Chat Memory Advisors
These advisors manage conversation history in a chat memory store:

MessageChatMemoryAdvisor

Retrieves memory and adds it as a collection of messages to the 
prompt. This approach maintains the structure of the conversation 
history. Note, not all AI Models support this approach.

PromptChatMemoryAdvisor

Retrieves memory and incorporates it into the prompt’s system text.

VectorStoreChatMemoryAdvisor

Retrieves memory from a VectorStore and adds it into the prompt’s 
system text. This advisor is useful for efficiently searching 
and retrieving relevant information from large datasets.

Question Answering Advisor
QuestionAnswerAdvisor

This advisor uses a vector store to provide question-answering 
capabilities, implementing the RAG (Retrieval-Augmented Generation) pattern.

Content Safety Advisor
SafeGuardAdvisor

A simple advisor designed to prevent the model from generating harmful
 or inappropriate content.

Spring AI 内置顾问程序
Spring AI 框架提供了几个内置的顾问程序来增强您的 AI 交互。以下是可用顾问的概述：

聊天记忆顾问
这些顾问在聊天内存存储中管理对话历史记录：

MessageChatMemoryAdvisor

检索内存并将其作为消息集合添加到提示符中。此方法维护会话历史记录的结构。请注意，
并非所有 AI 模型都支持此方法。

PromptChatMemoryAdvisor

检索内存并将其合并到提示的系统文本中。

VectorStoreChatMemoryAdvisor

从 VectorStore 中检索内存，并将其添加到提示符的系统文本中。此 advisor 
可用于从大型数据集中高效搜索和检索相关信息。

问题解答顾问
QuestionAnswerAdvisor

此 advisor 使用向量存储来提供问答功能，实现 RAG（检索增强生成）模式。

内容安全顾问
SafeGuardAdvisor

一个简单的 advisor，旨在防止模型生成有害或不适当的内容。