新增 Gemma 4 31B 地端模型 — 操作步驟
1
Gemma 4 目前的 vLLM 版本（v0.22.1）有支援，不需要更換 image。
但這個模型不在部署包內建的模型清單裡，需要自行新增一份模型定義檔，
並準備模型權重，兩者到位後才能安裝。


【重要：四個名稱必須完全一致】

以下四個地方的名稱要一模一樣，任一個對不上都會導致部署失敗或模型無法載入：

  1. 定義檔名          gemma-4-31b.yml
  2. 權重目錄          /opt/maiagent/ai-models/gemma-4-31b/
  3. served-model-name gemma-4-31b
  4. params.yml 的 name gemma-4-31b


【步驟一】新增模型定義檔

路徑：roles/ai_modules/modules/gemma-4-31b.yml

---
kind: llm
default_port: 8004
shm_size: "16g"
command:
  - "--model"
  - "/models"
  - "--served-model-name"
  - "gemma-4-31b"
  - "--dtype"
  - "bfloat16"
  - "--max-model-len"
  - "131072"
  - "--gpu-memory-utilization"
  - "0.90"
  - "--enable-chunked-prefill"
  - "--enable-prefix-caching"
  - "--trust-remote-code"
model_source:
  huggingface_repo: "google/gemma-4-31b-it"
  expected_size_gb: 62
  needs_hf_cache: true
fixture:
  name: "Gemma 4 31B"
  context_window: 131000
  max_tokens: 4096
  is_tool_calling_available: true
  is_functional_calling_available: false
  is_multi_modal_support: false


【步驟二】放置模型權重

把權重放到：/opt/maiagent/ai-models/gemma-4-31b/
（約 62GB。目錄名稱務必與上面的模型名稱一致）


【步驟三】params.yml 新增設定

ai_modules:
  - name: gemma-4-31b
    deploy: true
    gpu_device_ids: ["4"]

說明：指定 GPU 4（目前完全閒置的卡），讓這個模型獨占一張，
不與其他服務搶顯存。


【步驟四】部署

./scripts/install.sh -- --tags ai_modules

只重建 AI 模組，不影響其他已上線的服務。


【步驟五】驗證

# 看啟動狀況，出現 Application startup complete 即成功
docker logs -f ai-gemma-4-31b

# 確認模型已註冊
curl -s http://localhost:8004/v1/models

# 實際問一句
curl -s http://localhost:8004/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma-4-31b","messages":[{"role":"user","content":"你好"}],"max_tokens":50}'

另外到平台後台確認模型清單裡有出現這個模型。


【需要事先確認的兩項】

1. HuggingFace repo 名稱
   定義檔中的 google/gemma-4-31b-it 為暫定，實際名稱請以官方為準。

2. 權重大小
   62GB 為估算值（31B 參數 × bf16）。

以上兩項確認後再開始，避免下載到錯誤的模型。


【備註】

Gemma 系列在 HuggingFace 屬於 gated model，自行下載需先申請授權並設定 token。