Interaktiv felsökning med Visual Studio Code

GÄLLER FÖR:Python SDK azureml v1

Lär dig hur du interaktivt felsöker Azure Machine Learning-experiment, pipelines och distributioner med hjälp av Visual Studio Code (VS Code) och felsökning.

Köra och felsöka experiment lokalt

Använd Azure Machine Learning-tillägget för att validera, köra och felsöka dina maskininlärningsexperiment innan du skickar dem till molnet.

Förutsättningar

Felsöka experiment lokalt

Viktigt

Innan du kör experimentet lokalt kontrollerar du att:

  • Docker körs.
  • Inställningen azureML.CLI Compatibility Mode i Visual Studio Code är inställd på 1.0 enligt kraven
  1. Öppna Azure Machine Learning-tilläggsvyn i VS Code.

  2. Expandera prenumerationsnoden som innehåller din arbetsyta. Om du inte redan har en kan du skapa en Azure Machine Learning-arbetsyta med hjälp av tillägget.

  3. Expandera arbetsytans nod.

  4. Högerklicka på noden Experiment och välj Skapa experiment. När kommandotolken visas anger du ett namn för experimentet.

  5. Expandera noden Experiment , högerklicka på experimentet som du vill köra och välj Kör experiment.

  6. Välj Lokalt i listan med alternativ.

  7. Första gången endast i Windows. När du uppmanas att tillåta filresurs väljer du Ja. När du aktiverar filresursen kan Docker montera katalogen som innehåller skriptet i containern. Dessutom kan Docker lagra loggar och utdata från körningen i en tillfällig katalog i systemet.

  8. Välj Ja för att felsöka experimentet. Annars väljer du Nej. Om du väljer nej körs experimentet lokalt utan att kopplas till felsökaren.

  9. Välj Skapa ny körningskonfiguration för att skapa körningskonfigurationen. Körningskonfigurationen definierar det skript som du vill köra, beroenden och datauppsättningar som används. Om du redan har en kan du också välja den i listrutan.

    1. Välj din miljö. Du kan välja mellan valfri Azure Machine Learning-kuraterad eller skapa en egen.
    2. Ange namnet på skriptet som du vill köra. Sökvägen är relativ till katalogen som öppnas i VS Code.
    3. Välj om du vill använda en Azure Machine Learning-datauppsättning eller inte. Du kan skapa Azure Machine Learning-datauppsättningar med hjälp av tillägget.
    4. Felsökning krävs för att koppla felsökningsprogrammet till containern som kör experimentet. Om du vill lägga till felsökning som ett beroende väljer du Lägg till felsökning. Annars väljer du Hoppa över. Om du inte lägger till felsökning som ett beroende körs experimentet utan att kopplas till felsökaren.
    5. En konfigurationsfil som innehåller inställningarna för körningskonfigurationen öppnas i redigeraren. Om du är nöjd med inställningarna väljer du Skicka experiment. Du kan också öppna kommandopaletten (Visa > kommandopalett) från menyraden AzureML: Submit experiment och ange kommandot i textrutan.
  10. När experimentet har skickats skapas en Docker-avbildning som innehåller skriptet och de konfigurationer som anges i körningskonfigurationen.

    När Docker-avbildningens byggprocess börjar kommer innehållet i 60_control_log.txt filströmmen till utdatakonsolen i VS Code.

    Anteckning

    Första gången du skapar Docker-avbildningen kan det ta flera minuter.

  11. När avbildningen har skapats visas en uppmaning om att starta felsökningsprogrammet. Ange brytpunkterna i skriptet och välj Starta felsökningsprogrammet när du är redo att börja felsöka. På så sätt kopplas VS Code-felsökaren till containern som kör experimentet. Du kan också hovra över noden i Azure Machine Learning-tillägget för din aktuella körning och välja uppspelningsikonen för att starta felsökningsprogrammet.

    Viktigt

    Du kan inte ha flera felsökningssessioner för ett enda experiment. Du kan dock felsöka två eller flera experiment med flera VS Code-instanser.

Nu bör du kunna stega igenom och felsöka koden med VS Code.

Om du vill avbryta körningen högerklickar du på körningsnoden och väljer Avbryt körning.

Precis som med fjärrexperimentkörningar kan du expandera din körningsnod för att granska loggarna och utdata.

Tips

