# 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 整合的架構決策。狀態: ✅ 已實作*