종속성 선언

관리형 워크플로는 미리 준비된 Python 환경에서 실행됩니다. 작업은 인터넷에 접근할 수 없으므로 pip install로 패키지를 설치할 수 없습니다. 대신 Qiskit과 지원되는 패키지 목록이 이미 설치되어 있으며, 워크플로에 필요한 다른 패키지는 wheel을 업로드할 수 있습니다.

설치된 패키지 확인

모든 작업은 Linux(x86_64)의 Python 3.12에서 실행되며, 다음 패키지가 설치되어 있습니다.

• 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()

워크플로는 설정 없이 이러한 패키지를 모두 import할 수 있습니다. 워크플로는 작업이 시작될 때가 아니라 환경을 빌드할 때 이 패키지를 설치하므로, 작업의 시작 시간이 늘어나지 않습니다.

워크플로는 requirements.txt 또는 pyproject.toml 파일을 읽지 않으므로, 이러한 파일에 나열된 패키지를 설치하지 않습니다. ManagedWorkflow의 dependencies 인수는 더 이상 사용되지 않으며 무시되므로 이것도 패키지를 설치하지 않습니다. 업로드 코드에서 이를 제거하고 대신 wheel을 업로드하세요.

GPU 컴퓨트 프로필의 패키지

GPU 컴퓨트 프로필에서 실행되는 작업에는 다음 CUDA 패키지도 설치되어 있습니다. 이 패키지는 GPU 프로필에서만 작동하며, dependencies_versions()는 이를 나열하지 않습니다. 이 버전과 충돌하므로 직접 CUDA wheel을 업로드하지 마세요.

패키지	버전
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을 설치하므로, 각 wheel은 Linux(x86_64)의 Python 3.12에서 작동해야 합니다. 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을 사용하면, macOS 또는 Windows에서 실행하더라도 pip download가 작업의 플랫폼용 wheel을 가져옵니다. 또한 pendulum의 python-dateutil, six, tzdata처럼 패키지의 종속성도 다운로드합니다. 작업은 각 wheel을 종속성 없이 설치하므로, 환경에 없는 모든 종속성의 wheel을 업로드하고 폴더의 나머지 wheel은 삭제하세요.

순수 Python wheel(py3-none-any.whl)은 모든 플랫폼에서 작동합니다. 컴파일된 코드가 있는 패키지에 PyPI의 Linux x86_64 wheel이 없다면, 예를 들어 python:3.12 컨테이너와 같은 Linux에서 빌드하세요. pip가 파일 이름에서 패키지 이름, 버전, 플랫폼을 읽으므로 원래 파일 이름을 유지하세요.

wheel 업로드

로컬 노트북에서 add_wheels()로 wheel을 업로드하세요.

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은 워크플로와 함께 저장되므로 wheel을 추가하기 전에 워크플로를 업로드하세요. wheel은 다른 파일과 분리되어 워크플로의 파일 스토리지에 있는 wheels 폴더로 들어갑니다.

wheel 교체 또는 제거

워크플로에 업로드된 wheel을 보려면 list_wheels()를 호출하세요. wheel을 제거하려면 파일 이름을 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을 추가하세요. 새 버전은 파일 이름이 다르므로, 이전 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 설치

패키지를 import하기 전에 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()는 wheels 폴더에 있는 모든 wheel을 설치합니다. 워크플로에 wheel이 없으면 이 호출은 아무 일도 하지 않습니다. wheel은 실행할 때마다 다시 설치되므로, wheel이 많으면 각 작업의 시작 시간이 늘어납니다.

모범 사례: 없는 패키지만 가져오기

모범 사례로, 환경에 없는 패키지의 wheel만 업로드하세요. numpy처럼 이미 설치된 패키지의 wheel을 올리면 사본이 하나 더 설치되고, 이를 import하는 코드는 두 사본 중 어느 쪽이든 가져올 수 있습니다. 불일치로 인한 오류는 작업이 실행될 때에야 나타납니다.

업로드하기 전에 로컬 노트북에서 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()를 호출하기 전에 패키지를 import합니다.
업로드한 패키지의 의존성에서 ModuleNotFoundError가 발생합니다.	wheel은 의존성 없이 설치됩니다. 누락된 의존성의 wheel을 업로드하세요.
오류 메시지에 wheel이 is not a supported wheel on this platform이라고 나옵니다.	wheel이 다른 운영 체제 또는 Python 버전용입니다. Linux x86_64의 Python 3.12용 wheel을 구하세요.
install_uploaded_wheels()가 ResolutionImpossible로 실패합니다.	wheels 폴더에 같은 패키지의 두 버전이 있습니다. remove_wheels()로 이전 wheel을 제거하세요.
wheel을 업로드한 후 GPU 컴퓨트 프로필에서 cupy 같은 CUDA 패키지가 실패합니다.	wheel이 환경에서 제공하는 CUDA 패키지 중 하나를 대체했습니다. remove_wheels()로 해당 wheel을 제거하세요.
wheel을 업로드한 후 numpy 같은 설치된 패키지가 실패합니다.	wheel이 환경에서 제공하는 패키지의 두 번째 사본을 설치했습니다. remove_wheels()로 해당 wheel을 제거하세요.