Abhängigkeiten deklarieren

Ein verwalteter Workflow läuft in einer Python-Umgebung, die er im Voraus vorbereitet. Der Job hat keinen Zugriff auf das Internet und kann daher keine Pakete mit pip install installieren. Stattdessen sind Qiskit und eine Liste unterstützter Pakete bereits installiert, und für jedes andere Paket, das dein Workflow braucht, kannst du Wheels hochladen.

Prüfen, welche Pakete installiert sind

Jeder Job läuft mit Python 3.12 auf Linux (x86_64) mit den folgenden installierten Paketen:

• qiskit, qiskit-ibm-runtime, qiskit-serverless und ihre Abhängigkeiten, etwa numpy.

• Die unterstützten Pakete, etwa qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim und pyscf. Jedes ist in einer festen Version installiert.

Um die unterstützten Pakete und ihre Versionen zu sehen, rufe dependencies_versions() in deinem lokalen Notebook auf:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Dein Workflow kann jedes dieser Pakete ohne Einrichtung importieren. Der Workflow installiert sie beim Aufbau der Umgebung, nicht beim Start eines Jobs, sodass sie die Startzeit eines Jobs nicht verlängern.

Ein Workflow liest keine requirements.txt- oder pyproject.toml-Datei und installiert daher die Pakete, die diese Dateien auflisten, nicht. Das Argument dependencies von ManagedWorkflow ist veraltet und wird ignoriert, sodass es ebenfalls keine Pakete installiert. Entferne es aus deinem Upload-Code und lade stattdessen Wheels hoch.

Pakete auf GPU-Compute-Profilen

Auf Jobs, die auf einem GPU-Compute-Profil laufen, sind zusätzlich die folgenden CUDA-Pakete installiert. Diese Pakete funktionieren nur auf einem GPU-Profil, und dependencies_versions() listet sie nicht auf. Lade keine eigenen CUDA-Wheels hoch, da sie mit diesen Versionen in Konflikt geraten.

Paket	Version
gpu4pyscf-cuda12x	1.8.1
gpu4pyscf-libxc-cuda12x	0.8.1
cupy-cuda12x	14.2.0
cutensor-cu12	2.8.0
cuda-pathfinder	1.8.5
nvidia-cublas-cu12	12.9.3.13
nvidia-cuda-nvrtc-cu12	12.9.86
nvidia-cuda-runtime-cu12	12.9.79
nvidia-cufft-cu12	11.4.1.4
nvidia-curand-cu12	10.3.10.19
nvidia-cusolver-cu12	11.7.5.82
nvidia-cusparse-cu12	12.5.10.65
nvidia-nvjitlink-cu12	12.9.86

Die nvidia-*-cu12-Versionen können sich ändern, wenn die Umgebung neu aufgebaut wird. Code, der von einer exakten Version einer CUDA-Bibliothek abhängt, muss nach einem neuen Release möglicherweise angepasst werden.

Ein Paket anfordern

Wenn auch andere Nutzer ein Paket benötigen würden, fordere es auf GitHub an. Ein akzeptiertes Paket wird in einem späteren Release zur Umgebung hinzugefügt. Bis dahin, oder für ein privates Paket, füge es als Wheel hinzu.

Eigene Pakete hinzufügen

Um ein Paket zu verwenden, das nicht installiert ist, sammle seine Wheel-Dateien auf deinem Computer, lade sie in den Dateispeicher des Workflows hoch und installiere sie zu Beginn des Workflows. Du lädst sie nur dann erneut hoch, wenn sie sich ändern.

Wheels erstellen

Der Job installiert Wheels ohne Internetverbindung, daher muss jedes Wheel mit Python 3.12 unter Linux (x86_64) funktionieren. Sammle die Wheels in einem Ordner:

Local terminal

# Your own package
pip wheel --no-deps --wheel-dir wheels ./mypkg

# A package from PyPI, for the job's platform
pip download --only-binary=:all: --platform manylinux_2_28_x86_64 \
    --python-version 3.12 --dest wheels pendulum==3.1.0

Mit --platform und --python-version lädt pip download Wheels für die Plattform des Jobs herunter, auch wenn du es unter macOS oder Windows ausführst. Es lädt außerdem die Abhängigkeiten des Pakets herunter, etwa python-dateutil, six und tzdata für pendulum. Da der Job jedes Wheel ohne seine Abhängigkeiten installiert, lade für jede Abhängigkeit, die der Umgebung fehlt, ein Wheel hoch, und lösche die übrigen Wheels aus dem Ordner.

Ein reines Python-Wheel (py3-none-any.whl) funktioniert auf jeder Plattform. Wenn für ein Paket mit kompiliertem Code auf PyPI kein Linux-x86_64-Wheel existiert, erstelle eines unter Linux, zum Beispiel in einem python:3.12-Container. Behalte die ursprünglichen Dateinamen bei, denn pip liest Paketname, Version und Plattform daraus ab.

Wheels hochladen

Lade die Wheels aus deinem lokalen Notebook mit add_wheels() hoch:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
my_workflow = client.load("my-workflow")

client.add_wheels(my_workflow, ["wheels/*.whl"])
print(client.list_wheels(my_workflow))

Jeder Pfad kann ein Dateiname oder ein Glob-Muster sein, und add_wheels() gibt die Namen der hochgeladenen Wheels zurück. Wenn ein Muster keine Dateien findet oder eine Datei findet, die keine .whl-Datei ist, löst add_wheels() eine QiskitServerlessException aus.

Lade den Workflow hoch, bevor du Wheels hinzufügst, denn die Wheels werden zusammen mit ihm gespeichert. Sie landen in einem Ordner wheels im Dateispeicher des Workflows, getrennt von deinen anderen Dateien.

Wheels ersetzen oder entfernen

Um die Wheels zu sehen, die in einen Workflow hochgeladen wurden, rufe list_wheels() auf. Um Wheels zu entfernen, übergib ihre Dateinamen an remove_wheels():

run_workflow_remotely.ipynb

client.list_wheels(my_workflow)
# ['mypkg-1.0-py3-none-any.whl']

client.remove_wheels(my_workflow, ["mypkg-1.0-py3-none-any.whl"])

Um ein Paket zu aktualisieren, entferne das alte Wheel und füge dann das neue hinzu. Eine neue Version hat einen anderen Dateinamen. Wenn du das alte Wheel behältst, installiert install_uploaded_wheels() daher beide Versionen.

run_workflow_remotely.ipynb

client.remove_wheels(my_workflow, ["mypkg-1.0-py3-none-any.whl"])
client.add_wheels(my_workflow, ["wheels/mypkg-1.1-*.whl"])

Wheels in deinem Workflow installieren

Bearbeite den Code deines Workflows so, dass er install_uploaded_wheels() aufruft, bevor er die Pakete importiert:

source_files/my_workflow.py

from qiskit_serverless import install_uploaded_wheels

install_uploaded_wheels()

import pendulum  # Installed from an uploaded wheel

install_uploaded_wheels() installiert jedes Wheel im Ordner wheels. Wenn der Workflow keine Wheels hat, tut der Aufruf nichts. Die Wheels werden bei jedem Lauf erneut installiert, daher verlängert eine große Menge an Wheels die Startzeit jedes Jobs.

Best Practice: nur fehlende Pakete mitbringen

Als Best Practice lädst du nur Wheels für die Pakete hoch, die der Umgebung fehlen. Ein Wheel für ein bereits installiertes Paket, wie numpy, installiert eine zweite Kopie, und der Code, der es importiert, kann beide Kopien erhalten. Fehler durch eine Inkonsistenz zeigen sich erst, wenn der Job läuft.

Prüfe vor dem Hochladen deine Anforderungen mit dependency_report() aus deinem lokalen Notebook:

run_workflow_remotely.ipynb

print(client.dependency_report(["pendulum==3.1.0", "qiskit-aer", "qiskit-addon-sqd==0.10.0"]))

requirement               status  note
pendulum==3.1.0           bring   not in image — upload a wheel
qiskit-aer                baked   already in image (qiskit-aer==0.17.2)
qiskit-addon-sqd==0.10.0  clash   image ships qiskit-addon-sqd==0.13.1

Der Bericht weist jeder Anforderung einen der folgenden Status zu:

• baked: Die Umgebung stellt das Paket bereits bereit. Lade dafür kein Wheel hoch.

• bring: Der Umgebung fehlt das Paket. Lade dafür ein Wheel hoch.

• clash: Die Umgebung stellt eine andere Version bereit. Ändere die Version, die dein Code benötigt, oder erstelle dein Paket für die installierte Version neu.

Der Bericht prüft nur die unterstützten Pakete, daher zeigt er qiskit, qiskit-ibm-runtime, qiskit-serverless und numpy als bring an. Die Umgebung enthält sie, lade also keine Wheels für sie hoch. Der Bericht zeigt clash nur bei einer exakten ==-Version an. Einen Bereich, wie >=0.10, zeigt er als baked an. Der Bericht lädt keine Dateien hoch.

Abhängigkeiten beheben

Problem	Ursache
pip install schlägt im Workflow fehl.	Der Job hat keinen Zugang zum Internet. Lade stattdessen ein Wheel hoch.
ModuleNotFoundError für ein Paket, das du hochgeladen hast.	Der Workflow importiert das Paket, bevor er install_uploaded_wheels() aufruft.
ModuleNotFoundError für eine Abhängigkeit eines Pakets, das du hochgeladen hast.	Wheels werden ohne ihre Abhängigkeiten installiert. Lade ein Wheel für die fehlende Abhängigkeit hoch.
Der Fehler besagt, dass ein Wheel is not a supported wheel on this platform.	Das Wheel ist für ein anderes Betriebssystem oder eine andere Python-Version. Besorge ein Wheel für Python 3.12 unter Linux x86_64.
install_uploaded_wheels() schlägt mit ResolutionImpossible fehl.	Der Ordner wheels enthält zwei Versionen desselben Pakets. Entferne das alte Wheel mit remove_wheels().
Ein CUDA-Paket, wie cupy, schlägt nach dem Hochladen von Wheels auf einem GPU-Rechenprofil fehl.	Ein Wheel hat eines der CUDA-Pakete ersetzt, die die Umgebung bereitstellt. Entferne dieses Wheel mit remove_wheels().
Ein installiertes Paket, wie numpy, schlägt nach dem Hochladen von Wheels fehl.	Ein Wheel hat eine zweite Kopie eines Pakets installiert, das die Umgebung bereitstellt. Entferne dieses Wheel mit remove_wheels().