Skip to main content

Chat Client API

关于 ChatClient​

ChatClient 提供了一个流畅的 API 用于与 AI 模型进行通信。它同时支持同步和流式编程模型。

tip

关于 ChatClient 中命令式和响应式编程模型组合使用的相关说明，请参阅本文档底部的实现说明部分。

ChatClient API 提供了构建 Prompt 各个组成部分的方法，这些 Prompt 将作为输入传递给 AI 模型。从 API 的角度来看，Prompt 包含了一系列消息。AI 模型处理两种主要类型的消息:用户消息(来自用户的直接输入)和系统消息(由系统生成以指导对话)。这些消息通常包含占位符，这些占位符会在运行时根据用户输入进行替换，以定制 AI 模型对用户输入的响应。还可以指定 Prompt 选项，例如要使用的 AI 模型名称和 topK 或创造性的 temperature 设置。

创建 ChatClient​

ChatClient 是使用 ChatClient.Builder 对象创建的。ChatBuilder 中需要传入一个 ChatModel，您可以集成相关的 Spring Boot Starter 或者使用编程方式自动创建一个 ChatModel 传入。

使用自动配置的 ChatClient.Builder​

在最简单的用例中，Spring AI 提供了 Spring Boot Starter，为您创建一个原型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 实例，它们都使用相同的基础模型类型但具有不同的配置。

// 以编程方式创建 ChatClient 实例
ChatModel myChatModel = ... // 已由 Spring Boot 自动配置
ChatClient chatClient = ChatClient.create(myChatModel);

// 或使用构建器以获得更多控制
ChatClient.Builder builder = ChatClient.builder(myChatModel);
ChatClient customChatClient = builder
    .defaultSystemPrompt("你是一个乐于助人的助手。")
    .build();
不同模型类型的 ChatClient​

当使用多个 AI 模型时，您可以为每个模型定义单独的 ChatClient bean:

@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;

            // 模型选择
            System.out.println("\n 选择您的 AI 模型:");
            System.out.println("1. OpenAI");
            System.out.println("2. Anthropic");
            System.out.print("输入您的选择 (1 或 2):");
            String choice = scanner.nextLine().trim();

            if (choice.equals("1")) {
                chat = openAiChatClient;
                System.out.println("使用 OpenAI 模型");
            } else {
                chat = anthropicChatClient;
                System.out.println("使用 Anthropic 模型");
            }

            // 使用选定的聊天客户端
            System.out.print("\n 输入您的问题:");
            String input = scanner.nextLine();
            String response = chat.prompt(input).call().content();
            System.out.println("助手:" + 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 {
            // 为 Groq (Llama3) 派生新的 OpenAiApi
            OpenAiApi groqApi = baseOpenAiApi.mutate()
                .baseUrl("https://api.groq.com/openai")
                .apiKey(System.getenv("GROQ_API_KEY"))
                .build();

            // 为 OpenAI GPT-4 派生新的 OpenAiApi
            OpenAiApi gpt4Api = baseOpenAiApi.mutate()
                .baseUrl("https://api.openai.com")
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .build();

            // 为 Groq 派生新的 OpenAiChatModel
            OpenAiChatModel groqModel = baseChatModel.mutate()
                .openAiApi(groqApi)
                .defaultOptions(OpenAiChatOptions.builder().model("llama3-70b-8192").temperature(0.5).build())
                .build();

            // 为 GPT-4 派生新的 OpenAiChatModel
            OpenAiChatModel gpt4Model = baseChatModel.mutate()
                .openAiApi(gpt4Api)
                .defaultOptions(OpenAiChatOptions.builder().model("gpt-4").temperature(0.7).build())
                .build();

            // 两个模型的简单提示
            String prompt = "法国的首都是什么?";
            String groqResponse = ChatClient.builder(groqModel).build().prompt(prompt).call().content();
            String gpt4Response = ChatClient.builder(gpt4Model).build().prompt(prompt).call().content();

            logger.info("Groq (Llama3) 响应:{}", groqResponse);
            logger.info("OpenAI GPT-4 响应:{}", gpt4Response);
        } catch (Exception e) {
            logger.error("多客户端流程中的错误", e);
        }
    }
}

ChatClient Fluent API​

ChatClient Fluent API 允许您使用重载的 prompt 方法以三种不同的方式创建提示:

  • prompt(): 这个无参数方法让您开始使用 Fluent API，允许您构建用户、系统和其他提示部分。
  • prompt(Prompt prompt): 这个方法接受一个 Prompt 参数，让您传入使用 Prompt 的非 Fluent API 创建的 Prompt 实例。
  • prompt(String content): 这是一个类似于前一个重载的便捷方法。它接受用户的文本内容。

ChatClient 响应​

ChatClient API 提供了几种使用 Fluent API 格式化 AI 模型响应的方法。

返回 ChatResponse​

AI 模型的响应是一个由ChatResponse类型定义的丰富结构。它包括有关如何生成响应的元数据，还可以包含多个响应，称为Generations，每个都有自己的元数据。元数据包括用于创建响应的令牌数量(每个令牌大约是一个单词的 3/4)。这些信息很重要，因为托管 AI 模型根据每个请求使用的令牌数量收费。

