Запуск керованого робочого процесу

Версії пакетів

Код на цій сторінці було розроблено з використанням таких вимог. Рекомендуємо використовувати ці версії або новіші.

qiskit-serverless~=0.38.0

Завдання керованого робочого процесу працює як пакетне завдання, яке ти надсилаєш до планувальника HPC. run() надсилає завдання та негайно повертає об'єкт Job. Використовуй об'єкт Job для задач, які в кластері виконують squeue, вихідний файл завдання та scancel. Завдання продовжує виконуватися після того, як ти закриєш свій ноутбук.

Приклади на цій сторінці використовують невеликий робочий процес, який зчитує один кут, theta, і завершується помилкою, якщо кут поза допустимим діапазоном. Завантаж його, як описано в розділі Розгортання першого керованого робочого процесу.

# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util

_needed = {"qiskit_ibm_catalog": "qiskit-ibm-catalog", "qiskit_serverless": "qiskit-serverless"}
_missing = [pip for module, pip in _needed.items()
            if importlib.util.find_spec(module) is None]
# One at a time, so a package that fails to install does not block the others
for _pip in _missing:
    %pip install -q {_pip}
if not _missing:
    print("\u2713 All required packages are installed")

# This cell is hidden from users. It creates the working directory.
from pathlib import Path

Path("./source_files").mkdir(exist_ok=True)

%%writefile ./source_files/my_workflow.py
import math

from qiskit_serverless import get_arguments, save_result

arguments = get_arguments()
theta = arguments["theta"]
if not 0 <= theta <= math.pi:
    raise ValueError(f"theta must be between 0 and pi, got {theta}")

print(f"Computing the expectation value for theta={theta}", flush=True)
save_result({"theta": theta, "expectation_value": math.cos(theta)})

Writing ./source_files/my_workflow.py

Запуск завдання

Отримай робочий процес за його назвою та викличи run() з аргументами, які зчитує робочий процес:

# This cell is hidden from users. It uploads the workflow under a title that
# other test notebooks do not use, and makes load("my-workflow") return it.
# It also silences the account warning that job.cancel() logs.
import logging

from qiskit_ibm_catalog import ManagedWorkflow, ManagedWorkflowClient

logging.getLogger("qiskit_ibm_runtime").setLevel(logging.ERROR)

_test_title = "docs-run-managed-workflow"
ManagedWorkflowClient().upload(
    ManagedWorkflow(
        title=_test_title,
        entrypoint="my_workflow.py",
        working_dir="./source_files/",
    )
)
_load = ManagedWorkflowClient.load
ManagedWorkflowClient.load = lambda self, title, *a, **k: _load(
    self, _test_title if title == "my-workflow" else title, *a, **k
)

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
my_workflow = client.load("my-workflow")

job = my_workflow.run(theta=0.5)
job_id = job.job_id

run() повертається після того, як робочий процес поставить завдання в чергу. Збережи ідентифікатор завдання, щоб ти міг знайти завдання з нового сеансу.

Щоб вибрати, які аргументи приймає робочий процес, і перевірити їх до початку завдання, дивись Визначення вхідних і вихідних даних.
Щоб запустити завдання з іншим розміром обчислювальних ресурсів, передай function_size. Дивись Вибір розміру для кожного запуску.

Відстеження завдання

Перевірка статусу

Одразу після виклику run() статус зазвичай QUEUED: run_workflow_remotely.ipynb

job.status()

'QUEUED'

Статус	Значення
`QUEUED`	Завдання очікує на обчислювальний слот.
`INITIALIZING`	Робочий процес запускає середовище з обчислювальним профілем завдання.
`RUNNING`	Виконується точка входу робочого процесу.
`RUNNING: <stage>`	Точка входу повідомила про етап за допомогою `update_status()`, наприклад `RUNNING: WAITING_FOR_QPU`.
`CANCELING`	Ти скасував завдання, і робочий процес його зупиняє.
`DONE`	Точка входу успішно завершилася.
`ERROR`	Точка входу викликала помилку або завершилася з ненульовим кодом. Дивись Пошук причини помилки.
`CANCELED`	Ти скасував завдання, або воно досягло 24-годинного ліміту.

DONE, ERROR і CANCELED є кінцевими, і job.in_terminal_state() повертає для них True. Цикл перевірки статусу, що чекає на інше значення, наприклад SUCCEEDED, ніколи не завершується.

Очікування завершення завдання

Щоб дочекатися завершення завдання, викличи wait_for_final_state(). Він повертає кінцевий статус, а з verbose=True виводить кожну зміну статусу. Якщо задати timeout у секундах, wait_for_final_state() викликає TimeoutError, коли час спливає до завершення завдання. Завдання продовжує виконуватися:

run_workflow_remotely.ipynb

job.wait_for_final_state(timeout=600, verbose=True)

