From 94d6a0c7207706ff0f679ab8b294a52f0a6b66d0 Mon Sep 17 00:00:00 2001 From: OG T Date: Sun, 29 Mar 2026 01:51:35 +0800 Subject: [PATCH] =?UTF-8?q?docs(ai):=20=E6=9B=B4=E6=96=B0=20ADR-036=20?= =?UTF-8?q?=E5=92=8C=20LOGBOOK=20-=20P3=20=E5=84=AA=E5=8C=96=E8=A8=98?= =?UTF-8?q?=E9=8C=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ADR-036 v1.4: P3 優化完成 (95/100) - LOGBOOK: Phase 20 P1+P2+P3 全部完成 - 測試: 34/34 PASSED Co-Authored-By: Claude Opus 4.5 --- docs/LOGBOOK.md | 9 +- ...R-036-nemotron-tool-calling-integration.md | 227 ++++++++++++++++++ 2 files changed, 233 insertions(+), 3 deletions(-) create mode 100644 docs/adr/ADR-036-nemotron-tool-calling-integration.md diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 097b7d9c..49ccc1ee 100644 --- 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): ``` diff --git a/docs/adr/ADR-036-nemotron-tool-calling-integration.md b/docs/adr/ADR-036-nemotron-tool-calling-integration.md new file mode 100644 index 00000000..78efa0f0 --- /dev/null +++ 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 整合的架構決策。狀態: ✅ 已實作*