Prompt Debugging

当 LLM/Agent 输出质量异常时，从最终组装 Prompt、消息顺序、上下文来源、截断/token budget、工具结果与版本差异建立证据链，区分 Prompt 本身、Context assembly、Model 与 Tool/Runtime 问题。

#debug #evergreen #ai

[!info] related notes

所属 MOC: Observability Engineering MOC

Prompt 生命周期: Prompt Management

运行证据: Trace

评估: Agent Testing 与 Evals

方法论: Hypothesis-Driven Debugging

Prompt Debugging

症状

同一任务突然回答变差；
模型忽略关键约束；
明明检索到资料，却没有利用；
Agent 重复调用错误工具；
上下文很长，但答案反而更差；
改了 Prompt 后不知道到底是改善还是随机波动。

第一原则：先看最终模型真正收到什么

不要只看源码里的 template。

真正需要记录的是本次 run 的 assembled input：

system/developer instructions；
user message；
retrieved context；
memory；
tool results；
conversation history；
schema/tool definitions；
truncation/summarization 后的实际内容。

Prompt Debugging 的第一步是把“我以为发给模型的内容”变成“模型实际看到的内容”。

第二步：检查 Context Assembly

常见根因：

关键证据根本没被召回；
正确证据被错误排序到很后面；
上下文被截断；
旧 memory 覆盖当前事实；
多个 instruction 互相冲突；
tool result 太长，把真正任务挤出有效上下文。

这类问题不是“改 system prompt 两句话”就能解决。

第三步：检查指令冲突与优先级

逐层问：

有哪些 instruction source？
哪些是 always-on？
是否存在相互冲突的要求？
task-specific instruction 是否被更高层规则覆盖？
是否把例子误写成了强规则？

如果模型行为稳定地偏向错误方向，instruction conflict 往往比“模型随机”更值得先查。

第四步：看 Token / Truncation，但不要迷信 Token 数

Token 分布可以帮助发现：

history 占比过大；
tool schema 太多；
retrieved chunks 重复；
system prompt 不必要膨胀。

但：

token 多不自动意味着坏，token 少也不自动意味着好。

真正要问的是这些 token 是否与当前决策有关。

第五步：把 Model 与 Prompt 问题分开

做最小对照：

same model + old prompt
same model + new prompt
same prompt + model A
same prompt + model B

一次只改变一个变量。

否则你无法知道提升来自 Prompt、模型版本、temperature、tool policy 还是 retrieval。

第六步：工具与 Runtime 也可能是根因

例如模型选择了正确工具，但：

tool schema 描述误导；
tool result 缺字段；
runtime 把 observation 截断；
retry 后重复注入旧结果；
tool error 被包装成正常文本。

这时继续改 Prompt 会掩盖真正系统问题。

第七步：用 Eval 而不是主观挑样本

如果 Prompt 是重要产品资产：

建一组代表性输入；
固定 judge/rubric；
记录 prompt version；
记录 model/runtime version；
比较 pass/fail / score distribution；
把线上失败加入 regression dataset。

详见 Agent Testing 与 Evals。

诊断矩阵

证据	优先怀疑
最终 prompt 根本没有关键事实	retrieval/context assembly
事实存在但被冲突 instruction 覆盖	prompt hierarchy
长 history 后才出错	truncation/context pollution
同 prompt 换模型明显改善	model capability/behavior
模型选对工具但结果仍错	tool/runtime contract
单个例子好、dataset 退化	overfitting / prompt regression

迁移检查

场景：一个客服 Agent 昨天还能正确引用退款政策，今天开始频繁编造。

不看正文：

首先要保存哪份 run-level 证据？
怎样证明问题在 retrieval，而不是 model？
怎样检查 instruction conflict？
为什么只看总 token 数不够？
如何设计一次只改变一个变量的对照实验？
最终怎样把这个线上失败变成 regression eval？