Deklarasikan dependensi

Managed workflow berjalan di lingkungan Python yang disiapkannya lebih dulu. Job tidak bisa mengakses internet, jadi tidak bisa pip install paket. Sebagai gantinya, Qiskit dan daftar paket yang didukung sudah terpasang, dan kamu bisa mengunggah wheel untuk paket lain yang dibutuhkan workflow kamu.

Cek paket apa saja yang terpasang

Setiap job berjalan dengan Python 3.12 di Linux (x86_64), dengan paket berikut terpasang:

• qiskit, qiskit-ibm-runtime, qiskit-serverless, dan dependensinya, seperti numpy.

• Paket yang didukung, seperti qiskit-aer, qiskit-addon-sqd, qiskit-addon-utils, qiskit-mitigation, qiskit-addon-slc, qiskit-paulice, ffsim, dan pyscf. Masing-masing terpasang pada satu versi tetap.

Untuk melihat paket yang didukung beserta versinya, panggil dependencies_versions() dari notebook lokal kamu:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

Workflow kamu bisa mengimpor paket mana pun dari ini tanpa penyiapan. Workflow memasangnya saat membangun lingkungan, bukan saat job dimulai, jadi paket-paket ini tidak menambah waktu mulai job.

Workflow tidak membaca file requirements.txt atau pyproject.toml, jadi tidak memasang paket yang tercantum di file-file itu. Argumen dependencies dari ManagedWorkflow sudah deprecated dan diabaikan, jadi juga tidak memasang paket. Hapus dari kode unggahan kamu, dan unggah wheel sebagai gantinya.

Paket di compute profile GPU

Job yang berjalan di compute profile GPU juga memiliki paket CUDA berikut yang terpasang. Paket-paket ini hanya bekerja di profile GPU, dan dependencies_versions() tidak mendaftarkannya. Jangan unggah wheel CUDA sendiri, karena akan bentrok dengan versi ini.

Paket	Versi
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

Versi nvidia-*-cu12 bisa berubah saat lingkungan dibangun ulang. Kode yang bergantung pada versi library CUDA yang persis mungkin perlu diperbarui setelah rilis baru.

Minta sebuah paket

Kalau pengguna lain juga akan membutuhkan sebuah paket, minta di GitHub. Paket yang diterima akan ditambahkan ke lingkungan di rilis berikutnya. Sampai saat itu, atau untuk paket privat, tambahkan sebagai wheel.

Tambahkan paket kamu sendiri

Untuk memakai paket yang belum terpasang, kumpulkan file wheel-nya di komputer kamu, unggah ke penyimpanan file workflow, dan pasang di awal workflow. Kamu hanya perlu mengunggahnya lagi kalau isinya berubah.

Bangun wheel

Job memasang wheel tanpa koneksi internet, jadi setiap wheel harus bisa jalan dengan Python 3.12 di Linux (x86_64). Kumpulkan wheel dalam satu 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

Dengan --platform dan --python-version, pip download mengambil wheel untuk platform job, bahkan saat kamu menjalankannya di macOS atau Windows. Perintah ini juga mengunduh dependensi paketnya, seperti python-dateutil, six, dan tzdata untuk pendulum. Karena job memasang setiap wheel tanpa dependensinya, unggah wheel untuk setiap dependensi yang tidak ada di lingkungan, dan hapus wheel lainnya dari folder.

Wheel pure-Python (py3-none-any.whl) bekerja di platform mana pun. Kalau paket dengan kode terkompilasi tidak punya wheel Linux x86_64 di PyPI, bangun satu di Linux, misalnya di container python:3.12. Pertahankan nama file aslinya, karena pip membaca nama paket, versi, dan platform dari nama itu.

Unggah wheel

Unggah wheel dari notebook lokalmu dengan 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))

Setiap path bisa berupa nama file atau pola glob, dan add_wheels() mengembalikan nama wheel yang diunggah. Kalau sebuah pola tidak cocok dengan file apa pun, atau cocok dengan file yang bukan file .whl, add_wheels() akan memunculkan QiskitServerlessException.

Unggah workflow sebelum menambahkan wheel, karena wheel disimpan bersama workflow. Wheel masuk ke folder wheels di penyimpanan file milik workflow, terpisah dari file lainmu.

Ganti atau hapus wheel

Untuk melihat wheel yang sudah diunggah ke sebuah workflow, panggil list_wheels(). Untuk menghapus wheel, berikan nama file-nya ke 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"])

Untuk meng-upgrade sebuah paket, hapus wheel lama, lalu tambahkan yang baru. Versi baru punya nama file yang berbeda, jadi kalau wheel lama tetap ada, install_uploaded_wheels() akan memasang kedua versi.

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

Pasang wheel di workflow-mu

Ubah kode workflow-mu agar memanggil install_uploaded_wheels() sebelum mengimpor paket:

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() memasang setiap wheel di folder wheels. Kalau workflow tidak punya wheel, panggilan ini tidak melakukan apa-apa. Wheel dipasang ulang di setiap run, jadi kumpulan wheel yang besar akan menambah waktu mulai setiap job.

Praktik terbaik: bawa hanya paket yang belum ada

Sebagai praktik terbaik, unggah wheel hanya untuk paket yang tidak ada di environment. Wheel untuk paket yang sudah terpasang, seperti numpy, akan memasang salinan kedua, dan kode yang mengimpornya bisa mendapat salah satu salinan. Error akibat ketidakcocokan baru muncul saat job berjalan.

Sebelum mengunggah, periksa requirement-mu dengan dependency_report() dari notebook lokalmu:

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

Laporan memberi setiap requirement salah satu status berikut:

• baked: Environment sudah menyediakan paket tersebut. Jangan unggah wheel untuknya.

• bring: Environment tidak punya paket tersebut. Unggah wheel untuknya.

• clash: Environment menyediakan versi yang berbeda. Ubah versi yang dibutuhkan kodemu, atau build ulang paketmu untuk versi yang terpasang.

Laporan hanya memeriksa paket yang didukung, jadi qiskit, qiskit-ibm-runtime, qiskit-serverless, dan numpy ditampilkan sebagai bring. Environment sudah menyertakannya, jadi jangan unggah wheel untuk paket-paket itu. Laporan menampilkan clash hanya untuk versi == yang persis. Untuk rentang, seperti >=0.10, laporan menampilkannya sebagai baked. Laporan ini tidak mengunggah file apa pun.

Atasi masalah dependensi

Masalah	Penyebab
pip install gagal di dalam workflow.	Job tidak bisa mengakses internet. Unggah wheel saja.
ModuleNotFoundError untuk paket yang sudah kamu unggah.	Workflow mengimpor paket sebelum memanggil install_uploaded_wheels().
ModuleNotFoundError untuk dependensi dari paket yang sudah kamu unggah.	Wheel dipasang tanpa dependensinya. Unggah wheel untuk dependensi yang hilang.
Error menyebut wheel is not a supported wheel on this platform.	Wheel itu untuk sistem operasi atau versi Python yang lain. Gunakan wheel untuk Python 3.12 di Linux x86_64.
install_uploaded_wheels() gagal dengan ResolutionImpossible.	Folder wheels berisi dua versi dari paket yang sama. Hapus wheel lama dengan remove_wheels().
Paket CUDA, seperti cupy, gagal di compute profile GPU setelah kamu mengunggah wheel.	Sebuah wheel menggantikan salah satu paket CUDA yang disediakan environment. Hapus wheel itu dengan remove_wheels().
Paket yang terpasang, seperti numpy, gagal setelah kamu mengunggah wheel.	Sebuah wheel memasang salinan kedua dari paket yang sudah disediakan environment. Hapus wheel itu dengan remove_wheels().