跳到主要内容

AI 应用失败样本库

AI 应用项目最常见的问题不是“完全不能运行”，而是看起来能跑，但在某些输入下不稳定。失败样本库的作用是把这些问题分层记录下来，帮助你知道应该回到哪一层排查。

这个页面不是替代具体章节，而是一个索引。遇到问题时，先判断失败属于 LLM API、Prompt、RAG、Agent、工具、安全还是部署，再回到对应章节细查。

怎么记录一个失败样本​

建议每个失败样本至少包含这些字段：

字段说明
用户输入触发失败的真实问题或任务
预期结果系统本来应该输出什么或执行什么
实际结果系统实际怎么回答或怎么行动
失败层级LLM API / Prompt / RAG / Agent / Tool / Safety / Deploy
相关日志request_id、trace、retrieved_docs、tool_call 等
初步原因你认为最可能的问题点
修复动作准备改什么
回归测试如何确认以后不会再犯

一个失败样本如果没有日志，就很难复盘；一个失败样本如果没有回归测试，就很容易下次再出现。

LLM API 层失败​

现象优先排查修复方向
请求偶发失败timeout、rate limit、网络错误、服务端错误增加超时、有限重试、错误分类和 fallback
成本突然升高prompt_tokens、completion_tokens、上下文长度压缩上下文、减少重复历史、记录 usage
延迟明显变慢模型选择、top-k、重试次数、网络状态限制重试、缓存结果、拆分同步和异步任务
输出为空或格式异常raw output、错误码、响应解析逻辑保留原始响应，统一响应结构
不知道哪次调用出了问题request_id 和日志字段缺失统一记录 model、prompt_version、latency、error

API 层失败通常先看日志，而不是先改 Prompt。如果连请求是否成功、用了多少 token、耗时多少都不知道，后面很难定位。

Prompt / 结构化输出失败​

现象优先排查修复方向
JSON 解析失败是否有额外解释文字、括号是否闭合要求只输出 JSON，增加解析失败重试
字段缺失schema 必填项是否清楚在 Prompt 中列出 required 字段
字段类型不稳定数字、布尔、数组是否被写成文本明确类型和示例，增加校验器
分类标签漂移枚举值是否固定给出允许值，禁止自造分类
改了 Prompt 后旧样本变差没有固定测试集建 Prompt 版本和回归测试样本

Prompt 问题不要只靠“再写清楚一点”解决。更稳的做法是：schema、示例、校验、失败样本和回归测试一起做。

RAG 层失败​

现象优先排查修复方向
知识库有答案但没命中chunk、query、embedding、关键词匹配调整切块、加混合检索或 query rewrite
正确资料排得靠后top-k 原始结果、score、rerank 前后对比增加 rerank，调整混合检索权重
命中了资料但回答漏条件context packing、prompt、答案格式保留关键条件，要求逐条引用
引用和答案对不上source_refs、引用片段、claim做 citation check，禁止无证据结论
版本或来源错metadata filter、source_origin、日期字段加过滤条件和来源优先级

RAG 失败最重要的是分清：是没有找对，还是找对了但没有用好。前者看检索日志，后者看 context 和生成约束。

Agent / 工具层失败​

现象优先排查修复方向
Agent 选错工具工具名、description、候选工具数量改 schema，减少无关工具，加入工具选择日志
工具参数错误arguments、参数校验、错误返回增加校验器和结构化错误
Agent 一直循环max_steps、停止条件、observation 是否重复设置最大步数、无新增信息时停止
工具失败后直接崩溃safe_dispatch、retryable、fallback区分可重试和不可重试错误
最终结果无法解释trace 缺失记录 goal、step、action、arguments、observation、next_decision

Agent 失败不要只看最终答案。真正要看的，是每一步为什么这样行动，以及观察结果如何影响下一步。

安全与权限失败​

现象优先排查修复方向
Agent 执行了不该执行的动作工具权限、风险分级、人工确认高风险工具默认确认或禁用
外部文档诱导越权是否把外部内容当成指令标记外部内容不可信，工具层做权限限制
日志泄露敏感信息日志字段、脱敏策略API key、隐私数据和内部资料脱敏
用户没有真正确认风险确认文本是否清楚展示动作、对象、参数、风险、回滚方式
出问题后无法追责audit_log 缺失记录 request_id、工具名、参数、确认人、结果

安全问题不能只靠模型自觉。系统应该用权限、白名单、确认、审计和回滚来保证边界。

部署与线上运行失败​

现象优先排查修复方向
本地能跑，线上失败环境变量、依赖版本、路径、权限写清部署配置，使用 .env.example
API key 失效或泄露密钥管理、日志、前端暴露后端代理调用，日志脱敏，轮换密钥
高并发下不稳定限流、队列、超时、重试加 rate limit、异步任务和降级策略
线上成本不可控token 统计、缓存、用户配额成本监控、请求限额、模型分级
用户反馈无法进入改进没有反馈字段和样本收集保存 thumbs、纠错文本和失败样本

部署失败通常不是单纯代码问题，而是配置、权限、运行时和监控共同决定的。

失败样本复盘模板​

## 失败样本标题

### 用户输入

### 预期结果

### 实际结果

### 失败层级

### 相关日志

### 初步原因

### 修复动作

### 回归测试

### 是否已解决

建议每个阶段项目至少保留 3 个失败样本。作品集级项目最好能展示：修复前是什么，修复后指标或样例怎样变化，还有哪些失败没有解决。