使用 ADK AI 代理和 Gemini 模型对陈述进行事实核查

编码级别： 先进的
期间30 分钟
项目类型：自定义功能

概览

一个用于 Google 表格的事实核查自定义函数，可作为由 Vertex AI 代理和 Gemini 模型提供支持的绑定 Apps 脚本项目使用。

此示例演示了如何直接在 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 Agent（Python 示例）。
• 输出格式：Gemini 模型。

此解决方案使用 UrlFetchApp 请求 Vertex AI REST API。

架构

下图展示了自定义函数使用的 Google Workspace 和 Google Cloud 资源的架构。

前提条件

如需使用此示例，您需要满足以下前提条件：

• 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. 在 位置 字段中，单击 浏览 以显示项目的潜在位置。然后，单击 选择。
   注意：找不到您的 Google Workspace 组织？
   这意味着您尚未登录 Google Workspace 账号。Google Workspace 开发者文档中描述的部分功能仅适用于与组织关联的项目。
4. 点击创建。Google Cloud 控制台会转到“信息中心”页面，您的项目会在几分钟内创建完毕。

gcloud CLI

在以下任一开发环境中，访问 Google Cloud CLI (gcloud)：

• Cloud Shell: 要使用已设置好 gcloud CLI 的在线终端，请激活 Cloud Shell。
  激活 Cloud Shell
• 本地 Shell: 要使用本地开发环境，请安装并初始化 gcloud CLI。
  如需创建 Cloud 项目，请使用 gcloud projects create 命令：

  gcloud projects create PROJECT_ID

  通过设置要创建的项目的 ID 来替换 PROJECT_ID。

启用云项目的计费功能

如果您无法关联结算账号，则表示您没有进行此更改所需的权限。如需了解详情，请参阅启用结算所需的权限。

Google Cloud 控制台

1. 在 Google Cloud 控制台中，前往结算。点击菜单 > 账单 > 我的项目。

   前往我的项目结算页面

2. 在选择组织中，选择与您的 Google Cloud 项目关联的组织。
3. 在项目行中，打开操作菜单 ()，点击更改结算信息，然后选择 Cloud Billing 账号。
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. 确认您正在正确的云项目中启用 Vertex AI API，然后单击 下一步。

3. 确认您要启用的 API 正确无误，然后点击启用。

gcloud CLI

1. 如有必要，请将当前 Cloud 项目设置为您使用 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 和管理 > 服务账号。

   转到“服务账号”

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 控制台中，转到“菜单”。 > 身份与访问管理 > 服务账号。

   转到“服务账号”

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 存储分区。

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

   替换以下内容：

   1. CLOUD_STORAGE_BUCKET_NAME 使用您想要使用的唯一存储分区名称。
   2. PROJECT_ID 包含您创建的云项目的 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，您稍后需要使用该 ID 来配置自定义函数。

   python3 deployment/deploy.py --list

请查看示例代码

（可选）在创建新电子表格之前，请花点时间查看并熟悉 GitHub 上托管的示例代码。

在 GitHub 上查看

在新电子表格中创建和配置

1. 点击以下按钮，完整复制示例 Google 表格，包括其容器绑定的 Apps 脚本项目。

   复制 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 包含先前步骤中部署的 LLM Auditor ADK Agent 的 ID，例如 1234567890。
   4. SERVICE_ACCOUNT_KEY 替换为在之前的步骤中下载的服务账号的 JSON 密钥，例如 { ... }。

4. 点击保存脚本属性

测试自定义函数

1. 打开新创建的电子表格。
2. 更改列 A 中的陈述。
3. B 列中的公式会执行，然后显示事实核查结果。

清理

为避免系统因本教程中使用的资源向您的 Google Cloud 账号收取费用，我们建议您删除 Cloud 项目。

警告：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您在本教程使用现有项目，则删除该项目后，还将删除您已在该项目中完成的其他所有工作。
• 自定义项目 ID 会丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。如需保留使用该项目 ID 的网址（例如 appspot.com 上的网址），请删除项目内的所选资源，而不是删除整个项目。

如果您计划探索多个教程和快速入门指南，重复使用项目可以帮助您避免超出项目配额限制。

1. 在 Google Cloud 控制台中，转到 管理资源 页面。点击菜单 > 身份与访问管理 > 管理资源。

   转到资源管理器

2. 在项目列表中，选择要删除的项目，然后单击 删除 。
3. 在对话框中输入项目 ID，然后点击关停以删除项目。

后续步骤

• 借助 Google Workspace 中提供的 AI 代理规划行程
• Google 表格中的自定义函数
• 扩展 Google 表格