Автоматическое развертывание веб-приложения Next.js с генеративным искусственным интеллектом из системы контроля версий в облако

1. Обзор

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

В этой лабораторной работе вы напишете веб-приложение и настроите Cloud Run для автоматического развертывания вашего приложения при внесении изменений в исходный код. Затем вы внесете изменения в приложение и снова его развернете.

Что вы узнаете

  • Напишите веб-приложение с помощью редактора Cloud Shell.
  • Сохраняйте код своего приложения на GitHub.
  • Автоматически разверните ваше приложение в Cloud Run.
  • Внедрите генеративный ИИ в свое приложение с помощью Vertex AI.

2. Предварительные требования

  1. Если у вас еще нет учетной записи Google, вам необходимо ее создать .
    • Используйте личный аккаунт вместо рабочего или учебного. Рабочие и учебные аккаунты могут иметь ограничения, которые не позволят вам включить API, необходимые для этой лабораторной работы.
  2. Если у вас еще нет учетной записи GitHub, вам необходимо ее создать.

3. Настройка проекта

  1. Войдите в консоль Google Cloud .
  2. Включите выставление счетов в облачной консоли.
    • Выполнение этой лабораторной работы должно обойтись менее чем в 1 доллар США в виде облачных ресурсов.
    • В конце этой лабораторной работы вы можете выполнить действия по удалению ресурсов, чтобы избежать дальнейших списаний средств.
    • Новые пользователи могут воспользоваться бесплатной пробной версией стоимостью 300 долларов США .
    • Собираетесь посетить мероприятие Gen AI for Devs? Возможно, вам будет предоставлен кредит в размере 1 доллара США .
  3. Создайте новый проект или выберите вариант повторного использования существующего проекта.
  4. Подтвердите, что выставление счетов включено в разделе «Мои проекты» в Cloud Billing.
    • Если в столбце Billing account Billing is disabled :
      1. Нажмите на три точки в столбце Actions .
      2. Нажмите «Изменить оплату».
      3. Выберите платежный аккаунт, который вы хотите использовать.
    • Если вы посещаете мероприятие Gen AI for Devs, ваша учетная запись, скорее всего, будет называться Google Cloud Platform Trial Billing Account.

4. Откройте редактор Cloud Shell.

  1. Перейдите в редактор Cloud Shell.
  2. Если терминал не отображается в нижней части экрана, откройте его:
    • Нажмите на значок гамбургера. значок меню "гамбургер"
    • Нажмите «Терминал»
    • Нажмите «Новый терминал» Откройте новый терминал в редакторе Cloud Shell.
  3. В терминале настройте свой проект с помощью этой команды:
    • Формат: 
      gcloud config set project [PROJECT_ID]
    • Пример: 
      gcloud config set project lab-project-id-example
    • Если вы не помните идентификатор своего проекта:
      • Вы можете вывести список всех идентификаторов ваших проектов с помощью: 
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Установите идентификатор проекта в терминале редактора Cloud Shell.
  4. Если появится запрос на авторизацию, нажмите «Авторизовать» , чтобы продолжить. Нажмите, чтобы авторизовать Cloud Shell.
  5. Вы должны увидеть следующее сообщение:
    Updated property [core/project].
    Если вы видите WARNING и вас спрашивают Do you want to continue (Y/N)? , то, скорее всего, вы неправильно ввели идентификатор проекта. Нажмите N , затем Enter и попробуйте снова выполнить команду gcloud config set project .

5. Включите API.

В терминале включите API:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

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

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Настройка Git

  1. Укажите адрес электронной почты вашего глобального пользователя Git: 
    git config --global user.email "you@example.com"
  2. Укажите ваше глобальное имя пользователя Git: 
    git config --global user.name "Your Name"
  3. Установите глобальную ветку по умолчанию в Git на main : 
    git config --global init.defaultBranch main

7. Напишите свой код.

Чтобы написать приложение на Next.js:

  1. Перейдите в домашний каталог: 
    cd ~
  2. Создайте новое приложение codelab-genai Next.js: 
    npx create-next-app@latest codelab-genai \
    --ts \
    --eslint \
    --tailwind \
    --no-src-dir \
    --app \
    --no-import-alias
  3. Если появится запрос на установку create-next-app , нажмите Enter , чтобы продолжить: 
    Need to install the following packages:
create-next-app@14.2.14
Ok to proceed? (y)
  4. Перейдите в каталог codelab-genai : 
    cd codelab-genai
  5. Откройте файл page.tsx в редакторе Cloud Shell:
    cloudshell edit app/page.tsx
    Теперь в верхней части экрана должен появиться файл. Здесь вы можете редактировать файл page.tsx . Покажите, что код размещается в верхней части экрана.
  6. Удалите существующий код. Скопируйте следующий код и вставьте его в открытый файл page.tsx :
    import React from "react";

