这一篇要解决一个很具体的问题:为什么你在 Playground 里跑得好好的提示词,搬进 Spring Boot 之后就开始出错、报异常、或者更糟——不报错但结果是错的。
原因是提示词进入 Java 之后,它不再是"一段话",而是变成了字符串模板 + 类型契约 + 解析器这三样东西的组合。任何一个环节没对齐,故障就来了,而且四类故障的表现完全不同:
| 环节 | 典型故障 | 什么时候暴露 |
|---|---|---|
| 模板渲染 | IllegalArgumentException: The template string is not valid. |
第一次调用,5xx |
| 变量注入 | 提示词里出现 null 或 ab 这种残字 |
运行期,结果错但不报错 |
| 系统提示词拼装 | 预算超了,最后一条约束被截掉 | 线上效果悄悄变差 |
| 结构化输出解析 | RuntimeException 且 getMessage() == null |
模型换了/升级了才出现 |
下面按这四段的顺序讲,每段都给可跑的代码。文中的结论都来自对 Spring AI 1.1.8 的实测(反编译 + 运行时探针),不是文档转述——因为文档在这一点上讲得很含糊,而这些细节恰好决定了你会不会踩坑。
一、模板的第一次爆炸:你不能在模板里写 JSON 示例
先看一行看起来完全正常的代码:
PromptTemplate pt = new PromptTemplate("请输出 {\"intent\":\"refund_status\"} 这样的 JSON");
运行结果:
java.lang.IllegalArgumentException: The template string is not valid.
点开堆栈,根因是 org.stringtemplate.v4.compiler.STException,而它的 getMessage() 是 null。也就是说:日志里除了"模板字符串不合法"这七个字,什么线索都没有。这是本篇最值钱的一条经验——这类错误的成本不在修,在定位。
为什么会这样
Spring AI 1.x 的 PromptTemplate 默认渲染器是 StTemplateRenderer(StringTemplate 4 的封装),构造时是:
// PromptTemplate 的静态初始化,反编译原文
DEFAULT_TEMPLATE_RENDERER = StTemplateRenderer.builder().build();
// builder 默认值:startDelimiter='{' (123)、endDelimiter='}' (125)、ValidationMode.THROW
分隔符是 {
和 }。于是模板里的每一个左花括号都被当成"变量引用"的开始,而 {"intent":"refund_status"} 里花括号后面的内容 "intent":"refund_status" 根本不是合法的变量名——解析器直接罢工。
JSON 和模板语法撞车了,这是设计上的必然,不是 bug。
我把常见写法全试了一遍
为了不靠猜,我写了个探针,把 20 种写法挨个渲染,结果如下:
| 模板写法 | 结果 |
|---|---|
这是集合 { 左括号 |
❌ 抛异常(未闭合) |
{"intent":"refund"} |
❌ 抛异常 |
{
{"intent":"refund"}} |
⚠️ 渲染成 "intent":"refund" —— 外层大括号被静默吃掉 |
\{literal\} |
✅ 渲染成 {literal},反斜杠转义有效 |
{schema}(值是 JSON 字符串) |
✅ 原样输出,变量值不参与二次解析 |
{a.b} |
❌ cannot have '.' in attribute names |
价格 $100、增长 50%、<b>粗体</b> |
✅ 都是普通字符,不用转义 |
{userName} 但没传变量 |
❌ IllegalStateException: Not all variables were replaced... |
两条被广泛误传的说法可以纠正了:$ 不需要转义(那是 StringTemplate 3 时代的经验),{
{ }} 也不是转义语法——它不会报错,但会悄悄改掉你的内容,比报错更危险。
三条可行路线,按推荐顺序
路线一(首选):把 JSON 当变量传。
@Component
public class RefundIntentPrompt {
private final BeanOutputConverter<RefundIntent> converter =
new BeanOutputConverter<>(RefundIntent.class);
/** 模板里只有 {schema} 和 {question},一个裸花括号都没有。 */
public String render(String question) {
return PromptTemplate.builder()
.template("""
请把用户的话转成结构化结果。
必须严格符合以下 JSON Schema:
{schema}
用户原话:
{question}""")
.variables(Map.of(
"schema", converter.getJsonSchema(), // JSON 字符串,含大量花括号
"question", question))
.build()
.render();
}
}
关键在于变量值是替换进去的,不会再被解析一遍。所以 getJsonSchema() 里那几十个花括号全部安全。这一条是整篇的地基:它同时解决了"不能写 JSON"和"schema 会随类型变化"两个问题——schema 由 RefundIntent 这个类型推导出来,改字段就自动同步,不用手工维护一份容易过期的示例。
路线二:反斜杠转义。 适合少量、固定的字面量:
public static String escape(String literal) {
return literal.replace("{", "\\{").replace("}", "\\}");
}
// "输出 {\"intent\":\"refund\"}" → 渲染后得到一字不差的原串
路线三:换分隔符。 StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>'),实测可行。但代价是整个正文里不能再出现 < 和 >——对写 HTML 片段、泛型签名的地方是灾难。不建议作为默认方案,只在"模板里既有大量 JSON 又有少量变量"的极端场景考虑。
顺手两个静默陷阱
这两个不报错,但结果错,属于最难查的一类。
陷阱 A:null 变量渲染成空字符串。
Map<String, Object> vars = new HashMap<>();
vars.put("orderNo", null);
new PromptTemplate("订单号:{orderNo}").render(vars); // → "订单号:"
模型收到的是"订单号:"后面什么都没有。它既不会报错,也不会告诉你少了个参数——它会自己编一个订单号补上。所以变量组装那一层必须做 Assert.notNull,或者在渲染前统一校验:
vars.forEach((k, v) -> Assert.notNull(v, "提示词变量 " + k + " 不能为 null,缺值请显式传空串"));
陷阱 B:集合变量不会自动加分隔符。
new PromptTemplate("items={list}").render(Map.of("list", List
328



被折叠的 条评论
为什么被折叠?



