前情提要

我有一個自己每天在用的 LINE Bot，linebot-helper-python。日常拿來丟網址回摘要、丟 YouTube 連結針對影片內容追問、查地圖景點跟管書籤。在模型配置上，為了平衡回應速度與荷包，許多工作流先前陸續跑在 Gemini 3.5（像是負責高吞吐、低延遲分類與資料擷取的 gemini-3.5-flash-lite）以及 Gemini 3.6（負責多步驟工具呼叫與多模態推理的 gemini-3.6-flash）上。

十月中 Google 正式把 Gemini 4 Argon (gemini-4-argon) 推上 GA 穩定版（搭配 Python google-genai >= 2.30.1）。

看完官方公告與遷移文件，表面上最吸引人的是那些大數字：輸入、思考與輸出共用的 1M 統一 Token 視窗、單次呼叫自動接力跑到 100 萬輸出 Token 的 Long Decode、正式 GA 且省下 88% Token 的 Agentic Video Understanding，還有已經成為預設主流的 Interactions API (/v1beta/interactions)。

但如果你的目標跟我一樣，是想把現有 LINE Bot 裡面的 Gemini 3.5 / 3.6 升級（或部分切換）到 Gemini 4 Argon，千萬不要以為只是把 model="gemini-3.6-flash" 改成 model="gemini-4-argon" 就收工了。

這一代在參數規範、Token 預算計算方式、快取機制，甚至等待時間的假設上，都有幾個剛好打在 LINE Bot 痛點上的改變。這篇把從 3.5 / 3.6 轉移到 Gemini 4 需要注意的細節全部整理起來。

先看規格對照：3.5 Flash-Lite / 3.6 Flash vs. Gemini 4 Argon

在動手改設定之前，先把這三顆模型放在同一張表上看清楚它們的定位差異：

光看這張表，就能抓出幾個直接換模型名稱會踩到的雷。下面逐條拆解。

踩坑一：LINE Bot 習慣把 max_output_tokens 設很小，在 Gemini 4 會直接拿回空字串

這是 LINE Bot 開發者最容易中招的第一個暗坑。

因為 LINE 單則文字訊息有 5,000 字上限，而且手機螢幕閱讀不適合長篇大論，很多人（包含以前的我）習慣在 GenerateContentConfig 裡把 max_output_tokens 設成 2048 或 4096，當作一道省錢兼防爆字數的保險。

在 Gemini 4 Argon 上這樣設，遇到稍微複雜一點的問題，你會發現模型回傳 finish_reason: "MAX_TOKENS"，但 response.text 是空的，或是講不到兩句話就斷頭了。

原因是 Gemini 4 Argon 改採 Unified 1M Input-Output Window，而且有兩條硬規則：

1. Thinking tokens 直接算進 max_output_tokens 預算裡：模型在回答前花掉的每一顆思考 Token，都在扣你的 max_output_tokens。當問題需要深度推理時，模型很容易光靠思考就把你設的 4096 額度全部燒光，還沒開始吐出正式回答就撞牆停下來了。
2. generateContent 非串流（Non-streaming）單次請求上限從 64K 降為 32K：在 Gemini 3.5 / 3.6 上，單次非串流回應上限是 65,536；到了 gemini-4-argon，若繼續走傳統 generateContent，非串流單次上限被調降為 32,768 tokens（串流或是改走新版 Interactions API 同步呼叫則是 65,536）。

原因與解法： 官方遷移指南寫得很明白——如果你的舊專案把 max_output_tokens 設在 32K 以下，升上 gemini-4-argon 請至少調高到 32768（或乾脆保留預設的 65536）。

在 Gemini 4 裡，max_output_tokens 是拿來當「防止極端狀況把錢燒乾的總煞車」，不是拿來控制回答字數的。

• 想要少花一點 Token、加快回應速度：去調低 thinking_level="low"。
• 想要讓輸出符合 LINE 訊息長度：寫在 system_instruction 裡（例如「請控制在 400 字以內、使用條列式重點」）。

# ❌ 以前在 LINE Bot 常寫的防爆設定，在 gemini-4-argon 上思考過程就會把 2048 吃光
config = types.GenerateContentConfig(
    max_output_tokens=2048,
)

# ✅ Gemini 4 Argon 正確寫法：放寬 max_output_tokens，用 thinking_level 控制成本與延遲
config = types.GenerateContentConfig(
    max_output_tokens=32768,
    thinking_config=types.ThinkingConfig(thinking_level="low"),
    system_instruction="你是 LINE 助理，回答請精簡扼要，控制在 500 字以內。",
)

踩坑二：thinking_level 的檔位差異——3.5-flash-lite 的 "minimal" 不能直接搬過來

如果你原本在 Gemini 3.5 / 3.6 已經把舊時代的 thinking_budget（傳整數 Token 數量）改成了 thinking_level，這裡還有一個小陷阱：

• 在 gemini-3.5-flash-lite 上，預設的思考等級叫做 "minimal"。
• 但在 gemini-4-argon 上，支援的檔位只有三檔："low"、"medium"（預設）、"high"。

如果你的 config 共用了同一個產生器，把 "minimal" 原封不動帶進 gemini-4-argon，或是還留著舊的 thinking_budget（雖然目前 API 會幫你映射成最接近的 level，但會回傳 deprecation warning），都會讓設定變得不乾淨。

對 LINE Bot 來說，這三檔在 gemini-4-argon 的實務分工非常明確：

• "low"：LINE 一般對話、網址摘要、即時問答的首選。Token 消耗最少、首字延遲（TTFT）最低。
• "medium"（預設）：適合需要呼叫多支工具（Function Calling）、讀長影片或寫程式的場景。
• "high"：深度數學、複雜行程最佳化、長篇分析。注意：開到 "high" 幾乎不可能在 LINE 的 replyToken 有效時間內跑完，一定要走非同步推播架構。

踩坑三：LINE Webhook 的幾秒壽命 vs. 官方建議的「20 分鐘 Timeout」

讀 Gemini 4 Argon 遷移文件的時候，有一條項目讓我看了直接笑出來：

Increase client timeouts: Set HTTP client timeouts to at least 15–20 minutes per call.

官方甚至在 Long Decode 章節補了一個 Note：遇到困難任務時，gemini-4-argon 可能會把整整一個 32K 或 64K 的 hop 全部拿去思考，直到下一個 hop 才吐出真正的答案（在 generateContent 下，新版 SDK google-genai >= 2.30.1 預設開啟 automatic_continuation=True，會在客戶端用 continuation_token 自動幫你跑迴圈接下去；而在 Interactions API 下，若要超過單次同步上限 65536 則必須開啟 background=True 交給伺服器端跑多輪 hop）。

這在自己電腦跑 CLI 腳本完全沒問題；但放在 LINE Bot + Cloud Run 的架構下，在客戶端同步死等叫做災難：

1. LINE 的 replyToken 壽命極短，等不了你思考兩分鐘。
2. LINE 使用者在聊天室盯著畫面超過 10 秒沒反應，就會開始狂按第二次、第三次。
3. 如果你在同一個 Webhook request 裡同步死等 automatic_continuation 跑完好幾個 hop，Cloud Run 的連線跟 worker 很快就會被卡死。

原因與解法：要把 Gemini 4 放進 LINE Bot，架構上必須做兩件事：

1. 不要淘汰 3.5 / 3.6，而是做成「快慢模型路由」

官方在文件中特地強調 gemini-3.6-flash 與 gemini-3.5-flash-lite 依然是線上穩定供應的主力模型。最健康的 LINE Bot 架構不是「全部換成 gemini-4-argon」，而是：

• 第一線秒回 / 意圖分類 / 簡單結構化萃取：繼續交給 gemini-3.5-flash-lite（$0.30/1M，極快）或 gemini-3.6-flash（$1.50/1M，少廢話、工具呼叫省步數）。
• 重度推理 / 長影片追問 / 複雜任務：才路由給 gemini-4-argon。

2. 重任務改走新版 Interactions API 的 background=True + webhook_config

這一代 Google 把我們熟悉的 generateContent 標上了 (Legacy)，在文件首頁全面改推 Gemini Interactions API (/v1beta/interactions)。

Interactions API 對 LINE Bot 最大的價值，就是它原生支援 background=True 跟 Webhooks（支援專案級註冊的 Static Webhooks，或是單次請求夾帶的 Dynamic webhook_config）：

1. 使用者在 LINE 問了一個需要 gemini-4-argon 開 "high" 思考或跑長輸出的問題。
2. LINE Bot 先呼叫 LINE Loading Animation API，並用 replyToken 秒回：「這題比較深，我正在背景深度推理中，完成後直接推播給您！」
3. 同時呼叫 client.interactions.create(..., background=True, webhook_config=...)，把任務丟給 Google 伺服器端自己慢慢跑多輪 hop，而且還可以把 line_user_id 直接塞進 user_metadata 讓 Google 回呼時原封不動帶回來。
4. 等 Google 算完發送 interaction.completed 事件打你的 /webhooks/gemini 端點時，再用 client.interactions.get(interaction_id) 取回結果（若跑了超過 64K 的多輪 Long Decode，所有段落會完整記錄在 interaction.steps 的 model_output 中），從容呼叫 LINE 的 push_message 把結果推進聊天室。

from google import genai

client = genai.Client()

def dispatch_heavy_line_task(line_user_id: str, prompt: str):
    # 交給 Google 伺服器在背景執行（連 Long Decode 的多輪 64K hop 都會在伺服器端自動接完）
    interaction = client.interactions.create(
        model="gemini-4-argon",
        input=prompt,
        background=True,
        generation_config={
            "max_output_tokens": 131072,
            "thinking_level": "high",
        },
        webhook_config={
            "uris": ["https://your-cloud-run.a.run.app/webhooks/gemini"],
            "user_metadata": {"line_user_id": line_user_id},
        },
    )
    return interaction.id

踩坑四：Explicit Caching 直接報錯——Prompt 的排列順序決定你省不省得到 95%

如果你的 LINE Bot 裡塞了一整份產品 FAQ、長篇 System Instruction，或是使用者上傳的大型文件，以前為了省錢可能會寫 client.caches.create() 建立 Explicit Cache，再把 cached_content 塞進 GenerateContentConfig。

升上 gemini-4-argon 後，這段程式碼必須全部拔掉。

gemini-4-argon 不支援 Explicit Caching，只要你呼叫 caches.create 或在 config 裡帶 cached_content，API 會直接回傳 Error。

取而代之的是全面預設開啟的 Implicit Caching（隱式快取）：

• 只要單次 Prompt 長度達到 4,096 tokens 以上，且前面的內容（Prefix）跟先前的請求一致，系統會自動命中快取。
• 快取命中的 Input Tokens 直接給 95% 折扣（打 0.5 折）——以早鳥價來說，從 $2.00 / 1M 直接掉到 $0.10 / 1M，比 gemini-3.5-flash-lite 還便宜！（甚至連 Long Decode 自動接續下一輪 hop 時，前面重複的 Context 也會自動套用 95% 快取折扣。）

對 LINE Bot 的關鍵影響： 既然變成了自動前綴比對（Prefix Matching），你在組裝 Prompt 時的順序就決定了帳單厚度：

• 永遠放在最前面（不可變動）：長篇 system_instruction、共用的背景知識庫、Few-shot 範例、該群組固定的背景文件。
• 永遠放在最後面（每次變動）：current_time 時間戳記、LINE 使用者的名稱/狀態、當下這一則訊息。

只要你不小心把「現在時間：2026-10-15 21:40:02」寫在 System Prompt 的第一行，每次請求的第一個 Token 就都不一樣，95% 的快取折扣當場歸零。

踩坑五：從 3.5 / 3.6 一路收緊的鐵則——取樣參數、Prefill 與 Thought Signatures

這三條規則其實從 gemini-3.5-flash-lite 和 gemini-3.6-flash 就已經開始執行，但如果你是跨版本整理 codebase，務必一起清乾淨：

1. 移除 temperature、top_p、top_k、candidate_count

這四個取樣參數在 Gemini 3.5 / 3.6 與 Gemini 4 Argon 上全部棄用且被忽略（官方預告後續世代帶這些參數會直接回 HTTP 400）。以前習慣設 temperature=0.0 來確保 Bot 穩定輸出格式，現在請全部刪掉，改用 Structured Outputs (response_schema) 與明確的 system_instruction。

2. 禁止 Prefilled Model Turn（最後一輪不能是 role: "model"）

以前有個常見的 Prompt 技巧：為了阻止模型講「好的！以下為您整理…」這類開場白，或是逼它直接從 { 開始吐 JSON，會在 contents 陣列的最後一筆塞一個 {"role": "model", "parts": [{"text": "{"}]}。

現在只要 payload 的最後一輪非空內容是 model 角色，API 會直接回傳 HTTP 400 Error。想壓掉開場白，請乖乖寫進 system_instruction。

3. 多輪對話與 Function Calling 必須保留 thought_signature（或乾脆改用 previous_interaction_id）

LINE Bot 在跑多步驟工具呼叫（例如：先查書籤 DB $\rightarrow$ 再抓網頁內容 $\rightarrow$ 最後整理摘要）時，模型回傳的 Part 裡會帶有 thought_signature。如果你自己手刻陣列維護對話歷史，卻只把文字跟 function_call 抽出來重組、漏掉了 thought_signature，多輪工具呼叫的品質會大幅退化甚至報錯。

不想自己管 thought_signature 序列化的人，升級到 Gemini 4 最省事的做法是改用 Interactions API 的 previous_interaction_id：

# 只在 Redis 記住該 LINE user 上一次的 interaction.id，歷史狀態與 thought_signature 全交給 Google 伺服器管
interaction = client.interactions.create(
    model="gemini-4-argon",
    input=user_message,
    previous_interaction_id=last_interaction_id,
)

真正值得為它改 LINE Bot 的新武器：Agentic Video Understanding GA

講完所有避坑事項，最後講一個升級 gemini-4-argon（以及搭配 3.8-flash）對 LINE Bot 最有感的正向升級：Agentic Video Understanding 正式 GA。

我的 LINE Bot 有一個核心功能是「丟 YouTube 連結進來，直接對影片內容連續追問」。 以前傳統的影片理解（static 模式）是把整支影片每秒截一張圖（1 FPS）塞進 Context Window，遇到 30～60 分鐘的長演講或 Podcast 影片，就算 Context 塞得下，Token 消耗也非常驚人。

切成 Agentic 模式後（注意：在包含 gemini-4-argon 的所有模型上預設還是 static，必須顯式開啟），模型的行為變成了：

1. 先讀音軌逐字稿與時間軸結構。
2. 根據使用者的問題，自己決定要「拉時間軸」跳去哪幾個秒數區間。
3. 只針對關鍵畫面動態載入高解析度與高幀率的影格來細看。

無論你是用新版 Interactions API 還是原本的 generate_content，記得都要加上對應的參數（兩邊的參數名稱與大小寫略有不同）：

# 寫法 A：使用新版 Interactions API (參數為 processing="agentic")
interaction = client.interactions.create(
    model="gemini-4-argon",
    input=[
        {
            "type": "video",
            "uri": youtube_url,
            "mime_type": "video/mp4",
            "processing": "agentic",  # 記得顯式打開，預設仍是 static
        },
        {
            "type": "text",
            "text": "講者在影片中展示架構圖的那一頁，提到的三個瓶頸是什麼？請附上 [MM:SS] 時間戳記。",
        },
    ],
    generation_config={
        "max_output_tokens": 32768,
        "thinking_level": "medium",
    },
)

# 寫法 B：使用傳統 generate_content (參數為 media_processing="AGENTIC")
response = client.models.generate_content(
    model="gemini-4-argon",
    contents=[
        types.Part.from_uri(
            file_uri=youtube_url,
            mime_type="video/mp4",
            media_processing="AGENTIC",  # 記得顯式打開，預設仍是 STATIC
        ),
        "講者在影片中展示架構圖的那一頁，提到的三個瓶頸是什麼？請附上 [MM:SS] 時間戳記。",
    ],
    config=types.GenerateContentConfig(
        max_output_tokens=32768,
        thinking_config=types.ThinkingConfig(thinking_level="medium"),
    ),
)

官方實測在 5～10 分鐘以上的長影片與「大海撈針」式的細節提問上，Token 用量最高省下 88%，準確率還提升了 7%。光是這一點，就把 gemini-4-argon 較高的單價完全賺回來了。

升級檢查清單（Checklist）

最後整理一份給 LINE Bot 專案的 PR 自我檢查清單，從 Gemini 3.5 / 3.6 升上 gemini-4-argon 前逐項打勾：

1. SDK 與帳單確認：google-genai 升到 >= 2.30.1；確認 API Key 所屬專案已綁定 Paid Tier（Free Tier 與 Google AI Pro 無法呼叫 gemini-4-argon）。
2. 拔掉取樣參數與 Prefill：全專案搜尋並移除 temperature、top_p、top_k、candidate_count，以及任何以 role="model" 結尾的預填 prompt。
3. 移除 Explicit Caching：拔掉 caches.create 與 cached_content；檢查 Prompt 組裝邏輯，確保固定不變的長 System Instruction 放在最前面以觸發 95% 折扣的 Implicit Caching。
4. 調高 max_output_tokens：把小於 32768 的上限調高到至少 32768（避免被思考 Token 吃光預算導致空回應），字數限制改寫進 system_instruction。
5. 檢查 thinking_level 枚舉值：把 3.5-flash-lite 專用的 "minimal" 或舊的 thinking_budget 換成 "low"、"medium" 或 "high"。
6. 快慢分流與非同步推播：需要在 LINE replyToken 幾秒內秒回的任務設為 thinking_level="low" 或繼續交給 3.5-flash-lite / 3.6-flash；深度推理任務改走 Interactions API (background=True + webhook_config) 搭配 LINE push_message。
7. 影片理解打開 Agentic 模式：處理 YouTube 或長影片時，在 Part.from_uri 加上 media_processing="AGENTIC"（或 Interactions API 加上 "processing": "agentic"）。

如果你有用支援 Skills 的 Coding Agent（像是 Antigravity 或 Claude Code），官方這次也直接提供了一支遷移 Skill（/gemini-api-dev migrate my app to Gemini 4 Argon）可以幫忙自動掃描上面這些參數變更。不過架構層面的「LINE replyToken 逾時分流」跟「Prompt 前綴快取順序」，還是得靠自己動手設計。