Files

OG T 94d6a0c720 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

7.9 KiB

Raw Blame History

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 高風險保護

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)	✅

環境配置

# 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)

Langfuse 整合 (LangfuseTraceContext)
OTEL Tracing (start_as_current_span)

P2 修復 (2026-03-29 10:30)

INvidiaProvider Protocol (@runtime_checkable)
邊界測試補充 (15 → 25 測試案例)
model_registry NVIDIA 配置

P3 優化 (2026-03-29 11:15)

Circuit Breaker 狀態機 (CLOSED/OPEN/HALF_OPEN)
指數退避重試 (含 jitter)
Prometheus Metrics (requests/latency/circuit_breaker)
測試擴充 (25 → 34 測試案例)

驗證結果

# 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

變更記錄

日期	版本	變更	作者
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 整合的架構決策。狀態: ✅ 已實作

7.9 KiB Raw Blame History Unescape Escape