التصريح بالاعتماديات

يعمل سير العمل المُدار في بيئة Python يجهزها مسبقًا. لا تستطيع المهمة الوصول إلى الإنترنت، لذا لا يمكنها تنفيذ pip install للحزم. بدلًا من ذلك، يكون Qiskit وقائمة من الحزم المدعومة مثبّتين مسبقًا، ويمكنك رفع ملفات wheel لأي حزمة أخرى يحتاجها سير العمل.

التحقق من الحزم المثبّتة

تعمل كل مهمة بـ Python 3.12 على Linux (x86_64)، مع تثبيت الحزم التالية:

• qiskit وqiskit-ibm-runtime وqiskit-serverless واعتمادياتها، مثل numpy.

• الحزم المدعومة، مثل qiskit-aer وqiskit-addon-sqd وqiskit-addon-utils وqiskit-mitigation وqiskit-addon-slc وqiskit-paulice وffsim وpyscf. كل منها مثبّتة بإصدار ثابت واحد.

لرؤية الحزم المدعومة وإصداراتها، استدعِ dependencies_versions() من دفتر الملاحظات المحلي:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.dependencies_versions()

يمكن لسير العمل استيراد أي من هذه الحزم بدون إعداد. يثبّتها سير العمل عند بناء البيئة، وليس عند بدء مهمة، لذا فهي لا تضيف إلى وقت بدء المهمة.

لا يقرأ سير العمل ملف requirements.txt أو pyproject.toml، لذا لا يثبّت الحزم المدرجة في هذه الملفات. الوسيط dependencies في ManagedWorkflow مهجور ويُتجاهل، لذا لا يثبّت حزمًا أيضًا. أزله من كود الرفع الخاص بك، وارفع ملفات wheel بدلًا من ذلك.

الحزم في ملفات حوسبة GPU

الوظائف التي تعمل على ملف حوسبة GPU تأتي أيضًا مع حزم CUDA التالية مثبّتة. هذه الحزم تعمل فقط على ملف GPU، وdependencies_versions() لا يعرضها. لا ترفع حزم CUDA الخاصة بك (wheels)، لأنها تتعارض مع هذه الإصدارات.

الحزمة	الإصدار
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

إصدارات nvidia-*-cu12 ممكن تتغير لما يُعاد بناء البيئة. الكود اللي يعتمد على إصدار محدد من مكتبة CUDA ممكن يحتاج تحديثات بعد إصدار جديد.

اطلب حزمة

إذا كان مستخدمون آخرون يحتاجون الحزمة أيضًا، اطلبها على GitHub. الحزمة المقبولة تُضاف إلى البيئة في إصدار لاحق. وإلى ذلك الحين، أو للحزم الخاصة، أضفها كـ wheel.

أضف حزمك الخاصة

لاستخدام حزمة غير مثبّتة، اجمع ملفات wheel الخاصة بها على جهازك، وارفعها إلى مساحة تخزين ملفات سير العمل، وثبّتها في بداية سير العمل. ترفعها مرة ثانية فقط لما تتغير.

ابنِ ملفات wheel

الوظيفة تثبّت ملفات wheel بدون اتصال بالإنترنت، فلازم يشتغل كل wheel مع Python 3.12 على Linux (x86_64). اجمع ملفات wheel في مجلد واحد:

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

مع --platform و--python-version، يجلب pip download ملفات wheel الخاصة بمنصة الوظيفة، حتى لو شغّلته على macOS أو Windows. وهو ينزّل أيضًا اعتماديات الحزمة، مثل python-dateutil وsix وtzdata للحزمة pendulum. بما أن الوظيفة تثبّت كل wheel بدون اعتمادياته، ارفع wheel لكل اعتمادية تنقص البيئة، واحذف باقي ملفات wheel من المجلد.

ملف wheel بلغة Python الصرفة (py3-none-any.whl) يشتغل على أي منصة. إذا لم يكن لحزمة فيها كود مُترجَم wheel لـ Linux x86_64 على PyPI، ابنِ واحدًا على Linux، مثلًا داخل حاوية python:3.12. احتفظ بأسماء الملفات الأصلية، لأن pip يقرأ اسم الحزمة والإصدار والمنصة منها.

ارفع ملفات wheel

ارفع ملفات wheel من دفتر الملاحظات المحلي باستخدام 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))

