Gemini 開發者指南

課程概述

呼叫 Gemini API 不難，真正容易踩雷的是把 Demo 直接當成正式服務。官方課程教的是把 Gemini 當成開發協作者：請它解釋程式碼、推薦 Google Cloud 服務和產生程式碼，再用一個 Lab 體驗在 IDE 裡靠 Gemini 協助開發應用程式。這篇再往下走一步，從開發者自己呼叫 Gemini API 時會遇到的選擇切入：什麼時候用完整回應、串流、結構化輸出或 Function Calling，以及認證、驗證、重試和監控應該放在哪一層。

你將學到

• 使用 Google Gen AI SDK（google-genai）初始化 Gemini 模型並發送請求
• 處理多模態輸入：文字 + 圖片、文字 + 影片、文字 + 音訊
• 實作串流回應（Streaming）以提升使用者體驗
• 運用 Function Calling 讓 Gemini 呼叫外部 API 與工具
• 依任務品質、延遲、成本與支援模態選擇合適模型

核心概念

Gemini 模型家族

Gemini 有偏重複雜推理的 Pro、重視速度與成本的 Flash，以及更適合高流量工作的 Flash-Lite 等系列；另有提供裝置端能力的模型，但不能把它當成雲端 API 裡單純可互換的選項。模型名稱和生命週期變動很快，正式開發時應先列出目前可用模型，再用自己的測試集比較品質、首字延遲、總回應時間、Token 用量與支援模態，不要只看系列名稱決定。

多模態輸入的實作

Gemini 可以在一次請求裡接收文字與其他模態，例如把架構圖連同「請找出潛在單點故障」一起送出。檔案可以直接帶入、以内嵌資料提供，或先放在服務支援的儲存位置；實際格式、大小與上傳方式要看所選 API 和模型。圖片、音訊與影片都會占用上下文與費用，送出前應先縮小範圍，不要把整段影片丟進去只問其中五秒的畫面。

Function Calling 機制

Function Calling 讓模型提出「想呼叫哪個函式、要帶哪些參數」的結構化要求。真正執行函式的仍是你的應用程式，因此參數驗證、使用者授權、逾時、重試、冪等性與稽核紀錄都不能交給模型。執行完成後，再把成功結果或可處理的錯誤回傳給模型整理答案。Google Gen AI SDK 也能自動呼叫直接傳入的 Python 函式，但牽涉付款、刪除或外部寫入時，手動控制通常比較安心。

串流回應（Streaming）

一般呼叫會等回應完成後一次傳回；串流則會陸續送出內容片段，能改善使用者感受到的等待時間，但不一定縮短整體生成時間。用 Google Gen AI SDK 時，可透過 generate_content_stream() 取得同步串流。前端還要處理中途中斷、使用者取消、錯誤狀態，以及內容尚未完整時不要提早解析半截 JSON。

%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 24, "rankSpacing": 32}}}%%
flowchart TB
  subgraph CHOOSE["① 先看應用要怎麼使用結果"]
      direction TB
      START["定義結果用途、失敗方式<br/>以及使用者能等多久"] --> ACTION{"需要查資料、呼叫服務<br/>或造成外部動作嗎？"}
      ACTION -->|"不需要"| PARSE{"結果要交給程式<br/>穩定解析嗎？"}
      ACTION -->|"需要"| TOOL["使用 Function<br/>Calling<br/>讓模型只提出<br/>工具要求"]
      TOOL --> VALIDATE["應用驗證參數、<br/>權限、額度<br/>與冪等鍵"]
      VALIDATE --> EXECUTE["執行工具<br/>並把結果或錯誤<br/>回傳給模型整理"]
      PARSE -->|"要"| JSON["使用結構化輸出<br/>與 Schema<br/>收到後仍做<br/>商業規則驗證"]
      PARSE -->|"不用"| LONG{"回答較長，<br/>而且使用者<br/>需要盡快看到<br/>內容嗎？"}
      LONG -->|"需要"| STREAM["使用 Streaming<br/>處理取消、<br/>中斷與部分內容"]
      LONG -->|"不需要"| FULL["使用完整回應<br/>流程最單純"]
  end
  subgraph GUARD["② 所有路徑都要有共同保護"]
      direction TB
      EXECUTE --> CHECK["套用逾時、重試、限流、<br/>安全檢查與觀測"]
      JSON --> CHECK
      STREAM --> CHECK
      FULL --> CHECK
      CHECK --> RETURN["只把通過驗證的結果<br/>交給前端或下游系統"]
  end

實作重點

• 安裝 google-genai SDK（from google import genai），完成認證並初始化 Client；舊 Vertex AI SDK 的生成式模組自 2025 年 6 月 24 日起淘汰，官方公告的移除日是 2026 年 6 月 24 日（之後發布的 SDK 版本不再包含這些模組），舊程式應依官方遷移資訊改用 Google Gen AI SDK
• 撰寫一個同時傳入文字與圖片的多模態請求，測試圖片理解能力
• 定義兩個 Function（如天氣查詢、匯率轉換），實作完整的 Function Calling 流程
• 從目前可用模型挑選兩個候選者，用同一份測試集比較品質、首字延遲、總時間與成本
• 在 Cloud Run 上部署一個簡單的 Gemini API 後端服務

Lab 導讀

Lab 連結：Gemini for Application Developers — Google Skills

依課程頁，這門課有兩段教學影片、一個實作 Lab「Develop an app with Gemini」、一段用 Gemini 部署 Node.js 的影片和一個測驗；官方對這個 Lab 的描述是在 IDE 裡靠 Gemini 的協助開發應用程式，沒有提到 Jupyter Notebook 或用 Python 呼叫 Gemini API。本文的 SDK、串流與 Function Calling 是延伸內容，動手寫時以目前的 google-genai 寫法為準，不要混用新舊兩套物件。Function Calling 的重點是把四個角色分清楚：應用定義工具、模型提出呼叫、應用驗證並執行、模型整理結果。模型從頭到尾都不該直接握有未受限制的系統權限。

延伸學習

• Gemini 貫穿軟體開發生命週期 — Gemini 在 SDLC 各階段的應用
• 建構 GenAI 應用 — 完整的 GenAI 應用建構流程
• Agent Platform（原 Vertex AI）+ Flutter 打造 AI Agent — 把 Gemini 整合進跨平台 Agent 應用