Установка и настройка Toolbox для Gen AI & Агентические приложения на AlloyDB

1. Обзор

Gen AI Toolbox for Databases — это сервер с открытым исходным кодом от Google, который упрощает создание инструментов Gen AI для взаимодействия с базами данных. Он позволяет вам разрабатывать инструменты проще, быстрее и безопаснее, справляясь с такими сложностями, как объединение пулов соединений, аутентификация и многое другое. Это поможет вам создать инструменты Gen AI, которые позволят вашим агентам получать доступ к данным в вашей базе данных. Панель инструментов обеспечивает:

Упрощенная разработка: интегрируйте инструменты в свой агент менее чем за 10 строк кода, повторно используйте инструменты между несколькими агентами или платформами и упростите развертывание новых версий инструментов.

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

Повышенная безопасность: встроенная аутентификация для более безопасного доступа к вашим данным.

Сквозное наблюдение: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.

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

Что ты построишь

В рамках этой лабораторной работы вы создадите приложение, использующее инструмент для выполнения простого запроса к базе данных (AlloyDB), который можно вызвать из вашего агента или генеративного приложения искусственного интеллекта. Для этого вы будете

  1. Установить панель инструментов
  2. Настройте инструмент (предназначенный для выполнения задач в AlloyDB) на сервере Toolbox.
  3. Развертывание Toolbox в Cloud Run
  4. Протестируйте инструмент с развернутой конечной точкой Cloud Run.
  5. Создайте функцию запуска облака для вызова панели инструментов.

Требования

  • Браузер, например Chrome или Firefox.
  • Проект Google Cloud с включенной оплатой (шаги описаны в следующем разделе).

2. Прежде чем начать

Создать проект

  1. В Google Cloud Console на странице выбора проекта выберите или создайте проект Google Cloud.
  2. Убедитесь, что для вашего облачного проекта включена оплата. Узнайте, как проверить, включена ли оплата в проекте .
  3. Вы будете использовать Cloud Shell , среду командной строки, работающую в Google Cloud. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud.

Изображение кнопки «Активировать Cloud Shell»

  1. После подключения к Cloud Shell проверьте, прошли ли вы аутентификацию и установлен ли для проекта правильный идентификатор проекта, используя следующую команду: 
gcloud auth list
  1. Выполните следующую команду в Cloud Shell, чтобы убедиться, что команда gcloud знает о вашем проекте. 
gcloud config list project
  1. Если ваш проект не установлен, используйте следующую команду, чтобы установить его: 
gcloud config set project <YOUR_PROJECT_ID>
  1. Включите необходимые API, выполнив одну за другой следующие команды в терминале Cloud Shell:

Существует также одна команда для запуска приведенной ниже команды, но если вы являетесь пользователем пробной учетной записи, вы можете столкнуться с проблемами квот при попытке включить их массово. Именно поэтому команды выделены по одной в строке.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

Альтернатива команде gcloud — через консоль , выполнив поиск по каждому продукту или воспользовавшись этой ссылкой .

Если какой-либо API пропущен, вы всегда можете включить его в ходе реализации.

Обратитесь к документации по командам и использованию gcloud.

3. Настройка базы данных

В этой лабораторной работе мы будем использовать AlloyDB в качестве базы данных для хранения данных о розничной торговле. Он использует кластеры для хранения всех ресурсов, таких как базы данных и журналы. Каждый кластер имеет основной экземпляр , который предоставляет точку доступа к данным. Таблицы будут содержать фактические данные.

Давайте создадим кластер, экземпляр и таблицу AlloyDB, куда будет загружен набор данных электронной коммерции.

Создайте кластер и экземпляр

  1. Перейдите на страницу AlloyDB в Cloud Console.

Самый простой способ найти большинство страниц в Cloud Console — это выполнить их поиск с помощью панели поиска консоли.

  1. Выберите СОЗДАТЬ КЛАСТЕР на этой странице:

f76ff480c8c889aa.png

  1. Вы увидите экран, подобный показанному ниже. Создайте кластер и экземпляр со следующими значениями (убедитесь, что значения совпадают, если вы клонируете код приложения из репозитория):
  • идентификатор кластера: " vector-cluster "
  • пароль: " alloydb "
  • Совместимость с PostgreSQL 15
  • Регион: " us-central1 "
  • Сеть: « default »

