Dichiara le dipendenze

Un workflow gestito viene eseguito in un ambiente Python che prepara in anticipo. Il job non può accedere a internet, quindi non può eseguire pip install per i pacchetti. Invece, Qiskit e un elenco di pacchetti supportati sono già installati, e puoi caricare wheel per qualsiasi altro pacchetto di cui il tuo workflow ha bisogno.

Controlla quali pacchetti sono installati

Ogni job viene eseguito con Python 3.12 su Linux (x86_64), con i seguenti pacchetti installati:

• qiskit, qiskit-ibm-runtime, qiskit-serverless e le loro dipendenze, come numpy.

• I pacchetti supportati, come qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim e pyscf. Ognuno è installato a una versione fissa.

Per vedere i pacchetti supportati e le loro versioni, chiama dependencies_versions() dal tuo notebook locale:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Il tuo workflow può importare uno qualsiasi di questi pacchetti senza alcuna configurazione. Il workflow li installa quando costruisce l'ambiente, non quando un job viene avviato, quindi non aumentano il tempo di avvio di un job.

Un workflow non legge un file requirements.txt o pyproject.toml, quindi non installa i pacchetti elencati in questi file. Anche l'argomento dependencies di ManagedWorkflow è deprecato e ignorato, quindi non installa pacchetti. Rimuovilo dal tuo codice di caricamento e carica invece le wheel.

Pacchetti nei profili di calcolo GPU

I job eseguiti su un profilo di calcolo GPU hanno installati anche i seguenti pacchetti CUDA. Questi pacchetti funzionano solo su un profilo GPU e dependencies_versions() non li elenca. Non caricare le tue wheel CUDA, perché sono in conflitto con queste versioni.

Pacchetto	Versione
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

Le versioni nvidia-*-cu12 possono cambiare quando l'ambiente viene ricostruito. Il codice che dipende dalla versione esatta di una libreria CUDA potrebbe richiedere aggiornamenti dopo una nuova release.

Richiedi un pacchetto

Se anche altri utenti avessero bisogno di un pacchetto, richiedilo su GitHub. Un pacchetto accettato viene aggiunto all'ambiente in una release successiva. Fino ad allora, o per un pacchetto privato, aggiungilo come wheel.

Aggiungi i tuoi pacchetti

Per usare un pacchetto che non è installato, raccogli i suoi file wheel sul tuo computer, caricali nell'archiviazione file del workflow e installali all'inizio del workflow. Li carichi di nuovo solo quando cambiano.

Crea le wheel

Il job installa le wheel senza una connessione a Internet, quindi ogni wheel deve funzionare con Python 3.12 su Linux (x86_64). Raccogli le wheel in una cartella:

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

Con --platform e --python-version, pip download scarica le wheel per la piattaforma del job, anche se lo esegui su macOS o Windows. Scarica anche le dipendenze del pacchetto, come python-dateutil, six e tzdata per pendulum. Poiché il job installa ogni wheel senza le sue dipendenze, carica una wheel per ogni dipendenza che manca nell'ambiente ed elimina dalla cartella le altre wheel.

Una wheel in puro Python (py3-none-any.whl) funziona su qualsiasi piattaforma. Se un pacchetto con codice compilato non ha una wheel Linux x86_64 su PyPI, creane una su Linux, ad esempio in un container python:3.12. Mantieni i nomi dei file originali, perché pip ricava da essi il nome del pacchetto, la versione e la piattaforma.

Carica le wheel

Carica le wheel dal tuo notebook locale con 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))

Ogni percorso può essere un nome di file o un pattern glob, e add_wheels() restituisce i nomi delle wheel caricate. Se un pattern non corrisponde ad alcun file, o corrisponde a un file che non è un file .whl, add_wheels() solleva una QiskitServerlessException.

Carica il workflow prima di aggiungere le wheel, perché le wheel vengono archiviate insieme a esso. Vanno in una cartella wheels nell'archiviazione file del workflow, separata dagli altri tuoi file.

Sostituisci o rimuovi le wheel

Per vedere le wheel caricate in un workflow, chiama list_wheels(). Per rimuovere le wheel, passa i loro nomi di file a 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"])

Per aggiornare un pacchetto, rimuovi la vecchia wheel e poi aggiungi quella nuova. Una nuova versione ha un nome di file diverso, quindi se mantieni la vecchia wheel, install_uploaded_wheels() installa entrambe le versioni.

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

Installa le wheel nel tuo workflow

Modifica il codice del tuo workflow per chiamare install_uploaded_wheels() prima che importi i pacchetti:

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() installa ogni wheel presente nella cartella wheels. Se il workflow non ha wheel, la chiamata non fa nulla. Le wheel vengono reinstallate a ogni esecuzione, quindi un grande insieme di wheel aumenta il tempo di avvio di ogni job.

Buona pratica: porta solo i pacchetti mancanti

Come buona pratica, carica le wheel solo per i pacchetti che mancano nell'ambiente. Una wheel per un pacchetto già installato, come numpy, installa una seconda copia, e il codice che lo importa può ottenere l'una o l'altra copia. Gli errori dovuti a una discordanza compaiono solo quando il job viene eseguito.

Prima di caricare, controlla i tuoi requisiti con dependency_report() dal tuo notebook locale:

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

Il report assegna a ogni requisito uno dei seguenti stati:

• baked: l'ambiente fornisce già il pacchetto. Non caricare una wheel per esso.

• bring: nell'ambiente manca il pacchetto. Carica una wheel per esso.

• clash: l'ambiente fornisce una versione diversa. Cambia la versione richiesta dal tuo codice, oppure ricostruisci il tuo pacchetto per la versione installata.

Il report controlla solo i pacchetti supportati, quindi mostra qiskit, qiskit-ibm-runtime, qiskit-serverless e numpy come bring. L'ambiente li include, quindi non caricare wheel per essi. Il report mostra clash solo per una versione esatta con ==. Mostra un intervallo, come >=0.10, come baked. Il report non carica alcun file.

Risolvi i problemi delle dipendenze

Problema	Causa
pip install fallisce all'interno del workflow.	Il job non può raggiungere Internet. Carica invece una wheel.
ModuleNotFoundError per un pacchetto che hai caricato.	Il workflow importa il pacchetto prima di chiamare install_uploaded_wheels().
ModuleNotFoundError per una dipendenza di un pacchetto che hai caricato.	Le wheel vengono installate senza le loro dipendenze. Carica una wheel per la dipendenza mancante.
L'errore dice che una wheel is not a supported wheel on this platform.	La wheel è per un altro sistema operativo o un'altra versione di Python. Ottieni una wheel per Python 3.12 su Linux x86_64.
install_uploaded_wheels() fallisce con ResolutionImpossible.	La cartella wheels contiene due versioni dello stesso pacchetto. Rimuovi la vecchia wheel con remove_wheels().
Un pacchetto CUDA, come cupy, fallisce su un profilo di calcolo GPU dopo aver caricato le wheel.	Una wheel ha sostituito uno dei pacchetti CUDA forniti dall'ambiente. Rimuovi quella wheel con remove_wheels().
Un pacchetto installato, come numpy, fallisce dopo aver caricato le wheel.	Una wheel ha installato una seconda copia di un pacchetto fornito dall'ambiente. Rimuovi quella wheel con remove_wheels().