Docker-avbildningar som använder samma beroenden som definieras i din miljö återanvänds mellan körningar. Men om du kör ett experiment med en ny eller annan miljö skapas en ny avbildning. Eftersom avbildningarna sparas i din lokala lagring rekommenderar vi att du tar bort gamla eller oanvända Docker-avbildningar. Om du vill ta bort avbildningar från systemet använder du Docker CLI eller VS Code Docker-tillägget.

Felsöka pipelines för maskininlärning

I vissa fall kan du behöva felsöka Python-koden interaktivt i din ML-pipeline. Genom att använda VS Code och felsökning kan du ansluta till koden när den körs i träningsmiljön.

Förutsättningar

  • En Azure Machine Learning-arbetsyta som är konfigurerad för att använda en Azure-Virtual Network.

  • En Azure Machine Learning-pipeline som använder Python-skript som en del av pipelinestegen. Till exempel ett PythonScriptStep.

  • Ett Azure Machine Learning Compute-kluster som finns i det virtuella nätverket och används av pipelinen för träning.

  • En utvecklingsmiljö som finns i det virtuella nätverket. Utvecklingsmiljön kan vara något av följande:

    • En virtuell Azure-dator i det virtuella nätverket
    • En beräkningsinstans av notebook-dator i det virtuella nätverket
    • En klientdator som har en privat nätverksanslutning till det virtuella nätverket, antingen via VPN eller via ExpressRoute.

Mer information om hur du använder en Azure-Virtual Network med Azure Machine Learning finns i Översikt över isolering av virtuella nätverk och sekretess.

Tips

Även om du kan arbeta med Azure Machine Learning-resurser som inte ligger bakom ett virtuellt nätverk rekommenderar vi att du använder ett virtuellt nätverk.

Så här fungerar det

Dina ML-pipelinesteg kör Python-skript. Dessa skript ändras för att utföra följande åtgärder:

  1. Logga IP-adressen för värden som de kör på. Du använder IP-adressen för att ansluta felsökaren till skriptet.

  2. Starta felsökningskomponenten och vänta tills ett felsökningsprogram ansluter.

  3. Från utvecklingsmiljön övervakar du loggarna som skapats av träningsprocessen för att hitta IP-adressen där skriptet körs.

  4. Du talar om för VS Code att IP-adressen ska ansluta felsökaren till med hjälp av en launch.json fil.

  5. Du bifogar felsökningsprogrammet och går interaktivt igenom skriptet.

Konfigurera Python-skript

Om du vill aktivera felsökning gör du följande ändringar i Python-skripten som används av stegen i ML-pipelinen:

  1. Lägg till följande importinstruktioner:

    import argparse
    import os
    import debugpy
    import socket
    from azureml.core import Run
    
  2. Lägg till följande argument. Med de här argumenten kan du aktivera felsökningsprogrammet efter behov och ange tidsgränsen för att koppla felsökningsprogrammet:

    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. Lägg till följande instruktioner. Dessa instruktioner läser in den aktuella körningskontexten så att du kan logga IP-adressen för noden som koden körs på:

    global run
    run = Run.get_context()
    
  4. Lägg till en if instruktion som startar felsökning och väntar på att ett felsökningsprogram ska kopplas. Om inget felsökningsprogram ansluts före tidsgränsen fortsätter skriptet som vanligt. Se till att ersätta HOST värdena och PORT är listen funktionen med din egen.

    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()}')
    

I följande Python-exempel visas en enkel train.py fil som aktiverar felsökning:

# 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)

Konfigurera ML-pipeline

Om du vill ange de Python-paket som behövs för att starta felsökningen och hämta körningskontexten skapar du en miljö och anger pip_packages=['debugpy', 'azureml-sdk==<SDK-VERSION>']. Ändra SDK-versionen så att den matchar den du använder. Följande kodfragment visar hur du skapar en miljö:

# 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>'])

I avsnittet Konfigurera Python-skript har nya argument lagts till i skripten som används av ml-pipelinestegen. Följande kodfragment visar hur du använder dessa argument för att aktivera felsökning för komponenten och ange en tidsgräns. Det visar också hur du använder miljön som skapades tidigare genom att ange 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)

När pipelinen körs skapar varje steg en underordnad körning. Om felsökning är aktiverat loggar det ändrade skriptet information som liknar följande text i för den underordnade körningen 70_driver_log.txt :

Timeout for debug connection: 300
ip_address: 10.3.0.5

Spara värdet ip_address . Den används i nästa avsnitt.

Tips

Du hittar även IP-adressen från körningsloggarna för den underordnade körningen för det här pipelinesteget. Mer information om hur du visar den här informationen finns i Övervaka Azure Machine Learning-experimentkörningar och mått.

