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

1. Обзор

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

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

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

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

2. Требования

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

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

  1. Войдите в консоль Google Cloud.
  2. Включите оплату в Cloud Console.
  3. Создайте новый проект или выберите существующий.
  4. Убедитесь, что платежные функции включены в разделе My projects (Мои проекты) в 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. Если терминал не появился внизу экрана, откройте его:
    • Нажмите на значок меню в виде трех горизонтальных полосок Значок меню в виде трех полосок.
    • Выберите Терминал.
    • Нажмите New Terminal (Новый терминал).Открыть новый терминал в редакторе 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. Напишите код

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

  1. Перейдите в домашний каталог:
    cd ~
    
  2. Создайте каталог codelab-genai:
    mkdir codelab-genai
    
  3. Перейдите в каталог codelab-genai:
    cd codelab-genai
    
  4. Создайте файл main.py:
    touch main.py
    
  5. Создайте файл requirements.txt со списком зависимостей:
    cat > requirements.txt << EOF
    Flask==3.0.0
    gunicorn==20.1.0
    EOF
    
  6. Откройте файл main.py в редакторе Cloud Shell:
    cloudshell edit main.py
    
    В верхней части экрана появится пустой файл. Здесь вы можете изменить файл main.py. Покажите, что код вводится в верхней части экрана.
  7. Скопируйте следующий код и вставьте его в открытый файл main.py:
    import os
    
    from flask import Flask
    
    app = Flask(__name__)
    
    @app.route("/")
    def hello_world():
        return f"Hello world!"
    
    
    if __name__ == "__main__":
        app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
    
    Через несколько секунд редактор Cloud Shell автоматически сохранит ваш код. Этот код отвечает на 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. What is your preferred protocol for Git operations on this host? HTTPS
    3. Как выполнить аутентификацию Git с помощью учетных данных GitHub? Y (Пропустите этот шаг, если такого варианта нет.)
    4. How would you like to authenticate GitHub CLI? Login with a web browser
    5. Скопируйте одноразовый код
    6. Откройте страницу https://github.com/login/device.
    7. Вставьте одноразовый код
    8. Нажмите Authorize github (Авторизовать 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/main.py \n\n"

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

  1. Не закрывайте вкладку редактора Cloud Shell. Мы вернемся к этой вкладке позже.
  2. В новой вкладке откройте страницу Cloud Run.
  3. Выберите нужный проект Google Cloud в консоли Раскрывающийся список проектов в консоли Google Cloud.
  4. Нажмите CONNECT REPO (Подключить репозиторий).
  5. Нажмите SET UP WITH CLOUD BUILD (НАСТРОИТЬ С ПОМОЩЬЮ CLOUD BUILD).
    1. В качестве поставщика хранилища выберите GitHub.
      • Если вы не вошли в аккаунт GitHub в браузере, войдите в него, используя свои учетные данные.
    2. Нажмите Выполнить аутентификацию, а затем – Продолжить.
    3. После входа на странице Cloud Run появится сообщение Приложение GitHub не установлено ни в одном из ваших хранилищ.
    4. Нажмите кнопку INSTALL GOOGLE CLOUD BUILD (Установить Google Cloud Build).
      • На странице Installation Setup (Настройка установки) выберите Only select repositories (Только выбранные хранилища) и укажите хранилище codelab-genai, созданное с помощью CLI.
      • Нажмите Установить.
      • Примечание. Если у вас много хранилищ GitHub, загрузка может занять несколько минут.
    5. В качестве хранилища выберите your-user-name/codelab-genai.
      • Если хранилища нет, нажмите на ссылку Manage Connected Repositories (Управление подключенными хранилищами).
    6. В поле Branch (Ветвь) оставьте значение ^main$.
    7. Нажмите Go, Node.js, Python, Java, .NET Core, Ruby or PHP via Google Cloud's buildpacks (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, вы можете пропустить эти шаги.

  1. Перейдите в редактор Cloud Shell.
  2. Если терминал не появился внизу экрана, откройте его:
    • Нажмите на значок меню в виде трех горизонтальных полосок Значок меню в виде трех полосок.
    • Выберите Терминал.
    • Нажмите New Terminal (Новый терминал).Открыть новый терминал в редакторе 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. Добавьте зависимость Vertex AI SDK к существующим зависимостям:
    sed -i -e '$agoogle-cloud-aiplatform==1.59.0' requirements.txt
    
  4. Добавьте библиотеку google auth к существующим зависимостям:
    sed -i -e '$agoogle-auth==2.32.0' requirements.txt
    
  5. Повторно открыть main.py в редакторе Cloud Shell
    cloudshell edit main.py
    
  6. Замените код в файле main.py на следующий:
    import os
    
    from flask import Flask, request
    
    import google.auth
    import vertexai
    from vertexai.generative_models import GenerativeModel
    
    _, project = google.auth.default()
    
    app = Flask(__name__)
    
    @app.route("/")
    def hello_world():
        vertexai.init(project=project, location="us-central1")
        model = GenerativeModel("gemini-1.5-flash")
        animal = request.args.get("animal", "dog") 
        prompt = f"Give me 10 fun facts about {animal}. Return this as html without backticks."
        response = model.generate_content(prompt)
        return response.text
    
    if __name__ == "__main__":
        app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
    

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 и администрирование.
  2. Убедитесь, что существующий проект Google Cloud – это тот, в котором вы создаете приложение Cloud Run.
  3. В таблице Конфигурация журналов аудита доступа к данным найдите и выберите Vertex AI API в столбце "Сервис".
  4. На вкладке Log Types (Типы журналов) выберите типы журналов аудита доступа к данным 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. Нажмите Выполнить запрос.

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

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

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

  1. Повторно открыть main.py в редакторе Cloud Shell
    cloudshell edit ~/codelab-genai/main.py
    
  2. После строки import os (строка 1) добавьте следующие строки:
    import sys, json, logging
    
    class JsonFormatter(logging.Formatter):
        def format(self, record):
            json_log_object = {
                "severity": record.levelname,
                "message": record.getMessage(),
            }
            json_log_object.update(getattr(record, "json_fields", {}))
            return json.dumps(json_log_object)
    logger = logging.getLogger(__name__)
    sh = logging.StreamHandler(sys.stdout)
    sh.setFormatter(JsonFormatter())
    logger.addHandler(sh)
    logger.setLevel(logging.DEBUG)
    
    
    Эти строки изменяют форматирование журналов Python по умолчанию на структурированное форматирование JSON, которое можно использовать в Google Cloud.
  3. После строки, вызывающей model.generate_content(prompt) (строка 34), добавьте следующие строки:
        json_fields = {"prompt": prompt, "response": response.to_dict()}
        logger.debug("Content is generated", extra={"json_fields": json_fields})
    
    Этот код выводит структурированную информацию о создании контента в stdout, откуда она считывается агентом ведения журналов и передается в Cloud Logging.
  4. Снова откройте Cloud Shell и введите следующую команду, чтобы убедиться, что вы находитесь в правильном каталоге:
    cd ~/codelab-genai
    
  5. Зафиксируйте изменения:
    git commit -am "observe generated content"
    
  6. Отправьте изменения в 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. Чтобы избежать дополнительных расходов, вы можете удалить облачный проект. После удаления облачного проекта оплата за все ресурсы, используемые в нем, перестанет взиматься.

При желании удалите проект:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

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

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

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

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