Skip to content

提示工程:从试错到可维护 ​

本篇要点:把提示词从「群里随手改的一段话」变成有结构、有版本、有回归测试的工程产物,做到改坏之后十分钟内能定位并回滚。 前置:上一章讲过调用方式、token 预算和结构化输出,这一章默认你已经能发出一个带 messages 的请求,也会用 json.loads 校验返回值。

为什么需要它 ​

先看一个几乎每家公司都会重演的过程。

我们给一个电商客户做退款助手,提示词最初是产品经理写在文档里的一段话,大概两百字。上线第一周,客服主管说「语气太硬,加一句亲切点」;第二周,运营说「退款规则变了,把七天改成签收后七天」;第三周,风控说「用户一提投诉就转人工」。这些话都很合理,于是提示词被改了六次,每次都直接改在服务器上的一个环境变量里,改完重启生效。

第七版上线当天,工单系统开始报错:json.decoder.JSONDecodeError。追下去发现,第 5 次改动时有人在结尾加了一句示例,示例里写的是「好的,我先帮您确认一下」,而这段话模型会当成输出格式的一部分照抄,于是 JSON 前面多了一个「好的」。

再想回滚,才发现没有第三版了。环境变量只留了最后一次的值,改动记录散在三个群里,没有人说得清哪一版最好,也没有人说得出第七版到底比第三版差在哪——大家只是「感觉最近答得不太对」。

这一章要解决的就是这件事:让提示词像代码一样有结构、有版本、有测试。听起来比随手调一句麻烦,实际上它省下的是每一次「到底哪次改动导致的」的排查时间。

版本口径:截至 2026 年 11 月,主流厂商都把「系统提示」和「用户消息」分开传(OpenAI 的 role: system / developer,Anthropic 顶层的 system 参数,见 OpenAI 对话文档 与 Anthropic Messages API)。模板引擎方面,Python 工具链里 Jinja2 仍在维护,但下面例子只用标准库的字符串替换——大多数场景用不上模板引擎,少一个依赖就少一处渲染差异。

核心概念 ​

四段式:角色、任务、约束、示例 ​

一段能维护的提示,通常能拆成四块,顺序固定。

角色(role / persona)作用域最小,一句话说清「你是谁、管什么范围」,比如「你是电商售后助手,只处理退款与退货」。它不是用来夸模型的,「你是一位世界级专家」这类话除了占 token 没有别的作用,反而让模型把范围放得过宽。

任务(task)用动词开头,一句话说清输入到输出:「根据用户描述判断是否符合退款条件,给出下一步操作」。

约束(constraints)是唯一能被程序检查的部分,所以必须写成可判定的条件:只输出 JSON、字段见 schema、无法判断时取 need_info、不得承诺到账时间、提到投诉时取 escalate。「回答要专业、要贴心」不是约束,是无法判定的愿望。

示例(examples)是规格的一部分,下一节单独讲。

类比:这四段像给新人的一张工单。角色是岗位说明,任务是这次要做的事,约束是红线,示例是「上一单是这么处理的」。四样都给,新人第一次就能做对;只给一句「你看着办」,做出来的东西一定跑偏。

反例:把所有内容揉成一段长文,约束埋在第 5 句和第 11 句中间。「如果信息不足就反问」这句写在示例之后,而示例本身从不反问,模型学的是示例,于是它从不反问。

Few-shot:示例是规格,不是数量 ​

few-shot(少样本示例)指的是在提示里给几条「输入 → 期望输出」的配对,让模型照着做。它的效果比描述强得多——模型真正模仿的对象是示例,不是形容词。

所以示例要按「覆盖」来选,不是按数量堆。四条能覆盖一类任务:一条最典型的、一条边界(信息不全)、一条该拒答或转人工的、一条格式最复杂的(嵌套字段最多的)。二十条几乎一样的示例只会让模型学会抄最后一条,还额外占掉几百个 token。

约束(constraint)和示例之间要一致。约束说「不得承诺到账时间」,示例里就不能出现「三天内到账」,否则模型信示例不信托词。

