Перейти до основного вмісту

Початок роботи з Qiskit Functions

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime
# This cell is hidden from users
# It gets these details programmatically so we can test this notebook
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.circuit.random import random_circuit
from qiskit_ibm_catalog import QiskitFunctionsCatalog

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name
catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")
qesem_function = catalog.load("qedma/qesem")
circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits

Користувачі планів Premium, Flex і On-Prem (через IBM Quantum Platform API) можуть безкоштовно почати використовувати IBM Qiskit Functions або придбати ліцензію в одного з партнерів, що надав функцію до каталогу.

Запит безкоштовної пробної версії сторонніх Qiskit Functions​

Щоб запросити безкоштовну пробну версію, перейди до Qiskit Functions Catalog і переглянь панель деталей. Натисни Request a free trial і заповни інформацію, необхідну партнеру Functions, включно з AccessGroupId IBM Cloud:

  1. Перейди до IBM Cloud IAM.

  2. Перевір право на участь.

    • Переключи свій акаунт у меню на панелі заголовка на такий, що має наступний формат: XXXXXXX - [Organization Name]

    • Переконайся, що організація збігається з тією, яка пов'язана з твоїм акаунтом Premium.

    • Якщо ти бачиш "[Your Name]'s Account", ти використовуєш свій особистий акаунт, який не має права на преміум-доступ.

  3. Знайди ідентифікатор своєї групи доступу.

    • Натисни на назву групи.

    • Натисни Details.

    • Скопіюй ідентифікатор групи доступу. Він має починатися з AccessGroup-.

Встановлення клієнта Qiskit Functions Catalog​

  1. Щоб почати використовувати Qiskit Functions, встанови клієнт IBM Qiskit Functions Catalog:

    pip install qiskit-ibm-catalog

  2. Отримай свій API ключ з панелі IBM Quantum Platform і активуй своє віртуальне середовище Python. Перегляньте інструкції з встановлення, якщо в тебе ще немає налаштованого віртуального середовища.

    If you are working in a trusted Python environment (such as on a personal laptop or workstation), use the save_account() method to save your credentials locally. (Skip to the next step if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)

    Екземпляр, з яким ти автентифікуєшся, повинен мати увімкнений доступ до Qiskit Functions. Щоб налаштувати це на наявному екземплярі, див. Налаштування доступу до Qiskit Functions на екземплярі.

    Щоб використати save_account(), запусти python у своїй оболонці, а потім введи наступне:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog

    QiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")

    Введи exit(). Відтепер, коли тобі потрібно автентифікуватися до сервісу, ти можеш завантажити свої облікові дані наступним чином:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog
    catalog = QiskitFunctionsCatalog()

    Наприклад:

# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

Avoid executing code on an untrusted machine or an external cloud Python environment to minimize security risks. If you must use an untrusted environment (on, for example, a public computer), change your API key after each use by deleting it on the IBM Cloud API keys page to reduce risk. Learn more in the Managing user API keys topic. To initialize the service in this situation, use this code:

from qiskit_ibm_catalog import QiskitFunctionsCatalog

# After using the following code, delete your API key on the
# IBM Quantum Platform home dashboard
catalog = QiskitFunctionsCatalog(token="<YOUR_API_KEY>") # Use the 44-character
# API_KEY you created and saved from the IBM Quantum Platform Home dashboard
Protect your API key

Ніколи не включай свій ключ у вихідний код, скрипти Python або файли notebook. Коли ділишся кодом з іншими, переконайся, що твій API ключ не вбудований безпосередньо в скрипт Python. Натомість, поділись скриптом без ключа і надай інструкції щодо безпечного його налаштування.

Якщо ти випадково поділився своїм ключем з кимось або включив його в систему контролю версій, наприклад Git, негайно відклич свій ключ, видаливши його на сторінці IBM Cloud API keys, щоб зменшити ризик. Дізнайся більше в розділі Managing user API keys.

Перелік функцій, до яких у тебе є доступ​

