動手做：用 Gemini API 打造你的第一個 AI 應用

動手做：用 Gemini API 打造你的第一個 AI 應用

上一課我們認識了 Google Cloud 的 AI 產品全景，現在是時候捲起袖子寫程式了。這堂課會帶你從零開始，用最新的 Google GenAI SDK 呼叫 Gemini 3.1 API，一步步完成文字生成、圖片分析、串流回應、系統指令到多輪對話，最後再做一個實戰小專案。

前置準備

開始之前，請確認以下環境已準備好：

1. GCP 專案 — 已建立 Google Cloud 專案並設定付費帳戶
2. 啟用 API — 在 GCP Console 啟用 Vertex AI API
3. 安裝 gcloud CLI — 並完成身份驗證
4. Python 3.10+ — 本課程的範例皆使用 Python

在終端機執行以下指令完成身份驗證：

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

💡 提示：如果你還沒有 GCP 專案，可以使用 Google Cloud 免費方案，新帳號提供 300 美元的免費額度，足夠完成本課所有練習。

Step 1：安裝 Google GenAI SDK

Google 在 2025 年底推出了全新的 google-genai SDK，統一了過去 google-cloud-aiplatform 和 vertexai 等多套 SDK 的功能，API 設計更簡潔直覺。

pip install google-genai

安裝完成後，快速確認版本：

import google.genai
print(google.genai.__version__)

💡 提示：本課使用的是新版 google-genai SDK，不是舊版的 google-cloud-aiplatform 或 vertexai。如果你在網路上找到使用 vertexai.generative_models 的範例，那是舊版 API，不建議新專案使用。

Step 2：基本文字生成

先從最簡單的開始——送一段文字給 Gemini，讓它回應：

from google import genai

# 建立客戶端，連接 Vertex AI
client = genai.Client(project='YOUR_PROJECT', location='us-central1')

# 呼叫 Gemini 3.1 Flash 模型
response = client.models.generate_content(
    model='gemini-3.1-flash',
    contents='用一段話解釋什麼是 Kubernetes'
)

print(response.text)

執行結果會類似這樣：

Kubernetes 是一個開源的容器編排平台，用於自動化部署、擴展和管理容器化應用程式，
讓開發團隊能夠在大規模叢集中可靠地運行服務。

就這麼簡單！三行核心程式碼就能呼叫 Gemini API。

回應物件結構

response 不只有 .text，還包含其他實用資訊：

# 查看 token 使用量
print(f"輸入 tokens: {response.usage_metadata.prompt_token_count}")
print(f"輸出 tokens: {response.usage_metadata.candidates_token_count}")
print(f"總計 tokens: {response.usage_metadata.total_token_count}")

💡 提示：我們選用 gemini-2.5-flash 是因為它速度快、成本低，適合大部分場景。只有在需要最強推理能力時才考慮升級到 gemini-2.5-pro。

Step 3：多模態——圖片分析

Gemini 最強大的特色之一就是原生多模態支援。你可以直接把圖片丟給它分析：

from google import genai
from google.genai import types

client = genai.Client(project='YOUR_PROJECT', location='us-central1')

# 從本地載入圖片
with open('architecture-diagram.png', 'rb') as f:
    image_bytes = f.read()

# 建立圖片 Part
image_part = types.Part.from_bytes(data=image_bytes, mime_type='image/png')

# 送出文字 + 圖片的混合請求
response = client.models.generate_content(
    model='gemini-3.1-flash',
    contents=[
        '請分析這張架構圖，說明它使用了哪些 GCP 服務，並指出潛在的改善建議。',
        image_part
    ]
)

print(response.text)

你也可以直接使用網路圖片的 URI：

image_part = types.Part.from_uri(
    file_uri='gs://your-bucket/diagram.png',
    mime_type='image/png'
)

💡 提示：Gemini 2.5 支援的圖片格式包含 PNG、JPEG、GIF、WebP。單張圖片最大 20 MB，單次請求最多可傳入多張圖片。

Step 4：串流回應（Streaming）

當 AI 需要生成較長的回應時，等待全部生成完畢才顯示會讓使用者覺得卡住了。串流回應讓你能逐步接收並顯示內容，大幅提升使用體驗：

from google import genai

client = genai.Client(project='YOUR_PROJECT', location='us-central1')

# 使用 generate_content_stream 取得串流回應
response_stream = client.models.generate_content_stream(
    model='gemini-3.1-flash',
    contents='請詳細說明如何在 GCP 上設計一個高可用的微服務架構，包含至少 5 個服務元件。'
)

# 逐段印出回應
for chunk in response_stream:
    print(chunk.text, end='', flush=True)

# 換行
print()

執行時你會看到文字一段一段地冒出來，就像 ChatGPT 的打字效果。

串流 vs 非串流的取捨

Step 5：系統指令（System Instructions）

系統指令讓你定義 AI 的角色、語氣和行為規範，就像是給 AI 一份「工作說明書」：

