使用 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 代理（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 控制台中，依次前往菜单 > IAM 和管理 > 创建项目。

   前往“创建项目”

2. 在 Project Name 字段中，输入项目的描述性名称。

   可选：如需修改项目 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。

为 Cloud 项目启用结算功能

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

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. 确认您要在正确的 Cloud 项目中启用 Vertex AI API，然后点击下一步。

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

gcloud CLI

1. 如有必要，请将当前 Cloud 项目设置为您使用 gcloud config set project 命令创建的项目：

   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 和管理 > 服务账号。

   转到“服务账号”

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 和管理 > 服务账号。

   转到“服务账号”

2. 选择您的服务账号。
3. 依次点击密钥 > 添加密钥 > 创建新密钥。
4. 选择 JSON，然后点击创建。

   系统会生成新的公钥/私钥对，并以新文件的形式下载到您的计算机。将下载的 JSON 文件以 credentials.json 的名称保存到工作目录中。此文件是相应密钥的唯一副本。如需了解如何安全地存储密钥，请参阅管理服务账号密钥。

5. 点击关闭。

如需详细了解服务账号，请参阅 Google Cloud IAM 文档中的服务账号。

部署 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 替换为您创建的 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，稍后您需要使用该 ID 来配置自定义函数。

   python3 deployment/deploy.py --list

查看示例代码

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

在 GitHub 上查看

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

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

   复制 Google 表格

2. 在新创建的电子表格中，依次前往扩展程序 > Apps 脚本。

3. 在 Apps 脚本项目中，前往项目设置，点击修改脚本属性，然后点击添加脚本属性以添加以下脚本属性：

   1. 将 LOCATION 替换为在之前的步骤中创建的 Google Cloud 项目的位置，例如 us-central1。
   2. 将 GEMINI_MODEL_ID 替换为您要使用的 Gemini 模型，例如 gemini-2.5-flash-lite。
   3. 将 REASONING_ENGINE_ID 替换为在之前的步骤中部署的 LLM 审核员 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 和管理 > 管理资源。

   前往资源管理器

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

后续步骤

• Google 表格中的自定义函数
• 扩展 Google 表格