كل مسار ممكن يكون اسم ملف أو نمط glob، وadd_wheels() يرجع أسماء ملفات wheel المرفوعة. إذا لم يطابق النمط أي ملف، أو طابق ملفًا ليس ملف .whl، يرفع add_wheels() الاستثناء QiskitServerlessException.

ارفع سير العمل قبل ما تضيف ملفات wheel، لأنها تُخزَّن معه. تذهب إلى مجلد wheels في تخزين ملفات سير العمل، منفصلة عن ملفاتك الأخرى.

استبدل ملفات wheel أو احذفها

لعرض ملفات wheel المرفوعة إلى سير عمل، استدعِ list_wheels(). ولحذفها، مرّر أسماء ملفاتها إلى 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"])

لترقية حزمة، احذف الـ wheel القديم، ثم أضف الجديد. الإصدار الجديد له اسم ملف مختلف، فإذا أبقيت الـ wheel القديم، سيثبّت install_uploaded_wheels() الإصدارين معًا.

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

ثبّت ملفات wheel في سير العمل

عدّل كود سير العمل ليستدعي install_uploaded_wheels() قبل استيراد الحزم:

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() يثبّت كل wheel في مجلد wheels. إذا لم يكن لسير العمل أي ملفات wheel، لا يفعل الاستدعاء شيئًا. تُثبَّت ملفات wheel من جديد في كل تشغيل، فمجموعة كبيرة منها تزيد وقت بدء كل وظيفة.

أفضل ممارسة: أحضر الحزم الناقصة فقط

كأفضل ممارسة، ارفع ملفات wheel فقط للحزم التي تنقص البيئة. wheel لحزمة مثبّتة أصلًا، مثل numpy، يثبّت نسخة ثانية، والكود اللي يستوردها ممكن ياخذ أي من النسختين. الأخطاء الناتجة عن عدم التطابق تظهر فقط عند تشغيل الوظيفة.

قبل الرفع، تحقق من متطلباتك باستخدام dependency_report() من دفتر الملاحظات المحلي:

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

يعطي التقرير كل متطلب واحدة من الحالات التالية:

• baked: البيئة توفّر الحزمة أصلًا. لا ترفع wheel لها.

• bring: البيئة تنقصها الحزمة. ارفع wheel لها.

• clash: البيئة توفّر إصدارًا مختلفًا. غيّر الإصدار الذي يتطلبه كودك، أو أعد بناء حزمتك للإصدار المثبّت.

التقرير يفحص فقط الحزم المدعومة، لذلك يعرض qiskit وqiskit-ibm-runtime وqiskit-serverless وnumpy كـ bring. البيئة تتضمنها، فلا ترفع ملفات wheel لها. التقرير يعرض clash فقط للإصدار الدقيق ==. أما النطاق، مثل >=0.10، فيعرضه كـ baked. التقرير لا يرفع أي ملفات.

استكشاف أخطاء الاعتماديات وإصلاحها

المشكلة	السبب
pip install يفشل داخل سير العمل.	الوظيفة لا تستطيع الوصول إلى الإنترنت. ارفع wheel بدلًا من ذلك.
ModuleNotFoundError لحزمة رفعتها.	سير العمل يستورد الحزمة قبل أن يستدعي install_uploaded_wheels().
ModuleNotFoundError لاعتمادية تابعة لحزمة رفعتها.	ملفات wheel تُثبَّت بدون اعتمادياتها. ارفع wheel للاعتمادية الناقصة.
الخطأ يقول إن wheel is not a supported wheel on this platform.	الـ wheel مخصص لنظام تشغيل أو إصدار Python آخر. احصل على wheel لـ Python 3.12 على Linux x86_64.
install_uploaded_wheels() يفشل مع ResolutionImpossible.	مجلد wheels فيه إصداران من نفس الحزمة. احذف الـ wheel القديم باستخدام remove_wheels().
حزمة CUDA، مثل cupy، تفشل على ملف حوسبة GPU بعد رفع ملفات wheel.	wheel استبدل إحدى حزم CUDA التي توفرها البيئة. احذف ذلك الـ wheel باستخدام remove_wheels().
حزمة مثبّتة، مثل numpy، تفشل بعد رفع ملفات wheel.	wheel ثبّت نسخة ثانية من حزمة توفرها البيئة. احذف ذلك الـ wheel باستخدام remove_wheels().