Déclarer les dépendances

Un workflow géré s'exécute dans un environnement Python qu'il prépare à l'avance. Le job ne peut pas accéder à Internet, il ne peut donc pas faire de pip install de paquets. À la place, Qiskit et une liste de paquets pris en charge sont déjà installés, et tu peux téléverser des wheels pour tout autre paquet dont ton workflow a besoin.

Vérifier quels paquets sont installés

Chaque job s'exécute avec Python 3.12 sous Linux (x86_64), avec les paquets suivants installés :

• qiskit, qiskit-ibm-runtime, qiskit-serverless et leurs dépendances, comme numpy.

• Les paquets pris en charge, comme qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim et pyscf. Chacun est installé dans une version fixe.

Pour voir les paquets pris en charge et leurs versions, appelle dependencies_versions() depuis ton notebook local :

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Ton workflow peut importer n'importe lequel de ces paquets sans configuration. Le workflow les installe lorsqu'il construit l'environnement, et non au démarrage d'un job, donc ils n'allongent pas le temps de démarrage d'un job.

Un workflow ne lit pas de fichier requirements.txt ni pyproject.toml, il n'installe donc pas les paquets que ces fichiers listent. L'argument dependencies de ManagedWorkflow est obsolète et ignoré, il n'installe donc pas non plus de paquets. Supprime-le de ton code de téléversement, et téléverse plutôt des wheels.

Paquets sur les profils de calcul GPU

Les jobs qui s'exécutent sur un profil de calcul GPU ont aussi les paquets CUDA suivants installés. Ces paquets fonctionnent uniquement sur un profil GPU, et dependencies_versions() ne les liste pas. Ne téléverse pas tes propres wheels CUDA, car elles entrent en conflit avec ces versions.

Paquet	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

Les versions nvidia-*-cu12 peuvent changer lorsque l'environnement est reconstruit. Le code qui dépend d'une version exacte d'une bibliothèque CUDA peut nécessiter des mises à jour après une nouvelle version.

Demander un paquet

Si d'autres utilisateurs ont aussi besoin d'un paquet, demande-le sur GitHub. Un paquet accepté est ajouté à l'environnement dans une version ultérieure. D'ici là, ou pour un paquet privé, ajoute-le sous forme de wheel.

Ajouter tes propres paquets

Pour utiliser un paquet qui n'est pas installé, rassemble ses fichiers wheel sur ton ordinateur, téléverse-les dans le stockage de fichiers du workflow, et installe-les au début du workflow. Tu ne les téléverses à nouveau que lorsqu'ils changent.

Construire des wheels

Le job installe les wheels sans connexion Internet, donc chaque wheel doit fonctionner avec Python 3.12 sur Linux (x86_64). Rassemble les wheels dans un seul dossier :

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

Avec --platform et --python-version, pip download récupère les wheels pour la plateforme du job, même si tu l'exécutes sur macOS ou Windows. Il télécharge aussi les dépendances du paquet, comme python-dateutil, six et tzdata pour pendulum. Comme le job installe chaque wheel sans ses dépendances, téléverse une wheel pour chaque dépendance qui manque à l'environnement, et supprime les autres wheels du dossier.

Une wheel en Python pur (py3-none-any.whl) fonctionne sur n'importe quelle plateforme. Si un paquet contenant du code compilé n'a pas de wheel Linux x86_64 sur PyPI, construis-en une sur Linux, par exemple dans un conteneur python:3.12. Conserve les noms de fichiers d'origine, car pip y lit le nom du paquet, la version et la plateforme.

Téléverser des wheels

Téléverse les wheels depuis ton notebook local avec add_wheels() :

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

Chaque chemin peut être un nom de fichier ou un motif glob, et add_wheels() renvoie les noms des wheels téléversées. Si un motif ne correspond à aucun fichier, ou correspond à un fichier qui n'est pas un fichier .whl, add_wheels() lève une QiskitServerlessException.

Téléverse le workflow avant d'ajouter des wheels, car les wheels sont stockées avec lui. Elles vont dans un dossier wheels du stockage de fichiers du workflow, séparé de tes autres fichiers.

Remplacer ou supprimer des wheels

Pour voir les wheels téléversées dans un workflow, appelle list_wheels(). Pour supprimer des wheels, passe leurs noms de fichiers à 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"])

Pour mettre à niveau un paquet, supprime l'ancienne wheel, puis ajoute la nouvelle. Une nouvelle version a un nom de fichier différent ; si tu conserves l'ancienne wheel, install_uploaded_wheels() installe donc les deux versions.

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"])

Installer les wheels dans ton workflow

Modifie le code de ton workflow pour appeler install_uploaded_wheels() avant qu'il importe les paquets :

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() installe chaque wheel du dossier wheels. Si le workflow n'a aucune wheel, l'appel ne fait rien. Les wheels sont réinstallées à chaque exécution, donc un grand nombre de wheels allonge le temps de démarrage de chaque job.

Bonne pratique : n'apporte que les paquets manquants

Par bonne pratique, téléverse des wheels uniquement pour les paquets qui manquent à l'environnement. Une wheel pour un paquet déjà installé, comme numpy, installe une seconde copie, et le code qui l'importe peut obtenir l'une ou l'autre copie. Les erreurs dues à une incompatibilité n'apparaissent qu'à l'exécution du job.

Avant de téléverser, vérifie tes dépendances avec dependency_report() depuis ton notebook local :

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

Le rapport attribue à chaque dépendance l'un des statuts suivants :

• baked : l'environnement fournit déjà le paquet. Ne téléverse pas de wheel pour celui-ci.

• bring : l'environnement ne contient pas le paquet. Téléverse une wheel pour celui-ci.

• clash : l'environnement fournit une version différente. Change la version que ton code requiert, ou reconstruis ton paquet pour la version installée.

Le rapport ne vérifie que les paquets pris en charge, il affiche donc qiskit, qiskit-ibm-runtime, qiskit-serverless et numpy comme bring. L'environnement les inclut, donc ne téléverse pas de wheels pour eux. Le rapport affiche clash uniquement pour une version exacte avec ==. Il affiche une plage, comme >=0.10, comme baked. Le rapport ne téléverse aucun fichier.

Dépanner les dépendances

Problème	Cause
pip install échoue dans le workflow.	Le job ne peut pas accéder à Internet. Téléverse plutôt une wheel.
ModuleNotFoundError pour un paquet que tu as téléversé.	Le workflow importe le paquet avant d'appeler install_uploaded_wheels().
ModuleNotFoundError pour une dépendance d'un paquet que tu as téléversé.	Les wheels sont installées sans leurs dépendances. Téléverse une wheel pour la dépendance manquante.
L'erreur indique qu'une wheel is not a supported wheel on this platform.	La wheel est destinée à un autre système d'exploitation ou à une autre version de Python. Obtiens une wheel pour Python 3.12 sur Linux x86_64.
install_uploaded_wheels() échoue avec ResolutionImpossible.	Le dossier wheels contient deux versions du même paquet. Supprime l'ancienne wheel avec remove_wheels().
Un paquet CUDA, comme cupy, échoue sur un profil de calcul GPU après le téléversement de wheels.	Une wheel a remplacé l'un des paquets CUDA que fournit l'environnement. Supprime cette wheel avec remove_wheels().
Un paquet installé, comme numpy, échoue après le téléversement de wheels.	Une wheel a installé une seconde copie d'un paquet que fournit l'environnement. Supprime cette wheel avec remove_wheels().