高阶加餐 08｜Prompt 故障定位与可观测性：模型突然变差时，别再靠“重新写一遍 Prompt”解决

真正进入生产环境以后，Prompt 最大的问题不是"不会写"，而是：出了问题你根本不知道问题在哪。

很多人做 Prompt 调优时，流程是这样的：

text 复制代码

结果不好
→ 改 Prompt
→ 再试一次
→ 这次好像好了
→ 上线
→ 过几天又坏了
→ 再改 Prompt

这不是工程，这是碰运气。

只要你的 Prompt 已经被用于：

内容生产
客服
知识库
代码审查
Agent
数据抽取
工作流
企业自动化

你就必须面对一个现实：

同一个 Prompt 的输出质量，会受到很多外部变量影响。

例如：

用户输入结构变了；
模型版本升级了；
System Prompt 改了；
检索结果排序变了；
上下文长度变了；
工具返回字段变了；
Few-shot 被删了；
Temperature 被调整了；
上游清洗逻辑变化了；
后端解析器变严格了；
数据本身发生分布漂移；
模型供应商行为发生变化。

如果你没有可观测性，就只能把所有失败都怪到"Prompt 不够好"。

这篇讲一套真正可落地的方法：

让 Prompt 像代码一样可调试、可追踪、可复现、可定位、可回滚。

一、先建立一个概念：Prompt 故障，不等于 Prompt 本身有问题

线上大模型系统的最终输出，可以抽象成：

text 复制代码

最终结果
=
模型
× Prompt
× 输入
× 上下文
× 工具
× 检索
× 参数
× 解析器
× 运行环境

其中任何一项变化，都可能让结果变差。

所以当有人说：

text 复制代码

今天模型怎么突然变笨了？

你第一反应不应该是：

text 复制代码

我去把 Prompt 再写详细点。

而应该先问：

text 复制代码

到底是哪一个变量发生了变化？

这就是故障定位思维。

二、Prompt 可观测性到底要观察什么

建议至少记录 8 类信息。

1. Prompt 版本

必须记录：

text 复制代码

prompt_name
prompt_version
prompt_hash

例如：

text 复制代码

prompt_name: complaint_classifier
prompt_version: 1.4.2
prompt_hash: a81d3c7

为什么需要 hash？

因为有时候版本号没变，但有人偷偷改了 Prompt 文本。

Hash 可以直接发现：

text 复制代码

代码说是 v1.4.2
实际内容已经不是原来的 v1.4.2

2. 模型信息

至少记录：

text 复制代码

provider
model
model_version
reasoning_config
temperature
top_p
max_tokens

不要只记录：

text 复制代码

model=deepseek

你真正需要的是：

text 复制代码

provider: xxx
model: deepseek-xxx
temperature: 0.2
max_tokens: 2000

因为同一个 Prompt 在不同参数下也可能出现不同结果。

3. 输入快照

至少保存：

text 复制代码

input_length
input_type
input_hash
input_sample

敏感业务不要直接保存全部明文，可以：

脱敏
Hash
抽样
保存结构信息

核心目的是：

以后你能够知道这次失败到底输入了什么。

4. 上下文来源

如果用了记忆、RAG、历史摘要，就必须记录：

text 复制代码

context_sources
retrieved_docs
memory_version
history_length

否则你会遇到：

text 复制代码

同一个问题昨天回答对，今天回答错。

但实际上昨天检索到了 D1、D2，今天只检索到了 D3。

问题根本不在 Prompt。

5. 工具调用记录

Agent 场景至少记录：

text 复制代码

tool_name
arguments
result_status
latency
error_code
retry_count

否则最终回答错了，你无法知道：

是模型选错工具；
还是参数错；
还是工具本身返回了错误数据。

6. 模型原始输出

一定要保存：

text 复制代码

raw_model_output

不要只保存解析后的结果。

例如模型原始输出：

text 复制代码

{
  "score": "90分"
}

解析器可能修成：

json 复制代码

{
  "score": 90
}

如果只看最终数据，你会误以为模型一直输出得很好。

7. 解析结果