Konfigurera utvecklingsmiljön

  1. Om du vill installera felsökning i VS Code-utvecklingsmiljön använder du följande kommando:

    python -m pip install --upgrade debugpy
    

    Mer information om hur du använder felsökning med VS Code finns i Fjärrfelsökning.

  2. Om du vill konfigurera VS Code för att kommunicera med Azure Machine Learning-beräkningen som kör felsökningsprogrammet skapar du en ny felsökningskonfiguration:

    1. Från VS Code väljer du menyn Felsök och sedan Öppna konfigurationer. En fil med namnet launch.json öppnas.

    2. Leta reda på raden som innehåller "configurations": [i filen launch.json och infoga följande text efter den. Ändra posten "host": "<IP-ADDRESS>" till DEN IP-adress som returneras i loggarna från föregående avsnitt. Ändra posten "localRoot": "${workspaceFolder}/code/step" till en lokal katalog som innehåller en kopia av skriptet som debugged:

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

      Viktigt

      Om det redan finns andra poster i avsnittet konfigurationer lägger du till ett kommatecken (,) efter koden som du infogade.

      Tips

      Det bästa sättet, särskilt för pipelines, är att behålla resurserna för skript i separata kataloger så att koden endast är relevant för vart och ett av stegen. I det här exemplet localRoot refererar exempelvärdet till /code/step1.

      Om du felsöker flera skript skapar du i olika kataloger ett separat konfigurationsavsnitt för varje skript.

    3. Spara filen launch.json .

Ansluta felsökningsprogrammet

  1. Öppna VS Code och öppna en lokal kopia av skriptet.

  2. Ange brytpunkter där du vill att skriptet ska stoppas när du har anslutit.

  3. Medan den underordnade processen kör skriptet och Timeout for debug connection visas i loggarna använder du F5-nyckeln eller väljer Felsök. När du uppmanas till det väljer du konfigurationen för Azure Machine Learning Compute: remote debug . Du kan också välja felsökningsikonen från sidofältet , posten Azure Machine Learning: remote debug från listrutan Felsök och sedan använda den gröna pilen för att koppla felsökningsprogrammet.

    Vid den här tidpunkten ansluter VS Code till felsökning på beräkningsnoden och stoppas vid den brytpunkt som du angav tidigare. Nu kan du gå igenom koden när den körs, visa variabler osv.

    Anteckning

    Om loggen visar en post som anger Debugger attached = Falsehar tidsgränsen upphört att gälla och skriptet fortsatte utan felsökaren. Skicka pipelinen igen och anslut felsökningsprogrammet efter meddelandet Timeout for debug connection och innan tidsgränsen går ut.

Felsöka distributioner

I vissa fall kan du behöva felsöka Python-koden i modelldistributionen interaktivt. Om till exempel postskriptet misslyckas och orsaken inte kan fastställas genom extra loggning. Genom att använda VS Code och felsökningen kan du ansluta till koden som körs i Docker-containern.

Tips

Om du använder hanterade onlineslutpunkter och distributioner lokalt kan du läsa Felsöka hanterade onlineslutpunkter lokalt i Visual Studio Code (förhandsversion).

Viktigt

Den här felsökningsmetoden fungerar inte när du använder Model.deploy() och LocalWebservice.deploy_configuration distribuerar en modell lokalt. I stället måste du skapa en avbildning med metoden Model.package().

Distributioner av lokala webbtjänster kräver en fungerande Docker-installation på det lokala systemet. Mer information om hur du använder Docker finns i Docker-dokumentationen. När du arbetar med beräkningsinstanser är Docker redan installerat.

Konfigurera utvecklingsmiljön

  1. Om du vill installera felsökning i din lokala VS Code-utvecklingsmiljö använder du följande kommando:

    python -m pip install --upgrade debugpy
    

    Mer information om hur du använder felsökning med VS Code finns i Fjärrfelsökning.

  2. Om du vill konfigurera VS Code för att kommunicera med Docker-avbildningen skapar du en ny felsökningskonfiguration:

    1. Från VS Code väljer du menyn Felsöka i Körningsförlopp och väljer sedan Öppna konfigurationer. En fil med namnet launch.json öppnas.

    2. I filen launch.json letar du upp objektet "configurations" (raden som innehåller "configurations": [) och infogar följande text efter den.

      {
          "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"
              }
          ]
      }
      

      Efter infogningen bör filen launch.json likna följande:

      {
      // 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"
                  }
              ]
          }
          ]
      }
      

      Viktigt

      Om det redan finns andra poster i avsnittet konfigurationer lägger du till ett kommatecken ( , ) efter koden som du infogade.

      Det här avsnittet ansluter till Docker-containern med port 5678.

    3. Spara filen launch.json .