export default function Home() {
return (
    <main>
        Hello World!
    </main>
);
}
    Через несколько секунд редактор Cloud Shell автоматически сохранит ваш код. Этот код отвечает на HTTP-запросы нашим приветствием "Hello world!".

Исходный код вашего приложения готов и может быть сохранен в системе контроля версий.

8. Создайте репозиторий.

  1. Вернитесь к терминалу Cloud Shell в нижней части экрана.
  2. Убедитесь, что вы по-прежнему находитесь в правильной директории: 
    cd ~/codelab-genai
  3. Инициализируйте свой репозиторий Git. 
    git init -b main
  4. Войдите в интерфейс командной строки GitHub.
    gh auth login
    Нажмите Enter , чтобы принять параметры по умолчанию, и следуйте инструкциям в инструменте командной строки GitHub, включая:
    1. В какой учетной записи вы хотите войти? GitHub.com
    2. Какой протокол вы предпочитаете использовать для операций Git на этом хосте? HTTPS
    3. Аутентифицировать Git с помощью учетных данных GitHub? Y (Пропустите, если этот пункт не отображается.)
    4. Как вы хотите авторизоваться в GitHub CLI? Login with a web browser
    5. Скопируйте свой одноразовый код
    6. Откройте https://github.com/login/device
    7. Вставьте свой одноразовый код
    8. Нажмите «Авторизовать GitHub»
    9. Завершите вход в систему.
  5. Подтвердите, что вы вошли в систему:
    gh api user -q ".login"
    Если вы успешно вошли в систему, отобразится ваше имя пользователя на GitHub.
  6. Создайте переменную GITHUB_USERNAME 
    GITHUB_USERNAME=$(gh api user -q ".login")
  7. Убедитесь, что вы создали переменную среды:
    echo ${GITHUB_USERNAME}
    Если вы успешно создали переменную, то в результате должно отобразиться ваше имя пользователя на GitHub.
  8. Создайте пустой репозиторий GitHub с именем codelab-genai :
    gh repo create codelab-genai --private
    Если вы получили ошибку:
    GraphQL: Name already exists on this account (createRepository)
    Значит, у вас уже есть репозиторий с именем codelab-genai . Для продолжения выполнения этого руководства у вас есть два варианта:
  9. Добавьте репозиторий codelab-genai в качестве удаленного origin : 
    git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9. Поделитесь своим кодом

  1. Убедитесь, что вы находитесь в правильной директории: 
    cd ~/codelab-genai
  2. Добавьте все файлы из текущего каталога в этот коммит: 
    git add .
  3. Создайте первый коммит: 
    git commit -m "add http server"
  4. Отправьте свой коммит в main ветку репозитория origin : 
    git push -u origin main

Вы можете выполнить эту команду и перейти по полученному URL-адресу, чтобы просмотреть код своего приложения на GitHub: 

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/app/page.tsx \n\n"

10. Настройте автоматическое развертывание.

  1. Оставьте вкладку «Редактор Cloud Shell» открытой. Мы вернемся к этой вкладке позже.
  2. В новой вкладке перейдите на страницу Cloud Run .
  3. Выберите нужный проект Google Cloud в консоли. Выпадающее меню проекта Google Cloud Console
  4. Нажмите ПОДКЛЮЧИТЬ РЕПОЗИТОРИЙ
  5. Нажмите «НАСТРОЙКА С ПОМОЩЬЮ CLOUD BUILD».
    1. Выберите GitHub в качестве поставщика репозитория.
      • Если вы не вошли в свою учетную запись GitHub в браузере, войдите, используя свои учетные данные.
    2. Нажмите «Аутентифицировать» , а затем « Продолжить» .
    3. После входа в систему на странице Cloud Run вы увидите сообщение о том, что приложение GitHub не установлено ни в одном из ваших репозиториев.
    4. Нажмите на кнопку «УСТАНОВИТЬ GOOGLE CLOUD BUILD» .
      • На странице «Настройка установки» выберите «Выбрать только репозитории» и выберите репозиторий codelab-genai , который вы создали через CLI.
      • Нажмите «Установить».
      • Примечание: Если у вас много репозиториев GitHub, загрузка может занять несколько минут.
    5. Выберите your-user-name/codelab-genai в качестве репозитория.
      • Если репозиторий отсутствует, нажмите ссылку «Управление подключенными репозиториями» .
    6. Оставить ветку как ^main$
    7. Используйте Go, Node.js, Python, Java, .NET Core, Ruby или PHP через buildpacks от Google Cloud.
      • Остальные поля ( Build context directory , Entrypoint и Function target ) оставьте без изменений.
    8. Нажмите «Сохранить».
  6. Прокрутите вниз до раздела «Аутентификация» .
  7. Нажмите «Разрешить неаутентифицированные вызовы».
  8. Нажмите СОЗДАТЬ

