提示词版本怎么管理：样例、变量与回归集一起提交

提示词不要只存在于聊天记录或某个同事的脑子里。比较稳妥的做法是把它当成一份小型工程契约：模板负责指令，变量文件负责输入边界，模型参数负责运行条件，回归集负责判断改动是否真的变好，四者和变更说明放进同一次 Git 提交。这样下次出现“昨天效果很好，今天却复现不了”时，至少能先定位是提示词、输入、模型还是参数变了。

先把提示词拆成模板、变量和参数契约

我在项目里最先会拆掉一件事：把系统指令、用户输入、示例答案和温度等参数混在一段长字符串里。混合写法短期方便，长期却无法看出一次提交到底改了哪一层。建议至少保留一个模板文件、一个变量契约和一个模型配置文件。

模板只表达任务和输出要求，变量契约写清名称、类型、是否必填、长度边界与示例值，模型配置则记录模型标识、温度、最大输出长度和服务端默认值。版本号可以使用 Git commit，也可以在文件中增加业务版本，但不要只写“最新版”。

# variables.yaml：变量契约用注释说明边界，示例值必须脱敏
name: customer_reply
variables:
  - key: customer_message
    type: string
    required: true
    max_length: 2000
    example: "订单配送延迟，客户希望知道处理进度"
  - key: tone
    type: enum
    required: true
    allowed: [简洁, 安抚, 专业]
    example: "专业"

模板里只引用约定好的变量名，并把输出格式写成可检查的规则。例如要求返回 JSON，就同时规定字段、枚举值和缺失字段的处理方式，不要只说“请结构化输出”。变量名一旦进入回归集，改名应视为兼容性变更。

让样例和回归集成为提交的一部分

样例不是为了展示最漂亮的结果，而是为了覆盖真实任务的分支。一个客服回复提示词至少应有正常咨询、信息缺失、情绪激烈、超长输入和要求越权的样例。每条样例保存输入、硬约束、期望结构和检查方式；涉及客户数据时先使用脱敏文本。

回归集可以用 JSONL 保存，方便逐行追加和定位单条失败。下面的结构是数据契约示意，字段解释放在代码块外，避免把注释塞进严格 JSON。

{"id":"missing-order-id","input":{"customer_message":"包裹还没有收到","tone":"专业"},"checks":["不得编造物流单号","必须提出补充信息","输出为JSON"]}
{"id":"angry-customer","input":{"customer_message":"已经等了很久，请明确处理时间","tone":"安抚"},"checks":["先承认影响","不承诺无法确认的时间","输出为JSON"]}

每条结果还应带上输入哈希、提示词 commit、模型标识和参数快照。这样“同一个样例”才真的可比：输入变了，不能把结果差异归因于模板；模型变了，也不能只说是提示词优化成功。

如果使用带提示词管理能力的平台，可以把本地 Git 作为审查和回滚入口，再把已批准版本同步到平台。Google Cloud 的 Vertex AI 文档提供了提示词版本列表和读取指定版本的示例，官方地址是 https://cloud.google.com/vertex-ai/generative-ai/docs/samples/generativeaionvertexai-prompt-list-prompt-version。平台版本和 Git commit 最好互相记录，而不是各自生成一套无法对应的编号。

用同一批输入比较旧版和新版

回归执行的重点不是追求一个总分，而是先检查硬约束，再看格式稳定性、事实风险、人工抽检和成本。硬约束失败时，即使新答案读起来更顺，也不应直接发布。对于开放式文本，可以把不可违反的规则变成可判断的检查；无法自动判断的部分保留人工复核标记。

const cases = loadRegressionCases();
const promptVersion = process.env.PROMPT_COMMIT;

for (const item of cases) {
  // 输入哈希用于确认新旧结果使用的是同一份脱敏样例。
  const inputHash = sha256(JSON.stringify(item.input));
  const result = await callModel({
    // 版本、模型和参数一起落账，避免只保存最终文本。
    promptVersion,
    input: item.input,
    model: process.env.MODEL_NAME,
    temperature: 0.2
  });

  // 硬约束失败先记为失败，不用“整体感觉不错”覆盖它。
  const checks = checkConstraints(result.text, item.checks);
  await appendJsonl('results.jsonl', {
    id: item.id, inputHash, promptVersion,
    model: result.model, checks, output: result.text
  });
}

结果账本不要保存不必要的个人信息，也不要把完整敏感输出上传到公共日志。对长文本可以保存摘要、字段级检查结果和受控存储的引用；发布评审看的是可解释证据，不是把所有原文复制到评论区。

一次提交要能解释、比较并回退

目录不必复杂，但提交边界要稳定。一个实用的最小结构如下：

prompts/customer-reply/
├── prompt.md          # 系统指令和输出格式
├── variables.yaml     # 输入变量契约
├── model.yaml         # 模型与采样参数
├── regression.jsonl    # 脱敏回归集
└── CHANGELOG.md       # 修改原因、风险和回滚说明

提交说明写“减少订单场景中的无依据承诺，补充缺失信息样例”，比写“优化提示词”有用得多。发布评审可按下面的清单决定：

Git 的 annotated tag 适合标记准备发布的提示词版本，临时试验则用普通分支或 commit 即可。不要为了“保持 v1 不变”强行移动已经共享出去的标签；如果旧版本已经被消费，新的修订应使用新的版本名，并在变更说明里写兼容影响。

常见问题

提示词只保存 Git commit，不保存模型参数可以吗？

不建议。温度、最大输出长度、模型标识和系统默认值都可能影响结果；缺少这些信息，回归结果无法解释。

回归集是不是越大越好？

先保证覆盖关键分支和失败边界，再逐步增加样例。几十条高质量、可重复的样例通常比大量重复的正常输入更适合定位变化。

平台自带的提示词版本和 Git 应该二选一吗？

不必二选一。Git 适合审查、协作和回滚，平台版本适合运行时读取与权限管理；用 commit、平台版本号和发布时间建立映射即可。