Mouryan-J/Root-Cause-Analysis-Agent-using-Hybrid-RAG

# RootCauseAnalysis [](https://github.com/Mouryan-J/RootCause/actions/workflows/ci.yml) [](https://www.python.org/) [](https://rootcause-api.onrender.com) [](https://root-cause-psi.vercel.app) **自动化故障根因分析与响应 Copilot** 这是一个多智能体 AI 系统，能够对生产环境故障进行调查，并自动生成基于证据的排序版根因假设。 **在线演示：** https://root-cause-psi.vercel.app ## 功能 - **多智能体 RCA pipeline**：LangGraph supervisor 按顺序路由通过 分流 → 检索 → RCA → 修复 智能体 - **混合 RAG 检索**：使用 Reciprocal Rank Fusion 融合 BM25 + Qdrant 向量搜索，随后由 Cohere 重排序以提升精准度 - **服务依赖图**：基于 Neo4j 的上下游服务关系图，在结果页面进行可视化展示 - **排序后的根因**：提供 1–3 个带有置信度分数 (0–100%)、证据引用和促成因素的假设 - **修复步骤**：提供具体的、带编号的修复步骤，并参考匹配的 runbook - **实时结果轮询**：结果页面每 2 秒更新一次，直到分析完成 - **故障历史**：浏览所有过往的故障，包含严重程度、状态和相对时间戳 - **LLM 可观测性**：每次智能体调用均通过 Langfuse 进行追踪，并记录每次故障的 token 数量和成本 - **Redis 缓存**：已完成的分析会缓存 30 分钟，从而避免重复的数据库查询 - **CI/CD**：GitHub Actions 会在每次推送时运行 ruff lint 和 27 个 pytest 单元测试 ## 检索评估 基于数据库、缓存和基础设施类别下的 50 个查询进行评估，并带有真实的 runbook 映射。 | 指标 | 仅 BM25 | 混合检索 (BM25 + Qdrant + Cohere) | 提升 | |---|---|---|---| | Recall@1 | 84.0% | 96.0% | **+12.0%** | | Recall@3 | 92.0% | 98.0% | **+6.0%** | | Recall@5 | 98.0% | 98.0% | +0.0% | | MRR | 89.5% | 97.0% | **+7.5%** | 混合检索在 **96% 的情况下**能将正确的 runbook 作为首选结果检索出来，而单独使用 BM25 仅为 84%。 ## RCA 推理评估 上面的检索基准测试的是文档搜索，而不是诊断能力——它的查询直接复用了目标 runbook 的原有措辞，因此高分主要只能证明 embedding/BM25 技术栈找对了文档。而这个基准测试直接考察诊断能力：包含 8 个手工编写的故障案例 (`rca_eval_v2.jsonl`)，涵盖了 7 种故障类型——资源争用、功能开关回归、schema 不匹配、依赖版本偏差、级联的第三方延迟、缓存失效竞态——这些故障的标题和日志都没有直接提到故障模式，而且每个错误的候选原因都与正确原因共享真实证据，而不是显而易见的错误。由一个独立的 LLM（非被评估的 LLM）来判断排名第一的假设是否指出了实际的机制。 **常规推理** | | Top-1 | Top-3 | 幻觉 | 回退 | |---|---|---|---|---| | 无检索/图的裸 LLM | 100% (n=7) | 100% (n=7) | 7.1%\* | 12.5% | | 完整 pipeline | 100% (n=8) | 100% (n=8) | 0.0% | 0.0% | \* 经手工检查：两个被标记的引用都是真实证据，并非捏造——详见 `docs/evaluation.md`。 在这里，单次裸 LLM 调用与完整 pipeline 打成了平手。当日志已经列出了所有相关的服务时，额外的检索/图/分流机制并不会改变结论——因此下一个测试去掉了这个捷径。 **图依赖探测** 3 个故障案例 (`rca_eval_graph_test.jsonl`)，其中日志仅给出一个 *类型* 特征——锁等待超时 (lock-wait-timeout) 暗示了数据库，键值驱逐 (key-eviction) 暗示了缓存——并且从未直接指出依赖项本身： | | 指出了实际的依赖项 | |---|---| | 裸 LLM | 0/3 — 笼统的 ("一个下游事务存储") | | 完整 pipeline | 3/3 — 具体的 ("postgres 上的锁竞争") | 这是一个可以证明依赖图有其存在价值的实测案例：它将一个类型正确的猜测转化为了可操作的诊断。完整的方法论、分析示例，以及在评估过程中发现的两个生产环境 bug，详见 [`docs/evaluation.md`](docs/evaluation.md)。 ## 工作原理 1. **提交**：将故障标题、受影响的服务、严重程度和原始日志粘贴到表单中 2. **分流**：分流智能体 (gpt-4o-mini) 评估严重程度并提取关键信号以构建搜索查询 3. **检索**：检索智能体并行运行 BM25 + Qdrant 向量搜索，使用 RRF 融合排名，然后由 Cohere 对最靠前的结果进行重排序；同时还会查询 Neo4j 以获取该服务的上下游依赖关系 4. **分析**：RCA 智能体 (claude-haiku) 阅读检索到的 runbook 和依赖上下文，以生成 1–3 个带有置信度分数和证据引用的排序版根因假设 5. **修复**：修复智能体 (gpt-4o-mini) 编写参考了匹配 runbook 且带编号的修复步骤 6. **结果**：页面每 2 秒轮询一次，并在完成后渲染完整报告；服务依赖图会进行内联展示；结果将在 Redis 中缓存 30 分钟 所有过往故障均可在历史视图中浏览。 ## 架构 