После завершения сборки (что займет несколько минут) выполните эту команду и перейдите по полученному URL-адресу, чтобы просмотреть запущенное приложение: 

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. Измените свой код

Вернуться в редактор Cloud Shell

Если у вас все еще открыт редактор Cloud Shell, вы можете пропустить эти шаги.

  1. Перейдите в редактор Cloud Shell.
  2. Если терминал не отображается в нижней части экрана, откройте его:
    • Нажмите на значок гамбургера. значок меню "гамбургер"
    • Нажмите «Терминал»
    • Нажмите «Новый терминал» Откройте новый терминал в редакторе Cloud Shell.
  3. В терминале настройте свой проект с помощью этой команды:
    • Формат: 
      gcloud config set project [PROJECT_ID]
    • Пример: 
      gcloud config set project lab-project-id-example
    • Если вы не помните идентификатор своего проекта:
      • Вы можете вывести список всех идентификаторов ваших проектов с помощью: 
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Установите идентификатор проекта в терминале редактора Cloud Shell.
  4. Если появится запрос на авторизацию, нажмите «Авторизовать» , чтобы продолжить. Нажмите, чтобы авторизовать Cloud Shell.
  5. Вы должны увидеть следующее сообщение:
    Updated property [core/project].
    Если вы видите WARNING и вас спрашивают Do you want to continue (Y/N)? , то, скорее всего, вы неправильно ввели идентификатор проекта. Нажмите N , затем Enter и попробуйте снова выполнить команду gcloud config set project .

Добавьте Vertex AI в свое приложение.

  1. Вернитесь к терминалу Cloud Shell в нижней части экрана.
  2. Убедитесь, что вы по-прежнему находитесь в правильной директории: 
    cd ~/codelab-genai
  3. Установите Node.js Vertex AI SDK: 
    npm install @google-cloud/vertexai
  4. Установите Node.js Google Auth SDK: 
    npm install google-auth-library
  5. Создайте файл app/actions.ts в терминале. 
    touch app/actions.ts
  6. Откройте actions.ts в редакторе Cloud Shell. 
    cloudshell edit app/actions.ts
  7. Скопируйте следующий код и вставьте его в открытый файл actions.ts : 
    'use server'

import { VertexAI } from '@google-cloud/vertexai';
import { GoogleAuth } from 'google-auth-library';
const auth = new GoogleAuth();

export async function getFunFactsAction(animal: string) {
    const project = await auth.getProjectId();

    const vertex = new VertexAI({ project: project });
    const generativeModel = vertex.getGenerativeModel({
        model: 'gemini-1.5-flash'
    });

    const prompt = `Give me 10 fun facts about ${animal || 'dog'}. 
            Return as json as an array in the format ['fact 1', 'fact 2']
            Remove backticks and other markdown formatting.`;
    const resp = await generativeModel.generateContent(prompt);

    if (!resp.response.candidates) {
        throw new Error('Did not receive response candidates.')
    }

    console.log({ text: resp.response.candidates[0].content.parts[0].text })

    const factArray = JSON.parse(resp.response.candidates[0].content.parts[0].text || '');
    return factArray;
};
  8. Откройте page.tsx в редакторе Cloud Shell. 
    cloudshell edit ~/codelab-genai/app/page.tsx
  9. Замените код в файле page.tsx следующим: 
    'use client'

import React, { useState } from "react";
import { getFunFactsAction } from "./actions";

export default function Home() {
    const [animal, setAnimal] = useState('');
    const [funFacts, setFunFacts] = useState<string[]>([]);
    async function getNewFunFacts() {
        const funFacts = await getFunFactsAction(animal);
        setFunFacts(funFacts);
    }
    return (
        <main>
            <h1 className="text-xl">Animal Fun Facts!</h1>
            <label className="text-lg p-2 m-2">Animal</label>
            <input
                placeholder="dog"
                value={animal}
                onChange={(e) => setAnimal(e.target.value)}
                className="text-black border-2 p-2 m-2 rounded"
            />
            <button
                onClick={getNewFunFacts}
                className="font-bold border-2 p-2 m-2 rounded hover:bg-white hover:text-black"
            >
                Get New Fun Facts
            </button>
            <ul className="list-disc list-inside">
                {funFacts.map(function (thing) {
                    return <li key={thing}>{thing}</li>
                })}
            </ul>
        </main>
    );
}

