第1882篇：那次因为Prompt变更导致的P0故障——细节决定成败
第1882篇：那次因为Prompt变更导致的P0故障——细节决定成败
很多人觉得Prompt是软配置，改一改无所谓，顶多效果变差一点。
直到我们经历了那次P0故障，我才彻底改变了这个认知。
故障经过：一个"无害"的措辞修改
事情发生在一个普通的工作日上午。产品经理找到我，说用户反馈AI客服的回复"太生硬"，希望语气更亲切一些。这个需求听起来完全正常，于是我们的Prompt工程师对系统提示词做了一次措辞上的调整。
原来的Prompt中有一段是这样的：
你是一个专业的客服助手。回答用户问题时，请严格按照以下JSON格式输出：
{
"answer": "回答内容",
"category": "问题分类",
"confidence": 0.0-1.0之间的数字,
"needEscalate": true或false
}
不要输出JSON以外的任何内容。修改之后变成了：
你是小慧，一个温暖贴心的客服助手。用自然、亲切的语气回答用户的问题，让用户感受到被关心。
回答时请按照以下格式：
{
"answer": "你的回答",
"category": "问题类型",
"confidence": 置信度（0到1之间）,
"needEscalate": 是否需要转人工（true/false）
}两个版本一对比，修改点有三处：增加了角色设定，换了更"人性化"的措辞，还把"不要输出JSON以外的任何内容"这句话删掉了。
修改完之后，Prompt工程师在测试环境里测了十几条用例，回复效果很好，语气确实亲切了不少，就上线了。
上线后的头一个小时，看起来一切正常。然后，告警来了。
故障现象：系统开始大批量抛异常
告警显示，我们的AI客服后端开始大量抛出JSON解析异常。错误日志里满屏都是：
com.fasterxml.jackson.core.JsonParseException: Unexpected character ('我' (code 25105))
at [Source: (String)"我理解您现在的心情，这确实让人感到不便。针对您的问题...
{
"answer": "已为您记录，将在24小时内处理",
...
}"; line: 1, column: 2]模型不再"严格按照JSON格式输出"了，而是先输出了一段自然语言，然后才输出JSON。这导致我们的解析代码直接崩溃。
而且，不是所有响应都这样。大概有40%的请求，模型会先说一段话再输出JSON；剩下60%还是正常的纯JSON。这种不稳定性比"全部出错"更难处理，因为偶发性故障比稳定性故障难排查得多。
更糟糕的是，needEscalate字段的值开始出现奇怪的形式。原来是true或false，现在偶尔会出现"是"、"需要"这样的中文字符串，导致我们的Boolean解析直接抛出类型异常。
系统的错误率在一小时内升到了35%，客服工单开始积压，已经构成P0事故。
深层原因：Prompt是代码，不是文案
在做故障根因分析的时候，我对着那两个Prompt版本想了很久。
表面上看，问题是删掉了"不要输出JSON以外的任何内容"这句话，加了角色设定之后模型变得"话多了"。但实际上，问题比这复杂。
根本原因一：把Format约束和Persona设定混在了一起，产生了冲突。
当你告诉模型"你是一个温暖贴心的助手"，同时又要求它"输出纯JSON"，这两个指令存在张力。模型的"温暖贴心"倾向会促使它先表达共情，然后再给出结构化结果。我们在测试时没有发现这个问题，是因为测试用例都是中性问题，没有触发共情场景。
根本原因二：注释式说明替代了强制约束。
原版本的"不要输出JSON以外的任何内容"是一个明确的禁止指令。新版本的"请按照以下格式"是一个建议性措辞，对模型的约束力弱得多。这一字之差，在大模型输出这件事上影响是巨大的。
根本原因三：confidence字段的格式说明模糊了。
原版本写的是"0.0-1.0之间的数字"，新版本写的是"置信度（0到1之间）"。这个括号里的中文说明，偶尔会让模型输出"0.85（高置信度）"这种带注释的格式，同样导致解析失败。
核心教训：Prompt变更需要工程化管理
这次故障让我彻底意识到，Prompt不是文案，是代码。
一段控制输出格式的Prompt，其重要性不亚于一段数据处理代码。修改它需要同等级别的审查、测试和发布流程。
我们当时的Prompt管理方式是：Prompt直接写在代码里的常量，或者放在配置文件里。修改Prompt就是修改配置，走的是配置变更的流程，而不是代码变更的流程。配置变更的测试要求比代码变更宽松很多。
事故之后，我们建立了一套Prompt工程化管理流程：
第一步：Prompt版本化
每个Prompt都有独立的版本号，变更历史完整可追溯。
@Entity
@Table(name = "prompt_version")
public class PromptVersion {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String promptKey; // 唯一标识，如 "customer_service_system"
private Integer version; // 版本号
private String content; // Prompt内容
private String changeNote; // 变更说明
private String author; // 修改人
private Boolean isActive; // 是否当前生效版本
private LocalDateTime createdAt;
// 回滚到某个版本只需要把isActive切换
}第二步：Output Schema强校验
对于所有要求结构化输出的Prompt，必须有对应的Schema定义，并且在运行时做校验。
public class StructuredOutputValidator {
private final ObjectMapper objectMapper = new ObjectMapper();
/**
* 从LLM响应中提取有效JSON，支持模型在JSON前/后附加文字的情况
*/
public String extractJson(String rawResponse) {
// 尝试直接解析
if (isValidJson(rawResponse.trim())) {
return rawResponse.trim();
}
// 查找第一个 { 和最后一个 }
int start = rawResponse.indexOf('{');
int end = rawResponse.lastIndexOf('}');
if (start == -1 || end == -1 || start >= end) {
throw new InvalidOutputException("No valid JSON found in LLM response: " + rawResponse);
}
String candidate = rawResponse.substring(start, end + 1);
if (isValidJson(candidate)) {
log.warn("LLM output contained extra text outside JSON, extracted successfully");
return candidate;
}
throw new InvalidOutputException("Failed to extract valid JSON from: " + rawResponse);
}
/**
* 验证JSON是否符合预期的Schema
*/
public <T> T parseAndValidate(String json, Class<T> targetClass) {
try {
T result = objectMapper.readValue(json, targetClass);
Set<ConstraintViolation<T>> violations = validator.validate(result);
if (!violations.isEmpty()) {
throw new SchemaValidationException("Output validation failed: " + violations);
}
return result;
} catch (JsonProcessingException e) {
throw new InvalidOutputException("Failed to parse LLM output as " + targetClass.getSimpleName(), e);
}
}
}
// 对应的输出类，用注解做校验
public class CustomerServiceResponse {
@NotNull
@NotBlank
private String answer;
@NotNull
@NotBlank
private String category;
@NotNull
@DecimalMin("0.0")
@DecimalMax("1.0")
private Double confidence;
@NotNull
private Boolean needEscalate;
}第三步：Prompt变更测试套件
每个Prompt必须对应一组测试用例，覆盖各种边缘场景。Prompt变更时，必须跑通所有测试用例才能上线。
@SpringBootTest
public class CustomerServicePromptTest {
@Autowired
private LlmService llmService;
@Autowired
private StructuredOutputValidator validator;
// 测试用例：普通查询
@Test
public void testNormalQuery() {
String response = llmService.callWithPrompt(
CUSTOMER_SERVICE_PROMPT,
"我的订单什么时候发货？"
);
CustomerServiceResponse parsed = validator.parseAndValidate(
validator.extractJson(response),
CustomerServiceResponse.class
);
assertNotNull(parsed.getAnswer());
assertNotNull(parsed.getCategory());
assertFalse(parsed.getNeedEscalate()); // 普通查询不应该触发转人工
}
// 测试用例：触发共情的投诉场景（这类场景最容易让模型"话多"）
@Test
public void testComplaintScenario() {
String response = llmService.callWithPrompt(
CUSTOMER_SERVICE_PROMPT,
"我真的很生气，你们的快递已经丢失了，客服还不解决！"
);
// 即使是投诉场景，也必须返回纯JSON
String json = validator.extractJson(response);
CustomerServiceResponse parsed = validator.parseAndValidate(
json, CustomerServiceResponse.class
);
assertTrue(parsed.getNeedEscalate()); // 投诉应该触发转人工
}
// 测试用例：confidence必须是数字，不能是文字
@Test
public void testConfidenceIsNumeric() {
String response = llmService.callWithPrompt(
CUSTOMER_SERVICE_PROMPT,
"请问退款需要多少天？"
);
String json = validator.extractJson(response);
CustomerServiceResponse parsed = validator.parseAndValidate(
json, CustomerServiceResponse.class
);
assertTrue(parsed.getConfidence() >= 0.0 && parsed.getConfidence() <= 1.0);
}
}第四步：灰度发布和自动回滚
Prompt变更不能直接全量上线，必须走灰度流程。而且要配置自动回滚条件。
@Service
public class PromptABTestService {
@Autowired
private PromptVersionRepository promptRepo;
@Autowired
private MetricsService metricsService;
/**
* 根据灰度比例决定使用哪个版本的Prompt
*/
public String getActivePrompt(String promptKey, Long userId) {
PromptABConfig config = abConfigRepo.findByPromptKey(promptKey);
if (config == null || !config.isExperimenting()) {
return promptRepo.findActiveVersion(promptKey).getContent();
}
// 根据userId做稳定的流量分割
int bucket = (int) (userId % 100);
if (bucket < config.getNewVersionPercent()) {
return promptRepo.findVersion(promptKey, config.getNewVersion()).getContent();
} else {
return promptRepo.findVersion(promptKey, config.getBaseVersion()).getContent();
}
}
/**
* 定时检查新版本指标，如果出现劣化则自动回滚
*/
@Scheduled(fixedDelay = 60000)
public void checkAndAutoRollback() {
List<PromptABConfig> experiments = abConfigRepo.findAllRunning();
for (PromptABConfig exp : experiments) {
double newVersionParseErrorRate = metricsService.getParseErrorRate(
exp.getPromptKey(), exp.getNewVersion(), Duration.ofMinutes(10)
);
double baseVersionParseErrorRate = metricsService.getParseErrorRate(
exp.getPromptKey(), exp.getBaseVersion(), Duration.ofMinutes(10)
);
// 如果新版本解析错误率超过旧版本2倍，自动回滚
if (newVersionParseErrorRate > baseVersionParseErrorRate * 2
&& newVersionParseErrorRate > 0.05) {
log.error("Prompt {} new version {} parse error rate too high ({} vs {}), auto rollback!",
exp.getPromptKey(), exp.getNewVersion(),
newVersionParseErrorRate, baseVersionParseErrorRate);
rollbackExperiment(exp);
alertService.sendAlert("Prompt自动回滚",
String.format("Prompt %s 新版本解析错误率 %.1f%%，已自动回滚",
exp.getPromptKey(), newVersionParseErrorRate * 100));
}
}
}
}关于"强制格式输出"的技术方案
除了Prompt工程化管理，我们还在技术层面加了一道保险：使用支持结构化输出的API模式。
OpenAI的response_format、Claude的tool_use模式，都能在一定程度上保证输出格式的稳定性。
// 使用OpenAI的JSON模式
public CustomerServiceResponse callWithStructuredOutput(String userMessage) {
ChatCompletionRequest request = ChatCompletionRequest.builder()
.model("gpt-4o")
.messages(List.of(
new SystemMessage(CUSTOMER_SERVICE_PROMPT),
new UserMessage(userMessage)
))
.responseFormat(ResponseFormat.JSON_OBJECT) // 强制JSON输出
.temperature(0.3) // 降低随机性
.build();
String rawResponse = openAiClient.call(request).getContent();
return validator.parseAndValidate(rawResponse, CustomerServiceResponse.class);
}但要注意，即使用了JSON模式，也不代表字段值的格式是对的。模型可能输出合法的JSON，但confidence字段的值是"高"而不是0.85。Schema级别的校验仍然是必要的。
一些反思
这次事故之后，团队内部有一场很有意思的讨论：产品提的需求（让AI更亲切）本身有没有错？
没有错。但执行的方式有问题。
正确的做法是：在Persona设定和Format约束之间建立明确的优先级。让模型"温暖亲切"可以体现在answer字段的内容里，而不是让整个输出格式变得"温暖亲切"。
这两件事是可以分离的：
你是小慧，一名温暖的客服助手。
[重要：你的所有输出必须是且只能是合法的JSON格式，不包含任何JSON以外的文字]
在JSON的answer字段中，用温暖、亲切的语气回答用户的问题。
在回答投诉类问题时，answer字段应先表达理解和共情，再给出解决方案。把"亲切"限制在数据字段内，而不是让它影响整个输出结构。这才是正确的Prompt设计思路。
现在我们团队里有一条不成文的规矩：任何包含输出格式约束的Prompt，修改时必须保留"不要输出格式以外的内容"这类硬约束，哪怕改了一个字，也要重新跑完整测试套件。
这条规矩不优雅，但它救过我们好几次。