Declară dependențele

Un workflow gestionat rulează într-un mediu Python pe care îl pregătește în avans. Jobul nu are acces la internet, deci nu poate face pip install de pachete. În schimb, Qiskit și o listă de pachete acceptate sunt deja instalate, iar pentru orice alt pachet de care are nevoie workflow-ul tău poți încărca wheel-uri.

Verifică ce pachete sunt instalate

Fiecare job rulează cu Python 3.12 pe Linux (x86_64), cu următoarele pachete instalate:

• qiskit, qiskit-ibm-runtime, qiskit-serverless și dependențele lor, cum ar fi numpy.

• Pachetele acceptate, cum ar fi qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim și pyscf. Fiecare este instalat la o versiune fixă.

Pentru a vedea pachetele acceptate și versiunile lor, apelează dependencies_versions() din notebookul tău local:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Workflow-ul tău poate importa oricare dintre aceste pachete fără configurare. Workflow-ul le instalează când construiește mediul, nu când pornește un job, deci nu adaugă timp la pornirea unui job.

Un workflow nu citește un fișier requirements.txt sau pyproject.toml, deci nu instalează pachetele listate în aceste fișiere. Argumentul dependencies al ManagedWorkflow este depreciat și ignorat, deci nici el nu instalează pachete. Elimină-l din codul tău de încărcare și încarcă wheel-uri în schimb.

Pachete pe profiluri de calcul cu GPU

Joburile care rulează pe un profil de calcul GPU au instalate și următoarele pachete CUDA. Aceste pachete funcționează doar pe un profil GPU, iar dependencies_versions() nu le listează. Nu încărca propriile wheel-uri CUDA, deoarece intră în conflict cu aceste versiuni.

Pachet	Versiune
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

Versiunile nvidia-*-cu12 se pot schimba când mediul este reconstruit. Codul care depinde de o versiune exactă a unei biblioteci CUDA ar putea necesita actualizări după o nouă versiune.

Solicită un pachet

Dacă și alți utilizatori ar avea nevoie de un pachet, solicită-l pe GitHub. Un pachet acceptat este adăugat în mediu într-o versiune ulterioară. Până atunci, sau pentru un pachet privat, adaugă-l ca wheel.

Adaugă propriile pachete

Pentru a folosi un pachet care nu este instalat, adună fișierele wheel ale acestuia pe computerul tău, încarcă-le în stocarea de fișiere a workflow-ului și instalează-le la începutul workflow-ului. Le încarci din nou doar când se schimbă.

Construiește wheel-uri

Jobul instalează wheel-urile fără conexiune la internet, deci fiecare wheel trebuie să funcționeze cu Python 3.12 pe Linux (x86_64). Adună wheel-urile într-un singur folder:

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

Cu --platform și --python-version, pip download obține wheel-uri pentru platforma jobului, chiar dacă îl rulezi pe macOS sau Windows. Descarcă și dependențele pachetului, precum python-dateutil, six și tzdata pentru pendulum. Deoarece jobul instalează fiecare wheel fără dependențele sale, încarcă un wheel pentru fiecare dependență pe care mediul nu o are și șterge celelalte wheel-uri din folder.

Un wheel pur Python (py3-none-any.whl) funcționează pe orice platformă. Dacă un pachet cu cod compilat nu are wheel Linux x86_64 pe PyPI, construiește unul pe Linux, de exemplu într-un container python:3.12. Păstrează numele originale ale fișierelor, deoarece pip citește din ele numele pachetului, versiunea și platforma.

Încarcă wheel-uri

Încarcă wheel-urile din notebookul tău local cu 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))

Fiecare cale poate fi un nume de fișier sau un tipar glob, iar add_wheels() returnează numele wheel-urilor încărcate. Dacă un tipar nu se potrivește cu niciun fișier sau se potrivește cu un fișier care nu este .whl, add_wheels() ridică o QiskitServerlessException.

Încarcă workflow-ul înainte de a adăuga wheel-uri, deoarece wheel-urile sunt stocate împreună cu el. Ele merg într-un folder wheels din stocarea de fișiere a workflow-ului, separat de celelalte fișiere ale tale.

Înlocuiește sau elimină wheel-uri

Pentru a vedea wheel-urile încărcate într-un workflow, apelează list_wheels(). Pentru a elimina wheel-uri, transmite numele fișierelor lor către 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"])

Pentru a actualiza un pachet, elimină wheel-ul vechi și apoi adaugă-l pe cel nou. O versiune nouă are alt nume de fișier, deci dacă păstrezi wheel-ul vechi, install_uploaded_wheels() le instalează pe ambele versiuni.

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

Instalează wheel-uri în workflow-ul tău

Modifică codul workflow-ului tău pentru a apela install_uploaded_wheels() înainte de a importa pachetele:

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() instalează fiecare wheel din folderul wheels. Dacă workflow-ul nu are wheel-uri, apelul nu face nimic. Wheel-urile sunt instalate din nou la fiecare rulare, deci un set mare de wheel-uri adaugă timp la pornirea fiecărui job.

Bună practică: adu doar pachetele lipsă

Ca bună practică, încarcă wheel-uri doar pentru pachetele pe care mediul nu le are. Un wheel pentru un pachet deja instalat, precum numpy, instalează o a doua copie, iar codul care îl importă poate primi oricare dintre copii. Erorile cauzate de nepotrivire apar doar când rulează jobul.

Înainte de încărcare, verifică cerințele cu dependency_report() din notebookul tău 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

Raportul atribuie fiecărei cerințe unul dintre următoarele statusuri:

• baked: Mediul oferă deja pachetul. Nu încărca un wheel pentru el.

• bring: Mediului îi lipsește pachetul. Încarcă un wheel pentru el.

• clash: Mediul oferă o versiune diferită. Schimbă versiunea cerută de codul tău sau reconstruiește-ți pachetul pentru versiunea instalată.

Raportul verifică doar pachetele suportate, deci arată qiskit, qiskit-ibm-runtime, qiskit-serverless și numpy ca bring. Mediul le include, deci nu încărca wheel-uri pentru ele. Raportul arată clash doar pentru o versiune exactă ==. Pentru un interval, precum >=0.10, arată baked. Raportul nu încarcă niciun fișier.

Depanează dependențele

Problemă	Cauză
pip install eșuează în interiorul workflow-ului.	Jobul nu poate accesa internetul. Încarcă un wheel în schimb.
ModuleNotFoundError pentru un pachet pe care l-ai încărcat.	Workflow-ul importă pachetul înainte de a apela install_uploaded_wheels().
ModuleNotFoundError pentru o dependență a unui pachet pe care l-ai încărcat.	Wheel-urile sunt instalate fără dependențele lor. Încarcă un wheel pentru dependența lipsă.
Eroarea spune că un wheel is not a supported wheel on this platform.	Wheel-ul este pentru alt sistem de operare sau altă versiune de Python. Obține un wheel pentru Python 3.12 pe Linux x86_64.
install_uploaded_wheels() eșuează cu ResolutionImpossible.	Folderul wheels are două versiuni ale aceluiași pachet. Elimină wheel-ul vechi cu remove_wheels().
Un pachet CUDA, precum cupy, eșuează pe un profil de calcul GPU după ce ai încărcat wheel-uri.	Un wheel a înlocuit unul dintre pachetele CUDA oferite de mediu. Elimină acel wheel cu remove_wheels().
Un pachet instalat, precum numpy, eșuează după ce ai încărcat wheel-uri.	Un wheel a instalat o a doua copie a unui pachet oferit de mediu. Elimină acel wheel cu remove_wheels().