Langkau ke kandungan utama

Mula menggunakan 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

Pengguna Pelan Premium, Flex, dan On-Prem (melalui API IBM Quantum Platform) boleh mula menggunakan IBM Qiskit Functions secara percuma, atau boleh mendapatkan lesen daripada salah satu rakan kongsi yang telah menyumbangkan fungsi kepada katalog.

Minta percubaan percuma untuk Qiskit Functions pihak ketiga​

Untuk meminta percubaan percuma, navigasi ke Qiskit Functions Catalog, dan terokai panel butiran. Klik Request a free trial dan isi maklumat yang diperlukan oleh rakan kongsi Functions, termasuk AccessGroupId IBM Cloud:

  1. Navigasi ke IBM Cloud IAM.

  2. Sahkan kelayakan.

    • Tukar akaun anda dalam bar menu pada header kepada satu dengan format berikut: XXXXXXX - [Organization Name]

    • Pastikan organisasi adalah sama dengan yang berkaitan dengan akaun Premium anda.

    • Jika anda melihat "[Your Name]'s Account", anda menggunakan akaun peribadi anda, yang tidak layak untuk akses premium.

  3. Cari ID kumpulan akses anda.

    • Klik nama kumpulan.

    • Klik Details.

    • Salin ID kumpulan akses. Ia sepatutnya bermula dengan AccessGroup-.

Pasang klien Qiskit Functions Catalog​

  1. Untuk mula menggunakan Qiskit Functions, pasang klien IBM Qiskit Functions Catalog:

    pip install qiskit-ibm-catalog

  2. Ambil API key anda daripada papan pemuka IBM Quantum Platform, dan aktifkan persekitaran maya Python anda. Lihat arahan pemasangan jika anda belum mempunyai persekitaran maya yang disediakan.

    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.)

    Instance yang anda gunakan untuk pengesahan mestilah mempunyai akses Qiskit Functions yang didayakan. Untuk mengkonfigurasikannya pada instance sedia ada, lihat Konfigurasikan akses Qiskit Functions pada instance.

    Untuk menggunakan save_account(), jalankan python dalam shell anda, kemudian masukkan yang berikut:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog

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

    Taip exit(). Mulai sekarang, apabila anda perlu mengesahkan diri ke perkhidmatan, anda boleh memuatkan kelayakan anda dengan yang berikut:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog
    catalog = QiskitFunctionsCatalog()

    Contohnya:

# 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

Jangan sekali-kali sertakan key anda dalam kod sumber, skrip Python, atau fail notebook. Apabila berkongsi kod dengan orang lain, pastikan API key anda tidak dibenamkan terus dalam skrip Python. Sebaliknya, kongsikan skrip tanpa key dan berikan arahan untuk menyediakannya dengan selamat.

Jika anda secara tidak sengaja berkongsi key anda dengan seseorang atau menyertakannya dalam kawalan versi seperti Git, segera batalkan key anda dengan memadamkannya pada halaman IBM Cloud API keys untuk mengurangkan risiko. Ketahui lebih lanjut dalam topik Managing user API keys.

Senaraikan fungsi yang boleh anda akses​

Selepas anda mengesahkan diri, anda boleh menyenaraikan fungsi daripada Qiskit Functions Catalog yang boleh anda akses:

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

Jalankan fungsi yang didayakan​

Selepas objek katalog dijana contohnya, anda boleh memilih fungsi dengan menggunakan catalog.load("<provider/function-name>"):

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

Setiap Qiskit Function mempunyai input, pilihan, dan output tersendiri. Semak halaman dokumentasi khusus untuk fungsi yang ingin anda jalankan untuk maklumat lanjut. Secara lalai, semua pengguna hanya boleh menjalankan satu kerja fungsi pada satu masa:

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'
petua

run() menyemak kapasiti baki anda dan akses backend sebelum ia menghantar kerja. Jika instance anda kehabisan kapasiti, atau backend yang anda namakan tidak boleh diakses, run() menimbulkan ralat serta-merta dan bukannya membiarkan kerja itu gagal dalam baris gilir. Apabila kapasiti rendah, run() mengeluarkan amaran. Hantar suppress_low_usage_warning=True untuk membisukannya.

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
    # },
)

Semak status kerja​

