首页 › Spring AI › ChatClient 与 Prompt 工程

ChatClient 是 Spring AI 中最核心的接口，封装了与 LLM 的所有交互。

ChatClient 的创建

// 方式一：使用 Builder（推荐）
@Configuration
public class AIConfig {
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
            .defaultSystem("You are a helpful Java developer assistant")
            .build();
    }
}

// 方式二：每次调用时创建（适合不同角色）
ChatClient.Builder builder = ...
ChatClient client = builder.build();

基本调用

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    // 最简调用：文本输入 → 文本输出
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.call(message);
    }

    // 带系统指令的调用
    @GetMapping("/translate")
    public String translate(@RequestParam String text) {
        return chatClient.call(new Prompt(
            new SystemMessage("Translate the following to Chinese:"),
            new UserMessage(text)
        )).getResult().getOutput().getContent();
    }
}

Prompt 调用方式

call() 方法支持多种入参：

// 1. String → String（最简）
String response = chatClient.call("Hello");

// 2. Prompt → ChatResponse
ChatResponse response = chatClient.call(
    new Prompt("Generate a haiku")
);
String content = response.getResult().getOutput().getContent();
Generation generation = response.getResult();

// 3. Prompt 带参数
ChatResponse response = chatClient.call(
    new Prompt(
        List.of(
            new SystemMessage("You are a poet"),
            new UserMessage("Write a poem about spring")
        ),
        ChatOptionsBuilder.builder()
            .withTemperature(0.8)
            .withMaxTokens(200)
            .build()
    )
);

ChatResponse 结构

ChatResponse response = chatClient.call(new Prompt("Say hello"));

// 响应结构
response.getResult()           // Generation
response.getResult().getOutput()    // AssistantMessage
response.getResult().getOutput().getContent()  // 文本内容
response.getMetadata()               // 元数据（Token 用量等）

// Token 用量
ChatResponseMetadata metadata = response.getMetadata();
Usage usage = metadata.getUsage();
usage.getPromptTokens();       // 输入 Token 数
usage.getGenerationTokens();   // 输出 Token 数
usage.getTotalTokens();        // 总 Token 数

默认配置

在 Builder 中设置全局默认值：

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
        .defaultSystem("You are a helpful AI assistant")
        .defaultOptions(ChatOptionsBuilder.builder()
            .withTemperature(0.7)
            .withMaxTokens(500)
            .build())
        .build();
}

测试

@SpringBootTest
class AIControllerTest {
    @Autowired
    private ChatClient chatClient;

    @Test
    void testBasicChat() {
        String response = chatClient.call("Count from 1 to 3");
        assertNotNull(response);
        System.out.println(response);
    }
}

小结

• ChatClient 是 Spring AI 的核心对话接口，通过 Builder 创建。
• call(String) 最简调用；call(Prompt) 支持完整 Prompt 和参数控制。
• ChatResponse 包含 Generation（回复）和 Metadata（Token 用量）。
• Builder 的 defaultSystem() 和 defaultOptions() 设置全局默认值。
• 切换模型提供商无需更改调用代码，只需改 Starter 和配置。

上一节：第一个 Spring AI 应用 下一节：Prompt 模板

贡献者: 布欧-Lewyon