Przejdź do głównej treści
Ten projekt jest w wersji beta. Znalazłeś błąd? Otwórz zgłoszenie na GitHub. Masz pytanie lub pomysł? Zapytaj w Discussions — chętnie poznamy Twoją opinię!
Jak oceniasz jakość tłumaczenia tej strony?

Pierwsze kroki z Qiskit Functions

# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util

_needed = {"qiskit": "qiskit", "qiskit_ibm_catalog": "qiskit-ibm-catalog", "qiskit_ibm_runtime": "qiskit-ibm-runtime"}
_missing = [pip for module, pip in _needed.items()
            if importlib.util.find_spec(module) is None]
# One at a time, so a package that fails to install does not block the others
for _pip in _missing:
    %pip install -q {_pip}
if not _missing:
    print("\u2713 All required packages are installed")
# 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

Użytkownicy planów Premium, Flex i On-Prem (poprzez IBM Quantum Platform API) mogą zacząć korzystać z IBM Qiskit Functions za darmo lub nabyć licencję od jednego z partnerów, którzy udostępnili funkcję w katalogu.

Poproś o darmowy okres próbny funkcji Qiskit Functions od partnerów zewnętrznych​

Aby poprosić o darmowy okres próbny, przejdź do Qiskit Functions Catalog i zapoznaj się z panelem szczegółów. Kliknij Request a free trial i wypełnij informacje wymagane przez partnera dostarczającego funkcję, w tym AccessGroupId w IBM Cloud:

  1. Przejdź do IBM Cloud IAM.

  2. Sprawdź, czy się kwalifikujesz.

    • Przełącz swoje konto w menu na pasku nagłówka na konto o następującym formacie: XXXXXXX - [Organization Name]

    • Upewnij się, że organizacja jest taka sama jak ta powiązana z Twoim kontem Premium.

    • Jeśli widzisz „[Your Name]'s Account”, korzystasz ze swojego konta osobistego, które nie kwalifikuje się do dostępu premium.

  3. Znajdź identyfikator swojej grupy dostępu.

    • Kliknij nazwę grupy.

    • Kliknij Details.

    • Skopiuj identyfikator grupy dostępu. Powinien zaczynać się od AccessGroup-.

Zainstaluj klienta Qiskit Functions Catalog​

  1. Aby zacząć korzystać z Qiskit Functions, zainstaluj klienta IBM Qiskit Functions Catalog:

    pip install qiskit-ibm-catalog

  2. Pobierz swój klucz API z panelu IBM Quantum Platform i aktywuj swoje wirtualne środowisko Python. Zobacz instrukcje instalacji, jeśli nie masz jeszcze skonfigurowanego wirtualnego środowiska.

    Jeśli pracujesz w zaufanym środowisku Python (na przykład na osobistym laptopie lub stacji roboczej), użyj metody save_account(), aby zapisać swoje dane uwierzytelniające lokalnie. (Przejdź do następnego kroku, jeśli nie korzystasz z zaufanego środowiska, takiego jak współdzielony lub publiczny komputer, do uwierzytelniania w IBM Quantum Platform.)

    Instancja, z którą się uwierzytelniasz, musi mieć włączony dostęp do Qiskit Functions. Aby skonfigurować go dla istniejącej instancji, zobacz Konfigurowanie dostępu do Qiskit Functions dla instancji.

    Aby użyć save_account(), uruchom python w swojej powłoce, a następnie wprowadź:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog

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

    Wpisz exit(). Od tej pory, gdy tylko będziesz musiał uwierzytelnić się w usłudze, możesz wczytać swoje dane uwierzytelniające za pomocą:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog
    catalog = QiskitFunctionsCatalog()

    Na przykład:

# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

