GSP1209

總覽

Google Gen AI SDK 提供統一的介面，方便您使用 Google 生成式 AI 的各項 API 服務。這個 SDK 簡化了整合程序，使生成式 AI 功能可輕鬆與應用程式和服務搭配運用，方便開發人員透過 Google 先進的 AI 模型處理各種工作。本實驗室將帶您探索 Google Gen AI SDK，瞭解如何連結 AI 服務、傳送各種提示，以及微調 Gemini 的回覆。不僅如此，您還可以實際練習一些進階技巧，做好充分準備，以便在自己的專案上運用生成式 AI 的強大功能。

目標

在本實驗室中，您將瞭解如何透過 Google Gen AI SDK for Python 與 Google 的生成式 AI 服務和模型 (包括 Gemini) 互動。學習重點如下：

• 安裝 Gen AI SDK。
• 連結 API 服務。
• 傳送文字和多模態提示。
• 設定系統指示。
• 設定模型參數和安全篩選機制。
• 管理模型互動 (多輪對話、內容串流、非同步要求)。
• 使用進階功能 (詞元數計算、脈絡快取、函式呼叫、批次預測、文字嵌入)。

事前準備

開始這個實驗室之前，您應已熟悉下列概念：

• 基本 Python 程式設計。
• 一般 API 概念。
• 在 Vertex AI Workbench 使用 Jupyter 筆記本執行 Python 程式碼。

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

工作 1：開啟 Vertex AI Workbench 中的筆記本

1. 前往 Google Cloud 控制台，依序點按「導覽選單」圖示 >「Vertex AI」>「Workbench」。

2. 找出 執行個體，點按「Open JupyterLab」按鈕。

Workbench 執行個體的 JupyterLab 介面會在新瀏覽器分頁中開啟。

工作 2：設定筆記本

開啟筆記本檔案、匯入程式庫，然後選擇模型。

1. 開啟 檔案。

2. 出現「Select Kernel」對話方塊時，從可用核心清單中選取「Python 3」。

3. 執行筆記本的下列部分：

   • 開始使用
   • 使用 Google Gen AI SDK
   • 連結生成式 AI API 服務

「專案 ID」請使用 ，「位置」則使用 。

注意：請略過所有標有「僅限 Colab」的筆記本儲存格。如果執行筆記本儲存格後出現 429 回應，稍候 1 分鐘再重新執行儲存格，應該就能繼續操作。

點選「Check my progress」，確認目標已達成。 匯入程式庫及設定筆記本

工作 3：與模型互動

如要進一步瞭解 Vertex AI 中所有的 AI 模型和 API，請參閱 Google 模型和 Model Garden 的相關說明文件。

選擇模型

• 執行筆記本的「選擇模型」部分。

傳送文字提示

使用 generate_content 方法，生成提示的回覆。您可以將文字傳給 generate_content，並透過 .text 屬性取得回覆的文字內容。

• 執行筆記本的「傳送文字提示」部分。

傳送多模態提示

您可以在提示要求中加入文字、PDF 文件、圖像、音訊和影片，並取得文字或程式碼形式的回覆。

您也可以直接在要求中使用 Part.from_uri，將檔案網址直接傳給模型。

• 執行筆記本的「傳送多模態提示」(Send multimodal prompts) 部分。

設定系統指示

系統指示可用來控制模型的行為。您可以設定系統指示，提供額外的脈絡資訊，讓模型瞭解任務內容、提供更符合需求的回覆，並在與使用者互動時遵守特定指引。

• 執行筆記本的「設定系統指示」部分。

點選「Check my progress」，確認目標已達成。 與模型互動

工作 4：設定及控制模型

設定模型參數

您可以將參數值加入要傳送至模型的每個呼叫，藉以控制模型生成回覆的方式。詳情請參閱「測試不同參數值」一文。

• 執行筆記本的「設定模型參數」部分。

設定安全篩選機制

Gemini API 提供安全篩選機制，您可加以調整，藉此限制或允許特定類型的內容。您可以運用這些篩選機制，根據使用情境將模型調整為適當的狀態。詳情請參閱「設定安全篩選機制」的說明頁面。

向模型提出要求後，系統會分析內容並給予安全評分。您可以使用 print 指令顯示模型回覆，查看生成內容的安全評分，如下方範例所示：

• 執行筆記本的「設定安全篩選機制」部分。

開始多輪對話

透過 Gemini API，您就能與模型展開任意形式的多輪對話。

• 執行筆記本的「開始多輪對話」部分。

