使用 ADK AI 代理程式和 Gemini 模型查證陳述內容

程式碼程度：進階
所需時間：30 分鐘
專案類型：自訂函式

總覽

Google 試算表的查證自訂函式，可做為由 Vertex AI 代理程式和 Gemini 模型支援的繫結 Apps Script 專案。

這個範例說明如何直接在 Google 試算表中使用兩種強大的 AI 資源：

  1. AI 代理 使用部署在 Vertex AI 代理引擎中的 ADK 代理，實現複雜的多工具、多步驟推理能力。
  2. AI 模型 使用 Vertex AI 的 Gemini 模型實現高階理解、生成和摘要功能。

事實查核 Google 試算表自訂函式的使用範例

目標

  • 瞭解解決方案的功能。
  • 瞭解解決方案的實作方式。
  • 部署 Vertex AI 代理。
  • 設定指令碼。
  • 執行指令碼。

認識這項解決方案

Sheets 自訂函數名為 FACT_CHECK，它作為端對端解決方案運行。這項功能會分析陳述內容、根據最新的網路資訊提供回應，並以您需要的格式傳回結果：

  • 用法：
    • =FACT_CHECK("Your statement here")，以取得簡潔的摘要輸出內容。
    • =FACT_CHECK("Your statement here", "Your output formatting instructions here")，以取得特定輸出格式的資料。
  • 原因：LLM Auditor ADK AI 代理程式 (Python 範例)。
  • 輸出格式：Gemini 模型。

此解決方案使用 UrlFetchApp 請求 Vertex AI REST API。

架構

下圖展示了自訂函數所使用的 Google Workspace 和 Google Cloud 資源的架構。

Google Sheets 自訂函數事實查核功能的架構圖

必要條件

要使用此範例，您需要滿足以下先決條件：

  • Google 帳戶（Google Workspace 帳戶可能需要管理員批准）。

  • 可連接網際網路的網路瀏覽器。

  • LLM 審計師 ADK 代理的先決條件

    • Python 3.11+：要進行安裝，請按照官方 Python 網站 上的說明進行操作。
    • Python Poetry：要進行安裝，請按照官方 Poetry 網站 上的說明進行操作。
    • Google Cloud CLI：如要安裝，請按照官方 Google Cloud 網站上的指示操作。

準備環境

本節說明如何建立及設定 Google Cloud 專案。

建立一個 Google Cloud 項目

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往「選單」。 > 身分與存取管理 > 創建專案。

    前往「建立專案」

  2. 在項目名稱請在此輸入項目的描述性名稱。

    選用：若要編輯 項目 ID，請點選 編輯。專案 ID 無法在專案建立後更改，因此請選擇一個能夠滿足專案整個生命週期需求的 ID。

  3. 在 位置 欄位中，按一下 瀏覽 以顯示項目的潛在位置。然後，按一下 選擇。
  4. 按一下「建立」，Google Cloud 控制台會跳到資訊中心頁面，您的專案將在幾分鐘內建立完成。

gcloud CLI

在以下開發環境之一中，造訪 Google Cloud CLI (gcloud):

  • Cloud Shell: 若要使用已設定好 gcloud CLI 的線上終端，請啟動 Cloud Shell。
    啟動雲 Shell
  • 本機 Shell: 若要使用本機開發環境，請安裝並初始化 gcloud CLI。
    若要建立雲端項目，請使用 gcloud projects create 指令： 
    gcloud projects create PROJECT_ID
     將 PROJECT_ID 替換為要建立的專案 ID。

啟用雲端項目的計費功能

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往 結算。點選選單 > 帳單 > 我的項目。

    前往我的專案結算頁面

  2. 在「選取機構」中，選擇與 Google Cloud 專案相關聯的機構。
  3. 在專案列中開啟「動作」選單 ()，按一下「變更帳單」，然後選擇 Cloud 帳單帳戶。
  4. 按一下 [設定帳戶]。

gcloud CLI

  1. 如要列出可用的帳單帳戶，請執行： 
    gcloud billing accounts list
  2. 將帳單帳戶連結至 Google Cloud 專案： 
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

    更改下列內容：

    • PROJECT_ID 是您要啟用計費的雲端項目的 項目 ID。
    • BILLING_ACCOUNT_ID 是要與 Google Cloud 項目關聯的 結算帳號 ID。

啟用 Vertex AI API

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，啟用 Vertex AI API。

    啟用 API

  2. 確認您正在正確的雲端專案中啟用 Vertex AI API，然後按一下 下一步。

  3. 請確認您啟用的是正確的 API，然後按一下 啟用。

gcloud CLI

  1. 如有必要，請將目前雲端項目設定為您使用 gcloud config set project 指令建立的項目：

    gcloud config set project PROJECT_ID

    將 PROJECT_ID 替換為您建立的雲端項目的 項目 ID。

  2. 使用 gcloud services enable 指令啟用 Vertex AI API：

    gcloud services enable aiplatform.googleapis.com

在 Google Cloud 控制台中建立服務帳戶

請依照下列步驟建立具有 Vertex AI User 角色的新服務帳戶：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，依序前往「選單」圖示 >「IAM 與管理」 >「服務帳戶」。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 按一下「建立服務帳戶」。
  3. 填寫服務帳戶詳細信息，然後點擊建立並繼續。
  4. （可選）為您的服務帳號指派角色，以授予對 Google Cloud 專案資源的存取權限。詳情請參閱「授予、變更及撤銷資源的存取權」。
  5. 按一下「繼續」。
  6. （可選）輸入可以管理此服務帳戶並使用該帳戶執行操作的使用者或群組。詳情請參閱「管理服務帳戶模擬功能」。
  7. 按一下「完成」，記下服務帳戶的電子郵件地址。

gcloud CLI

  1. 建立服務帳戶： 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. （可選）為您的服務帳號指派角色，以授予對 Google Cloud 專案資源的存取權限。詳情請參閱「授予、變更及撤銷資源的存取權」。

服務帳號會顯示在服務帳號頁面。接下來，為服務帳戶建立私鑰。

建立私密金鑰

如要建立及下載服務帳戶的私密金鑰，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往「選單」。 > 身分與存取管理 > 服務帳戶。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 選取服務帳戶。
  3. 依序點選「金鑰」>「新增金鑰」>「建立新的金鑰」。
  4. 選取「JSON」，然後按一下「建立」。

    接著，系統就會為您產生一對新的公開/私密金鑰，並以新檔案的形式下載至您的電腦中。將下載的 JSON 檔案儲存為工作目錄中的 credentials.json。這個檔案是這組金鑰的唯一副本，如要瞭解如何安全儲存金鑰，請參閱「管理服務帳戶金鑰」一文。

  5. 點選「關閉」。

有關服務帳號的更多信息，請參閱 Google Cloud IAM 文件中的 service accounts。

部署 LLM 審計員 ADK AI 代理

  1. 如果尚未完成，請使用您的 Google Cloud 帳戶進行驗證，並設定 Google Cloud CLI 以使用您的 Google Cloud 專案。

    gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID

    將 PROJECT_ID 替換為您建立的 Cloud 專案 ID。

  2. 下載這個 GitHub 存放區

    下載

  3. 在您首選的本機開發環境中，解壓縮下載的存檔檔案並開啟 adk-samples/python/agents/llm-auditor 目錄。

    unzip adk-samples-main.zip
cd adk-samples-main/python/agents/llm-auditor

  4. 建立一個專門用於 ADK 代理程式的新 Cloud Storage 儲存桶。

    gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

    更改下列內容：

    1. CLOUD_STORAGE_BUCKET_NAME 使用您想要使用的唯一儲存桶名稱。
    2. 將 PROJECT_ID 替換為您建立的 Cloud 專案 ID。
    3. PROJECT_LOCATION 包含您建立的雲端項目的位置。

  5. 請設定下列環境變數：

    export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

    更改下列內容：

    1. CLOUD_STORAGE_BUCKET_NAME 為您建立的儲存桶的名稱。
    2. PROJECT_ID 包含您建立的雲端項目的 ID。
    3. PROJECT_LOCATION 包含您建立的雲端項目的位置。

  6. 從虛擬環境安裝並部署 ADK 代理程式。

    python3 -m venv myenv
source myenv/bin/activate
poetry install --with deployment
python3 deployment/deploy.py --create

  7. 取得代理 ID，稍後需要用它來配置自訂功能。

    python3 deployment/deploy.py --list

查看程式碼範例

(選用) 建立新試算表前，請先花點時間查看並熟悉 GitHub 上託管的範例程式碼。

在 GitHub 上查看

在新試算表中建立及設定

  1. 點擊以下按鈕，完整複製範例 Google Sheets 電子表格及其容器綁定的 Apps Script 專案。

    複製 Google 試算表

  2. 在新建的電子表格中，前往 Extensions > Apps Script。

  3. 在 Apps Script 專案中，前往「專案設定」，按一下「編輯指令碼屬性」，然後按一下「新增指令碼屬性」，新增下列指令碼屬性：

    1. LOCATION 以及在前面的步驟中建立的 Google Cloud 專案的位置，例如 us-central1。
    2. GEMINI_MODEL_ID 與您想要使用的 Gemini 型號，例如 gemini-2.5-flash-lite。
    3. REASONING_ENGINE_ID，例如 1234567890，這是先前步驟中部署的 LLM Auditor ADK 代理程式 ID。
    4. SERVICE_ACCOUNT_KEY，其中 { ... } 是您在先前步驟中下載的服務帳戶 JSON 金鑰。

  4. 點選儲存腳本屬性

測試自訂函式

  1. 開啟新建立的電子表格。
  2. 變更A 欄中的陳述句。
  3. 列 B 中的公式執行後會顯示事實查核結果。

清除所用資源

為避免因本教學中使用的資源而產生 Google Cloud 帳戶費用，我們建議您刪除 Cloud 專案。

  1. 在 Google Cloud 控制台中，前往 管理資源 頁面。依序點選「選單」「IAM 與管理」>「管理資源」>。

    前往 Resource Manager

  2. 在項目清單中，選擇要刪除的項目，然後按一下 刪除 。
  3. 在對話方塊中，輸入項目 ID，然後按一下 關閉 刪除項目。

後續步驟