Skapa en avbildning som innehåller felsökning

  1. Ändra conda-miljön för distributionen så att den innehåller felsökning. I följande exempel visas hur du lägger till den med hjälp av parametern 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. Om du vill starta felsökningen och vänta på en anslutning när tjänsten startar lägger du till följande överst score.py i filen:

    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. Skapa en avbildning baserat på miljödefinitionen och hämta avbildningen till det lokala registret.

    Anteckning

    Det här exemplet förutsätter att pekar ws på din Azure Machine Learning-arbetsyta och att det är modellen som model distribueras. Filen myenv.yml innehåller conda-beroendena som skapades i steg 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()
    

    När avbildningen har skapats och laddats ned (den här processen kan ta mer än 10 minuter) visas bildsökvägen (inklusive lagringsplats, namn och tagg, som i det här fallet också är dess sammandrag) i ett meddelande som liknar följande:

    Status: Downloaded newer image for myregistry.azurecr.io/package@sha256:<image-digest>
    
  4. Om du vill göra det enklare att arbeta med avbildningen lokalt kan du använda följande kommando för att lägga till en tagg för den här avbildningen. Ersätt myimagepath i följande kommando med platsvärdet från föregående steg.

    docker tag myimagepath debug:1
    

    För resten av stegen kan du referera till den lokala avbildningen som debug:1 i stället för det fullständiga bildsökvägsvärdet.

Felsöka tjänsten

Tips

Om du anger en tidsgräns för felsökningsanslutningen score.py i filen måste du ansluta VS Code till felsökningssessionen innan tidsgränsen går ut. Starta VS Code, öppna den lokala kopian av score.py, ange en brytpunkt och gör den redo innan du använder stegen i det här avsnittet.

Mer information om felsökning och inställning av brytpunkter finns i Felsökning.

  1. Om du vill starta en Docker-container med avbildningen använder du följande kommando:

    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
    

    Det här kommandot ansluter din score.py lokalt till den i containern. Därför återspeglas alla ändringar som görs i redigeraren automatiskt i containern

  2. För en bättre upplevelse kan du gå in i containern med ett nytt VS Code-gränssnitt. Välj omfattning från VS Code-sidofältet och leta reda på den lokala container som skapats. I den Docker här dokumentationen är det debug:1. Högerklicka på den här containern och välj "Attach Visual Studio Code". Sedan öppnas ett nytt VS Code-gränssnitt automatiskt, och det här gränssnittet visar insidan av den skapade containern.

    Vs Code-containergränssnittet

  3. I containern kör du följande kommando i gränssnittet

    runsvdir /var/runit
    

    Sedan kan du se följande utdata i gränssnittet i containern:

    Utdata från containerkörningskonsolen

  4. Om du vill koppla VS Code till felsökning i containern öppnar du VS Code och använder F5-nyckeln eller väljer Felsök. När du uppmanas väljer du konfigurationen Azure Machine Learning Deployment: Docker Debug . Du kan också välja ikonen Körningsutbredning i sidofältet, posten Azure Machine Learning Deployment: Docker Debug från listrutan Felsök och sedan använda den gröna pilen för att koppla felsökningsprogrammet.

    Felsökningsikonen, knappen Starta felsökning och konfigurationsväljaren

    När du har valt den gröna pilen och bifogat felsökningsprogrammet kan du se ny information i vs code-containergränssnittet:

    Bifogad information om containerfelsökaren

    I ditt huvudsakliga VS Code-gränssnitt kan du också se följande:

    VS Code-brytpunkten i score.py

Och nu har den lokala score.py som är kopplad till containern redan stoppats vid de brytpunkter som du anger. I det här läget ansluter VS Code till felsökning i Docker-containern och stoppar Docker-containern vid den brytpunkt som du angav tidigare. Nu kan du stega igenom koden när den körs, visa variabler osv.

Mer information om hur du använder VS Code för att felsöka Python finns i Felsöka din Python-kod.

Stoppa containern

Om du vill stoppa containern använder du följande kommando:

docker stop debug

Nästa steg

Nu när du har konfigurerat VS Code Remote kan du använda en beräkningsinstans som fjärrberäkning från VS Code för att interaktivt felsöka koden.

Läs mer om felsökning: