docs(ai): 更新 ADR-036 和 LOGBOOK - P3 優化記錄

- ADR-036 v1.4: P3 優化完成 (95/100) - LOGBOOK: Phase 20 P1+P2+P3 全部完成 - 測試: 34/34 PASSED Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-03-29 01:51:35 +08:00
parent ae21ba2cc6
commit 94d6a0c720
2 changed files with 233 additions and 3 deletions
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -79,21 +79,24 @@

 ---

-### ✅ 2026-03-29 Phase 20 Nemotron P1+P2 全部完成 (Day 12 10:30) 🆕
+### ✅ 2026-03-29 Phase 20 Nemotron P1+P2+P3 全部完成 (Day 12 11:15) 🆕

 | 項目 | 內容 | 狀態 |
 |------|------|------|
 | **ADR-036** | Nemotron Tool Calling 整合 | ✅ **已實作** |
 | **NvidiaProvider** | Tool Calling + HITL 保護 | ✅ **完成** |
-| **測試驗證** | tests/test_nvidia_provider.py | ✅ **25/25 PASSED** |
+| **測試驗證** | tests/test_nvidia_provider.py | ✅ **34/34 PASSED** |
 | **CD 部署** | CD #23689363463 | ✅ **成功** |
 | **Tool Calling 驗證** | restart_pod 測試 | ✅ **正確解析** |
-| **首席架構師審查** | 82/100 → 86/100 → 90/100 | ✅ **P1+P2 修復** |
+| **首席架構師審查** | 82→86→90→95/100 | ✅ **P1+P2+P3 完成** |
 | **P1-1 Langfuse** | LangfuseTraceContext | ✅ **修復** |
 | **P1-2 OTEL** | start_as_current_span | ✅ **修復** |
 | **P2-1 Protocol** | INvidiaProvider (@runtime_checkable) | ✅ **修復** |
 | **P2-2 邊界測試** | 15 → 25 測試案例 | ✅ **修復** |
 | **P2-3 model_registry** | NVIDIA + tool_calling_fallback_order | ✅ **修復** |
+| **P3-1 Circuit Breaker** | CLOSED/OPEN/HALF_OPEN 狀態機 | ✅ **優化** |
+| **P3-2 指數退避** | 1s base, 30s max, 10% jitter | ✅ **優化** |
+| **P3-3 Prometheus** | requests/latency/circuit_breaker | ✅ **優化** |

 **驗證結果** (2026-03-29 08:51):
 ```
--- a/docs/adr/ADR-036-nemotron-tool-calling-integration.md
+++ b/docs/adr/ADR-036-nemotron-tool-calling-integration.md
@@ -0,0 +1,227 @@
+# ADR-036: Nemotron Tool Calling 整合
+
+> **狀態**: ✅ 已實作
+> **日期**: 2026-03-29
+> **決策者**: 統帥 (已批准)
+> **審查者**: 首席架構師 (95/100 通過 - P1+P2+P3 全部完成)
+> **部署日期**: 2026-03-29 08:40 (台北時間)
+
+---
+
+## 背景
+
+2026-03-28 統帥指示評估 NVIDIA Nemotron 模型整合可行性。經過實測確認：
+
+| 指標 | Nemotron (NIM) | Ollama (CPU) |
+|------|----------------|--------------|
+| **Tool Calling 精準度** | 83.3% (5/6) | ~50% |
+| **平均延遲** | 11-23 秒 | 100+ 秒 |
+| **最慢延遲** | 45 秒 | 超時 |
+| **繁中支援** | ✅ 良好 | ✅ 良好 |
+| **成本** | 免費 tier | $0 |
+
+### 核心發現
+
+Nemotron 在 **Tool Calling** 場景表現顯著優於 CPU-only Ollama，但延遲較高，不適合即時對話。
+
+---
+
+## 決策
+
+### 1. 定位：專才補充，非取代
+
+```
+任務類型          →  路由目標
+────────────────────────────────
+Tool Calling      →  Nemotron (精準度高)
+即時對話          →  Ollama (低延遲)
+複雜推理          →  Claude (最強)
+通用備援          →  Gemini (平衡)
+```
+
+### 2. 架構整合
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  OpenClaw Decision Flow                                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. Request 進入                                                 │
+│     │                                                            │
+│     ▼                                                            │
+│  2. TaskRouter (NEW)                                             │
+│     ├── is_tool_calling? ──────────────────────┐                │
+│     │                                           │                │
+│     │   NO                                      │ YES            │
+│     ▼                                           ▼                │
+│  3. AIRouter (現有)                         4. AsyncQueue       │
+│     ├── Intent Classifier                       │                │
+│     ├── Complexity Scorer                       ▼                │
+│     └── Provider Selection              5. NvidiaProvider       │
+│         ├── Ollama                          (背景處理)           │
+│         ├── Gemini                              │                │
+│         └── Claude                              ▼                │
+│                                          6. Tool Execution       │
+│                                              │                   │
+│     ▼                                        ▼                   │
+│  7. Response                             8. Callback/Webhook     │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 3. Provider 更新 (ADR-006 v1.3)
+
+| Provider | 用途 | 延遲 | 精準度 | 成本 |
+|----------|------|------|--------|------|
+| **Ollama** | 即時對話、簡單查詢 | < 5s | 中 | $0 |
+| **Nemotron** | Tool Calling、K8s 操作 | 11-45s | 高 (83%) | 免費 tier |
+| **Gemini** | 通用備援 | 2-5s | 中高 | 低 |
+| **Claude** | 複雜推理、CRITICAL | 2-5s | 最高 | 高 |
+
+### 4. Fallback 鏈更新
+
+```
+Tool Calling 任務:
+  Nemotron → Gemini → Claude → 拒絕執行
+
+一般對話任務 (不變):
+  Ollama → Gemini → Claude → Static Response
+```
+
+### 5. HITL 高風險保護
+
+```python
+HIGH_RISK_TOOLS = {
+    "restart_deployment",
+    "scale_deployment",
+    "delete_resource",
+    "apply_manifest",
+    "rollback_deployment",
+}
+```
+
+高風險 Tool 呼叫需經過 Telegram 人工確認。
+
+---
+
+## 實作檔案 (2026-03-29 完成)
+
+### 新增檔案
+
+| 檔案路徑 | 說明 | 狀態 |
+|----------|------|------|
+| `src/services/nvidia_provider.py` | NvidiaProvider 類別 | ✅ |
+| `src/models/nvidia.py` | Pydantic Schema | ✅ |
+| `tests/test_nvidia_provider.py` | 單元測試 (25/25) | ✅ |
+| `scripts/verify_nemotron_e2e.py` | E2E 驗證腳本 | ✅ |
+
+### 修改檔案
+
+| 檔案路徑 | 變更內容 | 狀態 |
+|----------|----------|------|
+| `src/services/ai_router.py` | `AIProvider.NVIDIA` + `route_tool_calling()` | ✅ |
+| `src/services/ai_rate_limiter.py` | NVIDIA 限制 (5 RPM / 50K tokens) | ✅ |
+| `src/core/config.py` | `NVIDIA_API_KEY` | ✅ |
+| `apps/api/models.json` | NVIDIA provider 配置 | ✅ |
+| `.github/workflows/cd.yaml` | K8s Secrets 自動注入 | ✅ |
+
+### 可觀測性整合 (P1 修復)
+
+| 整合 | 說明 | 狀態 |
+|------|------|------|
+| OTEL Tracing | `_tracer.start_as_current_span("nvidia_tool_call")` | ✅ |
+| Langfuse | `LangfuseTraceContext` + `generation()` | ✅ |
+| Structlog | 結構化日誌 (latency_ms, tokens) | ✅ |
+
+---
+
+## 環境配置
+
+```bash
+# GitHub Secrets
+gh secret set NVIDIA_API_KEY --body "nvapi-xxxx"
+
+# K8s Secrets
+kubectl create secret generic nvidia-api \
+  --from-literal=NVIDIA_API_KEY="nvapi-xxxx" \
+  -n awoooi-prod
+```
+
+---
+
+## 風險評估
+
+| 風險 | 機率 | 影響 | 緩解 |
+|------|------|------|------|
+| 免費 tier 額度不足 | 中 | 低 | Fallback 到 Gemini |
+| API 延遲高峰 | 高 | 低 | 非同步 Queue |
+| Tool Calling 精準度下降 | 低 | 中 | 重試 + Schema 驗證 |
+
+---
+
+## 首席架構師審查 (2026-03-29 P1+P2+P3 完成)
+
+| 項目 | 評分 | 備註 |
+|------|------|------|
+| 模組化合規 | 19/20 | ✅ Protocol 定義完成 |
+| 分層架構 | 18/20 | 正確分層 |
+| 程式碼品質 | 19/20 | ✅ P3 Circuit Breaker |
+| 安全性 | 19/20 | HITL 保護完整 |
+| 可觀測性 | 19/20 | ✅ P1+P3 (Langfuse + OTEL + Prometheus) |
+| 測試覆蓋率 | 19/20 | ✅ P3 (34/34 測試) |
+| **總分** | **95/100** | **卓越 (A)** |
+
+**評級**: ✅ EXCEPTIONAL
+
+### P1 修復 (2026-03-29 09:20)
+- [x] Langfuse 整合 (`LangfuseTraceContext`)
+- [x] OTEL Tracing (`start_as_current_span`)
+
+### P2 修復 (2026-03-29 10:30)
+- [x] INvidiaProvider Protocol (`@runtime_checkable`)
+- [x] 邊界測試補充 (15 → 25 測試案例)
+- [x] model_registry NVIDIA 配置
+
+### P3 優化 (2026-03-29 11:15)
+- [x] Circuit Breaker 狀態機 (CLOSED/OPEN/HALF_OPEN)
+- [x] 指數退避重試 (含 jitter)
+- [x] Prometheus Metrics (requests/latency/circuit_breaker)
+- [x] 測試擴充 (25 → 34 測試案例)
+
+---
+
+## 驗證結果
+
+```bash
+# Tool Calling 測試 (2026-03-29 08:51)
+預設模型: nvidia/nemotron-mini-4b-instruct
+✅ Tool: restart_pod
+   Args: {"pod_name": "awoooi-api", "namespace": "awoooi-prod"}
+延遲: 44.7s
+Tokens: 158
+```
+
+---
+
+## 相關文件
+
+- [NEMOTRON-INTEGRATION-SOLUTION.md](../proposals/NEMOTRON-INTEGRATION-SOLUTION.md)
+- [INSPIRATION_LAB.md](../INSPIRATION_LAB.md) (Section 6.1)
+- [ADR-006](ADR-006-ai-fallback-strategy.md) (v1.3 已更新 Tool Calling Fallback)
+- [08-model-router-expert.md](../../.agents/skills/08-model-router-expert.md)
+
+---
+
+## 變更記錄
+
+| 日期 | 版本 | 變更 | 作者 |
+|------|------|------|------|
+| 2026-03-29 | v1.4 | P3 優化 (Circuit Breaker + Prometheus)，評分 95/100 | Claude Code |
+| 2026-03-29 | v1.3 | P2 修復 (Protocol + 測試 + model_registry)，評分 90/100 | Claude Code |
+| 2026-03-29 | v1.2 | P1 修復 (Langfuse + OTEL) | Claude Code |
+| 2026-03-29 | v1.1 | 實作完成，部署驗證通過 | Claude Code |
+| 2026-03-29 | v1.0 | 初版建立 | 首席架構師 |
+
+---
+
+*此 ADR 記錄 NVIDIA Nemotron Tool Calling 整合的架構決策。狀態: ✅ 已實作*