1. Обзор
В этом практическом занятии вы создадите Neighbor Loop, приложение для устойчивого обмена излишками ресурсов, которое рассматривает интеллект как полноправного участника уровня данных.
Интеграция Gemini 3.0 Flash и AlloyDB AI позволит вам выйти за рамки простого хранения данных и перейти к интеллектуальному анализу непосредственно в базе данных. Вы научитесь выполнять многомодальный анализ элементов и семантическое обнаружение прямо в SQL, устраняя «налог на ИИ», связанный с задержками и раздуванием архитектуры.
Что вы построите
Высокопроизводительное веб-приложение с функцией "подбор совпадений по свайпу" для обмена излишками товаров и услуг внутри сообщества.
Что вы узнаете
- Создание кластера и экземпляра AlloyDB в один клик: как настроить кластер и экземпляр, предназначенные для рабочих нагрузок ИИ.
- Встраивание данных в базу данных: генерация векторов text-embedding-005 непосредственно в операторах INSERT.
- Мультимодальное мышление: использование Gemini 3.0 Flash для «просмотра» элементов и автоматического создания остроумных биографий в стиле сайтов знакомств.
- Семантическое обнаружение: выполнение логических «проверок на соответствие» внутри SQL-запросов с использованием функции ai.if() для фильтрации результатов на основе контекста, а не только математических вычислений.
Архитектура
Метод Neighbor Loop позволяет обойти традиционные узкие места на уровне приложений. Вместо извлечения данных для их обработки мы используем:
- AlloyDB AI: для генерации и хранения векторов в режиме реального времени.
- 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 и их использовании обратитесь к документации .
Подводные камни и устранение неполадок
Синдром «Проекта-призрака» | Вы выполнили команду |
Баррикада Биллинга | Вы активировали проект, но забыли указать платежный аккаунт. AlloyDB — высокопроизводительный движок; он не запустится, если «топливо» (платежный бак) пуст. |
Задержка распространения API | Вы нажали «Включить API», но в командной строке по-прежнему отображается сообщение |
Квота Квагс | Если вы используете совершенно новую пробную учетную запись, вы можете столкнуться с региональной квотой на экземпляры AlloyDB. Если |
«Скрытый» сервисный агент | Иногда агенту службы AlloyDB автоматически не предоставляется роль |
3. Настройка базы данных
В этой лабораторной работе мы будем использовать AlloyDB в качестве базы данных для тестовых данных. Она использует кластеры для хранения всех ресурсов, таких как базы данных и журналы. Каждый кластер имеет основной экземпляр , который обеспечивает точку доступа к данным. Таблицы будут содержать сами данные.
Давайте создадим кластер AlloyDB, экземпляр и таблицу, куда будет загружен тестовый набор данных.
- Нажмите на кнопку или скопируйте ссылку ниже в браузер, где вы авторизованы в Google Cloud Console.
- После завершения этого шага репозиторий будет клонирован в ваш локальный редактор CloudShell, и вы сможете запустить приведенную ниже команду, указав папку проекта (важно убедиться, что вы находитесь в каталоге проекта):
sh run.sh
- Теперь воспользуйтесь пользовательским интерфейсом (щелкните ссылку в терминале или щелкните ссылку «предварительный просмотр в веб-браузере» в терминале).
- Введите данные для идентификатора проекта, названия кластера и экземпляра, чтобы начать работу.
- Пока прокручиваются логи, выпейте кофе, а подробнее о том, как это всё происходит за кулисами, вы можете прочитать здесь.
Подводные камни и устранение неполадок
Проблема «терпения» | Кластеры баз данных — это ресурсоемкая инфраструктура. Если вы обновите страницу или завершите сессию Cloud Shell, потому что она «зависла», вы можете получить «фантомный» экземпляр, который будет частично выделен и его невозможно будет удалить без ручного вмешательства. |
Региональное несоответствие | Если вы включили API в регионе |
Скопления зомби | Если вы ранее использовали это же имя для кластера и не удалили его, скрипт может сообщить, что имя кластера уже существует. Имена кластеров должны быть уникальными в рамках одного проекта. |
Таймаут облачной оболочки | Если ваш перерыв на кофе длится 30 минут, Cloud Shell может перейти в спящий режим и отключить процесс |
4. Предоставление схемы
После запуска кластера и экземпляра AlloyDB перейдите в редактор SQL AlloyDB Studio, чтобы включить расширения AI и настроить схему.
Возможно, вам потребуется дождаться завершения создания экземпляра. После этого войдите в 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;
Создайте таблицу
В AlloyDB 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;
Предоставьте учетной записи службы AlloyDB роль пользователя Vertex AI.
В консоли Google Cloud IAM предоставьте учетной записи службы AlloyDB (которая выглядит следующим образом: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) доступ к роли "Пользователь Vertex AI". В поле PROJECT_NUMBER будет указан номер вашего проекта.
В качестве альтернативы вы можете выполнить следующую команду в терминале 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"
Зарегистрируйте модель Gemini 3 Flash в AlloyDB.
Выполните приведенный ниже SQL-запрос в редакторе запросов AlloyDB.
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 => 'llm',
model_auth_type => 'alloydb_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.
Подводные камни и устранение неполадок
Цикл «Забвения паролей» | Если вы использовали настройку "в один клик" и не помните свой пароль, перейдите на страницу основной информации об экземпляре в консоли и нажмите "Изменить", чтобы сбросить пароль |
Ошибка "Расширение не найдено" | Если |
Разрыв в распространении IAM | Вы выполнили команду |
Несоответствие размерности вектора | Таблица |
Опечатка в идентификаторе проекта | Если в вызове функции |
5. Хранилище изображений (Google Cloud Storage)
Для хранения фотографий наших излишков товаров мы используем хранилище GCS. В целях данного демонстрационного приложения нам необходимо, чтобы изображения были общедоступны и мгновенно отображались на наших считывающих картах.
- Создание хранилища: Создайте новое хранилище в вашем проекте GCP (например, neighborloop-images), предпочтительно в том же регионе, что и ваша база данных и приложение.
- Настройка публичного доступа: * Перейдите на вкладку «Разрешения» в настройках хранилища.
- Добавьте субъект allUsers .
- Назначьте роль « Просмотрщик объектов хранилища» (чтобы все могли видеть фотографии) и роль « Создатель объектов хранилища» (для целей загрузки демонстрационных файлов).
Альтернативный вариант (служебная учетная запись): Если вы предпочитаете не использовать публичный доступ, убедитесь, что служебной учетной записи вашего приложения предоставлен полный доступ к AlloyDB и необходимые роли хранилища для безопасного управления объектами.
Подводные камни и устранение неполадок
Региональный перетаскивание | Если ваша база данных находится в регионе |
Уникальность названия категории | Имена сегментов (bucket names) представляют собой глобальное пространство имен. Если вы попытаетесь присвоить своему сегменту имя |
Путаница между «создателем» и «зрителем» | Путаница с «Создателем» и «Просмотрщиком»: если вы добавите только «Просмотрщика», ваше приложение будет аварийно завершать работу, когда пользователь попытается добавить новый элемент, поскольку у него нет разрешения на запись в файл. Для этой конкретной демонстрационной конфигурации вам нужны оба параметра. |
6. Давайте создадим приложение.
Клонируйте этот репозиторий в свой проект, и давайте разберемся.
- Чтобы клонировать этот проект, в терминале Cloud Shell (в корневом каталоге или в любом другом месте, где вы хотите его создать) выполните следующую команду:
git clone https://github.com/AbiramiSukumaran/neighbor-loop
Это должно создать проект, и вы можете проверить это в редакторе 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, вы можете получить ошибку |
Защита от утечки ключей | Если вы случайно |
"Тайм-аут соединения" недействителен. | Вы использовали частный IP-адрес в файле .env, но пытаетесь подключиться извне VPC (например, с локального компьютера). Частные IP-адреса доступны только внутри сети Google Cloud. Переключитесь на публичный IP-адрес! |
Порт 5432 Предположение | Хотя 5432 — это стандартный порт PostgreSQL, AlloyDB иногда требует настройки определенных портов, если вы используете прокси-сервер аутентификации. Для этой лабораторной работы убедитесь, что вы добавляете :5432 в конец строки с адресами хоста. |
Привратник «Авторизованных сетей» | Даже если у вас есть публичный IP-адрес, AlloyDB откажет в подключении, если вы не добавили IP-адрес машины, на которой запущен код, в белый список. Решение: В настройках экземпляра AlloyDB добавьте 0.0.0.0/0 (только для временного тестирования !) или ваш конкретный IP-адрес в список авторизованных сетей. |
Сбой установления соединения SSL/TLS | AlloyDB предпочитает защищенные соединения. Если в вашем DATABASE_URL неправильно указан драйвер (например, используется pg8000 ), рукопожатие может завершиться неудачей без уведомления, что приведет к стандартной ошибке «База данных недоступна». |
Обмен "Основной пул против пула чтения" | Если вы случайно скопируете IP-адрес пула чтения вместо IP-адреса основного экземпляра, ваше приложение будет работать для поиска элементов, но завершится с ошибкой "Только для чтения" при попытке вывести список новых элементов. Всегда используйте IP-адрес основного экземпляра для операций записи. |
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")
)
Встраивание данных в базу данных в реальном времени
Одна из самых крутых особенностей AlloyDB — это возможность генерировать эмбеддинги, не выходя из контекста 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 решает эту проблему с помощью расширенного векторного поиска AlloyDB AI.
Используя расширение pgvector и оптимизированное хранилище AlloyDB, мы можем выполнять чрезвычайно быстрый поиск сходства. Но настоящая «магия» происходит, когда мы объединяем векторную близость с логикой на основе LLM.
AlloyDB AI позволяет нам вызывать такие модели, как Gemini, непосредственно в наших SQL-запросах. Это означает, что мы можем выполнить семантическое обнаружение, включающее логическую «проверку на корректность» с помощью функции ai.if():
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
AND ai.if(
prompt => 'Does this text: "' || bio ||'" match the user request: "' || :query || '", at least 60%? "',
model_id => 'gemini-3-flash-preview'
)
ORDER BY score DESC
LIMIT 5
Этот запрос представляет собой серьёзный архитектурный сдвиг: мы переносим логику в данные. Вместо того чтобы извлекать тысячи результатов в код приложения для их фильтрации, Gemini 3 Flash выполняет «проверку на соответствие» внутри механизма базы данных. Это снижает задержку, уменьшает затраты на исходящий трафик и гарантирует, что результаты не просто математически похожи, но и контекстно релевантны.
Цикл "Проведите пальцем для совпадения"
Пользовательский интерфейс представляет собой классическую колоду карт.
Проведите пальцем влево: Отменить.
Проведите пальцем вправо: Совпадение!
При свайпе вправо бэкэнд записывает взаимодействие в нашу таблицу свайпов и помечает товар как соответствующий. Фронтенд мгновенно запускает модальное окно с контактной информацией поставщика, чтобы вы могли договориться о самовывозе.
8. Давайте развернем его в Cloud Run.
- Разверните проект в Cloud Run, выполнив следующую команду в терминале Cloud Shell, куда клонирован проект, и убедитесь, что вы находитесь в корневой папке проекта .
Выполните следующую команду в терминале Cloud Shell:
gcloud beta run deploy neighbor-loop \
--source . \
--region=us-central1 \
--network=<<YOUR_NETWORK_NAME>> \
--subnet=<<YOUR_SUBNET_NAME>> \
--allow-unauthenticated \
--vpc-egress=all-traffic \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:<<PORT>>/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Замените значения для заполнителей <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
После завершения выполнения команды она выведет URL-адрес сервиса. Скопируйте его.
- Предоставьте учетной записи службы Cloud Run роль клиента AlloyDB. Это позволит вашему бессерверному приложению безопасно подключаться к базе данных через туннель.
Выполните следующую команду в терминале Cloud Shell:
# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"
Теперь используйте URL-адрес сервиса (конечная точка Cloud Run, которую вы скопировали ранее) и протестируйте приложение. Загрузите фотографию старого электроинструмента, и Gemini сделает все остальное!
Подводные камни и устранение неполадок
Цикл "Редактирование не удалось" | Если развертывание завершилось успешно, но URL-адрес выдает |
Роль "тени" в системе IAM | Даже если у вас есть разрешение на развертывание, учетной записи службы Cloud Run (обычно |
9. Устранение неполадок высокого уровня
10. Демонстрация
Вы сможете использовать свою конечную точку для проведения тестов.
Но в демонстрационных целях, на несколько дней, вы можете поэкспериментировать с этим:
11. Уборка
После завершения этой лабораторной работы не забудьте удалить кластер и экземпляр AlloyDB.
Это должно привести к очистке кластера вместе с его экземплярами.
12. Поздравляем!
Вы успешно создали приложение Neighbor Loop для устойчивых сообществ с помощью Google Cloud. Перенеся логику встраивания и Flash AI Gemini 3 в AlloyDB , приложение работает невероятно быстро (в зависимости от настроек развертывания), а код отличается исключительной чистотой. Мы храним не просто данные — мы храним намерения .
Сочетание скорости Gemini 3 Flash и оптимизированной векторной обработки AlloyDB — это поистине новый рубеж для платформ, управляемых сообществом.