О практической работе
1. Введение
Spanner — это полностью управляемая, горизонтально масштабируемая, глобально распределенная служба базы данных, которая отлично подходит как для реляционных, так и для нереляционных рабочих нагрузок.
Spanner имеет встроенную поддержку векторного поиска, что позволяет выполнять поиск по сходству или семантическому поиску, а также реализовывать расширенную генерацию поиска (RAG) в приложениях GenAI в больших масштабах, используя либо точные функции K-ближайших соседей (KNN), либо приближенные функции ближайших соседей (ANN).
Векторные поисковые запросы Spanner возвращают свежие данные в реальном времени сразу после совершения транзакций, как и любой другой запрос к вашим операционным данным.
В этой лабораторной работе вы изучите настройку основных функций, необходимых для использования Spanner для выполнения векторного поиска, а также получите доступ к моделям встраивания и LLM из модельного парка VertexAI с помощью SQL.
Архитектура будет выглядеть так:
Используя эту основу, вы научитесь создавать векторный индекс на основе алгоритма ScaNN и использовать функции расстояния APPROX, когда ваши семантические рабочие нагрузки необходимо масштабировать.
Что вы построите
В рамках этой лабораторной работы вы:
- Создать экземпляр Spanner
- Настройте схему базы данных Spanner для интеграции с встраиванием и моделями LLM в VertexAI
- Загрузить набор розничных данных
- Выполнять поисковые запросы на сходство с набором данных
- Предоставьте контекст модели LLM для разработки рекомендаций по конкретным продуктам.
- Измените схему и создайте векторный индекс.
- Измените запросы, чтобы использовать вновь созданный векторный индекс.
Чему вы научитесь
- Как настроить экземпляр Spanner
- Как интегрироваться с VertexAI
- Как использовать Spanner для выполнения векторного поиска с целью нахождения похожих товаров в наборе данных розничной торговли
- Как подготовить базу данных к масштабированию рабочих нагрузок векторного поиска с использованием поиска на основе ИНС.
Что вам понадобится
2. Настройка и требования
Создать проект
Если у вас еще нет учетной записи Google (Gmail или Google Apps), вам необходимо ее создать . Войдите в консоль Google Cloud Platform ( console.cloud.google.com ) и создайте новый проект.
Если у вас уже есть проект, щелкните раскрывающееся меню выбора проекта в левом верхнем углу консоли:
и нажмите кнопку «НОВЫЙ ПРОЕКТ» в появившемся диалоговом окне, чтобы создать новый проект:
Если у вас еще нет проекта, вы увидите подобное диалоговое окно для создания своего первого проекта:
Последующий диалог создания проекта позволяет вам ввести данные вашего нового проекта:
Запомните идентификатор проекта, который является уникальным именем для всех проектов Google Cloud (имя выше уже занято и не будет работать для вас, извините!). Далее в этой кодовой лаборатории он будет называться PROJECT_ID.
Далее, если вы этого еще не сделали, вам необходимо включить выставление счетов в Developers Console, чтобы использовать ресурсы Google Cloud и включить API Spanner .
Прохождение этой кодовой лаборатории не должно обойтись вам дороже нескольких долларов, но может обойтись дороже, если вы решите использовать больше ресурсов или оставите их запущенными (см. раздел «Очистка» в конце этого документа). Цены на Google Cloud Spanner задокументированы здесь .
Новые пользователи Google Cloud Platform имеют право на бесплатную пробную версию стоимостью 300 долларов США , что должно сделать эту практическую работу полностью бесплатной.
Настройка Google Cloud Shell
Хотя Google Cloud и Spanner можно использовать удаленно с вашего ноутбука, в этой лабораторной работе мы будем использовать Google Cloud Shell — среду командной строки, работающую в облаке.
Эта виртуальная машина на базе Debian загружена всеми необходимыми вам инструментами разработки. Она предлагает постоянный домашний каталог на 5 ГБ и работает в Google Cloud, значительно повышая производительность сети и аутентификацию. Это означает, что для этой кодовой лаборатории вам понадобится только браузер (да, он работает на Chromebook).
- Чтобы активировать Cloud Shell из Cloud Console, просто нажмите «Активировать Cloud Shell».
(подготовка и подключение к среде займет всего несколько минут).
После подключения к Cloud Shell вы должны увидеть, что вы уже аутентифицированы и что проекту уже присвоен ваш PROJECT_ID.
gcloud auth list
Вывод команды
Credentialed accounts:
- <myaccount>@<mydomain>.com (active)
gcloud config list project
Вывод команды
[core]
project = <PROJECT_ID>
Если по какой-то причине проект не установлен, просто выполните следующую команду:
gcloud config set project <PROJECT_ID>
Ищете свой PROJECT_ID ? Проверьте, какой идентификатор вы использовали на этапах настройки, или найдите его на панели управления Cloud Console:
Cloud Shell также устанавливает некоторые переменные среды по умолчанию, что может быть полезно при запуске будущих команд.
echo $GOOGLE_CLOUD_PROJECT
Вывод команды
<PROJECT_ID>
Включить API Spanner и API VertexAI
gcloud services enable spanner.googleapis.com
gcloud services enable aiplatform.googleapis.com
Проверьте политику IAM :
Единственное, что нужно в политике IAM, чтобы поиск векторов работал в экземпляре spanner, — это предоставить service-<PROJECT_NUMBER>@gcp-sa-spanner.iam.gserviceaccount.com в качестве Cloud Spanner API Service Agent. Щелкните значок с тремя полосками в левом верхнем углу, как показано ниже,
Там вы увидите политику IAM:
Вы можете проверить настройки IAM в разделе «Разрешения», как показано ниже.
А если Cloud Spanner API Service Agent отсутствует, используйте команду ниже, чтобы предоставить его. Дополнительные инструкции можно найти здесь .
$ gcloud beta services identity create --service=spanner.googleapis.com --project=<PROJECT_ID>
$ gcloud projects add-iam-policy-binding <PROJECT_NUMBER> --member=serviceAccount:service-<PROJECT_NUMBER>@gcp-sa-spanner.iam.gserviceaccount.com --role=roles/spanner.serviceAgent --condition=None
Краткое содержание
На этом этапе вы настроили свой проект, если у вас его еще нет, активировали Cloud Shell и включили необходимые API.
Далее
Далее вам предстоит настроить экземпляр и базу данных Spanner.
3. Создать экземпляр Spanner и базу данных
Создайте экземпляр Spanner
На этом шаге мы настраиваем наш экземпляр Spanner для codelab. Чтобы сделать это, откройте Cloud Shell и выполните эту команду:
export SPANNER_INSTANCE_ID=retail-demo
gcloud spanner instances create $SPANNER_INSTANCE_ID \
--edition=ENTERPRISE \
--config=regional-us-central1 \
--description="spanner AI retail demo" \
--nodes=1
Самая низкая версия должна быть ENTERPRISE . Версия STANDARD не имеет возможности поиска векторов.
Вывод команды:
$ Creating instance...done.
Создать базу данных
После запуска вашего экземпляра вы можете создать базу данных. Spanner позволяет использовать несколько баз данных на одном экземпляре.
База данных — это место, где вы определяете свою схему. Вы также можете контролировать, кто имеет доступ к базе данных, настраивать пользовательское шифрование, настраивать оптимизатор и устанавливать период хранения.
Чтобы создать базу данных, снова используйте инструмент командной строки gcloud:
export SPANNER_DATABASE=cymbal-bikes
gcloud spanner databases create $SPANNER_DATABASE \
--instance=$SPANNER_INSTANCE_ID
Вывод команды:
$ Creating database...done.
Краткое содержание
На этом этапе вы создали экземпляр и базу данных Spanner.
Далее
Далее вам предстоит настроить схему и данные Spanner.
4. Загрузить схему и данные Cymbal
Создать схему тарелок
Чтобы настроить схему, перейдите в Spanner Studio:
Схема состоит из двух частей. Во-первых, вы хотите добавить таблицу products . Скопируйте и вставьте этот оператор в пустую вкладку.
Для схемы скопируйте и вставьте этот DDL в поле:
CREATE TABLE products(
categoryId INT64 NOT NULL,
productId INT64 NOT NULL,
productName STRING(MAX) NOT NULL,
productDescription STRING(MAX) NOT NULL,
productDescriptionEmbedding ARRAY<FLOAT32>,
createTime TIMESTAMP NOT NULL
OPTIONS (
allow_commit_timestamp = TRUE),
inventoryCount INT64 NOT NULL,
priceInCents INT64,)
PRIMARY KEY(categoryId, productId);
Затем нажмите кнопку run и подождите несколько секунд, пока будет создана ваша схема.
Далее вы создадите две модели и настроите их на конечные точки модели VertexAI.
Первая модель — это модель встраивания, которая используется для генерации встраиваний из текста, а вторая — это модель LLM, которая используется для генерации ответов на основе данных в Spanner.
Вставьте следующую схему в новую вкладку в Spanner Studio:
CREATE OR REPLACE MODEL EmbeddingsModel
INPUT(content STRING(MAX)) OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>) REMOTE
OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/<PROJECT_ID>/locations/us-central1/publishers/google/models/text-embedding-004');
CREATE OR REPLACE MODEL LLMModel
INPUT(prompt STRING(MAX)) OUTPUT(content STRING(MAX)) REMOTE
OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/<PROJECT_ID>/locations/us-central1/publishers/google/models/gemini-2.0-flash-001',
default_batch_size = 1);
Затем нажмите кнопку run и подождите несколько секунд, пока будут созданы ваши модели.
На левой панели Spanner Studio вы должны увидеть следующие таблицы и модели:
Загрузить данные
Теперь вам нужно будет вставить некоторые продукты в вашу базу данных. Откройте новую вкладку в Spanner Studio, затем скопируйте и вставьте следующие операторы вставки:
INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents)
VALUES (1, 1, "Cymbal Helios Helmet", "Safety meets style with the Cymbal children's bike helmet. Its lightweight design, superior ventilation, and adjustable fit ensure comfort and protection on every ride. Stay bright and keep your child safe under the sun with Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999),
(1, 2, "Cymbal Sprout", "Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years. Its lightweight frame, low seat height, and puncture-proof tires promote stability and confidence as little ones learn to balance and steer. Watch them sprout into cycling enthusiasts with Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999),
(1, 3, "Cymbal Spark Jr.", "Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8). Its sturdy frame, easy-to-use brakes, and puncture-resistant tires inspire confidence and endless playtime. Let the spark of cycling ignite with Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900),
(1, 4, "Cymbal Summit", "Conquering trails is a breeze with the Summit mountain bike. Its lightweight aluminum frame, responsive suspension, and powerful disc brakes provide exceptional control and comfort for experienced bikers navigating rocky climbs or shredding downhill. Reach new heights with Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999),
(1, 5, "Cymbal Breeze", "Cruise in style and embrace effortless pedaling with the Breeze electric bike. Its whisper-quiet motor and long-lasting battery let you conquer hills and distances with ease. Enjoy scenic rides, commutes, or errands with a boost of confidence from Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999),
(1, 6, "Cymbal Trailblazer Backpack", "Carry all your essentials in style with the Trailblazer backpack. Its water-resistant material, multiple compartments, and comfortable straps keep your gear organized and accessible, allowing you to focus on the adventure. Blaze new trails with Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999),
(1, 7, "Cymbal Phoenix Lights", "See and be seen with the Phoenix bike lights. Powerful LEDs and multiple light modes ensure superior visibility, enhancing your safety and enjoyment during day or night rides. Light up your journey with Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999),
(1, 8, "Cymbal Windstar Pump", "Flat tires are no match for the Windstar pump. Its compact design, lightweight construction, and high-pressure capacity make inflating tires quick and effortless. Get back on the road in no time with Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999),
(1, 9,"Cymbal Odyssey Multi-Tool","Be prepared for anything with the Odyssey multi-tool. This handy gadget features essential tools like screwdrivers, hex wrenches, and tire levers, keeping you ready for minor repairs and adjustments on the go. Conquer your journey with Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999),
(1, 10,"Cymbal Nomad Water Bottle","Stay hydrated on every ride with the Nomad water bottle. Its sleek design, BPA-free construction, and secure lock lid make it the perfect companion for staying refreshed and motivated throughout your adventures. Hydrate and explore with Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);
Нажмите кнопку run , чтобы вставить данные.
Краткое содержание
На этом этапе вы создали схему и загрузили некоторые основные данные в базу данных cymbal-bikes .
Далее
Далее вы выполните интеграцию с моделью встраивания для генерации встраиваний описаний продуктов, а также преобразуете текстовый поисковый запрос во встраивание для поиска соответствующих продуктов.
5. Работа с вложениями
Создание векторных вложений для описаний продуктов
Чтобы поиск по схожести работал с продуктами, вам необходимо сгенерировать вложения для описаний продуктов.
С EmbeddingsModel , созданным в схеме, это простой оператор UPDATE DML.
UPDATE products p1
SET
productDescriptionEmbedding = (
SELECT embeddings.values
FROM
ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT productDescription AS content))
)
WHERE categoryId = 1;
Нажмите кнопку run , чтобы обновить описания продуктов.
Если возникла какая-либо ошибка, попробуйте выполнить команду sql в терминале с помощью команды gcloud, чтобы получить более подробное сообщение об ошибке, например:
gcloud spanner databases execute-sql <YOUR_DATA_BASE> --instance=<YOUR_INSTANCE> --sql 'UPDATE products p1
SET
productDescriptionEmbedding = (
SELECT embeddings.values
FROM
ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT productDescription AS content FROM products p2 WHERE p2.productId = p1.productId))
)
WHERE categoryId = 1;'
Использование векторного поиска
В этом примере вы предоставите поисковый запрос на естественном языке через SQL-запрос. Этот запрос превратит поисковый запрос в вложение, а затем выполнит поиск похожих результатов на основе сохраненных вложений описаний продуктов, которые были сгенерированы на предыдущем шаге.
-- Use Spanner's vector search, and integration with embedding and LLM models to
-- return items that are semantically relevant and available in inventory based on
-- real-time data.
SELECT
productName,
productDescription,
inventoryCount,
COSINE_DISTANCE(
productDescriptionEmbedding,
(
SELECT embeddings.values
FROM
ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT "I'd like to buy a starter bike for my 3 year old child" AS content))
)) AS distance
FROM products
WHERE inventoryCount > 0
ORDER BY distance
LIMIT 5;
Нажмите кнопку run , чтобы найти похожие продукты. Результаты должны выглядеть следующим образом:
Обратите внимание, что в запросе используются дополнительные фильтры, например, интересуются только теми товарами, которые есть в наличии ( inventoryCount > 0 ).
Краткое содержание
На этом этапе вы создали вложения описания продукта и вложения поискового запроса с использованием SQL, используя интеграцию Spanner с моделями в VertexAI. Вы также выполнили векторный поиск, чтобы найти похожие продукты, которые соответствуют поисковому запросу.
Следующие шаги
Далее давайте используем результаты поиска для передачи их в LLM, чтобы сгенерировать индивидуальный ответ для каждого продукта.
6. Работа с LLM
Spanner упрощает интеграцию с моделями LLM, обслуживаемыми VertexAI. Это позволяет разработчикам использовать SQL для прямого взаимодействия с LLM, не требуя от приложения выполнения логики.
Например, у нас есть результаты предыдущего SQL-запроса пользователя "I'd like to buy a starter bike for my 3 year old child".
Разработчик хотел бы предоставить ответ на каждый результат о том, подходит ли продукт пользователю, используя следующую подсказку:
"Answer with 'Yes' or 'No' and explain why: Is this a good fit for me? I'd like to buy a starter bike for my 3 year old child"
Вот запрос, который вы можете использовать:
-- Use an LLM to analyze this list and provide a recommendation on whether each
-- product is a good fit for the user. We use the vector search and real time
-- inventory data to first filter the products to reduce the size of the prompt to
-- the LLM.
SELECT productName, productDescription, inventoryCount, content AS LLMResponse
FROM
ML.PREDICT(
MODEL LLMModel,
(
SELECT
FORMAT(
"""Answer with Yes or No and explain why: Is this a good fit for me?
I would like to buy a starter bike for my 3 year old child \n Product Name: %s\nProduct Description: %s""", productName,productDescription) AS prompt,
-- Pass through columns.
inventoryCount,
productName,
productDescription,
FROM products
WHERE inventoryCount > 0
ORDER BY
COSINE_DISTANCE(
productDescriptionEmbedding,
(
SELECT embeddings.values
FROM
ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT "I'd like to buy a starter bike for my 3 year old child" AS content))
))
LIMIT 5
));
Нажмите кнопку run , чтобы выполнить запрос. Результаты должны выглядеть следующим образом:
Первый продукт подходит для 3-летнего ребенка из-за возрастного диапазона в описании продукта (2-4 года). Остальные продукты не очень подходят.
Краткое содержание
На этом этапе вы работали с LLM, чтобы генерировать базовые ответы на запросы пользователя.
Следующие шаги
Далее давайте узнаем, как использовать ИНС для масштабирования векторного поиска.
7. Масштабирование поиска векторов
Предыдущие примеры векторного поиска использовали точный векторный поиск KNN. Это здорово, когда вы можете запрашивать очень конкретные подмножества данных Spanner. Такие типы запросов называются высокоразделимыми .
Если у вас нет рабочих нагрузок, которые можно легко разбить на разделы, и у вас большой объем данных, вам следует использовать векторный поиск на основе ИНС, используя алгоритм ScaNN для повышения производительности поиска.
Чтобы сделать это в Spanner, вам нужно будет сделать две вещи:
- Создать векторный индекс
- Измените свой запрос, чтобы использовать функции расстояния APPROX .
Создать векторный индекс
Чтобы создать векторный индекс на этом наборе данных, нам сначала нужно будет изменить столбец productDescriptionEmbeddings , чтобы определить длину каждого вектора. Чтобы добавить длину вектора в столбец, необходимо удалить исходный столбец и создать его заново.
ALTER TABLE products DROP COLUMN productDescriptionEmbedding;
ALTER TABLE products
ADD COLUMN productDescriptionEmbedding ARRAY<FLOAT32>(vector_length => 768);
Затем снова создайте вложения из шага Generate Vector embedding вы выполнили ранее.
UPDATE products p1
SET
productDescriptionEmbedding = (
SELECT embeddings.values
FROM
ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT productDescription AS content FROM products p2 WHERE p2.productId = p1.productId))
)
WHERE categoryId = 1;
После создания столбца создайте индекс:
CREATE VECTOR INDEX ProductDescriptionEmbeddingIndex
ON products(productDescriptionEmbedding)
WHERE productDescriptionEmbedding IS NOT NULL
OPTIONS (
distance_type = 'COSINE'
);
Если вам интересно, ознакомьтесь с PDML по адресу https://cloud.google.com/spanner/docs/backfill-embeddings . Один оператор DML — это транзакция, на которую распространяется ограничение в 80 тыс. мутаций, поэтому вы не можете обновить слишком много строк одновременно. PDML эффективно обрабатывает разбиение на более мелкие партии.
Используйте новый индекс
Чтобы использовать новый векторный индекс, вам придется немного изменить предыдущий запрос на внедрение.
Вот исходный запрос:
SELECT
productName,
productDescription,
inventoryCount,
COSINE_DISTANCE(
productDescriptionEmbedding,
(
SELECT embeddings.values
FROM
ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT "I'd like to buy a starter bike for my 3 year old child" AS content))
)) AS distance
FROM products
WHERE inventoryCount > 0
ORDER BY distance
LIMIT 5;
Вам придется внести следующие изменения:
- Используйте подсказку индекса для нового векторного индекса:
@{force_index=ProductDescriptionEmbeddingIndex} - Измените вызов функции
COSINE_DISTANCEнаAPPROX_COSINE_DISTANCE. Обратите внимание, что параметры JSON в последнем запросе ниже также являются обязательными. - Сгенерируйте вложения из функции ML.PREDICT отдельно.
- Скопируйте результаты встраиваний в окончательный запрос.
Сгенерируйте и используйте вложения:
-- Generate the prompt embeddings
SELECT embeddings.values
FROM ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT "I'd like to buy a starter bike for my 3 year old child" as content)
);
Выделите результаты запроса и скопируйте их.
Затем замените <VECTOR> в следующем запросе, вставив скопированные вами вложения.
-- Generate the embeddings and query them using the vector index
SELECT
productName,
productDescription,
inventoryCount,
APPROX_COSINE_DISTANCE(
productDescriptionEmbedding,
array<float32>[@VECTOR],
options => JSON '{\"num_leaves_to_search\": 10}') AS distance
FROM products @{force_index = ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;
Это должно выглядеть примерно так:
Краткое содержание
На этом этапе вы преобразовали свою схему для создания векторного индекса. А затем вы переписали запрос на встраивание для выполнения поиска ANN с использованием векторного индекса. Это важный шаг, поскольку ваши данные растут для масштабирования рабочих нагрузок векторного поиска.
Следующие шаги
Теперь пришло время уборки!
8. Уборка (по желанию)
Чтобы навести порядок, просто удалите экземпляр « retail-demo », который мы создали в кодовой лаборатории.
9. Поздравляю!
Поздравляем, вы успешно выполнили поиск по сходству с помощью встроенного векторного поиска Spanner. Кроме того, вы увидели, как легко работать с встраиванием и моделями LLM для предоставления генеративной функциональности ИИ напрямую с помощью SQL.
Наконец, вы изучили процесс выполнения поиска с использованием ИНС, поддерживаемого алгоритмом ScaNN для масштабирования рабочих нагрузок векторного поиска.
Что дальше?
Подробнее о функции поиска точного ближайшего соседа Spanner (векторный поиск KNN) можно узнать здесь: https://cloud.google.com/spanner/docs/find-k-nearest-neighbors
Подробнее о функции поиска ближайшего соседа (поиск вектора ИНС) Spanner можно узнать здесь: https://cloud.google.com/spanner/docs/find-approximate-nearest-neighbors
Вы также можете узнать больше о том, как выполнять онлайн-прогнозы с помощью SQL, используя интеграцию VertexAI от Spanner, здесь: https://cloud.google.com/spanner/docs/ml