Waiting for job 3f2a1c0e-6b1d-4c0e-9a51-2f0c4d1e7a90
0:00:00  QUEUED
0:02:10  RUNNING
0:03:05  RUNNING: WAITING_FOR_QPU
0:41:44  DONE
'DONE'

wait_for_final_state() перевіряє статус через 1, 2, 4, 8, 16 і 32 секунди, а потім кожні 60 секунд, тож він помічає завершення короткого завдання протягом секунд і робить мало запитів для довгого завдання. Щоб натомість перевіряти з фіксованим інтервалом, передай poll_interval у секундах.

Читання журналів

Усе, що робочий процес записує в стандартний вивід або стандартний потік помилок, потрапляє до журналів завдання. Ти можеш читати їх за допомогою job.logs(), поки завдання виконується, ще до появи результату:

# This cell is hidden from users. It waits for the job to end, so that the
# logs are complete.
job.wait_for_final_state()

run_workflow_remotely.ipynb

print(job.logs())

Computing the expectation value for theta=0.5

# This cell is hidden from users. It checks the logs.
assert "Computing the expectation value for theta=0.5" in job.logs()

Робочий процес завантажує нові рядки журналу приблизно кожні 15 секунд і ще раз наприкінці, коли завдання завершується або скасовується. Одразу після запуску завдання job.logs() повертає No logs yet.
Робочий процес зберігає найновіші 50 МБ журналів для кожного завдання та додає вгорі рядок, який повідомляє, що журнали було усічено.

Щоб визначити, що логує твій робочий процес, дивись Запис журналів. Щоб показати лише рядки, які відповідають регулярному виразу, передай include до job.filtered_logs(). Щоб приховати рядки, передай exclude.

Отримання результату

job.result() чекає завершення завдання, а потім повертає значення, яке робочий процес передав до save_result(): run_workflow_remotely.ipynb

job.result()

{'theta': 0.5, 'expectation_value': 0.8775825618903728}

# This cell is hidden from users. It checks the result.
assert _ == {"theta": 0.5, "expectation_value": 0.8775825618903728}, _  # noqa: F821

За замовчуванням job.result() перевіряє статус кожні 30 секунд і чекає без обмеження часу. Передай maxwait, щоб обмежити кількість перевірок. Наприклад, job.result(maxwait=40) чекає приблизно 20 хвилин. Щоб перевірити один раз без очікування, передай wait=False. Якщо job.result() припиняє очікування до завершення завдання, він повертає {}.

Перевірка тривалості кожного етапу

job.events() перелічує кожну зміну статусу та етапу завдання з її часом, тож ти можеш побачити, скільки завдання чекало на обчислювальні ресурси і скільки тривав кожен етап: run_workflow_remotely.ipynb

for event in reversed(job.events()):
    print(
        event.created,
        event.data.get("status") or event.data.get("sub_status"),
    )

2026-11-02T14:43:07.134377Z QUEUED
2026-11-02T14:43:24.474199Z PENDING
2026-11-02T14:46:07.309519Z RUNNING
2026-11-02T14:46:21.115038Z SUCCEEDED

# This cell is hidden from users. It checks the events.
_statuses = [e.data.get("status") for e in job.events()]
assert "QUEUED" in _statuses and "SUCCEEDED" in _statuses, _statuses

Події використовують збережені назви статусів. PENDING — це INITIALIZING, а SUCCEEDED — це DONE. Про використання QPU запуском дивись Пошук завдань QPU запуску.

Пошук причини помилки

Коли робочий процес викликає виняток, завдання завершується зі статусом ERROR. Наприклад, запусти робочий процес із кутом, який він відхиляє: run_workflow_remotely.ipynb

failed_job = my_workflow.run(theta=-1.0)

# This cell is hidden from users. It waits for the job to end.
failed_job.wait_for_final_state()

run_workflow_remotely.ipynb

failed_job.status()

'ERROR'

Журнали показують трасування стека: run_workflow_remotely.ipynb

print(failed_job.logs())

Traceback (most recent call last):
  File "/function_user_data/my_workflow.py", line 8, in <module>
    raise ValueError(f"theta must be between 0 and pi, got {theta}")
ValueError: theta must be between 0 and pi, got -1.0

job.result() raises a QiskitServerlessException: run_workflow_remotely.ipynb

from qiskit_serverless.exception import QiskitServerlessException

try:
    failed_job.result()
except QiskitServerlessException as error:
    print(error)

raise ValueError(f"theta must be between 0 and pi, got {theta}")
ValueError: theta must be between 0 and pi, got -1.0

# This cell is hidden from users. It checks the error.
assert failed_job.status() == "ERROR", failed_job.status()
assert (
    "ValueError: theta must be between 0 and pi, got -1.0"
    in failed_job.logs()
)
assert failed_job.events(type="ERROR") == []

Якщо робочий процес повідомляє про помилки за допомогою send_error(), читай їх за допомогою job.events(type="ERROR"), а їхні повідомлення читай за допомогою job.error_message(). Для завдання без повідомлених помилок job.events(type="ERROR") повертає порожній список, а job.error_message() повертає {}.