需要单独记录：

text 复制代码

parse_success
schema_valid
validation_errors

例如：

text 复制代码

parse_success: true
schema_valid: false
validation_errors:
- severity must be integer

这样你能立刻知道：

模型回答业务内容可能没错，只是格式不合格。

8. 最终业务结果

例如：

text 复制代码

accepted
rejected
human_corrected
user_retry
user_dislike

这是最终闭环。

没有业务反馈，你永远不知道：

text 复制代码

技术上"合法"的结果到底有没有用。

三、最重要的原则：每一次模型调用都要有 Trace ID

建议每个请求生成唯一：

text 复制代码

trace_id

例如：

text 复制代码

trace_id = 20260812-8f02c9e1

所有相关记录都挂在这个 ID 下：

text 复制代码

trace_id
├── 用户输入
├── Prompt 版本
├── 模型参数
├── RAG 检索结果
├── Tool Calls
├── Raw Output
├── Parsed Output
├── Validation
└── Final Result

这样线上有人说：

text 复制代码

这个回答为什么错了？

你不是靠猜，而是直接查这条 Trace。

四、一个推荐的 Prompt Trace 数据结构

可以采用：

json 复制代码

{
  "trace_id": "20260812-8f02c9e1",
  "task": "complaint_classifier",
  "prompt": {
    "version": "1.4.2",
    "hash": "a81d3c7"
  },
  "model": {
    "provider": "example",
    "name": "deepseek-model",
    "temperature": 0.2,
    "max_tokens": 2000
  },
  "input": {
    "length": 438,
    "hash": "b7c2..."
  },
  "context": {
    "documents": ["D1", "D7"],
    "memory_version": "m12"
  },
  "tools": [],
  "output": {
    "raw": "...",
    "parse_success": true,
    "schema_valid": false
  },
  "validation": {
    "errors": [
      "severity must be integer"
    ]
  },
  "latency_ms": 2410,
  "status": "failed"
}

这类结构才是真正的"Prompt 调试基础设施"。

五、模型回答错了，先做"故障分型"

不要一上来就改 Prompt。

先给失败打标签。

推荐最少使用下面 10 类。

类型 1：INPUT_ERROR

输入本身有问题。

例如：

text 复制代码

用户只写了"这个怎么弄"

但上下文里没有"这个"是什么。

这不是 Prompt 错，是信息不足。

类型 2：PROMPT_RULE_GAP

Prompt 规则缺失。

例如：

text 复制代码

用户问退款问题。
模型把它分类为 billing。

但业务真正希望：

text 复制代码

涉及退款必须进入 manual_review。

如果 Prompt 没写，这就是规则缺口。

类型 3：PROMPT_CONFLICT

Prompt 内部规则冲突。

例如：

text 复制代码

规则 A：尽量完整回答。
规则 B：不确定时必须拒答。

模型遇到证据不足时就可能随机偏向其中一个。

类型 4：CONTEXT_MISSING

关键上下文没进来。

例如：

text 复制代码

用户之前明确说"不使用 Redis"

但摘要里丢了这条。

模型后来再次推荐 Redis。

Prompt 没错，是上下文压缩错了。

类型 5：RAG_RETRIEVAL_ERROR

检索错了。

例如用户问：

text 复制代码

退款时效是多少？

检索却返回：

text 复制代码

登录帮助
账号注册

模型再强也很难答对。

类型 6：TOOL_SELECTION_ERROR

Agent 选错工具。

例如：

text 复制代码

用户要查真实余额

模型却没有调用余额查询工具。

类型 7：TOOL_RESULT_ERROR

工具本身返回异常。

例如：

text 复制代码

API 返回缓存旧数据。

模型只是忠实使用了错误数据。

类型 8：MODEL_BEHAVIOR_DRIFT

模型行为发生漂移。

典型表现：

同样 Prompt，格式遵守率下降；
拒答策略改变；
输出明显变长；
JSON 更容易多解释；
旧测试集大量同时失败。

这时候才应该怀疑模型升级或供应商行为变化。

