Declarar dependencias

Un workflow gestionado se ejecuta en un entorno de Python que prepara de antemano. El trabajo no puede acceder a internet, así que no puede hacer pip install de paquetes. En su lugar, Qiskit y una lista de paquetes admitidos ya están instalados, y puedes subir wheels de cualquier otro paquete que necesite tu workflow.

Comprobar qué paquetes están instalados

Cada trabajo se ejecuta con Python 3.12 en Linux (x86_64), con los siguientes paquetes instalados:

• qiskit, qiskit-ibm-runtime, qiskit-serverless y sus dependencias, como numpy.

• Los paquetes admitidos, como qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim y pyscf. Cada uno se instala en una versión fija.

Para ver los paquetes admitidos y sus versiones, llama a dependencies_versions() desde tu notebook local:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Tu workflow puede importar cualquiera de estos paquetes sin configuración. El workflow los instala cuando construye el entorno, no cuando se inicia un trabajo, así que no se suman al tiempo de inicio de un trabajo.

Un workflow no lee un archivo requirements.txt ni pyproject.toml, así que no instala los paquetes que estos archivos enumeran. El argumento dependencies de ManagedWorkflow está obsoleto y se ignora, así que tampoco instala paquetes. Elimínalo del código de subida y sube wheels en su lugar.

Paquetes en perfiles de cómputo con GPU

Los trabajos que se ejecutan en un perfil de cómputo con GPU también tienen instalados los siguientes paquetes de CUDA. Estos paquetes solo funcionan en un perfil con GPU, y dependencies_versions() no los incluye en la lista. No subas tus propios wheels de CUDA, porque entran en conflicto con estas versiones.

Paquete	Versión
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

Las versiones de nvidia-*-cu12 pueden cambiar cuando se reconstruye el entorno. El código que depende de una versión exacta de una biblioteca de CUDA podría necesitar actualizaciones después de una nueva versión.

Solicitar un paquete

Si otros usuarios también necesitarían un paquete, solicítalo en GitHub. Un paquete aceptado se añade al entorno en una versión posterior. Mientras tanto, o si se trata de un paquete privado, añádelo como wheel.

Añadir tus propios paquetes

Para usar un paquete que no está instalado, reúne sus archivos wheel en tu computadora, súbelos al almacenamiento de archivos del workflow e instálalos al inicio del workflow. Solo tienes que subirlos de nuevo cuando cambien.

Crear wheels

El trabajo instala los wheels sin conexión a internet, por lo que cada wheel debe funcionar con Python 3.12 en Linux (x86_64). Reúne los wheels en una sola carpeta:

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 y --python-version, pip download obtiene wheels para la plataforma del trabajo, incluso cuando lo ejecutas en macOS o Windows. También descarga las dependencias del paquete, como python-dateutil, six y tzdata para pendulum. Como el trabajo instala cada wheel sin sus dependencias, sube un wheel para cada dependencia que le falte al entorno y elimina de la carpeta los demás wheels.

Un wheel de Python puro (py3-none-any.whl) funciona en cualquier plataforma. Si un paquete con código compilado no tiene un wheel para Linux x86_64 en PyPI, créalo en Linux, por ejemplo en un contenedor python:3.12. Conserva los nombres de archivo originales, porque pip lee de ellos el nombre del paquete, la versión y la plataforma.

Subir wheels

Sube los wheels desde tu notebook local 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))

Cada ruta puede ser un nombre de archivo o un patrón glob, y add_wheels() devuelve los nombres de los wheels subidos. Si un patrón no coincide con ningún archivo, o coincide con un archivo que no es .whl, add_wheels() lanza una QiskitServerlessException.

Sube el workflow antes de añadir wheels, porque los wheels se almacenan junto con él. Van a una carpeta wheels del almacenamiento de archivos del workflow, separada de tus demás archivos.

Reemplazar o eliminar wheels

Para ver los wheels que se han subido a un workflow, llama a list_wheels(). Para eliminar wheels, pasa sus nombres de archivo 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"])

Para actualizar un paquete, elimina el wheel antiguo y luego añade el nuevo. Una versión nueva tiene un nombre de archivo distinto, así que si conservas el wheel antiguo, install_uploaded_wheels() instala ambas versiones.

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

Instalar wheels en tu workflow

Edita el código de tu workflow para llamar a install_uploaded_wheels() antes de importar los paquetes:

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() instala todos los wheels de la carpeta wheels. Si el workflow no tiene wheels, la llamada no hace nada. Los wheels se instalan de nuevo en cada ejecución, por lo que un conjunto grande de wheels aumenta el tiempo de inicio de cada trabajo.

Práctica recomendada: aporta solo los paquetes que faltan

Como práctica recomendada, sube wheels solo para los paquetes que le faltan al entorno. Un wheel de un paquete ya instalado, como numpy, instala una segunda copia, y el código que lo importa puede obtener cualquiera de las dos. Los errores por esa discrepancia solo aparecen cuando se ejecuta el trabajo.

Antes de subir, comprueba tus requisitos con dependency_report() desde tu 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

El informe asigna a cada requisito uno de los siguientes estados:

• baked: El entorno ya incluye el paquete. No subas un wheel para él.

• bring: Al entorno le falta el paquete. Sube un wheel para él.

• clash: El entorno incluye una versión diferente. Cambia la versión que requiere tu código, o reconstruye tu paquete para la versión instalada.

El informe solo comprueba los paquetes admitidos, por lo que muestra qiskit, qiskit-ibm-runtime, qiskit-serverless y numpy como bring. El entorno los incluye, así que no subas wheels para ellos. El informe muestra clash solo para una versión exacta con ==. Muestra un rango, como >=0.10, como baked. El informe no sube ningún archivo.

Solucionar problemas de dependencias

Problema	Causa
pip install falla dentro del workflow.	El trabajo no puede acceder a internet. En su lugar, sube un wheel.
ModuleNotFoundError para un paquete que subiste.	El workflow importa el paquete antes de llamar a install_uploaded_wheels().
ModuleNotFoundError para una dependencia de un paquete que subiste.	Los wheels se instalan sin sus dependencias. Sube un wheel para la dependencia que falta.
El error dice que un wheel is not a supported wheel on this platform.	El wheel es para otro sistema operativo o versión de Python. Obtén un wheel para Python 3.12 en Linux x86_64.
install_uploaded_wheels() falla con ResolutionImpossible.	La carpeta wheels tiene dos versiones del mismo paquete. Elimina el wheel antiguo con remove_wheels().
Un paquete de CUDA, como cupy, falla en un perfil de cómputo con GPU después de subir wheels.	Un wheel reemplazó uno de los paquetes de CUDA que proporciona el entorno. Elimina ese wheel con remove_wheels().
Un paquete instalado, como numpy, falla después de subir wheels.	Un wheel instaló una segunda copia de un paquete que proporciona el entorno. Elimina ese wheel con remove_wheels().