聊天客户端 API
ChatClient
提供了与 AI 模型通信的流畅 API。
它支持同步和流式编程模型。
有关 |
流畅 API 具有用于构建 Prompt 的组成部分的方法,该 Prompt 作为输入传递给 AI 模型。
Prompt
包含指导 AI 模型输出和行为的指令文本。从 API 的角度来看,Prompt 由消息集合组成。
AI 模型处理两种主要类型的消息:用户消息(来自用户的直接输入)和系统消息(由系统生成以指导对话)。
这些消息通常包含占位符,这些占位符在运行时根据用户输入进行替换,以自定义 AI 模型对用户输入的响应。
还可以指定 Prompt 选项,例如要使用的 AI 模型名称和控制生成输出的随机性或创造性的温度设置。
创建 ChatClient
ChatClient
使用 ChatClient.Builder
对象创建。
您可以获取任何 ChatModel Spring Boot 自动配置的自动配置 ChatClient.Builder
实例,或者以编程方式创建。
使用自动配置的 ChatClient.Builder
在最简单的用例中,Spring AI 提供了 Spring Boot 自动配置,为您创建了一个原型 ChatClient.Builder
bean,以便您将其注入到您的类中。
这是一个检索对简单用户请求的 String
响应的简单示例。
@RestController
class MyController {
private final ChatClient chatClient;
public MyController(ChatClient.Builder chatClientBuilder) {
this.chatClient = chatClientBuilder.build();
}
@GetMapping("/ai")
String generation(String userInput) {
return this.chatClient.prompt()
.user(userInput)
.call()
.content();
}
}
在这个简单的示例中,用户输入设置了用户消息的内容。
call()
方法向 AI 模型发送请求,content()
方法返回 AI 模型的 String
响应。
使用多个聊天模型
在单个应用程序中,您可能需要使用多个聊天模型,这有几种情况:
-
对不同类型的任务使用不同的模型(例如,对于复杂推理使用强大的模型,对于简单任务使用更快、更便宜的模型)
-
当一个模型服务不可用时,实现回退机制
-
对不同的模型或配置进行 A/B 测试
-
根据用户偏好为用户提供模型选择
-
组合专业模型(一个用于代码生成,另一个用于创意内容等)
默认情况下,Spring AI 自动配置单个 ChatClient.Builder
bean。但是,您可能需要在应用程序中使用多个聊天模型。以下是处理此场景的方法:
在所有情况下,您都需要通过设置属性 spring.ai.chat.client.enabled=false
来禁用 ChatClient.Builder
自动配置。
这允许您手动创建多个 ChatClient
实例。
具有单一模型类型的多个 ChatClient
本节介绍了一个常见用例,您需要创建多个 ChatClient 实例,所有实例都使用相同的底层模型类型但配置不同。
// Create ChatClient instances programmatically
ChatModel myChatModel = ... // already autoconfigured by Spring Boot
ChatClient chatClient = ChatClient.create(myChatModel);
// Or use the builder for more control
ChatClient.Builder builder = ChatClient.builder(myChatModel);
ChatClient customChatClient = builder
.defaultSystemPrompt("You are a helpful assistant.")
.build();
适用于不同模型类型的 ChatClient
使用多个 AI 模型时,您可以为每个模型定义单独的 ChatClient
bean:
import org.springframework.ai.chat.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class ChatClientConfig {
@Bean
public ChatClient openAiChatClient(OpenAiChatModel chatModel) {
return ChatClient.create(chatModel);
}
@Bean
public ChatClient anthropicChatClient(AnthropicChatModel chatModel) {
return ChatClient.create(chatModel);
}
}
然后,您可以使用 @Qualifier
注解将这些 bean 注入到应用程序组件中:
@Configuration
public class ChatClientExample {
@Bean
CommandLineRunner cli(
@Qualifier("openAiChatClient") ChatClient openAiChatClient,
@Qualifier("anthropicChatClient") ChatClient anthropicChatClient) {
return args -> {
var scanner = new Scanner(System.in);
ChatClient chat;
// Model selection
System.out.println("\nSelect your AI model:");
System.out.println("1. OpenAI");
System.out.println("2. Anthropic");
System.out.print("Enter your choice (1 or 2): ");
String choice = scanner.nextLine().trim();
if (choice.equals("1")) {
chat = openAiChatClient;
System.out.println("Using OpenAI model");
} else {
chat = anthropicChatClient;
System.out.println("Using Anthropic model");
}
// Use the selected chat client
System.out.print("\nEnter your question: ");
String input = scanner.nextLine();
String response = chat.prompt(input).call().content();
System.out.println("ASSISTANT: " + response);
scanner.close();
};
}
}
多个 OpenAI 兼容的 API 端点
OpenAiApi
和 OpenAiChatModel
类提供了 mutate()
方法,允许您创建具有不同属性的现有实例的变体。这在需要使用多个 OpenAI 兼容 API 时特别有用。
@Service
public class MultiModelService {
private static final Logger logger = LoggerFactory.getLogger(MultiModelService.class);
@Autowired
private OpenAiChatModel baseChatModel;
@Autowired
private OpenAiApi baseOpenAiApi;
public void multiClientFlow() {
try {
// Derive a new OpenAiApi for Groq (Llama3)
OpenAiApi groqApi = baseOpenAiApi.mutate()
.baseUrl("https://api.groq.com/openai")
.apiKey(System.getenv("GROQ_API_KEY"))
.build();
// Derive a new OpenAiApi for OpenAI GPT-4
OpenAiApi gpt4Api = baseOpenAiApi.mutate()
.baseUrl("https://api.openai.com")
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
// Derive a new OpenAiChatModel for Groq
OpenAiChatModel groqModel = baseChatModel.mutate()
.openAiApi(groqApi)
.defaultOptions(OpenAiChatOptions.builder().model("llama3-70b-8192").temperature(0.5).build())
.build();
// Derive a new OpenAiChatModel for GPT-4
OpenAiChatModel gpt4Model = baseChatModel.mutate()
.openAiApi(gpt4Api)
.defaultOptions(OpenAiChatOptions.builder().model("gpt-4").temperature(0.7).build())
.build();
// Simple prompt for both models
String prompt = "What is the capital of France?";
String groqResponse = ChatClient.builder(groqModel).build().prompt(prompt).call().content();
String gpt4Response = ChatClient.builder(gpt4Model).build().prompt(prompt).call().content();
logger.info("Groq (Llama3) response: {}", groqResponse);
logger.info("OpenAI GPT-4 response: {}", gpt4Response);
}
catch (Exception e) {
logger.error("Error in multi-client flow", e);
}
}
}
ChatClient 流畅 API
ChatClient
流畅 API 允许您使用重载的 prompt
方法以三种不同的方式创建 prompt,以启动流畅 API:
-
prompt()
: 这个没有参数的方法允许您开始使用流畅 API,允许您构建用户、系统和 prompt 的其他部分。 -
prompt(Prompt prompt)
: 这个方法接受一个Prompt
参数,允许您传入一个您使用 Prompt 的非流畅 API 创建的Prompt
实例。 -
prompt(String content)
: 这是一个便利方法,类似于前面的重载。它接受用户的文本内容。
ChatClient 响应
ChatClient
API 提供了几种使用流畅 API 格式化 AI 模型响应的方法。
返回 ChatResponse
AI 模型的响应是一个由类型 ChatResponse
定义的丰富结构。
它包含有关响应如何生成的元数据,并且还可以包含多个响应,称为 Generations,每个响应都有自己的元数据。
元数据包括用于创建响应的令牌数量(每个令牌大约是 3/4 个单词)。
此信息很重要,因为托管 AI 模型根据每个请求使用的令牌数量收费。
下面通过在 call()
方法后调用 chatResponse()
来返回包含元数据的 ChatResponse
对象的示例。
ChatResponse chatResponse = chatClient.prompt()
.user("Tell me a joke")
.call()
.chatResponse();
返回实体
您通常希望返回一个从返回的 String
映射的实体类。
entity()
方法提供了此功能。
例如,给定 Java 记录:
record ActorFilms(String actor, List<String> movies) {}
您可以轻松地使用 entity()
方法将 AI 模型的输出映射到此记录,如下所示:
ActorFilms actorFilms = chatClient.prompt()
.user("Generate the filmography for a random actor.")
.call()
.entity(ActorFilms.class);
还有一个重载的 entity
方法,其签名是 entity(ParameterizedTypeReference<T> type)
,允许您指定泛型列表等类型:
List<ActorFilms> actorFilms = chatClient.prompt()
.user("Generate the filmography of 5 movies for Tom Hanks and Bill Murray.")
.call()
.entity(new ParameterizedTypeReference<List<ActorFilms>>() {});
流式响应
stream()
方法允许您获取异步响应,如下所示:
Flux<String> output = chatClient.prompt()
.user("Tell me a joke")
.stream()
.content();
您还可以使用 Flux<ChatResponse> chatResponse()
方法流式传输 ChatResponse
。
将来,我们将提供一个便利方法,允许您使用响应式 stream()
方法返回 Java 实体。
同时,您应该使用 结构化输出转换器 明确转换聚合响应,如下所示。
这还演示了在流畅 API 中使用参数,这将在文档的后面部分更详细地讨论。
var converter = new BeanOutputConverter<>(new ParameterizedTypeReference<List<ActorsFilms>>() {});
Flux<String> flux = this.chatClient.prompt()
.user(u -> u.text("""
Generate the filmography for a random actor.
{format}
""")
.param("format", this.converter.getFormat()))
.stream()
.content();
String content = this.flux.collectList().block().stream().collect(Collectors.joining());
List<ActorsFilms> actorFilms = this.converter.convert(this.content);
提示模板
ChatClient
流畅 API 允许您提供带有变量的用户和系统文本模板,这些变量在运行时被替换。
String answer = ChatClient.create(chatModel).prompt()
.user(u -> u
.text("Tell me the names of 5 movies whose soundtrack was composed by {composer}")
.param("composer", "John Williams"))
.call()
.content();
在内部,ChatClient 使用 PromptTemplate
类处理用户和系统文本,并替换运行时提供的值的变量,依赖于给定的 TemplateRenderer
实现。
默认情况下,Spring AI 使用 StTemplateRenderer
实现,该实现基于 Terence Parr 开发的开源 StringTemplate 引擎。
Spring AI 还提供了一个 NoOpTemplateRenderer
,用于不需要模板处理的情况。
直接在 |
如果您想使用不同的模板引擎,可以直接向 ChatClient 提供 TemplateRenderer
接口的自定义实现。您也可以继续使用默认的 StTemplateRenderer
,但使用自定义配置。
例如,默认情况下,模板变量由 {}
语法标识。如果您计划在 prompt 中包含 JSON,您可能希望使用不同的语法来避免与 JSON 语法冲突。例如,您可以使用 <
和 >
分隔符。
String answer = ChatClient.create(chatModel).prompt()
.user(u -> u
.text("Tell me the names of 5 movies whose soundtrack was composed by <composer>")
.param("composer", "John Williams"))
.templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
.call()
.content();
call() 返回值
在 ChatClient
上指定 call()
方法后,有几种不同的响应类型选项。
-
String content()
: 返回响应的 String 内容 -
ChatResponse chatResponse()
: 返回ChatResponse
对象,该对象包含多个生成以及有关响应的元数据,例如用于创建响应的令牌数量。 -
ChatClientResponse chatClientResponse()
: 返回一个ChatClientResponse
对象,其中包含ChatResponse
对象和 ChatClient 执行上下文,使您可以访问在 Advisor 执行期间使用的额外数据(例如在 RAG 流程中检索到的相关文档)。 -
ResponseEntity<?> responseEntity()
: 返回一个ResponseEntity
,其中包含完整的 HTTP 响应,包括状态码、标头和正文。当您需要访问响应的低级 HTTP 详细信息时,这很有用。 -
entity()
返回 Java 类型-
entity(ParameterizedTypeReference<T> type)
: 用于返回实体类型的Collection
。 -
entity(Class<T> type)
: 用于返回特定的实体类型。 -
entity(StructuredOutputConverter<T> structuredOutputConverter)
: 用于指定StructuredOutputConverter
的实例,将String
转换为实体类型。
-
您还可以调用 stream()
方法而不是 call()
。
调用 |
stream() 返回值
在 ChatClient
上指定 stream()
方法后,有几种响应类型选项:
-
Flux<String> content()
: 返回 AI 模型正在生成的字符串的Flux
。 -
Flux<ChatResponse> chatResponse()
: 返回ChatResponse
对象的Flux
,其中包含有关响应的额外元数据。 -
Flux<ChatClientResponse> chatClientResponse()
: 返回ChatClientResponse
对象的Flux
,其中包含ChatResponse
对象和 ChatClient 执行上下文,使您可以访问在 Advisor 执行期间使用的额外数据(例如在 RAG 流程中检索到的相关文档)。
使用默认值
在 @Configuration
类中创建具有默认系统文本的 ChatClient
简化了运行时代码。
通过设置默认值,您只需在调用 ChatClient
时指定用户文本,从而无需在运行时代码路径中为每个请求设置系统文本。
默认系统文本
在以下示例中,我们将系统文本配置为始终以海盗的口吻回复。
为了避免在运行时代码中重复系统文本,我们将在 @Configuration
类中创建一个 ChatClient
实例。
@Configuration
class Config {
@Bean
ChatClient chatClient(ChatClient.Builder builder) {
return builder.defaultSystem("You are a friendly chat bot that answers question in the voice of a Pirate")
.build();
}
}
以及一个 @RestController
来调用它:
@RestController
class AIController {
private final ChatClient chatClient;
AIController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai/simple")
public Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("completion", this.chatClient.prompt().user(message).call().content());
}
}
通过 curl 调用应用程序端点时,结果是:
❯ curl localhost:8080/ai/simple
{"completion":"Why did the pirate go to the comedy club? To hear some arrr-rated jokes! Arrr, matey!"}
带有参数的默认系统文本
在以下示例中,我们将在系统文本中使用占位符,以在运行时而不是设计时指定完成的语音。
@Configuration
class Config {
@Bean
ChatClient chatClient(ChatClient.Builder builder) {
return builder.defaultSystem("You are a friendly chat bot that answers question in the voice of a {voice}")
.build();
}
}
@RestController
class AIController {
private final ChatClient chatClient;
AIController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai")
Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message, String voice) {
return Map.of("completion",
this.chatClient.prompt()
.system(sp -> sp.param("voice", voice))
.user(message)
.call()
.content());
}
}
通过 httpie 调用应用程序端点时,结果是:
http localhost:8080/ai voice=='Robert DeNiro'
{
"completion": "You talkin' to me? Okay, here's a joke for ya: Why couldn't the bicycle stand up by itself? Because it was two tired! Classic, right?"
}
其他默认值
在 ChatClient.Builder
级别,您可以指定默认的提示配置。
-
defaultOptions(ChatOptions chatOptions)
: 传入在ChatOptions
类中定义的可移植选项或模型特定选项,例如OpenAiChatOptions
中的选项。有关模型特定的ChatOptions
实现的更多信息,请参阅 JavaDocs。 -
defaultFunction(String name, String description, java.util.function.Function<I, O> function)
:name
用于在用户文本中引用该函数。description
解释了函数的作用,并帮助 AI 模型选择正确的函数以获得准确的响应。function
参数是一个 Java 函数实例,模型在必要时将执行该实例。 -
defaultFunctions(String… functionNames)
: 应用程序上下文中定义的java.util.Function
的 bean 名称。 -
defaultUser(String text)
,defaultUser(Resource text)
,defaultUser(Consumer<UserSpec> userSpecConsumer)
: 这些方法允许您定义用户文本。Consumer<UserSpec>
允许您使用 lambda 表达式指定用户文本和任何默认参数。 -
defaultAdvisors(Advisor… advisor)
: Advisors 允许修改用于创建Prompt
的数据。QuestionAnswerAdvisor
实现通过将与用户文本相关的上下文信息附加到 prompt 来启用检索增强生成
模式。 -
defaultAdvisors(Consumer<AdvisorSpec> advisorSpecConsumer)
: 此方法允许您定义Consumer
以使用AdvisorSpec
配置多个 advisors。Advisors 可以修改用于创建最终Prompt
的数据。Consumer<AdvisorSpec>
允许您指定一个 lambda 表达式来添加 advisors,例如QuestionAnswerAdvisor
,它通过根据用户文本附加相关的上下文信息来支持检索增强生成
。
您可以使用不带 default
前缀的相应方法在运行时覆盖这些默认值。
-
options(ChatOptions chatOptions)
-
function(String name, String description, java.util.function.Function<I, O> function)
-
functions(String… functionNames)
-
user(String text)
,user(Resource text)
,user(Consumer<UserSpec> userSpecConsumer)
-
advisors(Advisor… advisor)
-
advisors(Consumer<AdvisorSpec> advisorSpecConsumer)
顾问 (Advisors)
Advisors API 提供了一种灵活而强大的方式来拦截、修改和增强 Spring 应用程序中的 AI 驱动交互。
调用带有用户文本的 AI 模型时,一种常见模式是附加或增强带有上下文数据的提示。
此上下文数据可以是不同类型。常见类型包括:
-
您自己的数据: 这是 AI 模型尚未训练过的数据。即使模型看到过类似数据,附加的上下文数据在生成响应时也具有优先权。
-
对话历史记录: 聊天模型的 API 是无状态的。如果您告诉 AI 模型您的名字,它在后续交互中不会记住。对话历史记录必须随每个请求发送,以确保在生成响应时考虑先前的交互。
ChatClient 中的 Advisor 配置
ChatClient 流畅 API 提供了 AdvisorSpec
接口用于配置顾问。此接口提供了添加参数、一次设置多个参数以及向链中添加一个或多个顾问的方法。
interface AdvisorSpec {
AdvisorSpec param(String k, Object v);
AdvisorSpec params(Map<String, Object> p);
AdvisorSpec advisors(Advisor... advisors);
AdvisorSpec advisors(List<Advisor> advisors);
}
顾问添加到链中的顺序至关重要,因为它决定了它们的执行顺序。每个顾问都会以某种方式修改提示或上下文,一个顾问所做的更改将传递给链中的下一个顾问。
ChatClient.builder(chatModel)
.build()
.prompt()
.advisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
QuestionAnswerAdvisor.builder(vectorStore).build()
)
.user(userText)
.call()
.content();
在此配置中,MessageChatMemoryAdvisor
将首先执行,将对话历史记录添加到提示中。然后,QuestionAnswerAdvisor
将根据用户的提问和添加的对话历史记录执行其搜索,可能会提供更相关的结果。
检索增强生成
请参阅 检索增强生成 指南。
日志记录
SimpleLoggerAdvisor
是一个顾问,它记录 ChatClient
的 request
和 response
数据。
这对于调试和监控您的 AI 交互很有用。
Spring AI 支持 LLM 和向量存储交互的可观测性。有关更多信息,请参阅 可观测性 指南。 |
要启用日志记录,请在创建 ChatClient 时将 SimpleLoggerAdvisor
添加到顾问链中。
建议将其添加到链的末尾:
ChatResponse response = ChatClient.create(chatModel).prompt()
.advisors(new SimpleLoggerAdvisor())
.user("Tell me a joke?")
.call()
.chatResponse();
要查看日志,请将顾问包的日志级别设置为 DEBUG
:
logging.level.org.springframework.ai.chat.client.advisor=DEBUG
将其添加到您的 application.properties
或 application.yaml
文件中。
您可以使用以下构造函数自定义从 AdvisedRequest
和 ChatResponse
记录的数据:
SimpleLoggerAdvisor(
Function<ChatClientRequest, String> requestToString,
Function<ChatResponse, String> responseToString,
int order
)
使用示例:
SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
request -> "Custom request: " + request.prompt().getUserMessage(),
response -> "Custom response: " + response.getResult(),
0
);
这允许您根据您的特定需求定制记录的信息。
在生产环境中记录敏感信息时要谨慎。 |
聊天记忆
接口 ChatMemory
代表聊天对话记忆的存储。它提供了将消息添加到对话、从对话中检索消息和清除对话历史记录的方法。
目前有一个内置实现:MessageWindowChatMemory
。
MessageWindowChatMemory
是一种聊天记忆实现,它维护一个消息窗口,最大大小为指定值(默认:20 条消息)。当消息数量超过此限制时,较旧的消息将被逐出,但系统消息将保留。如果添加了新的系统消息,所有以前的系统消息将从记忆中删除。这确保了对话始终可用最新的上下文,同时保持内存使用量有界。
MessageWindowChatMemory
由 ChatMemoryRepository
抽象支持,该抽象为聊天对话记忆提供存储实现。有几种可用的实现,包括 InMemoryChatMemoryRepository
、JdbcChatMemoryRepository
、CassandraChatMemoryRepository
和 Neo4jChatMemoryRepository
。
有关更多详细信息和使用示例,请参阅 聊天记忆 文档。
实现注意事项
在 ChatClient
中结合使用命令式和响应式编程模型是 API 的一个独特方面。
通常,应用程序要么是响应式的,要么是命令式的,但不会两者兼而有之。
-
当自定义模型实现的 HTTP 客户端交互时,必须同时配置 RestClient 和 WebClient。
由于 Spring Boot 3.4 中的一个错误,必须设置 "spring.http.client.factory=jdk" 属性。否则,它默认为 "reactor",这会破坏某些 AI 工作流,例如 ImageModel。
-
流式传输仅通过响应式堆栈支持。因此,命令式应用程序必须包含响应式堆栈(例如 spring-boot-starter-webflux)。
-
非流式传输仅通过 Servlet 堆栈支持。因此,响应式应用程序必须包含 Servlet 堆栈(例如 spring-boot-starter-web),并期望某些调用是阻塞的。
-
工具调用是命令式的,导致阻塞工作流。这也会导致 Micrometer 观察结果部分/中断(例如,ChatClient span 和工具调用 span 不连接,第一个 span 因此保持不完整)。
-
内置的顾问对标准调用执行阻塞操作,对流式调用执行非阻塞操作。用于顾问流式调用的 Reactor 调度器可以通过每个顾问类上的 Builder 进行配置。