12. Передислокация

  1. Убедитесь, что вы по-прежнему находитесь в правильной директории в Cloud Shell: 
    cd ~/codelab-genai
  2. Выполните следующие команды, чтобы добавить новую версию вашего приложения в локальный репозиторий Git: 
    git add .
git commit -m "add latest changes"
  3. Отправьте изменения в GitHub: 
    git push
  4. После завершения сборки выполните эту команду и откройте развернутое приложение: 
    echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

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

Историю всех изменений можно посмотреть здесь: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (Необязательно) Проведите аудит использования Vertex AI.

Как и в других сервисах Google Cloud, вы можете проводить аудит операций Vertex AI . Журналы аудита помогут вам ответить на вопросы: «Кто что сделал, где и когда?». Административные журналы аудита для Vertex AI включены по умолчанию. Чтобы проводить аудит запросов на генерацию контента, необходимо включить журналы аудита доступа к данным :

  1. В консоли Google Cloud перейдите на страницу «Журналы аудита» :

    Если вы воспользуетесь строкой поиска, чтобы найти эту страницу, выберите результат, подзаголовок которого — IAM & Admin .
  2. Убедитесь, что вы создаете приложение Cloud Run именно в том существующем проекте Google Cloud.
  3. В таблице конфигурации журналов аудита доступа к данным в столбце «Сервис» выберите Vertex AI API .
  4. На вкладке «Типы журналов» выберите типы журналов аудита доступа к данным: Admin read и Data read .
  5. Нажмите « Сохранить ».

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

  1. Вернитесь к развернутому приложению и обновите страницу, чтобы запустить запись в журнал.
  2. В консоли Google Cloud перейдите на страницу Log Explorer :

  3. В окне запроса введите: 
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"
  4. Нажмите « Выполнить запрос» .

Журналы аудита фиксируют использование API Vertex AI, но они не позволяют отслеживать данные, связанные с рабочей нагрузкой, такие как подсказки или подробности ответов.

14. (Необязательно) Повысьте наблюдаемость вашей рабочей нагрузки ИИ.

Журналы аудита не фиксируют информацию, связанную с рабочей нагрузкой. Для повышения наблюдаемости ваших рабочих нагрузок необходимо явно регистрировать эту информацию. Для этого можно использовать любую удобную систему логирования. Следующие шаги демонстрируют, как это сделать с помощью встроенного механизма логирования Node.js.

  1. Откройте файл actions.ts в редакторе Cloud Shell. 
    cloudshell edit ~/codelab-genai/app/actions.ts
  2. После вызова метода await generativeModel.generateContent(prompt) (строка 19) добавьте следующую строку:
        console.log(JSON.stringify({
        severity: 'DEBUG',
        message: 'Content is generated',
        prompt: prompt,
        response: resp.response,
    }));
    Этот код записывает в stdout информацию о сгенерированном контенте, используя структурированный формат логирования . Агент логирования в Cloud Run перехватывает вывод, отображаемый в stdout , и записывает этот формат в Cloud Logging.
  3. Откройте Cloud Shell заново и введите следующую команду, чтобы убедиться, что вы находитесь в правильном каталоге: 
    cd ~/codelab-genai
  4. Подтвердите изменения: 
    git commit -am "observe generated content"
  5. Отправьте изменения в GitHub, чтобы запустить повторное развертывание измененной версии: 
    git push

После развертывания новой версии вы сможете просмотреть отладочную информацию о вызовах к Vertex AI.

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

  1. В консоли Google Cloud перейдите на страницу Log Explorer :

  2. В окне запроса введите: 
    LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG
  3. Нажмите « Выполнить запрос» .

Результат запроса отображает журналы с запросом и ответом от Vertex AI, включая «рейтинги безопасности», которые можно использовать для мониторинга соблюдения правил техники безопасности.

15. (Необязательно) Уборка

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

При желании вы можете удалить проект: 

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Вы также можете удалить ненужные ресурсы с диска Cloudshell. Для этого выполните следующие действия:

  1. Удалите каталог проекта codelab: 
    rm -rf ~/codelab-genai
  2. Внимание! Это действие необратимо! Если вы хотите удалить все данные в Cloud Shell, чтобы освободить место, вы можете удалить всю свою домашнюю директорию . Будьте внимательны и убедитесь, что все, что вы хотите сохранить, сохранено в другом месте. 
    sudo rm -rf $HOME

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

В этой лабораторной работе вы написали веб-приложение и настроили Cloud Run для автоматического развертывания приложения при внесении изменений в исходный код. Затем вы модифицировали приложение и развернули его снова.

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

Вот несколько вариантов для продолжения обучения: