Проверка фактов с помощью агента ADK AI и модели Gemini

Уровень кодирования : продвинутый
Продолжительность : 30 минут
Тип проекта : Пользовательская функция

Обзор

Пользовательская функция проверки фактов для Google Таблиц, которая будет использоваться в качестве связанного проекта Apps Script на основе агента Vertex AI и модели Gemini.

В этом примере показано, как можно использовать два мощных типа ресурсов ИИ непосредственно в таблицах Google Sheets:

1. Агенты ИИ для сложных, многоинструментальных, многошаговых возможностей рассуждения с использованием агентов ADK, развернутых в Vertex AI Agent Engine.
2. Модели ИИ для расширенного понимания, генеративных и резюмирующих возможностей с использованием моделей Gemini от Vertex AI.

Цели

• Поймите, что делает решение.
• Понять, как реализуется решение.
• Разверните агента Vertex AI.
• Настройте сценарий.
• Запустите скрипт.

Об этом решении

Пользовательская функция Таблиц называется FACT_CHECK и представляет собой комплексное решение. Она анализирует выписку, обосновывает свой ответ, используя актуальную информацию из интернета, и возвращает результат в нужном вам формате:

• Использование:
  • =FACT_CHECK("Your statement here") для краткого и обобщенного вывода.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") для определенного формата вывода.
• Рассуждение: LLM Auditor ADK AI Agent (пример Python) .
• Форматирование вывода: модель Gemini .

Это решение запрашивает API Vertex AI REST с помощью UrlFetchApp .

Архитектура

На следующей диаграмме показана архитектура ресурсов 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. В поле «Название проекта» введите описательное название вашего проекта.

   Необязательно: чтобы изменить идентификатор проекта , нажмите «Изменить» . Идентификатор проекта нельзя изменить после его создания, поэтому выберите идентификатор, который будет соответствовать вашим потребностям на протяжении всего жизненного цикла проекта.

3. В поле «Местоположение» нажмите «Обзор» , чтобы отобразить возможные местоположения для вашего проекта. Затем нажмите « Выбрать» .
   Внимание: не можете найти свою организацию Google Workspace?
   Это означает, что вы не вошли в аккаунт Google Workspace. Некоторые функции, описанные в документации для разработчиков Google Workspace, доступны только для проектов, связанных с организацией.
4. Нажмите «Создать» . Консоль Google Cloud перейдет на страницу панели управления, и ваш проект будет создан в течение нескольких минут.

gcloud CLI

В одной из следующих сред разработки получите доступ к Google Cloud CLI ( gcloud ):

• Cloud Shell : чтобы использовать онлайн-терминал с уже настроенным интерфейсом командной строки gcloud, активируйте Cloud Shell.
  Активировать Cloud Shell
• Локальная оболочка : чтобы использовать локальную среду разработки, установите и инициализируйте gcloud CLI.
  Чтобы создать облачный проект, используйте команду gcloud projects create :

  gcloud projects create PROJECT_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 — это идентификатор облачного проекта, для которого вы хотите включить выставление счетов.
   • BILLING_ACCOUNT_ID — идентификатор платежного аккаунта для связи с проектом Google Cloud.

Включить API Vertex AI

Консоль Google Cloud

1. В консоли Google Cloud включите API Vertex AI.

   Включить API

2. Подтвердите, что вы включаете API Vertex AI в правильном облачном проекте, затем нажмите Далее .

3. Подтвердите, что вы включаете правильный API, затем нажмите Включить .

gcloud CLI

1. При необходимости установите текущий проект Cloud на тот, который вы создали с помощью команды gcloud config set project :

   gcloud config set project PROJECT_ID

   Замените PROJECT_ID на идентификатор созданного вами облачного проекта.

2. Включите API Vertex AI с помощью команды gcloud services enable :

   gcloud services enable aiplatform.googleapis.com

Создайте учетную запись службы в консоли Google Cloud

Создайте новую учетную запись службы с ролью Vertex AI User выполнив следующие действия:

Консоль Google Cloud

1. В консоли Google Cloud перейдите в > IAM и администрирование > Учетные записи служб .

   Перейти к учетным записям служб

2. Нажмите Создать учетную запись службы .
3. Заполните данные учетной записи службы, затем нажмите «Создать» и продолжите .
   Примечание: По умолчанию Google создаёт уникальный идентификатор учётной записи сервиса. Если вы хотите изменить идентификатор, укажите его в поле «Идентификатор учётной записи сервиса».
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 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 на идентификатор созданного вами облачного проекта.

2. Загрузите этот репозиторий GitHub

   Скачать

3. В предпочитаемой вами локальной среде разработки извлеките загруженный архивный файл и откройте каталог adk-samples/python/agents/llm-auditor .

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

4. Создайте новый контейнер облачного хранилища, выделенный для агента ADK.

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

   Заменить следующее:

   1. CLOUD_STORAGE_BUCKET_NAME на уникальное имя контейнера, которое вы хотите использовать.
   2. PROJECT_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 на идентификатор созданного вами облачного проекта.
   3. PROJECT_LOCATION на местоположение созданного вами облачного проекта.

6. Установка и развертывание агента ADK из виртуальной среды.

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

7. Получите идентификатор агента, он понадобится вам позже для настройки пользовательской функции.

   python3 deployment/deploy.py --list

Ознакомьтесь с примером кода

При желании перед созданием новой электронной таблицы выделите немного времени на то, чтобы просмотреть и ознакомиться с примером кода, размещенным на GitHub.

Посмотреть на GitHub

Создать и настроить в новой электронной таблице

1. Нажмите следующую кнопку и создайте полную копию примера электронной таблицы Google Таблиц, включая проект Apps Script, привязанный к контейнеру.

   Копировать таблицу Google Таблиц

2. В только что созданной таблице перейдите в раздел Расширения > Скрипт приложений .

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, развернутого на предыдущих этапах, например 1234567890 .
   4. SERVICE_ACCOUNT_KEY с ключом JSON из учетной записи службы, загруженной на предыдущих шагах, например { ... } .

4. Нажмите Сохранить свойства скрипта.

Протестируйте пользовательскую функцию

1. Перейдите к только что созданной электронной таблице.
2. Измените утверждения в столбце А.
3. Формулы в столбце B выполняются, а затем выводят на экран результаты проверки фактов.

Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этом руководстве, мы рекомендуем вам удалить проект Cloud.

Внимание: удаление проекта имеет следующие последствия:

• Всё в проекте будет удалено. Если для этого руководства вы использовали существующий проект, при его удалении будет удалена и вся остальная работа, проделанная вами в этом проекте.
• Пользовательские идентификаторы проектов утеряны. При создании этого проекта вы могли создать собственный идентификатор проекта, который захотите использовать в будущем. Чтобы сохранить URL-адреса, использующие этот идентификатор проекта, например URL-адрес на appspot.com, удалите выбранные ресурсы внутри проекта, а не весь проект.

Если вы планируете изучить несколько учебных пособий и кратких руководств, повторное использование проектов может помочь вам избежать превышения квот проекта.

1. В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Выберите « Меню > «IAM и администрирование» > «Управление ресурсами» .

   Перейти к диспетчеру ресурсов

2. В списке проектов выберите проект .
3. В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить» , чтобы удалить проект.

Следующие шаги

• Пользовательские функции в Google Таблицах
• Расширение Google Таблиц