Автоматическое развертывание веб-приложения Angular с генеративным ИИ из системы управления версиями в Cloud Run

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. Напишите свой код.

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

  1. Перейдите в домашний каталог: 
    cd ~
  2. Создайте новое Angular-приложение codelab-genai : 
    npx @angular/cli new codelab-genai \
    --minimal \
    --inline-template \
    --inline-style \
    --ssr \
    --defaults
  3. Если появится запрос на установку @angular/cli , нажмите Enter , чтобы продолжить: 
    Need to install the following packages:
@angular/cli@18.2.4
Ok to proceed? (y)
  4. Перейдите в каталог codelab-genai : 
    cd codelab-genai
  5. Откройте файл app.component.ts в редакторе Cloud Shell:
    cloudshell edit src/app/app.component.ts
    Теперь в верхней части экрана должен появиться пустой файл. Здесь вы можете редактировать файл app.component.ts . Покажите, что код размещается в верхней части экрана.
  6. Скопируйте следующий код и вставьте его в открытый файл app.component.ts :
    import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
    selector: 'app-root',
    standalone: true,
    imports: [RouterOutlet],
    template: `
        <h1>Hello world!</h1>

        <router-outlet />
    `,
    styles: [],
})
export class AppComponent { }
    Через несколько секунд редактор 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/src/app/app.component.ts \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. Откройте файл server.ts в редакторе Cloud Shell. 
    cloudshell edit server.ts
  6. Замените код в файле server.ts следующим: 
    // server.ts
import { APP_BASE_HREF } from '@angular/common';
import { CommonEngine } from '@angular/ssr';
import express from 'express';
import { fileURLToPath } from 'node:url';
import { dirname, join, resolve } from 'node:path';
import bootstrap from './src/main.server';

import { VertexAI } from '@google-cloud/vertexai';
import { GoogleAuth } from 'google-auth-library';


// The Express app is exported so that it can be used by serverless Functions.
export function app(): express.Express {
    const server = express();
    const serverDistFolder = dirname(fileURLToPath(import.meta.url));
    const browserDistFolder = resolve(serverDistFolder, '../browser');
    const indexHtml = join(serverDistFolder, 'index.server.html');
    const commonEngine = new CommonEngine();

    const auth = new GoogleAuth();

    server.set('view engine', 'html');
    server.set('views', browserDistFolder);

    // Example Express Rest API endpoints
    server.get('/api/facts', async (req, res) => {
        const project = await auth.getProjectId();

        const vertex = new VertexAI({ project: project });
        const generativeModel = vertex.getGenerativeModel({
            model: 'gemini-1.5-flash',
            generationConfig: { responseMimeType: 'application/json' }
        });

        const animal = req.query['animal'] || 'dog';
        const prompt = `Give me 10 fun facts about ${animal}. 
                        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);
        let factArray = '';

        if (resp.response.candidates) {
            factArray = JSON.parse(resp.response.candidates[0].content.parts[0].text || '');
        }
        res.send(factArray);
    });

    // Serve static files from /browser
    server.get('**', express.static(browserDistFolder, {
        maxAge: '1y',
        index: 'index.html',
    }));

    // All regular routes use the Angular engine
    server.get('**', (req, res, next) => {
        const { protocol, originalUrl, baseUrl, headers } = req;

        commonEngine
            .render({
                bootstrap,
                documentFilePath: indexHtml,
                url: `${protocol}://${headers.host}${originalUrl}`,
                publicPath: browserDistFolder,
                providers: [{ provide: APP_BASE_HREF, useValue: baseUrl }],
            })
            .then((html) => res.send(html))
            .catch((err) => next(err));
    });

    return server;
}

function run(): void {
    const port = process.env['PORT'] || 4000;

    // Start up the Node server
    const server = app();
    server.listen(port, () => {
        console.log(`Node Express server listening on http://localhost:${port}`);
    });
}

run();
  7. Откройте файл app.component.ts в редакторе Cloud Shell. 
    cloudshell edit src/app/app.component.ts
  8. Замените код в файле app.components.ts следующим: 
    // app.component.ts
import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { RouterOutlet } from '@angular/router';

@Component({
    selector: 'app-root',
    standalone: true,
    imports: [RouterOutlet, FormsModule],
    template: `
        <section>
            <input
                type="text"
                placeholder="dog"
                [(ngModel)]="animal"
                class="text-black border-2 p-2 m-2 rounded"
            />
            <button
                (click)="getNewFunFacts()"
            >
                Get New Fun Facts
            </button>
            <ol>
                @for(fact of facts(); track fact) {
                    <li>{{fact}}</li>  
                } @empty {
                    <li>No facts are available</li>
                }
            </ol>
        </section>
    `,
    styles: '',
})
export class AppComponent {
    animal = '';
    facts = signal<string[]>([]);

    getNewFunFacts() {
        fetch(`/api/facts?animal=${this.animal}`).then(response => response.json()).then(facts => {
            this.facts.set(facts);
        });
    }
}

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. Откройте файл server.ts в редакторе Cloud Shell. 
    cloudshell edit ~/codelab-genai/server.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 для автоматического развертывания приложения при внесении изменений в исходный код. Затем вы модифицировали приложение и развернули его снова.

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

Если вас интересует участие в исследовании пользовательского опыта (UX) для улучшения продуктов, с которыми вы работаете сегодня, зарегистрируйтесь здесь .

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