Интерактивная отладка с помощью Visual Studio Code

ОБЛАСТЬ ПРИМЕНЕНИЯ:Пакет SDK для Python azureml версии 1

Узнайте, как выполнять интерактивную отладку экспериментов, конвейеров и развертываний Машинного обучения Azure с помощью Visual Studio Code (VS Code) и debugpy.

Запуск и отладка экспериментов в локальной среде

Используйте расширение Машинное обучение Azure для проверки, запуска и отладки экспериментов машинного обучения перед их отправкой в облако.

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

Отладка эксперимента локально

Важно!

Перед запуском эксперимента в локальной среде убедитесь, что:

  • Docker запущен.
  • Параметр azureML.CLI Compatibility Mode в Visual Studio Code имеет значение 1.0, как указано в предварительных требованиях
  1. В VS Code откройте представление расширения Машинного обучения Azure.

  2. Разверните узел подписки, содержащий рабочую область. Если у вас ее еще нет, можно создать рабочую область машинного обучения Azure с помощью расширения.

  3. Разверните узел рабочей области.

  4. Щелкните правой кнопкой мыши узел Эксперименты и выберите Создать эксперимент. При появлении запроса введите имя для эксперимента.

  5. Разверните узел эксперименты, щелкните правой кнопкой мыши эксперимент, который необходимо запустить, и выберите команду Запустить эксперимент.

  6. Выберите в списке параметр Локально.

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

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

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

    1. Подготовка среды. Вы можете выбрать любой из машинное обучение Azure проверенного или создать свой собственный.
    2. Укажите имя файла сценария для выполнения. Путь задается относительно каталога, открытого в VS Code.
    3. Выберите, следует ли использовать набор данных Машинного обучения Azure. Вы можете создавать наборы данных машинного обучения Azure с помощью расширения.
    4. Debugpy требуется для подключения отладчика к контейнеру, выполняющему эксперимент. Чтобы добавить Debugpy в качестве зависимости, выберите Добавить Debugpy. В противном случае выберите Пропустить. Если вы не добавили debugpy в качестве зависимости, это запускает ваш эксперимент без подключения к отладчику.
    5. В редакторе откроется файл конфигурации, содержащий параметры конфигурации запуска. Если вы удовлетворены параметрами, выберите Отправить эксперимент. Кроме того, вы можете открыть палитру команд (Представление > Палитра команд) в строке меню и ввести команду AzureML: Submit experiment в текстовое поле.
  10. После отправки эксперимента создается образ Docker, содержащий скрипт, и конфигурации, указанные в конфигурации запуска.

    Когда начинается процесс сборки образа Docker, файловый поток 60_control_log.txt выводится в консоль вывода в VS Code.

    Примечание

    Первое создание образа Docker может занять несколько минут.

  11. После сборки образа появится запрос на запуск отладчика. Задайте точки останова в скрипте и нажмите кнопку запустить отладчик, когда будете готовы начать отладку. Это присоединяет отладчик VS Code к контейнеру, выполняющему эксперимент. Кроме того, в расширении Машинное обучение Azure наведите указатель мыши на узел для текущего запуска и щелкните значок воспроизведения, чтобы запустить отладчик.

    Важно!

    Для одного эксперимента нельзя использовать несколько сеансов отладки. Однако можно выполнить отладку двух или более экспериментов, используя несколько экземпляров VS Code.

На этом этапе вы сможете пошагово отлаживать код с помощью VS Code.

Если вы хотите отменить запуск в любой момент, щелкните правой кнопкой мыши узел выполнить и выберите команду Отменить запуск.

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

Совет

Образы Docker, использующие те же зависимости, определенные в вашей среде, используются повторно между запусками. Однако при запуске эксперимента с помощью новой или другой среды создается новый образ. Так как эти образы сохраняются в локальном хранилище, рекомендуется удалить старые или неиспользуемые образы Docker. Чтобы удалить образы из системы, используйте Docker CLI или расширение VS Code Docker.

Отладка и устранение неполадок в конвейерах машинного обучения

В некоторых случаях может потребоваться интерактивная отладка кода Python, используемого в конвейере машинного обучения. С помощью VS Code и debugpy можно присоединяться к коду, как он выполняется в среде обучения.

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

  • Рабочая область машинного обучения Azure, настроенная для использования виртуальной сети Azure.

  • Конвейер машинного обучения Azure, использующий скрипты Python в рамках этапов конвейера. Например, PythonScriptStep.

  • Машинное обучение вычислительного кластера Azure, который находится в виртуальной сети и используется конвейером для обучения.

  • Среда разработки, которая находится в виртуальной сети. Средой разработки может быть одно из следующего:

    • Виртуальная машина Azure в виртуальной сети
    • Вычислительный экземпляр виртуальной машины записной книжки в виртуальной сети
    • Клиентский компьютер, имеющий подключение к виртуальной сети по частной сети либо по VPN, либо через ExpressRoute.

Дополнительные сведения об использовании виртуальной сети Azure с Машинным обучением Azure см. в статье Общие сведения об изоляции и конфиденциальности виртуальной сети.

Совет

Хотя вы можете работать с ресурсами Машинного обучения Azure, которые не находятся за виртуальной сетью, рекомендуется использовать виртуальную сеть.

Принцип работы

Этапы конвейера машинного обучения запускают скрипты Python. Эти скрипты изменяются для выполнения следующих действий:

  1. Регистрация IP-адреса узла, на котором они выполняются. Используйте IP-адрес для подключения отладчика к сценарию.

  2. Запустите компонент отладки debugpy и дождитесь подключения отладчика.

  3. В среде разработки вы отслеживаете журналы, созданные процессом обучения, чтобы найти IP-адрес, на котором выполняется сценарий.

  4. Вы указываете VS Code IP-адреса для подключения отладчика к с помощью launch.json файла.

  5. Вы подключаете отладчик и интерактивно пройдите по сценарию.

Настройка скриптов Python

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

  1. Добавьте в файл следующие операторы импорта:

    import argparse
    import os
    import debugpy
    import socket
    from azureml.core import Run
    
  2. Добавьте следующие аргументы. Эти аргументы позволяют включить отладчик по мере необходимости и задать время ожидания для подключения отладчика:

    parser.add_argument('--remote_debug', action='store_true')
    parser.add_argument('--remote_debug_connection_timeout', type=int,
                        default=300,
                        help=f'Defines how much time the Azure Machine Learning compute target '
                        f'will await a connection from a debugger client (VSCODE).')
    parser.add_argument('--remote_debug_client_ip', type=str,
                        help=f'Defines IP Address of VS Code client')
    parser.add_argument('--remote_debug_port', type=int,
                        default=5678,
                        help=f'Defines Port of VS Code client')
    
  3. Добавьте следующие операторы. Эти инструкции загружают текущий контекст выполнения, чтобы можно было зарегистрировать IP-адрес узла, на котором выполняется код:

    global run
    run = Run.get_context()
    
  4. Добавьте инструкцию if, запускающую debugpy, и дождитесь присоединения отладчика. Если отладчик не подключается до истечения времени ожидания, сценарий продолжится в нормальном режиме. Обязательно замените значения HOST и PORT в listen собственной функцией.

    if args.remote_debug:
        print(f'Timeout for debug connection: {args.remote_debug_connection_timeout}')
        # Log the IP and port
        try:
            ip = args.remote_debug_client_ip
        except:
            print("Need to supply IP address for VS Code client")
        print(f'ip_address: {ip}')
        debugpy.listen(address=(ip, args.remote_debug_port))
        # Wait for the timeout for debugger to attach
        debugpy.wait_for_client()
        print(f'Debugger attached = {debugpy.is_client_connected()}')
    

В следующем примере кода Python показан простой файл train.py, позволяющий выполнять отладку:

# Copyright (c) Microsoft. All rights reserved.
# Licensed under the MIT license.

import argparse
import os
import debugpy
import socket
from azureml.core import Run

print("In train.py")
print("As a data scientist, this is where I use my training code.")

parser = argparse.ArgumentParser("train")

parser.add_argument("--input_data", type=str, help="input data")
parser.add_argument("--output_train", type=str, help="output_train directory")

# Argument check for remote debugging
parser.add_argument('--remote_debug', action='store_true')
parser.add_argument('--remote_debug_connection_timeout', type=int,
                    default=300,
                    help=f'Defines how much time the Azure Machine Learning compute target '
                    f'will await a connection from a debugger client (VSCODE).')
parser.add_argument('--remote_debug_client_ip', type=str,
                    help=f'Defines IP Address of VS Code client')
parser.add_argument('--remote_debug_port', type=int,
                    default=5678,
                    help=f'Defines Port of VS Code client')

# Get run object, so we can find and log the IP of the host instance
global run
run = Run.get_context()

args = parser.parse_args()

# Start debugger if remote_debug is enabled
if args.remote_debug:
    print(f'Timeout for debug connection: {args.remote_debug_connection_timeout}')
    # Log the IP and port
    ip = socket.gethostbyname(socket.gethostname())
    # try:
    #     ip = args.remote_debug_client_ip
    # except:
    #     print("Need to supply IP address for VS Code client")
    print(f'ip_address: {ip}')
    debugpy.listen(address=(ip, args.remote_debug_port))
    # Wait for the timeout for debugger to attach
    debugpy.wait_for_client()
    print(f'Debugger attached = {debugpy.is_client_connected()}')

print("Argument 1: %s" % args.input_data)
print("Argument 2: %s" % args.output_train)

if not (args.output_train is None):
    os.makedirs(args.output_train, exist_ok=True)
    print("%s created" % args.output_train)

Настройка конвейера машинного обучения

Чтобы предоставить пакеты Python, необходимые для запуска debugpy и получения контекста выполнения, создайте среду и задайте pip_packages=['debugpy', 'azureml-sdk==<SDK-VERSION>']. Измените версию пакета SDK, чтобы она соответствовала используемой. В следующем фрагменте кода показано, как создать кластер AKS:

# Use a RunConfiguration to specify some additional requirements for this step.
from azureml.core.runconfig import RunConfiguration
from azureml.core.conda_dependencies import CondaDependencies
from azureml.core.runconfig import DEFAULT_CPU_IMAGE

# create a new runconfig object
run_config = RunConfiguration()

# enable Docker 
run_config.environment.docker.enabled = True

# set Docker base image to the default CPU-based image
run_config.environment.docker.base_image = DEFAULT_CPU_IMAGE

# use conda_dependencies.yml to create a conda environment in the Docker image for execution
run_config.environment.python.user_managed_dependencies = False

# specify CondaDependencies obj
run_config.environment.python.conda_dependencies = CondaDependencies.create(conda_packages=['scikit-learn'],
                                                                           pip_packages=['debugpy', 'azureml-sdk==<SDK-VERSION>'])

В разделе Настройка скриптов Python в скрипты, используемые этапами конвейера машинного обучения, были добавлены новые аргументы. В следующем фрагменте кода показано, как использовать эти аргументы, чтобы включить отладку для компонента и установить время ожидания. Здесь также показано, как использовать созданную ранее среду, задав runconfig=run_config:

# Use RunConfig from a pipeline step
step1 = PythonScriptStep(name="train_step",
                         script_name="train.py",
                         arguments=['--remote_debug', '--remote_debug_connection_timeout', 300,'--remote_debug_client_ip','<VS-CODE-CLIENT-IP>','--remote_debug_port',5678],
                         compute_target=aml_compute,
                         source_directory=source_directory,
                         runconfig=run_config,
                         allow_reuse=False)

При выполнении конвейера каждый шаг создает дочерний запуск. Если включена отладка, то измененный сценарий записывает в журнал сведения, аналогичные следующему тексту в 70_driver_log.txt для дочернего запуска:

Timeout for debug connection: 300
ip_address: 10.3.0.5

Сохраните значение ip_address. Они будут использоваться в следующем разделе.

Совет

Вы также можете найти IP-адрес из журналов выполнения для дочернего выполнения этого шага конвейера. Дополнительные сведения о просмотре этих сведений см. в статье Мониторинг выполнения экспериментов и метрик Машинного обучения Azure.

Настройка среды разработки

  1. Чтобы установить debugpy в среде разработки VS Code, используйте следующую команду:

    python -m pip install --upgrade debugpy
    

    Дополнительные сведения об использовании PTVSD в VS Code см. на этой странице.

  2. Чтобы настроить VS Code для взаимодействия с вычислителем Машинного обучения Azure, в котором работает отладчик, создайте новую конфигурацию отладки:

    1. В VS Code выберите меню Отладка, а затем щелкните Открыть конфигурации. Откроется файл с именем launch.json.

    2. В файле launch.json найдите строку, содержащую "configurations": [, и вставьте после нее следующий текст. Измените запись "host": "<IP-ADDRESS>" на IP-адрес, возвращенный в журналах из предыдущего раздела. Измените запись "localRoot": "${workspaceFolder}/code/step" на локальный каталог, содержащий копию отлаживаемого скрипта:

      {
          "name": "Azure Machine Learning Compute: remote debug",
          "type": "python",
          "request": "attach",
          "port": 5678,
          "host": "<IP-ADDRESS>",
          "redirectOutput": true,
          "pathMappings": [
              {
                  "localRoot": "${workspaceFolder}/code/step1",
                  "remoteRoot": "."
              }
          ]
      }
      

      Важно!

      Если в разделе конфигурации уже есть другие записи, добавьте запятую (,) после вставленного кода.

      Совет

      Рекомендуется, особенно для конвейеров, размещать ресурсы для скриптов в отдельных каталогах, чтобы код был важен только для каждого из шагов. В этом примере пример значения localRoot ссылается на /code/step1.

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

    3. Сохраните файл launch.json.

Подключение отладчика

  1. Откройте VS Code и откройте локальную копию скрипта.

  2. Задайте точки останова, где сценарий должен останавливаться после присоединения.

  3. Пока в дочернем процессе выполняется сценарий, а в журналах отображается Timeout for debug connection, используйте клавишу F5 или выберите параметр Отладка. При появлении запроса выберите конфигурациюAzure Machine Learning: Docker Debug (Машинное обучение Azure: отладка Docker). Можно также выбрать значок отладки на боковой панели, в раскрывающемся меню Отладка выберите машинное обучение Azure: Удаленная отладка, а затем с помощью зеленой стрелки присоединить отладчик.

    На этом этапе VS Code подключается к PTVSD внутри контейнера Docker и останавливается при достижении точки останова, заданной ранее. Теперь вы можете пошагово выполнять код, просматривать переменные и т. д.

    Примечание

    Если в журнале отображается запись Debugger attached = False, то время ожидания истекает, и скрипт продолжает работу без отладчика. Снова отправьте конвейер и подключите отладчик после сообщения Timeout for debug connection и до истечения времени ожидания.

Устранение неполадок развертываний

В некоторых случаях может потребоваться интерактивная отладка кода Python, содержащегося в развертывании модели. Например, если начальный сценарий не работает и причину невозможно определить с помощью дополнительного ведения журнала. Используя VS Code и debugpy, вы можете присоединить отладчик к коду, выполняющемуся внутри контейнера Docker.

Совет

Если вы используете управляемые сетевые конечные точки и развертывания локально, см. статью Отладка управляемых сетевых конечных точек локально в Visual Studio Code (предварительная версия) .

Важно!

Этот метод отладки не работает при использовании Model.deploy() и LocalWebservice.deploy_configuration для развертывания модели в локальной среде. В этом случае необходимо создать образ, используя метод Model.package().

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

Настройка среды разработки

  1. Чтобы установить debugpy в локальной среде разработки VS Code, используйте следующую команду:

    python -m pip install --upgrade debugpy
    

    Дополнительные сведения об использовании PTVSD в VS Code см. на этой странице.

  2. Чтобы настроить VS Code для взаимодействия с образом Docker, создайте новую конфигурацию отладки:

    1. В VS Code выберите меню Отладка в области выполнения, а затем выберите Открыть конфигурации. Откроется файл с именем launch.json.

    2. В файле launch.json найдите единицу "configurations" (строку, содержащую "configurations": [) и вставьте после нее следующий текст.

      {
          "name": "Azure Machine Learning Deployment: Docker Debug",
          "type": "python",
          "request": "attach",
          "connect": {
              "port": 5678,
              "host": "0.0.0.0",
          },
          "pathMappings": [
              {
                  "localRoot": "${workspaceFolder}",
                  "remoteRoot": "/var/azureml-app"
              }
          ]
      }
      

      После вставки launch.js файл должен выглядеть следующим образом:

      {
      // Use IntelliSense to learn about possible attributes.
      // Hover to view descriptions of existing attributes.
      // For more information, visit: https://go.microsoft.com/fwlink/linkid=830387
      "version": "0.2.0",
      "configurations": [
          {
              "name": "Python: Current File",
              "type": "python",
              "request": "launch",
              "program": "${file}",
              "console": "integratedTerminal"
          },
          {
              "name": "Azure Machine Learning Deployment: Docker Debug",
              "type": "python",
              "request": "attach",
              "connect": {
                  "port": 5678,
                  "host": "0.0.0.0"
                  },
              "pathMappings": [
                  {
                      "localRoot": "${workspaceFolder}",
                      "remoteRoot": "/var/azureml-app"
                  }
              ]
          }
          ]
      }
      

      Важно!

      Если в разделе конфигурации уже есть другие записи, добавьте запятую ( , ) после вставленного кода.

      Этот раздел присоединяется к контейнеру Docker через порт 5678.

    3. Сохраните файл launch.json.

Создание образа, содержащего debugpy

  1. Измените среду conda для своего развертывания, добавив в нее PTVSD. В следующем примере демонстрируется добавление с помощью параметра pip_packages:

    from azureml.core.conda_dependencies import CondaDependencies 
    
    
    # Usually a good idea to choose specific version numbers
    # so training is made on same packages as scoring
    myenv = CondaDependencies.create(conda_packages=['numpy==1.15.4',
                                'scikit-learn==0.19.1', 'pandas==0.23.4'],
                                 pip_packages = ['azureml-defaults==1.0.83', 'debugpy'])
    
    with open("myenv.yml","w") as f:
        f.write(myenv.serialize_to_string())
    
  2. Чтобы запустить debugpy и дождаться подключения при запуске службы, добавьте следующее в начало файла score.py:

    import debugpy
    # Allows other computers to attach to debugpy on this IP address and port.
    debugpy.listen(('0.0.0.0', 5678))
    # Wait 30 seconds for a debugger to attach. If none attaches, the script continues as normal.
    debugpy.wait_for_client()
    print("Debugger attached...")
    
  3. Создайте образ на основе определения среды и извлеките его в локальный реестр.

    Примечание

    В этом примере предполагается, что ws указывает на вашу рабочую область Машинное обучение Azure, а model представляет собой развертываемую модель. Файл myenv.yml содержит зависимости conda, созданные на шаге 1.

    from azureml.core.conda_dependencies import CondaDependencies
    from azureml.core.model import InferenceConfig
    from azureml.core.environment import Environment
    
    
    myenv = Environment.from_conda_specification(name="env", file_path="myenv.yml")
    myenv.docker.base_image = None
    myenv.docker.base_dockerfile = "FROM mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:latest"
    inference_config = InferenceConfig(entry_script="score.py", environment=myenv)
    package = Model.package(ws, [model], inference_config)
    package.wait_for_creation(show_output=True)  # Or show_output=False to hide the Docker build logs.
    package.pull()
    

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

    Status: Downloaded newer image for myregistry.azurecr.io/package@sha256:<image-digest>
    
  4. Чтобы упростить работу с изображением локально, можно использовать следующую команду, чтобы добавить тег для этого изображения. Замените myimagepath в следующей команде на значение местоположения из предыдущего шага.

    docker tag myimagepath debug:1
    

    На остальных шагах для обозначения расположения локального образа вы можете указывать debug:1 вместо значения полного пути.

Отладка службы

Совет

Если вы установили время ожидания для подключения debugpy в файле score.py, необходимо подключить VS Code к сеансу отладки до истечения этого времени. Запустите VS Code, откройте локальную копию score.py, установите точку останова и подготовьте ее к работе, прежде чем выполнять действия, описанные в этом разделе.

Дополнительные сведения об отладке и установке точек останова см. на этой странице.

  1. Чтобы запустить контейнер Docker с помощью образа, используйте следующую команду:

    docker run -it --name debug -p 8000:5001 -p 5678:5678 -v <my_local_path_to_score.py>:/var/azureml-app/score.py debug:1 /bin/bash
    

    Эта команда присоединяет ваш score.py локально к объекту в контейнере. Таким образом, любые изменения в редакторе автоматически отражаются в контейнере

  2. Чтобы улучшить работу, вы можете перейти в контейнер с помощью нового интерфейса VS Code. Выберите расширение Docker на боковой панели VS Code, найдите созданный локальный контейнер (в этой документации — debug:1). Щелкните этот контейнер правой кнопкой мыши и выберите "Attach Visual Studio Code", затем автоматически откроется новый интерфейс VS Code, и этот интерфейс отобразится внутри созданного контейнера.

    Интерфейс VS Code контейнера

  3. В контейнере выполните следующую команду в оболочке

    runsvdir /var/runit
    

    После этого в оболочке в контейнере можно увидеть следующие выходные данные:

    Контейнер для запуска выходных данных консоли

  4. Чтобы присоединить VS Code к debugpy в контейнере, откройте VS Code и нажмите клавишу F5 или выберите Отладка. При появлении запроса выберите конфигурациюAzure Machine Learning: Docker Debug (Машинное обучение Azure: отладка Docker). Вы также можете выбрать значок расширения Запускна боковой панели, запись Azure Machine Learning Deployment: Docker Debug (Машинное обучение Azure: отладка Docker), а затем щелкнуть зеленую стрелку, чтобы присоединить отладчик.

    Значок отладки, кнопка запуска отладки и селектор конфигурации

    Когда вы нажмете зеленую стрелку и подключите отладчик, то увидите новые сведения в интерфейсе VS Code контейнера:

    Сведения о присоединенном отладчике контейнеров

    Кроме того, в основном интерфейсе VS Code доступны следующие возможности:

    Точка останова VS Code в score.py

И теперь локальный объект, score.py присоединенный к контейнеру, уже остановлен в точках останова, где вы задали значение. На этом этапе VS Code подключается к PTVSD внутри контейнера Docker и останавливается при достижении точки останова, заданной ранее. Теперь вы можете пошагово выполнять код, просматривать переменные и т. д.

Дополнительные сведения об использовании VS Code для отладки Python см. на странице Отладка кода Python.

Остановка контейнера

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

docker stop debug

Дальнейшие действия

Теперь, когда вы настроили VS Code удаленно, вы можете использовать вычислительный экземпляр в качестве удаленного вычислений от VS Code для интерактивной отладки кода.

Ознакомьтесь с дополнительными сведениями об устранении неполадок: