跳至主要內容
登雲學院 CloudOn 登雲學院.
ESC
跳到課程內容
實作入門 動手呼叫 Gemini API：從環境設定到多輪對話
0%
3 / 5 中級 50 分鐘 00:00

動手呼叫 Gemini API：從環境設定到多輪對話

使用 Google Gen AI SDK 與 Vertex AI，完成文字、圖片、串流和多輪對話的可執行練習。

2026年3月19日 Updated: 2026年7月14日

這一課的目標很單純：把 Gemini 從網頁上的試玩介面，接進一支能重複執行的 Python 程式。

我們會固定使用目前為 GA 的 gemini-3.5-flash。如果你在較晚的時間閱讀，請先查看官方模型版本與生命週期，確認 Model ID 和可用區域仍相同。

完成後會有什麼？

你會依序做到：

  1. 用 Vertex AI 驗證身分
  2. 傳送第一個文字請求
  3. 查看 Token 用量
  4. 加入圖片
  5. 串流顯示較長的回答
  6. 建立多輪對話
  7. 把這些能力組成一個需求澄清助手

所有範例都使用官方建議的 google-genai 套件。

步驟一：準備專案

你需要一個已啟用計費功能的 Google Cloud 專案。先打開 Cloud Shell，確認目前專案：

gcloud config get-value project

如果不是要使用的專案，改成自己的 Project ID：

gcloud config set project YOUR_PROJECT_ID

啟用 Vertex AI API：

gcloud services enable aiplatform.googleapis.com

目前帳號至少要能使用 Vertex AI。公司專案通常由管理員授予 Vertex AI User（roles/aiplatform.user）或等效的自訂角色。

Cloud Shell 和本機登入方式不同

Cloud Shell 已經帶有目前登入帳號的憑證，通常不必再跑登入指令。

如果你改在本機終端機操作，除了先安裝並登入 Google Cloud CLI，還要建立 Application Default Credentials（ADC）：

gcloud auth application-default login

gcloud auth login 是讓 CLI 登入；gcloud auth application-default login 則是讓本機應用程式取得 ADC。兩者用途不同，是常見的卡關點。

步驟二：建立 Python 環境

在 Cloud Shell 或本機建立虛擬環境：

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade google-genai

設定 SDK 會讀取的環境變數：

export GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_VERTEXAI="true"

這三個設定分別告訴 SDK：

  • 使用哪個 Google Cloud 專案
  • 從哪個位置呼叫模型
  • 使用 Vertex AI，而不是 Gemini Developer API

若組織政策不允許 global，請改用模型支援且公司核准的區域。

步驟三：送出第一個請求

建立 app.py：

from google import genai

MODEL_ID = "gemini-3.5-flash"

client = genai.Client()

response = client.models.generate_content(
    model=MODEL_ID,
    contents="用三個重點說明 Cloud Run 適合什麼工作負載。",
)

print(response.text)

執行：

python app.py

如果看到三個重點，代表 API、憑證、專案與模型位置都能正常配合。

也可以在程式中明確指定 Vertex AI

正式服務有時不希望依賴本機環境變數，可以明確建立 Client：

from google import genai

client = genai.Client(
    vertexai=True,
    project="YOUR_PROJECT_ID",
    location="global",
)

不要把服務帳戶金鑰直接寫進程式。部署到 Cloud Run 等 Google Cloud 服務時，應替執行環境配置服務帳戶與最小必要權限。

步驟四：查看 Token 用量

回應物件包含這次呼叫的用量資訊：

usage = response.usage_metadata

print(f"輸入 Token：{usage.prompt_token_count}")
print(f"輸出 Token：{usage.candidates_token_count}")
print(f"總 Token：{usage.total_token_count}")

欄位可能隨回應類型或 SDK 版本而略有差異，正式程式最好先判斷值是否存在。

Token 用量不只是帳單問題。當輸入突然變長，可能代表你把過多對話歷史、重複文件或不必要的資料送進模型。把用量記進監控，通常能比月底看帳單更早發現問題。

步驟五：加入圖片

Gemini 可以同時看文字和圖片。準備一張 architecture.png，再把下面程式加入 app.py：

from pathlib import Path

from google import genai
from google.genai import types

MODEL_ID = "gemini-3.5-flash"
client = genai.Client()

image_bytes = Path("architecture.png").read_bytes()

response = client.models.generate_content(
    model=MODEL_ID,
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type="image/png",
        ),
        "請描述這張架構圖的資料流，並列出兩個需要確認的風險。"
    ],
)

print(response.text)

如果檔案是 JPEG，mime_type 要改成 image/jpeg。副檔名與 MIME type 對不上時，API 可能無法正確解析。

模型可以幫忙看圖，但它不知道圖中沒有畫出的網路政策、流量與復原需求。比較安全的問法是請它列出「需要確認的資訊」，而不是要求它直接宣告架構一定安全。

步驟六：串流顯示回答

較長的回答如果等全部生成完才顯示，使用者會覺得介面卡住。可以改用串流：

from google import genai

MODEL_ID = "gemini-3.5-flash"
client = genai.Client()