Unikaj uruchamiania kodu na niezaufanej maszynie lub w zewnętrznym chmurowym środowisku Python, aby zminimalizować ryzyko związane z bezpieczeństwem. Jeśli musisz korzystać z niezaufanego środowiska (na przykład na publicznym komputerze), zmieniaj swój klucz API po każdym użyciu, usuwając go na stronie IBM Cloud API keys, aby zmniejszyć ryzyko. Dowiedz się więcej w temacie Managing user API keys. Aby zainicjować usługę w tej sytuacji, użyj tego kodu:

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
Chroń swój klucz API

Nigdy nie umieszczaj swojego klucza w kodzie źródłowym, skryptach Python ani plikach notatnika. Podczas udostępniania kodu innym osobom upewnij się, że Twój klucz API nie jest osadzony bezpośrednio w skrypcie Python. Zamiast tego udostępnij skrypt bez klucza i podaj instrukcje dotyczące bezpiecznego jego skonfigurowania.

Jeśli przypadkowo udostępnisz swój klucz komuś lub umieścisz go w systemie kontroli wersji, takim jak Git, natychmiast unieważnij swój klucz, usuwając go na stronie IBM Cloud API keys, aby zmniejszyć ryzyko. Dowiedz się więcej w temacie Managing user API keys.

Wyświetl listę funkcji, do których masz dostęp​

Po uwierzytelnieniu możesz wyświetlić listę funkcji z Qiskit Functions Catalog, do których masz dostęp:

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

Uruchamianie włączonych funkcji​

Po utworzeniu instancji obiektu katalogu możesz wybrać funkcję za pomocą catalog.load("<provider/function-name>"):

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

Każda funkcja Qiskit Function ma niestandardowe dane wejściowe, opcje i wyniki. Sprawdź konkretne strony dokumentacji dla funkcji, którą chcesz uruchomić, aby uzyskać więcej informacji. Domyślnie wszyscy użytkownicy mogą uruchamiać tylko jedno zadanie funkcji jednocześnie:

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'
wskazówka

run() sprawdza pozostałą dostępną pojemność i dostęp do backendu przed przesłaniem zadania. Jeśli Twoja instancja nie ma dostępnej pojemności lub podany backend jest niedostępny, run() natychmiast zgłasza błąd, zamiast pozostawiać zadanie do niepowodzenia w kolejce. Gdy dostępna pojemność jest niska, run() wysyła ostrzeżenie. Przekaż suppress_low_usage_warning=True, aby je wyciszyć.

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

Sprawdzanie stanu zadania​

Za pomocą job_id funkcji Qiskit Function możesz sprawdzić stan uruchomionych zadań. Obejmuje to następujące stany:

  • QUEUED: Zdalny program znajduje się w kolejce Qiskit Functions. Priorytet w kolejce zależy od tego, jak dużo korzystałeś z Qiskit Functions.

  • INITIALIZING: Zdalny program się uruchamia; obejmuje to konfigurację zdalnego środowiska i instalację zależności.

  • RUNNING: Program jest uruchomiony. Obejmuje to również kilka bardziej szczegółowych stanów, jeśli są obsługiwane przez konkretne funkcje.

    • RUNNING: MAPPING: Funkcja aktualnie mapuje Twoje dane wejściowe klasyczne na dane wejściowe kwantowe.

    • RUNNING: OPTIMIZING_FOR_HARDWARE: Funkcja optymalizuje pod wybrany QPU. Może to obejmować transpilację obwodu, charakterystykę QPU, propagację wsteczną obserwabli i tak dalej.

    • RUNNING: WAITING_FOR_QPU: Funkcja przesłała zadanie do IBM Quantum Compute Service i czeka w kolejce.

    • RUNNING: EXECUTING_QPU: Funkcja ma aktywne zadanie Quantum Compute.

    • RUNNING: POST_PROCESSING: Funkcja wykonuje przetwarzanie końcowe wyników, co może obejmować łagodzenie błędów, mapowanie wyników kwantowych na klasyczne i tak dalej.

  • DONE: Program jest zakończony i możesz pobrać dane wynikowe za pomocą job.result().

  • ERROR: Program przestał działać z powodu problemu. Użyj job.result(), aby uzyskać komunikat o błędzie.

  • CANCELED: Program został anulowany przez użytkownika, usługę lub serwer.

