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

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

總覽

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

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

1. AI 代理：使用在 Vertex AI Agent Engine 中部署的 ADK 代理，提供精密的多工具、多步驟推理功能。
2. AI 模型：使用 Vertex AI 的 Gemini 模型，進行進階解讀、生成和摘要。

目標

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

認識這項解決方案

Google 試算表自訂函式名為 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 帳戶 (Google Workspace 帳戶可能需要管理員核准)。

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

• LLM Auditor ADK 代理程式的必要條件

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

準備環境

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

建立 Google Cloud 專案

Google Cloud 控制台

1. 前往 Google Cloud 控制台，依序點選「選單」圖示 >「IAM 與管理」 >「建立專案」。

   前往「建立專案」

2. 在「Project Name」(專案名稱) 欄位中，輸入專案的描述性名稱。

   選用：如要編輯「專案 ID」，請按一下「編輯」。專案建立後就無法變更專案 ID，因此請選用符合專案執行期間需求的 ID。

3. 在「Location」(位置) 欄位中，按一下「Browse」(瀏覽)，即可顯示專案的可能位置。然後按一下「選取」。
   注意：找不到 Google Workspace 機構嗎？
   這表示你未登入 Google Workspace 帳戶。Google Workspace 開發人員文件所述的部分功能，僅適用於與機構相關聯的專案。
4. 按一下「建立」，Google Cloud 控制台會前往「資訊主頁」頁面，並在幾分鐘內建立專案。

gcloud CLI

在下列任一開發環境中，存取 Google Cloud CLI (gcloud)：

• Cloud Shell：如要使用已設定 gcloud CLI 的線上終端機，請啟用 Cloud Shell。
  啟用 Cloud Shell
• 本機殼層：如要使用本機開發環境，請安裝並初始化 gcloud CLI。
  如要建立 Cloud 專案，請使用 gcloud projects create 指令：

  gcloud projects create PROJECT_ID

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

啟用 Cloud 專案的計費功能

如果無法連結帳單帳戶，表示您沒有進行這項變更所需的權限。詳情請參閱「啟用帳單功能所需的權限」。

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 是要啟用計費功能的 Cloud 專案的專案 ID。
   • BILLING_ACCOUNT_ID 是要連結至 Google Cloud 專案的帳單帳戶 ID。

啟用 Vertex AI API

Google Cloud 控制台

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

   啟用 API

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

3. 確認要啟用的 API 正確無誤，然後按一下「啟用」。

gcloud CLI

1. 如有必要，請使用 gcloud config set project 指令，將目前的 Cloud 專案設為您建立的專案：

   gcloud config set project PROJECT_ID

   將 PROJECT_ID 替換為您建立的 Cloud 專案的專案 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. 填寫服務帳戶詳細資料，然後按一下「建立並繼續」。
   注意：根據預設，Google 會建立專屬服務帳戶 ID。如要變更 ID，請修改服務帳戶 ID 欄位中的 ID。
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 控制台中，依序前往「選單」圖示 >「IAM 與管理」 >「服務帳戶」。

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

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

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

5. 點選「關閉」。

如要進一步瞭解服務帳戶，請參閱 Google Cloud IAM 說明文件中的服務帳戶。

部署 LLM Auditor 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 bucket。

   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，並填入您建立的 Cloud 專案位置。

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 替換為您建立的 Cloud 專案 ID。
   3. PROJECT_LOCATION，並填入您建立的 Cloud 專案位置。

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 試算表，包括其繫結的 Apps Script 專案。

   複製 Google 試算表

2. 在新建立的試算表中，依序前往「擴充功能」>「Apps Script」。

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

   1. LOCATION，其中包含先前步驟中建立的 Google Cloud 專案位置，例如 us-central1。
   2. GEMINI_MODEL_ID，例如 gemini-2.5-flash-lite。
   3. REASONING_ENGINE_ID，並替換為先前步驟中部署的 LLM Auditor ADK 代理程式 ID，例如 1234567890。
   4. SERVICE_ACCOUNT_KEY，其中 { ... } 是您在先前步驟中下載的服務帳戶 JSON 金鑰。

4. 按一下「儲存指令碼屬性」

測試自訂函式

1. 前往新建立的試算表。
2. 變更A 欄中的陳述句。
3. B 欄中的公式會執行，然後顯示事實查核結果。

清除所用資源

為避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，建議您刪除 Cloud 專案。

警告：刪除專案會出現以下結果：

• 專案中的所有內容都會遭到刪除。 如果您之前使用現有的專案來進行本教學課程，當您刪除該專案時，也會一併刪除您在該專案中完成的所有其他工作。
• 自訂專案 ID 不復存在。您建立這個專案時，可能已建立日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (如 appspot.com 上的網址)，請在專案中刪除選定的資源，不要刪除整個專案。

如果打算進行多個教學課程及快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

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

   前往 Resource Manager

2. 在專案清單中選取要刪除的專案，然後按一下「刪除」圖示 。
3. 在對話方塊中輸入專案 ID，然後按一下「Shut down」(關閉) 即可刪除專案。

後續步驟

• Google 試算表的自訂函式
• 擴充 Google 試算表功能