# AWOOOI AI 模型治理卡（AI Model Cards）

> **文件類型**: AI 模型治理規格  
> **版本**: v1.0（對應 models.json v1.3.0）  
> **建立日期**: 2026-04-14（台北時間）  
> **建立者**: Claude Sonnet 4.6（首席架構師）  
> **資料來源**: `apps/api/models.json` v1.3.0、`feedback_ai_model_config.md`  
> **維護**: 每次更換主力模型後更新；費用變更須統帥批准（`feedback_cost_change_approval.md`）

---

## 模型路由架構

```
告警進入
   │
   ▼
AIRouter（ADR-052）
   │
   ├─ purpose: rca         → deepseek-r1:14b（Ollama priority 1）
   ├─ purpose: summary      → qwen2.5:7b-instruct
   ├─ purpose: embedding    → nomic-embed-text
   ├─ purpose: code_review  → qwen2.5-coder:7b
   │
   ├─ Ollama 失敗 → Gemini 2.0 Flash（priority 2）
   ├─ Gemini 失敗 → Claude 3 Haiku（priority 3）
   └─ 特殊用途    → NVIDIA Nemotron（priority 4，tool_calling only）
```

**控制開關**: `USE_AI_ROUTER=true`（絞殺者模式，ADR-052）

---

## 模型卡片

---

### 卡片 1：deepseek-r1:14b

| 屬性 | 值 |
|------|---|
| **Model ID** | `deepseek-r1:14b` |
| **Provider** | Ollama（本地）|
| **Endpoint** | `http://192.168.0.111:11434` |
| **Priority** | 1（最優先）|
| **硬體** | 188 主機，NVIDIA GPU |
| **Cost** | $0（完全離線）|

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `rca` | Root Cause Analysis — 告警根因分析 |
| `diagnose` | 深度診斷（含 log 關聯） |
| `log_anomaly` | 日誌異常偵測 |

**特性**
- 推理型模型（Chain-of-Thought），擅長多步邏輯
- 本地執行，無資料隱私疑慮
- 14B 參數，P95 延遲 ~8-15s（依硬體負載）

**限制**
- 僅在 188 主機可用；188 離線時全部 fallback 至 Gemini
- 無 Tool Calling 能力（使用 structured prompt 替代）
- 高負載時延遲可能超過 25s LLM timeout → Expert System 降級

**信心校準**
- RCA confidence 由 `confidence_scorer` 計算
- 規則精確匹配 → confidence=1.0；無 kubectl_command → confidence=0.0

---

### 卡片 2：qwen2.5:7b-instruct

| 屬性 | 值 |
|------|---|
| **Model ID** | `qwen2.5:7b-instruct` |
| **Provider** | Ollama（本地）|
| **Endpoint** | `http://192.168.0.111:11434` |
| **Priority** | 1（與 deepseek-r1 同層，purpose 分工）|
| **Cost** | $0（完全離線）|

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `drift_summary` | 配置漂移摘要 |
| `rag_generate` | RAG 知識庫生成回答 |
| `playbook_draft` | Playbook 草稿生成 |
| `summary` | 事件摘要（Incident Summary）|

**特性**
- 指令微調版本（-instruct），生成文字品質高
- 7B 參數，延遲較 deepseek 低（P95 ~4-8s）
- 適合結構化輸出（JSON、Markdown）

**限制**
- 推理深度不如 deepseek-r1；複雜 RCA 不使用此模型
- 同在 188 主機；與 deepseek 共享 GPU 資源，高負載時互相競爭

---

### 卡片 3：nomic-embed-text

| 屬性 | 值 |
|------|---|
| **Model ID** | `nomic-embed-text:latest` |
| **Provider** | Ollama（本地）|
| **Endpoint** | `http://192.168.0.111:11434` |
| **Priority** | 1（embedding 專用）|
| **Cost** | $0（完全離線）|

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `embedding` | 文字向量化（KM 搜尋、RAG 索引）|

**特性**
- 768 維向量輸出
- 速度快（~50ms/request），適合即時 RAG 檢索
- 與 pgvector 整合（PostgreSQL 向量索引）

**注意事項**
- 嵌入向量與文字模型的 embedding 不可混用
- 若 nomic-embed-text 下線，KM 搜尋功能降級（知識庫返回空）

---

### 卡片 4：qwen2.5-coder:7b

| 屬性 | 值 |
|------|---|
| **Model ID** | `qwen2.5-coder:7b` |
| **Provider** | Ollama（本地）|
| **Endpoint** | `http://192.168.0.111:11434` |
| **Priority** | 1（code_review 專用）|
| **Cost** | $0（完全離線）|

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `code_review` | 程式碼審查（CI/CD Pipeline 整合）|

**特性**
- 程式碼專用微調，理解 Python/TypeScript/YAML/Bash
- 適合靜態分析、安全掃描建議

---

### 卡片 5：Gemini 2.0 Flash

| 屬性 | 值 |
|------|---|
| **Model ID** | `gemini-2.0-flash` |
| **Provider** | Google Gemini API（雲端）|
| **Priority** | 2（Ollama 失敗時 fallback）|
| **Daily Limit** | 70,000 tokens/day |
| **Cost** | 免費額度內 $0；超出計費 |

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `rca` | Ollama 失敗時的 RCA fallback |
| `summary` | 事件摘要 fallback |
| `drift_summary` | 配置漂移摘要 fallback |

**特性**
- 速度快（Flash 版），適合 fallback 場景
- 70K tokens/day 足夠支撐日均 ~20-30 incident 分析
- 雲端模型，有資料外送（請勿傳送含 secrets 的日誌）

**費用控制**
- Token 消耗監控：Langfuse → `provider=gemini` traces
- 超過 60K tokens/day → Telegram 告警（`feedback_cost_change_approval.md`）
- 費用變更必須停下等統帥批准

**限制**
- 超過日限後拒絕請求（HTTP 429）→ fallback 至 Claude 3 Haiku
- 網路中斷時不可用

---

### 卡片 6：Claude 3 Haiku

| 屬性 | 值 |
|------|---|
| **Model ID** | `claude-3-haiku-20240307` |
| **Provider** | Anthropic API（雲端）|
| **Priority** | 3（Gemini 失敗或超限時 fallback）|
| **Daily Limit** | 35,000 tokens/day |
| **Cost** | 按用量計費（$0.25/1M input tokens）|

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `rca` | 緊急 fallback（Ollama+Gemini 均失效）|
| `summary` | 緊急 fallback |

**特性**
- Anthropic 最快、最便宜的模型
- 35K tokens/day 作為「最後防線」使用，不應成為主力

**費用控制**
- 達到 Priority 3 代表 Ollama 和 Gemini 都失效，需立即告警
- 每次使用 Claude API → Langfuse 記錄 `provider=claude`
- 月度費用報告需包含 Claude 用量

**限制**
- 模型知識截止日期較 GPT-4 早
- 不含 Tool Calling 於此整合（純文字生成）

---

### 卡片 7：NVIDIA Nemotron-Mini-4B

| 屬性 | 值 |
|------|---|
| **Model ID** | `nvidia/nemotron-mini-4b-instruct` |
| **Provider** | NVIDIA NIM API（雲端）|
| **Priority** | 4（特殊場景專用）|
| **Accuracy** | 83.3%（`nemoclaw` 任務）|
| **Cost** | 按用量計費 |

**用途（purposes）**

| Purpose Key | 說明 |
|-------------|------|
| `nemoclaw` | Tool Calling（OpenClaw 整合）|
| `tool_calling` | 結構化函式呼叫 |

**特性**
- 4B 小型模型，專為 Tool Calling 優化
- 83.3% Tool Call 準確率（AIOps 場景測試）
- 整合 NVIDIA NIM 推論加速

**限制**
- 僅用於 `nemoclaw` / `tool_calling` purpose；RCA 不使用此模型
- NIM API 延遲依網路狀況（通常 2-5s）
- API Key 在 K8s Secret `nvidia-api-key`

---

## Fallback 順序總表

```
目的           Priority 1      Priority 2     Priority 3     Priority 4
─────────────────────────────────────────────────────────────────────────
rca            deepseek-r1  →  gemini-flash  →  claude-haiku  →  N/A
summary        qwen2.5-7b   →  gemini-flash  →  claude-haiku  →  N/A
drift_summary  qwen2.5-7b   →  gemini-flash  →  N/A           →  N/A
rag_generate   qwen2.5-7b   →  N/A           →  N/A           →  N/A
playbook_draft qwen2.5-7b   →  N/A           →  N/A           →  N/A
embedding      nomic-embed  →  N/A           →  N/A           →  N/A
code_review    qwen2.5-coder→  N/A           →  N/A           →  N/A
nemoclaw       N/A          →  N/A           →  N/A           →  nemotron
```

**Fallback 觸發條件**: Ollama timeout（> 25s）、HTTP 5xx、連線失敗、quota 超限

---

## 模型健康監控

| 指標 | 來源 | 告警閾值 |
|------|------|---------|
| Ollama 可用性 | Prometheus scrape 188:9090 | 失效 > 30s → Telegram |
| Gemini 日用量 | Langfuse `provider=gemini` | > 60K tokens/day |
| Claude 日用量 | Langfuse `provider=claude` | > 25K tokens/day |
| LLM P95 延遲 | SLO-2（< 20s for P95） | 超過 25s → Expert System 降級 |
| Fallback 頻率 | Priority 2+ 被觸發次數 | > 3次/小時 → 告警 |

---

## 模型更換 SOP

1. 在 `models.json` 新增/修改模型配置
2. 在本文件更新對應的模型卡片
3. 若涉及費用變更 → 停下等統帥批准（`feedback_cost_change_approval.md`）
4. 更新 `LOGBOOK.md` + 推版至 Gitea
5. 驗證 Langfuse 追蹤正確記錄新 model_id

---

*本文件由 Claude Sonnet 4.6 於 2026-04-14 台北時間建立，以 models.json v1.3.0 為資料來源*