From d3d90121cf677cf17ba5eb9957ed88e840bf4918 Mon Sep 17 00:00:00 2001 From: OoO Date: Sun, 3 May 2026 23:42:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(adr):=20ADR-030=20Frontier=20=E5=A4=9A?= =?UTF-8?q?=E4=BE=9B=E6=87=89=E5=95=86=E7=AD=96=E7=95=A5=20=E2=80=94=20Ant?= =?UTF-8?q?hropic=20+=20Google=20+=20OpenRouter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operation Ollama-First v5.0 / Phase 12 / Phase 7 落地後追認 Phase 7 引入 Anthropic Claude（Opus 4.7 接 Code Review）後， 戰役有 2 家 Frontier 供應商，需明確治理準則： 決策矩陣（與 ADR-028 鎖定 7 場景對齊）： - 場景 #5 Code Review ⭐: Claude Opus 4.7 (Arena Elo 1548) → Gemini 2.5 Flash → ElephantAlpha 49B (3 層 fallback) - 其他 6 場景維持 Gemini 主鏈 Prompt cache 戰術： - Anthropic 5min ephemeral：Code Review 命中率預估 80%+，省 ~90% 成本 - Google Gemini：隱式 server-side cache，不可預測 預估月成本：~$32 USD - Claude $10 + Gemini $8 + NIM $5×2 + OpenRouter $3 + Ollama $0.02 新增供應商 SOP： 1. service wrapper 加 feature flag + is_available() 檢查 2. budget 種子 + ai_calls.provider 白名單 3. unit test (fallback 鏈 + cache hit/miss) 4. 獨立 ADR 對齊： - migration 024（claude in provider 白名單） - migration 025（claude $10/月 budget 種子） - ai_call_logger COST_TABLE（claude-opus/sonnet/haiku 三模型） - services/anthropic_service.py（Phase 7 落地） Co-Authored-By: Claude Opus 4.7 (1M context) --- .../ADR-030-frontier-multi-vendor-strategy.md | 215 ++++++++++++++++++ docs/adr/README.md | 1 + 2 files changed, 216 insertions(+) create mode 100644 docs/adr/ADR-030-frontier-multi-vendor-strategy.md diff --git a/docs/adr/ADR-030-frontier-multi-vendor-strategy.md b/docs/adr/ADR-030-frontier-multi-vendor-strategy.md new file mode 100644 index 0000000..cc0ab05 --- /dev/null +++ b/docs/adr/ADR-030-frontier-multi-vendor-strategy.md @@ -0,0 +1,215 @@ +# ADR-030: Frontier 多供應商策略 — Anthropic + Google + OpenRouter + +- **Status**: Accepted +- **Date**: 2026-05-03 +- **Decision Maker**: 統帥 +- **Author**: Operation Ollama-First v5.0（Phase 7 落地後追認） +- **Supersedes**: 無 +- **Related**: ADR-028（LLM 路由統一準則）、ADR-029（Hermes-First 雙塔分工）、ADR-027（Primary Ollama on GCP） + +--- + +## Context + +戰役 v5.0 Wave 1 完成後（commits 4648673~943de84），momo-pro 的 LLM 治理已具備： +- 三主機 Ollama 級聯（Primary/Secondary/Fallback） +- 13 caller 接入 ai_call_logger +- 7 場景鎖定 Gemini（不可走 Ollama） +- ADR-029 Hermes-First 雙塔分工 + +但 **Phase 7 升級（Claude Opus 4.7 接 Code Review）** 引入了第二家 Frontier 供應商（Anthropic），戰役需要明確的多供應商治理準則： + +1. **何時用 Anthropic vs Google？** — 兩家都是 Frontier，但能力分布不同 +2. **Prompt cache 戰術** — Anthropic 5min ephemeral / Google 隱式，省成本邏輯不同 +3. **配額 / 帳單 / 失敗鏈** — 多家供應商需獨立 budget 與 fallback 順序 +4. **OpenRouter 角色** — 既有 PPT deepseek-v3.2 鏈為何不丟掉？ + +**單一供應商風險**（戰役 v3.0 起的核心觀察）：Gemini 月用量 50M tokens，若 Google 端配額爆 / 政策變更 / API key 撤銷 → 全系統癱瘓。多供應商提供工程級 fault tolerance。 + +--- + +## Decision + +### 1. 三家 Frontier 供應商角色定位 + +| 供應商 | 模型 | 適用場景 | 計費模式 | +|---|---|---|---| +| **Anthropic Claude** | Opus 4.7 / Sonnet 4.6 / Haiku 4.5 | **程式碼推理** + agentic 工具 + 長 context (200K) | metered / **prompt cache 5min ephemeral** | +| **Google Gemini** | 2.5 Flash / 2.5 Pro | **Search Grounding** + 繁中商業文體 + 多模態 | metered | +| **OpenRouter** | DeepSeek V3.2 / 其他 | **PPT 簡報降級** + 實驗性多供應商 | passthrough metered | + +### 2. 場景對應決策矩陣（與 ADR-028 鎖定 7 場景對齊） + +| ADR-028 場景 | 主供應商 | 備援供應商 | 依據 | +|---|---|---|---| +| #1 MCP 即時情報 | Gemini 2.5 Pro Grounding | Gemini 1.5 Flash Grounding | 唯一聯網 grounding（Phase 10 將補 mcp-omnisearch） | +| #2/3/4 OpenClaw 週/月/年報 | Gemini 2.5 Flash | NIM llama-3.3-70b | 長 context + 繁中商業文體 | +| #5 Code Review ⭐ | **Claude Opus 4.7** | Gemini 2.5 Flash → ElephantAlpha 49B | Arena code Elo 1548（程式碼 #1）+ 200K context | +| #6 EA HITL | Gemini 2.0 Flash | Hermes Ollama 預跑 | 統帥決策時效 | +| #7 PPT 簡報 | Gemini 2.0 Flash | Ollama qwen2.5-coder:7b → DeepSeek V3.2 | 5K rows 長 context | + +⭐ **#5 Code Review 是 Phase 7 主要升級點**： +- **Claude Opus 4.7 程式碼能力 Arena Elo 1548 vs Gemini 2.5 Flash ~1450**（+7%） +- **200K context** 支援全 repo diff（Gemini Flash 限 1M 但實測響應品質下降） +- **Prompt cache** 對 Code Review 的「固定 system_prompt + 變動 diff」場景命中率預估 80%+，省 ~90% 成本 +- 預估月成本：Opus 4.7 $25 vs Gemini 2.5 Flash $5（差 $20，但 +7% 品質 + 主權冗餘值得） + +### 3. Prompt Cache 戰術 + +#### Anthropic（5 分鐘 ephemeral） +```python +# services/anthropic_service.py 已實作 +kwargs["system"] = [ + {"type": "text", "text": system_prompt, + "cache_control": {"type": "ephemeral"}} +] +``` +**適用場景**：Code Review（system_prompt 固定、diff 變動）、相同 caller 5 分鐘內多次調用。 + +**省成本估算**： +- 第一次調用：input_tokens 全價 + cache_creation 收費（同 input） +- 第 2-N 次（5min 內）：cache_read 0.1× input 價格 → 省 90% + +#### Google Gemini（隱式 server-side cache） +- 無顯式 API，依靠 Google 內部優化 +- 不可預測，不納入成本估算 + +### 4. Budget 與告警（與 migration 025 種子對齊） + +| Provider | 月預算 | 種子位置 | 告警閾值 | +|---|---|---|---| +| `claude` | $10 | `ai_call_budgets` | 80% | +| `gemini` | $8 | 同上 | 80% | +| `nim` | $5 | 同上 | 80% | +| `nim_via_elephant` | $5 | 同上 | 80% | +| `openrouter` | $3 | 同上 | 80% | +| `gcp_ollama` | $0.01 | 同上（異常激增告警） | 100% | +| `ollama_111` | $0.01 | 同上 | 100% | + +**戰役 v5.0 月成本上限**：~$32 USD（vs 戰前估算 ~$25 + Phase 7 升級增量 $20 - Hermes-first 攔截 -$13） + +### 5. Fallback 鏈規範 + +**Code Review** (Phase 7 落地)： +``` +L0: Claude Opus 4.7 (CODE_REVIEW_USE_CLAUDE=true) + ↓ 失敗 / SDK 不可用 +L1: Gemini 2.5 Flash (REVIEW_MODEL) + ↓ 失敗 +L2: ElephantAlpha NIM 49B (services/elephant_service.py) +``` + +**EA HITL**（依 ADR-029 雙塔分工）： +``` +L0: Gemini 2.0 Flash (orchestrator) + ↓ 信心度不足 +L1: Hermes Ollama 預跑（5s timeout，免費） + ↓ 0 threats +L2: short-circuit 不送（避免空泛訊息）⭐ commit 56504ed 修補 +``` + +**新增供應商規則**： +- 任何新 Frontier 供應商引入需獨立 ADR（如 Phase 7 引入 Claude） +- service wrapper 必加 feature flag + `is_available()` 檢查 +- 必加 cost budget 種子 + ai_calls.provider 白名單 +- 必有對應 unit test（fallback 鏈 + cache hit/miss） + +--- + +## Alternatives Considered + +| 方案 | 否決理由 | +|---|---| +| **A. 單一 Frontier (只用 Gemini)** | 單供應商風險：API 撤銷 / 配額爆 / 政策變更全系統癱瘓 | +| **B. 全 Frontier 多家互通（all-providers fallback）** | 模型輸出格式差異大（tool_calls schema、temperature 行為），統一介面工程量 > ROI | +| **C. 自建 Code Review 用 Ollama（DeepSeek-V3）** | A2 web research 紅燈：Ollama deepseek-r1 chat template tools 假支援（GitHub Issue #10935） | +| **D. 等 Gemini 3.0 Pro GA 再升級** | Anthropic Claude Opus 4.7 已驗 Arena Elo 1548 程式碼 #1，等待無價值 | +| **E. 用 OpenRouter 統一接入所有家** | 增加中間層延遲 + 失去 Anthropic prompt cache 優勢 | + +--- + +## Consequences + +### 正面（5） +1. **單供應商風險解除**：Code Review 從 Gemini 唯一改 Claude L0，戰時可一鍵切回 Gemini L1 +2. **Code Review 品質 +7%**（Arena Elo 1548 vs ~1450） +3. **Prompt cache 隱性節省**：Code Review 重跑命中率 80%+，省 ~90% Claude 成本 +4. **Frontier 配額分散**：Claude $10 + Gemini $8 + 其他 = 不會卡單一家配額 +5. **未來新增供應商 SOP 化**：feature flag + budget + ADR 三件套 + +### 負面（3） +1. **月成本 +$20**（Claude Opus 4.7 對 Code Review 升級） +2. **依賴 Anthropic SDK**：版本升級需追蹤（requirements.txt anthropic>=0.40.0） +3. **多供應商除錯複雜度↑**：故障時要追三家失敗鏈 + +### 風險（4） +1. **Anthropic API key 洩漏**：與 Gemini 同等保護（.env + Gitea Secret） +2. **Claude Opus 4.7 模型下架**：CLAUDE_MODEL env 可即時切 sonnet-4-6 不需改 code +3. **Cache hit 不如預期**：監控 `ai_calls.cache_read_tokens` 比例，<40% 觸發 INFO 告警 +4. **多家帳單分散觀測**：token 日報 Section 4「成本拆解」需明確分家統計（已就位） + +--- + +## Verification + +### V1：service wrapper 可用性 +```python +from services.anthropic_service import anthropic_service +print(anthropic_service.is_available()) # True if ANTHROPIC_API_KEY set +print(anthropic_service.check_connection()) # True if Claude API responds +``` + +### V2：Code Review 切換驗證 +```bash +# 戰前（CODE_REVIEW_USE_CLAUDE=false） +# ai_calls 應只有 provider='gemini' for code_review_openclaw + +# 戰後（CODE_REVIEW_USE_CLAUDE=true） +# ai_calls 應有 provider='claude' + cache_read_tokens > 0（5min 內第二次） +``` + +### V3：Prompt cache 命中率 +```sql +SELECT + AVG(CASE WHEN cache_hit THEN 1.0 ELSE 0.0 END) * 100 AS cache_hit_pct +FROM ai_calls +WHERE provider = 'claude' + AND called_at > NOW() - INTERVAL '7 days'; +-- 期望 ≥ 60% （首次 + 5min 內後續） +``` + +### V4：月成本對齊預算 +```sql +SELECT provider, SUM(cost_usd) AS month_cost +FROM ai_calls +WHERE called_at > date_trunc('month', NOW()) +GROUP BY provider +ORDER BY month_cost DESC; +-- 期望: claude < $10, gemini < $8, total < $32 +``` + +--- + +## Migration Plan + +| Phase | 工作 | 狀態 | +|---|---|---| +| 7.1 | Anthropic SDK 包裝 + COST_TABLE | ✅ commit 943de84 | +| 7.2 | code_review_pipeline 加 L0 Claude 路由 | ✅ commit 943de84 | +| 7.3 | feature flag CODE_REVIEW_USE_CLAUDE 預設 OFF | ✅ commit 943de84 | +| 7.4 | requirements.txt + .env.example | ✅ commit 943de84 | +| 7.5 | 統帥手動：`.env` 加 ANTHROPIC_API_KEY + 翻 ON | ⏳ 待 | +| 7.6 | 觀察 1-2 週 cache hit rate + 成本 | ⏳ 待 | +| 7.7 | 達標後寫 ADR-031（同類 SOP 用於其他升級） | ⏳ 後續 | + +--- + +## References + +- [Anthropic Prompt Caching](https://docs.anthropic.com/en/docs/prompt-caching) +- [Arena Code LLM Leaderboard](https://arena.ai/leaderboard) — Claude Opus 4.7 Elo 1548 +- ADR-028（LLM 路由統一準則） +- ADR-029（Hermes-First 雙塔分工） +- migration 024/025（ai_calls + budgets schema） +- services/anthropic_service.py（Phase 7 落地） +- services/code_review_pipeline_service.py:46-58（feature flag） diff --git a/docs/adr/README.md b/docs/adr/README.md index afee54b..29001f1 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -51,6 +51,7 @@ | [027](ADR-027-primary-ollama-on-gcp.md) | Primary Ollama 遷移至 GCP 高效能主機（v5.0 戰役後追加附錄：三主機架構 / 4 fallback 鏈 / 廢止 188 Ollama） | Accepted | 2026-05-03 | | [028](ADR-028-llm-routing-unified-principles.md) | LLM 路由統一準則 — Ollama-First 五大支柱（補述 ADR-027） | Accepted | 2026-05-03 | | [029](ADR-029-hermes-first-twin-tower.md) | Hermes-First 雙塔分工（戰術主塔 / 戰略副塔，Gemini 月支出 -23%） | Accepted | 2026-05-03 | +| [030](ADR-030-frontier-multi-vendor-strategy.md) | Frontier 多供應商策略（Anthropic + Google + OpenRouter；Phase 7 Code Review 升 Claude Opus 4.7） | Accepted | 2026-05-03 | ## 規範