ข้ามไปยังเนื้อหาหลัก

เริ่มต้นใช้งาน 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 ได้ฟรี หรือสามารถจัดหาใบอนุญาตจากพาร์ทเนอร์รายใดรายหนึ่งที่ได้มีส่วนร่วม function ให้กับ catalog

ขอทดลองใช้ฟรีสำหรับ Qiskit Functions จากบุคคลที่สาม​

หากต้องการขอทดลองใช้ฟรี ไปที่ Qiskit Functions Catalog แล้วสำรวจแผงรายละเอียด คลิก Request a free trial และกรอกข้อมูลที่พาร์ทเนอร์ Functions ต้องการ รวมถึง AccessGroupId ของ IBM Cloud:

  1. ไปที่ IBM Cloud IAM

  2. ตรวจสอบสิทธิ์

    • สลับบัญชีของคุณในแถบเมนูที่ header ไปเป็นบัญชีที่มีรูปแบบดังนี้: XXXXXXX - [Organization Name]

    • ตรวจสอบให้แน่ใจว่าองค์กรตรงกับองค์กรที่เชื่อมโยงกับบัญชี Premium ของคุณ

    • หากคุณเห็น "[Your Name]'s Account" แสดงว่าคุณกำลังใช้บัญชี ส่วนตัว ของคุณ ซึ่งไม่มีสิทธิ์เข้าถึงระดับ premium

  3. ค้นหา access group ID ของคุณ

    • คลิกชื่อกลุ่ม

    • คลิก Details

    • คัดลอก access group ID ควรขึ้นต้นด้วย AccessGroup-

ติดตั้ง Qiskit Functions Catalog client​

  1. ในการเริ่มใช้งาน Qiskit Functions ให้ติดตั้ง IBM Qiskit Functions Catalog client:

    pip install qiskit-ibm-catalog

  2. ดึง API key ของคุณจาก IBM Quantum Platform dashboard และเปิดใช้งาน Python virtual environment ของคุณ ดู installation instructions หากคุณยังไม่มี virtual environment ตั้งค่าไว้

    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 ที่คุณใช้ authenticate ต้องเปิดใช้งานสิทธิ์เข้าถึง Qiskit Functions หากต้องการตั้งค่าบน instance ที่มีอยู่แล้ว โปรดดู Configure Qiskit Functions access on an instance.

    ในการใช้ save_account() ให้รัน python ใน shell ของคุณ จากนั้นป้อนสิ่งต่อไปนี้:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog

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

    พิมพ์ exit() จากนี้ไป เมื่อใดก็ตามที่คุณต้องยืนยันตัวตนกับบริการ คุณสามารถโหลด credentials ของคุณด้วยสิ่งต่อไปนี้:

    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

อย่าใส่ key ของคุณไว้ใน source code, Python scripts หรือ notebook files. เมื่อแชร์โค้ดกับผู้อื่น ตรวจสอบให้แน่ใจว่า API key ของคุณไม่ได้ฝังอยู่ใน Python script โดยตรง แต่ให้แชร์ script โดยไม่มี key และให้คำแนะนำสำหรับการตั้งค่าอย่างปลอดภัยแทน

หากคุณแชร์ key ของคุณกับผู้อื่นโดยไม่ตั้งใจ หรือใส่ไว้ใน version control อย่าง Git ให้เพิกถอน key ของคุณทันทีโดยลบมันที่หน้า IBM Cloud API keys เพื่อลดความเสี่ยง เรียนรู้เพิ่มเติมได้ที่หัวข้อ Managing user API keys

แสดงรายการ functions ที่คุณเข้าถึงได้​

หลังจากยืนยันตัวตนแล้ว คุณสามารถแสดงรายการ functions จาก 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)]

รัน functions ที่เปิดใช้งาน​

หลังจากสร้าง instance ของ catalog object แล้ว คุณสามารถเลือก function ได้โดยใช้ catalog.load("<provider/function-name>"):

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

แต่ละ Qiskit Function มี inputs, options และ outputs ที่กำหนดเอง ตรวจสอบหน้าเอกสารเฉพาะของ function ที่คุณต้องการรันเพื่อดูข้อมูลเพิ่มเติม โดยค่าเริ่มต้น ผู้ใช้ทุกคนสามารถรัน function job ได้ครั้งละหนึ่งงานเท่านั้น:

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 ของคุณก่อนที่จะส่ง job หากอินสแตนซ์ของคุณมีความจุไม่พอ หรือ backend ที่คุณระบุไม่สามารถเข้าถึงได้ run() จะแจ้ง error ทันทีแทนที่จะปล่อยให้ job ล้มเหลวในคิว เมื่อความจุต่ำ run() จะแสดง warning ส่ง 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​

ด้วย Qiskit Function job_id ของคุณ คุณสามารถตรวจสอบสถานะของ jobs ที่กำลังรันอยู่ได้ ซึ่งรวมถึงสถานะต่อไปนี้:

  • QUEUED: remote program อยู่ในคิวของ Qiskit Function ลำดับความสำคัญในคิวขึ้นอยู่กับปริมาณการใช้ Qiskit Functions ของคุณ

  • INITIALIZING: remote program กำลังเริ่มทำงาน ซึ่งรวมถึงการตั้งค่า remote environment และติดตั้ง dependencies

  • RUNNING: program กำลังรันอยู่ ซึ่งรวมถึงสถานะโดยละเอียดเพิ่มเติมหากรองรับโดย function เฉพาะนั้น

    • RUNNING: MAPPING: function กำลัง map inputs แบบคลาสสิกของคุณไปเป็น quantum inputs

    • RUNNING: OPTIMIZING_FOR_HARDWARE: function กำลัง optimize สำหรับ QPU ที่เลือกไว้ ซึ่งอาจรวมถึง circuit transpilation, การหาคุณลักษณะ QPU, observable backpropagation และอื่น ๆ

    • RUNNING: WAITING_FOR_QPU: function ได้ส่ง job ไปยัง IBM Quantum Compute Service แล้ว และกำลังรอในคิว

    • RUNNING: EXECUTING_QPU: function มี Quantum Compute job ที่กำลังทำงานอยู่

    • RUNNING: POST_PROCESSING: function กำลังประมวลผลผลลัพธ์ขั้นหลัง ซึ่งอาจรวมถึงการลด error, การ map ผลลัพธ์ quantum ไปเป็นคลาสสิก และอื่น ๆ

  • DONE: program ทำงานเสร็จสมบูรณ์แล้ว และคุณสามารถดึงข้อมูลผลลัพธ์ได้ด้วย job.result()

  • ERROR: program หยุดทำงานเนื่องจากมีปัญหา ใช้ job.result() เพื่อดูข้อความ error

  • CANCELED: program ถูกยกเลิกโดยผู้ใช้ บริการ หรือเซิร์ฟเวอร์

job.status()
'QUEUED'

ดึงผลลัพธ์​

หลังจาก program มีสถานะ DONE แล้ว คุณสามารถใช้ job.result() เพื่อดึงผลลัพธ์ รูปแบบผลลัพธ์นี้จะแตกต่างกันไปตามแต่ละ function ดังนั้นควรทำตามเอกสารเฉพาะเสมอ:

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 ได้ทุกเมื่อ:

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

เข้าถึง Quantum Compute jobs ที่เกี่ยวข้อง​

Qiskit Function หนึ่งตัวสามารถส่ง Quantum Compute jobs ได้หนึ่งงานหรือมากกว่านั้นไปยัง QPU ขณะที่มันทำงาน ในการดึง ID ของ runtime jobs เหล่านั้น ให้ใช้ job.runtime_jobs() คุณสามารถใช้ ID เหล่านี้เพื่อดึง runtime job objects จาก instance ของ QiskitRuntimeService หรือเพื่อค้นหา workloads บนหน้า dashboard ของ IBM Quantum® Platform

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

หาก function จัดกลุ่ม runtime jobs ของมันเป็น sessions หรือ batches ให้ใช้ job.runtime_sessions() เพื่อแสดงรายการ session ID ส่ง session ID หนึ่งตัวไปยัง job.runtime_jobs() เพื่อคืนค่าเฉพาะ runtime jobs ใน session นั้น:

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.")
หมายเหตุ

รายการที่ส่งกลับมาอาจว่างเปล่าได้ function จะรายงาน runtime job ของมันก็ต่อเมื่อมันส่ง job เหล่านั้นผ่าน runtime service ที่ function ได้รับตอน runtime เท่านั้น และบาง function ก็ไม่ได้ส่ง runtime job โดยตรง

ดู job logs​

ใช้ job.logs() เพื่อดึง log output ที่ function สร้างขึ้นขณะที่มันทำงาน logs มีประโยชน์สำหรับการติดตามความคืบหน้าและการดีบัก job ที่จบลงด้วยสถานะ ERROR

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

สำหรับ job ที่รันนานและสร้าง log lines จำนวนมาก ให้ใช้ job.filtered_logs() เพื่อคืนค่าเฉพาะบรรทัดที่คุณต้องการ ส่ง regular expression ไปยัง include เพื่อเก็บบรรทัดที่ตรงกัน หรือไปยัง exclude เพื่อตัดบรรทัดที่ตรงกันออก:

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

แสดงรายการ Qiskit Functions jobs ที่รันก่อนหน้านี้​

คุณสามารถใช้ jobs() เพื่อแสดงรายการ 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>]

ในการจำกัดผลลัพธ์ให้แคบลง ให้ส่ง filters กรองตาม function ด้วย 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

หากคุณมี job ID สำหรับ job หนึ่งอยู่แล้ว คุณสามารถดึง job นั้นได้ด้วย 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​

หากสถานะ program คือ ERROR ให้ใช้ job.error_message() เพื่อดึงข้อความ error ดังนี้:

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

ขั้นตอนถัดไป​

Recommendations

  • สำรวจ circuit functions เพื่อสร้าง algorithms และ applications ใหม่ ๆ โดยไม่ต้องจัดการ transpilation หรือการจัดการ error

  • สำรวจ application functions เพื่อแก้ปัญหาเฉพาะโดเมน ด้วย inputs และ outputs แบบคลาสสิก

  • ดู เอกสารอ้างอิง API สำหรับ Qiskit Functions

  • สำหรับประสบการณ์ลงมือปฏิบัติ ลองดู tutorials ที่สาธิต Qiskit Functions

แหล่งที่มา: IBM Quantum docs — อัปเดตเมื่อ 3 ก.ย. 2569
เวอร์ชันภาษาอังกฤษ บน doQumentation — อัปเดตเมื่อ 3 ก.ย. 2569
ปัญหาเกี่ยวกับเว็บไซต์หรือการแปล?ปัญหาเกี่ยวกับเนื้อหา? แก้ไขที่ IBM Quantum docs