类型 9：OUTPUT_FORMAT_ERROR

业务判断可能正确，但输出格式错。

例如：

json 复制代码

{
  "severity": "5"
}

Schema 要的是整数。

类型 10：PARSER_ERROR

模型输出其实合法，但你自己的解析器失败。

例如模型输出：

json 复制代码

{"name":"A"}

解析器因为编码、转义或类型实现 bug 报错。

这绝对不能甩锅给模型。

六、建立一个真正可用的"故障诊断 Prompt"

你可以让模型帮助做失败分析，但要给它完整材料。

模板：

text 复制代码

你是大模型应用故障诊断工程师。

你的任务不是重写 Prompt，而是先定位失败原因。

【本次任务】
{{TASK}}

【Prompt 版本】
{{PROMPT_VERSION}}

【实际 Prompt】
{{PROMPT}}

【模型配置】
{{MODEL_CONFIG}}

【用户输入】
{{INPUT}}

【上下文】
{{CONTEXT}}

【工具调用】
{{TOOLS}}

【模型原始输出】
{{RAW_OUTPUT}}

【Schema / 验收规则】
{{VALIDATION_RULES}}

【实际错误】
{{ERROR}}

请按以下类型判断主要原因：

- INPUT_ERROR
- PROMPT_RULE_GAP
- PROMPT_CONFLICT
- CONTEXT_MISSING
- RAG_RETRIEVAL_ERROR
- TOOL_SELECTION_ERROR
- TOOL_RESULT_ERROR
- MODEL_BEHAVIOR_DRIFT
- OUTPUT_FORMAT_ERROR
- PARSER_ERROR

输出：

1. primary_cause
2. secondary_causes
3. evidence
4. 是否需要修改 Prompt
5. 如果要修改，最小修改点
6. 如果不该改 Prompt，应修改哪个环节

禁止直接重写整套 Prompt。

这一句非常关键：

text 复制代码

禁止直接重写整套 Prompt。

否则模型很容易跳过诊断，直接给你重新写一版。

七、不要"修一次错一个地方"，要建立失败样本库

每次线上出现真实失败，都应该进入：

text 复制代码

failure_cases

例如：

text 复制代码

case_001
问题：退款投诉被误分到普通咨询
原因：PROMPT_RULE_GAP
修复：增加退款强制人工规则

下一次 Prompt 修改后，所有历史失败样本重新跑。

这就是：

Prompt 回归测试。

八、历史失败样本比"随便想几个例子"更有价值

为什么？

因为这些样本已经证明：

text 复制代码

你的真实系统确实会在这里失败。

所以测试集优先级建议：

text 复制代码

P0：历史线上事故
P1：高风险业务样本
P2：边界案例
P3：常规样本
P4：随机样本

不要反过来。

九、Prompt Diff：每次修改必须知道"改了什么"

Prompt 不能像文章一样：

text 复制代码

我感觉这版更顺。

推荐每次修改记录：

text 复制代码

Version: 1.4.2 → 1.4.3

Changed:
- 新增退款场景强制 need_human=true

Reason:
- case_037 退款投诉被模型判断为普通咨询

Expected impact:
- 提高退款场景召回率

Risk:
- 可能导致普通价格咨询被误判

Regression:
- 全部历史样本
- 退款边界集

这才叫工程变更。

十、最小修改原则：只修导致失败的那一层

假设失败原因是：

text 复制代码

模型经常把 severity 输出成字符串。

不要重写整个 Prompt。

只加：

text 复制代码

severity 必须为整数，不允许字符串。

然后回归。

这样你才能知道：

text 复制代码

到底是哪一个修改产生了效果。

十一、为什么"大改 Prompt"特别危险

一次同时修改：

角色；
任务描述；
示例；
输出格式；
规则；
顺序；
语气；

即使结果变好了，你也不知道：

text 复制代码

到底是哪一项有效。

如果变差，更难定位。

所以生产环境推荐：

text 复制代码

单变量修改
→ 回归
→ 记录
→ 再下一项

十二、建立 Prompt 健康指标

不能只看：

text 复制代码

