把 Prompt 当作代码管理，每次修改有版本、有测试、有评审，上线后能追踪，出问题能回滚。
下面按开发、测试、发布和回滚组织流程。文中的数量、比例、时长和阈值是起步示例，执行前由团队确认。
| 阶段 | 负责人 | 要交付什么 | 进入下一步的条件 |
|---|---|---|---|
| 开发 | PM + MLE | Prompt、变更说明、本地测试结果 | Review 通过 |
| 测试 | MLE 执行，PM 验收 | 新旧版本对比报告 | 本次目标达到，关键指标达标 |
| 发布 | 指定发布负责人 | 发布记录、灰度观察结果 | 达到放量条件后全量 |
| 回滚 | 发布负责人 + MLE | 恢复验证、影响记录、修复计划 | 确认恢复，修复后重新测试 |
PM 负责业务需求和验收，MLE 指负责模型接入、评估和运行的工程人员，可由研发兼任。同一人可以兼任多个角色，执行前填好具体负责人。
1. 版本管理
Prompt 会影响应用的业务行为。改错一条规则，就可能让原本正确的回答或分类出错，因此修改前后都要留记录。
| 对比 | 传统代码 | Prompt |
|---|---|---|
| 变更影响 | 功能行为变化 | 模型行为变化（更不可预测） |
| 测试难度 | 自动化成熟 | 需人工 + 自动混合 |
| 版本回溯 | Git 标准操作 | 同时关联模型、参数及上下文配置 |
| 灰度发布 | 按版本分流 | 按 Prompt 及运行配置分流 |
没有版本控制的典型失败
场景 1：PM 在对话窗口改了 Prompt → 忘了同步到代码 → 线上和代码不一致 → 出问题无法排查
场景 2：上个版本 Prompt 效果更好，但找不到旧版本 → 只能凭记忆重写
场景 3：修改后直接覆盖线上版本 → 所有用户同时受影响 → 发现问题后找不到可恢复版本
版本管理方案
| 方案 | 适合情况 | 使用要求 |
|---|---|---|
| Git + Markdown | 研发维护为主 | 随提交保存模板、配置和测试结果 |
| 已有配置中心 | 已有配置发布流程 | 保留历史版本，设置修改和发布权限 |
| 专用平台（LangSmith/MLflow） | 多人编辑、独立发布和对比评估 | 使用平台的版本及环境管理能力 |
LangSmith 提供版本对比、环境晋升和回滚，MLflow 提供不可修改的 Prompt 版本及可切换的别名，可以直接复用这些能力。LangSmith 文档、MLflow 文档
材料放在哪里
采用 Git 时，在应用仓库中为每个 Prompt 建一个目录。下面以 support-intent 为例，文件名是本文采用的约定，可以沿用项目已有命名。
prompts/support-intent/
├── requirements.md # 需求、验收标准、负责人
├── prompt.md # Prompt 模板
├── version.md # 版本和运行配置
├── cases.json # 测试输入与预期结果
├── reports/
│ └── v1.1.md # 逐条测试结果、汇总、评审结论
└── releases/
└── v1.1.md # 发布、放量和回滚记录- 开始修改前，从当前稳定提交创建分支。
- 修改模板和相关配置，更新
version.md，把触发问题的案例补入cases.json。 - 将测试报告和变更一起提交评审，记录待测提交的完整 Git commit ID。
- 发布时记录实际运行的 commit ID 和配置版本，后续修改另建提交。
如果使用管理平台，把这些材料保存到对应的 Prompt、数据集、实验和发布记录中，用稳定 ID 相互关联。
版本记录模板
每次提交保存一份，发布时记录实际使用的版本。
名称 <Prompt 名称>
版本 <版本号>
维护人 <姓名>
修改时间 <日期和时间>
修改原因 <发现了什么问题>
修改内容 <改了哪些规则或示例>
运行配置 <模型标识、参数、知识库和工具配置版本>
关联代码 <应用代码 commit ID、输入输出格式版本>
验证记录 <测试集版本、报告位置、评审结论>
上一稳定版本 <可恢复的版本及相关配置>运行配置填写实际值或可追踪的配置版本，密钥通过现有凭据管理方式注入。引用的公共 Prompt 片段也固定版本，更新片段后重新测试使用它的任务。
2. 开发阶段
Prompt 编写流程
明确需求和验收标准 → Prompt 初稿 → 快速测试（5-10 例）→ Review → 固定待测版本
需求与验收模板
先填到 requirements.md，由 PM 和 MLE 确认，再编写 Prompt。
任务 <要完成什么，结果用于哪一步业务>
输入 <字段、来源、必填项、长度限制>
输出 <字段、类型、格式，以及接收结果的程序>
异常处理 <空输入、信息不足、无关输入时返回什么>
测试入口 <现有调试页面，或批量测试命令及执行位置>
本次修改目标 <要修复或改善的具体问题>
关键案例 <必须通过的案例 ID>
验收指标 <指标定义、通过门槛、允许的退化范围>
验收人 <姓名>例如，修改目标写成“将‘还没发货，我要退款’正确归入退款类”，对应案例 TC-012。验收时既检查这条案例，也检查原来的物流请求是否仍能正确分类。
Prompt 编写模板
任务、输入、约束和输出要求写清楚，角色和示例按任务需要补充。
## 系统角色
你是谁、能力边界、风格
## 任务指令
具体任务、输入参数、输出格式
## 约束条件
必须遵守的规则、内容安全限制
## 示例（Few-shot）
正常输入→期望输出
边缘输入→期望输出
## 输出格式
格式模板、必要字段编写原则
| 原则 | 反例 | 正例 |
|---|---|---|
| 明确任务 | ”分析这段文本" | "提取文本中的问题、原因和处理结果” |
| 具体指令 | ”总结一下" | "用 3 句话总结，每句 ≤20 字” |
| 输出约束 | ”返回结果” | 返回 JSON 对象，包含字符串字段 summary |
| 负面提示 | 省略 | ”不要编造事实，不确定就说无法确认” |
| 示例引导 | 省略 | ”正确输出示例：[示例]“ |
本地测试流程
步骤 1：准备 5-10 条用例（正常×5 + 边缘×2 + 异常×2）
步骤 2：在 Notebook / Gradio / Playground 运行
步骤 3：逐条对照预期结果，检查内容、格式和约束，记录失败原因
步骤 4：发现问题 → 修改 Prompt → 重复
将用例输入填入模板，使用 version.md 中记录的配置运行。每条保存“案例 ID、预期结果、实际输出、通过与否、失败原因”，放到本版本的测试报告中。评估依赖知识库或工具时，带上真实调用所需的资料和工具结果。
需要 JSON 输出时，优先使用接口支持的结构化输出能力，并做本地校验，具体见 结构化输出是什么：拿到 JSON 不等于拿到有效业务数据。
Review 检查清单
完整性
- 任务指令、输入变量、输出格式、约束条件写清楚？
- 包含失败处理（不确定时怎么办）？
正确性
- 指令准确表达需求？无歧义？示例无误？
- 敏感数据、提示注入和工具权限相关检查通过？
健壮性
- 处理了空输入、超长输入、无关输入、恶意输入？
可维护性
- 结构清晰？注释充分？统一模板格式？
PM vs MLE 在 Review 中的角色
| Review 方面 | 主要评审者 | 关注点 |
|---|---|---|
| 业务准确性 | PM | 是否反映业务需求 |
| 用户体验 | PM | 输出是否符合用户期望 |
| 技术可行性 | MLE | 是否高效、稳定 |
| 安全性 | MLE + 安全 | 提示注入等风险 |
| 格式正确性 | MLE | 输出是否可解析 |
Review 通过后保存版本和评审结论。后续再修改，就生成新版本并更新测试结果。
3. 测试阶段
回归测试
每次 Prompt 修改都运行固定测试集，检查原来能通过的场景是否受影响。
- 固定本次使用的
cases.json版本，数量按业务覆盖和评估成本增加。 - 选择线上稳定版本和候选版本，运行同一份用例，尽量保持模型和其他配置一致。
- 保存逐条结果，计算指标，与当前稳定版本 Baseline 比较。
- 复核失败案例和关键场景，由 PM 与 MLE 确认通过或退回。
首次上线时，先用人工确认的预期结果验收，保存通过的版本作为后续 Baseline。生成结果波动较大时，对关键用例重复运行，并保存每次结果。
测试报告模板
保存到 reports/v1.1.md。先填写报告信息，再附逐条结果和汇总表。下面的数字用于演示报告格式。
测试时间 <日期和时间>
Baseline <稳定版本及 commit ID>
候选版本 <版本及 commit ID>
运行配置 <两版各自的模型、参数和相关配置>
测试集 <版本及案例数>
评估规则 <规则或评分 Prompt、评分模型的版本>
运行次数 <每条案例的运行次数，重试规则>
执行人 <姓名>
验收人 <姓名>
结论 <通过 / 退回，原因和待处理案例 ID>| 测试项 | Baseline | 新版本 | 变化 | 通过 |
|---|---|---|---|---|
| 准确率 | 87.5% | 91.2% | +3.7 个百分点 | ✅ |
| 格式合规 | 95.0% | 98.0% | +3.0 个百分点 | ✅ |
| 幻觉率 | 4.2% | 2.1% | -2.1 个百分点 | ✅ |
| 长度合规 | 92.0% | 88.0% | -4.0 个百分点 | ❌ |
每项是否通过，按测试前确认的门槛填写。上表长度合规未通过，先判断它是否属于必须满足的条件。必须满足时退回修复，允许取舍时由验收人记录接受理由，其他关键门槛仍需通过。
对比测试（旧 vs 新）
- 随机抽 50 条用例
- 用新/旧 Prompt 分别生成输出
- 隐藏版本信息、随机交换展示顺序后盲评
- 按准确度、有用性、风格、安全性评分
- 统计偏好
质量门禁
| 条件 | 标准 | 说明 |
|---|---|---|
| 回归测试 | 所有核心指标达标 | 不可绕过 |
| 对比测试 | 本次目标达到，其他退化在约定范围内 | 按关键场景分别检查 |
| 安全测试 | 约定的安全用例全部通过 | 关键项不可绕过 |
| 人工评审 | PM 与 MLE 确认验收结论 | 重要变更安排独立复核 |
4. 发布阶段
发布流程
Review 和回归通过 → 保存发布版本 → 部署 Staging → 验证 → 灰度 → 全量 → 监控
发布前检查
Staging 是预发布环境。在这里从应用正常入口发起请求，检查实际输入、模型配置、输出解析和后续业务步骤。
- 待发布版本与测试通过的版本一致，报告和验收结论可查。
- 正常输入、信息不足和历史失败案例已走通完整流程。
- 已记录当前线上版本，确认有权限切回且相关依赖可用。
- 已填写灰度范围、观察人、监控窗口、放量与回滚条件。
- 日志能够查询到实际加载的版本，告警能送达负责人。
发布记录模板
保存到 releases/v1.1.md，每次放量在同一记录中补充时间、范围和观察结论。
发布时间 <日期和时间>
发布人 <姓名>
原线上版本 <版本和运行配置>
本次发布版本 <版本、commit ID、运行配置>
验收报告 <报告位置或实验 ID>
灰度范围 <账号名单或分组规则、比例>
观察负责人 <姓名>
放量条件 <观察时长、有效请求数、关键场景及指标门槛>
回滚条件 <触发条件、统计窗口、处理负责人>
恢复入口 <配置项、平台操作位置或已有回滚流程>
观察结论 <继续观察 / 放量 / 回滚，以及依据>灰度方案
| 方案 | 实现 | 优点 | 缺点 |
|---|---|---|---|
| 按用户 ID hash | stable_hash(user_id) % 100 | 用户分组稳定 | 小样本时比例可能不均 |
| 按流量比例 | 随机采样 x% | 简单 | 体验不一致 |
| 按用户层级 | 名单/付费层级 | 可控风险 | 选择偏差 |
灰度放量节奏
| 阶段 | 流量 | 时长 | 检查点 |
|---|---|---|---|
| 内部灰度 | 内部测试账号名单 | 1 天 | 关键流程通过，无严重错误 |
| 小范围 | 5% | 1-2 天 | 核心指标稳定 |
| 中范围 | 20%→50% | 2-3 天 | 监控无异常 |
| 全量 | 100% | 持续 | 持续监控 |
同一会话或工作流固定版本。按比例分组时，可以使用稳定哈希计算桶号，桶号小于 5 的用户进入 5% 灰度组，其余使用稳定版本。表中的 stable_hash 表示由应用选定并保持一致的哈希算法。
每次放量前检查观察时长、有效请求量和关键场景覆盖，样本不足时继续观察。版本通过检查后再调整分组比例，并确认实际请求已按新比例运行。
灰度监控指标
| 类别 | 指标 | 告警阈值 |
|---|---|---|
| 质量 | 负面反馈率 | > 前 7 天均值 + 2σ |
| 质量 | 重新生成率 | > 前 7 天均值 + 2σ |
| 性能 | 延迟 P99 | > 3s |
| 技术 | 错误率 | > 0.5% |
| 安全 | 内容举报 | 收到举报立即核查严重程度和影响 |
告警配置中写明统计窗口和最低样本量。历史均值用于发现异常，放量时同时比较同期灰度组与对照组。σ 是同口径历史指标的标准差，样本稀疏时结合请求明细判断。
灰度期间每日检查清单
- 检查核心监控指标
- 检查用户反馈（应用内、客服、社交媒体）
- 随机采样 20-30 条对话，人工检查
- 对比新旧版本指标差异
- 决定是否继续放量
发布记录保存上线时间、版本、范围、操作人和回滚目标。调用日志关联实际版本、模型配置、耗时、用量和执行结果，输入输出按需脱敏并限制访问。
收到负面反馈后，用请求 ID 找到实际版本、输入、工具结果和错误记录，确认问题出在哪一步。把可复用的失败输入脱敏，补充人工确认的预期结果和案例 ID，加入下一版测试集。
5. 回滚策略
触发条件
| 优先级 | 条件 | 响应 | 回滚方式 |
|---|---|---|---|
| P0 | 安全/合规违规 | 立即 | 全量回滚 |
| P0 | 核心指标相对基线下降 > 20% | 立即 | 全量回滚 |
| P1 | 负面反馈率 > 5% | 30 分钟 | 按用户回滚 |
| P1 | 错误率 > 1% | 30 分钟 | 全量回滚 |
| P2 | 非核心指标持续下降 | 观察 24h | 按需 |
回滚方案
| 方案 | 速度 | 影响 | 适用 |
|---|---|---|---|
| 全量回滚 | 目标 < 5 分钟 | 全部用户 | P0 |
| 按用户回滚 | 目标 < 10 分钟 | 受影响用户 | P1 |
| 自动回滚 | 目标 < 2 分钟 | 全部用户 | 已配置并演练自动回滚 |
| 降级处理 | 目标 < 30 分钟 | 部分功能 | 关闭异常步骤或转人工 |
回滚操作步骤
- 停止放量，记录异常和影响范围。
- 确认目标版本的模型、代码、知识库和工具仍兼容。
- 将灰度比例归零或切回稳定版本，检查各实例和缓存是否已经更新。
- 从应用入口运行关键案例，用请求 ID 查询实际版本，再查看错误率与业务指标，确认恢复。
- 检查在途任务，补救已写入的数据或已执行的外部操作。
- 发送回滚记录，安排修复和复盘。
回滚耗时通过演练确认。旧版本不可用时，执行降级方案。
回滚沟通模板
回滚时间：YYYY-MM-DD HH:MM
回滚版本：v1.0 ← v1.1
原因：[描述]
影响：全量/灰度用户
状态：<处理中 / 已恢复>
验证：<验证请求 ID、实际版本、关键案例和指标结果>
跟进：
- [ ] 根因分析
- [ ] 修复问题
- [ ] 重新走测试和灰度流程回滚后复盘要点
- 问题描述：什么 Prompt 版本？什么问题？影响多少用户？
- 根因分析：Review 为何没发现？测试覆盖不足？放量太快？
- 改进措施：测试流程、Review checklist、灰度策略如何更新？
- 行动计划：Owner 和 ETA
6. Prompt 测试基础设施
评估数据集设计
[
{
"id": "TC-012",
"category": "历史失败",
"input": { "question": "还没发货，我要退款", "history": [] },
"expected": { "category": "退款" },
"difficulty": "简单"
}
]保存为 cases.json，新增案例时在数组中追加对象，每条使用唯一 ID。这里的 TC-012 与需求中的案例对应，input 字段根据任务的输入约定填写。应用读取 input 发起调用，评估时再拿实际输出与 expected 比较。预期结果只供评分使用。
开发时经常使用的案例与发布验收案例分开维护。若线上知识库或工具数据会变化，测试时保存所需的数据快照或固定结果，完整业务验证时再检查实际服务。
覆盖维度
| 维度 | 比例 | 说明 |
|---|---|---|
| 正常输入 | 60% | 最常见请求 |
| 边缘输入 | 20% | 超长、特殊字符、多语言 |
| 异常输入 | 15% | 空输入、无关输入 |
| 恶意输入 | 5% | Prompt 注入、越权 |
评估指标
| 指标 | 计算 | 目标 |
|---|---|---|
| 准确率 | 正确数/总数 | ≥90% |
| 格式合规 | 合规数/总数 | ≥95% |
| 完整率 | 完整数/总数 | ≥90% |
| 一致性 | 同一问题多次运行，关键事实或业务决定一致的比例 | 按任务设定 |
| 安全用例通过率 | 通过的安全用例数/安全用例总数 | 关键用例 100% |
在 requirements.md 中确定指标口径。例如分类准确率按“类别正确的次数 / 全部执行次数”计算，调用失败和解析失败计为未通过，另列失败率。统计格式合规率时也保留全部执行作为分母。若采用重试，固定重试次数，同时记录首次结果和重试后的结果。
开放式回答的完整率需要列出必答项，幻觉率需要规定哪些事实要核验、按回答还是陈述计数。只统计适用于当前任务的指标，并分别查看关键业务类别。原文依据是否充分、是否完整，按规则评分并保留判断理由。
自动化 vs 人工评估
| 方式 | 检查内容 | 执行要求 |
|---|---|---|
| 程序检查 | 格式、字段、枚举、长度，答案明确的分类和提取 | 保存规则和预期答案 |
| 模型评分 | 回答相关性、依据充分性、表达 | 固定评分规则及模型，用人工样本校准 |
| 人工评估 | 业务争议、关键失败、最终验收 | 给出评分依据，有争议时复核 |
这些方法可以组合使用，按指标选择评估方式。LangSmith 评估文档
混合策略推荐
| 层次 | 方法 | 频率 |
|---|---|---|
| 日常回归测试 | 自动化 | 每次提交 |
| 每日快照 | 自动化全量 + 人工抽样 | 每日 |
| 版本发布前 | 自动化全量 + 关键场景、失败案例和抽样人工复核 | 每次发布 |
| 灰度期间 | 自动化实时 + 人工抽样 | 持续 |
评估基础设施架构
Prompt 版本控制 → 自动化评估管线 → 人工评估平台
↓ ↓
回归测试+对比测试 标注界面
↓ ↓
评估报告 + 仪表盘
↓
决策 → 发布/回滚
7. 管理视角
Prompt 责任归属
| 场景 | 负责人 | 理由 |
|---|---|---|
| 初版原型 | PM | 业务理解最重要 |
| 性能优化 | MLE | 需模型推理深入理解 |
| 用户体验/语气 | PM + 设计 | 用户感知角度 |
| 安全防护 | MLE + 安全 | 安全专业知识 |
推荐模式：PM 写初版 → PM + MLE Review → MLE 技术优化 → PM 验收 → 共同上线
Review 制度
- 谁可以提交：PM + MLE（需培训）
- Review 团队：PM × 1 + MLE × 1
- 流程：MR/PR 提交 → 24h 内初审 → 修改后 24h 内终审 → 合并
- 紧急修改由有发布权限的人操作，保存恢复目标、运行关键案例并快速复核，发布后立即验证，24h 内补齐完整评审和回归报告
生产 Prompt 监控
| 指标 | 级别 | 条件 | 响应角色 |
|---|---|---|---|
| 负面反馈率 | P1 | > 5% | PM |
| 隐式负向信号 | P1 | > 均值 + 2σ | PM + MLE |
| 错误率 | P1 | > 1% | MLE |
| 延迟 P99 | P1 | > 3s | MLE |
| 安全事件 | P0 | 任何违规 | PM + 安全 |
| 成本异常 | P2 | 上升 > 20% | PM |
最佳实践清单
| 实践 | 优先级 |
|---|---|
| 所有 Prompt 进版本控制 | ★★★★★ |
| 每次修改有 Review | ★★★★★ |
| 评估集与 Prompt 一起版本化 | ★★★★☆ |
| 灰度发布而非全量 | ★★★★★ |
| 修改后持续观察，满足时长和有效样本要求 | ★★★★☆ |
| 建立 Prompt 模板库 | ★★★☆☆ |
| 每月 Review Prompt 效果 | ★★★☆☆ |