1. 為什么提示詞模板管理是 Agent 開發(fā)的分水嶺很多人做 Agent 開發(fā)第一步就是寫一個(gè)能跑的循環(huán)接收用戶輸入、拼接提示詞、調(diào)用模型、解析輸出、執(zhí)行工具、把結(jié)果塞回上下文。跑通 Demo 的那一刻確實(shí)很爽但接下來就會(huì)遇到一個(gè)繞不開的問題——提示詞散落在代碼各處改一個(gè)措辭要翻五個(gè)文件同一個(gè)角色在不同環(huán)節(jié)的提示詞風(fēng)格不一致調(diào)試的時(shí)候根本不知道模型到底收到了什么。我見過不少 Agent 項(xiàng)目功能邏輯寫得挺漂亮但提示詞管理一塌糊涂。系統(tǒng)提示詞硬編碼在 Python 字符串里工具描述用 f-string 拼少樣本示例直接塞在函數(shù)中間變量名還叫prompt1、prompt2、prompt_final。這種項(xiàng)目在單輪對(duì)話里能跑一旦進(jìn)入多輪、多工具、多角色的 Agent 場(chǎng)景維護(hù)成本會(huì)指數(shù)級(jí)上升。提示詞模板管理要解決的核心問題其實(shí)就三個(gè)可復(fù)用、可追蹤、可組合?？蓮?fù)用意味著同一個(gè)角色定義不需要在多個(gè)地方重復(fù)寫可追蹤意味著每次模型調(diào)用時(shí)實(shí)際發(fā)送的完整提示詞能被記錄下來方便排查問題可組合意味著復(fù)雜 Agent 的提示詞可以由多個(gè)小模板按規(guī)則拼裝而成而不是寫成一坨幾千字的巨型字符串。這三個(gè)需求聽起來簡(jiǎn)單但真正落地時(shí)會(huì)牽扯出一堆設(shè)計(jì)決策。模板用什么格式存變量怎么注入版本怎么管理不同 Agent 之間怎么共享模板編排層怎么決定在什么時(shí)機(jī)用哪個(gè)模板這些問題沒有標(biāo)準(zhǔn)答案但有一些經(jīng)過實(shí)踐檢驗(yàn)的思路。這篇文章會(huì)從零開始把提示詞模板管理和 Agent 提示詞編排這兩件事講透。不管你是剛接觸 Agent 開發(fā)的新手還是已經(jīng)寫過幾個(gè) Agent 但覺得提示詞管理很亂的老手都能從中找到可以直接抄作業(yè)的方案。我會(huì)先講模板系統(tǒng)的基本設(shè)計(jì)再講變量注入和渲染的細(xì)節(jié)然后是編排層的核心邏輯最后聊一聊版本管理和調(diào)試追蹤這些容易被忽略但極其重要的環(huán)節(jié)。2. 提示詞模板系統(tǒng)的底層設(shè)計(jì)從硬編碼到結(jié)構(gòu)化2.1 模板的最小數(shù)據(jù)結(jié)構(gòu)應(yīng)該包含什么一個(gè)提示詞模板最樸素的理解就是一段帶占位符的文本。但如果只把它當(dāng)成字符串很快就會(huì)遇到問題。比如你想知道這個(gè)模板是給哪個(gè)角色用的、有哪些變量、變量的默認(rèn)值是什么、這個(gè)模板的版本號(hào)是多少這些信息都沒地方放。所以模板的最小數(shù)據(jù)結(jié)構(gòu)應(yīng)該是一個(gè)對(duì)象至少包含這幾個(gè)字段from dataclasses import dataclass, field from typing import Optional dataclass class PromptTemplate: name: str # 模板唯一標(biāo)識(shí)如 agent.system.base template: str # 模板正文含 {variable} 占位符 variables: list[str] field(default_factorylist) # 聲明的變量列表 defaults: dict field(default_factorydict) # 變量默認(rèn)值 description: str # 模板用途說明 version: str 1.0.0 # 版本號(hào) tags: list[str] field(default_factorylist) # 分類標(biāo)簽 metadata: dict field(default_factorydict) # 擴(kuò)展字段這個(gè)結(jié)構(gòu)看起來有點(diǎn)重但每一項(xiàng)都有實(shí)際用途。name用于在編排層引用模板variables用于在渲染前校驗(yàn)變量是否齊全defaults讓可選變量有兜底值version在模板迭代時(shí)能追溯歷史tags方便按場(chǎng)景篩選模板。我個(gè)人的經(jīng)驗(yàn)是variables這個(gè)字段一定要顯式聲明不要靠解析模板字符串來推斷。原因很簡(jiǎn)單解析{variable}這種占位符看起來容易但一旦模板里出現(xiàn) JSON 示例、代碼塊、或者需要轉(zhuǎn)義的花括號(hào)解析就會(huì)出錯(cuò)。顯式聲明變量列表渲染時(shí)只替換聲明的變量其他花括號(hào)原樣保留這樣最穩(wěn)。2.2 模板存儲(chǔ)格式的選擇YAML、JSON 還是數(shù)據(jù)庫模板存哪里這個(gè)問題取決于你的項(xiàng)目階段。早期用文件存就夠了YAML 和 JSON 都可以。YAML 的可讀性更好適合手寫和維護(hù)JSON 的解析更嚴(yán)格適合程序生成。如果模板數(shù)量超過幾十個(gè)或者需要支持熱更新、A/B 測(cè)試、多環(huán)境隔離那就該考慮存數(shù)據(jù)庫了。我一般推薦這樣的演進(jìn)路徑階段存儲(chǔ)方式適用場(chǎng)景注意事項(xiàng)原型期Python 字典模板少于 10 個(gè)改模板要重啟服務(wù)成長(zhǎng)期YAML 文件模板 10-50 個(gè)需要文件監(jiān)聽熱加載成熟期數(shù)據(jù)庫模板 50 個(gè)以上需要緩存和版本管理平臺(tái)期數(shù)據(jù)庫 對(duì)象存儲(chǔ)多團(tuán)隊(duì)協(xié)作需要權(quán)限和審計(jì)YAML 文件的一個(gè)典型長(zhǎng)這樣name: agent.system.base version: 1.2.0 description: Agent 基礎(chǔ)系統(tǒng)提示詞 variables: - agent_name - available_tools - current_time defaults: agent_name: 助手 template: | 你是 {agent_name}一個(gè)樂于助人的智能助手。 當(dāng)前時(shí)間{current_time} 你可以使用以下工具 {available_tools} 請(qǐng)根據(jù)用戶需求選擇合適的工具如果不確定先詢問澄清。 tags: - system - base這種格式的好處是非技術(shù)人員也能看懂和修改。產(chǎn)品經(jīng)理要調(diào)整 Agent 的人設(shè)直接改 YAML 就行不需要?jiǎng)哟a。但要注意YAML 對(duì)縮進(jìn)敏感模板正文里的換行和空格要特別小心建議用|塊標(biāo)量保留原始格式。2.3 模板加載器的實(shí)現(xiàn)要點(diǎn)加載器負(fù)責(zé)把存儲(chǔ)層的模板讀進(jìn)內(nèi)存并提供按名稱查詢的能力。實(shí)現(xiàn)時(shí)有幾個(gè)細(xì)節(jié)容易踩坑。第一是緩存策略。如果每次渲染都去讀文件或查數(shù)據(jù)庫性能會(huì)很差。合理的做法是在內(nèi)存里維護(hù)一個(gè)模板字典啟動(dòng)時(shí)全量加載之后通過文件監(jiān)聽或定時(shí)輪詢來更新。更新時(shí)要加鎖避免讀到寫了一半的模板。第二是變量校驗(yàn)時(shí)機(jī)。我建議在加載時(shí)就校驗(yàn)?zāi)０迓暶鞯淖兞亢湍０逭睦锏恼嘉环欠褚恢?。如果聲明了variables但正文里沒有對(duì)應(yīng)的{variable}或者正文里有未聲明的占位符加載時(shí)就報(bào)錯(cuò)而不是等到渲染時(shí)才失敗。這樣能把問題暴露在啟動(dòng)階段而不是運(yùn)行階段。第三是繼承與覆蓋。實(shí)際項(xiàng)目中很多模板是相似的比如不同 Agent 的系統(tǒng)提示詞可能只有人設(shè)不同其他部分一樣。這時(shí)候可以用繼承機(jī)制定義一個(gè)基礎(chǔ)模板其他模板通過extends字段繼承它只覆蓋需要改的部分。實(shí)現(xiàn)上可以用深度合并的方式把子模板的字段合并到父模板上。class TemplateLoader: def __init__(self, template_dir: str): self.template_dir template_dir self._cache: dict[str, PromptTemplate] {} self._lock threading.RLock() self._load_all() def _load_all(self): for file in Path(self.template_dir).glob(*.yaml): data yaml.safe_load(file.read_text(encodingutf-8)) tpl PromptTemplate(**data) self._validate(tpl) self._cache[tpl.name] tpl def _validate(self, tpl: PromptTemplate): declared set(tpl.variables) # 用正則找出正文里的占位符排除轉(zhuǎn)義的花括號(hào) found set(re.findall(r(?!\{)\{(\w)\}(?!\}), tpl.template)) if declared ! found: raise ValueError( f模板 {tpl.name} 變量聲明不一致 f聲明了 {declared}正文里有 {found} ) def get(self, name: str) - PromptTemplate: with self._lock: if name not in self._cache: raise KeyError(f模板 {name} 不存在) return self._cache[name]這段代碼里正則(?!\{)\{(\w)\}(?!\})的作用是匹配單個(gè)花括號(hào)包裹的變量名同時(shí)排除{{和}}這種轉(zhuǎn)義寫法。這個(gè)細(xì)節(jié)很重要因?yàn)槟０謇锝?jīng)常需要寫 JSON 示例比如{{key: value}}如果不排除就會(huì)被誤認(rèn)為是變量。3. 變量注入與渲染那些文檔不會(huì)告訴你的細(xì)節(jié)3.1 變量注入的三種模式及其適用場(chǎng)景變量注入看起來就是字符串替換但實(shí)際用起來有三種模式各有各的適用場(chǎng)景。直接替換是最簡(jiǎn)單的把{variable}替換成對(duì)應(yīng)的值。適合變量值是短文本、不需要額外處理的場(chǎng)景比如{agent_name}、{current_time}。格式化注入是在替換前對(duì)變量值做處理比如把列表轉(zhuǎn)成帶序號(hào)的文本、把字典轉(zhuǎn)成 JSON、把長(zhǎng)文本截?cái)?。適合變量值是結(jié)構(gòu)化數(shù)據(jù)的場(chǎng)景比如{available_tools}可能是一個(gè)工具列表需要格式化成易讀的文本。條件注入是根據(jù)變量值決定是否包含某段內(nèi)容。比如{has_tools}為真時(shí)才插入工具說明段落。這種模式在 Agent 提示詞里特別有用因?yàn)椴煌瑘?chǎng)景下 Agent 的能力集可能不同。實(shí)現(xiàn)上我建議把變量處理邏輯獨(dú)立出來用一個(gè)VariableResolver來統(tǒng)一管理class VariableResolver: def __init__(self): self._formatters {} def register(self, name: str, formatter: callable): self._formatters[name] formatter def resolve(self, name: str, value, context: dict) - str: if name in self._formatters: return self._formatters[name](value, context) if isinstance(value, list): return \n.join(f- {item} for item in value) if isinstance(value, dict): return json.dumps(value, ensure_asciiFalse, indent2) return str(value)這樣設(shè)計(jì)的好處是格式化邏輯可以按變量名注冊(cè)不同模板里同名的變量會(huì)自動(dòng)用同一套格式化規(guī)則。比如所有叫available_tools的變量都會(huì)用工具列表的格式化方式處理保證輸出風(fēng)格一致。3.2 渲染時(shí)的轉(zhuǎn)義與安全邊界渲染環(huán)節(jié)最容易出問題的地方是轉(zhuǎn)義。模板里經(jīng)常需要寫 JSON、代碼塊、或者包含花括號(hào)的示例如果渲染時(shí)無腦替換所有{...}這些內(nèi)容就會(huì)被破壞。我的做法是約定一套轉(zhuǎn)義規(guī)則{{表示字面量的{}}表示字面量的}。渲染時(shí)先把{{和}}替換成占位符做完變量替換后再還原。這樣模板作者可以放心地寫 JSON 示例。另一個(gè)安全邊界是變量值的注入攻擊。如果變量值來自用戶輸入而用戶輸入里包含{system_prompt}這樣的內(nèi)容直接替換可能會(huì)導(dǎo)致意外的模板展開。雖然 Python 的str.format不會(huì)遞歸展開但如果你用的是多層渲染就可能出問題。防御方法是渲染時(shí)只做一次替換不對(duì)替換結(jié)果再做二次解析。還有一個(gè)容易被忽略的點(diǎn)是變量值的長(zhǎng)度控制。Agent 的上下文窗口是有限的如果某個(gè)變量值特別長(zhǎng)比如工具返回了一大段文本直接塞進(jìn)提示詞可能會(huì)擠占其他重要內(nèi)容的空間。我通常會(huì)給每個(gè)變量設(shè)一個(gè)最大長(zhǎng)度超過就截?cái)嗖⒓邮÷蕴?hào)同時(shí)在日志里記錄截?cái)嗍录奖闩挪椤?.3 渲染結(jié)果的緩存與失效在 Agent 的多輪循環(huán)里系統(tǒng)提示詞往往是固定的只有對(duì)話歷史和工具結(jié)果在變。如果每輪都重新渲染系統(tǒng)提示詞純屬浪費(fèi)。合理的做法是把渲染結(jié)果緩存起來key 是模板名加變量值的哈希value 是渲染后的字符串。但緩存有個(gè)陷阱如果變量值里包含時(shí)間戳、隨機(jī)數(shù)、或者每次調(diào)用都不同的 ID緩存就永遠(yuǎn)命中不了。所以緩存 key 的生成要排除這些易變變量或者干脆把模板分成靜態(tài)部分和動(dòng)態(tài)部分靜態(tài)部分緩存動(dòng)態(tài)部分每次渲染。class RenderCache: def __init__(self, max_size: int 128): self._cache OrderedDict() self._max_size max_size def get_or_render(self, tpl: PromptTemplate, variables: dict, resolver: VariableResolver) - str: # 排除易變變量后生成 key stable_vars {k: v for k, v in variables.items() if k not in (current_time, request_id)} key (tpl.name, tpl.version, hash(frozenset(stable_vars.items()))) if key in self._cache: self._cache.move_to_end(key) return self._cache[key] result render(tpl, variables, resolver) self._cache[key] result if len(self._cache) self._max_size: self._cache.popitem(lastFalse) return result這個(gè)緩存實(shí)現(xiàn)用了OrderedDict做 LRU超過容量就淘汰最久未使用的。實(shí)測(cè)下來在系統(tǒng)提示詞固定的場(chǎng)景里緩存命中率能到 90% 以上渲染開銷基本可以忽略。4. Agent 提示詞編排從單模板到多模板協(xié)同4.1 編排層要解決的核心問題單個(gè)模板管理好了接下來就是編排。Agent 的提示詞通常不是一個(gè)大模板而是由多個(gè)部分組成系統(tǒng)人設(shè)、能力說明、工具列表、輸出格式要求、少樣本示例、當(dāng)前任務(wù)描述、對(duì)話歷史、工具返回結(jié)果。這些部分來源不同、更新頻率不同、復(fù)用程度也不同硬拼成一個(gè)模板會(huì)很難維護(hù)。編排層的職責(zé)就是決定在什么時(shí)機(jī)、按什么順序、用哪些模板、注入哪些變量最終組裝成發(fā)給模型的完整提示詞。這聽起來像是一個(gè)簡(jiǎn)單的拼接問題但實(shí)際上涉及幾個(gè)關(guān)鍵決策。第一個(gè)決策是分層還是平鋪。分層是指把提示詞分成系統(tǒng)層、任務(wù)層、對(duì)話層每層有自己的模板平鋪是指所有內(nèi)容都在一個(gè)模板里按順序排列。分層更靈活但實(shí)現(xiàn)復(fù)雜平鋪更簡(jiǎn)單但復(fù)用性差。我的建議是Agent 超過三個(gè)工具、或者有多個(gè)角色時(shí)就上分層。第二個(gè)決策是靜態(tài)編排還是動(dòng)態(tài)編排。靜態(tài)編排是指提示詞結(jié)構(gòu)在代碼里寫死只是變量值在變動(dòng)態(tài)編排是指根據(jù)運(yùn)行時(shí)狀態(tài)決定用哪些模板。比如 Agent 在規(guī)劃階段用一套提示詞在執(zhí)行階段用另一套在反思階段又用一套。動(dòng)態(tài)編排更強(qiáng)大但需要一套規(guī)則引擎來決定模板選擇。第三個(gè)決策是同步還是異步。如果模板渲染涉及遠(yuǎn)程調(diào)用比如從配置中心拉取就要考慮異步。但大多數(shù)場(chǎng)景下模板都在本地內(nèi)存里同步渲染就夠了沒必要引入異步的復(fù)雜度。4.2 分層編排的具體實(shí)現(xiàn)我常用的分層結(jié)構(gòu)是這樣的class PromptOrchestrator: def __init__(self, loader: TemplateLoader, resolver: VariableResolver): self.loader loader self.resolver resolver self.layers [ (system, agent.system.base), (capability, agent.capability.tools), (format, agent.format.output), (task, agent.task.current), (history, agent.history.dialogue), ] def compose(self, context: dict) - str: parts [] for layer_name, tpl_name in self.layers: if not self._should_include(layer_name, context): continue tpl self.loader.get(tpl_name) variables self._extract_variables(tpl, context) rendered render(tpl, variables, self.resolver) parts.append(rendered) return \n\n.join(parts) def _should_include(self, layer: str, context: dict) - bool: if layer capability: return bool(context.get(tools)) if layer history: return bool(context.get(messages)) return True def _extract_variables(self, tpl: PromptTemplate, context: dict) - dict: result {} for var in tpl.variables: if var in context: result[var] context[var] elif var in tpl.defaults: result[var] tpl.defaults[var] else: raise ValueError(f模板 {tpl.name} 缺少變量 {var}) return result這個(gè)編排器的核心邏輯是按預(yù)定義的層順序遍歷每層判斷是否應(yīng)該包含然后渲染對(duì)應(yīng)模板最后用雙換行拼接。_should_include方法實(shí)現(xiàn)了條件包含比如沒有工具時(shí)就不插入能力說明層沒有對(duì)話歷史時(shí)就不插入歷史層。這種設(shè)計(jì)的靈活性在于層順序和層內(nèi)容都可以配置。如果某個(gè) Agent 需要額外的安全約束層只需要在layers列表里加一項(xiàng)再寫一個(gè)對(duì)應(yīng)的模板就行不需要改編排邏輯。4.3 多 Agent 場(chǎng)景下的模板共享與隔離當(dāng)系統(tǒng)里有多個(gè) Agent 時(shí)模板管理會(huì)變得更復(fù)雜。有些模板是所有 Agent 共享的比如輸出格式要求有些是某個(gè) Agent 獨(dú)有的比如特定領(lǐng)域的人設(shè)。這時(shí)候需要一套命名規(guī)范和繼承機(jī)制。我通常用命名空間來區(qū)分agent.system.base是基礎(chǔ)模板agent.system.coder是編碼 Agent 的覆蓋模板agent.system.writer是寫作 Agent 的覆蓋模板。覆蓋模板通過extends字段繼承基礎(chǔ)模板只改需要改的部分。name: agent.system.coder extends: agent.system.base version: 1.0.0 variables: - agent_name - available_tools - current_time - language defaults: agent_name: 編碼助手 language: Python template: | 你是 {agent_name}專注于 {language} 開發(fā)。 當(dāng)前時(shí)間{current_time} 你可以使用以下工具 {available_tools} 回答時(shí)請(qǐng)給出可運(yùn)行的代碼并解釋關(guān)鍵邏輯。加載器在處理extends時(shí)先加載父模板再把子模板的字段合并上去。template字段直接覆蓋variables和defaults做合并tags做并集。這樣既保證了共享部分的一致性又允許每個(gè) Agent 有自己的特色。隔離方面要注意的是變量作用域。不同 Agent 可能有同名但含義不同的變量比如language在編碼 Agent 里指編程語言在翻譯 Agent 里指目標(biāo)語言。如果共用一套變量解析器可能會(huì)出問題。我的做法是給變量加前綴比如coder_language、translator_language或者在編排時(shí)傳入不同的 context讓同名變量在不同 Agent 的上下文里有不同的值。5. 版本管理與調(diào)試追蹤讓提示詞變更可回溯5.1 模板版本號(hào)的語義化規(guī)范模板版本號(hào)看起來是個(gè)小問題但實(shí)際項(xiàng)目中經(jīng)常因?yàn)榘姹竟芾砘靵y導(dǎo)致事故。我見過最離譜的情況是線上 Agent 行為突然變了排查半天發(fā)現(xiàn)是有人改了模板但沒記錄也沒通知任何人。版本號(hào)建議用語義化版本主版本.次版本.修訂號(hào)。主版本變更表示模板結(jié)構(gòu)或核心指令有破壞性改動(dòng)比如刪除了某個(gè)變量、改變了輸出格式要求次版本變更表示新增了功能或變量但向后兼容修訂號(hào)變更表示措辭微調(diào)、錯(cuò)別字修正等不影響行為的改動(dòng)。每次修改模板都要在metadata里記錄變更說明name: agent.system.base version: 1.3.0 metadata: changelog: - version: 1.3.0 date: 2025-01-15 author: zhang change: 新增 current_time 變量要求 Agent 在回答中考慮時(shí)效性 - version: 1.2.0 date: 2025-01-10 author: li change: 調(diào)整工具調(diào)用指令的措辭減少誤調(diào)用這樣出問題時(shí)能快速定位是哪個(gè)版本引入的。如果配合 Git 管理模板文件還能直接 diff 出具體改動(dòng)。5.2 渲染快照排查問題的關(guān)鍵手段Agent 出問題時(shí)最常見的原因是模型收到的提示詞和預(yù)期不一樣。要排查這個(gè)問題就必須能還原每次調(diào)用時(shí)實(shí)際發(fā)送的完整提示詞。這就是渲染快照的作用。實(shí)現(xiàn)上每次渲染完成后把模板名、版本、變量值、渲染結(jié)果存一份到日志或數(shù)據(jù)庫。注意變量值里可能包含敏感信息存儲(chǔ)前要做脫敏?？煺盏?key 可以用request_id這樣從一次請(qǐng)求的日志里就能找到對(duì)應(yīng)的提示詞。def render_with_snapshot(tpl, variables, resolver, request_id): result render(tpl, variables, resolver) snapshot { request_id: request_id, template: tpl.name, version: tpl.version, variables: sanitize(variables), rendered: result, timestamp: time.time(), } snapshot_store.save(snapshot) return result有了快照排查問題時(shí)就能對(duì)比預(yù)期提示詞和實(shí)際提示詞的差異。我遇到過好幾次Agent 行為異常是因?yàn)槟硞€(gè)變量值傳錯(cuò)了比如工具列表里多了一個(gè)不該有的工具或者對(duì)話歷史被截?cái)嗟貌粚?duì)。沒有快照的話這種問題很難定位。5.3 A/B 測(cè)試與灰度發(fā)布當(dāng)你想優(yōu)化提示詞時(shí)直接全量替換風(fēng)險(xiǎn)很大。更穩(wěn)妥的做法是 A/B 測(cè)試讓一部分請(qǐng)求用舊模板一部分用新模板對(duì)比效果指標(biāo)。實(shí)現(xiàn)上可以在編排層加一個(gè)路由邏輯根據(jù)request_id的哈希值決定用哪個(gè)版本。比如哈希值對(duì) 100 取模小于 10 的用新版本其余用舊版本這樣就是 10% 的灰度。def select_template_version(base_name: str, request_id: str, new_version: str, ratio: int 10) - str: if hash(request_id) % 100 ratio: return f{base_name}{new_version} return base_name灰度期間要重點(diǎn)監(jiān)控幾個(gè)指標(biāo)任務(wù)完成率、工具調(diào)用準(zhǔn)確率、用戶滿意度、平均對(duì)話輪數(shù)。如果新版本在這些指標(biāo)上明顯更好再逐步擴(kuò)大比例直到全量。如果變差了立即回滾并分析快照找出原因。這套機(jī)制聽起來有點(diǎn)重但對(duì)于線上 Agent 來說提示詞就是核心邏輯改提示詞相當(dāng)于改代碼必須有同等級(jí)別的謹(jǐn)慎。6. 實(shí)戰(zhàn)中踩過的坑與應(yīng)對(duì)經(jīng)驗(yàn)6.1 變量缺失導(dǎo)致的靜默失敗最常見的坑是變量缺失。如果渲染時(shí)某個(gè)變量沒傳而模板里又用了它str.format會(huì)直接拋KeyError。但如果用的是自定義渲染函數(shù)可能會(huì)靜默地把{variable}原樣保留導(dǎo)致模型收到一個(gè)帶占位符的提示詞行為變得莫名其妙。我的應(yīng)對(duì)方法是渲染前嚴(yán)格校驗(yàn)所有聲明的變量都有值包括默認(rèn)值渲染后再檢查結(jié)果里是否還有未替換的占位符。兩道檢查都通過才認(rèn)為渲染成功。def render(tpl, variables, resolver): # 第一道檢查變量齊全 missing set(tpl.variables) - set(variables) - set(tpl.defaults) if missing: raise ValueError(f模板 {tpl.name} 缺少變量{missing}) # 合并默認(rèn)值 merged {**tpl.defaults, **variables} # 執(zhí)行替換 result tpl.template for var in tpl.variables: value resolver.resolve(var, merged[var], merged) result result.replace(f{{{var}}}, value) # 第二道檢查無殘留占位符 residual re.findall(r(?!\{)\{(\w)\}(?!\}), result) if residual: raise ValueError(f模板 {tpl.name} 渲染后仍有占位符{residual}) return result這個(gè)雙重檢查機(jī)制幫我避免了好幾次線上事故。有一次是新增了一個(gè)變量但忘了在調(diào)用處傳值啟動(dòng)時(shí)沒報(bào)錯(cuò)第一次請(qǐng)求就拋異常了因?yàn)闄z查及時(shí)影響范圍很小。6.2 模板繼承的字段合并陷阱模板繼承用起來方便但字段合并的規(guī)則要定義清楚否則會(huì)出現(xiàn)意料之外的結(jié)果。比如父模板的variables是[a, b]子模板的variables是[b, c]合并后應(yīng)該是[a, b, c]還是[b, c]我的規(guī)則是variables做并集defaults做子覆蓋父template做子覆蓋父tags做并集metadata做深度合并。這個(gè)規(guī)則要寫進(jìn)文檔并且用單元測(cè)試覆蓋避免不同人理解不一致。另一個(gè)陷阱是多層繼承。如果 A 繼承 BB 繼承 C合并順序要保證 C 的字段先合并到 B再合并到 A。實(shí)現(xiàn)上可以用遞歸先解析父模板再合并子模板。6.3 上下文窗口超限的預(yù)防Agent 的提示詞很容易超上下文窗口尤其是對(duì)話歷史長(zhǎng)、工具返回結(jié)果大的時(shí)候。如果超了模型會(huì)報(bào)錯(cuò)或者截?cái)鄬?dǎo)致行為異常。預(yù)防方法是在編排層加一個(gè) token 預(yù)算管理。先估算各層的 token 數(shù)如果總和超過預(yù)算就按優(yōu)先級(jí)裁剪。優(yōu)先級(jí)一般是系統(tǒng)人設(shè) 當(dāng)前任務(wù) 工具列表 近期對(duì)話 遠(yuǎn)期對(duì)話 少樣本示例。def compose_with_budget(self, context: dict, max_tokens: int) - str: parts [] used 0 for layer_name, tpl_name in self.layers: if not self._should_include(layer_name, context): continue tpl self.loader.get(tpl_name) rendered render(tpl, self._extract_variables(tpl, context), self.resolver) tokens estimate_tokens(rendered) if used tokens max_tokens: # 嘗試截?cái)嘣搶觾?nèi)容 rendered truncate_to_tokens(rendered, max_tokens - used) tokens estimate_tokens(rendered) parts.append(rendered) used tokens if used max_tokens: break return \n\n.join(parts)estimate_tokens可以用簡(jiǎn)單的字符數(shù)除以 4 來近似也可以用 tiktoken 這類庫精確計(jì)算。實(shí)測(cè)下來近似估算對(duì)大多數(shù)場(chǎng)景夠用而且沒有額外依賴。6.4 模板熱更新的并發(fā)問題如果支持模板熱更新要注意并發(fā)問題。更新模板時(shí)可能有請(qǐng)求正在渲染舊模板。如果直接替換內(nèi)存里的模板對(duì)象正在渲染的請(qǐng)求可能會(huì)讀到一半新一半舊的數(shù)據(jù)。解決方案是用不可變對(duì)象加原子替換。每次更新時(shí)創(chuàng)建一個(gè)新的模板字典然后用原子操作替換引用。正在渲染的請(qǐng)求持有的是舊字典的引用不受影響。def reload(self): new_cache {} for file in Path(self.template_dir).glob(*.yaml): data yaml.safe_load(file.read_text(encodingutf-8)) tpl PromptTemplate(**data) self._validate(tpl) new_cache[tpl.name] tpl # 原子替換 self._cache new_cachePython 的賦值操作是原子的所以self._cache new_cache這一行執(zhí)行時(shí)其他線程要么看到舊字典要么看到新字典不會(huì)看到中間狀態(tài)。這個(gè)技巧在需要熱更新的場(chǎng)景里很實(shí)用。7. 從模板管理到 Agent 能力沉淀把提示詞模板管理和編排做好之后會(huì)發(fā)現(xiàn)一個(gè)額外的好處Agent 的能力開始可以沉淀了。以前每個(gè) Agent 都是從頭寫提示詞現(xiàn)在可以把經(jīng)過驗(yàn)證的模板片段抽出來形成模板庫。新 Agent 開發(fā)時(shí)直接組合已有模板開發(fā)效率會(huì)高很多。比如工具調(diào)用指令這個(gè)片段經(jīng)過多次迭代后已經(jīng)比較穩(wěn)定就可以抽成獨(dú)立模板所有需要工具調(diào)用的 Agent 都引用它。再比如輸出格式要求可以做成幾個(gè)標(biāo)準(zhǔn)模板JSON 格式、Markdown 格式、純文本格式按需選用。這種沉淀帶來的另一個(gè)好處是質(zhì)量一致性。同一個(gè)模板片段在所有 Agent 里表現(xiàn)一致不會(huì)出現(xiàn)這個(gè) Agent 的工具調(diào)用很準(zhǔn)、那個(gè) Agent 的工具調(diào)用很亂的情況。當(dāng)發(fā)現(xiàn)某個(gè)片段有問題時(shí)改一處所有引用的 Agent 都受益。我現(xiàn)在維護(hù)的模板庫大概有三十多個(gè)模板分成系統(tǒng)層、能力層、格式層、任務(wù)層、歷史層五大類。新做一個(gè) Agent通常只需要寫兩三個(gè)新模板其余全部復(fù)用。這套體系跑下來Agent 的開發(fā)周期從最初的兩三天縮短到半天而且線上問題明顯減少因?yàn)榇蟛糠帜０宥际墙?jīng)過驗(yàn)證的。如果你也在做 Agent 開發(fā)建議盡早把模板管理這件事做起來。不用一開始就做得很復(fù)雜從 YAML 文件加一個(gè)簡(jiǎn)單的加載器開始隨著模板數(shù)量增長(zhǎng)再逐步引入版本管理、快照、灰度這些機(jī)制。關(guān)鍵是養(yǎng)成提示詞即代碼的意識(shí)像管理代碼一樣管理提示詞后面會(huì)省很多事。