Spring AI PromptTemplate插入JSON时花括号冲突怎么办？三种可靠解决方案

原创 29天前 1950

Spring AI PromptTemplate插入JSON时花括号冲突怎么办？三种可靠解决方案

文章摘要

Spring AI默认使用花括号识别Prompt模板变量。当Prompt中包含JSON Schema、示例对象或代码时，JSON自身的 {} 可能被误当成模板变量，导致渲染报错、变量缺失或内容被错误替换。本文通过错误示例，介绍自定义 `` 分隔符、NoOpTemplateRenderer和外部Resource模板三种解决方式，并说明ChatClient模板与Advisor内部模板的作用范围差异。

一、典型问题

Prompt：

String template = """
请根据用户输入返回JSON：

{
  "name": "{name}",
  "age": 18
}
""";

这里存在两类花括号：

JSON对象花括号
模板变量{name}

Spring AI默认模板渲染器使用 {variable} 识别变量。

复杂JSON中可能出现：

把JSON字段误当变量；
提示缺少变量；
Schema渲染失败；
示例对象被修改；
Advisor模板报错。

二、方案一：修改模板变量分隔符

这是最推荐的方法。

使用：

作为变量语法。

import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.ai.template.st.StTemplateRenderer;

PromptTemplate promptTemplate =
        PromptTemplate.builder()
                .renderer(
                        StTemplateRenderer.builder()
                                .startDelimiterToken('')
                                .build()
                )
                .template("""
                        请根据用户信息返回JSON：

                        {
                          "name": "",
                          "department": "",
                          "enabled": true
                        }
                        """)
                .build();

String result = promptTemplate.render(
        Map.of(
                "name", "张三",
                "department", "产品部"
        )
);

JSON花括号保持原样，只有 和 会被替换。

三、在ChatClient中配置自定义Renderer

@Bean
ChatClient jsonFriendlyChatClient(
        ChatModel chatModel
) {
    return ChatClient.builder(chatModel)
            .templateRenderer(
                    StTemplateRenderer.builder()
                            .startDelimiterToken('')
                            .build()
            )
            .build();
}

调用：

String response = chatClient.prompt()
        .user(user -> user
                .text("""
                        把以下信息转换为JSON：

                        {
                          "customer": "",
                          "requirement": ""
                        }
                        """)
                .param(
                        "customer",
                        "某白酒企业"
                )
                .param(
                        "requirement",
                        "渠道动销分析"
                )
        )
        .call()
        .content();

注意：

ChatClient配置的TemplateRenderer只影响直接在ChatClient中定义的user和system模板。

它不会自动修改Advisor内部使用的模板。

四、方案二：不需要模板时使用NoOpTemplateRenderer

如果Prompt已经完整，不需要变量替换：

String prompt = """
请严格返回以下JSON结构：

{
  "status": "SUCCESS",
  "data": {
    "value": 100
  }
}
""";

可以关闭模板渲染：

@Bean
ChatClient noTemplateChatClient(
        ChatModel chatModel
) {
    return ChatClient.builder(chatModel)
            .templateRenderer(
                    NoOpTemplateRenderer.INSTANCE
            )
            .build();
}

适合：

动态字符串已经提前生成；
Prompt中大量JSON；
Prompt由外部系统渲染；
不需要Spring AI变量替换。

缺点是不能再使用 .param(...)。

因此，是否使用NoOp应按客户端用途拆分，不要全局关闭后又期待模板变量生效。

五、方案三：外部Resource模板

将Prompt放到：

src/main/resources/prompts/customer-analysis.st

模板：

你是企业经营分析助手。

客户：
分析周期：

请返回：

{
  "summary": "分析结论",
  "risks": [
    {
      "name": "风险名称",
      "level": "HIGH"
    }
  ]
}

加载：

@Value(
    "classpath:/prompts/customer-analysis.st"
)
private Resource promptResource;

构建：

PromptTemplate template =
        PromptTemplate.builder()
                .resource(promptResource)
                .renderer(
                        StTemplateRenderer.builder()
                                .startDelimiterToken('')
                                .build()
                )
                .build();

String prompt = template.render(
        Map.of(
                "customer",
                "某渠道客户",
                "period",
                "2026年7月"
        )
);

外部文件便于：

版本控制；
代码审查；
单独测试；
多语言；
Prompt复用；
减少Java字符串噪声。

六、为什么不推荐手工转义所有花括号

问题是：

不同模板引擎转义规则不同；
JSON Schema非常长；
可读性差；
容易漏掉嵌套对象；
模板升级后可能失效；
开发者难以区分JSON与变量。

改变变量分隔符通常更清晰。

七、JSON Schema场景

复杂Schema中花括号密集，推荐：

模板变量使用
JSON继续使用{ }

例如：

String template = """
任务：

输出必须符合以下Schema：

{
  "type": "object",
  "properties": {
    "result": {
      "type": "string"
    }
  }
}
""";

八、Advisor内部模板要单独配置

假设你配置了：

ChatClient.builder(chatModel)
        .templateRenderer(customRenderer)

QuestionAnswerAdvisor仍然可能使用自己的模板。

原因是：

ChatClient模板
Advisor内部模板

属于不同作用范围。

自定义RAG模板时，需要在Advisor Builder中设置对应PromptTemplate。

排查方法：

普通user模板是否正常
RAG开启后是否报错
错误是否来自QuestionAnswerAdvisor
Advisor是否有独立模板配置

九、模板变量缺失如何提前发现

不要等到运行时才发现。

可以写单元测试：

class PromptTemplateTest {

    @Test
    void shouldRenderJsonTemplate() {
        PromptTemplate template =
                createTemplate();

        String result = template.render(
                Map.of(
                        "name",
                        "张三"
                )
        );

        assertThat(result)
                .contains("\"name\": \"张三\"");

        assertThat(result)
                .contains("\"enabled\": true");
    }
}

测试：

所有变量可以渲染；
JSON格式保留；
没有未替换变量；
中文和换行正确；
示例代码没有被破坏。

十、检测未替换变量

private static final Pattern UNRESOLVED =
        Pattern.compile("");

public static void validateRenderedPrompt(
        String prompt
) {
    Matcher matcher = UNRESOLVED.matcher(prompt);

    if (matcher.find()) {
        throw new IllegalArgumentException(
                "存在未替换变量："
                + matcher.group()
        );
    }
}

推荐变量统一命名：

避免与普通XML标签混淆。

十一、用户输入中包含花括号怎么办

变量值可能是：

请解释Java中的Map和JSON { }。

正常模板替换不会再次递归解析变量值。

不要对渲染结果重复执行模板渲染，否则用户输入中的花括号可能被第二次解释。

十二、模板安全

PromptTemplate不是安全过滤器。

用户变量仍可能包含：

忽略之前的指令

需要独立处理：

Prompt Injection；
输入长度；
敏感信息；
HTML；
日志脱敏；
数据权限。

模板渲染只负责变量替换，不负责内容可信度。

十三、选择建议

Prompt包含JSON并需要变量

使用自定义分隔符

Prompt不需要变量

使用NoOpTemplateRenderer

Prompt较长、需要版本控制

使用Resource外部模板
＋自定义分隔符

Advisor内部Prompt

在Advisor中单独配置模板

总结

Spring AI PromptTemplate与JSON冲突的根因是：

模板变量和JSON共用花括号

最可靠的解决方式是将变量改为：

并通过单元测试确认JSON结构和变量替换都正确。

延伸阅读

如果你正在关注企业级 AI 应用、Agent、RAG、MCP 与大模型工程化落地，欢迎访问 智元界：

https://www.zyentor.com/

智元界将持续分享可运行的技术实战、架构设计、问题排查与企业应用案例。

长期主义数据库学习者 2026/07/18 10:53:11

白皮书方向是对的，但你说的低算力设备实时跑风险识别确实是硬骨头。我们之前试过在树莓派上部署轻量级模型，精度和延迟的平衡太难调了，最后只能靠云端兜底，成本直接翻倍。感觉现在很多方案还是理想化，真要到学生手里用，得先把边缘端的推理效率提上去才行。

内容方法手册 2026/07/18 08:31:12

确实，低算力设备上跑风险识别太难了，我们之前也卡在精度和延迟的平衡上。

暮色漫游集 2026/07/17 19:54:54

确实，白皮书的方向是对的，但落地时的算力瓶颈太真实了。我们之前做AI学习机，本地跑轻量模型误报率根本压不下来，上云又卡在成本和延迟上。感觉安全教育不能光靠技术围栏，还得在内容设计上多下功夫，比如用交互引导代替硬拦截。

小白LinuxLab 2026/07/17 19:02:16

确实，白皮书的方向很有价值，但落地时那个“低算力实时检测”的痛点太真实了。我身边不少做AI教育硬件的朋友，都在吐槽类似问题——云端推理贵且慢，本地模型又容易误杀，最后逼得他们干脆人工审核，完全背离了初衷。你提到的蒸馏BERT模型10%误拦截率，其实在行业里算不错了，我们试过更轻量的方案，结果连“科学实验”这种词都被拦截，用户直接投诉产品“智障”。说到底，安全防护和用户体验之间的平衡，目前还是靠牺牲一方来换。不知道白皮书有没有考虑过混合架构？比如关键场景走云端，常规内容靠本地轻量模型，再搭配人工兜底。另外，思维链教学法听起来很理想化，但实际教学中，孩子不按预设路径思考时，这套方法会不会反而限制创造力？这些问题不解决，再好的理论也难逃“纸上谈兵”。

认真做效率案例库 2026/07/17 18:59:36

确实，白皮书的框架很完整，但落地时那些“围栏”得先跨过算力和延迟的坎。我们之前试过在低端平板上跑轻量级模型，准确率一降，用户反馈直接崩了。感觉现在缺的不是方案，而是能在移动端低成本跑起来的精准模型，这块不突破，再好的思维链也只能是纸上谈兵。

Spring AI PromptTemplate插入JSON时花括号冲突怎么办？三种可靠解决方案

Spring AI PromptTemplate插入JSON时花括号冲突怎么办？三种可靠解决方案

文章摘要

一、典型问题

二、方案一：修改模板变量分隔符

三、在ChatClient中配置自定义Renderer

四、方案二：不需要模板时使用NoOpTemplateRenderer

五、方案三：外部Resource模板

六、为什么不推荐手工转义所有花括号

七、JSON Schema场景

八、Advisor内部模板要单独配置

九、模板变量缺失如何提前发现

十、检测未替换变量

十一、用户输入中包含花括号怎么办

十二、模板安全

十三、选择建议

Prompt包含JSON并需要变量

Prompt不需要变量

Prompt较长、需要版本控制

Advisor内部Prompt

总结

延伸阅读

评论 5

📖 关联推荐

精选推荐