6. Spring AI 核心概念

String response = chatClient.prompt()
        .system("你是一个资深的 Java 开发程序员")
        .user("什么是 Spring Boot？")
        .call()
        .content();

package com.albertstack.aichat.config;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AiConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.build();
    }
}

package com.albertstack.aichat.ai;

import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.messages.Message;
import org.springframework.ai.chat.messages.SystemMessage;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.model.Generation;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import reactor.test.StepVerifier;

import java.util.List;

import lombok.extern.slf4j.Slf4j;

import static org.junit.jupiter.api.Assertions.*;

@Slf4j
@SpringBootTest
class ChatClientTest {

    @Autowired
    private ChatClient chatClient;

    @Autowired
    private ChatModel chatModel;

    /**
     * 打印 ChatResponse 的完整信息（回复内容 + 思考过程 + 元数据）
     */
    private void logChatResponse(String label, ChatResponse response) {
        Generation result = response.getResult();

        // 回复内容
        log.info("[{}] 回复: {}", label, result.getOutput().getText());

        // 思考过程（部分模型如 qwen3、deepseek-r1 支持，存放在 Generation 的 metadata 中）
        Object thinking = result.getMetadata().get("thinking");
        if (thinking != null && !thinking.toString().isBlank()) {
            log.info("[{}] 思考过程: {}", label, thinking);
        }

        // 模型元数据
        log.info("[{}] 模型: {}", label, response.getMetadata().getModel());
    }

    // ========== 同步调用 ==========

    @Test
    void call_shouldReturnNonEmptyResponse() {
        String userMsg = "用一句话解释什么是 Java";
        log.info("---------- 同步调用（基础） ----------");
        log.info("[提问] {}", userMsg);

        ChatResponse response = chatClient.prompt()
                .user(userMsg)
                .call()
                .chatResponse();

        assertNotNull(response.getResult());
        logChatResponse("同步调用", response);
        log.info(" ✅ 同步调用成功");
    }

    @Test
    void call_withSystemMessage_shouldFollowInstruction() {
        String systemMsg = "你是一个简洁的助手，回答不超过20个字";
        String userMsg = "什么是 Spring Boot？";
        log.info("---------- 同步调用（系统提示词） ----------");
        log.info("[系统] {}", systemMsg);
        log.info("[提问] {}", userMsg);

        ChatResponse response = chatClient.prompt()
                .system(systemMsg)
                .user(userMsg)
                .call()
                .chatResponse();

        assertNotNull(response.getResult());
        logChatResponse("简洁模式", response);
        log.info(" ✅ 系统提示词生效");
    }

    // ========== 流式调用 ==========

    @Test
    void stream_shouldEmitMultipleChunks() {
        String userMsg = "用三句话介绍 Spring AI";
        log.info("---------- 流式调用 ----------");
        log.info("[提问] {}", userMsg);

        var flux = chatClient.prompt()
                .user(userMsg)
                .stream()
                .chatResponse();

        StringBuilder content = new StringBuilder();
        StringBuilder thinking = new StringBuilder();
        int[] chunkCount = {0};
        boolean[] thinkingPhase = {true};

        StepVerifier.create(flux)
                .thenConsumeWhile(chunk -> {
                    Generation result = chunk.getResult();
                    if (result == null || result.getOutput() == null) return true;

                    chunkCount[0]++;

                    // 思考过程：逐 chunk 实时输出
                    Object reason = result.getMetadata().get("thinking");
                    if (reason != null && !reason.toString().isEmpty()) {
                        if (thinkingPhase[0] && thinking.isEmpty()) {
                            System.out.print("[思考] ");
                        }
                        System.out.print(reason);
                        System.out.flush();
                        thinking.append(reason);
                    }

                    // 回复内容：逐 chunk 实时输出
                    String text = result.getOutput().getText();
                    if (text != null && !text.isEmpty()) {
                        if (thinkingPhase[0]) {
                            thinkingPhase[0] = false;
                            System.out.println();
                            System.out.print("[回复] ");
                        }
                        System.out.print(text);
                        System.out.flush();
                        content.append(text);
                    }

                    return true;
                })
                .verifyComplete();

        System.out.println();
        log.info("[流式] 共接收 {} 个 chunk（思考: {} 字符，回复: {} 字符）",
                chunkCount[0], thinking.length(), content.length());
        log.info(" ✅ 流式调用完成");
    }

    // ========== 底层 ChatModel 调用 ==========

    @Test
    void chatModel_call_shouldReturnChatResponse() {
        String userMsg = "1 + 1 等于几？只回答数字";
        log.info("---------- ChatModel 底层调用 ----------");
        log.info("[提问] {}", userMsg);

        Prompt prompt = new Prompt(List.of(new UserMessage(userMsg)));
        ChatResponse response = chatModel.call(prompt);

        assertNotNull(response);
        assertNotNull(response.getResult());
        logChatResponse("ChatModel", response);
        log.info(" ✅ ChatModel 底层调用成功");
    }

    // ========== 多轮对话 ==========

    @Test
    void multiTurn_shouldMaintainContext() {
        log.info("---------- 多轮对话 ----------");

        // 第一轮
        String systemMsg = "你是一个数学助手";
        String firstUserMsg = "我叫 Albert，请记住我的名字";
        log.info("[系统] {}", systemMsg);
        log.info("[第一轮提问] {}", firstUserMsg);

        List<Message> messages = List.of(
                new SystemMessage(systemMsg),
                new UserMessage(firstUserMsg)
        );

        ChatResponse firstResponse = chatModel.call(new Prompt(messages));
        String firstReply = firstResponse.getResult().getOutput().getText();
        logChatResponse("第一轮", firstResponse);

        // 第二轮：带上历史消息
        String secondUserMsg = "我叫什么名字？";
        log.info("[第二轮提问] {}", secondUserMsg);

        List<Message> secondMessages = List.of(
                new SystemMessage(systemMsg),
                new UserMessage(firstUserMsg),
                new AssistantMessage(firstReply),
                new UserMessage(secondUserMsg)
        );

        ChatResponse secondResponse = chatModel.call(new Prompt(secondMessages));
        String secondReply = secondResponse.getResult().getOutput().getText();
        logChatResponse("第二轮", secondResponse);

        assertTrue(secondReply.contains("Albert"), "AI 应该记住用户的名字，实际回复: " + secondReply);
        log.info(" ✅ 多轮对话上下文保持正确");
    }
}

chatClient.prompt().user("hello").call().content()

chatClient.prompt().user("hello").stream().chatResponse()

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: qwen3.5:9b # 默认模型（带思考）

# 自定义配置
ai:
  model:
    no-think: frob/qwen3.5-instruct:9b
  prompt:
    default: classpath:prompts/default.txt
    no-think: classpath:prompts/no-think.txt

你是一个严谨的AI助手，请严格遵循以下规则：

【事实性要求】
- 只能基于已知信息或合理推断回答问题
- 不允许编造、虚构或猜测事实
- 若信息不足，请明确说明"无法确定"或"需要更多信息"

【表达要求】
- 使用简洁、清晰、专业的中文回答
- 避免冗余、废话和重复内容
- 优先给出结论，再补充必要解释

【风格要求】
- 保持客观、中立、技术导向
- 不使用情绪化表达或迎合性语言

请按照以上规则回答用户问题。

你是一个高效的AI助手，请严格遵循以下规则：

【核心要求】
- 直接给出结论，不展示推理过程
- 不编造事实，不确定时直接说明

【表达要求】
- 使用简洁、清晰的中文
- 控制输出长度，避免冗余解释

【行为约束】
- 不输出思考过程
- 不进行不必要的扩展分析

请直接回答用户问题。

package com.albertstack.aichat.config;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.ollama.api.OllamaChatOptions;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.Resource;

import java.io.IOException;
import java.nio.charset.StandardCharsets;

@Configuration
public class AiConfig {

    @Value("${ai.model.no-think}")
    private String noThinkModel;

    @Value("${ai.prompt.default}")
    private Resource defaultPrompt;

    @Value("${ai.prompt.no-think}")
    private Resource noThinkPrompt;

    /**
     * 默认 ChatClient（使用 yaml 中配置的默认模型，带思考）
     */
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) throws IOException {
        return builder
                .defaultSystem(defaultPrompt.getContentAsString(StandardCharsets.UTF_8))
                .build();
    }

    /**
     * 无思考 ChatClient（使用 instruct 模型，跳过推理过程）
     */
    @Bean
    public ChatClient noThinkChatClient(ChatClient.Builder builder) throws IOException {
        return builder
                .defaultSystem(noThinkPrompt.getContentAsString(StandardCharsets.UTF_8))
                .defaultOptions(OllamaChatOptions.builder()
                        .model(noThinkModel)
                        .build())
                .build();
    }
}

@Autowired
private ChatClient chatClient; // 带思考，适合复杂问题

@Autowired
private ChatClient noThinkChatClient; // 无思考，适合简单问答

// 复杂问题 -> 用带思考的模型
String deepAnswer = chatClient.prompt()
        .user("证明根号2是无理数")
        .call()
        .content();

// 简单问答 -> 用无思考的模型，响应更快
String quickAnswer = noThinkChatClient.prompt()
        .user("1 + 1 等于几？")
        .call()
        .content();

ChatResponse response = chatClient.prompt()
        .user("证明根号2是无理数")
        .call()
        .chatResponse();

String reply = response.getResult().getOutput().getText();

// 思考过程（仅思考模型支持，instruct 模型此处为 null）
Object thinking = response.getResult().getMetadata().get("thinking");
if (thinking != null && !thinking.toString().isBlank()) {
    log.info("思考过程: {}", thinking);
}

import org.springframework.ai.chat.prompt.PromptTemplate;

// 定义模板（使用 {变量名} 占位）
PromptTemplate template = new PromptTemplate(
        "请将以下内容翻译成{language}：\n\n{content}"
);

// 填充变量并生成 Prompt
Prompt prompt = template.create(Map.of(
        "language", "英文",
        "content", "Spring AI 是一个很棒的框架"
));

// 调用
String result = chatClient.prompt(prompt).call().content();

请将以下内容翻译成{language}：

{content}

要求：
- 保持原文的技术术语不翻译
- 翻译要自然流畅

PromptTemplate template = new PromptTemplate(
        new ClassPathResource("prompts/translate.st")
);

package com.albertstack.aichat.ai;

import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.model.Generation;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

import java.util.Map;

import lombok.extern.slf4j.Slf4j;

import static org.junit.jupiter.api.Assertions.*;

@Slf4j
@SpringBootTest
class PromptTipsTest {

    @Autowired
    private ChatClient chatClient; // 默认模型（带思考）

    @Autowired
    private ChatClient noThinkChatClient; // instruct 模型（无思考）

    // ========== 思考模式切换 ==========

    @Test
    void thinkModel_shouldIncludeThinkingProcess() {
        String userMsg = "证明 1 + 1 = 2 的基本思路是什么？用两句话概括";
        log.info("---------- 带思考模型 ----------");
        log.info("[提问] {}", userMsg);

        ChatResponse response = chatClient.prompt()
                .user(userMsg)
                .call()
                .chatResponse();

        Generation result = response.getResult();
        assertNotNull(result);

        String reply = result.getOutput().getText();
        log.info("[回复] {}", reply);

        // 思考模型应包含推理过程
        Object thinking = result.getMetadata().get("thinking");
        boolean hasThinking = thinking != null && !thinking.toString().isBlank();
        log.info("[思考过程] {}", hasThinking ? "有（" + thinking.toString().length() + " 字符）" : "（无）");

        assertTrue(hasThinking, "带思考的模型应返回思考过程");
        log.info(" ✅ 思考模型验证通过");
    }

    @Test
    void noThinkModel_shouldSkipThinkingProcess() {
        String userMsg = "1 + 1 等于几？只回答数字";
        log.info("---------- 无思考模型 ----------");
        log.info("[提问] {}", userMsg);

        ChatResponse response = noThinkChatClient.prompt()
                .user(userMsg)
                .call()
                .chatResponse();

        Generation result = response.getResult();
        assertNotNull(result);

        String reply = result.getOutput().getText();
        log.info("[回复] {}", reply);

        // instruct 模型不应有思考过程
        Object thinking = result.getMetadata().get("thinking");
        boolean hasThinking = thinking != null && !thinking.toString().isBlank();
        log.info("[思考过程] {}", hasThinking ? thinking : "（无）");

        assertFalse(hasThinking, "无思考模型不应返回思考过程");
        log.info(" ✅ 无思考模型验证通过");
    }

    // ========== System Prompt 设计原则 ==========

    @Test
    void systemPrompt_shouldConstrainResponseFormat() {
        String systemPrompt = """
                你是一个 JSON 格式化助手，遵循以下规则：
                1. 只输出合法的 JSON，不要输出任何其他内容
                2. 不要用 Markdown 代码块包裹
                3. 如果无法转为 JSON，返回 {"error": "无法处理"}
                """;
        String userMsg = "将以下信息转为 JSON：名称Albert，年龄18，职业程序员";
        log.info("---------- System Prompt 格式约束 ----------");
        log.info("[系统] {}", systemPrompt);
        log.info("[提问] {}", userMsg);

        String reply = chatClient.prompt()
                .system(systemPrompt)
                .user(userMsg)
                .call()
                .content();

        log.info("[回复] {}", reply);

        // 验证回复是合法 JSON 格式（包含关键字段）
        assertTrue(reply.contains("Albert"), "回复应包含姓名信息");
        assertTrue(reply.contains("{") && reply.contains("}"), "回复应为 JSON 格式");
        log.info(" ✅ 系统提示词成功约束了输出格式");
    }

    @Test
    void systemPrompt_shouldLimitScope() {
        String systemPrompt = """
                你是一个 Java 编程助手。
                规则：只回答 Java 编程相关问题，如果用户问的不是编程问题，回复"抱歉，我只能回答编程相关问题"。
                """;
        String userMsg = "今天天气怎么样？";
        log.info("---------- System Prompt 范围限定 ----------");
        log.info("[系统] {}", systemPrompt);
        log.info("[提问] {}", userMsg);

        String reply = chatClient.prompt()
                .system(systemPrompt)
                .user(userMsg)
                .call()
                .content();

        log.info("[回复] {}", reply);

        // AI 应该拒绝回答非编程问题
        assertTrue(reply.contains("编程") || reply.contains("抱歉") || reply.contains("无法"),
                "AI 应拒绝回答非编程问题，实际回复: " + reply);
        log.info(" ✅ 系统提示词成功限定了回答范围");
    }

    // ========== PromptTemplate 模板化提示词 ==========

    @Test
    void promptTemplate_shouldFillVariables() {
        log.info("---------- PromptTemplate 变量填充 ----------");

        PromptTemplate template = new PromptTemplate(
                "请将以下内容翻译成{language}，直接输出译文：\n\n{content}"
        );

        String targetLang = "英文";
        String content = "Spring AI 让 Java 开发者能快速集成大语言模型";
        log.info("[模板变量] language={}, content={}", targetLang, content);

        Prompt prompt = template.create(Map.of(
                "language", targetLang,
                "content", content
        ));

        String reply = chatClient.prompt(prompt).call().content();
        log.info("[翻译结果] {}", reply);

        // 翻译结果应包含英文单词
        assertTrue(reply.matches(".*[a-zA-Z]{3,}.*"),
                "翻译结果应包含英文，实际回复: " + reply);
        log.info(" ✅ PromptTemplate 变量填充并调用成功");
    }

    @Test
    void promptTemplate_multiVariable_shouldGenerateStructuredOutput() {
        log.info("---------- PromptTemplate 多变量结构化 ----------");

        PromptTemplate template = new PromptTemplate(
                "用{language}写一个{function}函数，要求：\n- 函数名：{functionName}\n- 只输出代码，不要解释"
        );

        Prompt prompt = template.create(Map.of(
                "language", "Java",
                "function", "判断一个数是否为质数",
                "functionName", "isPrime"
        ));

        log.info("[生成的 Prompt] {}", prompt.getContents());

        String reply = chatClient.prompt(prompt).call().content();
        log.info("[生成代码]\n{}", reply);

        // 验证生成了包含指定函数名的代码
        assertTrue(reply.contains("isPrime"),
                "生成的代码应包含函数名 isPrime，实际回复: " + reply);
        log.info(" ✅ 多变量模板成功生成结构化代码");
    }
}