控制生成的輸出內容

Gemini API 的「控制生成」功能可讓您設下限制，規定模型採用結構化格式輸出內容。您可以提供 Pydantic 模型或 JSON 字串做為結構定義。

您也可以在 Python 字典中界定回覆結構定義，但只能使用以下欄位，系統會忽略其他欄位。

• enum
• items
• maxItems
• nullable
• properties
• required

在以下示例中，您指示模型分析產品評論資料、擷取重要實體、進行情緒分類 (從多個選項中擇一)、提供額外說明，並以 JSON 格式輸出結果。

• 執行筆記本的「控制生成的輸出內容」部分。

點選「Check my progress」，確認目標已達成。 設定及控制模型

工作 5：管理模型互動

生成內容串流

根據預設，整個生成程序完成後，模型才會傳回回覆。您也可以使用 generate_content_stream 方法，在回覆生成的同時串流回覆內容。模型在回覆的一部分生成完畢後，就會傳回該部分。

• 執行筆記本的「生成內容串流」部分。

傳送非同步要求

您可以使用 client.aio 模組傳送非同步要求。這個模組比照 client 中的所有方法提供類似的非同步版本。

舉例來說，client.aio.models.generate_content 是 client.models.generate_content 的非同步版本。

• 執行筆記本的「傳送非同步要求」部分。

計算詞元數和運算詞元

您可以使用 count_tokens 方法計算輸入詞元數，再將要求傳送至 Gemini API。詳情請參閱「列出和計算詞元數」頁面。

計算詞元數

• 執行筆記本的「計算詞元數」部分。

運算詞元

• 執行筆記本的「運算詞元」部分。

點選「Check my progress」，確認目標已達成。 管理模型互動

工作 6：進階功能

函式呼叫

您可以透過「函式呼叫」功能提供一組工具，讓模型在回應使用者提示時使用。只要在程式碼中撰寫函式說明，然後透過要求傳送給語言模型，模型的回覆就會包含符合說明的函式名稱，以及呼叫該函式所需的引數。

如要查看更多函式呼叫範例，請參閱這個筆記本。

• 執行筆記本的「函式呼叫」部分。

點選「Check my progress」，確認目標已達成。 函式呼叫

使用脈絡快取功能

您可以透過「脈絡快取」功能，將常用的輸入詞元儲存在專屬快取中，並在後續要求中參照這些詞元，這樣就不必反覆將同一組詞元傳至模型。

注意：脈絡快取功能僅適用於有修正版本的穩定模型 (例如 gemini-2.0-flash-001)。指定模型時，必須加上版本後置字串 (例如 -001)，才能確保功能正常運作。

建立快取

• 執行筆記本的「建立快取」部分。

使用快取

• 執行筆記本的「使用快取」部分。

刪除快取

• 執行筆記本的「刪除快取」部分。

點選「Check my progress」，確認目標已達成。 使用脈絡快取功能

批次預測

取得線上 (同步) 回覆與在 Vertex AI 使用 Gemini API 執行批次預測並不相同，前者一次只能發出一項輸入要求，後者則可讓您一次傳送大量要求給 Gemini，然後系統會以非同步方式，將模型回覆填入 Cloud Storage 或 BigQuery 的輸出內容儲存位置。

需要處理大量輸入內容，但不一定要立即得到回覆時，建議採用批次預測，因為這個做法的效率和成本效益通常比線上預測高。

為批次輸入做好準備

提交批次要求時，應在輸入內容中指定要送交模型預測的項目。

對 Gemini 提出批次要求時，適用的輸入來源包括 BigQuery 儲存空間和 Cloud Storage。如要進一步瞭解批次輸入格式，請前往「批次文字生成」的說明頁面。

本實驗室以 Cloud Storage 為例，輸入規定如下：

• 檔案格式：JSON Lines (JSONL)
• 位置：us-central1
• 服務帳戶的適當讀取權限

某些參數可用來控制模型生成回覆的方式，您在傳送要求給模型時，可以加入這類參數。如要進一步瞭解 Gemini 參數，請參閱「測試不同參數值」頁面。

以下是 JSONL 輸入檔案 batch_requests_for_multimodal_input_2.jsonl 中的一個要求範例：

{"request":{"contents": [{"role": "user", "parts": [{"text": "List objects in this image."}, {"file_data": {"file_uri": "gs://cloud-samples-data/generative-ai/image/office-desk.jpeg", "mime_type": "image/jpeg"}}]}],"generationConfig":{"temperature": 0.4}}}