反例:示例里的字段写 orderNo,而下游 schema 是 order_no,模型有相当概率跟着示例走,你的校验器每次都拒。

提示复用与版本化:把提示当代码 ​

提示复用(prompt reuse)指把提示做成带变量的模板,一份模板服务多个入口,而不是每个接口抄一份。版本化(versioning)指每次改动都留下可 diff、可回滚的记录。

具体做法很朴素:提示放在仓库的 prompts/<场景>/v3.yaml,文件头写 version、model、variables、changelog,正文用 占位。渲染时先检查变量是否齐全,缺了直接抛错——不检查就会渲染出字符串 None 发给模型,而模型会很认真地跟你讨论一个叫 None 的订单。

一次只改一类东西。改语气就别动 schema,改规则就别动示例。混合改动之后,回归集出现红灯你分不清是哪一半造成的。

反例:把提示放进后台的富文本框,让运营直接编辑。听起来灵活,代价是没有 diff、没有版本号、没有回滚,出问题只能靠回忆和截图。

失败模式与回归 ​

失败不是一种。把它分成四类,处理方式完全不同:

失败模式典型症状先查哪里修法
格式失败解析报 JSONDecodeError示例与约束是否冲突、有没有开 schema 约束加 schema 校验 + 重试,示例只留 JSON
约束违反超长、答了范围外的问题、承诺时效约束是否排在长上下文的中段约束前置、拆成枚举、加后置检查
内容错误编造政策条款、算错金额该信息是否在提示里根本没有补资料或转工具,别让它猜
不稳定同一输入多次结果摇摆示例互相矛盾、温度设置删矛盾示例、固定采样参数、比对结构而非全文

回归(regression)就是拿一批固定输入跑一遍,看断言是否还过。断言只检查结构和你真正在意的规则:能解析吗、必需字段在吗、该拒答的拒了吗、有没有出现禁止的措辞。别断言全文相等,模型每次措辞都会变,全文比对的结果是天天红灯,两周后就没人看了。

样本从真实日志里抽,二十到五十条就够起步,覆盖上面四类失败各几条。跑在 CI 里,提示一改就触发。

一条提示的生命周期 ​

图 2-1 一条提示从模板到线上的完整路径:渲染、校验、回归、灰度、采样回流

如图 2-1 所示,线上采样不是可选的一步,它是下一版提示的输入。没有这条回流,回归集几个月后就和真实分布脱节了,测试全绿而线上照旧出问题。

动手实践 ​

三步:把提示做成模板、给它配回归集、改一次看回归怎么报警。

第一步,建模板并让它在缺变量时失败。新建 prompts/refund/v3.yaml 里的正文部分,这里直接放进脚本方便跑:

python
import re

TPL = """你是一名电商售后助手,只处理退款与退货相关问题。

【任务】
根据用户描述判断是否符合退款条件,并给出下一步操作。

【约束】
1. 只输出 JSON,字段见 schema,不要任何解释性文字。
2. 无法判断时 verdict 取 need_info,并在 missing 里列出缺的信息。
3. 不得承诺具体到账时间,只能引用 policy_days。
4. 用户提到投诉或曝光时,verdict 取 escalate。

【示例】
用户:东西收到就坏了,能退吗
输出:{"verdict":"refund","reason":"质量问题","missing":[]}

用户:我不想要了
输出:{"verdict":"need_info","reason":"需确认是否在无理由期内","missing":["下单日期"]}

今天的政策:签收后 {{policy_days}} 天内可无理由退货。
用户:{{question}}"""

def render(**variables) -> str:
    declared = set(re.findall(r"\{\{(\w+)\}\}", TPL))
    missing = declared - variables.keys()
    if missing:
        raise KeyError(f"模板变量缺失:{sorted(missing)}")
    return re.sub(r"\{\{(\w+)\}\}", lambda m: str(variables[m.group(1)]), TPL)

print(render(question="耳机三天前买的,能退吗", policy_days=7).splitlines()[0])
try:
    render(question="耳机三天前买的,能退吗")
except KeyError as e:
    print("KeyError:", e)

预期输出:

text
你是一名电商售后助手,只处理退款与退货相关问题。
KeyError: "模板变量缺失:['policy_days']"

注意最后那行:漏传 policy_days 没有变成一段含糊的回答,而是在发请求之前就炸了。这个失败越早越好,早到不用花钱。

第二步,配回归集。四条样本,覆盖典型、边界、转人工、范围外四种情况。断言只看结构,不看措辞。

python
import json
from dataclasses import dataclass

@dataclass
class Case:
    q: str
    expect: dict

CASES = [
    Case("收到的锅裂了,怎么退", {"verdict": "refund"}),
    Case("我不想要了", {"verdict": "need_info"}),
    Case("再不退款我就去平台投诉", {"verdict": "escalate"}),
    Case("你们老板手机号多少", {"verdict": "out_of_scope"}),
]

def check(reply: str, expect: dict) -> tuple[bool, str]:
    try:
        data = json.loads(reply)
    except json.JSONDecodeError as e:
        return False, f"parse 失败: {e}"
    for key, value in expect.items():
        if data.get(key) != value:
            return False, f"{key}={data.get(key)!r} 期望 {value!r}"
    if "到账" in reply and "天" in reply:
        return False, "承诺了到账时效"
    return True, "ok"

def run(question: str) -> str:
    ...  # 渲染 TPL 并调用模型,返回原始文本

for case in CASES:
    ok, msg = check(run(case.q), case.expect)
    print(f"{'PASS' if ok else 'FAIL'}  {case.q}  {msg}")

预期输出(第三条是故意留的真失败:加约束之前,它被判成 refund):

text
PASS  收到的锅裂了,怎么退  ok
PASS  我不想要了  ok
FAIL  再不退款我就去平台投诉  verdict='refund' 期望 'escalate'
PASS  你们老板手机号多少  ok

第三步,做最小改动并观察。约束 4 加上之后重跑,第三条转绿,其他三条不受影响——这就是「一次只改一类」的好处。如果同时改了语气和规则,红灯出现时你分不清是谁的问题。改动完成后把 version 从 v2 提到 v3,changelog 写一行「新增投诉转人工规则,示例补一条边界」,git diff 就是这次的全部内容。

常见误解 ​

以为提示词越长越稳,多写一句不会坏事。 约束在长提示里会被稀释,尤其在中间位置。加一段前先问:这段是替换了某句,还是净增?净增的每一句都在挤压别的句子。改完必须跑回归,别靠「我读了一遍觉得没问题」。

以为 Few-shot 越多越好。 示例是模型真正在模仿的东西,五条精选的覆盖比三十条雷同的重复有效得多,也便宜得多。堆数量还有个副作用:示例彼此矛盾的几率上升,模型开始摇摆,你把它归因成「模型不稳定」。

以为温度设为零,输出就固定,所以不用回归。 服务端不承诺逐字一致,混合专家模型的路由、批处理的合并都会让结果有差异。回归要比对字段和规则,用「通过率」而不是「字符串相等」来判断好坏。《评估与可观测性:效果怎么证明》会把这件事扩成完整的评估体系。

小结 ​

  • 提示拆四段:角色定范围、任务说清输入输出、约束必须是可判定的、示例按覆盖选而不按数量堆。
  • 示例的效力大于描述。约束和示例冲突时,模型跟示例走,所以两者必须一起改。
  • 提示是模板:变量声明在文件里,缺变量在渲染阶段就失败,别让 None 进上下文。
  • 提示要版本化:进仓库、能 diff、能回滚,一次只改一类东西。
  • 回归集从真实日志抽样,二十到五十条起步,断言结构与规则而非全文;改提示必跑,红灯先回滚再排查。

相关主题 ​

提示能把「说清楚」解决掉,但提示解决不了「拿到实时数据」。用户问「这个订单发货了吗」,你把提示写得再好,模型也只能编。《工具调用:Function Calling 设计》 工具调用:Function Calling 设计 讲怎么把接口交给模型调用,让工具描述、参数 schema 和错误返回都变成它能读懂的信号。