用户有没有投诉。

可以持续监控：

格式指标

text 复制代码

JSON 合法率
Schema 通过率
字段缺失率
非法枚举率

业务指标

text 复制代码

任务准确率
拒答准确率
人工纠正率
用户重试率

运行指标

text 复制代码

平均 Token
平均延迟
重试率
工具失败率

稳定性指标

text 复制代码

相同测试集成功率
输出长度变化
格式漂移
模型版本前后差异

十三、最实用的告警：不要等用户发现

例如：

text 复制代码

过去 1 小时 JSON 合法率：
99.4% → 91.2%

应该自动告警。

或者：

text 复制代码

人工纠正率：
4% → 15%

也应该告警。

这种变化很可能说明：

Prompt 刚上线有问题；
模型行为变化；
上游输入结构变了；
检索结果异常。

十四、Shadow Test：新 Prompt 不要直接替换旧 Prompt

假设线上当前：

text 复制代码

Prompt V1

你开发：

text 复制代码

Prompt V2

不要直接：

text 复制代码

100% 用户 → V2

可以做：

text 复制代码

真实请求
├── V1 正常给用户
└── V2 后台影子执行

V2 的结果不展示给用户，只做比较。

比较：

text 复制代码

准确率
格式率
Token
延迟
拒答
失败样本

如果 V2 确实更好，再灰度上线。

十五、Canary 灰度：Prompt 也应该逐步发布

例如：

text 复制代码

V2：
1% 流量
→ 5%
→ 20%
→ 50%
→ 100%

每一步观察指标。

如果异常：

text 复制代码

立即回滚 V1

这比直接"全量替换 Prompt"安全得多。

十六、一定要保存 Prompt 的可回滚版本

至少保留：

text 复制代码

current
previous
stable

不要出现：

text 复制代码

昨天的 Prompt 被覆盖了，现在找不到。

生产 Prompt 最少应该有：

text 复制代码

版本号
发布时间
修改人
修改原因
测试报告
回滚目标

十七、DeepSeek 实战：模型突然开始输出 Markdown

假设系统要求：

json 复制代码

{
  "risk": "high"
}

之前一直正常。

某天开始输出：

text 复制代码

```json
{
  "risk": "high"
}
```

很多人的第一反应：

text 复制代码

把 Prompt 加强一下。

先别急。

正确排查流程：

第 1 步：查 Prompt 版本

是否刚改过？

第 2 步：查模型版本

供应商是否切了模型？

第 3 步：查参数

temperature、structured output 是否变化？

第 4 步：查失败比例

是单个案例，还是 30% 请求都变了？

第 5 步：跑固定回归集

旧 Prompt + 当前模型是否也失败？

如果：

text 复制代码

旧 Prompt 也突然大量失败

更像模型行为漂移。

如果：

text 复制代码

只有新 Prompt 失败

更像 Prompt 变更问题。

这就是可观测性的价值。

十八、DeepSeek 实战：知识库回答突然开始"编"

假设之前 RAG 很稳定。

今天用户问：

text 复制代码

退款多久到账？

模型开始回答：

text 复制代码

通常 3~5 个工作日。

但知识库没这个内容。

排查：

检查 1：检索结果

是不是原来能检索到退款制度，现在没检索到？

检查 2：Prompt

"资料不足必须拒答"规则还在吗？

检查 3：上下文

是不是检索资料被截断了？

检查 4：模型

同一套固定资料下，旧测试是否开始失败？

不同结果对应不同修复点。

不要所有情况都加一句：

text 复制代码

请不要编造。

十九、把"为什么失败"结构化保存

推荐每次事故写：

json 复制代码

{
  "case_id": "incident_20260812_001",
  "trace_id": "trace_xxx",
  "failure_type": "RAG_RETRIEVAL_ERROR",
  "severity": "high",
  "root_cause": "退款制度文档未进入 Top-K",
  "prompt_change_required": false,
  "fix": "调整检索 metadata filter",
  "regression_case_added": true
}

这会逐渐形成一套真正的模型应用经验库。

二十、Prompt 调试最忌讳的 8 件事

