Prompt模板版本化记录变量与输出差异的流程

Prompt 调优最容易留下一个“看起来更好”的结果，却说不清到底改了哪一处。真正可复用的做法是把模板正文、变量快照、模型配置、输入样例集和输出评测拆成独立记录，再用一次运行编号把它们串起来。这样改模板时可以重放同一批输入，既看文本差异，也看质量、延迟和成本是否一起变化。

先把 Prompt 版本拆成五类对象

不要把一段最终 Prompt 当成唯一资产。模板正文应该有自己的版本号；业务变量保存脱敏后的键和值；模型记录名称、采样参数和系统指令；输入集记录样例来源与快照；评测记录则保存规则、指标和结论。Hugging Face 的 Chat Template 文档也把消息列表、角色内容和额外参数视为渲染输入，这说明“同一模板”并不等于“同一最终文本”。

用运行记录固定一次可重放实验

每次运行都生成一个不可变的 run_id，并把 template_version、variable_snapshot、model_config、dataset_version 和 rendered_prompt_hash 写进去。变量值可能包含用户信息，实际保存时应先脱敏或只保留稳定指纹；否则为了追踪差异反而扩大数据暴露面。

import hashlib
import json

def build_run_record(template_version, variables, model_config, dataset_version, output_text):
    # 只对稳定排序后的渲染输入计算指纹，避免字典顺序造成假差异
    snapshot = {"template": template_version, "variables": variables, "model": model_config}
    canonical = json.dumps(snapshot, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
    prompt_hash = hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
    return {
        "run_id": f"{template_version}-{prompt_hash}",
        "template_version": template_version,
        "variable_snapshot": variables,
        "model_config": model_config,
        "dataset_version": dataset_version,
        "rendered_prompt_hash": prompt_hash,
        "output_text": output_text,
    }

# 生产环境应把返回对象写入追加式 JSONL，而不是覆盖上一条运行记录
record = build_run_record("prompt-v7", {"tone": "简洁"}, {"temperature": 0.2}, "cases-v3", "示例输出")
print(json.dumps(record, ensure_ascii=False))

这个记录还可以增加 token 数、首字延迟、总耗时和人工评分，但字段要保持稳定。不要把“本次调用用了哪个版本”只写在日志文本里，否则后续很难按字段聚合。

差异比较要先固定输入，再分层看结果

比较 v6 和 v7 时，先让两版使用相同的输入集、相同的评测规则和明确的模型配置。第一层看渲染后的 Prompt 是否变化；第二层看输出文本的结构、关键字段和事实错误；第三层再看准确率、拒答率、延迟、Token 和费用。只看到一条回答变好，不能证明模板升级成功。

可以把每个样例的结果保存为一行，并增加 diff_type：prompt 表示渲染输入变化，content 表示回答内容变化，metric 表示评分变化，runtime 表示延迟或成本变化。对结构化输出，优先比较字段级结果；对长文本，再补充统一规则下的人工抽样。

用阈值和决策记录控制上线

评测结果最好同时写“通过条件”和“不可接受变化”。例如关键字段准确率不能下降，平均延迟允许小幅上升，Token 成本必须低于预算；对安全或合规相关输出，则以阻断项优先。阈值应绑定任务，不要用一个总分掩盖某一类样例全部失败。

上线记录至少包含 approved_template、评测运行范围、负责人、时间和回滚版本。线上服务读取批准指针，离线实验写入新版本目录；这样 v7 评测失败时，只需把指针切回 v6，不必从代码或聊天记录里找旧 Prompt。

常见问题

只保存最终 Prompt 文本够不够？

不够。变量、模型参数和输入集变化同样会改变输出，至少要保存它们的快照或稳定指纹。

输出差异很大时先改模板还是先换模型？

先固定模型和输入集重放模板，再固定模板比较模型；一次只改变一个主要变量，结论才可归因。

评测集是否需要每次都全部运行？

小改动可以先跑分层抽样，但合并或上线前应跑完整冻结集，并保留每个样例的结果。