Автоматическое развертывание веб-приложения Generative AI Go из системы контроля версий в облако Run

1. Обзор

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

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

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

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

• Добавьте генеративный ИИ в свое приложение с помощью Vertex AI

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

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

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

1. Войдите в Google Cloud Console .
2. Включите выставление счетов в Cloud Console.
   • Выполнение этой лабораторной работы обойдется менее чем в 1 доллар США в виде облачных ресурсов.
   • Вы можете следовать инструкциям в конце этой лабораторной работы, чтобы удалить ресурсы и избежать дальнейших расходов.
   • Новые пользователи имеют право на бесплатную пробную версию стоимостью 300 долларов США .
   • Планируете мероприятие Gen AI for Devs? Возможно, вам будет доступен кредит в размере 1 доллара США .
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. Если терминал не отображается внизу экрана, откройте его:
   • Нажмите на меню гамбургера.
   • Нажмите «Терминал»
   • Нажмите «Новый терминал».
3. В терминале настройте свой проект с помощью этой команды:
   • Формат:

     gcloud config set project [PROJECT_ID]
     

   • Пример:

     gcloud config set project lab-project-id-example
     

   • Если вы не можете вспомнить идентификатор своего проекта:
     • Вы можете вывести список всех идентификаторов своих проектов с помощью:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Если будет предложено авторизоваться, нажмите «Авторизовать» , чтобы продолжить.
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 "[e-mail]"
   

2. Задайте глобальное имя пользователя git:

   git config --global user.name "Your Name"
   

3. Установите глобальную ветку git по умолчанию на main :

   git config --global init.defaultBranch main
   

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

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

1. Перейдите в домашний каталог:

   cd ~
   

2. Создайте каталог codelab-genai :

   mkdir codelab-genai
   

3. Перейдите в каталог codelab-genai :

   cd codelab-genai
   

4. Инициализируем файл go.mod для объявления нашего модуля:

   go mod init codelab-genai
   

5. Создайте файл main.go :

   touch main.go
   

6. Откройте файл main.go в редакторе Cloud Shell:

   cloudshell edit main.go
   

   В верхней части экрана должен появиться пустой файл. Здесь вы можете редактировать файл main.go
7. Отредактируйте main.go и вставьте в него следующий код:

   package main
   
   import (
       "fmt"
       "log"
       "net/http"
       "os"
   )
   
   func main() {
       http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
           fmt.Fprintln(w, "Hello, world!")
       })
   
       port := os.Getenv("PORT")
   
       if port == "" {
           port = "8080"
       }
       if err := http.ListenAndServe(":"+port, nil); err != nil {
           log.Fatal(err)
       }
   }
   

   Через несколько секунд 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 , у вас есть два варианта продолжить работу с этим руководством:
   • Удалить существующий репозиторий GitHub
   • Создайте репозиторий с другим именем и не забудьте изменить его в следующих командах.
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/main.go \n\n"

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

1. Оставьте вкладку «Редактор Cloud Shell» открытой. Мы вернёмся к этой вкладке позже.
2. В новой вкладке откройте страницу Cloud Run .
3. Выберите правильный проект Google Cloud в консоли.
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. Измените свой код

1. Вернитесь к терминалу Cloud Shell в нижней части экрана.
2. Убедитесь, что вы все еще находитесь в правильном каталоге:

   cd ~/codelab-genai
   

3. Повторно откройте main.go в редакторе Cloud Shell.

   cloudshell edit main.go
   

4. Установите Vertex AI SDK для Go:

   go get cloud.google.com/go/vertexai/genai
   

5. Установите библиотеку метаданных для Go, чтобы получить текущий идентификатор проекта:

   go get cloud.google.com/go/compute/metadata
   

