透過 Firebase Remote Config 動態控制 AI 模型名稱與生成參數實作計畫

根據 Google 官方 Firebase AI Logic: Remotely change model name 技術規範，本實作將於 MockExam-CCNA 導入 Firebase Remote Config 機制，使 App 在不需重新打包送審的情況下，即可從遠端動態調整雲端 AI 模型（如升級至 gemini-2.5-flash、gemini-3.5-flash、gemini-2.5-pro 等）、備用模型以及生成參數（Temperature、Max Tokens）。

系統架構與設計決策

1. 依賴套件: 導入 firebase_remote_config 套件，與現有 firebase_core (v4.2.1) 及 firebase_auth、firebase_database 完美相容。
2. 參數配置:
   • gemini_model_name: 主要雲端 AI 模型名稱（預設：gemini-2.5-flash）
   • gemini_fallback_model: 備用雲端 AI 模型名稱（預設：gemini-2.5-pro）
   • ai_temperature: 生成多樣性參數（預設：0.4）
   • ai_max_tokens: 最大生成 Token 數（預設：2048）
3. 階層優先序:
   • 第一優先: 使用者／管理員在設定中手動選擇的自訂模型（若有設定）。
   • 第二優先 (預設/自動): Firebase Remote Config 即時抓取的遠端最新模型與參數。
   • 第三優先 (底層防護): 程式碼內建之靜態預設值與本地離線 Gemma 4 模型降級機制。
4. 離線與網路韌性:
   • 初始化設定合理的快取時間（正式環境 1 小時，除錯環境 0 秒）。
   • 若處於離線或連線超時，自動使用本機快取值或程式碼內建預設值，不影響 App 正常啟動與運作。

預計變更檔案 (Proposed Changes)

1. 套件依賴設定

[MODIFY] pubspec.yaml

• 在 dependencies 中加入 firebase_remote_config: ^5.3.0。

2. 核心服務層 (Services)

[NEW] lib/services/remote_config_service.dart

• 建立 RemoteConfigService 單例類別：
  • initialize(): 設定預設值映射表（Defaults Map）、抓取逾時（10 秒）與最小抓取間隔。
  • 監聽 onConfigUpdated 串流，支援 Remote Config 即時動態熱更新。
  • 提供型別安全的 Getter 方法：geminiModelName, fallbackModelName, aiTemperature, aiMaxTokens。
  • 提供手動強制重新抓取方法 fetchAndActivate()。

[MODIFY] lib/services/local_cache_service.dart

• 修改 getSelectedModel() 方法：
  • 檢查是否有使用者自訂模型；若為 auto、default 或空值，則自動向 RemoteConfigService().geminiModelName 索取遠端最新模型名稱。

[MODIFY] lib/services/ai_generator_service.dart

• 在 generateLearnEnglishForQuestion 與 tutorChatWithKeys 中整合 Remote Config 所設定的模型、ai_temperature 與 ai_max_tokens。
• 當主要模型遭遇配額超限或 API 異常時，自動切換至 RemoteConfigService().fallbackModelName 進行重試。

3. 應用程式入口

[MODIFY] lib/main.dart

• 在 Firebase.initializeApp() 之後非同步調用 RemoteConfigService().initialize()，確保在 App 啟動階段完成參數加載。

4. 遠端部署與自動化範本 (CLI & Scripts)

[NEW] scripts/remote_config_template.json

• 定義 Firebase Remote Config 參數與條件設定的標準 JSON 範本。

[NEW] scripts/publish_remote_config.ps1

• 提供使用 Firebase CLI (firebase remoteconfig:set 或 REST API) 一鍵發布 Remote Config 設定的 PowerShell 腳本。

驗證計畫 (Verification Plan)

自動化靜態分析與測試

• 執行 flutter pub get 解析依賴關係。
• 執行 flutter analyze lib 確保無任何 Lint 錯誤或編譯問題。
• 執行 flutter test 驗證既有測試皆順利通過。
• 撰寫單元測試 test/services/remote_config_service_test.dart 驗證預設值與降級邏輯。

手動驗證

