wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity
Files
2a2cb16c135fd7e5b159d94de9b5ff04f6cf31f5
awoooi/docs/adr/ADR-036-nemotron-tool-calling-integration.md
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

228 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 整合的架構決策。狀態: ✅ 已實作*
Reference in New Issue View Git Blame Copy Permalink