別把 Prompt 硬編碼進代碼Spring AI PromptTemplate 與提示詞管理最佳實踐系列Spring AI 深入淺出第 5 篇版本Spring AI 2.0.1 / Spring Boot 4.1.x / JDK 21標簽#SpringAI #PromptTemplate #提示詞工程 #工程化前置閱讀第 2 篇《ChatClient 全拆解》預計字數(shù)6000 字可復制源碼 模板示例 踩坑 FAQ本文將解決把 prompt 寫成代碼里的字符串改一句提示就要重新發(fā)版。本文用PromptTemplate把提示詞做成可配置、可版本、可灰度的工程資產(chǎn)。你將學到為什么提示詞不能硬編碼PromptTemplate/SystemPromptTemplate的變量、渲染、消息生成條件片段與多模板組裝提示詞外置到配置/數(shù)據(jù)庫的方案版本化與灰度的思路一、版本標注本文基于 Spring AI 2.0.1 / Boot 4.1 / JDK 21。依賴沿用第 1 篇 pom。示例里 prompt 模板類屬核心模塊1.x/2.0 用法穩(wěn)定。二、為什么提示詞不能硬編碼硬編碼 prompt 的典型代碼StringreplychatClient.prompt().system(你是一個嚴謹?shù)?Java 技術助手回答必須給出代碼示例。).user(解釋一下q).call().content();問題在哪提示詞和業(yè)務邏輯耦合帶來四個痛點變更要重新發(fā)版調(diào)一句人設要走編譯、測試、上線。無法 A/B想對比兩套提示詞哪個效果好得改代碼部署兩遍。無法復用同一段提示詞散落在多個類里改一處漏一處。無法審計提示詞是 AI 應用的軟代碼散在代碼里沒法版本管理。架構師視角把提示詞當代碼管理——版本化、可配置、可灰度、可回滾。三、PromptTemplate 基礎3.1 變量占位與渲染importorg.springframework.ai.chat.prompt.PromptTemplate;PromptTemplatetemplatenewPromptTemplate(請用 {language} 實現(xiàn)一個 {algorithm} 排序算法);// 用 Map 填充變量生成 PromptPromptprompttemplate.create(Map.of(language,Java,algorithm,快速排序));StringreplychatClient.prompt(prompt).call().content();{language}、{algorithm}就是變量.create(Map)負責填充并渲染成完整 prompt。3.2 SystemPromptTemplate / UserPromptTemplate按角色拆分模板職責更清晰importorg.springframework.ai.chat.prompt.SystemPromptTemplate;importorg.springframework.ai.chat.prompt.UserPromptTemplate;SystemPromptTemplatesystemTemplatenewSystemPromptTemplate(你是 {role}回答風格要 {style}。);UserPromptTemplateuserTemplatenewUserPromptTemplate(幫我看看這段代碼有什么問題\n{code});SystemMessagesystemMsgsystemTemplate.createMessage(Map.of(role,資深 Java 架構師,style,嚴謹、給出修改建議));UserMessageuserMsguserTemplate.createMessage(Map.of(code,public void f(){ ... }));StringreplychatClient.prompt().messages(systemMsg,userMsg).call().content();四、條件片段與多模板組裝真實場景里一段 prompt 常由固定骨架 可選片段組成比如有沒有上下文、要不要約束輸出格式。不要用一堆if-else拼字符串而是按場景選模板Stringbase根據(jù)以下資料回答用戶問題。\n;StringwithContextbase資料\n{context}\n\n用戶問題{question};StringwithoutContext直接回答用戶問題{question};// 有檢索上下文時用帶 context 的模板否則用不帶PromptTemplatetemplatecontext!null?newPromptTemplate(withContext):newPromptTemplate(withoutContext);MapString,ObjectvarsnewHashMap();vars.put(question,question);if(context!null){vars.put(context,context);}Promptprompttemplate.create(vars);條件片段更高級的玩法是配合模板引擎如 StringTemplate做真正的條件渲染但多數(shù)項目用多模板 場景路由就夠了夠用且好維護。五、提示詞外置配置 / 數(shù)據(jù)庫5.1 外置到 yml配合 ConfigurationProperties把提示詞放進配置文件改提示不用重新編譯app:prompts:system:你是 {role}回答要 {style}。summarize:用一句話總結(jié){text}importorg.springframework.boot.context.properties.ConfigurationProperties;importorg.springframework.stereotype.Component;ComponentConfigurationProperties(prefixapp.prompts)publicclassPromptProperties{privateStringsystem;privateStringsummarize;// getter/setter 省略}RestControllerpublicclassPromptController{privatefinalPromptPropertiesprops;privatefinalChatClientchatClient;publicPromptController(PromptPropertiesprops,ChatClient.Builderbuilder){this.propsprops;this.chatClientbuilder.build();}GetMapping(/summarize)publicStringsummarize(RequestParamStringtext){PromptpromptnewPromptTemplate(props.getSummarize()).create(Map.of(text,text));returnchatClient.prompt(prompt).call().content();}}5.2 外置到數(shù)據(jù)庫動態(tài)管理提示詞放數(shù)據(jù)庫配合緩存可實現(xiàn)不改代碼、不重啟地調(diào)整提示詞甚至運營同學也能改。核心是一個按 key 取模板的倉儲 本地緩存這里給出骨架思路ServicepublicclassPromptService{// 從數(shù)據(jù)庫按 key 加載模板本地緩存 失效刷新publicStringgetTemplate(Stringkey){/* 查詢 緩存 */}}提示外置后要理解配置綁定的時機——yml 里的值在啟動時綁定改文件要重啟數(shù)據(jù)庫方案配合緩存才能熱更新。六、版本化與灰度進階把提示詞當軟代碼就需要版本和灰度版本號模板帶版本如summarize:v2改提示詞是發(fā)新版可對比、可回滾。多版本并存數(shù)據(jù)庫里同時存 v1/v2?；叶嚷酚砂醋鈶?按比例把部分流量打到 v2觀察效果再全量呼應本系列第 22 篇的灰度架構。骨架publicStringrender(StringpromptKey,Stringversion,MapString,Objectvars){StringtemplatepromptRepo.get(promptKey,version);// 按 key版本取模板returnnewPromptTemplate(template).create(vars).getContents();}七、原理圖解提示詞生命周期90%10%效果好效果差編寫模板配置/入庫版本化 v1/v2灰度路由v1v2觀察效果全量 v2回滾 v1八、踩坑 FAQ坑 1變量沒傳全報模板變量缺失現(xiàn)象運行報Template variable xxx not found之類異常。原因模板里有{xxx}但create(Map)里沒給這個 key。解決核對模板里所有{...}變量Map 里一一對應?？?2字面量花括號沒轉(zhuǎn)義現(xiàn)象prompt 里本來要輸出{或}結(jié)果被當成變量解析報錯。原因{}是占位符語法字面量花括號要特殊處理。解決確認模板引擎的轉(zhuǎn)義規(guī)則確實要輸出花括號時用轉(zhuǎn)義或避免在模板里寫?？?3外置到 yml 后改了不生效現(xiàn)象改了 yml 里的提示詞運行沒變化。原因ConfigurationProperties在啟動時綁定改文件要重啟且可能有緩存。解決明確外置不等于熱更新要熱更新用數(shù)據(jù)庫 緩存失效方案?？?4模板從 classpath 讀取路徑寫錯現(xiàn)象從classpath:/prompts/xx.st讀模板報找不到。原因文件路徑或資源目錄不對。解決確認模板文件在src/main/resources下路徑用classpath:前綴文件名大小寫一致?？?5多套提示詞散落各處難維護現(xiàn)象同一段提示詞在多個類里重復改一處漏一處。原因沒有統(tǒng)一管理。解決用PromptProperties/PromptService集中管理按 key 引用杜絕硬編碼。九、小結(jié)與合集導航本篇把提示詞從代碼里的字符串升級為可管理的工程資產(chǎn)PromptTemplate變量渲染 SystemPromptTemplate/UserPromptTemplate按角色拆分多模板按場景組裝替代 if-else 拼字符串外置到配置/數(shù)據(jù)庫實現(xiàn)不改代碼調(diào)提示版本化 灰度讓提示詞可對比、可回滾下一篇《Advisor 責任鏈原理》——本系列的靈魂篇講清 ChatClient 背后所有橫切能力的統(tǒng)一機制。十、互動鉤子投票你的 prompt 現(xiàn)在放哪代碼里硬編碼配置文件數(shù)據(jù)庫專門的提示詞管理平臺評論區(qū)聊聊你是怎么管提示詞的源碼見置頂評論。