Führen Sie Ihren lokalen Code als Hybrid-Job aus

Amazon Braket Hybrid Jobs bietet eine vollständig verwaltete Orchestrierung hybrider quantenklassischer Algorithmen und kombiniert Amazon EC2 EC2-Rechenressourcen mit dem Zugriff auf die Amazon Braket Quantum Processing Unit (QPU). Quantenaufgaben, die in einem Hybrid-Job erstellt wurden, haben Vorrang vor einzelnen Quantenaufgaben, sodass Ihre Algorithmen nicht durch Schwankungen in der Warteschlange für Quantenaufgaben unterbrochen werden. Jede QPU unterhält eine separate Warteschlange für Hybrid-Jobs, wodurch sichergestellt wird, dass jeweils nur ein Hybrid-Job ausgeführt werden kann.

Erstellen Sie einen Hybrid-Job aus lokalem Python-Code

Sie können Ihren lokalen Python-Code als Amazon Braket Hybrid Job ausführen. Sie können dies tun, indem Sie Ihren Code mit einem @hybrid_job Decorator annotieren, wie im folgenden Codebeispiel gezeigt. Für benutzerdefinierte Umgebungen können Sie sich dafür entscheiden, einen benutzerdefinierten Container aus Amazon Elastic Container Registry (ECR) zu verwenden.

Anmerkung

Standardmäßig wird nur Python 3.10 unterstützt.

Sie können den @hybrid_job Decorator verwenden, um eine Funktion mit Anmerkungen zu versehen. Braket wandelt den Code im Decorator in ein Braket-Hybrid-Job-Algorithmus-Skript um. Der Hybrid-Job ruft dann die Funktion innerhalb des Decorators auf einer Amazon EC2 EC2-Instance auf. Sie können den Fortschritt des Jobs mit job.state() oder mit der Braket-Konsole überwachen. Das folgende Codebeispiel zeigt, wie eine Sequenz von fünf Zuständen auf dem State Vector Simulator (SV1) device ausgeführt wird.

from braket.aws import AwsDevice
from braket.circuits import Circuit, FreeParameter, Observable
from braket.devices import Devices
from braket.jobs.hybrid_job import hybrid_job
from braket.jobs.metrics import log_metric

device_arn = Devices.Amazon.SV1


@hybrid_job(device=device_arn)  # choose priority device
def run_hybrid_job(num_tasks=1):
    device = AwsDevice(device_arn)  # declare AwsDevice within the hybrid job

    # create a parametric circuit
    circ = Circuit()
    circ.rx(0, FreeParameter("theta"))
    circ.cnot(0, 1)
    circ.expectation(observable=Observable.X(), target=0)

    theta = 0.0  # initial parameter

    for i in range(num_tasks):
        task = device.run(circ, shots=100, inputs={"theta": theta})  # input parameters
        exp_val = task.result().values[0]

        theta += exp_val  # modify the parameter (possibly gradient descent)

        log_metric(metric_name="exp_val", value=exp_val, iteration_number=i)

    return {"final_theta": theta, "final_exp_val": exp_val}

Sie erstellen den Hybrid-Job, indem Sie die Funktion wie normale Python-Funktionen aufrufen. Die Decorator-Funktion gibt jedoch eher das Hybrid-Job-Handle als das Ergebnis der Funktion zurück. Um die Ergebnisse abzurufen, nachdem sie abgeschlossen ist, verwenden Siejob.result().

job = run_hybrid_job(num_tasks=1)
result = job.result() 

Das Geräteargument im @hybrid_job Decorator gibt das Gerät an, auf das der Hybrid-Job vorrangigen Zugriff hat — in diesem Fall den SV1 Simulator. Um die QPU-Priorität zu erhalten, müssen Sie sicherstellen, dass der in der Funktion verwendete Geräte-ARN mit dem im Decorator angegebenen übereinstimmt. Der Einfachheit halber können Sie die Hilfsfunktion verwenden, get_job_device_arn() um den in deklarierten Geräte-ARN zu erfassen@hybrid_job.

Anmerkung

Jeder Hybrid-Job hat mindestens eine Minute Startzeit, da er eine containerisierte Umgebung auf Amazon EC2 erstellt. Für sehr kurze Arbeitslasten, wie z. B. einen einzelnen Schaltkreis oder eine Reihe von Schaltungen, kann es daher ausreichend sein, Quantenaufgaben zu verwenden.

Hyperparameter

Die run_hybrid_job() Funktion verwendet das Argumentnum_tasks, um die Anzahl der erstellten Quantenaufgaben zu kontrollieren. Der Hybrid-Job erfasst dies automatisch als Hyperparameter.

Anmerkung

Hyperparameter werden in der Braket-Konsole als Zeichenketten angezeigt, die auf 2500 Zeichen begrenzt sind.

Metriken und Protokollierung

Innerhalb der run_hybrid_job() Funktion werden Metriken aus iterativen Algorithmen mit log_metrics aufgezeichnet. Metriken werden automatisch auf der Braket-Konsolenseite unter der Registerkarte Hybrid-Job dargestellt. Mit dem Braket-Kosten-Tracker können Sie die Kosten für Quantenaufgaben während der Ausführung des Hybrid-Jobs nahezu in Echtzeit verfolgen. Im obigen Beispiel wird der Metrikname „Wahrscheinlichkeit“ verwendet, der die erste Wahrscheinlichkeit aus dem Ergebnistyp aufzeichnet.

Ergebnisse werden abgerufen

Nach Abschluss des Hybrid-Jobs können Sie job.result() die Ergebnisse der Hybrid-Jobs abrufen. Alle Objekte in der Rückmeldung werden automatisch von Braket erfasst. Beachten Sie, dass die von der Funktion zurückgegebenen Objekte ein Tupel sein müssen, wobei jedes Element serialisierbar sein muss. Der folgende Code zeigt beispielsweise ein funktionierendes und ein fehlgeschlagenes Beispiel.

@hybrid_job(device=Devices.Amazon.SV1)
def passing():
    np_array = np.random.rand(5)
    return np_array  # serializable
    
@hybrid_job(device=Devices.Amazon.SV1)
def failing():
    return MyObject() # not serializable

Name des Berufs

Standardmäßig wird der Name für diesen Hybrid-Job aus dem Funktionsnamen abgeleitet. Sie können auch einen benutzerdefinierten Namen mit einer Länge von bis zu 50 Zeichen angeben. Im folgenden Code lautet der Jobname beispielsweise „my-job-name“.

@hybrid_job(device=Devices.Amazon.SV1, job_name="my-job-name")
def function():
    pass

Lokaler Modus

Lokale Jobs werden erstellt, indem das Argument local=True zum Decorator hinzugefügt wird. Dadurch wird der Hybrid-Job in einer containerisierten Umgebung in Ihrer lokalen Computerumgebung, z. B. Ihrem Laptop, ausgeführt. Lokale Jobs haben keine Priorität in der Warteschlange für Quantenaufgaben. In fortgeschrittenen Fällen, wie z. B. bei mehreren Knoten oder MPI, haben lokale Jobs möglicherweise Zugriff auf die erforderlichen Braket-Umgebungsvariablen. Der folgende Code erstellt einen lokalen Hybrid-Job mit dem Gerät als SV1-Simulator.

@hybrid_job(device=Devices.Amazon.SV1, local=True)
def run_hybrid_job(num_tasks = 1):
    return ...

Alle anderen Hybrid-Job-Optionen werden unterstützt. Eine Liste der Optionen finden Sie im Modul braket.jobs.quantum_job_creation.

Installieren Sie zusätzliche Python-Pakete und Quellcode

Sie können Ihre Laufzeitumgebung so anpassen, dass sie Ihre bevorzugten Python-Pakete verwendet. Sie können entweder eine requirements.txt Datei, eine Liste von Paketnamen oder Ihren eigenen Container (BYOC) verwenden. Informationen zum Anpassen einer Laufzeitumgebung mithilfe einer requirements.txt Datei finden Sie im folgenden Codebeispiel.

@hybrid_job(device=Devices.Amazon.SV1, dependencies="requirements.txt")
def run_hybrid_job(num_tasks = 1):
    return ...

Die requirements.txt Datei kann beispielsweise andere zu installierende Pakete enthalten.

qiskit 
pennylane >= 0.31
mitiq == 0.29

Alternativ können Sie die Paketnamen wie folgt als Python-Liste angeben.

@hybrid_job(device=Devices.Amazon.SV1, dependencies=["qiskit", "pennylane>=0.31", "mitiq==0.29"])
def run_hybrid_job(num_tasks = 1):
    return ...

Zusätzlicher Quellcode kann entweder als Liste von Modulen oder als einzelnes Modul wie im folgenden Codebeispiel angegeben werden.

@hybrid_job(device=Devices.Amazon.SV1, include_modules=["my_module1", "my_module2"])
def run_hybrid_job(num_tasks = 1):
    return ...

Speichern und laden Sie Daten in eine Hybrid-Job-Instanz

Angabe der Eingabe-Trainingsdaten

Wenn Sie einen Hybrid-Job erstellen, können Sie Eingabe-Trainingsdatensätze bereitstellen, indem Sie einen Amazon Simple Storage Service (Amazon S3) -Bucket angeben. Sie können auch einen lokalen Pfad angeben, dann lädt Braket die Daten automatisch auf Amazon S3 hoch unter. s3://<default_bucket_name>/jobs/<job_name>/<timestamp>/data/<channel_name> Wenn Sie einen lokalen Pfad angeben, ist der Kanalname standardmäßig auf „input“ eingestellt. Der folgende Code zeigt eine Numpy-Datei aus dem lokalen Pfad. data/file.npy

@hybrid_job(device=Devices.Amazon.SV1, input_data="data/file.npy")
def run_hybrid_job(num_tasks = 1):
    data = np.load("data/file.npy")
    return ...

Für S3 müssen Sie die get_input_data_dir() Hilfsfunktion verwenden.

s3_path = "s3://amazon-braket-us-west-1-961591465522/job-data/file.npy"

@hybrid_job(device=None, input_data=s3_path)
def job_s3_input():
    np.load(get_input_data_dir() + "/file.npy")
    
@hybrid_job(device=None, input_data={"channel": s3_path})
def job_s3_input_channel():
    np.load(get_input_data_dir("channel") + "/file.npy")

Sie können mehrere Eingabedatenquellen angeben, indem Sie ein Wörterbuch mit Kanalwerten und S3-URIs oder lokalen Pfaden bereitstellen.

input_data = {
    "input": "data/file.npy",
    "input_2": "s3://my-bucket/data.json"
} 


@hybrid_job(device=None, input_data=input_data)
def multiple_input_job():
    np.load(get_input_data_dir("input") + "/file.npy")
    np.load(get_input_data_dir("input_2") + "/data.json")

Anmerkung

Wenn die Eingabedaten groß sind (> 1 GB), dauert es lange, bis der Job erstellt wird. Dies liegt an den lokalen Eingabedaten, wenn sie zum ersten Mal in einen S3-Bucket hochgeladen werden. Anschließend wird der S3-Pfad zur Jobanforderung hinzugefügt. Schließlich wird die Jobanfrage an den Braket-Service übermittelt.

Ergebnisse auf S3 speichern

Um Ergebnisse zu speichern, die nicht in der Return-Anweisung der dekorierten Funktion enthalten sind, müssen Sie allen Schreibvorgängen von Dateien das richtige Verzeichnis anhängen. Das folgende Beispiel zeigt das Speichern eines Numpy-Arrays und einer Matplotlib-Figur.

@hybrid_job(device=Devices.Amazon.SV1)
def run_hybrid_job(num_tasks = 1):
    result = np.random.rand(5)
    
    # save a numpy array
    np.save("result.npy", result)
    
    # save a matplotlib figure
    plt.plot(result)
    plt.savefig("fig.png")
    return ...

Alle Ergebnisse werden in einer Datei mit dem Namen komprimiert. model.tar.gz Sie können die Ergebnisse mit der Python-Funktion job.result() herunterladen oder indem Sie auf der Hybrid-Job-Seite in der Braket-Managementkonsole zum Ergebnisordner navigieren.

Speichern und von Checkpoints aus fortsetzen

Bei Hybrid-Jobs mit langer Laufzeit wird empfohlen, den Zwischenstatus des Algorithmus regelmäßig zu speichern. Sie können die integrierte save_job_checkpoint() Hilfsfunktion verwenden oder Dateien im AMZN_BRAKET_JOB_RESULTS_DIR Pfad speichern. Letzteres ist mit der Hilfsfunktion verfügbarget_job_results_dir().

Im Folgenden finden Sie ein minimales funktionierendes Beispiel für das Speichern und Laden von Checkpoints mit einem hybriden Job Decorator:

from braket.jobs import save_job_checkpoint, load_job_checkpoint, hybrid_job

@hybrid_job(device=None, wait_until_complete=True)
def function():
    save_job_checkpoint({"a": 1})

job = function()
job_name = job.name
job_arn = job.arn

@hybrid_job(device=None, wait_until_complete=True, copy_checkpoints_from_job=job_arn)
def continued_function():
    load_job_checkpoint(job_name)

continued_job = continued_function()

Im ersten Hybrid-Job save_job_checkpoint() wird ein Wörterbuch aufgerufen, das die Daten enthält, die wir speichern möchten. Standardmäßig muss jeder Wert als Text serialisierbar sein. Um komplexere Python-Objekte wie Numpy-Arrays zu überprüfen, können Sie festlegen. data_format = PersistedJobDataFormat.PICKLED_V4 Dieser Code erstellt und überschreibt eine Checkpoint-Datei mit dem Standardnamen <jobname>.json in Ihren Hybrid-Job-Artefakten in einem Unterordner namens „Checkpoints“.

Um einen neuen Hybrid-Job zu erstellen, um vom Checkpoint aus fortzufahren, müssen wir übergeben, copy_checkpoints_from_job=job_arn wo job_arn sich der Hybrid-Job-ARN des vorherigen Jobs befindet. Dann laden wir load_job_checkpoint(job_name) normalerweise vom Checkpoint aus.

Bewährte Verfahren für hybride Jobdekorateure

Machen Sie sich Asynchronität zu eigen

Hybrid-Jobs, die mit der Decorator-Annotation erstellt wurden, sind asynchron — sie werden ausgeführt, sobald die klassischen Ressourcen und die Quantenressourcen verfügbar sind. Sie überwachen den Fortschritt des Algorithmus mithilfe von Braket Management Console oder Amazon CloudWatch. Wenn Sie Ihren Algorithmus zur Ausführung einreichen, führt Braket Ihren Algorithmus in einer skalierbaren containerisierten Umgebung aus und die Ergebnisse werden abgerufen, wenn der Algorithmus abgeschlossen ist.

Führen Sie iterative Variationsalgorythmen aus

Hybrid-Jobs bieten Ihnen die Tools, um iterative quantenklassische Algorithmen auszuführen. Verwenden Sie für reine Quantenprobleme Quantenaufgaben oder eine Reihe von Quantenaufgaben. Der bevorzugte Zugriff auf bestimmte QPUs ist am vorteilhaftesten für lang andauernde Variationsalgorithmen, die mehrere iterative Aufrufe der QPUs mit klassischer Verarbeitung dazwischen erfordern.

Debuggen Sie im lokalen Modus

Bevor Sie einen Hybrid-Job auf einer QPU ausführen, wird empfohlen, ihn zunächst auf dem Simulator SV1 auszuführen, um sicherzustellen, dass er wie erwartet ausgeführt wird. Für Tests in kleinem Maßstab können Sie den lokalen Modus verwenden, um eine schnelle Iteration und ein schnelles Debuggen zu ermöglichen.

Verbessern Sie die Reproduzierbarkeit mit Bring Your Own Container (BYOC)

Erstellen Sie ein reproduzierbares Experiment, indem Sie Ihre Software und ihre Abhängigkeiten in einer containerisierten Umgebung kapseln. Indem Sie Ihren gesamten Code, Ihre Abhängigkeiten und Einstellungen in einem Container verpacken, verhindern Sie potenzielle Konflikte und Versionsprobleme.

Verteilte Simulatoren mit mehreren Instanzen

Wenn Sie eine große Anzahl von Schaltungen ausführen möchten, sollten Sie erwägen, die integrierte MPI-Unterstützung zu verwenden, um lokale Simulatoren auf mehreren Instanzen innerhalb eines einzigen Hybrid-Jobs auszuführen. Weitere Informationen finden Sie unter Integrierte Simulatoren.

Verwenden Sie parametrische Schaltungen

Parametrische Schaltungen, die Sie über einen Hybrid-Job einreichen, werden automatisch auf bestimmten QPUs kompiliert. Dabei wird die parametrische Kompilierung verwendet, um die Laufzeiten Ihrer Algorithmen zu verbessern.

Regelmäßiger Checkpoint

Bei Hybrid-Jobs mit langer Laufzeit wird empfohlen, den Zwischenstatus des Algorithmus regelmäßig zu speichern.

Weitere Beispiele, Anwendungsfälle und bewährte Methoden finden Sie in den Amazon Braket-Beispielen. GitHub