538dba58908162fb.png

  1. Когда вы выберете сеть по умолчанию, вы увидите экран, подобный показанному ниже. Выберите НАСТРОЙКА СОЕДИНЕНИЯ.
    7939bbb6802a91bf.png
  2. Далее выберите «Использовать автоматически выделенный диапазон IP-адресов» и нажмите «Продолжить». Просмотрев информацию, выберите СОЗДАТЬ СОЕДИНЕНИЕ. 768ff5210e79676f.png
  3. После настройки сети вы можете продолжить создание кластера. Нажмите CREATE CLUSTER, чтобы завершить настройку кластера, как показано ниже:

e06623e55195e16e.png

Обязательно измените идентификатор экземпляра на «

vector-instance"

.

Обратите внимание, что создание кластера займет около 10 минут. В случае успеха вы должны увидеть экран с обзором только что созданного вами кластера.

4. Прием данных

Теперь пришло время добавить таблицу с данными о магазине. Перейдите в AlloyDB, выберите основной кластер, а затем AlloyDB Studio:

847e35f1bf8a8bd8.png

Возможно, вам придется подождать, пока ваш экземпляр завершится. После завершения войдите в AlloyDB, используя учетные данные, которые вы создали при создании кластера. Используйте следующие данные для аутентификации в PostgreSQL:

  • Имя пользователя: « postgres »
  • База данных: « postgres ».
  • Пароль: « alloydb »

После успешной аутентификации в AlloyDB Studio команды SQL можно будет вводить в редакторе. Вы можете добавить несколько окон редактора, используя плюс справа от последнего окна.

91a86d9469d499c4.png

Вы можете вводить команды для AlloyDB в окнах редактора, используя при необходимости параметры «Выполнить», «Форматировать» и «Очистить».

Включить расширения

Для создания этого приложения мы будем использовать расширения pgvector и google_ml_integration . Расширение pgvector позволяет хранить и искать вложения векторов. Расширение google_ml_integration предоставляет функции, которые вы используете для доступа к конечным точкам прогнозирования Vertex AI для получения прогнозов в SQL. Включите эти расширения, запустив следующие DDL:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

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

select extname, extversion from pg_extension;

Создать таблицу

Создайте таблицу, используя приведенный ниже оператор DDL:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

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

Прием данных

Для этой лабораторной работы у нас есть тестовые данные примерно из 72 записей в этом файле SQL . Он содержит поля id, name, description, quantity, price, image_url . Остальные поля будут заполнены позже в лабораторной работе.

Скопируйте оттуда операторы строк/вставки, а затем вставьте эти строки в пустую вкладку редактора и выберите «Выполнить».

Чтобы просмотреть содержимое таблицы, разверните раздел «Проводник», пока не увидите таблицу с именем «Одежда». Нажмите трехточие (⋮), чтобы увидеть возможность запроса таблицы. Оператор SELECT откроется на новой вкладке редактора.

cfaa52b717f9aaed.png

Предоставить разрешение

Запустите приведенный ниже оператор, чтобы предоставить пользователю postgres права на выполнение функции embedding :

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Предоставьте РОЛЬ пользователя Vertex AI сервисной учетной записи AlloyDB.

Перейдите в терминал Cloud Shell и введите следующую команду:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. Создайте вложения для контекста

Компьютерам гораздо проще обрабатывать числа, чем текст. Система внедрения преобразует текст в ряд чисел с плавающей запятой, называемых векторными внедрениями , которые должны представлять текст, независимо от того, как он сформулирован, на каком языке он используется и т. д.

Например, приморское место может называться «на воде», «на берегу моря», «прогулка из комнаты к океану», «сюр-ла-мер», «на берегу океана» и т. д. Все эти термины выглядят по-разному, но их семантическое значение или, в терминологии машинного обучения, их вложения должны быть очень близки друг к другу.