Mermaid 图表

``` flowchart TD User(["👤 User\nNext.js · Vercel"]) subgraph API["FastAPI Backend · Render"] direction TB GW["API Gateway\nCORS · Auth · Logging"] subgraph LG["LangGraph Pipeline"] direction TB CO["Coordinator"] TR["Triage\ngpt-4o-mini"] RT["Retrieval\nBM25 + Qdrant + Cohere"] RC["RCA\nclaude-haiku"] RM["Remediation\ngpt-4o-mini"] CO --> TR --> CO CO --> RT --> CO CO --> RC --> CO CO --> RM --> CO end GW --> LG end subgraph DBs["Data Layer"] PG[("PostgreSQL\nIncident records")] RD[("Redis\nResult cache")] QD[("Qdrant Cloud\nRunbook vectors")] N4[("Neo4j Aura\nService graph")] end subgraph OBS["Observability"] LF["Langfuse\nLLM tracing"] end User -- "POST /incidents/analyze" --> GW RT -- "BM25 + vector search" --> QD RT -- "Service dependencies" --> N4 LG -- "Store result" --> PG LG -- "Cache result" --> RD LG -- "Trace LLM calls" --> LF GW -- "GET /incidents/:id" --> PG GW -- "GET /incidents/:id (cached)" --> RD API -- "Results + graph" --> User ```

## 技术栈 | 层级 | 技术 | |---|---| | 前端 | Next.js 15, Tailwind CSS, 部署于 Vercel | | 后端 | Python 3.12, FastAPI, 部署于 Render | | AI 编排 | LangGraph (supervisor/worker 多智能体) | | LLM | 通过 Anthropic API 调用 Claude Haiku | | RAG 检索 | BM25 (rank-bm25) + Qdrant Cloud 向量 + Cohere 重排序 | | Embeddings | Cohere embed-english-v3.0 | | 数据库 | PostgreSQL (SQLAlchemy async) | | 缓存 | Redis (可选，支持优雅降级) | | 可观测性 | OpenTelemetry + structlog | | CI | GitHub Actions (ruff lint + pytest) | ## 项目结构 ``` rootcause/ ├── src/rootcause/ │ ├── agents/ # LangGraph agents (triage, retrieval, rca, remediation, graph) │ ├── api/ # FastAPI routes, schemas, middleware │ ├── core/ # Config, security, telemetry (Langfuse) │ ├── db/ # SQLAlchemy models, PostgreSQL, Redis, Neo4j clients │ └── rag/ # Corpus loader, BM25 + Qdrant hybrid retriever ├── frontend/ │ └── src/ │ ├── app/ # Next.js pages (submit, results, history) │ ├── components/ # ResultsPoller, ServiceGraphView, form components │ └── lib/ # API client ├── data/ │ ├── corpus/ # 252 runbooks and postmortems (source documents) │ └── eval/ # retrieval_eval.jsonl (50 queries) + rca_eval.jsonl (18 incidents, v1) + rca_eval_v2.jsonl (8 incidents, hardened schema) ├── scripts/ │ ├── seed_graph.py # Populates Neo4j with 11 services + 21 dependency edges │ ├── run_eval.py # BM25 vs Hybrid retrieval benchmark │ └── run_rca_eval.py # RCA reasoning benchmark (bare LLM vs full pipeline, LLM-judged) ├── docs/ │ └── evaluation.md # RCA reasoning eval methodology, results, worked failure cases └── tests/unit/ # 27 unit tests (config, security, RAG, RCA parsing, grounding filter, retry/fallback logic) ``` ## 在本地运行 **前置条件：** Python 3.12+, [uv](https://github.com/astral-sh/uv), Node.js 20+ ``` # 克隆 git clone https://github.com/Mouryan-J/RootCause.git cd RootCause # Backend cp .env.example .env # fill in API keys uv sync --extra dev uv run python -m rootcause.main # Frontend (单独的终端) cd frontend npm install npm run dev ``` **所需环境变量** (见 `.env.example`)： ``` ANTHROPIC_API_KEY=... DATABASE_URL=postgresql+asyncpg://... QDRANT_URL=https://xxx.qdrant.io:6333 QDRANT_API_KEY=... COHERE_API_KEY=... ``` ## 运行测试 ``` uv run pytest tests/unit/ -v uv run ruff check src/ tests/ ``` 包含 27 个单元测试，涵盖了配置、安全、RAG 检索以及 RCA 智能体的解析/基础/重试逻辑。

标签：AIOps, LangGraph, Neo4j, PyRIT, RAG, 多智能体系统, 搜索引擎查询, 根因分析, 测试用例, 用户代理, 运维自动化, 逆向工具