1. Обзор
В этом практическом занятии вы создадите Neighbor Loop, приложение для устойчивого обмена излишками ресурсов, которое рассматривает интеллект как полноправного участника уровня данных.
Интеграция Gemini 3.0 Flash и интеграций Cloud SQL с машинным обучением позволит вам выйти за рамки простого хранения данных и перейти в область интеллектуального анализа данных непосредственно в базе данных. Вы научитесь выполнять многомодальный анализ элементов и семантический поиск прямо в SQL.
Что вы построите
Высокопроизводительное веб-приложение с функцией "подбор совпадений по свайпу" для обмена излишками товаров и услуг внутри сообщества.
Что вы узнаете
- Создание экземпляра Cloud SQL в один клик: как настроить Cloud SQL и экземпляр, предназначенный для рабочих нагрузок ИИ.
- Встраивание данных в базу данных: генерация векторов text-embedding-005 непосредственно в операторах INSERT.
- Мультимодальное мышление: использование Gemini 3.0 Flash для «просмотра» элементов и автоматического создания остроумных биографий в стиле сайтов знакомств.
- Семантическое обнаружение: выполнение логических «проверок на соответствие» внутри SQL-запросов с использованием функции ai.if() для фильтрации результатов на основе контекста, а не только математических вычислений.
Архитектура
Метод Neighbor Loop позволяет обойти традиционные узкие места на уровне приложений. Вместо извлечения данных для их обработки мы используем:
- Интеграция Cloud SQL и машинного обучения: для генерации и хранения векторов в режиме реального времени.
- Google Cloud Storage: для хранения изображений.
- Gemini 3.0 Flash: Для выполнения вычислений с точностью до долей секунды на основе данных изображений и текста непосредственно через SQL.
- Cloud Run: Для размещения легковесного бэкенда на Flask, работающего в одном файле.
Требования
2. Прежде чем начать
Создать проект
- В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
- Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
- Вы будете использовать Cloud Shell — среду командной строки, работающую в Google Cloud. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud.
- После подключения к Cloud Shell необходимо проверить, прошли ли вы аутентификацию и установлен ли идентификатор вашего проекта, используя следующую команду:
gcloud auth list
- Выполните следующую команду в Cloud Shell, чтобы убедиться, что команда gcloud знает о вашем проекте.
gcloud config list project
- Если ваш проект не задан, используйте следующую команду для его установки:
gcloud config set project <YOUR_PROJECT_ID>
- Включите необходимые API: перейдите по ссылке и включите API.
В качестве альтернативы можно использовать команду gcloud. Для получения информации о командах gcloud и их использовании обратитесь к документации .
Подводные камни и устранение неполадок
Синдром «Проекта-призрака» | Вы выполнили команду |
Баррикада Биллинга | Вы активировали проект, но забыли указать платежный аккаунт. Cloud SQL не запустится, если платежный аккаунт пуст. |
Задержка распространения API | Вы нажали «Включить API», но в командной строке по-прежнему отображается сообщение |
3. Настройка базы данных
В этой лабораторной работе мы будем использовать Cloud SQL для PostgreSQL в качестве базы данных для тестовых данных.
Давайте создадим экземпляр Cloud SQL, куда будет загружен тестовый набор данных.
- Нажмите на кнопку или скопируйте ссылку ниже в браузер, где вы авторизованы в Google Cloud Console.
- После завершения этого шага репозиторий будет клонирован в ваш локальный редактор CloudShell, и вы сможете запустить приведенную ниже команду, указав папку проекта (важно убедиться, что вы находитесь в каталоге проекта):
sh run.sh
- Теперь воспользуйтесь пользовательским интерфейсом (щелкните ссылку в терминале или щелкните ссылку «предварительный просмотр в веб-браузере» в терминале).
- Введите данные для идентификатора проекта и имени экземпляра, чтобы начать.
- Пока прокручиваются логи, выпейте кофе, а подробнее о том, как это всё происходит за кулисами, вы можете прочитать здесь.
Подводные камни и устранение неполадок
Региональное несоответствие | Если вы включили API в регионе |
Таймаут облачной оболочки | Если ваш перерыв на кофе длится 30 минут, Cloud Shell может перейти в спящий режим и отключить процесс |
4. Предоставление схемы
После запуска экземпляра Cloud SQL перейдите в редактор SQL Cloud SQL Studio, чтобы включить расширения AI и настроить схему.
Возможно, вам потребуется дождаться завершения создания экземпляра. После этого войдите в свой экземпляр Cloud SQL, используя учетные данные, которые вы создали при его создании. Для аутентификации в PostgreSQL используйте следующие данные:
- Имя пользователя: "
postgres" - База данных: "
postgres" - Пароль: "
cloudsql" (или любой другой, который вы указали при создании учетной записи)
После успешной аутентификации в Cloud SQL Studio команды SQL вводятся в редакторе. Вы можете добавить несколько окон редактора, используя значок плюса справа от последнего окна.
Команды для Cloud SQL будут вводиться в окнах редактора, используя при необходимости параметры «Выполнить», «Форматировать» и «Очистить».
Включить расширения
Для создания этого приложения мы будем использовать расширения 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;
Создайте таблицу
В Cloud SQL Studio можно создать таблицу, используя приведенный ниже оператор DDL:
-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
owner_id UUID,
provider_name TEXT,
provider_phone TEXT,
title TEXT,
bio TEXT,
category TEXT,
image_url TEXT,
item_vector VECTOR(768),
status TEXT DEFAULT 'available',
created_at TIMESTAMP DEFAULT NOW()
);
-- Swipes Table (The Interaction)
CREATE TABLE swipes (
swipe_id SERIAL PRIMARY KEY,
swiper_id UUID,
item_id UUID REFERENCES items(item_id),
direction TEXT CHECK (direction IN ('left', 'right')),
is_match BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
Столбец item_vector позволит хранить векторные значения текста.
Предоставить разрешение
Выполните указанное ниже выражение, чтобы предоставить права на выполнение функции "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Включить интеграцию машинного обучения
Для непосредственного использования функций машинного обучения в вашей базе данных необходимо включить флаг интеграции машинного обучения.
Вы можете выполнить следующую команду в терминале Cloud Shell:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
gcloud sql instances patch $INSTANCE_NAME --tier=db-custom-1-3840
gcloud sql instances patch $INSTANCE_NAME \
--database-flags=cloudsql.enable_google_ml_integration=on
gcloud sql instances patch $INSTANCE_NAME --enable-google-ml-integration
Предоставьте учетной записи службы Cloud SQL роль пользователя Vertex AI.
В консоли Google Cloud IAM предоставьте учетной записи службы Cloud SQL (которая выглядит следующим образом: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) доступ к роли "Пользователь Vertex AI". В поле PROJECT_NUMBER будет указан номер вашего проекта.
В качестве альтернативы вы можете выполнить следующую команду в терминале Cloud Shell:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format='value(serviceAccountEmailAddress)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SA_EMAIL" \
--role="roles/aiplatform.user"
Зарегистрируйте модель Gemini 3 Flash в Cloud SQL.
Выполните приведенный ниже SQL-запрос в редакторе SQL-запросов Cloud SQL Query Editor.
CALL google_ml.create_model(
model_id => 'gemini-3-flash-preview',
model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
model_qualified_name => 'gemini-3-flash-preview',
model_provider => 'google',
model_type => 'generic',
model_auth_type => 'cloudsql_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.
Подводные камни и устранение неполадок
Цикл «Забвения паролей» | Если вы использовали настройку "в один клик" и не помните свой пароль, перейдите на страницу основной информации об экземпляре в консоли и нажмите "Изменить", чтобы сбросить пароль |
Ошибка "Расширение не найдено" | Если |
Разрыв в распространении IAM | Вы выполнили команду |
Несоответствие размерности вектора | Таблица |
Опечатка в идентификаторе проекта | Если в вызове функции |
Интеграция с Vertex AI отключена. | Выполните команду |
5. Хранилище изображений (Google Cloud Storage)
Для хранения фотографий наших излишков товаров мы используем хранилище GCS. В целях данного демонстрационного приложения нам необходимо, чтобы изображения были общедоступны и мгновенно отображались на наших считывающих картах.
- Создание хранилища (Bucket): Создайте новое хранилище в вашем проекте GCP (например, neighborloop-images), предпочтительно в том же регионе, что и ваша база данных и приложение.
- Настройка публичного доступа: * Перейдите на вкладку «Разрешения» в настройках хранилища.
- Добавьте субъект allUsers .
- Назначьте роль « Просмотрщик объектов хранилища» (чтобы все могли видеть фотографии) и роль « Создатель объектов хранилища» (для целей загрузки демонстрационных файлов).
Альтернативный вариант (служебная учетная запись): Если вы предпочитаете не использовать публичный доступ, убедитесь, что служебной учетной записи вашего приложения предоставлен полный доступ к Cloud SQL и необходимые роли хранилища для безопасного управления объектами.
Если вы хотите выполнить команду и предоставить к ней публичный доступ, выполните следующие команды в терминале Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Подводные камни и устранение неполадок
Региональный перетаскивание | Если ваша база данных находится в регионе |
Уникальность названия категории | Имена сегментов (bucket names) представляют собой глобальное пространство имен. Если вы попытаетесь присвоить своему сегменту имя |
Путаница между «создателем» и «зрителем» | Путаница с «Создателем» и «Просмотрщиком»: если вы добавите только «Просмотрщика», ваше приложение будет аварийно завершать работу, когда пользователь попытается добавить новый элемент, поскольку у него нет разрешения на запись в файл. Для этой конкретной демонстрационной конфигурации вам нужны оба параметра. |
6. Давайте создадим приложение.
Клонируйте этот репозиторий в свой проект, и давайте разберемся.
- Чтобы клонировать этот проект, в терминале Cloud Shell (в корневом каталоге или в любом другом месте, где вы хотите его создать) выполните следующие команды по очереди:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
Это должно создать проект, и вы можете проверить это в редакторе Cloud Shell.
- Как получить ключ API Gemini
- Посетите Google AI Studio: перейдите по адресу aistudio.google.com .
- Вход в систему: Используйте ту же учетную запись Google, которую вы используете для своего проекта Google Cloud.
- Создать ключ API:
- В левой боковой панели нажмите «Получить ключ API».
- Нажмите кнопку «Создать ключ API в новом проекте».
- Скопируйте ключ: После генерации ключа нажмите значок копирования.
- Теперь установите переменные среды в файле .env.
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Замените значения для заполнителей <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Подводные камни и устранение неполадок
Путаница с несколькими учетными записями | Если вы вошли в несколько учетных записей Google (личную и рабочую), AI Studio может по умолчанию использовать не ту. Проверьте аватар в правом верхнем углу, чтобы убедиться, что он соответствует вашей учетной записи проекта GCP. |
Ограничение по квоте "бесплатного уровня" | Если вы используете бесплатный тариф, действуют ограничения по количеству запросов в минуту (RPM). Если вы будете слишком быстро «проводить пальцем» по экрану в Neighbor Loop, вы можете получить ошибку |
Защита от утечки ключей | Если вы случайно |
7. Давайте проверим код.
«Профиль знакомств» для ваших вещей
Когда пользователь загружает фотографию товара, ему не нужно писать длинное описание. Я использую Gemini 3 Flash, чтобы "увидеть" товар и написать описание за него.
В административной панели пользователь просто указывает заголовок и фотографию. Gemini обрабатывает всё остальное:
prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
"bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
"category": "One-word category",
"tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
model="gemini-3-flash-preview",
contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
config=types.GenerateContentConfig(response_mime_type="application/json")
)
Встраивание данных в базу данных в реальном времени
Одна из самых крутых особенностей Cloud SQL — это возможность генерировать эмбеддинги, не выходя из контекста SQL. Вместо того чтобы вызывать модель эмбеддинга в Python и отправлять вектор обратно в базу данных, я делаю все это в одном операторе INSERT, используя функцию embedding():
INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
:owner, :name, :phone, :title, :bio, :cat, :url, 'available',
embedding('text-embedding-005', :title || ' ' || :bio)::vector
)
Это гарантирует, что каждый товар будет доступен для поиска по его назначению в момент публикации. И обратите внимание, что это та часть, которая описывает функцию «составления списка товаров» в приложении Neighbor Loop.
Расширенный векторный поиск и интеллектуальная фильтрация с Gemini 3.0
Стандартный поиск по ключевым словам имеет ограничения. Если вы ищете «что-нибудь, чтобы починить мой стул», традиционная база данных может ничего не выдать, если слово «стул» отсутствует в заголовке. Neighbor Loop решает эту проблему с помощью расширенного векторного поиска Cloud SQL AI.
Используя расширение pgvector и оптимизированное хранилище Cloud SQL, мы можем выполнять чрезвычайно быстрый поиск сходства. Но настоящая «магия» происходит, когда мы объединяем векторную близость с логикой на основе LLM.
SELECT item_id, title, bio, category, image_url,
1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items
WHERE status = 'available'
AND item_vector IS NOT NULL
ORDER BY score DESC
LIMIT 5
Этот запрос представляет собой серьёзный архитектурный сдвиг: мы переносим логику в данные. Вместо того чтобы извлекать тысячи результатов в код приложения для их фильтрации, Gemini 3 Flash выполняет «проверку на соответствие» внутри механизма базы данных. Это снижает задержку, уменьшает затраты на исходящий трафик и гарантирует, что результаты не просто математически похожи, но и контекстно релевантны.
Цикл "Проведите пальцем для совпадения"
Пользовательский интерфейс представляет собой классическую колоду карт.
Проведите пальцем влево: Отменить.
Проведите пальцем вправо: Совпадение!
При свайпе вправо бэкэнд записывает взаимодействие в нашу таблицу свайпов и помечает товар как соответствующий. Фронтенд мгновенно запускает модальное окно с контактной информацией поставщика, чтобы вы могли договориться о самовывозе.
8. Давайте развернем его в Cloud Run.
- Разверните проект в Cloud Run, выполнив следующую команду в терминале Cloud Shell, куда клонирован проект, и убедитесь, что вы находитесь в корневой папке проекта .
Выполните следующую команду в терминале Cloud Shell:
gcloud run deploy neighbor-loop-cloud-sql \
--source . \
--region=us-central1 \
--allow-unauthenticated \
--network=easy-cloudsql-vpc \
--subnet=easy-cloudsql-subnet \
--vpc-egress=private-ranges-only \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:5432/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Замените значения для заполнителей <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
После завершения выполнения команды она выведет URL-адрес сервиса. Скопируйте его.
Теперь используйте URL-адрес сервиса (конечная точка Cloud Run, которую вы скопировали ранее) и протестируйте приложение. Загрузите фотографию старого электроинструмента, и Gemini сделает все остальное!
Подводные камни и устранение неполадок
Цикл "Редактирование не удалось" | Если развертывание завершилось успешно, но URL-адрес выдает |
9. Устранение неполадок высокого уровня
10. Демонстрация
Вы сможете использовать свою конечную точку для проведения тестов.
Но в демонстрационных целях, на несколько дней, вы можете поэкспериментировать с этим:
11. Уборка
После завершения этой лабораторной работы не забудьте удалить экземпляр Cloud SQL.
12. Поздравляем!
Вы успешно создали приложение Neighbor Loop для устойчивых сообществ с помощью Google Cloud. Переместив логику встраивания и Flash AI Gemini 3 в Cloud SQL , вы добились невероятной скорости работы приложения (в зависимости от настроек развертывания) и замечательной чистоты кода. Мы храним не просто данные — мы храним намерения .
Сочетание скорости Gemini 3 Flash и оптимизированной векторной обработки Cloud SQL — это поистине новый рубеж для платформ, управляемых сообществом.