1. 项目概述从“硬编码”到“动态编排”的提示工程进化在构建基于大语言模型LLM的应用时我们经常遇到一个看似简单却无比核心的问题如何高效、灵活地构造发送给模型的指令也就是“提示词”Prompt如果你还在代码里用字符串拼接的方式像String prompt 请总结以下文章 articleContent 要求不超过100字。这样写那么恭喜你你正站在“提示工程”的起点也即将踏入第一个效率陷阱。硬编码的提示词就像给每个菜谱都单独写一本烹饪书一旦需要调整格式、更换内容或者支持多语言改动就会散落在代码的各个角落维护起来是一场噩梦。这正是Spring AI Alibaba中PromptTemplate组件要解决的核心痛点。它不是一个高深莫测的概念你可以把它理解为一个“智能字符串模板引擎”专门为与LLM对话而设计。它的核心价值在于“解耦”和“复用”。通过将提示词的结构模板与具体的内容变量分离我们能够像管理代码模板一样管理提示词实现动态生成、统一维护和批量测试。无论是简单的问答、复杂的内容生成还是需要多步推理的智能体Agent工作流PromptTemplate都是构建可维护、可扩展AI应用的基石。简单来说它让我们的提示词从“静态文本”变成了“可编程的指令工厂”。对于刚接触 Spring AI Alibaba 的开发者而言掌握PromptTemplate是摆脱新手村迈向高效AI应用开发的关键一步。接下来我将以一个内容总结的场景为例带你从零开始彻底搞懂如何创建、使用以及高级定制提示词模板并分享我在实际项目中积累的实战经验和避坑指南。2. 核心概念与设计思路拆解2.1 什么是提示词模板为什么需要它在深入代码之前我们有必要先厘清“模板”在此处的含义。传统的Web模板如Thymeleaf、FreeMarker是将数据模型填充到HTML结构中最终生成给浏览器渲染的页面。PromptTemplate的思路一脉相承但它生成的对象是给大语言模型“阅读”的自然语言指令。一个典型的提示词模板包含两部分静态文本部分这是提示词的固定骨架定义了任务指令、输出格式要求、角色设定等。例如“你是一位专业的科技文章编辑请将以下文本总结为要点列表并确保每个要点不超过15个字”动态变量部分这是需要被具体值替换的占位符通常对应着用户输入、上下文信息或系统参数。例如{article}或{maxLength}。为什么这种分离至关重要设想一个客服机器人场景。回复用户咨询的提示词基本结构是固定的“根据以下用户问题‘{question}’和知识库内容‘{knowledge}’生成一段友好、专业的回复。”如果没有模板每次调用模型你都需要拼接这个字符串。当产品经理要求在所有回复前加上“您好”时你就需要找到所有拼接了这段提示词的地方进行修改极易遗漏。而使用模板你只需修改一个模板文件或一处模板定义所有使用该模板的代码都会自动生效。这极大地提升了代码的可维护性和一致性。2.2 Spring AI Alibaba 中 PromptTemplate 的设计哲学Spring AI Alibaba 的PromptTemplate设计充分体现了 Spring 框架“约定优于配置”和“依赖注入”的思想。它不是一个孤立的工具类而是深度集成在 Spring AI 的AiClient调用流程中。其核心设计目标包括声明式定义支持通过Bean方式在配置类中声明模板也支持在代码中即时创建给予开发者最大的灵活性。强类型安全模板变量通过MapString, Object或对象Object进行绑定IDE的代码补全和编译期检查能在一定程度上减少运行时错误。表达式语言支持底层通常集成如 Spring Expression Language (SpEL) 这样的表达式引擎。这意味着你不仅能够做简单的变量替换{var}还能在模板中嵌入简单的逻辑判断或方法调用例如{user.name.toUpperCase()}虽然在实际提示工程中复杂逻辑应谨慎使用。与AiClient无缝集成构造好的Prompt对象可以直接传递给AiClient.call()方法使得从模板到模型调用的链路非常简洁。这种设计让开发者能够以熟悉的 Spring 风格来管理AI应用中最易变的部分——提示词将AI能力真正当作企业应用中的一个标准服务组件来调用和治理。3. 基础使用从创建到渲染的完整流程3.1 环境准备与基础依赖首先确保你的pom.xml或build.gradle中已经引入了 Spring AI Alibaba 的核心依赖。这里以主流的spring-ai-alibaba-qwen为例dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-qwen-spring-boot-starter/artifactId version最新版本/version !-- 请替换为如 1.0.0-M5 等实际版本 -- /dependency同时你需要在application.yml中配置通义千问的API密钥和端点如果你使用DashScope服务spring: ai: alibaba: qwen: api-key: your-api-key-here # 其他可选配置如 base-url, chat.options 等3.2 创建你的第一个提示词模板Spring AI Alibaba 提供了多种创建PromptTemplate的方式最直接的是使用其构造函数。示例1简单的字符串模板假设我们要创建一个用于文章总结的模板。import org.springframework.ai.alibaba.prompt.PromptTemplate; public class SummaryService { public String createSummaryPrompt(String articleContent, int maxLength) { // 1. 定义模板字符串使用花括号 {} 包裹变量名 String templateString 你是一位专业的编辑请将以下用三重引号包裹的文章内容总结为不超过{maxLength}个字的摘要。 文章内容\\\{article}\\\ 摘要 ; // 2. 创建 PromptTemplate 实例 PromptTemplate promptTemplate new PromptTemplate(templateString); // 3. 准备变量映射Map MapString, Object variables new HashMap(); variables.put(article, articleContent); variables.put(maxLength, maxLength); // 4. 渲染模板生成最终的 Prompt 对象 // Prompt 是 Spring AI 中表示一次完整请求的核心对象包含消息列表。 Prompt prompt promptTemplate.create(variables); // 此时prompt 已经是一个包含了完整、已替换变量提示词的请求对象。 // 例如如果 articleContent今天天气很好maxLength10 // 则 prompt 中的消息内容将是 // “你是一位专业的编辑...不超过10个字的摘要。文章内容\\\今天天气很好\\\ 摘要” return prompt; // 这个Prompt对象可以直接用于调用AiClient } }关键点解析变量占位符{article}和{maxLength}是模板中的占位符。变量名可以自定义但需与传入Map的key保持一致。Prompt对象promptTemplate.create()返回的是一个org.springframework.ai.prompt.Prompt对象而不是简单的字符串。这个对象可能包含多条消息例如在聊天场景中是AiClient接口的标准输入。多行字符串Java 15 的文本块语法非常适合编写包含换行的复杂提示词模板能保持格式清晰。3.3 使用对象而非Map进行变量绑定除了使用MapPromptTemplate也支持直接传入一个Java对象模板会自动根据对象的属性名来匹配变量。这种方式在变量较多时更优雅、更安全。// 首先定义一个承载变量的数据对象 Data // 使用Lombok注解生成getter/setter public class SummaryRequest { private String article; private Integer maxLength; private String language 中文; // 可以设置默认值 } // 在服务中使用 public class SummaryService { public Prompt createSummaryPrompt(SummaryRequest request) { String templateString 你是一位专业的{language}编辑请将以下文章总结为不超过{maxLength}个字的摘要。 文章{article} 摘要 ; PromptTemplate promptTemplate new PromptTemplate(templateString); // 直接传入对象模板引擎会通过反射读取 article, maxLength, language 属性 return promptTemplate.create(request); } }实操心得对于业务逻辑清晰的场景强烈推荐使用对象绑定的方式。它通过编译期的类型检查可以有效避免因拼写错误导致的变量无法替换的问题运行时通常会保留{xxx}原样导致模型困惑。同时这也更符合面向对象的设计原则便于后续扩展。4. 高级特性与实战技巧4.1 模板的集中化管理与注入在真实的项目中提示词模板应该被当作一种重要的“配置”或“资源”来管理。我们不应该将模板字符串硬编码在业务逻辑代码中。Spring 的依赖注入机制可以完美地解决这个问题。方法一在Configuration类中声明BeanConfiguration public class PromptTemplateConfig { Bean public PromptTemplate articleSummaryPromptTemplate() { String template 角色资深媒体编辑 任务总结文章核心思想 要求 1. 使用{language}输出。 2. 严格限制在{summaryLength}字以内。 3. 输出格式为首先用一句话概括然后分点列出关键论据。 待总结文章 {articleContent} 请开始你的总结 ; return new PromptTemplate(template); } Bean public PromptTemplate translationPromptTemplate() { // 另一个翻译模板 return new PromptTemplate(将以下{sourceLang}文本翻译成{targetLang}\n{text}); } }然后在你的服务类中直接注入使用Service public class AdvancedAIService { Autowired private PromptTemplate articleSummaryPromptTemplate; // 注入特定的模板Bean Autowired private AiClient aiClient; // 注入Spring AI Alibaba的客户端 public String summarizeArticle(String content, String language, int length) { MapString, Object vars Map.of( articleContent, content, language, language, summaryLength, length ); Prompt prompt articleSummaryPromptTemplate.create(vars); AiResponse response aiClient.call(prompt); // 调用模型 // 处理response... return response.getGeneration().getText(); } }方法二将模板存储在外部文件如YAML、Properties或数据库这是更专业、更灵活的做法尤其当需要非开发人员如产品经理、运营调整提示词时。# application-prompts.yml prompts: article-summary: | 角色{role} 任务总结文章 文章{article} 输出要求{outputFormat} text-polishing: | 请优化以下文本的语言表达使其更加{style}{text}然后通过一个ConfigurationProperties类来加载这些模板并动态创建PromptTemplate。Configuration EnableConfigurationProperties(PromptTemplatesProperties.class) public class ExternalTemplateConfig { Bean public MapString, PromptTemplate promptTemplateMap(PromptTemplatesProperties props) { MapString, String templateStrings props.getTemplates(); MapString, PromptTemplate templateMap new HashMap(); templateStrings.forEach((name, templateStr) - { templateMap.put(name, new PromptTemplate(templateStr)); }); return templateMap; } } // 使用 Service public class DynamicPromptService { Autowired private MapString, PromptTemplate promptTemplateMap; public void someMethod() { PromptTemplate summaryTemplate promptTemplateMap.get(article-summary); // ... 使用模板 } }注意事项外部存储模板时要特别注意版本管理和热更新。可以考虑将模板放在配置中心如Nacos并监听配置变化事件来动态刷新内存中的PromptTemplate实例避免重启应用。4.2 处理复杂变量与条件逻辑虽然提示词模板的主要目的是文本替换但借助SpEL我们可以实现一些简单的动态逻辑。但请务必谨慎使用因为复杂的逻辑会降低模板的可读性且不利于后续对提示词本身进行优化和A/B测试。示例根据用户级别提供不同详细程度的总结String template 你是一位为{userLevel}用户服务的编辑。 #{userLevel ‘VIP‘ ? ‘请提供非常详细、包含背景分析和行业洞察的总结。‘ : ‘请提供简明扼要的总结。‘} 总结以下文章{article} ; // 注意上述 #{...} 是SpEL表达式语法需要PromptTemplate支持。Spring AI默认的PromptTemplate可能不支持复杂SpEL具体需查看版本文档或使用自定义实现。更稳妥的做法是将条件逻辑放在Java代码中选择不同的模板public Prompt getSummaryPrompt(String article, User user) { String template; if (VIP.equals(user.getLevel())) { template VIP_SUMMARY_TEMPLATE; // 详细模板 } else { template NORMAL_SUMMARY_TEMPLATE; // 简洁模板 } PromptTemplate promptTemplate new PromptTemplate(template); return promptTemplate.create(Map.of(article, article, userName, user.getName())); }4.3 模板组合与嵌套对于复杂的任务我们可以将大任务拆解使用多个小模板组合完成。例如一个“翻译并总结”的任务可以先调用翻译模板再将结果作为变量传入总结模板。public String translateAndSummarize(String englishArticle, String targetLanguage) { // 第一步翻译 PromptTemplate translateTemplate new PromptTemplate(将以下英文翻译成{lang}\n{text}); Prompt translatePrompt translateTemplate.create(Map.of(lang, targetLanguage, text, englishArticle)); String translatedText aiClient.call(translatePrompt).getGeneration().getText(); // 第二步总结翻译后的文本 PromptTemplate summaryTemplate articleSummaryPromptTemplate; // 注入的Bean Prompt summaryPrompt summaryTemplate.create(Map.of(articleContent, translatedText, language, targetLanguage)); String summary aiClient.call(summaryPrompt).getGeneration().getText(); return summary; }这是一种“链式调用”的雏形。在更复杂的智能体Agent工作流中这种模板组合与数据传递的思想会进一步演化为通过Agent框架来管理。5. 常见问题排查与性能优化5.1 变量未替换或替换错误这是新手最常见的问题。渲染后的提示词中仍然留有{variable}这样的占位符。原因1变量名不匹配。Map中的key或对象属性名与模板中的占位符名称不一致大小写、拼写。排查仔细核对两者。建议使用常量来定义变量名。public class PromptVariables { public static final String ARTICLE “article”; public static final String MAX_LEN “maxLength”; } // 模板中使用 {article}, {maxLength} // Map中使用 PromptVariables.ARTICLE 作为key原因2传入的对象为null或属性为null。如果整个对象为null会报错。如果某个属性为null则对应占位符可能被替换为空字符串或报错取决于实现。解决在绑定前进行空值检查或为模板提供默认值如果模板引擎支持SpEL可以使用{variable?:‘default‘}语法。原因3模板字符串被错误转义。特别是在使用XML、YAML或Properties文件存储模板时要注意花括号{}是否被正确解析。解决检查配置文件格式在YAML多行字符串中使用|或|-来保留原格式。5.2 提示词渲染性能考量PromptTemplate的渲染本身开销极低通常不是性能瓶颈。性能瓶颈主要出现在网络I/O调用远程AI API和模型推理上。但以下几点仍值得注意避免在循环中重复创建相同的模板对象。尤其当模板字符串来自外部资源如数据库查询时应在循环外部创建好PromptTemplate实例。// 错误示范每次循环都解析模板字符串 for (Article article : articles) { PromptTemplate template new PromptTemplate(loadTemplateFromDB(“summary“)); // 低效 // ... } // 正确示范缓存模板实例 MapString, PromptTemplate templateCache new ConcurrentHashMap(); for (Article article : articles) { PromptTemplate template templateCache.computeIfAbsent(“summary“, k - new PromptTemplate(loadTemplateFromDB(k))); // ... }批量渲染与调用。如果业务允许可以将多个独立任务的输入变量收集起来使用同一个模板批量渲染出多个Prompt然后考虑是否可以使用模型的批量处理API如果AI服务商支持进行调用能显著减少网络往返次数。5.3 模板版本管理与测试随着业务发展提示词模板会不断迭代优化。如何管理不同版本的模板为模板命名并附带版本号例如article_summary_v1.2。可以在数据库或配置中心中存储模板内容和版本信息。A/B测试同时维护两个版本的模板如summary_A和summary_B在服务层通过分流逻辑决定使用哪个模板并收集模型输出的效果指标如人工评分、业务转化率用数据驱动提示词的优化。单元测试为PromptTemplate编写单元测试确保变量替换正确渲染后的提示词格式符合预期。可以模拟不同的输入验证输出字符串是否包含预期的关键词且不包含{}。Test void testSummaryPromptRendering() { PromptTemplate template new PromptTemplate(“总结{text}“); Prompt prompt template.create(Map.of(“text“, “测试内容“)); String renderedContent prompt.getContents(); // 获取渲染后的字符串 assertThat(renderedContent).contains(“测试内容“); assertThat(renderedContent).doesNotContain(“{“).doesNotContain(“}“); }6. 在智能体Agent工作流中的应用展望当你熟练掌握了PromptTemplate你就为理解和使用 Spring AI Alibaba 中更高级的概念——智能体Agent——打下了坚实基础。一个复杂的Agent通常由多个步骤Step或工具Tool组成每个步骤本质上都是一个或一组精心设计的提示词模板用于完成特定的子任务如思考、调用工具、解析结果。例如一个数据分析Agent的工作流可能如下理解任务模板接收用户问题“分析上个月销售数据”生成分析计划。查询数据模板根据计划生成查询数据库的SQL语句或调用工具。解释结果模板将查询到的数据填入模板让模型生成自然语言分析报告。在这个过程中PromptTemplate是串联整个工作流的“粘合剂”和“指令发生器”。通过将工作流分解为可复用的模板整个系统的可维护性和可观测性会大大增强。你可以单独调试和优化每一个模板而不影响其他部分。从“硬编码”到“模板化”再到“工作流化”这是构建生产级AI应用的必然路径。PromptTemplate作为这条路径上的第一个关键工具其价值远不止于简单的字符串替换。它代表了一种工程化的思维即将非结构化的自然语言指令通过结构化的方式进行管理、迭代和交付。掌握它你就拿到了高效开发AI应用的第一把钥匙。