• 檢查 App 啟動時是否成功讀取 Remote Config 預設值並記錄於 LogService。
• 模擬離線環境與雲端切換，確認模型回傳正常。

📘 Firebase Remote Model Config 與 AI 動態遙控全攻略（學習筆記）

💡 這是一份專為學習者與初學者編寫的完整技術筆記。即使完全沒有程式背景，跟著這份指南也能清楚理解「如何在不停機、不重新安裝 App 的情況下，隨時更換與微調 App 內的 AI 大腦」！

🧭 目錄

• 一、生活化比喻：什麼是 Remote Config？
• 二、我們實現了哪些功能？（功能總覽）
• 三、系統運作原理與四大層級架構
• 四、新手一步一步操作指南（三種操作方式）
  • 方式 A：最簡單！直接在 App 內管理介面操作（手機/電腦皆可）
  • 方式 B：登入 Firebase 官方網頁後台修改
  • 方式 C：使用終端機一鍵自動化腳本發布
• 五、程式碼檔案清單與功能說明
• 六、常見問題與避坑指南 (FAQ)

一、生活化比喻：什麼是 Remote Config？

想像一下您買了一台智慧電視（App）：

• 傳統做法：如果電視內建的節目單寫死在電視裡，電視台只要換了新節目，您就必須把整台電視搬回工廠拆開重新燒錄晶片（重新打包 App、上傳 Google Play 審核、等待使用者下載更新）。
• Remote Config 做法：電視機連上網路，電視台（Firebase 雲端）有一個中央廣播台。電視台只要按下一個按鈕切換節目名稱，全世界所有打開的電視機會像收到 LINE 訊息一樣，0.1 秒內自動切換到新節目！

在我們的 App 裡，這個「節目」就是 Google Gemini AI 模型（例如從 gemini-2.5-flash 升級成最新的 gemini-3.7-flash）。

二、我們實現了哪些功能？（功能總覽）

1. 雲端動態更換 AI 模型：
   • 隨時在雲端將主要模型切換為 gemini-3.7-flash、gemini-3.5-flash、gemini-2.5-pro 或任何未來的最新型號。
2. 即時熱更新 (Real-time Config Update)：
   • 採用 Google 官方 Real-time 機制，使用者正在使用 App 時就能自動接收新模型，不需要重開 App，也不需要重新登入。
3. 雙模型自動降級備援 (Fallback Protection)：
   • 如果主要模型剛好遇到 Google 伺服器忙線或超出免費額度 (429)，App 會在 0.5 秒內自動無縫切換到備用模型（例如 gemini-2.5-pro），使用者完全不會感受到錯誤。
4. App 內 Admin 管理面板：
   • 管理員直接在 App 的選單點擊即可調整模型、滑動拉桿微調溫度（Temperature）與最大字數（Max Tokens）。
5. 長文防截斷 (8,192 Tokens)：
   • 將輸出容量提升至 8,192 Tokens（超過 3,000 個中文字），解決研讀指南、指令速查表被中途截斷的問題。
6. 智慧主題檢索 (Topic-Aware RAG in NotebookLM)：
   • 在 NotebookLM 學習工作區輸入任何主題（如 VLAN、OSPF），系統會自動從數千頁的教材 PDF 中精準抓取對應章節進行生成。

三、系統運作原理與四大層級架構

當 App 需要向 AI 發問時，它是如何決定要用哪一個模型的？我們設計了嚴謹的「優先順序金字塔」：

┌──────────────────────────────────────────────────────────┐
│  第 1 優先（最高）：本機管理員測試覆蓋 (Local Override)   │ 👈 管理員在 App 內選「僅限本機測試」
├──────────────────────────────────────────────────────────┤
│  第 2 優先：全域 RTDB 設定 (Global Broadcast)            │ 👈 管理員在 App 內選「全域同步設定」
├──────────────────────────────────────────────────────────┤
│  第 3 優先：Firebase Remote Config 雲端參數              │ 👈 Firebase 網頁後台 / 腳本發布
├──────────────────────────────────────────────────────────┤
│  第 4 優先（最低）：App 內建靜態預設值 (Built-in Default) │ 👈 離線或無網路時的最後保險 (gemini-2.5-flash)
└──────────────────────────────────────────────────────────┘

四、新手一步一步操作指南（三種操作方式）

您可以選擇以下任何一種最適合您的操作方式：

方式 A：最簡單！直接在 App 內管理介面操作（手機/電腦皆可）

這是最直覺的方式，不需要打開任何網頁後台或終端機：

1. 登入 App：使用具有 Admin（管理員） 權限的帳號登入。
2. 打開側邊選單：點擊首頁左上角的三條線選單圖示（Drawer）。
3. 進入管理介面：在管理員專區中，點擊 「🤖 AI 模型與 Remote Config 管理」。
4. 挑選您想要設定的模型：
   • 主要模型：在下拉選單選擇最新模型（如 gemini-3.7-flash）。
   • 備用模型：選擇備援模型（如 gemini-2.5-pro）。
   • 溫度 (Temperature)：數值越低越精準嚴謹（建議 0.4），數值越高越生動活潑。
   • 最大 Token 數：建議保持 8192。
5. 選擇套用範圍：
   • 🌐 全域同步設定：按「儲存」後，全世界所有使用者的 App 會立刻收到通知並切換！
   • 📱 僅限本機測試：只有您手上的這台手機/電腦會套用新模型（適合自己除錯測試）。
6. 點擊下方綠色按鈕「套用並儲存設定」 ➔ 完成！

方式 B：登入 Firebase 官方網頁後台修改

如果您習慣在瀏覽器中管理雲端：

1. 開啟控制台網址：
   👉 https://console.firebase.google.com/project/YouProjectName/config
2. 找到參數列表：
   您會看到四個主要參數：
   • gemini_model_name：主要模型名稱（預設：gemini-2.5-flash，可修改為 gemini-3.7-flash）
   • gemini_fallback_model：備用模型名稱（預設：gemini-2.5-pro）
   • ai_temperature：溫度（預設：0.4）
   • ai_max_tokens：最大輸出字數（預設：8192）
3. 點擊鉛筆圖示進行修改：輸入新值後按「儲存 (Save)」。
4. 點擊右上角的「發布變更 (Publish changes)」 ➔ 所有 App 就會即時收到更新！

方式 C：使用終端機一鍵自動化腳本發布

如果您在電腦前開發，我們已經為您寫好了一鍵自動化 PowerShell 腳本：

1. 開啟終端機（PowerShell），確認處於專案資料夾。
2. 執行以下指令：

   powershell -ExecutionPolicy Bypass -File scripts\publish_remote_config.ps1
   

3. 腳本會自動讀取 remoteconfig.template.json 並推送到 Firebase 雲端，看到 [SUCCESS] 即代表發布完成！

五、程式碼檔案清單與功能說明

如果您想深入學習程式碼結構，以下是相關檔案的職責清單：

六、常見問題與避坑指南 (FAQ)

Q1：如果 Google 未來發布了全新的模型（例如 gemini-4.0-ultra），App 沒有預設列在選單裡怎麼辦？

A：我們已經實作了 「Google 官方 API 自動聯網查詢」 機制，您有兩種超簡單的解決方式：

1. 自動一鍵更新（推薦）：

   • 進入 App 管理介面時，系統會自動在背景向 Google 官方伺服器（https://generativelanguage.googleapis.com/v1beta/models）發送查詢。
   • 您也可以直接點擊「主要模型」旁的 「從 Google 官網更新」 按鈕。
   • 只要 Google 一發布新模型（如 gemini-4.0-ultra），該模型就會自動出現在下拉選單中（標註 GOOGLE 或 LATEST 標籤），點選即可使用！

2. 手動輸入自訂名稱：

   • 下拉選單選擇最底部的 「✍️ 自訂模型名稱 (Custom Model)」。
   • 在輸入框中手動輸入 gemini-4.0-ultra，點擊儲存即可立刻啟用！

Q2：為什麼有時候使用者不需要重開 App 就會變更，有時候需要等一下？

A：

• 正常連網狀態下，Firebase Real-time 會在數秒內透過背景長連線推送變更並自動調用 activate()。
• 若使用者當時處於弱網或飛航模式，App 會在下次連網時或下一次啟動時自動拉取最新設定。

