Визначення вхідних і вихідних даних

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

Local Python

def my_workflow(circuits, shots=4096):
    ...
    return {"counts": counts}

result = my_workflow(circuits=circuits, shots=1024)

У керованому робочому процесі run() є викликом, get_arguments() передає робочому процесу його параметри, а save_result() слугує його оператором return. Оскільки робочий процес виконується як окреме завдання на віддалених обчислювальних ресурсах, він відрізняється від виклику локальної функції трьома способами:

• Клієнт кодує аргументи й результати. Кожне значення має бути таким, яке клієнт може закодувати, а деякі типи змінюються. Див. Читання аргументів у робочому процесі.

• Виклик не чекає. run() одразу повертає завдання, а результат ти читаєш пізніше через job.result(). Див. Збереження результатів.

• Виклик ніщо не перевіряє. Функція Python відхиляє невідомий іменований аргумент, але робочий процес його ігнорує, доки ти не приєднаєш схему. Див. Рекомендована практика: перевіряй аргументи за допомогою схеми.

Читання аргументів у робочому процесі

Передай вхідні дані в робочий процес зі свого локального ноутбука:

run_workflow_remotely.ipynb

job = my_workflow.run(circuits=circuits, shots=1024)

Щоб це працювало, зміни код робочого процесу так, щоб він отримував аргументи через get_arguments(), яка повертає словник, ключами якого є назви аргументів:

source_files/my_workflow.py

from qiskit_serverless import get_arguments

arguments = get_arguments()
circuits = arguments["circuits"]
shots = arguments.get("shots", 4096)

Словник містить лише ті аргументи, які передав запуск, тому для необов'язкових аргументів використовуй arguments.get() зі значенням за замовчуванням. Можна використовувати будь-яку назву аргументу, крім захищених ключових слів config і function_size, бо run() використовує їх напряму. run() також відхиляє compute_profile. Щоб вибрати обчислювальні ресурси, передай function_size.

Щоб прочитати розмір, з яким виконується завдання, виклич get_function_size() у коді свого робочого процесу:

source_files/my_workflow.py

from qiskit_serverless import get_function_size

size = get_function_size()  # For example, "M"

Якщо запуск не передає function_size, get_function_size() повертає розмір робочого процесу за замовчуванням. Див. Вибір розміру для кожного запуску.

Підтримувані типи аргументів

Кожне значення має бути серіалізованим у JSON або об'єктом, який клієнт може закодувати, наприклад схемою Qiskit чи масивом NumPy. Оскільки клієнт кодує кожен аргумент перед надсиланням завдання, а get_arguments() декодує його всередині робочого процесу, робочий процес отримує вихідний об'єкт Python.

Клієнт надсилає int, float, str, bool, None, а також списки чи словники з них без змін. Інші об'єкти, такі як QuantumCircuit, numpy.ndarray або число complex, він кодує як словник із тегом __type__ і полем __value__. Ця форма потрібна, коли ти пишеш схему аргументів.

Оскільки для деяких типів у JSON немає еквівалента, під час кодування ці типи змінюються. Кортежі надходять як списки, ключі словників надходять як рядки, а цілі числа NumPy, такі як np.int64, надходять як int. Якщо клієнт не може закодувати значення, наприклад bytes чи np.float32, run() викликає TypeError і не створює завдання.

Деякі об'єкти не можна передавати як аргументи. Наприклад, передавай назву бекенда як рядок замість об'єкта Backend і створюй бекенд всередині робочого процесу. Див. Запуск квантових завдань із робочого процесу.

Обмеження розміру

Аргументи одного запуску можуть мати розмір до 32 МБ після кодування. Наприклад, одна схема зі 100 кубітів і глибиною 100 кодується приблизно в 39 КБ, тож один запуск може прийняти пакет із приблизно 800 таких схем. Для більших вхідних даних завантаж файл і передай його назву як аргумент.

Збереження результатів

Використовуй save_result() в кінці робочого процесу, щоб повернути результат у свій ноутбук. Прочитай результат у ноутбуці через job.result():

run_workflow_remotely.ipynb

result = job.result()

Щоб це працювало, виклич save_result() у коді свого робочого процесу:

source_files/my_workflow.py

from qiskit_serverless import save_result

if not save_result({"counts": counts, "circuit": isa_circuit}):
    raise ValueError("The result could not be encoded.")

save_result() кодує результат так само, як клієнт кодує аргументи, а job.result() його декодує. Тому результат може містити підтримувані типи аргументів, такі як схеми, масиви NumPy і результат завдання примітива, з тими самими змінами типів.

• Перевіряй повернуте значення. Якщо save_result() не може закодувати значення, вона записує попередження в журнал і повертає False замість того, щоб викликати помилку. Без перевірки завдання може завершитися зі статусом DONE і без результату.

• Зберігається лише останній save_result(). Кожен виклик замінює збережений результат. Щоб повернути кілька значень, збережи їх в одному словнику або запиши в журнали.

• Порожній словник означає відсутність результату. Якщо робочий процес ніколи не викликає save_result(), job.result() повертає {}.

Щоб повернути файли, наприклад великі масиви чи графіки, збережи їх у файловому сховищі і поверни їхні назви в результаті.

Рекомендована практика: перевіряй аргументи за допомогою схеми

