1. Prompt在Spring AI中的定位与核心模型
1.1 从ChatClient到Prompt：一次请求的完整链路
Spring AI 1.0.0 GA版本发布之后，我在生产环境里陆续接了好几个项目，发现很多刚上手的人最容易卡住的地方，恰恰是Prompt这个看似最不起眼的环节。大家都知道Spring AI把大模型接入做成了类似于Spring Data的抽象层，可以用统一的API对接OpenAI、通义千问、Ollama本地模型等，但真正写业务代码时，Prompt的组装方式直接决定了模型输出的质量和稳定性。
先用一句话说清楚Prompt在Spring AI里的位置：它是用户与模型之间的消息载体。你在代码里调用chatModel.call(prompt)，传入的就是一个Prompt对象，这个对象内部封装了至少一条Message，可能是SystemMessage、UserMessage，或者是带有模板参数的PromptTemplate渲染出来的消息。模型返回的也不是裸字符串，而是一个ChatResponse对象，里面包着AssistantMessage。
ChatClient chatClient = ChatClient.builder(chatModel).build(); String answer = chatClient.prompt() .system("你是一个资深的Java架构师") .user("请解释Spring AI中Prompt的作用") .call() .content();这段代码是Spring AI 1.0之后最推荐的写法，直接用ChatClient的流式API组装Prompt。它内部做的事情可以拆成三步：把system和user的字符串包装成Message、把多个Message塞进Prompt对象、调用chatModel.call(prompt)拿到响应。理解了这个链路，你才能明白下面要讲的模板、Token和异常处理到底发生在哪个环节。
1.2 Message体系：SystemMessage、UserMessage、AssistantMessage
很多人第一次看到Message接口时容易懵，其实类比一下微信群聊就很好懂。SystemMessage相当于群公告，规定聊天的整体规则和角色；UserMessage是你发的消息；AssistantMessage是模型回复的消息。在多轮对话里，每一轮都要把这三类消息按顺序传给模型，模型才能理解上下文。
Spring AI的Message接口定义非常简单，核心就两个方法：getMessageType()返回消息类型枚举，getTextContent()返回文本内容。它还有一个MediaContent子接口，用来承载图片、音频等多模态数据。落到实现类上，常用的有这几个：
SystemMessage：构造函数直接传字符串，系统提示词。UserMessage：可以传字符串，也可以传List<Media>，实现图文混合输入。AssistantMessage：一般你不需要手动创建，模型返回的ChatResponse里已经带了。MessageBuilder：Spring AI 1.0提供的建造者工具，可以链式设置文本和媒体。
我自己习惯把系统提示词写在一个常量类里统一管理，而不是散落在业务代码中。比如一个客服机器人的系统提示词，可以定义成public static final String SYSTEM_PROMPT = "你是某电商平台的智能客服..."，这样后续做Prompt版本管理也方便。
1.3 Prompt对象的核心方法解析
Prompt本身是个很轻的封装，内部主要持有一个List<Message>和一组可选的GenerationOptions。构造函数支持传入单条消息、消息列表，以及可选的模型参数。比如：
Prompt prompt = new Prompt( List.of( new SystemMessage("你是一个严谨的代码审查员"), new UserMessage("请审查下面这段代码，指出潜在问题：\n" + code) ), OpenAiChatOptions.builder() .withTemperature(0.2) .withMaxTokens(800) .build() );这里的OpenAiChatOptions是模型特定参数，控制temperature、maxTokens、topP这些采样参数。需要特别提醒的是，如果你用的是Ollama或通义千问，Options也要换成对应的实现类，Spring AI在这块没有做统一抽象，因为各家模型的参数确实不完全一样。Prompt的作用就是把“给模型看的消息”和“给模型用的参数”绑在一起，作为一次请求的完整输入。
2. PromptTemplate：模板绑定与参数渲染
2.1 基本用法：用占位符代替字符串拼接
写业务代码时，没人会天天手拼字符串。Spring AI提供了PromptTemplate，用起来和Java自带的String.format很像，但更灵活。它基于StringTemplate引擎，支持{placeholder}形式的占位符。
PromptTemplate template = new PromptTemplate( "给我写一篇关于{topic}的技术文章，风格要求{style}，字数控制在{words}字以内" ); Prompt prompt = template.create(Map.of( "topic", "Spring AI", "style", "通俗易懂且专业", "words", 3000 )); String content = chatModel.call(prompt).getResult().getOutput().getText();create方法接受一个Map<String, Object>，把占位符替换成实际值。这里要注意键名和占位符必须完全一致，少一个字母渲染出来的字符串里就会残留{topic}，这个Bug很隐蔽，排错时容易忽略。
2.2 参数绑定的三种姿势与选择建议
除了传Map，PromptTemplate还支持另外两种参数传入方式。第一种是用PromptTemplate.builder()链式设置：
PromptTemplate template = PromptTemplate.builder() .template("介绍一下{framework}的核心特性") .defaultValues(Map.of("framework", "Spring AI")) .build();第二种是留空占位符，运行时再通过create方法传入，适合参数动态变化的场景。我个人的经验是：默认值用defaultValues，动态值用create传入的Map，两者组合使用能让模板在不同场景下复用。比如定义一套客服回复模板，默认值里写死语气风格，调用时只传用户问题，模板的复用性一下子就上来了。
2.3 模板渲染背后做了什么：StringTemplate引擎与格式校验
Spring AI的PromptTemplate依赖的是ANTLR生成的StringTemplate引擎，它不只是简单做字符串替换，还支持条件判断、循环等高级语法，虽然我实际项目中很少用这些，因为Prompt模板本身应该保持简单。
{% if {urgent} %} 请优先处理这个问题，用户等待时间较长。 {% else %} 按正常流程处理。 {% endif %}这个语法有学习成本，但好处是模板可以表达逻辑分支。我自己常用的还是{占位符}这一种，原因有两条：一是维护模板的人不一定懂StringTemplate语法，二是模板里的条件逻辑如果太复杂，测试用例覆盖起来很麻烦，容易漏掉某些分支导致线上Prompt渲染出错。简单、可读、可测试，才是Prompt模板的第一要务。
3. Token、上下文窗口与成本控制
3.1 为什么Prompt Token是绕不开的话题
热词里有prompt token，说明很多人搜这个。用法上有个直观感受：同样的Prompt，有时模型回答质量突然下降，或者直接报错，很可能就是Token问题。OpenAI按Token计费、按模型上下文窗口限制输入，这是两个硬约束。比如gpt-4o-mini的上下文窗口是128K，但你要是一次性把整本《三体》塞进去，光是输入Token就可能花掉几十块人民币，这还没算输出。
Spring AI不会自动帮你精简Prompt，你传多少就是多少。所以在封装Prompt时，必须自己算清楚Token消耗量。在线搜索热度这么高，说明实际项目中很多人被Token超限或者成本超预算坑过。
3.2 快速估算Token：字符数与tiktoken的关系
有一个粗估公式：英文文本大约1个Token对应4个字符，中文因为分词方式不同，通常1个汉字约等于1到2个Token。精确的Token数是模型分词器决定的，OpenAI官方提供了tiktoken库，可以通过pip install tiktoken装来用。
import tiktoken enc = tiktoken.encoding_for_model("gpt-4o") tokens = enc.encode("Spring AI Prompt核心指南") print(len(tokens))在Java代码里没法直接调tiktoken，我的做法是：在预处理服务里用HTTP调用一个内部的Python服务来计算Token，或者直接用字符数做估算。如果是纯中文场景，我按“字符数除以1.5”来估Token数，实测下来的误差基本在10%以内，用来做预算控制够了。
3.3 控制上下文长度的实用策略
Prompt变长不只是花钱的问题，更关键的是模型会“遗忘”前面说过的话，因为注意力机制对长上下文的处理能力有限。有几种控制策略我在项目里反复用过：
- 滑动窗口：只保留最近几轮对话，丢弃过期的系统消息和旧用户消息。
- 摘要压缩：当对话轮次超过阈值，先让模型把历史对话浓缩成要点，再作为SystemMessage传下去，相当于“笔记代替原话”。
- 动态截断：计算当前对话的总Token数，超过预设值就删掉最早的消息，直到总Token降到安全线内。
Spring AI里可以通过自定义ChatMemory实现这些策略，配合ChatClient调用。网上关于prompt token搜索量很高，大概率是大家在处理长对话时都遇到过头疼的截断问题。
4. Prompt Engineering在Spring AI中的落地
4.1 系统提示词设计：先说角色，再说规则
热度词里有prompt engineering和prompt提示词，这确实是Prompt实践中最核心的一环。我建议系统提示词按三层结构来写：第一层定义角色，第二层定义任务规则，第三层定义输出格式。
String systemPrompt = """ 你是{domain}领域的资深专家，名叫小明。 你的任务是根据用户提问给出专业、准确的回答。 规则： 1. 只回答与{domain}相关的问题，与主题无关时礼貌拒绝。 2. 回答必须包含{minLength}字以上的详细解释。 3. 如果用户的问题存在多种观点，请客观对比后给出你的倾向。 4. 禁止编造数据，无法确认的信息要明确说明“我不确定”。 """;这种写法的好处是：模型对任务的把握更精准，而且每一层独立修改，不会牵一发动全身。生产环境里我见过太多系统提示词写成一大段散文，模型输出风格飘忽不定，改一句话就可能整体崩掉。分层写，本质上是在降低Prompt的耦合度。
4.2 结构化输出：用Prompt引导JSON/表格/代码
大部分业务系统接大模型，不是让它随便聊天，而是要稳定的结构化数据。Spring AI 1.0提供了BeanOutputConverter，可以配合PromptTemplate把输出直接转为Java对象。
BeanOutputConverter<MyDTO> converter = new BeanOutputConverter<>(MyDTO.class); PromptTemplate template = new PromptTemplate(""" 请将以下信息解析为JSON格式，要求字段名严格遵循给定的schema： {content} {format} """, Map.of( "content", userInput, "format", converter.getFormat() )); Prompt prompt = template.create(); // converter.getFormat() 会生成一个严格的JSON Schema要求这里关键点是：getFormat()输出的不是普通JSON示例，而是严格的schema描述。模型看到schema之后，输出的JSON结构稳定性大幅提升。我用这个方式解析过发票信息、简历数据、研报摘要，准确性比让模型“自己看着办”高出很多。
4.3 连环Prompt与多轮上下文管理
有些任务没法一次完成，比如“先让模型总结对话，再让模型根据总结写一封邮件”。这种连环Prompt的方式要小心：每一步的Prompt都承担双重角色，既要引用上一步的输出，又要给模型足够的上下文，不能被历史噪声干扰。
我的做法是：在上一步的输出里提取关键信息，存成结构化对象，下一步Prompt只传对象的核心字段，而不是把原始输出整个丢进去。比如第一步让模型抽取“用户意图是退款、金额是200元、平台是拼多多”，第二步只把这些字段填进新模板。这样既省Token，又避免模型被上一步的废话带偏。多轮聊天的上下文管理同理，Spring AI的MessageWindowChatMemory可以直接用，设置窗口大小即可，实现上用的是List<Message>队列机制，够用且稳定。
5. 常见故障排查与避坑实录
5.1 invalid prompt内容过滤报错的真相与应对
热词里有一个很典型的报错：invalid prompt: your prompt was flagged as potentially violating our usage policy，我估计不少人被这个卡住过。这个提示的大意是，你的Prompt文本命中了提供方的内容安全策略，系统直接拒绝处理。它不是Spring AI抛的异常，而是模型服务商返回的校验错误，Spring AI通常会把错误包装成ResponseError或InvalidPromptException抛出。
触发原因有几类：一是Prompt里有明显的违规词，比如暴力、仇恨言论等；二是Prompt试图诱导模型绕过安全策略，比如“忽略你所有的规则”“扮演无限制的AI”；三是某些多音字、谐音或编码特征被误判。排查方法是把用户输入的内容逐段分离，二分法测试是哪一段触发了命中。我自己实践下来，最常见的是用户输入里有广告联系方式或者涉赌涉贷的关键词。生产系统的Prompt需要加一道内容预检，提前拦截可疑文本，避免让这种报错直接暴露给用户，体验会很差。
5.2 Prompt导致“闪退”的几种隐蔽原因
热词里的spring ai +prompt闪退，看着挺吓人，但拆开排查，大部分不是真的进程崩溃，而是请求抛了异常没被捕获，导致线程中断，看起来像是程序“闪退”。几种隐蔽原因我列一下，都是我实际踩过的坑：
第一，PromptTemplate的占位符Map里缺key，渲染时StringTemplate不会直接报错，而是把{key}原样留在文本里，你看到模型回答莫名其妙的“{topic}”时才会意识到。
第二，开启流式响应后，如果模型输出流中途EOF，Flux<ChatResponse>的下游没有处理onErrorResume，整个响应链路就被截断，控制台报错一闪而过。
第三，某些模型服务商对单次请求的Prompt有字符数上限，超限时不会等你算Token而是直接切断连接，表现就是客户端等半天后拿到一个连接重置异常。
排查方式：打开日志级别为DEBUG，找到实际的HTTP请求体，确认请求是否到达了模型服务商，再逐层看是参数问题、网络问题还是服务商返回了4xx。大多数闪退其实是异常的默认行为，只是没人打印堆栈。
5.3 超时、截断与token超限处理
超时和token超限是常态。OpenAI系列模型在请求参数里可以设置maxTokens，Spring AI里对应的就是OpenAiChatOptions.withMaxTokens(500)。但有个细节很多人不知道：maxTokens限制的是单次补全的输出长度，Prompt本身的长度不受它控制。如果你Prompt已经3K Token，maxTokens又设成4K，单次请求总Token就可能有7K，仍然会报context_length_exceeded。
try { ChatResponse response = chatModel.call(prompt); } catch (ResponseErrorException e) { // 读取e.getErrorDetail()判断具体错误码 }我的建议是：在调用模型前先估算总Token数，超出模型上下文窗口的80%就主动截断或抛错给上层，不要傻乎乎地发起注定失败的请求。对用户侧则要用“稍后再试”之类的兜底文案替换异常信息，不要暴露内部错误。
6. 进阶：Prompt Optimizer与持续迭代
6.1 为什么Prompt需要版本管理
热词里有prompt optimizer使用教程，这说明大家已经意识到Prompt本身也需要优化、迭代和管理。Prompt工程和软件工程一样，需要版本管理。我不建议直接改线上SystemMessage，而是把每次Prompt变更当成一次代码提交，记录变更原因和效果。
// v1：初版客服提示词 public static final String SYSTEM_PROMPT_V1 = "你是客服，回答用户问题。"; // v2：增加情绪安抚要求 public static final String SYSTEM_PROMPT_V2 = "你是客服，先安抚用户情绪，再解答问题。";这看着简单，实际作用很大。模型输出有随机性，同一个Prompt在不同时间结果可能不同，没有版本对比就没法判断改动到底有没有效果。我在项目中用A/B测试的方式比较v1和v2的满意度指标，数据说话，比拍脑袋靠谱得多。
6.2 实测中的Prompt优化套路
Prompt Optimizer本身并没有统一的行业标准，搜索引擎里搜到的大多是各家模型厂商的自有工具。我落地过最有效的优化套路是“少样本+精细约束”。给模型一两组带标准答案的示例，比说一百遍“请专业作答”都管用。
String prompt = """ 请按照示例格式回答用户问题。 示例： 问：Spring AI支持哪些模型厂商？ 答：Spring AI支持OpenAI、Azure OpenAI、Ollama、通义千问等，通过统一的ChatModel接口接入。 注意：回答必须限定在Spring AI框架范围内，不扩展其他内容。 问：{question} 答： """;另一个套路是“漏斗式Prompt”。先输出一个宽泛的回答，再分步骤追加约束条件，逐步收敛结果。比如先要求“列出三种解决方案”，再要求“从中选一种，给出具体代码实现”，这样能利用模型的分步思考能力，得到的答案质量明显高。
6.3 后续扩展思路
写完这套Prompt相关的功能后，还有不少可以自然扩展的方向。比如接入Spring AI的Advisor机制，在发送Prompt前自动注入上下文、接口限流、内容审核等横切逻辑。再比如结合Evaluator工具构造一组自动化测试用例，每次调整Prompt后跑一遍回归，确保核心问题不退化，这个比人工肉眼验证效率和稳定性都高出一大截。
像我上面提到的Token预估算，更完整的做法是把“字数→Token”的映射做成独立服务，统一供多个业务部门调用，避免每个项目重复造轮子。等数据积累得足够多，还能拿这些测试用例来反向评估不同模型在相同Prompt下的表现差异，为后续切换模型提供决策依据。
实际操作后的几点体会
最后分享几个我在代码里真正受益的小习惯。第一，任何PromptTemplate的模板字符串都要用text block写法，别用加号拼接，模板长了你根本不想改；第二，所有Model的Options参数统一在一个配置类里初始化，通过构造函数注入到Service，方便测试时替换成Mock模型；第三，务必记录每次调用的输入和输出摘要，这不只是为了排查问题，更重要的是它能帮你发现Prompt的退化趋势，比如某类问题最近回答质量下降，大概率是模型API升级导致行为变化。Prompt这块的东西看起来简单，真正能稳定跑在生产环境里不动摇，靠的全是这些细节。