Після автентифікації ти можеш переглянути список функцій з Qiskit Functions Catalog, до яких у тебе є доступ:

catalog.list()
[QiskitFunction(qunova/hivqe-chemistry),
 QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),
 QiskitFunction(algorithmiq/tem),
 QiskitFunction(qedma/qesem),
 QiskitFunction(multiverse/singularity),
 QiskitFunction(ibm/circuit-function),
 QiskitFunction(q-ctrl/optimization-solver),
 QiskitFunction(colibritd/quick-pde),
 QiskitFunction(q-ctrl/performance-management),
 QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]

Запуск увімкнених функцій​

Після створення екземпляра каталогу ти можеш обрати функцію за допомогою catalog.load("<provider/function-name>"):

qesem_function = catalog.load("qedma/qesem")

Кожна Qiskit Function має власні вхідні дані, опції та вихідні дані. Перевір конкретну документацію для функції, яку хочеш запустити, для отримання додаткової інформації. За замовчуванням усі користувачі можуть запускати лише одне завдання функції одночасно:

from qiskit.quantum_info import SparsePauliOp

avg_magnetization = SparsePauliOp.from_sparse_list(
    [("Z", [q], 1 / 5) for q in range(5)], num_qubits=5
)

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)
job.job_id
'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'
порада

run() перевіряє твою залишкову ємність та доступ до backend перед відправкою завдання. Якщо в твого екземпляра закінчилася ємність, або названий тобою backend недоступний, run() одразу видає помилку, замість того щоб залишити завдання в черзі, де воно зазнає невдачі. Коли ємність низька, run() видає попередження. Передай suppress_low_usage_warning=True, щоб приховати його.

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    suppress_low_usage_warning=True,
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)

Перевірка статусу завдання​

Маючи job_id своєї Qiskit Function, ти можеш перевірити статус завдань, що виконуються. Це включає такі статуси:

  • QUEUED: Віддалена програма перебуває в черзі Qiskit Function. Пріоритет у черзі базується на тому, наскільки активно ти використовував Qiskit Functions.

  • INITIALIZING: Віддалена програма запускається; це включає налаштування віддаленого середовища та встановлення залежностей.

  • RUNNING: Програма виконується. Це також включає кілька детальніших статусів, якщо вони підтримуються конкретними функціями.

    • RUNNING: MAPPING: Функція наразі відображає твої класичні вхідні дані на квантові.

    • RUNNING: OPTIMIZING_FOR_HARDWARE: Функція оптимізує для обраного QPU. Це може включати транспіляцію схеми, характеризацію QPU, зворотне поширення спостережуваних величин тощо.

    • RUNNING: WAITING_FOR_QPU: Функція подала завдання до IBM Quantum Compute Service і очікує в черзі.

    • RUNNING: EXECUTING_QPU: Функція має активне завдання Quantum Compute.

    • RUNNING: POST_PROCESSING: Функція обробляє результати після виконання, що може включати пом'якшення помилок, відображення квантових результатів на класичні тощо.

  • DONE: Програма завершена, і ти можеш отримати дані результату за допомогою job.result().

  • ERROR: Виконання програми зупинилося через проблему. Використай job.result(), щоб отримати повідомлення про помилку.

  • CANCELED: Програму було скасовано користувачем, сервісом або сервером.

job.status()
'QUEUED'

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

Після того як програма набуде статусу DONE, ти можеш використати job.result(), щоб отримати результат. Формат виводу відрізняється для кожної функції, тому обов'язково звірся з відповідною документацією:

result = job.result()
print(result)
PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': True, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})

Ти також можеш скасувати завдання в будь-який момент:

job.cancel()
'Job has been stopped.'

Доступ до пов'язаних завдань Quantum Compute​

Qiskit Function може надіслати одне або кілька завдань Quantum Compute на QPU під час виконання. Щоб отримати ідентифікатори цих завдань виконання, використай job.runtime_jobs(). Ти можеш використати ці ідентифікатори, щоб отримати об'єкти завдань виконання з екземпляра QiskitRuntimeService, або щоб знайти робочі навантаження на панелі IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