Q3：如果主要模型被 Google 限制速率 (Rate Limited 429)，使用者會看到錯誤嗎？

A：不會！

• AiGeneratorService 內建了自動備援機制。當主要模型回傳 429 時，系統會在後台自動改用備用模型 (gemini-2.5-pro) 重新發送請求，使用者端體驗完全無縫。

筆記建立時間：2026-08-28
專案名稱：MockExam-CCNA

publish_remote_config.ps1

PowerShell script to deploy Firebase Remote Config template for MockExam-CCNA

param (
[string]$ProjectId = "YouProjectName",
[string]$TemplatePath = "$PSScriptRoot\remote_config_template.json"
)

Write-Host "=========================================================" -ForegroundColor Cyan
Write-Host " [Firebase Remote Config] Deploying AI Parameters Template" -ForegroundColor Green
Write-Host "=========================================================" -ForegroundColor Cyan

if (-not (Test-Path $TemplatePath)) {
Write-Error "Error: Cannot find template file: $TemplatePath"
exit 1
}

Write-Host "Target Project: $ProjectId" -ForegroundColor Yellow
Write-Host "Template File: $TemplatePath" -ForegroundColor Yellow

$firebaseCli = Get-Command "firebase" -ErrorAction SilentlyContinue

if ($null -ne $firebaseCli) {
Write-Host "Firebase CLI detected. Deploying remoteconfig..." -ForegroundColor Cyan
try {
# Deploy using firebase deploy command
$rootPath = Resolve-Path "$PSScriptRoot.."
firebase deploy --only remoteconfig --project $ProjectId
if ($LASTEXITCODE -eq 0) {
Write-Host ""
Write-Host "=========================================================" -ForegroundColor Green
Write-Host " [SUCCESS] Remote Config parameters successfully deployed!" -ForegroundColor Green
Write-Host " Project Console: https://console.firebase.google.com/project/$ProjectId/config" -ForegroundColor Cyan
Write-Host "=========================================================" -ForegroundColor Green
exit 0
} else {
Write-Host "Firebase CLI returned exit code $LASTEXITCODE." -ForegroundColor Yellow
}
} catch {
Write-Host "Deployment error: $_" -ForegroundColor Yellow
}
} else {
Write-Host "Firebase CLI is not found in PATH." -ForegroundColor Gray
}

Write-Host ""
Write-Host "=========================================================" -ForegroundColor Cyan
Write-Host " Manual Firebase Console Setup Instructions:" -ForegroundColor Green
Write-Host "=========================================================" -ForegroundColor Cyan
Write-Host "1. Visit Console: https://console.firebase.google.com/project/$ProjectId/config"
Write-Host "2. Click 'Remote Config' -> Add or edit the parameters below:"
Write-Host " - gemini_model_name: gemini-2.5-flash (String)"
Write-Host " - gemini_fallback_model: gemini-2.5-pro (String)"
Write-Host " - ai_temperature: 0.4 (Number)"
Write-Host " - ai_max_tokens: 2048 (Number)"
Write-Host "3. Click 'Publish changes' to sync immediately across all apps."
Write-Host "=========================================================" -ForegroundColor Cyan

remote_config_template.json

{
"parameters": {
"gemini_model_name": {
"defaultValue": {
"value": "gemini-2.5-flash"
},
"description": "Primary Gemini model name used for AI explanations, question classification, and AI Tutor chat.",
"valueType": "STRING"
},
"gemini_fallback_model": {
"defaultValue": {
"value": "gemini-2.5-pro"
},
"description": "Secondary fallback Gemini model name if the primary model fails or encounters rate limits.",
"valueType": "STRING"
},
"ai_temperature": {
"defaultValue": {
"value": "0.4"
},
"description": "Temperature parameter for AI Tutor generation (0.0 to 1.0).",
"valueType": "NUMBER"
},
"ai_max_tokens": {
"defaultValue": {
"value": "8192"
},
"description": "Maximum tokens for AI Tutor chat and English learning generation.",
"valueType": "NUMBER"
}
}
}