当前位置：首页 > news >正文

Spring AI 从入门到精通-结构化输出

news 2026/6/8 0:52:40

6. 结构化输出：让 AI 交作业，不是写散文

6.1 问题：AI 输出的是文本，但你要的是对象

AI 默认返回的是自然语言文本。但你的程序需要的是结构化的 Java 对象。怎么办？

// 你想要的是这个recordPerson(Stringname,intage,Stringcity){}// 但 AI 给你的是这个"张三，今年 25 岁，住在北京。他的朋友李四..."

6.2 BeanOutputConverter：文本 → Java Bean

// 1. 定义目标类型recordPerson(Stringname,intage,Stringcity){}// 2. 用 ChatClient 的 entity() 方法Personperson=chatClient.prompt().user("生成一个随机的人物信息").call().entity(Person.class);System.out.println(person.name());// 张三System.out.println(person.age());// 28System.out.println(person.city());// 上海

发生了什么？Spring AI 在后台做了两件事：

根据Person类生成 JSON Schema，追加到 Prompt 后面作为格式指令
拿到 AI 返回的 JSON 后，用 Jackson 反序列化成Person对象

6.3 泛型类型：返回 List

// 返回 List<Person>List<Person>people=chatClient.prompt().user("生成 5 个随机的人物信息").call().entity(newParameterizedTypeReference<List<Person>>(){});people.forEach(p->System.out.println(p.name()+", "+p.age()));

💡ParameterizedTypeReference是什么？因为 Java 在运行时会擦除泛型类型（List<Person>在运行时只是List），Spring AI 需要通过这个匿名内部类的方式拿到实际的泛型参数类型。记住这个写法模板就行，每次需要返回泛型集合时照抄。

6.4 MapOutputConverter：返回 Map

Map<String,Object>result=chatClient.prompt().user(u->u.text("列出 {subject} 的 {count} 个属性，用 JSON 格式").param("subject","一个 Java 开发者的简历").param("count",5)).call().entity(newParameterizedTypeReference<Map<String,Object>>(){});System.out.println(result);// {name=张三, experience=5年, skills=[Java, Spring, MySQL, Redis], ...}

6.5 ListOutputConverter：返回列表

List<String>flavors=chatClient.prompt().user(u->u.text("列出 {count} 种 {subject}").param("count",10).param("subject","冰淇淋口味")).call().entity(newListOutputConverter(newDefaultConversionService()));flavors.forEach(System.out::println);// 巧克力// 香草// 草莓// ...

6.6 Native Structured Output：更可靠的结构化

一些模型（GPT-4o、Claude 3.5 等）原生支持结构化输出。Spring AI 用 Advisor 参数来启用：

Personperson=chatClient.prompt().advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT).user("生成一个随机的人物信息").call().entity(Person.class);

区别：普通模式是在 Prompt 里加"请输出 JSON"，AI 可能不听话。Native 模式是把 JSON Schema 传给模型的原生 API，模型保证输出符合 Schema。

全局启用：

@BeanChatClientchatClient(ChatClient.Builderbuilder){returnbuilder.defaultAdvisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT).build();}

6.7 底层用法：手动使用 BeanOutputConverter

有时候你需要手动控制转换过程：

BeanOutputConverter<Person>converter=newBeanOutputConverter<>(Person.class);Stringformat=converter.getFormat();// 拿到格式指令StringuserTemplate=""" 生成一个随机人物信息。 {format} """;Promptprompt=newPrompt(PromptTemplate.builder().template(userTemplate).variables(Map.of("format",format)).build().createMessage());Generationgeneration=chatModel.call(prompt).getResult();Personperson=converter.convert(generation.getOutput().getText());