from google import genai
from google.genai import types

client = genai.Client(project='YOUR_PROJECT', location='us-central1')

response = client.models.generate_content(
    model='gemini-3.1-flash',
    config=types.GenerateContentConfig(
        system_instruction='你是一位資深 GCP 架構師，擁有 10 年雲端經驗。回答時請使用繁體中文，語氣專業但親切。如果問題超出 GCP 範圍，請禮貌地引導回 GCP 相關主題。回答盡量簡潔，重點條列。'
    ),
    contents='我想把公司的 monolith 應用搬到雲端，該怎麼規劃？'
)

print(response.text)

有了系統指令，同一個模型就能扮演不同角色——客服助理、程式碼審查員、翻譯專家，全靠系統指令來切換。

系統指令的最佳實踐

• 明確描述角色和專長領域
• 指定回應的語言和格式（條列、表格、段落）
• 設定邊界——哪些問題不回答
• 保持指令簡潔，避免過於冗長導致效果下降

Step 6：多輪對話（Multi-turn Chat）

真實的 AI 應用通常需要多輪來回對話，而不是單次問答。google-genai SDK 提供了方便的 Chat 介面：

from google import genai
from google.genai import types

client = genai.Client(project='YOUR_PROJECT', location='us-central1')

# 建立 Chat session，帶有系統指令
chat = client.chats.create(
    model='gemini-3.1-flash',
    config=types.GenerateContentConfig(
        system_instruction='你是一位 GCP 考試教練，幫助學生準備 Cloud Digital Leader 認證。用繁體中文回答，每次回答都附上一個小測驗題。'
    )
)

# 第一輪對話
response1 = chat.send_message('什麼是 Cloud Run？')
print(f"AI：{response1.text}\n")

# 第二輪對話——模型會記住上下文
response2 = chat.send_message('它跟 GKE 差在哪裡？')
print(f"AI：{response2.text}\n")

# 第三輪對話
response3 = chat.send_message('那什麼情況下該選 Cloud Run？')
print(f"AI：{response3.text}\n")

注意第二輪問「它跟 GKE 差在哪裡」，模型知道「它」指的是 Cloud Run，因為它保留了對話歷史。

對話也支援串流

response_stream = chat.send_message_stream('幫我總結到目前為止的重點')
for chunk in response_stream:
    print(chunk.text, end='', flush=True)
print()

實戰練習：GCP 架構建議器

把上面學到的技巧結合起來，做一個簡單的「GCP 架構建議器」——使用者描述需求，AI 推薦適合的 GCP 架構方案：

from google import genai
from google.genai import types

client = genai.Client(project='YOUR_PROJECT', location='us-central1')

SYSTEM_PROMPT = """你是「雲端架構顧問 Nimbus」，專精 Google Cloud Platform 架構設計。

你的職責：
1. 根據使用者的需求，推薦最適合的 GCP 架構方案
2. 說明推薦的理由，包含成本、效能、可維護性的考量
3. 提供簡單的架構示意（用文字描述元件與連接方式）
4. 提醒需要注意的安全性與合規要點

回答格式：
- 使用繁體中文
- 先用一句話總結推薦方案
- 再分「推薦架構」「為什麼選這個」「預估成本等級」「注意事項」四個區塊說明
- 成本等級用 💰（低）💰💰（中）💰💰💰（高）表示
"""

# 建立對話
chat = client.chats.create(
    model='gemini-3.1-flash',
    config=types.GenerateContentConfig(
        system_instruction=SYSTEM_PROMPT,
        temperature=0.7,
        max_output_tokens=2048
    )
)

print("🏗️ GCP 架構建議器（輸入 'exit' 結束）")
print("=" * 50)

while True:
    user_input = input("\n你的需求：")
    if user_input.lower() == 'exit':
        print("感謝使用，祝你的架構設計順利！")
        break

    response_stream = chat.send_message_stream(user_input)
    print("\nNimbus 建議：")
    for chunk in response_stream:
        print(chunk.text, end='', flush=True)
    print()

試試看輸入這些需求：

• 「我想做一個每日有 10 萬用戶的電商網站」
• 「我需要一個即時資料分析的 pipeline，資料來自 IoT 設備」
• 「幫我設計一個內部用的文件搜尋系統，有 10 萬份 PDF」

重點整理

這堂課我們完成了六個關鍵實作：

關鍵觀念

• 模型選擇：大多數場景用 gemini-2.5-flash，需要最強推理才用 gemini-2.5-pro
• SDK 選擇：新專案一律使用 google-genai，不要用舊版 SDK
• 成本控制：注意 token 用量，善用 max_output_tokens 限制輸出長度
• 安全性：不要在程式碼中硬寫認證資訊，使用 gcloud auth application-default login

下一步

在下一課中，我們將深入探討 Prompt Engineering 的進階技巧——包含 few-shot prompting、chain-of-thought 推理、以及如何用結構化輸出（JSON mode）建構更可靠的 AI 應用。