주 콘텐츠로 건너뛰기

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를 통한) Plan 사용자는 IBM Qiskit Functions를 무료로 시작하거나, 카탈로그에 함수를 제공한 파트너 중 한 곳에서 라이선스를 구매할 수 있습니다.

타사 Qiskit Functions에 대한 무료 평가판 요청하기​

무료 평가판을 요청하려면 Qiskit Functions Catalog로 이동하여 세부 정보 패널을 살펴보세요. Request a free trial을 클릭하고, IBM Cloud AccessGroupId를 포함하여 Functions 파트너가 요구하는 정보를 입력하세요:

  1. IBM Cloud IAM으로 이동합니다.

  2. 자격을 확인합니다.

    • 헤더의 메뉴 바에서 계정을 다음 형식의 계정으로 전환하세요: XXXXXXX - [Organization Name]

    • 조직이 Premium 계정과 연결된 조직과 동일한지 확인합니다.

    • "[내 이름]'s Account"가 표시되면 개인 계정을 사용하고 있는 것이며, 이는 프리미엄 액세스 대상이 아닙니다.

  3. 액세스 그룹 ID를 찾습니다.

    • 그룹 이름을 클릭합니다.

    • Details를 클릭합니다.

    • 액세스 그룹 ID를 복사합니다. AccessGroup-으로 시작해야 합니다.

Qiskit Functions Catalog 클라이언트 설치하기​

  1. Qiskit Functions를 사용하기 시작하려면 IBM Qiskit Functions Catalog 클라이언트를 설치하세요:

    pip install qiskit-ibm-catalog

  2. IBM Quantum Platform 대시보드에서 API 키를 가져오고, 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
API 키 보호하기

소스 코드, Python 스크립트, 노트북 파일에 절대 API 키를 포함하지 마세요. 다른 사람과 코드를 공유할 때는 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()은 작업을 제출하기 전에 남은 용량과 백엔드 접근 권한을 확인합니다. 인스턴스의 용량이 모두 소진되었거나 지정한 백엔드에 접근할 수 없는 경우, 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
    # },
)

작업 상태 확인하기​

Qiskit Function job_id를 사용하여 실행 중인 작업의 상태를 확인할 수 있습니다. 여기에는 다음과 같은 상태가 포함됩니다:

  • 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에 제출할 수 있습니다. 이러한 런타임 작업의 ID를 가져오려면 job.runtime_jobs()를 사용하세요. 이 ID를 사용하여 QiskitRuntimeService 인스턴스에서 런타임 작업 객체를 가져오거나, IBM Quantum® Platform 대시보드에서 워크로드를 찾을 수 있습니다.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

함수가 런타임 작업을 세션이나 배치로 그룹화하는 경우, job.runtime_sessions()를 사용하여 세션 ID 목록을 확인하세요. job.runtime_jobs()에 세션 ID 하나를 전달하면 해당 세션의 런타임 작업만 반환됩니다:

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.")
참고

반환된 목록은 비어 있을 수 있습니다. 함수는 실행 시점에 받은 런타임 서비스를 통해 작업을 제출하는 경우에만 런타임 작업을 보고하며, 일부 함수는 런타임 작업을 직접 제출하지 않습니다.

작업 로그 보기​

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

특정 작업의 작업 ID를 이미 알고 있다면, 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'

다음 단계​

권장 사항

  • 트랜스파일이나 오류 처리를 관리할 필요 없이 새로운 알고리즘과 애플리케이션을 구축하려면 circuit functions 살펴보기를 참조하세요.

  • 고전적 입력과 출력으로 도메인별 작업을 해결하려면 application functions 살펴보기를 참조하세요.

  • Qiskit Functions에 대한 API 참조 문서를 확인하세요.

  • 실습 경험을 원한다면, Qiskit Functions를 보여주는 튜토리얼을 시도해 보세요.

출처: IBM Quantum docs — 2026년 9월 3일 업데이트
doQumentation의 영어 버전 — 2026년 9월 3일 업데이트
사이트 또는 번역 문제?콘텐츠 문제? IBM Quantum docs에서 편집