Якщо функція групує свої завдання виконання в сесії або пакети, використай job.runtime_sessions(), щоб отримати список ідентифікаторів сесій. Передай один ідентифікатор сесії в job.runtime_jobs(), щоб повернути лише завдання виконання в цій сесії:

sessions = job.runtime_sessions()
if sessions:
    session_runtime_jobs = job.runtime_jobs(runtime_session=sessions[0])
    print(session_runtime_jobs)
else:
    print("No runtime sessions for this job.")
примітка

Повернутий список може бути порожнім. Функція повідомляє про свої runtime-завдання лише тоді, коли вона надсилає їх через runtime-сервіс, який функція отримує під час виконання, а деякі функції не надсилають runtime-завдання безпосередньо.

Перегляд журналів завдання​

Використай job.logs(), щоб отримати вивід журналу, який функція створює під час виконання. Журнали корисні для відстеження прогресу та для налагодження завдання, яке завершується станом ERROR.

print(job.logs().splitlines())

Для довготривалого завдання, яке створює багато рядків журналу, використай job.filtered_logs(), щоб повернути лише потрібні рядки. Передай регулярний вираз у include, щоб залишити відповідні рядки, або в exclude, щоб відкинути відповідні рядки:

print(job.filtered_logs(include="iteration"))

Перелік раніше виконаних завдань Qiskit Functions​

Ти можеш використати jobs(), щоб отримати список усіх завдань, надісланих до Qiskit Functions:

old_jobs = catalog.jobs()
old_jobs
[<Job | f6c29f49-4d5f-4fff-aca6-2e9a115b9763>,
 <Job | 7f08c9d5-471b-4da2-92e7-4f2cb94c23a8>,
 <Job | 62fe9176-d1e5-467e-b2bd-7a3f3c7be4e5>,
 <Job | af525b2e-16b1-45a1-80bb-dbd94ce30258>,
 <Job | b95a7a57-c1ad-4958-b7ac-953e4e1ee824>,
 <Job | 7bfa33da-0f17-4e67-84b6-f556f7eeb436>,
 <Job | ca46c191-9eb9-4de6-bfa7-b60d7eb29b5e>,
 <Job | 6ac0ba93-3831-43fb-9fb9-760da2225e06>,
 <Job | f0e38071-060d-47e8-988d-9cc1f69358e3>,
 <Job | 629cf110-e490-4675-8a07-f6d298d166b0>]

Щоб звузити результати, передай фільтри. Фільтруй за функцією за допомогою function, за статусом за допомогою status та за датою подання за допомогою created_after. Проглядай результати сторінками за допомогою limit та offset:

recent_errors = catalog.jobs(
    function=qesem_function,
    status="ERROR",
    created_after="2024-01-01T00:00:00Z",
    limit=5,
)
recent_errors

Якщо в тебе вже є ідентифікатор завдання для певного завдання, ти можеш отримати завдання за допомогою catalog.job():

# First, get the most recent job that has been executed.
latest_job = old_jobs[0]

# We can also get that same job with `catalog.job`
job_by_id = catalog.job(latest_job.job_id)

# Verify that the job is the same using both retrieval methods.
assert job_by_id.job_id == latest_job.job_id

# Print the job_id for this job.
print(job_by_id.job_id)
f6c29f49-4d5f-4fff-aca6-2e9a115b9763

Отримання повідомлень про помилки​

Якщо статус програми ERROR, використай job.error_message(), щоб отримати повідомлення про помилку наступним чином:

job.error_message()
qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'

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

Recommendations
Джерело: IBM Quantum docs — оновлено 3 вер. 2026 р.
Англійська версія на doQumentation — оновлено 3 вер. 2026 р.
Проблема із сайтом чи перекладом?Проблема з вмістом? Редагувати в IBM Quantum docs