以下示例通过调用call()方法后的chatResponse()返回包含元数据的ChatResponse对象:

ChatResponse chatResponse = chatClient.prompt()
    .user("给我讲个笑话")
    .call()
    .chatResponse();

返回实体​

您通常希望返回一个从返回的String映射的实体类。entity()方法提供了这个功能。

例如，给定 Java record:

record ActorFilms (String actor, List<String> movies) {}

您可以使用entity()方法轻松地将 AI 模型的输出映射到这个 record，如下所示:

ActorFilms actorFilms = chatClient.prompt()
    .user("生成一个随机演员的电影作品。")
    .call()
    .entity(ActorFilms.class);

还有一个重载的entity方法，签名为entity(ParameterizedTypeReference<T> type)，允许您指定泛型列表等类型:

List<ActorFilms> actorFilms = chatClient.prompt()
    .user("生成汤姆·汉克斯和比尔·默瑞的 5 部电影作品。")
    .call()
    .entity(new ParameterizedTypeReference<List<ActorFilms>>() {});

流式响应​

stream()方法让您可以获得异步响应，如下所示:

Flux<String> output = chatClient.prompt()
    .user("给我讲个笑话")
    .stream()
    .content();

您还可以使用方法Flux<ChatResponse> chatResponse()流式传输ChatResponse。

在未来，我们将提供一个便捷方法，让您使用响应式stream()方法返回 Java 实体。同时，您应该使用结构化输出转换器显式转换聚合响应，如下所示。这也演示了 Fluent API 中参数的使用，这将在文档的后面部分详细讨论。

var converter = new BeanOutputConverter<>(new ParameterizedTypeReference<List<ActorsFilms>>() {});
Flux<String> flux = this.chatClient.prompt()
    .user(u -> u.text("""
        生成一个随机演员的电影作品。
        {format}
        """)
        .param("format", this.converter.getFormat()))
    .stream()
    .content();
String content = this.flux.collectList().block().stream().collect(Collectors.joining());
List<ActorFilms> actorFilms = this.converter.convert(this.content);

提示模板​

ChatClient Fluent API 允许您提供带有变量的用户和系统文本作为模板，这些变量在运行时被替换。

String answer = ChatClient.create(chatModel).prompt()
    .user(u -> u
        .text("告诉我 5 部由{composer}作曲的电影原声带")
        .param("composer", "John Williams"))
    .call()
    .content();

在内部，ChatClient 使用 PromptTemplate 类来处理用户和系统文本，并使用给定的TemplateRenderer实现替换变量。默认情况下，Spring AI 使用StTemplateRenderer实现，它基于 Terence Parr 开发的开源 String Template 引擎。Spring AI 还提供了NoOpTemplateRenderer用于不需要模板处理的情况。

note

直接在ChatClient上配置的TemplateRenderer(通过.templateRenderer())仅适用于直接在ChatClient构建器链中定义的提示内容(例如，通过.user()、.system())。它不会影响 Advisors 内部使用的模板，如QuestionAnswerAdvisor，它们有自己的模板自定义机制(参见自定义 Advisor 模板)。

如果您想使用不同的模板引擎，您可以直接向 ChatClient 提供TemplateRenderer接口的自定义实现。您也可以继续使用默认的StTemplateRenderer，但使用自定义配置。

例如，默认情况下，模板变量由语法标识。如果您计划在提示中包含 JSON，您可能想使用不同的语法以避免与 JSON 语法冲突。例如，您可以使用<和>分隔符。

