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-appsRAG 问答系统出了错误答案时常见的应对是“加更多上下文”或“换一个更好的模型”但这类建议很难指出真正的问题环节。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依赖内容为openai1.6.0。然后设置 API key 环境变量推荐方式。脚本默认使用https://api.openai.com/v1和模型gpt-4o如需自定义端点或模型用OPENAI_BASE_URL和OPENAI_MODEL覆盖export OPENAI_API_KEYsk-... # 可选使用自定义端点时 # export OPENAI_BASE_URLhttps://your-proxy.example.com/v1 # export OPENAI_MODELgpt-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 driftKubernetes 部署后 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 给出的对照表如下ID模式名称典型症状P01Retrieval hallucination / grounding drift答案自信地与检索到的文档相矛盾。P02Chunk boundary or segmentation bug相关事实被切分或截断在不同的 chunk 中。P03Embedding mismatch / semantic vs vector distance余弦相似度与真实相关性不匹配。P04Index skew or staleness数据源已更新索引仍返回旧数据或缺数据。P05Query rewriting or router misalignment路由把查询发到错误的工具或数据集。P06Long-chain reasoning drift多步任务逐渐丢失早期约束。P07Tool-call misuse or ungrounded tools工具以错误参数调用或缺少 grounding。P08Session memory leak / missing context对话在轮次或会话之间丢失关键事实。P09Evaluation blind spots系统通过测试但在真实事故中失败。P10Startup ordering / dependency not ready部署后最初几分钟服务崩溃或返回 5xx。P11Config or secrets drift across environments本地正常仅因配置在 staging/prod 出错。P12Multi-tenant / multi-agent interference请求或 agent 互相覆盖状态或资源。这个模式库是有意做成“小型、可改”的README 建议根据你的生产事故增删或拆分模式每个 bug 恰好映射一个主模式最多附带两个次选候选。读取诊断结果控制台输出与 JSON 报告每轮运行模型以 temperature 0.2 被调用回答会直接打印到控制台结构化的 Markdown 固定包含四个部分由系统提示词约束Primary pattern— 恰好一个主模式 IDP01–P12Secondary 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 明确鼓励替换成你自己日志里脱敏后的事故片段如果你更喜欢 ColabREADME 提供的替代方式是把整个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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考