Теперь, когда данные и контекст готовы, мы запустим SQL, чтобы добавить встраивания описания продукта в таблицу в поле embedding . Вы можете использовать различные модели внедрения. Мы используем text-embedding-005 от Vertex AI. Обязательно используйте одну и ту же модель внедрения на протяжении всего проекта!

Примечание. Если вы используете старый проект Google Cloud, вам, возможно, придется продолжать использовать более старые версии модели встраивания текста, например textembedding-gecko.

Вернитесь на вкладку AlloyDB Studio и введите следующий DML: 

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Посмотрите на стол toys еще раз, чтобы увидеть некоторые вложения. Обязательно повторите оператор SELECT, чтобы увидеть изменения. 

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Это должно вернуть вектор внедрения, который выглядит как массив чисел с плавающей запятой, для описания игрушки, как показано ниже:

7d32f7cd7204e1f3.png

Примечание. Недавно созданные проекты Google Cloud на уровне бесплатного пользования могут столкнуться с проблемами квот, когда речь идет о количестве запросов на внедрение, разрешенных в секунду для моделей внедрения. Мы предлагаем вам использовать фильтрационный запрос для идентификатора, а затем выборочно выбирать 1–5 записей и т. д. при создании внедрения.

6. Выполните векторный поиск.

Теперь, когда таблица, данные и внедрения готовы, давайте выполним векторный поиск в реальном времени для текста поиска пользователя.

Предположим, пользователь спрашивает:

« I want a white plush teddy bear toy with a floral pattern ».

Вы можете найти совпадения для этого, выполнив запрос ниже: 

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

Давайте рассмотрим этот запрос подробно:

В этом запросе

  1. Текст поиска пользователя: « I want a white plush teddy bear toy with a floral pattern.
  2. Мы конвертируем его во встраивания в методе embedding() используя модель: text-embedding-005 . Этот шаг должен выглядеть знакомо после предыдущего шага, где мы применили функцию внедрения ко всем элементам таблицы.
  3. " <=> " представляет собой использование метода расстояния COSINE SIMILARITY . Вы можете найти все доступные меры сходства в документации pgvector .
  4. Мы преобразуем результат метода внедрения в векторный тип, чтобы сделать его совместимым с векторами, хранящимися в базе данных.
  5. LIMIT 5 означает, что мы хотим извлечь 5 ближайших соседей для искомого текста.

Результат выглядит следующим образом:

fa7f0fc3a4c68804.png

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

7. Подготовка AlloyDB для взаимодействия с Toolbox

Готовясь к настройке Toolbox, давайте включим общедоступное IP-подключение в нашем экземпляре AlloyDB, чтобы новый инструмент мог получить доступ к базе данных.

  1. Перейдите к своему экземпляру AlloyDB, нажмите «ИЗМЕНИТЬ» и перейдите на страницу «Редактировать основной экземпляр».
  2. Перейдите в раздел «Подключение по общедоступному IP-адресу», установите флажок «Включить общедоступный IP-адрес» и введите IP-адрес вашего компьютера Cloud Shell.
  3. Чтобы получить IP-адрес вашего компьютера Cloud Shell, перейдите в терминал Cloud Shell и введите ifconfig. В результате определите IP-адрес eth0 и замените последние 2 цифры на 0,0 с размером маски «/16». Например, это будет выглядеть как «XX.XX.0.0/16», где XX — числа.
  4. Вставьте этот IP-адрес в текстовое поле «Разрешенные внешние сети» «Сети» на странице редактирования экземпляра.

5f6e60e8dec2cea1.png

  1. После завершения нажмите ОБНОВИТЬ ЭКЗЕМПЛЯР.

Это займет несколько минут.

8. Установка ящика для инструментов

  1. Вы можете создать папку проекта для хранения сведений об инструменте. В данном случае, поскольку мы работаем с данными магазина игрушек, давайте создадим папку с именем «toystore» и перейдем в нее. Перейдите к терминалу Cloud Shell и убедитесь, что ваш проект выбран и отображается в командной строке терминала. Запустите приведенную ниже команду из терминала Cloud Shell: 
mkdir toystore

cd toystore
  1. Запустите приведенную ниже команду, чтобы загрузить и установить набор инструментов в новую папку: 
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  1. Переключитесь на редактор Cloud Shell. Разверните вновь созданную папку «toystore» и создайте новый файл с именемtools.yaml. Скопируйте содержимое ниже. Замените YOUR_PROJECT_ID и проверьте правильность всех остальных данных подключения. 
sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

В этом инструменте мы просто находим наиболее близкое совпадение с текстом поиска пользователя (индивидуальным описанием игрушки) и возвращаем его цену. Вы также можете изменить его, чтобы найти среднюю цену 5 наиболее подходящих игрушек:

выберите avg(цену) из (ВЫБЕРИТЕ цену ИЗ игрушек ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS вектор(768)) LIMIT 5) в качестве цены;

Все готово с определением инструмента!

Более подробную информацию о настройке Tools.yaml можно найти в этой документации .

  1. Переключитесь на терминал Cloud Shell и введите следующую команду, чтобы запустить сервер панели инструментов с вашей конфигурацией инструментов: 
./toolbox --tools_file "tools.yaml"
  1. Теперь, если вы откроете сервер в режиме веб-предварительного просмотра в облаке, вы сможете увидеть работающий сервер Toolbox с вашим новым инструментом под названием get-toy-price.

9. Развертывание Toolbox в облаке

Давайте развернем его в Cloud Run, чтобы вы могли использовать этот инструмент в реальных условиях.

  1. Следуйте инструкциям на этой странице один за другим, пока не дойдете до команды gcloud run deploy toolbox , которая находится в третьем пункте раздела «Развертывание в облаке». Вам нужен первый вариант, а не второй, который предназначен для случаев, когда вы используете метод сети VPC.
  2. После успешного развертывания вы получите развернутую конечную точку Cloud Run вашего сервера Toolbox. Проверьте это с помощью команды CURL.

Все готово для использования недавно развернутого инструмента в вашем агентном приложении!!!

10. Подключите свое приложение к Toolbox

В этой части мы создадим небольшое приложение для тестирования вашего инструмента на предмет взаимодействия с потребностями приложения и получения ответа.

  1. Перейдите в Google Colab и откройте новый блокнот.
  2. Запустите следующее в своем блокноте 
pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)
  1. У вас должно получиться следующее:

5074f209a86c4f15.png

Этот инструмент вызывается явно в приложении Python, которое использует набор toolbox-langchain .

  1. Если вы хотите использовать этот инструмент и привязать его к агенту в интегрированном приложении LangGraph, вы можете легко сделать это с помощью набора инструментов langgraph .
  2. Для этого обратитесь к фрагментам кода .

11. Отнесите его в Облако!!!

Давайте обернем этот фрагмент кода Python в функции облачного запуска, чтобы сделать его бессерверным!

  1. Скопируйте исходный код из папки репозитория кода, чтобы передать его в Cloud Functions.
  2. Перейдите в консоль Cloud Run Functions и нажмите CREATE FUNCTION.
  3. Оставьте его без аутентификации для демонстрационного приложения и выберите среду выполнения Python 3.11 на следующей странице.
  4. Скопируйте файлы main.py и requirements.txt из исходного репозитория, предоставленного на шаге 1, и вставьте в соответствующие файлы.
  5. Разверните эту функцию, и вы получите конечную точку REST для инструмента прогнозирования цен, доступ к которому будет осуществляться в веб-приложении магазина игрушек.
  6. Ваша конечная точка должна выглядеть так:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

  1. Вы можете протестировать его непосредственно в консоли Cloud Functions, перейдя на вкладку ТЕСТИРОВАНИЕ и введя в качестве входных данных запроса следующее:

{

               "`search`"`:` "`White plush toy`"

}

  1. Нажмите ПРОВЕРИТЬ ФУНКЦИЮ или запустите в терминале Cloud Shell любой вариант, который вы решите использовать. Вы должны увидеть результат справа под заголовком «Вывод»:

d7ba57cf5e5ca553.png

12. Поздравления

Поздравляем! Вы успешно создали надежный и по-настоящему модульный инструмент, который может взаимодействовать между базами данных, платформами и платформами оркестрации генеративного искусственного интеллекта, помогая создавать ваше агентное приложение.