String answer = ChatClient.create(chatModel).prompt()
    .user(u -> u
        .text("告诉我 5 部由<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 执行上下文，让您可以访问在执行 advisors 期间使用的其他数据(例如，在 RAG 流程中检索的相关文档)。
  • 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 执行上下文，让您可以访问在执行 advisors 期间使用的其他数据(例如，在 RAG 流程中检索的相关文档)。

使用默认值​

在@Configuration类中创建带有默认系统文本的ChatClient可以简化运行时代码。通过设置默认值，您只需要在调用ChatClient时指定用户文本，无需在运行时代码路径中为每个请求设置系统文本。

默认系统文本​

在以下示例中，我们将配置系统文本始终以海盗的声音回答。为了避免在运行时代码中重复系统文本，我们将在@Configuration类中创建一个ChatClient实例。

@Configuration
class Config {
    @Bean
    ChatClient chatClient (ChatClient.Builder builder) {
        return builder.defaultSystem("你是一个友好的聊天机器人，用海盗的声音回答问题")
            .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 = "给我讲个笑话") String message) {
        return Map.of("completion", this.chatClient.prompt().user(message).call().content());
    }
}

当通过curl调用应用程序端点时，结果是:

❯ curl localhost:8080/ai/simple
{"completion":"为什么海盗去喜剧俱乐部?为了听一些 arrr-rated 笑话!啊，伙计!"}

带参数的默认系统文本​

在以下示例中，我们将在系统文本中使用占位符，以便在运行时而不是设计时指定完成的声音。

@Configuration
class Config {
    @Bean
    ChatClient chatClient (ChatClient.Builder builder) {
        return builder.defaultSystem("你是一个友好的聊天机器人，用{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 = "给我讲个笑话") 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": "你在跟我说话吗?好吧，给你讲个笑话:为什么自行车不能自己站起来?因为它太累了!经典，对吧?"
}

其他默认值​

在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 实现通过将提示附加与用户文本相关的上下文信息来启用 Retrieval Augmented Generation 模式。
  • defaultAdvisors(Consumer<AdvisorSpec> advisorSpecConsumer): 此方法允许您定义一个Consumer来使用AdvisorSpec配置多个 advisors。Advisors 可以修改用于创建最终 Prompt 的数据。Consumer<AdvisorSpec>让您指定一个 lambda 来添加 advisors，如QuestionAnswerAdvisor，它通过将提示附加基于用户文本的相关上下文信息来支持Retrieval Augmented Generation。

您可以在运行时使用不带 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接口用于配置 advisors。这个接口提供了添加参数、一次性设置多个参数以及向链中添加一个或多个 advisors 的方法。

interface AdvisorSpec {
    AdvisorSpec param(String k, Object v);
    AdvisorSpec params(Map<String, Object> p);
    AdvisorSpec advisors(Advisor... advisors);
    AdvisorSpec advisors(List<Advisor> advisors);
}

重要: 将 advisors 添加到链中的顺序至关重要，因为它决定了它们的执行顺序。每个 advisor 都以某种方式修改提示或上下文，一个 advisor 所做的更改会传递给链中的下一个。

ChatClient.builder(chatModel)
    .build()
    .prompt()
    .advisors(
        MessageChatMemoryAdvisor.builder(chatMemory).build(),
        QuestionAnswerAdvisor.builder(vectorStore).build()
    )
    .user(userText)
    .call()
    .content();

在此配置中，MessageChatMemoryAdvisor将首先执行，将对话历史添加到提示中。然后，QuestionAnswerAdvisor将基于用户的问题和添加的对话历史执行其搜索，可能提供更相关的结果。

检索增强生成请参阅检索增强生成指南。

日志记录​

SimpleLoggerAdvisor是一个记录ChatClient的request和response数据的 advisor。这对于调试和监控您的 AI 交互很有用。

提示: Spring AI 支持 LLM 和向量存储交互的可观察性。有关更多信息，请参阅可观察性指南。

要启用日志记录，在创建 ChatClient 时将SimpleLoggerAdvisor添加到 advisor 链中。建议将其添加到链的末尾:

ChatResponse response = ChatClient.create(chatModel).prompt()
    .advisors(new SimpleLoggerAdvisor())
    .user("给我讲个笑话?")
    .call()
    .chatResponse();

要查看日志，将 advisor 包的日志级别设置为DEBUG:

logging.level.org.springframework.ai.chat.client.advisor=DEBUG

将此添加到您的application.properties或application.yaml文件中。

您可以通过使用以下构造函数自定义从AdvisedRequest和ChatResponse记录的哪些数据:

SimpleLoggerAdvisor(
    Function<AdvisedRequest, String> requestToString,
    Function<ChatResponse, String> responseToString
)

使用示例:

SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
    request -> "自定义请求:" + request.userText,
    response -> "自定义响应:" + response.getResult()
);

这允许您根据特定需求定制记录的信息。

提示: 在生产环境中要小心记录敏感信息。

聊天内存​

ChatMemory接口表示聊天对话内存的存储。它提供了向对话添加消息、从对话中检索消息以及清除对话历史的方法。目前有一个内置实现:MessageWindowChatMemory。

MessageWindowChatMemory是一个聊天内存实现，它维护一个最大指定大小(默认:20 条消息)的消息窗口。当消息数量超过此限制时，较旧的消息会被逐出，但系统消息会被保留。如果添加了新的系统消息，所有以前的系统消息都会从内存中删除。这确保了对话始终有最新的上下文可用，同时保持内存使用有界。

MessageWindowChatMemory由ChatMemoryRepository抽象支持，它提供了聊天对话内存的存储实现。有几种实现可用，包括InMemoryChatMemoryRepository、JdbcChatMemoryRepository、CassandraChatMemoryRepository和Neo4jChatMemoryRepository。

有关更多详细信息和用法示例，请参阅聊天内存文档。

实现说明​

ChatClient中命令式和响应式编程模型的组合使用是 API 的一个独特方面。通常，应用程序要么是响应式的，要么是命令式的，但不是两者都是。

  • 当自定义 Model 实现的 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 spans 和工具调用 spans 没有连接，第一个因此保持不完整)。
  • 内置的 advisors 对标准调用执行阻塞操作，对流式调用执行非阻塞操作。用于 advisor 流式调用的 Reactor Scheduler 可以通过每个 Advisor 类上的 Builder 进行配置。
Last updated on by ken.lj

Spring AI Alibaba 开源项目基于 Spring AI 构建，是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践，提供高层次的 AI API 抽象与云原生基础设施集成方案，帮助开发者快速构建 AI 应用。