Установка и настройка MCP Toolbox для баз данных для вашего поколения AI & Агентические приложения на AlloyDB

1. Обзор

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

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

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

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

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

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

Что вы построите

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

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

Требования

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

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

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

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

4. После подключения к Cloud Shell проверьте, прошли ли вы аутентификацию и указан ли для проекта правильный идентификатор, используя следующую команду:

gcloud auth list

5. Выполните следующую команду в Cloud Shell, чтобы убедиться, что команда gcloud знает о вашем проекте.

gcloud config list project

6. Если ваш проект не задан, используйте следующую команду для его настройки:

gcloud config set project <YOUR_PROJECT_ID>

7. Включите необходимые 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.

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

2. На этой странице выберите пункт «СОЗДАТЬ КЛАСТЕР»:

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

• Идентификатор кластера: " vector-cluster "
• пароль: " alloydb "
• Совместимость с PostgreSQL 15
• Регион: " us-central1 "
• Сетевые настройки: " default "

4. После выбора сети по умолчанию вы увидите экран, похожий на показанный ниже. Выберите «НАСТРОЙКА СОЕДИНЕНИЯ».
   
5. Затем выберите «Использовать автоматически выделенный диапазон IP-адресов» и продолжите. После проверки информации выберите «СОЗДАТЬ СОЕДИНЕНИЕ».
6. После настройки сети вы можете продолжить создание кластера. Нажмите кнопку «СОЗДАТЬ КЛАСТЕР», чтобы завершить настройку кластера, как показано ниже:

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

vector-instance"

.

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

4. Ввод данных

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

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

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

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

Команды для 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 . Остальные поля будут заполнены позже в ходе лабораторной работы.

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

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

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

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

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Предоставьте учетной записи службы AlloyDB роль пользователя Vertex AI.

Перейдите в терминал 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. Создайте векторные представления для контекста.

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

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

Теперь, когда данные и контекст готовы, мы выполним 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;

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

Примечание: В новых проектах Google Cloud, созданных в рамках бесплатного уровня, могут возникнуть проблемы с ограничением количества запросов на встраивание в секунду для моделей встраивания. Мы рекомендуем использовать фильтр по ID, а затем выборочно выбирать от 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 . Этот шаг должен показаться вам знакомым после предыдущего шага, где мы применили функцию embedding ко всем элементам таблицы.
3. " <=> " обозначает использование метода расстояния COSINE SIMILARITY . Все доступные меры сходства можно найти в документации pgvector .
4. Мы преобразуем результат метода встраивания в векторный тип, чтобы обеспечить его совместимость с векторами, хранящимися в базе данных.
5. Параметр LIMIT 5 означает, что мы хотим извлечь 5 ближайших соседей для искомого текста.

Результат выглядит так:

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

7. Подготовка AlloyDB к взаимодействию с панелью инструментов.

В рамках подготовки к настройке 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-адрес в текстовое поле «Авторизованные внешние сети» в разделе «Сети» на странице редактирования экземпляра.

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

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

8. Установка MCP Toolbox для баз данных.

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

mkdir toystore

cd toystore

2. Выполните следующую команду, чтобы загрузить и установить Toolbox в новую папку:

# 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

3. Переключитесь в редактор 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 наиболее близких по совпадению игрушек:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

С определением инструмента у вас всё в порядке!

Для получения более подробной информации о настройке файла tools.yaml обратитесь к этой документации .

4. Переключитесь на терминал Cloud Shell и введите следующую команду, чтобы запустить сервер Toolbox с вашей конфигурацией инструментов:

./toolbox --tools_file "tools.yaml"

5. Теперь, если вы откроете сервер в режиме веб-просмотра в облаке, вы сможете увидеть, что сервер Toolbox запущен и работает, а ваш новый инструмент называется get-toy-price.

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

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

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

Советы:

Внимательно следуйте инструкциям на странице и ничего не пропустите.

Теперь вы полностью готовы использовать свой недавно развернутый инструмент в своем агентском приложении!!!

10. Подключите ваше приложение к MCP Toolbox для баз данных.

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

1. Перейдите в Google Colab и откройте новую записную книжку.
2. Выполните следующие действия в своем ноутбуке.

!pip install toolbox-core
from toolbox_core import ToolboxClient

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

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

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

# Print result
print(result)

3. В результате должно получиться примерно следующее:

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

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

11. Перенесите это в облако!!!

Давайте обернем этот фрагмент кода на Python в Cloud Run Functions, чтобы сделать его бессерверным!

1. Скопируйте исходный код из папки репозитория , чтобы загрузить его в Cloud Functions.
2. Перейдите в консоль Cloud Run Functions и нажмите «СОЗДАТЬ ФУНКЦИЮ».
3. Для демонстрационного приложения оставьте аутентификацию отключенной, а на следующей странице выберите среду выполнения Python 3.11.
4. Скопируйте файлы main.py и requirements.txt из репозитория исходного кода, предоставленного на шаге 1, и вставьте их в соответствующие файлы.
5. Замените URL-адрес сервера в файле main.py на URL-адрес вашего сервера.
6. Разверните функцию, и у вас появится REST-эндпоинт для инструмента прогнозирования цен, доступный в веб-приложении магазина игрушек.
7. Ваш адрес конечной точки должен выглядеть следующим образом:

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

2. Вы можете протестировать это непосредственно в консоли Cloud Functions, перейдя на вкладку TESTING и введя в качестве входных данных запроса следующее:

{

           "search": "White plush toy"

}

3. Нажмите кнопку "ПРОВЕРИТЬ ФУНКЦИЮ" или запустите команду в терминале Cloud Shell (выберите удобный для вас способ). Результат должен отобразиться справа под заголовком "Вывод":

12. Поздравляем!

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