Declare dependências

Um workflow gerenciado é executado em um ambiente Python que ele prepara com antecedência. O job não consegue acessar a internet, então não pode executar pip install em pacotes. Em vez disso, o Qiskit e uma lista de pacotes compatíveis já vêm instalados, e você pode enviar wheels de qualquer outro pacote de que seu workflow precise.

Verifique quais pacotes estão instalados

Todo job é executado com Python 3.12 em Linux (x86_64), com os seguintes pacotes instalados:

• qiskit, qiskit-ibm-runtime, qiskit-serverless e suas dependências, como numpy.

• Os pacotes compatíveis, como qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim e pyscf. Cada um é instalado em uma versão fixa.

Para ver os pacotes compatíveis e suas versões, chame dependencies_versions() no seu notebook local:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Seu workflow pode importar qualquer um desses pacotes sem configuração. O workflow os instala ao criar o ambiente, e não quando um job é iniciado, então eles não aumentam o tempo de início de um job.

Um workflow não lê um arquivo requirements.txt ou pyproject.toml, então não instala os pacotes que esses arquivos listam. O argumento dependencies de ManagedWorkflow está obsoleto e é ignorado, então ele também não instala pacotes. Remova-o do seu código de envio e envie wheels em vez disso.

Pacotes em perfis de computação com GPU

Jobs executados em um perfil de computação com GPU também têm os seguintes pacotes CUDA instalados. Esses pacotes funcionam apenas em um perfil com GPU, e dependencies_versions() não os lista. Não envie seus próprios wheels de CUDA, porque eles entram em conflito com essas versões.

Pacote	Versão
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

As versões nvidia-*-cu12 podem mudar quando o ambiente é reconstruído. O código que depende de uma versão exata de uma biblioteca CUDA pode precisar de atualizações após uma nova versão.

Solicite um pacote

Se outros usuários também precisarem de um pacote, solicite-o no GitHub. Um pacote aceito é adicionado ao ambiente em uma versão posterior. Até lá, ou no caso de um pacote privado, adicione-o como um wheel.

Adicione seus próprios pacotes

Para usar um pacote que não está instalado, reúna os arquivos wheel dele no seu computador, envie-os para o armazenamento de arquivos do fluxo de trabalho e instale-os no início do fluxo de trabalho. Você só precisa enviá-los novamente quando eles mudarem.

Crie wheels

O job instala wheels sem conexão com a internet, então cada wheel precisa funcionar com Python 3.12 em Linux (x86_64). Reúna os wheels em uma pasta:

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

Com --platform e --python-version, pip download obtém wheels para a plataforma do job, mesmo quando você o executa em macOS ou Windows. Ele também baixa as dependências do pacote, como python-dateutil, six e tzdata para pendulum. Como o job instala cada wheel sem as respectivas dependências, envie um wheel para cada dependência que o ambiente não tem e exclua os outros wheels da pasta.

Um wheel em Python puro (py3-none-any.whl) funciona em qualquer plataforma. Se um pacote com código compilado não tiver um wheel para Linux x86_64 no PyPI, crie um em Linux, por exemplo em um contêiner python:3.12. Mantenha os nomes de arquivo originais, porque pip lê o nome do pacote, a versão e a plataforma a partir deles.

Envie wheels

Envie os wheels do seu notebook local com 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 caminho pode ser um nome de arquivo ou um padrão glob, e add_wheels() retorna os nomes dos wheels enviados. Se um padrão não corresponder a nenhum arquivo, ou corresponder a um arquivo que não seja .whl, add_wheels() gera uma QiskitServerlessException.

Envie o fluxo de trabalho antes de adicionar wheels, porque os wheels são armazenados junto com ele. Eles vão para uma pasta wheels no armazenamento de arquivos do fluxo de trabalho, separada dos seus outros arquivos.

Substitua ou remova wheels

Para ver os wheels enviados para um fluxo de trabalho, chame list_wheels(). Para remover wheels, passe os nomes de arquivo deles para 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 atualizar um pacote, remova o wheel antigo e depois adicione o novo. Uma nova versão tem um nome de arquivo diferente, então, se você mantiver o wheel antigo, install_uploaded_wheels() instala as duas versões.

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

Instale wheels no seu fluxo de trabalho

Edite o código do seu fluxo de trabalho para chamar install_uploaded_wheels() antes de importar os pacotes:

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 os wheels da pasta wheels. Se o fluxo de trabalho não tiver wheels, a chamada não faz nada. Os wheels são instalados novamente em toda execução, então um grande conjunto de wheels aumenta o tempo de início de cada job.

Prática recomendada: leve apenas os pacotes que faltam

Como prática recomendada, envie wheels apenas para os pacotes que o ambiente não tem. Um wheel de um pacote já instalado, como numpy, instala uma segunda cópia, e o código que o importa pode receber qualquer uma das cópias. Os erros causados por essa incompatibilidade só aparecem quando o job é executado.

Antes de enviar, verifique seus requisitos com dependency_report() no seu 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

O relatório atribui a cada requisito um dos seguintes status:

• baked: o ambiente já fornece o pacote. Não envie um wheel para ele.

• bring: o ambiente não tem o pacote. Envie um wheel para ele.

• clash: o ambiente fornece uma versão diferente. Altere a versão exigida pelo seu código ou reconstrua seu pacote para a versão instalada.

O relatório verifica apenas os pacotes compatíveis, então mostra qiskit, qiskit-ibm-runtime, qiskit-serverless e numpy como bring. O ambiente os inclui, portanto não envie wheels para eles. O relatório mostra clash apenas para uma versão exata com ==. Ele mostra um intervalo, como >=0.10, como baked. O relatório não envia nenhum arquivo.

Solucione problemas de dependências

Problema	Causa
pip install falha dentro do fluxo de trabalho.	O job não consegue acessar a internet. Envie um wheel no lugar.
ModuleNotFoundError para um pacote que você enviou.	O fluxo de trabalho importa o pacote antes de chamar install_uploaded_wheels().
ModuleNotFoundError para uma dependência de um pacote que você enviou.	Os wheels são instalados sem suas dependências. Envie um wheel para a dependência que falta.
O erro diz que um wheel is not a supported wheel on this platform.	O wheel é para outro sistema operacional ou outra versão do Python. Obtenha um wheel para Python 3.12 em Linux x86_64.
install_uploaded_wheels() falha com ResolutionImpossible.	A pasta wheels tem duas versões do mesmo pacote. Remova o wheel antigo com remove_wheels().
Um pacote CUDA, como cupy, falha em um perfil de computação com GPU depois que você envia wheels.	Um wheel substituiu um dos pacotes CUDA que o ambiente fornece. Remova esse wheel com remove_wheels().
Um pacote instalado, como numpy, falha depois que você envia wheels.	Um wheel instalou uma segunda cópia de um pacote que o ambiente fornece. Remova esse wheel com remove_wheels().