Spring AI 2.0 ChatModel 全解析：注入、提示词、多模态与工具调用

// ChatModel 是所有聊天模型的统一入口
public interface ChatModel extends Model<Prompt, ChatResponse> {

    // 简化用法：传字符串直接拿字符串回答
    default String call(String message) {
        // 内部会把 message 包装成 Prompt 再调用下面的方法
        ...
    }

    // 标准用法：接收 Prompt，返回结构化的 ChatResponse
    @Override
    ChatResponse call(Prompt prompt);
}

// 流式接口专门处理逐 token 输出的场景
public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

    default Flux<String> stream(String message) { ... }

    @Override
    Flux<ChatResponse> stream(Prompt prompt);
}

ChatResponse response = chatModel.call(new Prompt("给我讲个 Java 冷笑话"));

// getResult() 取第一个候选输出
String text = response.getResult().getOutput().getContent();

// getMetadata() 可以拿到 token 消耗等元数据（注意返回类型是 Integer，不是 Long）
Integer totalTokens = response.getMetadata().getUsage().getTotalTokens();

@RestController
@RequestMapping("/ai")
public class SimpleAiController {

    // 单模型场景，Spring Boot 已自动配置好，直接注入
    private final ChatModel chatModel;

    public SimpleAiController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/simple")
    public String simple(@RequestParam String message) {
        // call(String) 是最简写法，内部会自动包装为 Prompt
        return chatModel.call(message);
    }
}

@RestController
public class ChatClientController {

    private final ChatClient chatClient;

    // 注入自动配置的 Builder，在构造函数里 build 出可复用的 ChatClient
    public ChatClientController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultSystem("你是一位专业的 Java 开发助手")
                .build();
    }

    @GetMapping("/ai/simple")
    public String chat(@RequestParam String message) {
        return chatClient.prompt().user(message).call().content();
    }
}

@Configuration
public class ChatClientConfig {

    // 基于 OpenAiChatModel 自动配置好的 Bean 创建专属 ChatClient
    @Bean
    public ChatClient openAiChatClient(OpenAiChatModel chatModel) {
        return ChatClient.create(chatModel);
    }

    // 基于 googleGenAiChatClient（google）创建另一个 ChatClient
    @Bean
    public ChatClient googleGenAiChatClient(GoogleGenAiChatModel chatModel) {
        return ChatClient.create(chatModel);
    }
}

@Service
public class ModelRouterService {

    private final ChatClient openAiChatClient;
    private final ChatClient googleGenAiChatClient;

    public ModelRouterService(
            @Qualifier("openAiChatClient") ChatClient openAiChatClient,
            @Qualifier("googleGenAiChatClient") ChatClient googleGenAiChatClient) {
        this.openAiChatClient = openAiChatClient;
        this.googleGenAiChatClient = googleGenAiChatClient;
    }

    public String askByProvider(String provider, String message) {
        // 简单的路由逻辑：按需求选择不同模型
        ChatClient target = "openai".equals(provider) ? openAiChatClient : googleGenAiChatClient;
        return target.prompt().user(message).call().content();
    }
}

@Configuration
public class AiConfig {

    // @Primary：没有指定 Qualifier 时优先注入这个 ChatClient
    @Bean
    @Primary
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("You are a helpful assistant.").build();
    }

    // 专属场景使用的第二个 ChatClient，集中配置工具和顾问
    @Bean
    public ChatClient weatherChatClient(ChatClient.Builder builder) {
        return builder
                .defaultSystem("你是一个专业的气象助手。")
                .defaultTools(new WeatherTool())
                .build();
    }
}

@Configuration
public class MultiModelConfig {

    /**
     * 手动构造第二个 OpenAI 模型的 ChatModel（同一 API Key，不同模型规格）。
     *
     * Spring AI 2.0 中，通过 OpenAiChatOptions 传入 apiKey / model，
     * OpenAiChatModel 内部会基于 Options 字段自动构造专属的 OpenAIClient，
     * 无需手动 new OpenAIClient，也不依赖任何内部工具类。
     */
    @Bean
    public ChatModel secondaryChatModel(
            @Value("${spring.ai.openai.api-key}") String apiKey,
            @Value("${SECONDARY_LLM}") String secondaryModelName) {

        OpenAiChatOptions options = OpenAiChatOptions.builder()
                .apiKey(apiKey)           // 指定 API Key，框架据此创建专属客户端
                .model(secondaryModelName) // 指定模型名称，例如 "gpt-4o-mini"
                .build();

        return OpenAiChatModel.builder()
                .options(options)
                .build();
    }

    @Bean
    public ChatClient secondaryChatClient(@Qualifier("secondaryChatModel") ChatModel chatModel) {
        return ChatClient.create(chatModel);
    }
}

// 方式一：ChatClient.Builder 设置全局默认系统提示词
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultSystem("你是一位专业的 Java 开发助手，擅长使用 Spring 框架")
        .build();

// 方式二：单次请求内联设置系统提示词
String answer = chatClient.prompt()
        .system("请用简洁的语言回答，不超过 100 字")
        .user("什么是依赖注入？")
        .call()
        .content();

// 方式三：使用 Message 对象手动组装 Prompt
Message systemMessage = new SystemMessage("你是一名严谨的技术评审员");
Message userMessage = new UserMessage("评审这段代码是否有并发问题");
Prompt prompt = new Prompt(List.of(systemMessage, userMessage));
ChatResponse response = chatModel.call(prompt);

// {voice} 是占位符，运行时才决定用什么语气回答
String systemText = """
        You are a helpful AI assistant that helps people find information.
        Your name is {name}
        You should reply to the user's request in the style of a {voice}.
        """;

SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemText);
Message systemMessage = systemPromptTemplate.createMessage(
        Map.of("name", "小艾", "voice", "海盗"));

Prompt prompt = new Prompt(List.of(systemMessage, new UserMessage("介绍一下你自己")));
ChatResponse response = chatModel.call(prompt);

// defaultSystem 里预留了 {voice} 占位符
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultSystem("You are a friendly chat bot that answers in the voice of a {voice}")
        .build();

// 每次请求时动态填充 voice 参数
String result = chatClient.prompt()
        .system(sp -> sp.param("voice", "幽默的段子手"))
        .user("讲个程序员笑话")
        .call()
        .content();

// 把默认的 {} 换成 <>，避免和提示词里的 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();

@RestController
@RequestMapping("/ai")
public class MultiModalController {

    private final ChatClient chatClient;

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

    @GetMapping("/vision")
    public String explainImage() {
        // 从 classpath 加载图片资源
        Resource imageResource = new ClassPathResource("/static/image/product.png");

        return chatClient.prompt()
                .user(u -> u.text("请描述这张图片中的商品，并给出适合电商标题的关键词")
                        // 指定图片的 MimeType 和资源来源
                        .media(MimeTypeUtils.IMAGE_PNG, imageResource))
                .call()
                .content();
    }
}

// 使用远程图片 URL 作为多模态输入
UserMessage userMessage = UserMessage.builder()
        .text("这张图片里有几只香蕉？")
        .media(new Media(MimeTypeUtils.IMAGE_PNG,
                URI.create("https://example.com/fruit-bowl.png")))
        .build();

ChatResponse response = chatModel.call(new Prompt(userMessage));

// 加载本地音频文件作为多模态输入
Resource audioResource = new ClassPathResource("speech1.mp3");

UserMessage userMessage = new UserMessage(
        "这段录音在讲什么内容？请总结成 3 个要点",
        // 注意：MP3 的标准 MIME 类型是 audio/mpeg（RFC 3003），而非非标准写法 audio/mp3
        List.of(new Media(MimeTypeUtils.parseMimeType("audio/mpeg"), audioResource)));

// Spring AI 2.0 已移除 OpenAiApi 类，使用字符串指定模型名
ChatResponse response = chatModel.call(new Prompt(
        List.of(userMessage),
        OpenAiChatOptions.builder().model("gpt-4o-audio-preview").build()));

@Service
public class ManualMemoryChatService {

    private final ChatClient chatClient;
    // 简化示例：实际生产环境应按会话 ID 隔离并落库/落缓存
    private final Map<String, List<Message>> sessionHistory = new ConcurrentHashMap<>();

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

    public String chat(String sessionId, String userInput) {
        List<Message> history = sessionHistory.computeIfAbsent(sessionId, k -> new ArrayList<>());

        // 把新的用户消息加入历史
        history.add(new UserMessage(userInput));

        // 把完整历史一并发给模型
        ChatResponse response = chatClient.prompt(new Prompt(history)).call().chatResponse();
        Message assistantMessage = response.getResult().getOutput();

        // 把模型的回复也存入历史，供下一轮使用
        history.add(assistantMessage);
        return assistantMessage.getText();
    }
}

@Configuration
public class ChatMemoryConfig {

    // 存储实现：这里用内存版，生产环境建议换成 JDBC 或 Redis
    @Bean
    public ChatMemoryRepository chatMemoryRepository() {
        return new InMemoryChatMemoryRepository();
    }

    // 窗口管理：只保留最近 20 条消息，超出后自动淘汰旧消息
    @Bean
    public ChatMemory chatMemory(ChatMemoryRepository repository) {
        return MessageWindowChatMemory.builder()
                .chatMemoryRepository(repository)
                .maxMessages(20)
                .build();
    }

    // 把记忆能力以 Advisor 形式挂载到 ChatClient 上
    @Bean
    public ChatClient memoryChatClient(ChatClient.Builder builder, ChatMemory chatMemory) {
        return builder
                .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
                .build();
    }
}

@RestController
@RequestMapping("/ai")
public class MemoryController {

    private final ChatClient chatClient;

    public MemoryController(ChatClient memoryChatClient) {
        this.chatClient = memoryChatClient;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String sessionId, @RequestParam String message) {
        return chatClient.prompt()
                // 通过 conversationId 区分不同用户/会话的历史
                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId))
                .user(message)
                .call()
                .content();
    }
}

@Component
public class WeatherTools {

    // description 至关重要，模型靠它判断何时该调用这个方法
    @Tool(description = "查询指定城市的当前天气")
    public String getCurrentWeather(
            @ToolParam(description = "城市名称，例如：北京") String city) {
        // 真实场景这里应调用天气服务 API
        return "北京当前晴，气温 26 摄氏度";
    }
}

@RestController
public class ToolCallingController {

    private final ChatClient chatClient;
    private final WeatherTools weatherTools;

    public ToolCallingController(ChatClient.Builder builder, WeatherTools weatherTools) {
        this.weatherTools = weatherTools;
        // defaultTools 注册为默认工具，所有请求都可用
        this.chatClient = builder.defaultTools(weatherTools).build();
    }

    @GetMapping("/ai/weather")
    public String ask(@RequestParam String question) {
        return chatClient.prompt().user(question).call().content();
    }
}

// 定义输入输出的强类型 record
record WeatherRequest(String city, String unit) {}
record WeatherResponse(double temperature, String unit) {}

// 用标准 JDK 函数式接口实现业务逻辑
class WeatherService implements Function<WeatherRequest, WeatherResponse> {
    @Override
    public WeatherResponse apply(WeatherRequest request) {
        return new WeatherResponse(25.5, request.unit());
    }
}

// 将 Function 包装为 ToolCallback
ToolCallback weatherTool = FunctionToolCallback.builder("currentWeather", new WeatherService())
        .description("获取指定城市的实时天气")
        .inputType(WeatherRequest.class)
        .build();

String result = chatClient.prompt()
        .user("长沙今天天气怎么样？")
        .tools(weatherTool)
        .call()
        .content();

Method method = ReflectionUtils.findMethod(CalcTools.class, "add", int.class, int.class);

ToolDefinition definition = ToolDefinition.builder()
        .name("add")
        .description("计算两个整数的和")
        .inputSchema("""
                {
                  "type": "object",
                  "properties": {
                    "a": {"type": "integer", "description": "第一个数字"},
                    "b": {"type": "integer", "description": "第二个数字"}
                  },
                  "required": ["a", "b"]
                }
                """)
        .build();

ToolCallback callback = MethodToolCallback.builder()
        .toolDefinition(definition)
        .toolMethod(method)
        .toolObject(new CalcTools())
        .build();

String content = chatClient.prompt()
        .user("100 加 1000 等于多少？")
        .tools(callback)
        .call()
        .content();

// 2.0 中默认即可完整闭环，无需手动处理工具调用往返
String answer = chatClient.prompt()
        .user("帮我查一下上海天气，并换算成华氏度")
        .tools(new WeatherTools())
        .call()
        .content();

@Configuration
public class ToolSearchConfig {

    // 基于向量库对工具描述做语义索引
    @Bean
    public ToolIndex vectorToolIndex(VectorStore vectorStore) {
        return new VectorToolIndex(vectorStore);
    }

    @Bean
    public ToolSearchToolAdvisor toolSearchToolAdvisor(ToolIndex toolIndex) {
        return ToolSearchToolAdvisor.builder()
                .toolSearcher(toolIndex)
                .build();
    }
}

// 将 Advisor 挂载到 ChatClient，不再需要手动传入所有工具
@Bean
public ChatClient chatClient(ChatClient.Builder builder, ToolSearchToolAdvisor advisor) {
    return builder.defaultAdvisors(advisor).build();
}

// 定义目标 Record（Java 16+），用于接收模型返回的结构化数据
record ActorFilms(String actor, List<String> movies) {}

// 方式一：映射到单个 POJO / Record
ActorFilms result = chatClient.prompt()
        .user("生成一位随机演员的代表作品列表")
        .call()
        .entity(ActorFilms.class);

System.out.println(result.actor());  // 例如："周润发"
System.out.println(result.movies()); // 例如：["英雄本色", "赌神", ...]

// 方式二：映射到泛型集合
List<ActorFilms> films = chatClient.prompt()
        .user("分别生成三位不同演员的代表作品列表")
        .call()
        .entity(new ParameterizedTypeReference<List<ActorFilms>>() {});

ActorFilms result = chatClient.prompt()
        .user("生成一位随机演员的代表作品列表")
        .call()
        .entity(ActorFilms.class, spec -> spec
                // 启用模型原生结构化输出（需模型 API 本身支持该能力）
                .useProviderStructuredOutput()
                // 启用 Schema 校验：输出不符合则自动重试，默认最多重试 3 次
                .validateSchema());

// 自动根据 ActorFilms 的字段生成 JSON Schema，并将其注入提示词
BeanOutputConverter<ActorFilms> converter = new BeanOutputConverter<>(ActorFilms.class);

// getFormat() 返回需要追加到提示词中的格式指令
String formatInstructions = converter.getFormat();

PromptTemplate template = new PromptTemplate(
        "生成演员 {actor} 的代表作品列表。{format}",
        Map.of("actor", "成龙", "format", formatInstructions));

Generation generation = chatModel.call(template.create()).getResult();

// convert() 负责把模型返回的 JSON 字符串反序列化为 Java 对象
ActorFilms actorFilms = converter.convert(generation.getOutput().getContent());

// MapOutputConverter：让模型返回 JSON 键值对，解析为 Map
Map<String, Object> info = ChatClient.create(chatModel).prompt()
        .user("以 JSON 格式提供法国的首都和人口")
        .call()
        .entity(new MapOutputConverter());
// 结果形如：{"首都": "巴黎", "人口": 67000000}

// ListOutputConverter：让模型返回逗号分隔的列表，解析为 List
var listConverter = new ListOutputConverter(new DefaultConversionService());
List<String> flavors = ChatClient.create(chatModel).prompt()
        .user(u -> u.text("列出 5 种 {subject}")
                .param("subject", "冰淇淋口味"))
        .call()
        .entity(listConverter);

// ❌ 错误：多模型场景下裸注入，容器无法确定用哪个 Bean
@Autowired
private ChatModel chatModel;

// ✅ 正确：明确指定 Qualifier，意图清晰、编译期可追溯
@Autowired
@Qualifier("dashScopeChatModel")
private ChatModel chatModel;