test: add rag retrieval baseline

2026-07-05 02:02:27 +08:00
parent 79feed3314
commit 9a2a44d1b5
19 changed files with 946 additions and 0 deletions
@@ -0,0 +1,51 @@
+# RAG Retrieval Baseline
+
+This directory contains the offline retrieval baseline for the RAG refactor.
+
+The baseline is intentionally narrower than full diagnosis evaluation. It checks
+whether fixed retrieval queries can recover expected documents, breadcrumbs, and
+evidence keywords before changing L0 behavior, query augmentation, evidence
+post-processing, or Spring AI VectorStore integration.
+
+## Layout
+
+```text
+eval/rag-retrieval/
+  cases/golden-cases.json      Fixed retrieval golden cases
+  fixtures/*.json              Saved retrieval candidates for each case
+  reports/baseline.json        Machine-readable baseline report
+  reports/baseline.md          Human-readable baseline report
+```
+
+## Run
+
+From the repository root:
+
+```bash
+python scripts/eval_rag_retrieval.py
+```
+
+Custom paths are also supported:
+
+```bash
+python scripts/eval_rag_retrieval.py \
+  --cases eval/rag-retrieval/cases/golden-cases.json \
+  --fixtures eval/rag-retrieval/fixtures \
+  --json-report eval/rag-retrieval/reports/baseline.json \
+  --markdown-report eval/rag-retrieval/reports/baseline.md
+```
+
+## Hit Levels
+
+- `strong`: expected document is found and breadcrumb or evidence keyword coverage is satisfied.
+- `medium`: expected document is found, but breadcrumb or keyword coverage is incomplete.
+- `weak`: expected evidence keyword is found, but expected document is missing.
+- `miss`: expected document and expected evidence are not found.
+
+`Recall@K` counts `strong` and `medium` as retrieved.
+
+## Scope
+
+This baseline runs fully offline and does not call MySQL, Redis, Milvus, an LLM,
+or the Spring Boot application. It is a regression harness for retrieval behavior,
+not a claim that live production retrieval accuracy is complete.
@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "description": "Offline golden retrieval cases for RAG refactor baseline.",
+  "topK": 5,
+  "cases": [
+    {
+      "caseId": "chat-mysql-connection-pool",
+      "scenario": "chat",
+      "query": "MySQL connection pool is exhausted. How should I diagnose it?",
+      "expectedDocIds": ["mysql-connection-pool"],
+      "expectedBreadcrumbs": ["Database > MySQL > Connection Pool"],
+      "expectedKeywords": ["connection pool", "max_connections", "HikariCP"],
+      "notes": "Covers precise database troubleshooting retrieval."
+    },
+    {
+      "caseId": "chat-diagnosis-flow",
+      "scenario": "chat",
+      "query": "What is the standard troubleshooting flow for an application incident?",
+      "expectedDocIds": ["incident-diagnosis-flow"],
+      "expectedBreadcrumbs": ["AIOps > Diagnosis Flow"],
+      "expectedKeywords": ["collect evidence", "verify", "remediation"],
+      "notes": "Covers process-style knowledge where breadcrumb matters."
+    },
+    {
+      "caseId": "aiops-payment-latency-alert",
+      "scenario": "aiops",
+      "query": "Alert HighLatency on payment-service with p95 latency above threshold",
+      "expectedDocIds": ["payment-service-latency"],
+      "expectedBreadcrumbs": ["AIOps > Service Alerts > Payment Latency"],
+      "expectedKeywords": ["p95 latency", "payment-service", "downstream dependency"],
+      "notes": "Covers alert payload terms that should become retrieval hints."
+    },
+    {
+      "caseId": "aiops-prometheus-alert-scope",
+      "scenario": "aiops",
+      "query": "When an AIOps request already includes alert payload, should the agent diagnose unrelated active alerts?",
+      "expectedDocIds": ["aiops-alert-scope-control"],
+      "expectedBreadcrumbs": ["AIOps > Alert Scope Control"],
+      "expectedKeywords": ["payload", "unrelated active alerts", "scope"],
+      "notes": "Covers scoped alert diagnosis behavior."
+    },
+    {
+      "caseId": "chat-rag-chunk-context",
+      "scenario": "chat",
+      "query": "If a long section is split into multiple chunks, how do we keep retrieval context?",
+      "expectedDocIds": ["rag-chunk-context-reconstruction"],
+      "expectedBreadcrumbs": ["RAG > Chunking > Context Reconstruction"],
+      "expectedKeywords": ["neighbor chunk", "same section", "breadcrumb"],
+      "notes": "Covers the known RAG refactor issue around context reconstruction."
+    },
+    {
+      "caseId": "chat-l0-domain-hint",
+      "scenario": "chat",
+      "query": "Should L0 keyword matching decide the final retrieval result?",
+      "expectedDocIds": ["rag-l0-domain-entity-hint"],
+      "expectedBreadcrumbs": ["RAG > L0 > Domain Entity Hint"],
+      "expectedKeywords": ["domain detector", "entity extractor", "metadata filter"],
+      "notes": "Covers the target L0 role after refactor."
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "caseId": "aiops-payment-latency-alert",
+  "query": "Alert HighLatency on payment-service with p95 latency above threshold",
+  "retrievedAt": "2026-07-05T00:00:00Z",
+  "candidates": [
+    {
+      "rank": 1,
+      "docId": "payment-service-latency",
+      "title": "Payment Service Latency Alert Playbook",
+      "breadcrumb": "AIOps > Service Alerts > Payment Latency",
+      "content": "For payment-service p95 latency alerts, check downstream dependency latency, thread pool saturation, gateway retries, and recent deployment changes.",
+      "score": 0.84,
+      "retrievalLayer": "L1"
+    },
+    {
+      "rank": 2,
+      "docId": "mysql-connection-pool",
+      "title": "MySQL Connection Pool Troubleshooting",
+      "breadcrumb": "Database > MySQL > Connection Pool",
+      "content": "Database connection pool saturation can increase payment latency when checkout paths wait for connections.",
+      "score": 0.68,
+      "retrievalLayer": "L1"
+    }
+  ]
+}
@@ -0,0 +1,16 @@
+{
+  "caseId": "aiops-prometheus-alert-scope",
+  "query": "When an AIOps request already includes alert payload, should the agent diagnose unrelated active alerts?",
+  "retrievedAt": "2026-07-05T00:00:00Z",
+  "candidates": [
+    {
+      "rank": 1,
+      "docId": "aiops-alert-scope-control",
+      "title": "AIOps Alert Scope Control",
+      "breadcrumb": "AIOps > Alert Scope Control",
+      "content": "When payload mode is active, queryPrometheusAlerts can verify the supplied alert, but unrelated active alerts must remain scoped context and should not become full diagnoses.",
+      "score": 0.9,
+      "retrievalLayer": "L0+L1"
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "caseId": "chat-diagnosis-flow",
+  "query": "What is the standard troubleshooting flow for an application incident?",
+  "retrievedAt": "2026-07-05T00:00:00Z",
+  "candidates": [
+    {
+      "rank": 1,
+      "docId": "incident-diagnosis-flow",
+      "title": "Incident Diagnosis Flow",
+      "breadcrumb": "AIOps > Diagnosis Flow",
+      "content": "The standard flow is to collect evidence, identify the suspected fault domain, verify the hypothesis, apply remediation, and confirm recovery.",
+      "score": 0.82,
+      "retrievalLayer": "L1"
+    },
+    {
+      "rank": 2,
+      "docId": "rag-chunk-context-reconstruction",
+      "title": "RAG Chunk Context Reconstruction",
+      "breadcrumb": "RAG > Chunking > Context Reconstruction",
+      "content": "Long sections may require neighbor chunk expansion and breadcrumb-aware packing.",
+      "score": 0.55,
+      "retrievalLayer": "L1"
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "caseId": "chat-l0-domain-hint",
+  "query": "Should L0 keyword matching decide the final retrieval result?",
+  "retrievedAt": "2026-07-05T00:00:00Z",
+  "candidates": [
+    {
+      "rank": 1,
+      "docId": "rag-l0-domain-entity-hint",
+      "title": "RAG L0 Domain Entity Hint",
+      "breadcrumb": "RAG > L0 > Domain Entity Hint",
+      "content": "L0 should be retained as a domain detector, entity extractor, metadata filter generator, and explainability signal, not as the final retrieval decision.",
+      "score": 0.88,
+      "retrievalLayer": "L0"
+    },
+    {
+      "rank": 2,
+      "docId": "rag-l0-l1-fusion-ranking",
+      "title": "RAG L0 L1 Fusion Ranking",
+      "breadcrumb": "RAG > Ranking > Fusion",
+      "content": "L0 and L1 candidates should eventually be fused rather than handled as an early-return branch.",
+      "score": 0.75,
+      "retrievalLayer": "L1"
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "caseId": "chat-mysql-connection-pool",
+  "query": "MySQL connection pool is exhausted. How should I diagnose it?",
+  "retrievedAt": "2026-07-05T00:00:00Z",
+  "candidates": [
+    {
+      "rank": 1,
+      "docId": "mysql-connection-pool",
+      "title": "MySQL Connection Pool Troubleshooting",
+      "breadcrumb": "Database > MySQL > Connection Pool",
+      "content": "When the connection pool is exhausted, inspect HikariCP active connections, max_connections, slow SQL, leak detection, and database wait events.",
+      "score": 0.86,
+      "retrievalLayer": "L0+L1"
+    },
+    {
+      "rank": 2,
+      "docId": "incident-diagnosis-flow",
+      "title": "Incident Diagnosis Flow",
+      "breadcrumb": "AIOps > Diagnosis Flow",
+      "content": "Collect evidence, compare metrics and logs, then verify remediation before closing the incident.",
+      "score": 0.61,
+      "retrievalLayer": "L1"
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "caseId": "chat-rag-chunk-context",
+  "query": "If a long section is split into multiple chunks, how do we keep retrieval context?",
+  "retrievedAt": "2026-07-05T00:00:00Z",
+  "candidates": [
+    {
+      "rank": 1,
+      "docId": "rag-chunk-context-reconstruction",
+      "title": "RAG Chunk Context Reconstruction",
+      "breadcrumb": "RAG > Chunking > Context Reconstruction",
+      "content": "After a chunk hit, expand to neighbor chunk candidates from the same section and preserve breadcrumb metadata in the evidence pack.",
+      "score": 0.79,
+      "retrievalLayer": "L1"
+    },
+    {
+      "rank": 2,
+      "docId": "rag-breadcrumb-embedding-gap",
+      "title": "RAG Breadcrumb Embedding Gap",
+      "breadcrumb": "RAG > Embedding > Breadcrumb",
+      "content": "Embedding title and breadcrumb with content helps recover section semantics.",
+      "score": 0.72,
+      "retrievalLayer": "L1"
+    }
+  ]
+}
@@ -0,0 +1 @@
+
@@ -0,0 +1,131 @@
+{
+  "generatedAt": "2026-07-04T17:59:52.172759+00:00",
+  "caseFile": "eval/rag-retrieval/cases/golden-cases.json",
+  "fixtureDir": "eval/rag-retrieval/fixtures",
+  "aggregate": {
+    "caseCount": 6,
+    "topK": 5,
+    "strongHitCount": 6,
+    "mediumHitCount": 0,
+    "weakHitCount": 0,
+    "missCount": 0,
+    "recallAtK": 1.0,
+    "strongHitRate": 1.0,
+    "averageFirstHitRank": 1.0
+  },
+  "results": [
+    {
+      "caseId": "chat-mysql-connection-pool",
+      "scenario": "chat",
+      "query": "MySQL connection pool is exhausted. How should I diagnose it?",
+      "hitLevel": "strong",
+      "passed": true,
+      "firstExpectedRank": 1,
+      "topCandidates": [
+        "1:mysql-connection-pool",
+        "2:incident-diagnosis-flow"
+      ],
+      "matchedKeywords": [
+        "connection pool",
+        "max_connections",
+        "hikaricp"
+      ],
+      "breadcrumbMatched": true,
+      "failedChecks": []
+    },
+    {
+      "caseId": "chat-diagnosis-flow",
+      "scenario": "chat",
+      "query": "What is the standard troubleshooting flow for an application incident?",
+      "hitLevel": "strong",
+      "passed": true,
+      "firstExpectedRank": 1,
+      "topCandidates": [
+        "1:incident-diagnosis-flow",
+        "2:rag-chunk-context-reconstruction"
+      ],
+      "matchedKeywords": [
+        "collect evidence",
+        "verify",
+        "remediation"
+      ],
+      "breadcrumbMatched": true,
+      "failedChecks": []
+    },
+    {
+      "caseId": "aiops-payment-latency-alert",
+      "scenario": "aiops",
+      "query": "Alert HighLatency on payment-service with p95 latency above threshold",
+      "hitLevel": "strong",
+      "passed": true,
+      "firstExpectedRank": 1,
+      "topCandidates": [
+        "1:payment-service-latency",
+        "2:mysql-connection-pool"
+      ],
+      "matchedKeywords": [
+        "p95 latency",
+        "payment-service",
+        "downstream dependency"
+      ],
+      "breadcrumbMatched": true,
+      "failedChecks": []
+    },
+    {
+      "caseId": "aiops-prometheus-alert-scope",
+      "scenario": "aiops",
+      "query": "When an AIOps request already includes alert payload, should the agent diagnose unrelated active alerts?",
+      "hitLevel": "strong",
+      "passed": true,
+      "firstExpectedRank": 1,
+      "topCandidates": [
+        "1:aiops-alert-scope-control"
+      ],
+      "matchedKeywords": [
+        "payload",
+        "unrelated active alerts",
+        "scope"
+      ],
+      "breadcrumbMatched": true,
+      "failedChecks": []
+    },
+    {
+      "caseId": "chat-rag-chunk-context",
+      "scenario": "chat",
+      "query": "If a long section is split into multiple chunks, how do we keep retrieval context?",
+      "hitLevel": "strong",
+      "passed": true,
+      "firstExpectedRank": 1,
+      "topCandidates": [
+        "1:rag-chunk-context-reconstruction",
+        "2:rag-breadcrumb-embedding-gap"
+      ],
+      "matchedKeywords": [
+        "neighbor chunk",
+        "same section",
+        "breadcrumb"
+      ],
+      "breadcrumbMatched": true,
+      "failedChecks": []
+    },
+    {
+      "caseId": "chat-l0-domain-hint",
+      "scenario": "chat",
+      "query": "Should L0 keyword matching decide the final retrieval result?",
+      "hitLevel": "strong",
+      "passed": true,
+      "firstExpectedRank": 1,
+      "topCandidates": [
+        "1:rag-l0-domain-entity-hint",
+        "2:rag-l0-l1-fusion-ranking"
+      ],
+      "matchedKeywords": [
+        "domain detector",
+        "entity extractor",
+        "metadata filter"
+      ],
+      "breadcrumbMatched": true,
+      "failedChecks": []
+    }
+  ]
+}
@@ -0,0 +1,28 @@
+# RAG Retrieval Baseline
+
+Generated at: `2026-07-04T17:59:52.172759+00:00`
+
+## Aggregate
+
+| Metric | Value |
+|---|---:|
+| Cases | 6 |
+| Top K | 5 |
+| Recall@K | 1.0 |
+| Strong hit rate | 1.0 |
+| Strong hits | 6 |
+| Medium hits | 0 |
+| Weak hits | 0 |
+| Misses | 0 |
+| Average first hit rank | 1.0 |
+
+## Cases
+
+| Case | Scenario | Hit | First Expected Rank | Top Candidates | Failed Checks |
+|---|---|---|---:|---|---|
+| chat-mysql-connection-pool | chat | strong | 1 | 1:mysql-connection-pool<br>2:incident-diagnosis-flow |  |
+| chat-diagnosis-flow | chat | strong | 1 | 1:incident-diagnosis-flow<br>2:rag-chunk-context-reconstruction |  |
+| aiops-payment-latency-alert | aiops | strong | 1 | 1:payment-service-latency<br>2:mysql-connection-pool |  |
+| aiops-prometheus-alert-scope | aiops | strong | 1 | 1:aiops-alert-scope-control |  |
+| chat-rag-chunk-context | chat | strong | 1 | 1:rag-chunk-context-reconstruction<br>2:rag-breadcrumb-embedding-gap |  |
+| chat-l0-domain-hint | chat | strong | 1 | 1:rag-l0-domain-entity-hint<br>2:rag-l0-l1-fusion-ranking |  |