job.status()
'QUEUED'

Pobieranie wyników​

Po tym, jak program ma stan DONE, możesz użyć job.result(), aby pobrać wynik. Format wyjściowy różni się w zależności od funkcji, więc koniecznie zapoznaj się z konkretną dokumentacją:

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

Możesz również anulować zadanie w dowolnym momencie:

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

Dostęp do powiązanych zadań Quantum Compute​

Funkcja Qiskit Function może przesłać jedno lub więcej zadań Quantum Compute do QPU podczas działania. Aby pobrać identyfikatory tych zadań środowiska uruchomieniowego, użyj job.runtime_jobs(). Możesz użyć tych identyfikatorów, aby pobrać obiekty zadań środowiska uruchomieniowego z instancji QiskitRuntimeService lub znaleźć obciążenia w panelu IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

Jeśli funkcja grupuje swoje zadania środowiska uruchomieniowego w sesje lub grupy zadań, użyj job.runtime_sessions(), aby wyświetlić listę identyfikatorów sesji. Przekaż jeden identyfikator sesji do job.runtime_jobs(), aby zwrócić tylko zadania środowiska uruchomieniowego w tej sesji:

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

Zwrócona lista może być pusta. Funkcja zgłasza swoje zadania środowiska uruchomieniowego tylko wtedy, gdy przesyła je za pośrednictwem usługi środowiska uruchomieniowego, którą funkcja otrzymuje w czasie wykonywania, a niektóre funkcje nie przesyłają zadań środowiska uruchomieniowego bezpośrednio.

Wyświetlanie dzienników zadania​

Użyj job.logs(), aby pobrać dane wyjściowe dziennika generowane przez funkcję podczas działania. Dzienniki są przydatne do śledzenia postępu i debugowania zadania, które kończy się stanem ERROR.

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

W przypadku długo trwającego zadania, które generuje wiele linii dziennika, użyj job.filtered_logs(), aby zwrócić tylko potrzebne linie. Przekaż wyrażenie regularne do include, aby zachować pasujące linie, lub do exclude, aby odrzucić pasujące linie:

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

Wyświetlanie listy wcześniej uruchomionych zadań Qiskit Functions​

Możesz użyć jobs(), aby wyświetlić listę wszystkich zadań przesłanych do 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>]

Aby zawęzić wyniki, przekaż filtry. Filtruj według funkcji za pomocą function, według stanu za pomocą status i według daty przesłania za pomocą created_after. Przeglądaj wyniki stronami za pomocą limit i offset:

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

Jeśli masz już identyfikator zadania dla określonego zadania, możesz je pobrać za pomocą 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

Pobieranie komunikatów o błędach​

Jeśli stan programu to ERROR, użyj job.error_message(), aby pobrać komunikat o błędzie w następujący sposób:

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

Kolejne kroki​

Zalecenia

  • Poznaj funkcje obwodów, aby budować nowe algorytmy i aplikacje bez konieczności zarządzania transpilacją lub obsługą błędów.

  • Poznaj funkcje aplikacji, aby rozwiązywać zadania specyficzne dla danej dziedziny, z klasycznymi danymi wejściowymi i wyjściowymi.

  • Zobacz dokumentację referencyjną API dla Qiskit Functions.

  • Aby zdobyć praktyczne doświadczenie, wypróbuj niektóre samouczki, które demonstrują Qiskit Functions.

Źródło: Dokumentacja IBM Quantum — zaktualizowano 3 wrz 2026
Wersja angielska na doQumentation — zaktualizowano 3 wrz 2026
Problem ze stroną lub tłumaczeniem?Problem z treścią? Edytuj w IBM Quantum docs