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

1. Обзор

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

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

Чему вы научитесь

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

2. Предпосылки

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

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

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

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

  1. Перейдите в редактор Cloud Shell.
  2. Если терминал не отображается внизу экрана, откройте его:
    • Нажмите на меню гамбургера. Значок меню гамбургеров
    • Нажмите «Терминал»
    • Нажмите «Новый терминал». Откройте новый терминал в Cloud Shell Editor
  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 Editor
  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 Editor автоматически сохранит ваш код. Этот код отвечает на http-запросы нашим приветствием «Hello world!».

Ваш исходный код приложения завершен и готов к сохранению в системе контроля версий.

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

  1. Вернитесь к терминалу Cloud Shell в нижней части экрана.
  2. Убедитесь, что вы все еще находитесь в правильном каталоге: 
    cd ~/codelab-genai
  3. Инициализируйте свой git-репозиторий 
    git init -b main
  4. Войдите в GitHub CLI
    gh auth login
    Нажмите Enter , чтобы принять параметры по умолчанию, и следуйте инструкциям в инструменте GitHub CLI, включая:
    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. Нажмите «НАСТРОЙКА С ПОМОЩЬЮ ОБЛАЧНОГО СБОРА»
    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 через сборочные пакеты 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 Editor, вы можете пропустить эти шаги.

  1. Перейдите в редактор Cloud Shell.
  2. Если терминал не отображается внизу экрана, откройте его:
    • Нажмите на меню гамбургера. Значок меню гамбургеров
    • Нажмите «Терминал»
    • Нажмите «Новый терминал». Откройте новый терминал в Cloud Shell Editor
  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 Editor
  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. Убедитесь, что существующий проект Google Cloud — это тот проект, в котором вы создаете приложение Cloud Run.
  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 не взимает плату, когда сервис не используется, с вас может взиматься плата за хранение образа контейнера в Artifact Registry. Вы можете удалить свой проект 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) с целью улучшения продуктов, с которыми вы работали сегодня, зарегистрируйтесь здесь .

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