1. 只看最终答案

不看原始输出。

2. 不记录 Prompt 版本

出问题后无法复现。

3. 不记录模型参数

同样 Prompt 实际不是同样环境。

4. 一失败就改 Prompt

可能根本不是 Prompt 问题。

5. 一次改十处

无法判断因果。

6. 没有历史失败库

同一个 bug 反复回来。

7. 新 Prompt 直接全量上线

没有灰度。

8. 没有回滚

线上出事只能现场重写。

二十一、一个完整的 Prompt Debug SOP

可以直接给团队使用。

text 复制代码

STEP 1：定位 Trace ID

STEP 2：固定现场
- Prompt
- 模型
- 参数
- 输入
- 上下文
- 检索
- 工具
- Raw Output
- Parser Result

STEP 3：复现

STEP 4：故障分类
- Input
- Prompt
- Context
- Retrieval
- Tool
- Model
- Output
- Parser

STEP 5：找到 Root Cause

STEP 6：只修改真正的问题层

STEP 7：加入历史失败样本

STEP 8：全量回归

STEP 9：Shadow / Canary

STEP 10：监控

STEP 11：全量发布

STEP 12：保留可回滚版本

二十二、完整"Prompt 事故复盘模板"

text 复制代码

# Prompt Incident Review

事故编号：
发生时间：
影响任务：
Prompt 版本：
模型：
影响范围：

## 1. 用户表现

具体出现了什么错误？

## 2. Trace

输入：
上下文：
检索：
工具：
原始输出：
解析结果：

## 3. Root Cause

故障分类：

根本原因：

## 4. 为什么之前测试没有发现

测试缺口：

## 5. 修复

Prompt：
检索：
工具：
代码：
配置：

## 6. 新增回归案例

case_id：

## 7. 发布策略

Shadow：
Canary：
Rollback：

## 8. 防止再次发生

新增监控：
新增告警：
新增测试：

二十三、Prompt Observability 最终检查清单

上线前确认：

二十四、最终可复用的"Prompt 调试诊断母模板"

text 复制代码

你是大模型系统故障诊断工程师。

你的第一目标是定位根因，不是重写 Prompt。

【任务】
{{TASK}}

【Prompt】
版本：
{{PROMPT_VERSION}}

内容：
{{PROMPT}}

【模型配置】
{{MODEL_CONFIG}}

【输入】
{{INPUT}}

【上下文】
{{CONTEXT}}

【RAG】
{{RETRIEVAL}}

【工具】
{{TOOLS}}

【模型原始输出】
{{RAW_OUTPUT}}

【解析结果】
{{PARSED_OUTPUT}}

【校验错误】
{{VALIDATION_ERRORS}}

【期望结果】
{{EXPECTED}}

请完成：

1. 判断 primary failure type
2. 给出直接证据
3. 判断是否真正需要修改 Prompt
4. 如果需要，只给最小修改点
5. 如果不需要，指出应修改的真实环节
6. 给出应新增的回归测试案例
7. 给出上线前验证指标

故障类型只能从以下选择：

- INPUT_ERROR
- PROMPT_RULE_GAP
- PROMPT_CONFLICT
- CONTEXT_MISSING
- RAG_RETRIEVAL_ERROR
- TOOL_SELECTION_ERROR
- TOOL_RESULT_ERROR
- MODEL_BEHAVIOR_DRIFT
- OUTPUT_FORMAT_ERROR
- PARSER_ERROR

禁止在未完成根因判断前重写整套 Prompt。

结语

Prompt 真正进入生产后，最重要的能力已经不是：

text 复制代码

"能不能写出一个厉害的提示词？"

而是：

text 复制代码

"它出问题时，我能不能在 10 分钟内知道到底坏在哪？"

没有 Trace，没有版本，没有 Raw Output，没有失败分类，没有回归测试：

你拥有的只是一个"看起来能工作"的 Prompt。

当你开始具备：

可观测、可复现、可诊断、可测试、可灰度、可回滚

Prompt 才真正从一句文字，升级为可维护的工程组件。