文章编号：article_412
系列承接：上一篇《Token预算与调用成本建模》建立了按 Token 估算成本的思路，而成本估算的前提是提示模板可复现。本文讨论如何为提示模板建立版本化机制；下一篇将进入《JSON结构化输出与校验》。
问题背景
提示模板是连接业务上下文与模型输入的中间层，也是整个 LLM 应用里改动最频繁的组件之一。模型升级会要求调整指令措辞，评测反馈会催生新的约束，产品需求会引入新的示例。这些改动看似微小，却会改变输出分布、Token 消耗乃至最终成本，这正是上一篇成本建模所依赖的输入。如果模板没有版本号，历史调用就无法复现：A/B 对比会失去基线，成本回归分析会失去对照，线上出现问题时也无从回滚。在多人协作的团队里，模板往往散落各处、缺少统一登记，改动后很难知道谁在何时改了什么。因此，模板应当像代码一样被纳入版本化管理。
核心原理
版本化设计的核心可以归结为三点。第一，用语义化版本标识。用 (major, minor) 元组表示版本：major 变化表示指令意图或行为发生重大改变，minor 变化表示局部措辞调整或补充示例，调用方通过指定版本号来锁定行为。第二，正文不可变。模板正文一经发布就不再原地修改，任何调整都生成一个新版本，旧版本始终保留，从而保证历史可复现。第三，版本可追溯。把实际使用的版本号写入调用日志，并在模板元数据中记录变更说明。对 major 版本升级，调用方需要显式确认；对 minor 版本，可以在灰度中默认采用最新，但线上仍以显式锁定为主。在此基础上，配合内容哈希可以做完整性校验：正文发生任何字符变化，哈希值都会改变，能及时发现意外篡改或误覆盖。
第一次代码实验及输出
下面的最小实现用注册表维护多个版本，同时支持精确取用与最新版本解析。模板正文通过 str.format 的命名变量注入参数。
from dataclasses import dataclass
from typing import Dict, Tuple
@dataclass(frozen=True)
class PromptVersion:
major: int
minor: int
template: str
def key(self) –> Tuple[int, int]:
return (self.major, self.minor)
class PromptRegistry:
def __init__(self) –> None:
self.versions: Dict[Tuple[int, int], PromptVersion] = {}
def register(self, major: int, minor: int, template: str) –> None:
self.versions[(major, minor)] = PromptVersion(major, minor, template)
def latest(self) –> PromptVersion:
return self.versions[max(self.versions.keys())]
def render(self, major: int, minor: int, **params) –> str:
return self.versions[(major, minor)].template.format(**params)
registry = PromptRegistry()
registry.register(1, 0, "请总结以下文本：{text}")
registry.register(1, 1, "请用不超过{limit}字总结：{text}")
registry.register(2, 0, "你是摘要助手，请输出要点：{text}")
print(registry.latest().key())
print(registry.render(1, 1, limit=30, text="版本化模板"))
print(registry.render(2, 0, text="版本化模板"))
运行输出：
(2, 0)
请用不超过30字总结：版本化模板
你是摘要助手，请输出要点：版本化模板
输出显示：注册表自动把 (2, 0) 识别为最新版本；指定 (1, 1) 时能精确渲染出带长度限制的模板；指定 (2, 0) 时得到新的角色化指令。三个版本共存，互不覆盖。
工程化改进
上面的最小实现有一个隐患：PromptVersion 虽然是 frozen 的，但正文仍以普通字符串字段存在，后续逻辑若不当仍可能被替换；版本号也仅靠调用方自觉维护。工程化改进需要补齐四点。第一，用 frozen dataclass 承载模板，确保创建后不可变，修改只能通过新增版本完成。第二，用内容哈希做完整性校验，任何字符变化都会改变哈希值。第三，保留注册顺序，区分“最新版本”与“精确取用”两种语义，回滚时按精确版本取用，避免隐式降级。第四，把变更说明一并存储，便于事后审计。版本号采用元组而非字符串，可以避免 “1.10” 与 “1.9” 这类字符串比较带来的排序错误。
第二次代码实验及输出
下面的实现为每个模板计算 sha256 摘要，并通过比较正文判断版本间是否发生实质变化。
import hashlib
from dataclasses import dataclass
from typing import Dict, List, Tuple
def content_hash(text: str) –> str:
return hashlib.sha256(text.encode("utf-8")).hexdigest()
@dataclass(frozen=True)
class PromptTemplate:
version: Tuple[int, int]
body: str
class VersionedPrompts:
def __init__(self) –> None:
self.registry: Dict[Tuple[int, int], PromptTemplate] = {}
self.order: List[Tuple[int, int]] = []
def add(self, version: Tuple[int, int], body: str) –> None:
self.registry[version] = PromptTemplate(version, body)
self.order.append(version)
def get(self, version: Tuple[int, int]) –> PromptTemplate:
if version not in self.registry:
raise KeyError(version)
return self.registry[version]
def render(self, version: Tuple[int, int], **params) –> str:
return self.get(version).body.format(**params)
prompts = VersionedPrompts()
prompts.add((1, 0), "总结文本：{text}")
prompts.add((1, 1), "用不超过{limit}字总结：{text}")
prompts.add((2, 0), "你是摘要助手，请输出要点：{text}")
base = prompts.get((1, 1)).body
head = prompts.get((2, 0)).body
print("模板总数", len(prompts.registry))
print("渲染1.1", prompts.render((1, 1), limit=40, text="示例"))
print("渲染2.0", prompts.render((2, 0), text="示例"))
print("正文是否变化", base != head)
print("哈希长度", len(content_hash(head)))
运行输出：
模板总数 3
渲染1.1 用不超过40字总结：示例
渲染2.0 你是摘要助手，请输出要点：示例
正文是否变化 True
哈希长度 64
输出表明：注册表共有 3 个版本；1.1 与 2.0 的正文确实不同；哈希长度恒为 64，说明 sha256 摘要已生成，可作为完整性校验的指纹。
常见陷阱
第一，用字符串拼接生成模板。模板变量与真实内容混在一起，既难以审计，也容易在拼接时丢失版本信息。第二，只记录版本号、不记录正文。模板后续一旦被改写，仅凭版本号无法还原当时的真实输入，历史仍然不可复现。第三，把“最新版本”当作默认值。升级后旧评测、旧数据无法按原版本重跑，回归对比失去意义。第四，模板变量命名不一致。渲染时抛出 KeyError 才暴露问题，应当在发布前统一校验模板变量集合。第五，忽略哈希校验。模板被误改或合并冲突后仍静默上线，等问题爆发时已难以定位。
落地清单
- 版本号写入模板元数据，并在每次调用日志中记录实际版本；
- 模板正文不可变，任何调整都生成新版本；
- 渲染前校验模板变量集合是否完整，缺失即报错；
- 发布时计算并存储内容哈希，变更时自动比对；
- 回滚按精确版本取用，不做隐式降级；
- 评测、灰度、线上环境共用同一套版本号。
参考来源
- Python 官方文档：dataclasses — https://docs.python.org/3/library/dataclasses.html
- Python 官方文档：hashlib — https://docs.python.org/3/library/hashlib.html
- Python 官方文档：字符串格式化 — https://docs.python.org/3/library/string.html
👍 觉得有用就点个 赞 + 收藏，方便回头查阅；有疑问直接在评论区留言，我看到都会回。
🚀 本文属于 《可靠LLM应用工程》 系列，持续更新，关注不迷路。
📌 文章里的代码都能直接跑。想要可直接 clone 的完整工程 + 配套部署脚本 / 踩坑清单？评论一声或发邮件到 cj2664@qq.com，我免费发你。
如果你正好在做类似系统、或有工程化难题想找人做，也欢迎邮件聊一句——我按实际情况评估，能落地的就接单或出方案。评论和邮件都能直接找到我，不用跳别的平台。
