21dcfbd991
All checks were successful
Code Review / ai-code-review (push) Successful in 11s
Deploy Alert Rules / Deploy Prometheus Alert Rules (push) Successful in 22s
CD Pipeline / tests (push) Successful in 1m6s
CD Pipeline / build-and-deploy (push) Successful in 5m17s
CD Pipeline / post-deploy-checks (push) Successful in 1m38s
177 lines
6.3 KiB
Markdown
177 lines
6.3 KiB
Markdown
# ADR-100: AI 自主化飛輪 SLO
|
||
|
||
<!-- 2026-04-27 P3.4 by Claude — AI SLO -->
|
||
|
||
## 狀態：Active（2026-04-27）
|
||
|
||
## 背景
|
||
|
||
plan_complete_v3.0 P3.4 要求為 AI 自主化飛輪定義可量測的 SLO（Service Level Objectives），
|
||
以便持續追蹤飛輪健康度，並在 SLO 違反時自動降級行為，防止錯誤決策擴散。
|
||
|
||
## 4 個 SLO
|
||
|
||
---
|
||
|
||
### SLO 1 — 自主化率 ≥ 80%
|
||
|
||
**定義**：AI 自動執行的操作佔全部處理操作（含人工審核）的比例
|
||
|
||
**SLI 計算式**:
|
||
```promql
|
||
sum(rate(automation_operation_log_total{outcome="auto_executed"}[5m]))
|
||
/
|
||
sum(rate(automation_operation_log_total{}[5m]))
|
||
```
|
||
|
||
**Recording rule**: `sli:autonomy_rate:5m`
|
||
|
||
**目標值（SLO）**: ≥ 0.80
|
||
|
||
**Error budget（28d）**: 20%（即 28d × 20% = 5.6d 容許人工審核比例偏高）
|
||
|
||
**Burn rate alerts**:
|
||
| 視窗 | 消耗閾值 | 動作 |
|
||
|------|---------|------|
|
||
| Fast (1h) | budget × 14.4 = 2.88 | page（critical） |
|
||
| Medium (6h) | budget × 6 = 1.2 | ticket（warning） |
|
||
| Slow (3d) | budget × 1 → 累積 10% | review（info） |
|
||
|
||
**SLO 違反降級行為**:
|
||
- `< 0.70`（硬紅線）：降低 fusion auto-execute 閾值要求，發送 Telegram P0 告警
|
||
- `< 0.75`：governance_agent 加強監控頻率（30min → 15min）
|
||
|
||
---
|
||
|
||
### SLO 2 — 決策準確率 ≥ 90%
|
||
|
||
**定義**：自動執行後，verifier 驗證通過的比例
|
||
|
||
**SLI 計算式**:
|
||
```promql
|
||
sum(rate(post_execution_verification_total{outcome="success"}[5m]))
|
||
/
|
||
sum(rate(automation_operation_log_total{outcome="auto_executed"}[5m]))
|
||
```
|
||
|
||
**Recording rule**: `sli:decision_accuracy:5m`
|
||
|
||
**目標值（SLO）**: ≥ 0.90
|
||
|
||
**Error budget（28d）**: 10%（比自主化率更嚴格）
|
||
|
||
**Burn rate alerts**:
|
||
| 視窗 | 消耗閾值 | 動作 |
|
||
|------|---------|------|
|
||
| Fast (1h) | budget × 14.4 = 1.44 | page（critical） |
|
||
| Medium (6h) | budget × 6 = 0.6 | ticket（warning） |
|
||
| Slow (3d) | budget × 1 → 累積 10% | review（info） |
|
||
|
||
**SLO 違反降級行為**:
|
||
- `< 0.85`（硬紅線）：**凍結 auto_execute**，全部降級為 `human_required`，
|
||
直到滑動窗口回到 ≥ 0.90 才解凍
|
||
- `< 0.88`：增加 verifier 嚴格度（多一輪二次驗證）
|
||
|
||
---
|
||
|
||
### SLO 3 — 信心校準準確度 ≥ 80%
|
||
|
||
**定義**：AI 信心值 ≥ 0.8 的決策中，實際驗證通過的比例（高信心不能亂說）
|
||
|
||
**SLI 計算式**:
|
||
```promql
|
||
sum(rate(approval_records_high_confidence_success_total[1h]))
|
||
/
|
||
sum(rate(approval_records_high_confidence_total[1h]))
|
||
```
|
||
|
||
**Recording rule**: `sli:confidence_calibration:1h`
|
||
|
||
**目標值（SLO）**: ≥ 0.80
|
||
|
||
**Error budget（28d）**: 20%
|
||
|
||
**Burn rate alerts**:
|
||
| 視窗 | 消耗閾值 | 動作 |
|
||
|------|---------|------|
|
||
| Fast (1h) | budget × 14.4 = 2.88 | page（critical） |
|
||
| Medium (6h) | budget × 6 = 1.2 | ticket（warning） |
|
||
| Slow (3d) | budget × 1 → 累積 10% | review（info） |
|
||
|
||
**SLO 違反降級行為**:
|
||
- `< 0.70`（硬紅線）：觸發 P3.3 fine-tune 重訓流程，Telegram 通知人工介入
|
||
- `< 0.75`：將高信心閾值從 0.8 上調至 0.85（更嚴格的信心要求）
|
||
|
||
---
|
||
|
||
### SLO 4 — KM 增長率 ≥ +20 筆/day
|
||
|
||
**定義**：每 24h 新增的知識條目數，衡量飛輪學習輸出是否健康
|
||
|
||
**SLI 計算式**:
|
||
```promql
|
||
max(knowledge_entries_created_24h)
|
||
or
|
||
max(increase(knowledge_entries_total[24h]))
|
||
```
|
||
|
||
**Recording rule**: `sli:km_growth_rate:24h`
|
||
|
||
**資料來源備註（2026-05-14 T19）**：`knowledge_entries_created_24h`
|
||
是 API `/metrics` 直接從 PostgreSQL `knowledge_entries.created_at >= now()-24h`
|
||
產出的 gauge。`increase(knowledge_entries_total[24h])` 只作舊 counter fallback，
|
||
避免 emitter 新上線時 Prometheus 還沒有 24h counter history 而誤報 KM 增長為 0。
|
||
|
||
**目標值（SLO）**: ≥ 20 筆/day
|
||
|
||
**Error budget**：不適用標準 burn rate（絕對值 SLO），改用閾值告警
|
||
|
||
**告警閾值**:
|
||
| 值 | 動作 |
|
||
|----|------|
|
||
| `< 20/day` | warning：調查 KM 寫入路徑 |
|
||
| `< 5/day` | critical：疑似 KM 鏈斷裂，Telegram P0 告警 |
|
||
| `= 0` (持續 2h) | emergency：governance_agent 立即執行診斷 |
|
||
|
||
**SLO 違反降級行為**:
|
||
- `< 5/day`（硬紅線）：告警，疑似 KM 鏈又斷，自動觸發 `check_knowledge_degradation`
|
||
- `= 0` 持續 2h：立即執行 `governance_agent.run_self_check()`
|
||
|
||
---
|
||
|
||
## SLO 違反時的降級行為矩陣
|
||
|
||
| SLO | 輕度違反 | 硬紅線違反 | 降級行為 |
|
||
|-----|---------|-----------|---------|
|
||
| SLO 1 自主化率 | < 0.75 | < 0.70 | 降低 fusion 閾值 + Telegram |
|
||
| SLO 2 決策準確率 | < 0.88 | < 0.85 | **凍結 auto_execute** |
|
||
| SLO 3 信心校準 | < 0.75 | < 0.70 | 觸發 fine-tune + 提高信心閾值 |
|
||
| SLO 4 KM 增長率 | < 20/day | < 5/day | 告警 + 觸發 KM 診斷 |
|
||
|
||
## 與 governance_agent 整合
|
||
|
||
`GovernanceAgent.check_slo_compliance()` 實作（`apps/api/src/services/governance_agent.py`）：
|
||
|
||
- 每 1h 執行（與既有 4 項自檢合併為第 5 項）
|
||
- 從 Prometheus Recording rules 讀取 SLI 值（`PROMETHEUS_URL` from settings）
|
||
- 違反硬紅線時呼叫 `self._alert()` 寫 PG + 推 Telegram
|
||
- 異常隔離：任一 SLO 查詢失敗不阻斷其他項目
|
||
|
||
## 實作檔案
|
||
|
||
| 檔案 | 用途 |
|
||
|------|------|
|
||
| `ops/monitoring/slo-rules.yml` | Prometheus recording rules + 12 burn rate alerts |
|
||
| `ops/monitoring/tests/test_slo_rules.yaml` | promtool 單元測試 |
|
||
| `ops/monitoring/grafana/dashboards/ai-slo-dashboard.json` | Grafana SLO Dashboard |
|
||
| `apps/api/src/services/governance_agent.py` | `check_slo_compliance()` 整合 |
|
||
| `apps/api/src/services/adr100_slo_metrics_service.py` | 2026-05-14 T18：從 PostgreSQL 事實來源輸出 ADR-100 底層 Prometheus series；`automation_operation_log_total` 僅納入 remediation / PlayBook / auto-repair 範圍，背景治理工作不進 AI 自動修復 SLO 分母。2026-05-14 T19：追加 `*_created_24h` gauges，供治理 Agent / 前端直接顯示最近 24h 事實量，避免 counter 暖機造成 false red |
|
||
| `apps/api/src/main.py` `/metrics` | 2026-05-14 T18：追加 DB-derived SLO emitter，讓既有 `awoooi-api` scrape job 取得底層 series |
|
||
|
||
## 決策理由
|
||
|
||
1. **Recording rules 優先**：SLI 計算複雜，先存 recording rule 避免 Grafana/alert 重複計算
|
||
2. **3 窗口 burn rate**：參考 Google SRE 書 6.5 節，fast/medium/slow 三層防禦
|
||
3. **SLO 4 用絕對值**：KM 增長率是累積計數，burn rate 模型不適用
|
||
4. **governance_agent 整合**：SLO 違反直接觸發降級行為，閉合飛輪的自我修復迴圈
|