Mouryan-J/RootCause

# 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) **自动化故障 RCA 与响应 Copilot** 一个多 agent AI 系统，可调查生产环境故障并自动生成带有证据的、按优先级排序的根因假设。 **在线演示：** https://root-cause-psi.vercel.app ## 功能 - **多 agent RCA pipeline**：LangGraph supervisor 按顺序路由通过 triage → retrieval → RCA → remediation agent - **混合 RAG 检索**：使用 Reciprocal Rank Fusion 融合 BM25 + Qdrant 向量搜索，然后通过 Cohere rerank 以提高精度 - **服务依赖图**：Neo4j 图谱展示上游/下游服务关系，并在结果页面上可视化 - **排序的根因**：1–3 个带有置信度分数（0–100%）、证据引用和促成因素的假设 - **Remediation 步骤**：具体的、带编号的修复步骤，引用了匹配的 runbook - **实时结果轮询**：结果页面每 2 秒更新一次，直到分析完成 - **故障历史记录**：浏览所有过去的故障，包含严重程度、状态和相对时间戳 - **LLM 可观测性**：每次 agent 调用都会在 Langfuse 中追踪，记录 token 数量和每个故障的成本 - **Redis 缓存**：完成的分析缓存 30 分钟，消除重复的数据库命中 - **CI/CD**：GitHub Actions 在每次 push 时运行 ruff lint 和 17 个 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%。 ## 工作原理 1. **提交**：将故障标题、受影响的服务、严重程度和原始日志粘贴到表单中 2. **Triage**：Triage agent (gpt-4o-mini) 对严重程度进行分类并提取关键信号以构建搜索查询 3. **检索**：Retrieval agent 并行运行 BM25 + Qdrant 向量搜索，使用 RRF 融合排名，然后 Cohere 对排名靠前的结果进行重排；同时还会查询 Neo4j 以获取服务的上游/下游依赖关系 4. **分析**：RCA agent (claude-haiku) 读取检索到的 runbook 和依赖上下文，以生成 1–3 个带有置信度分数和证据引用的排序根因假设 5. **Remediation**：Remediation agent (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 多 agent) | | LLM | 通过 Anthropic API 调用 Claude Haiku | | RAG 检索 | BM25 (rank-bm25) + Qdrant Cloud 向量 + Cohere rerank | | 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 labeled queries) ├── scripts/ │ ├── seed_graph.py # Populates Neo4j with 11 services + 21 dependency edges │ └── run_eval.py # BM25 vs Hybrid retrieval benchmark └── tests/unit/ # 17 unit tests (config, security, RAG, RCA parsing) ``` ## 本地运行 **前置条件：** Python 3.12+, [uv](https://github.com/astral-sh/uv), Node.js 20+ ``` # Clone 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/ ``` 17 个单元测试，覆盖配置、安全、RAG 检索和 RCA agent 解析。

标签：AIOps, 事故响应, 多智能体, 搜索引擎查询, 根因分析, 检索增强生成, 测试用例, 运维, 逆向工具