提示词版本管理和Git结合怎么配置

文章导读
把提示词放进 Git 管理,真正要配置的往往是三样东西:目录与命名的约定、随文件一起提交的元数据(版本号、变量清单、归属人),以及能在日志里追溯的运行时版本标识。采用“放在共享盘里、靠文件名区分版本”的做法,基本上没法回退,也没法判断线上出问题的是哪一版。建议先把一个提示词目录按下面的骨架整理好,再接入 CI 校验和发布 tag。
📋 目录
  1. A 先确认当前场景和目标
  2. B 按这个顺序处理
  3. C 改完后怎么验证
  4. D 容易忽略的边界
A A

把提示词放进 Git 管理,真正要配置的往往是三样东西:目录与命名的约定、随文件一起提交的元数据(版本号、变量清单、归属人),以及能在日志里追溯的运行时版本标识。采用“放在共享盘里、靠文件名区分版本”的做法,基本上没法回退,也没法判断线上出问题的是哪一版。建议先把一个提示词目录按下面的骨架整理好,再接入 CI 校验和发布 tag。

提示词与 Git 结合,关键是让每个提示词都有稳定的 id、可读的版本文件和一份声明变量与当前版本的 manifest,并用 Git commit 或 tag 作为运行时版本标识写入日志。适合有一定量提示词、需要多人改动和回退的场景;如果提示词一天改十几次、需要线上热更新,或包含密钥等信息,就不适合全放在仓库里,需要拆分配置来源。

先确认当前场景和目标

先判断现在属于哪一类情况:提示词由固定几个人维护、改动频率不高、上线前有人 review,那么用 Git 管理,成本很低,收益也明确;提示词由运营直接在后台编辑、每次都要即时生效,那么 Git 更适合做“发布源”,也就是按版本发布,不宜当作“实时编辑入口”。这两种情况的处理方式不同,不要混着做。

需要先确认的几件事:

  • 提示词总数和改动频率,决定要不要按目录分组,以及是否需要 manifest 索引。
  • 提示词里有没有占位变量(如 {{order_id}}),变量名是否与代码里的传参一致。
  • 仓库里是否会出现密钥、内部数据、真实用户样例;一旦有,就必须先拆分出去。
  • 线上调用侧能否拿到并记录版本标识(commit 短哈希或 tag),拿不到就先补日志字段。

按这个顺序处理

第一步是确定目录结构。每个提示词一个目录,版本用文件区分,manifest 指向当前使用的版本:

提示词版本管理和Git结合怎么配置
prompts/
  support_triage/
    manifest.yaml
    v1.md
    v2.md
  order_summary/
    manifest.yaml
    v1.md

第二步是写 manifest,把版本、变量、归属人集中声明。下面是一份可替换的通用示例,字段名可以按团队习惯改:

id: support_triage
current: v2
owner: cs-platform
model: <模型名>
variables:
  - order_id
  - user_tier
change_note: 改动原因写在 PR 描述里,这里只留一句摘要

第三步是给提示词正文加上与 manifest 对齐的头部信息,方便单文件查看时也能确认身份:

提示词版本管理和Git结合怎么配置
---
id: support_triage
version: v2
variables: [order_id, user_tier]
---
你是一名客服助理,请结合订单 {{order_id}} 和用户等级 {{user_tier}} 给出处理建议。

第四步是加一个校验脚本,放进 CI 的必过检查。脚本只做两件事:manifest 指向的文件是否存在,正文里用到的变量和 manifest 声明的变量是否一致。这是一个通用骨架,按实际仓库路径替换即可:

import pathlib, re, sys, yaml

errors = []
for d in pathlib.Path("prompts").iterdir():
    if not d.is_dir():
        continue
    m = yaml.safe_load((d / "manifest.yaml").read_text(encoding="utf-8"))
    cur = d / f"{m['current']}.md"
    if not cur.exists():
        errors.append(f"{d.name}: current={m['current']} 对应文件不存在")
        continue
    used = set(re.findall(r"\{\{\s*(\w+)\s*\}\}", cur.read_text(encoding="utf-8")))
    declared = set(m.get("variables") or [])
    if used != declared:
        errors.append(f"{d.name}: 变量不一致 used={sorted(used)} declared={sorted(declared)}")

if errors:
    print("\n".join(errors))
    sys.exit(1)
print("ok")

第五步是把版本标识接到运行时。发布时打一个 tag(如 prompt-2024-xx 这类团队自定的命名),调用侧把 commit 短哈希和提示词 id 一起写进日志或追踪字段。下面只是拼接逻辑的骨架,不是某个 SDK 的真实接口:

import pathlib, subprocess

commit = subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], text=True).strip()
body = pathlib.Path("prompts/support_triage/v2.md").read_text(encoding="utf-8")
version_tag = f"support_triage@v2+{commit}"
# 调用模型时,把 version_tag 写入日志/追踪字段,正文另行传入

第六步是提交与评审约定:一次提交只改一个提示词、提交信息写清 id 和版本,保护主分支、要求 review,发布用 tag 而不是靠分支名表达状态。

提示词版本管理和Git结合怎么配置

改完后怎么验证

验证分三层,逐层确认即可:

  1. 本地或 CI 跑校验脚本,预期输出 ok、退出码为 0;再故意把正文里的 {{order_id}} 改成 {{orderid}},预期脚本报变量不一致并以非零退出,确认拦截生效。
  2. 用旧 tag 检出一次(例如 git checkout <上一个 tag>),再跑校验脚本,预期同样通过,说明历史版本仍可加载,回退路径可用。
  3. 触发一次实际调用,检查日志或追踪里是否出现 support_triage@v2+<commit> 这类标识;如果日志里只有提示词正文而没有版本标识,说明第五步没接上。

预期信号是:同一份提示词在仓库、运行日志、发布 tag 三处能对上同一个版本号。对不上就说明中间某一处是手工维护的,需要改成从同一来源取。

容易忽略的边界

  • 变量名是代码与提示词之间的约定,重命名变量必须同步改代码,否则校验脚本通过、运行时照样报错;建议变量改名和代码改动放在同一个 PR。
  • 提示词里不要写密钥、真实用户数据或内部业务规则原文;需要引用时用占位符,由运行时注入。
  • 不要把 Git 分支当作环境(dev/staging/prod 各一条长期分支),容易出现分支互相合并、环境和版本对不上;用 tag 或发布记录表达上线版本更清楚。
  • 模型参数(温度、最大输出长度)与提示词放在同一份 manifest 里便于对照,但两者变更节奏不同,参数调整不一定需要新提示词版本,版本号是否升要事先约定。
  • 如果提示词需要后台实时编辑、或一天改很多次,Git 这条路会变成频繁提交和频繁发布,此时更合适的是把 Git 当作基线版本,运行时配置另存,并保持两者可对比。
  • 回退建议:优先 git revert 到目标版本对应的提交,重新走一次发布;如果调用侧有提示词缓存,回退后要确认缓存已刷新,再观察日志里的版本标识是否变成目标版本。