• 執行筆記本的「為批次輸入做好準備」部分。

準備批次輸出位置

批次預測工作完成後，系統會根據您的要求，將輸出內容儲存在指定的位置。

• 位置的格式必須採用 Cloud Storage 或 BigQuery 的 URI 前置字串，例如：gs://path/to/output/data 或 bq://projectId.bqDatasetId。

• 如未指定，系統就會以 gs://STAGING_BUCKET/gen-ai-batch-prediction 做為 Cloud Storage 輸出位置，至於 BigQuery 輸出位置，則會使用 bq://PROJECT_ID.gen_ai_batch_prediction.predictions_TIMESTAMP。

本實驗室以 Cloud Storage bucket 做為輸出位置的範例。

您可以在 BUCKET_URI 中指定 Cloud Storage bucket 的 URI。如未指定，系統會為您建立新的 Cloud Storage bucket，格式為 gs://PROJECT_ID-TIMESTAMP。

• 執行筆記本的「準備批次輸出位置」部分。

傳送批次預測要求

如要提出批次預測要求，須指定來源模型 ID、輸入來源，以及 Vertex AI 用來儲存批次預測結果的輸出位置。

詳情請參閱「批次預測 API」頁面。您也可以前往控制台查看狀態，網址為：https://console.cloud.google.com/vertex-ai/batch-predictions。

• 執行筆記本的「傳送批次預測要求」部分。

注意：批次預測作業可能需要幾分鐘才能完成。

擷取批次預測結果

批次預測工作完成後，系統會根據您的要求，將預測結果儲存在指定的位置。此外，預測結果也會儲存於 batch_job.dest.bigquery_uri 或 batch_job.dest.gcs_uri。

輸出內容範例：

{"status": "", "processed_time": "2024-11-13T14:04:28.376+00:00", "request": {"contents": [{"parts": [{"file_data": null, "text": "List objects in this image."}, {"file_data": {"file_uri": "gs://cloud-samples-data/generative-ai/image/gardening-tools.jpeg", "mime_type": "image/jpeg"}, "text": null}], "role": "user"}], "generationConfig": {"temperature": 0.4}}, "response": {"candidates": [{"avgLogprobs": -0.10394711927934126, "content": {"parts": [{"text": "Here's a list of the objects in the image:\n\n* **Watering can:** A green plastic watering can with a white rose head.\n* **Plant:** A small plant (possibly oregano) in a terracotta pot.\n* **Terracotta pots:** Two terracotta pots, one containing the plant and another empty, stacked on top of each other.\n* **Gardening gloves:** A pair of striped gardening gloves.\n* **Gardening tools:** A small trowel and a hand cultivator (hoe). Both are green with black handles."}], "role": "model"}, "finishReason": "STOP"}], "modelVersion": "gemini-2.0-flash-001@default", "usageMetadata": {"candidatesTokenCount": 110, "promptTokenCount": 264, "totalTokenCount": 374}}}

• 執行筆記本的「擷取批次預測結果」部分。

點選「Check my progress」，確認目標已達成。 擷取批次預測結果

取得文字嵌入

您可以使用 embed_content 方法，取得某段文字的文字嵌入。所有模型預設都會生成包含 768 個維度的輸出內容。不過，有些模型能讓使用者選擇輸出的維度，範圍介於 1 到 768 之間。詳情請參閱「Vertex AI 文字嵌入 API」的相關說明。

• 執行筆記本的「取得文字嵌入」部分。

點選「Check my progress」，確認目標已達成。 取得文字嵌入

恭喜！

太棒了！您已順利完成 Google Gen AI SDK 探索之旅，瞭解如何連結 AI 服務、傳送各種提示，以及微調 Gemini 模型的回覆，還實際練習了一些進階技巧，例如管理互動、使用脈絡快取，甚至使用嵌入功能！您現在已掌握相關技能，可在自己的專案上運用生成式 AI 的強大功能。

後續行動/瞭解詳情

歡迎參考下列資源，進一步瞭解 Gemini：

• Gemini 簡介
• Vertex AI 生成式 AI 說明文件
• 透過 YouTube 瞭解生成式 AI
• 探索 Vertex AI 教戰手冊，瀏覽及搜尋眾多精心挑選的生成式 AI 筆記本。
• 前往 Google Cloud 生成式 AI 存放區，查看其他筆記本和範例。

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2025 年 5 月 5 日

實驗室上次測試日期：2025 年 5 月 5 日

Copyright 2025 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。