run_workflow_remotely.ipynb

for event in job.events(type="ERROR"):
    print(event.created, event.data.get("code"), event.data.get("message"))

Керування завданнями

Скасування завдання

Скасуй завдання за допомогою job.cancel(). Статус змінюється на CANCELING, поки робочий процес зупиняє завдання, а потім на CANCELED: run_workflow_remotely.ipynb

job_to_cancel = my_workflow.run(theta=1.0)
job_to_cancel.cancel()

'Job has been stopped. No active runtime job ID associated with this serverless job ID.'

# This cell is hidden from users. It checks the cancellation.
assert (
    job_to_cancel.wait_for_final_state() == "CANCELED"
), job_to_cancel.status()

job.cancel() повертає повідомлення про завдання та про його пов'язані завдання QPU, які він також намагається скасувати. Для завдання, що виконується, робочий процес надсилає SIGTERM твоїй точці входу. Щоб зберегти часткові результати, дивись Очищення, коли завдання скасовано. Якщо завдання вже завершилося, job.cancel() повертає Job already in terminal state. і нічого не змінює.

Пошук завдання з нового сеансу

Об'єкт Job і робочий процес існують лише в твоєму поточному сеансі Python. Після перезапуску ядра ноутбука передай збережений ідентифікатор завдання до client.job() або виведи список своїх останніх завдань за допомогою client.jobs(): run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
job = client.job(job_id)
my_workflow = client.load("my-workflow")

client.jobs(function=my_workflow, status="ERROR", limit=5)

[<Job | e6b1ffa1-cd26-437d-bd53-b265dd4ba952>,
 <Job | 11308f2a-8d7a-40a0-a970-7fdeca2b171b>,
 <Job | af597785-3470-469a-9051-607e0185892e>,
 <Job | a9051931-3bc2-4b80-9ce6-c39d28ce260c>,
 <Job | e329e8e3-e955-4188-9bfd-8f3050ee2d39>]

# This cell is hidden from users. It checks the job lookups.
assert job.result()["theta"] == 0.5
assert failed_job.job_id in [j.job_id for j in _]  # noqa: F821

client.jobs() повертає твої 10 найновіших завдань, найновіші першими. Фільтруй його за function, status (з таблиці статусів) або created_after (часова позначка ISO 8601) і переглядай по сторінках за допомогою limit та offset. Щоб вивести список робочих процесів, які ти завантажив, викличи client.list().

Таблиця Workloads на IBM Quantum Platform також показує твої завдання з їхнім статусом, обчислювальним профілем і часом виконання.

Ліміт часу

Керований робочий процес скасовує завдання, яке виконується понад 24 години, і завдання завершується зі статусом CANCELED. Під час тривалих запусків зберігай контрольні точки у файлове сховище, щоб не втратити роботу.

Усунення проблем із завданнями

Проблема	Причина
`run()` завершується помилкою `Code: 429` і `Active job limit reached.`	Ти досяг ліміту активних завдань. Зачекай, поки деякі завдання завершаться, або скасуй завдання, які тобі більше не потрібні.
Завдання залишається `QUEUED`, а `run()` попередив, що `your account, plan or subscription is blocked`.	Завдання не починається, доки не буде знято блокування з твого облікового запису, плану чи підписки. Зв'яжись зі своїм адміністратором.
`job.logs()` повертає `No logs yet.`	Завдання в черзі або щойно почалося. Зачекай приблизно 15 секунд.
`job.result()` повертає `{}`	Завдання не завершилося, було скасоване або не зберегло результату. Дивись Збереження результатів.
`job.error_message()` повертає `{}`	Робочий процес викликав виняток без повідомлення про помилку. Прочитай трасування стека за допомогою `job.logs()`.
Завдання `CANCELED`, але ти його не скасовував	Завдання досягло 24-годинного ліміту.

Наступні кроки

Рекомендації

Запис журналів і обробка помилок, щоб налаштувати журнали та помилки, про які повідомляє завдання.
Запуск перебору параметрів, щоб запустити робочий процес один раз для кожного набору вхідних даних.

Запуск завдання​

Відстеження завдання​

Перевірка статусу​

Очікування завершення завдання​

Читання журналів​

Отримання результату​

Перевірка тривалості кожного етапу​

Пошук причини помилки​

Керування завданнями​

Скасування завдання​

Пошук завдання з нового сеансу​

Ліміт часу​

Усунення проблем із завданнями​

Наступні кроки​

Запуск завдання

Відстеження завдання

Перевірка статусу

Очікування завершення завдання

Читання журналів

Отримання результату

Перевірка тривалості кожного етапу

Пошук причини помилки

Керування завданнями

Скасування завдання

Пошук завдання з нового сеансу

Ліміт часу

Усунення проблем із завданнями

Наступні кроки