6. Замените код в файле main.go на:

   package main
   
   import (
       "context"
       "fmt"
       "log"
       "net/http"
       "os"
   
       "cloud.google.com/go/compute/metadata"
       "cloud.google.com/go/vertexai/genai"
   )
   
   func main() {
       ctx := context.Background()
       var projectId string
       var err error
       projectId = os.Getenv("GOOGLE_CLOUD_PROJECT")
       if projectId == "" {
           projectId, err = metadata.ProjectIDWithContext(ctx)
           if err != nil {
               return
           }
       }
       var client *genai.Client
       client, err = genai.NewClient(ctx, projectId, "us-central1")
       if err != nil {
           return
       }
       defer client.Close()
   
       model := client.GenerativeModel("gemini-1.5-flash-001")
   
       http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
           animal := r.URL.Query().Get("animal")
           if animal == "" {
               animal = "dog"
           }
   
           resp, err := model.GenerateContent(
               ctx,
               genai.Text(
                   fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)),
           )
   
           if err != nil {
               w.WriteHeader(http.StatusServiceUnavailable)
               return
           }
   
           if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
               htmlContent := resp.Candidates[0].Content.Parts[0]
               w.Header().Set("Content-Type", "text/html; charset=utf-8")
               fmt.Fprint(w, htmlContent)
           }
       })
   
       port := os.Getenv("PORT")
   
       if port == "" {
           port = "8080"
       }
       if err := http.ListenAndServe(":"+port, nil); err != nil {
           log.Fatal(err)
       }
   }
   

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 :
   Перейти к Log Explorer
   
3. В окне запроса введите:

   LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
   protoPayload.serviceName="aiplatform.googleapis.com"
   

4. Нажмите Выполнить запрос .

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

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

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

1. Повторно откройте main.go в редакторе Cloud Shell.

   cloudshell edit ~/codelab-genai/main.go
   

2. Измените блок импорта, включив в него структурированное ведение журнала Go и библиотеки JSON:

   import (
       "context"
       "encoding/json"
       "fmt"
       "log"
       "log/slog"
       "net/http"
       "os"
   
       "cloud.google.com/go/compute/metadata"
       "cloud.google.com/go/vertexai/genai"
   )
   

3. После инициализации клиента Vertex (строка 33) добавьте следующие строки для инициализации структурированного регистратора, который использует правильные поля для Google Cloud Logging:

   opts := &slog.HandlerOptions{
   	Level: slog.LevelDebug,
   	ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
           if a.Key == slog.LevelKey {
               return slog.Attr{Key: "severity", Value: a.Value}
           }
           if a.Key == slog.MessageKey {
               return slog.Attr{Key: "message", Value: a.Value}
           }
           return slog.Attr{Key: a.Key, Value: a.Value}
   	},
   }
   
   jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
   slog.SetDefault(slog.New(jsonHandler))
   

4. После проверки ответа GenerateContent (строка 69) добавьте следующие строки внутрь блока if:

   jsonBytes, err := json.Marshal(resp)
   if err != nil {
       slog.Error("Failed to marshal response to JSON", "error", err)
   } else {
       jsonString := string(jsonBytes)
       slog.Debug("Complete response content", "json_response", jsonString)
   }
   

   Этот код записывает в stdout информацию о сгенерированном контенте, используя структурированный формат логирования . Агент логирования в Cloud Run перехватывает выводимые в stdout данные и записывает их в Cloud Logging.
5. Снова откройте Cloud Shell и введите следующую команду, чтобы убедиться, что вы находитесь в правильном каталоге:

   cd ~/codelab-genai
   

6. Зафиксируйте изменения:

   git commit -am "Observe generated content"
   

7. Отправьте изменения на GitHub, чтобы запустить повторное развертывание измененной версии:

   git push
   

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

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

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

   LOG_ID("run.googleapis.com%2Fstdout")
   severity=DEBUG
   

3. Нажмите Выполнить запрос .

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

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

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

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

Если хотите, удалите проект:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Вы также можете удалить ненужные ресурсы с диска CloudShell. Вы можете:

1. Удалить каталог проекта codelab:

   rm -rf ~/codelab-genai
   

2. Удалите все пакеты go, которые вам больше не нужны:

   cd ~
   go clean -modcache
   

3. Внимание! Это действие необратимо! Если вы хотите удалить всё из Cloud Shell, чтобы освободить место, вы можете удалить весь домашний каталог . Убедитесь, что всё, что вы хотите сохранить, сохранено где-то ещё.

   sudo rm -rf $HOME
   

16. Поздравления

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

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

• Питон
• Node.js
• Идти
• Ява
• Угловой
• Next.js

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

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

• Документация: используйте Genkit как гибкую абстракцию модели, которая упрощает интеграцию любого API модели и использование поддерживаемых сообществом моделей.
• Codelab: Как развернуть чат-приложение на базе Gemini в Cloud Run
• Как использовать вызов функций Gemini с помощью Cloud Run
• Семинар по запросу: Google Kubernetes Engine Onboard
• Как использовать API Cloud Run Jobs Video Intelligence для обработки видео по сценам