Як рекомендовану практику, приєднуй JSON Schema до кожного робочого процесу, який приймає аргументи. Схема описує аргументи, які приймає робочий процес, а робочий процес перевіряє за нею аргументи кожного запуску до створення завдання. Якщо аргументи не відповідають схемі, run() одразу завершується помилкою, що вказує на неправильне поле, і робочий процес не створює завдання. Без схеми неправильні аргументи потрапляють у робочий процес після запуску завдання, а робочий процес ігнорує аргумент із помилкою в назві.

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

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflow, ManagedWorkflowClient

arguments_schema = {
    "type": "object",
    "additionalProperties": False,
    "required": ["circuits"],
    "properties": {
        "circuits": {
            "type": "array",
            "minItems": 1,
            "items": {"$ref": "#/$defs/circuit"},
        },
        "shots": {"type": "integer", "minimum": 1, "maximum": 100000},
        "backend_name": {"type": "string", "minLength": 1},
    },
    "$defs": {
        "circuit": {
            "type": "object",
            "required": ["__type__", "__value__"],
            "properties": {
                "__type__": {"const": "QuantumCircuit"},
                "__value__": {"type": "string"},
            },
        }
    },
}

client = ManagedWorkflowClient()

my_workflow = client.upload(
    ManagedWorkflow(
        title="my-workflow",
        entrypoint="my_workflow.py",
        working_dir="./source_files/",
        arguments_schema=arguments_schema,
    )
)

Пам'ятай про такі моменти, коли пишеш схему:

• Опиши закодовану форму об'єктів Qiskit і NumPy. Схема перевіряє аргументи в тому вигляді, в якому їх надсилає клієнт, тож схема (circuit) є об'єктом на кшталт {"__type__": "QuantumCircuit", "__value__": "<base64-encoded QPY>"}, а не рядком чи масивом. Перевіряй тег __type__, а __value__ розглядай як непрозорий рядок. Схема, яка описує квантову схему як рядок, відхиляє кожен коректний запуск.

• Задай "additionalProperties": false. Без цього параметра робочий процес без попередження ігнорує аргумент із помилкою в назві, наприклад shotz, і працює зі значенням за замовчуванням. Перш ніж вмикати цей параметр, оголоси кожен аргумент, який приймає робочий процес.

• Познач обов'язкові аргументи. Додай до required кожен аргумент, який робочий процес читає без значення за замовчуванням.

Якщо аргументи не відповідають схемі, повідомлення про помилку вказує правило та місце неправильного значення:

'type' validation failed, schema requires 'integer': rejected value '4096'
path: ['shots']

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

Оновлення або видалення схеми

• Щоб замінити схему, задай нову arguments_schema і завантаж робочий процес повторно.

• Щоб видалити схему, завантаж робочий процес із arguments_schema={}.

• Якщо завантажити робочий процес без arguments_schema, робочий процес зберігає раніше збережену схему.

Щоб побачити чинну схему, прочитай my_workflow.arguments_schema. Значення None означає, що в робочого процесу немає схеми.

Перевірка аргументів перед запуском

Виклич validate_arguments(), щоб перевірити набір аргументів за схемою без запуску завдання:

run_workflow_remotely.ipynb

my_workflow.validate_arguments({"circuits": [circuit], "shots": 1024})
# {'valid': True}

Якщо аргументи недійсні, validate_arguments() викликає QiskitServerlessException з тим самим повідомленням, яке run() повертає для цих аргументів. Якщо в робочого процесу немає схеми, будь-які аргументи вважаються дійсними. Дійсний результат не гарантує, що run() завершиться успішно, бо run() також перевіряє інші обмеження, наприклад кількість активних завдань.

Правила схеми

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

• Схема може мати розмір до 64 КіБ, до 64 рівнів вкладеності та до 200 підсхем.

• Посилання мають вказувати всередину тієї самої схеми, наприклад #/$defs/circuit, і кожне посилання має розв'язуватися. Посилання на URL-адреси чи файли не дозволені.

• Схема має бути об'єктом або булевим значенням.

Також уникай таких проблем, які завантаження не виявляє:

• Вкладені квантифікатори в pattern. Шаблон на кшталт ^(a+)+$ може обчислюватися дуже довго. Робочий процес зупиняє перевірку після досягнення ліміту часу ЦП і відхиляє запуск. Пиши шаблони без квантифікатора навколо групи, яка вже його містить, наприклад ^ibm_[a-z0-9_]{1,40}$.

• false як схема. Схема false відхиляє кожен запуск. Щоб вимкнути перевірку, використовуй {}.

Усунення проблем зі схемою

Проблема	Причина
Кожен запуск відхиляється через аргумент-схему (circuit).	Схема описує квантову схему як рядок або масив. Опиши її як об'єкт із тегом __type__.
Коректні запуски відхиляються.	additionalProperties дорівнює false, а схема не оголошує аргумент, який передає запуск. Поле path у помилці вказує на цей аргумент.
Некоректні запуски не відхиляються.	У робочого процесу немає схеми. Перевір my_workflow.arguments_schema.
Жоден запуск не перевіряється, хоча ти задав схему.	Схему передано як рядок JSON. Передай словник.
Завантаження завершується помилкою 400.	Схема порушує одне з правил схеми.
Помилка повідомляє, що перевірка зайняла надто багато часу ЦП.	pattern має вкладені квантифікатори. Перепиши шаблон.