[AI工程] Spring AI 第七篇:结构化输出与初代 Tools 实现

用户："帮我退掉订单 XK3921"   ↓自由文本："好的，已为您查询到订单 XK3921..."   ❌ 代码无法判定下一步   ↓结构化输出：{"jobType":"CANCEL","keyInfos":[{"name":"张三","bookingCode":"XK3921"}]}   ✅ → Job 对象 → switch(jobType)

.stream() --> 一段段文本分片 --> 拼不出完整 JSON --> 无法反序列化成 T.call()   --> 一次拿到完整响应 --> 生成 / 校验 Schema --> T

Boolean needHuman = chatClient.prompt()        .system("你是客服意图审核器。只输出 true 或 false，不要任何解释。")        .user("判断下面的用户输入是否需要人工客服介入：" + message)        .call()        .entity(Boolean.class);if (Boolean.TRUE.equals(needHuman)) {    return transferToHuman(message);}

public class AiJob {    public enum JobType { CANCEL, QUERY, OTHER }    public record Job(            @JsonPropertyDescription("任务类型：CANCEL 退票、QUERY 查票、OTHER 其他闲聊")            JobType jobType,            @JsonPropertyDescription("从对话中提取的关键信息；用户没有提供则返回空数组")            List<KeyInfo> keyInfos    ) {}    public record KeyInfo(            @JsonPropertyDescription("乘客姓名") String name,            @JsonPropertyDescription("预定号 / 订单号") String bookingCode    ) {}}

AiJob.Job job = planningChatClient.prompt()        .user(message)        .call()        .entity(AiJob.Job.class);switch (job.jobType()) {    case CANCEL -> refundService.cancel(job.keyInfos());    case QUERY  -> ticketService.query(job.keyInfos());    case OTHER  -> chatService.reply(message);}

{  "jobType": "CANCEL",  "keyInfos": [{ "name": "张三", "bookingCode": "XK3921" }]}

List<AiJob.Job> jobs = chatClient.prompt()        .user("把下面这段话拆成多个独立任务：" + message)        .call()        .entity(new ParameterizedTypeReference<List<AiJob.Job>>() {});

ResponseEntity<ChatResponse, AiJob.Job> result = chatClient.prompt()        .user(message)        .call()        .responseEntity(AiJob.Job.class);AiJob.Job job = result.entity();long totalTokens = result.response().getMetadata().getUsage().getTotalTokens();

AiJob.Job job = planningChatClient.prompt()        .user(message)        .call()        .entity(AiJob.Job.class, spec -> spec                .useProviderStructuredOutput()   // 走厂商原生 JSON 模式                .validateSchema());              // 本地 Schema 校验 + 失败重试

① 目标类型 Job.class   ↓ Jackson 注解 + 字段类型② 生成 JSON Schema   ↓ 两种下发方式③ 附加到请求：response_format 参数  |  拼进系统提示词   ↓④ 模型返回 JSON   ↓⑤ validateSchema? --否--> 直接反序列化（畸形就抛异常）   ↓ 是⑥ Schema 校验 --不通过--> 错误信息回填 prompt --> 重试（≤3 次）   ↓ 通过⑦ 反序列化为 AiJob.Job

不写描述  --> 模型：不知道什么时候该返回空数组，于是开始编订单号写了描述  --> 模型：用户没给预定号就返回 []，代码才能判断"信息不全，要追问"

var converter = new BeanOutputConverter<>(AiJob.Job.class);String prompt = """        你是票务任务路由器。        %s        用户输入：%s        """.formatted(converter.getFormat(), message);ChatResponse response = chatModel.call(new Prompt(prompt));AiJob.Job job = converter.convert(response.getResult().getOutput().getText());

用户输入   ↓planningChatClient ──.entity(AiJob.Job)──> { jobType, keyInfos }   ↓ CANCEL ──> 信息齐全？──> 是 ──> 调 refundService（本地业务方法）   ↓                        └── 否 ──> 追问"请输入姓名和订单号"   ↓ QUERY  ──> 调 ticketService   ↓ OTHER  ──> botChatClient ──.stream()──> 流式回复

@Configurationpublic class AiConfig {    @Bean    public ChatClient planningChatClient(DashScopeChatModel chatModel,                                         DashScopeChatProperties options,                                         ChatMemory chatMemory) {        DashScopeChatOptions dashScopeChatOptions = DashScopeChatOptions.fromOptions(options.getOptions());        dashScopeChatOptions.setTemperature(0.7);        return ChatClient.builder(chatModel)                .defaultSystem("""                        # 票务助手任务拆分规则                        ## 1.要求                        ### 1.1 根据用户内容识别任务                        ## 2. 任务                        ### 2.1 JobType:退票(CANCEL) 要求用户提供姓名和预定号，或者从对话中提取；                        ### 2.2 JobType:查票(QUERY) 要求用户提供预定号，或者从对话中提取；                        ### 2.3 JobType:其他(OTHER)                        """)                .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())                .defaultOptions(dashScopeChatOptions)                .build();    }    @Bean    public ChatClient botChatClient(DashScopeChatModel chatModel,                                    DashScopeChatProperties options,                                    ChatMemory chatMemory) {        DashScopeChatOptions dashScopeChatOptions = DashScopeChatOptions.fromOptions(options.getOptions());        dashScopeChatOptions.setTemperature(1.2);        return ChatClient.builder(chatModel)                .defaultSystem("你是XS航空智能客服代理，请以友好的语气服务用户。")                .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())                .defaultOptions(dashScopeChatOptions)                .build();    }}

@RestControllerpublic class MultiModelsController {    @Autowired    ChatClient planningChatClient;    @Autowired    ChatClient botChatClient;    @GetMapping(value = "/stream", produces = "text/stream;charset=UTF8")    Flux<String> stream(@RequestParam String message) {        Sinks.Many<String> sink = Sinks.many().unicast().onBackpressureBuffer();        sink.tryEmitNext("正在计划任务...<br/>");        new Thread(() -> {            // 2.0：.entity() 只能挂在 .call() 上            AiJob.Job job = planningChatClient.prompt()                    .user(message)                    .call()                    .entity(AiJob.Job.class);            switch (job.jobType()) {                case CANCEL -> {                    if (job.keyInfos().isEmpty()) {                        sink.tryEmitNext("请输入姓名和订单号.");                    } else {                        // 真正的业务方法：票务数据在我们系统里                        sink.tryEmitNext(ticketService.cancel(job.keyInfos()));                    }                    sink.tryEmitComplete();                }                case QUERY -> {                    sink.tryEmitNext(ticketService.query(job.keyInfos()));                    sink.tryEmitComplete();                }                case OTHER -> {                    botChatClient.prompt()                            .user(message)                            .stream()                            .content()                            .doOnNext(sink::tryEmitNext)                            .doOnComplete(sink::tryEmitComplete)                            .doOnError(err -> sink.tryEmitError(err))                            .subscribe();                }                default -> {                    sink.tryEmitNext("解析失败");                    sink.tryEmitComplete();                }            }        }).start();        return sink.asFlux();    }}

用户：你好，你们航班的餐食有素食吗？后端：planning → { jobType: "OTHER", keyInfos: [] }输出：正在计划任务... 您好！我们提供素食餐，需在起飞前 24 小时预订……（流式）用户：我要退票后端：planning → { jobType: "CANCEL", keyInfos: [] }输出：请输入姓名和订单号.用户：张三，XK3921后端：planning（带记忆）→ { jobType: "CANCEL", keyInfos: [{name:"张三",bookingCode:"XK3921"}] }输出：退票成功!

Flux.defer(() -> {    AiJob.Job job = planningChatClient.prompt().user(message).call().entity(AiJob.Job.class);    return route(job);}).subscribeOn(Schedulers.boundedElastic());

初代 Tools    ：模型输出 Job --> Java switch --> Java 调方法     （路由在代码里）Tool Calling  ：模型输出 tool_calls --> 框架反射调用 @Tool 方法  （路由在模型手里）MCP           ：模型 + 外部进程提供的工具 --> 客户端动态发现