Dengan job_id Qiskit Function anda, anda boleh menyemak status kerja yang sedang berjalan. Ini termasuk status berikut:

  • QUEUED: Program jauh berada dalam baris gilir Qiskit Function. Keutamaan baris gilir adalah berdasarkan berapa banyak anda telah menggunakan Qiskit Functions.

  • INITIALIZING: Program jauh sedang dimulakan; ini termasuk menyediakan persekitaran jauh dan memasang kebergantungan.

  • RUNNING: Program sedang berjalan. Ini juga termasuk beberapa status yang lebih terperinci jika disokong oleh fungsi tertentu.

    • RUNNING: MAPPING: Fungsi sedang memetakan input klasik anda kepada input kuantum.

    • RUNNING: OPTIMIZING_FOR_HARDWARE: Fungsi sedang mengoptimumkan untuk QPU yang dipilih. Ini boleh termasuk transpilasi litar, pencirian QPU, perambatan balik cerapan, dan sebagainya.

    • RUNNING: WAITING_FOR_QPU: Fungsi telah menghantar kerja ke IBM Quantum Compute Service, dan sedang menunggu dalam baris gilir.

    • RUNNING: EXECUTING_QPU: Fungsi mempunyai kerja Quantum Compute yang aktif.

    • RUNNING: POST_PROCESSING: Fungsi sedang memproses pasca keputusan, yang boleh termasuk mitigasi ralat, pemetaan keputusan kuantum kepada klasik, dan sebagainya.

  • DONE: Program telah selesai, dan anda boleh mengambil data keputusan dengan job.result().

  • ERROR: Program berhenti berjalan kerana masalah. Gunakan job.result() untuk mendapatkan mesej ralat.

  • CANCELED: Program telah dibatalkan oleh pengguna, perkhidmatan, atau pelayan.

job.status()
'QUEUED'

Ambil keputusan​

Selepas program DONE, anda boleh menggunakan job.result() untuk mengambil keputusan. Format output ini berbeza-beza mengikut setiap fungsi, jadi pastikan anda mengikuti dokumentasi khusus:

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})

Anda juga boleh membatalkan kerja pada bila-bila masa:

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

Akses kerja Quantum Compute yang berkaitan​

Qiskit Function boleh menghantar satu atau lebih kerja Quantum Compute ke QPU semasa ia berjalan. Untuk mengambil ID kerja masa jalan tersebut, gunakan job.runtime_jobs(). Anda boleh menggunakan ID ini untuk mengambil objek kerja masa jalan daripada instance QiskitRuntimeService, atau untuk mencari beban kerja pada papan pemuka IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

Jika fungsi mengumpulkan kerja masa jalannya ke dalam sesi atau kelompok, gunakan job.runtime_sessions() untuk menyenaraikan ID sesi. Hantar satu ID sesi kepada job.runtime_jobs() untuk mengembalikan hanya kerja masa jalan dalam sesi tersebut:

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.")
nota

Senarai yang dikembalikan boleh kosong. Fungsi hanya melaporkan pekerjaan runtime miliknya apabila ia menghantarnya melalui perkhidmatan runtime yang diterima oleh fungsi tersebut semasa masa jalan, dan sesetengah fungsi tidak menghantar pekerjaan runtime secara langsung.

Lihat log kerja​

Gunakan job.logs() untuk mengambil output log yang dihasilkan oleh fungsi semasa ia berjalan. Log berguna untuk menjejaki kemajuan dan untuk menyahpepijat kerja yang berakhir dalam status ERROR.

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

Untuk kerja yang berjalan lama dan menghasilkan banyak baris log, gunakan job.filtered_logs() untuk mengembalikan hanya baris yang anda mahu. Hantar ungkapan biasa kepada include untuk mengekalkan baris yang sepadan, atau kepada exclude untuk membuang baris yang sepadan:

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

Senaraikan kerja Qiskit Functions yang telah dijalankan sebelum ini​

Anda boleh menggunakan jobs() untuk menyenaraikan semua kerja yang dihantar ke 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>]

Untuk menyempitkan keputusan, hantar penapis. Tapis mengikut fungsi dengan function, mengikut status dengan status, dan mengikut tarikh penghantaran dengan created_after. Layari keputusan mengikut halaman dengan limit dan offset:

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

Jika anda sudah mempunyai ID kerja untuk kerja tertentu, anda boleh mengambil kerja tersebut dengan 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

Ambil mesej ralat​

Jika status program ialah ERROR, gunakan job.error_message() untuk mengambil mesej ralat seperti berikut:

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

Langkah seterusnya​

Recommendations

  • Terokai fungsi litar untuk membina algoritma dan aplikasi baharu, tanpa perlu menguruskan transpilasi atau pengendalian ralat.

  • Terokai fungsi aplikasi untuk menyelesaikan tugas khusus domain, dengan input dan output klasik.

  • Lihat dokumentasi rujukan API untuk Qiskit Functions.

  • Untuk pengalaman secara praktikal, cuba beberapa tutorial yang menunjukkan Qiskit Functions.

Sumber: IBM Quantum docs — dikemas kini 3 Sep 2026
Versi bahasa Inggeris di doQumentation — dikemas kini 3 Sep 2026
Masalah laman web atau terjemahan?Masalah kandungan? Sunting di IBM Quantum docs