RAG 回答错误时如何用 awesome-llm-apps 的 RAG Failure Diagnostics Clinic 归类失败模式并得到最小修复建议

RAG 回答错误时如何用 awesome-llm-apps 的 RAG Failure Diagnostics Clinic 归类失败模式并得到最小修复建议

【免费下载链接】awesome-llm-apps100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-llm-apps

RAG 问答系统出了错误答案时，常见的应对是“加更多上下文”或“换一个更好的模型”，但这类建议很难指出真正的问题环节。awesome-llm-apps 仓库中的 RAG Failure Diagnostics Clinic 针对这个场景：把一个真实的 RAG bug 描述交给 LLM，让它把故障归类到一套固定的失败模式（P01–P12）中，并给出一个最小结构化修复建议（针对检索、索引、路由、评估或基础设施的改动），而不是空泛的提示词调整。它不依赖特定框架，README 明确说明该模式可以适配 LangChain、LlamaIndex、自建微服务等各种技术栈。

适用前提：

• Python 3.9 或更高版本；
• 任意OpenAI 兼容的 chat completion 端点的 API key（例如OPENAI_API_KEY对应https://api.openai.com/v1，也可以通过OPENAI_BASE_URL指向自己的代理）；
• 对 RAG 管线、日志和常见故障模式有基本了解。

准备：安装依赖并配置 API 凭据

从 awesome-llm-apps 仓库根目录进入教程目录并安装依赖，requirements.txt 只有一个依赖：

cd rag_tutorials/rag_failure_diagnostics_clinic pip install -r requirements.txt

依赖内容为openai>=1.6.0。

然后设置 API key 环境变量（推荐方式）。脚本默认使用https://api.openai.com/v1和模型gpt-4o，如需自定义端点或模型，用OPENAI_BASE_URL和OPENAI_MODEL覆盖：

export OPENAI_API_KEY="sk-..." # 可选：使用自定义端点时 # export OPENAI_BASE_URL="https://your-proxy.example.com/v1" # export OPENAI_MODEL="gpt-4o-mini"

如果不想用环境变量，也可以不设置OPENAI_API_KEY——启动脚本时它会通过getpass在终端交互式地提示输入 key。

执行诊断：启动脚本并选择故障描述

在rag_tutorials/rag_failure_diagnostics_clinic目录内运行：

python rag_failure_diagnostics_clinic.py

脚本会打印当前使用的 base URL 和模型名，然后进入一个简单的文本界面，让你选择本轮要诊断的故障：

[1] Example 1 — retrieval hallucination (P01 style) [2] Example 2 — startup ordering / dependency not ready (P10 style) [3] Example 3 — config or secrets drift (P11 style) [p] Paste my own RAG / LLM bug

三个内置示例分别对应：FAQ 里没有任何加密货币内容、但模型自信地声称支持比特币支付（检索幻觉/grounding drift）；Kubernetes 部署后 api-gateway 在最初几分钟内对 vector-db 连接超时并返回 500（启动顺序/依赖未就绪）；本地.env有SECRET_RAG_KEY而生产环境漏配导致部署后 500（跨环境配置漂移）。

选择p则粘贴自己的 bug 描述，以一行空行结束输入；如果粘贴后内容为空，脚本会提示No bug description detected, aborting this round.并跳过本轮。

每轮诊断结束后会询问Debug another bug? (y/n):，输入y继续诊断下一个 bug，输入其他任何内容退出会话。

12 个失败模式：P01–P12

模型被要求从固定的 12 个模式中选择，不能自创新的模式 ID。这个模式库定义在 脚本源码 的PATTERNS列表中，README 给出的对照表如下：

这个模式库是有意做成“小型、可改”的：README 建议根据你的生产事故增删或拆分模式，每个 bug 恰好映射一个主模式，最多附带两个次选候选。

读取诊断结果：控制台输出与 JSON 报告

每轮运行，模型以 temperature 0.2 被调用，回答会直接打印到控制台，结构化的 Markdown 固定包含四个部分（由系统提示词约束）：

• Primary pattern— 恰好一个主模式 ID（P01–P12）；
• Secondary candidates (optional)— 最多两个次选候选；
• Reasoning— 简短的要点式推理说明；
• Minimal structural fix— 最小结构化修复建议，约束为对检索、索引、路由、评估、工具或基础设施的改动，明确禁止“加更多上下文”“换更好的模型”这类泛化建议。

同时，每次运行都会在工作目录写出rag_failure_report.json文件。写入成功的确认信息是控制台打印的Saved report to rag_failure_report.json。报告内容来自 rag_failure_diagnostics_clinic.py，包含三个字段：

{ "bug_description": "…原始 bug 文本…", "model": "…本轮使用的模型名…", "assistant_markdown": "…模型的完整诊断回复…" }

这就是判断一轮诊断是否完成的依据：控制台出现四段式诊断，且报告文件被写入。README 建议把多份报告提交到自己仓库里，作为轻量的RAG 事故库用于后续分析或复盘。

排查与限制

运行中可能遇到两种脚本内的错误提示，对应不同的处理路径：

• Error while calling the model: …— 模型 API 调用异常（通常是网络或凭据问题），脚本打印异常信息后结束本轮，不会写出报告；
• Could not write report file: …— 诊断本身成功，但写rag_failure_report.json失败（例如当前目录不可写）。

其他边界：

• 模型被明确禁止自创新的模式 ID，回答只能来自 P01–P12；如果你的故障确实不在 12 个模式中，需要先改模式库再跑，而不是指望模型自由发挥；
• 内置三个示例只是演示，README 明确鼓励替换成你自己日志里脱敏后的事故片段；
• 如果你更喜欢 Colab，README 提供的替代方式是把整个rag_failure_diagnostics_clinic.py文件内容复制进一个 Colab cell 中运行。

下一步

README 的 "Extending this tutorial" 一节给出了几条在脚本副本上的延伸方向，都服务于把诊断流程落到你自己的事故中：用你自己日志中脱敏的事故替换内置示例；增删或拆分模式以贴合自己的技术栈；扩展 JSON 报告的 schema（严重级别、负责人、疑似组件）；把报告接入评估看板或事故跟踪系统。模式定义集中在脚本顶部的PATTERNS列表和build_system_prompt()中，修改时改自己的副本即可。

【免费下载链接】awesome-llm-apps100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-llm-apps