for chunk in client.models.generate_content_stream(
    model=MODEL_ID,
    contents="用條列方式比較 Cloud Run、GKE 與 Compute Engine 的選擇條件。",
):
    if chunk.text:
        print(chunk.text, end="", flush=True)

print()

串流改善的是感受時間，不會縮短模型實際完成整段回答所需的計算，也不代表費用變少。

步驟七：加入系統指示

當應用程式需要固定角色、語言或行為，可以放在 system_instruction：

from google import genai
from google.genai import types

MODEL_ID = "gemini-3.5-flash"
client = genai.Client()

response = client.models.generate_content(
    model=MODEL_ID,
    contents="我們的 API 偶爾出現 503，應該先看什麼？",
    config=types.GenerateContentConfig(
        system_instruction=(
            "你是雲端維運助理。使用繁體中文回答。"
            "先詢問缺少的環境資訊，再提供檢查順序；"
            "不要在沒有證據時直接判定根因。"
        ),
    ),
)

print(response.text)

系統指示能穩定行為，但不是安全邊界。應用程式的權限、資料過濾與工具核准，仍要由程式和雲端權限控制。

步驟八：建立多輪對話

Chat 介面會替目前程式保存對話歷史：

from google import genai
from google.genai import types

MODEL_ID = "gemini-3.5-flash"
client = genai.Client()

chat = client.chats.create(
    model=MODEL_ID,
    config=types.GenerateContentConfig(
        system_instruction="你是需求澄清助手。資訊不足時先提問，不要自行補完。",
    ),
)

first = chat.send_message(
    "我們想把一個內部 API 搬到 Google Cloud。"
)
print(first.text)

second = chat.send_message(
    "目前每天約一萬次請求，容器已經可以在本機執行。"
)
print(second.text)

SDK 會把歷史訊息送回模型，所以對話越長，輸入 Token 通常也會增加。

這個 Chat 物件也不是永久的對話資料庫。程式關閉後若要繼續同一段對話，應用程式必須自行保存必要歷史，並決定何時摘要或捨棄舊訊息。

綜合練習：需求澄清助手

把前面的概念組成一支小工具。它的任務不是直接推薦架構，而是先把缺少的資訊問完整。

from google import genai
from google.genai import types

MODEL_ID = "gemini-3.5-flash"
client = genai.Client()

SYSTEM_INSTRUCTION = """
你是 Google Cloud 需求澄清助手，使用繁體中文。
收到需求後：
1. 先整理已知條件。
2. 列出最多五個會影響架構選擇、但目前缺少的問題。
3. 如果資訊不足，不要直接選產品或估算費用。
4. 若提到價格，提醒使用者回到官方定價頁確認。
"""

request = """
我們要把現有網站搬上雲端。
平常流量不大，但每月活動日會突然增加。
團隊只有兩位工程師。
"""

response = client.models.generate_content(
    model=MODEL_ID,
    contents=request,
    config=types.GenerateContentConfig(
        system_instruction=SYSTEM_INSTRUCTION,
    ),
)

print(response.text)
print(f"總 Token：{response.usage_metadata.total_token_count}")

接著替它補上三種測試：

  • 完全沒有流量、資料庫與合規資訊
  • 已提供流量，但沒有可接受的停機時間
  • 資訊看似完整，卻要求模型保證每月費用

觀察它是否會先問問題，以及是否避免做出沒有根據的保證。這就是最小型的模型行為測試。

常見錯誤怎麼查？

401 或 ADC 相關錯誤

本機通常是 ADC 尚未建立或已失效。重新執行：

gcloud auth application-default login

部署環境則要檢查服務帳戶，不要在正式環境使用個人憑證。

403 Permission denied

依序確認：

  • Vertex AI API 是否已啟用
  • SDK 使用的專案是否正確
  • 目前身分是否具備 Vertex AI 使用權限
  • 組織政策是否限制該區域或服務

404 找不到模型

通常是 Model ID 打錯、模型已換版，或目前位置不支援。查看模型文件後，再一起確認 GOOGLE_CLOUD_LOCATION。

429 Resource exhausted

可能碰到配額或速率限制。正式程式要加入指數退避與重試，也要避免對不可重試的錯誤一直重送。若流量穩定超過配額，再依官方流程申請調整。

清理環境

這個練習不會建立 VM 或資料庫，但 API 呼叫仍可能產生費用。做完後可以離開虛擬環境：

deactivate

若這是專門練習用、之後不再使用的專案，也可以停用 Vertex AI API：

gcloud services disable aiplatform.googleapis.com

共用專案不要隨意停用服務，因為可能影響其他工作負載。

課後檢查

你現在應該能回答：

  • 為什麼 Vertex AI Client 需要專案、位置與 ADC？
  • 串流和一般回應的差別是什麼？
  • Chat 歷史為什麼會讓 Token 用量增加？
  • 系統指示為什麼不能取代 IAM 和應用程式驗證？

下一課會處理 Prompt。重點不會是背「神奇咒語」，而是把任務規格寫清楚，再用測試案例反覆確認輸出。

官方資料

徽章解鎖！