Migrasi daripada Sampler dan Estimator sisi pelayan ke sisi klien

Panduan ini menerangkan cara memigrasi daripada pelaksanaan sisi pelayan IBM Quantum® Sampler dan Estimator kepada pelaksanaan sisi klien baharu mereka dalam qiskit-ibm-runtime. Antara muka dan pilihan sebahagian besarnya tidak berubah, jadi kebanyakan kod berjalan seadanya, tetapi terdapat beberapa perbezaan tingkah laku yang perlu difahami.

Latar Belakang

Sampler dan Estimator ialah antara muka primitif yang ditakrifkan dalam Qiskit. IBM Quantum Compute Service (dahulunya Qiskit Runtime) secara sejarahnya telah menyediakan pelaksanaan primitif ini di dalam persekitaran runtime-nya. Apabila anda memanggil sampler.run() atau estimator.run(), permintaan dihantar ke perkhidmatan tersebut, dan semua pengiraan — termasuk penindasan dan pengurangan ralat — berlaku pada sisi pelayan.

Pengalaman kotak hitam ini adalah mudah: anda tidak perlu risau tentang butiran pelaksanaan. Tetapi ia juga menjadikan primitif ini sukar untuk dinyahpepijat, disesuaikan, atau dipelajari, kerana anda tidak dapat melihat apa yang berlaku semasa pemprosesan.

Model pelaksanaan terarah yang baru diperkenalkan mengambil pendekatan bertentangan dan menyediakan pengalaman kotak putih. Semua niat reka bentuk ditangkap pada sisi klien, dan satu primitif sisi pelayan Executor memproses input tersebut dengan tepat seperti yang diarahkan — ia tidak membuat sebarang keputusan tersirat bagi pihak anda.

Bermula dalam qiskit-ibm-runtime v0.50.0, Sampler dan Estimator dilaksanakan semula pada sisi klien di atas Executor. Mereka menyediakan kemudahan dan abstraksi yang sama seperti sebelum ini, dan kini anda boleh memeriksa butiran pelaksanaan apabila anda perlu berbuat demikian. Kerana antara muka dan pilihan kekal sebahagian besarnya sama, migrasi sepatutnya lancar.

Nota: IBM Quantum hanya menyokong versi 2 antara muka Sampler dan Estimator (BaseSamplerV2 dan BaseEstimatorV2). Oleh itu, ia hanya dirujuk sebagai Sampler dan Estimator dalam panduan ini.

Kemas kini import

Pada masa ini, anda perlu mengimport secara eksplisit pelaksanaan baharu daripada modul khusus mereka:

from qiskit_ibm_runtime.executor_sampler import Sampler
from qiskit_ibm_runtime.executor_estimator import Estimator

Dalam masa terdekat, import peringkat atas akan diselesaikan kepada pelaksanaan sisi klien baharu, dan tiada perubahan kod akan diperlukan:

# Coming soon — the following code will import the new client-side implementations.
from qiskit_ibm_runtime import Sampler, Estimator

Begitu juga, jika anda membina objek pilihan bertaip, anda perlu mengimportnya daripada qiskit_ibm_runtime.options_models sebaliknya, atau hanya hantar dict bersarang biasa:

from qiskit_ibm_runtime.options_models import SamplerOptions, EstimatorOptions

Apa yang kekal sama

Pembinaan primitif dengan mode dan options.
Tandatangan run() dan format PUB.
Pepohon pilihan (options.twirling, options.resilience, options.default_shots, dan sebagainya).
Struktur data hasil yang dikembalikan oleh job.result().

Perubahan tidak serasi dalam Sampler baharu

Perubahan	Tindakan migrasi
Primitif asas kini adalah Executor. Kedua-dua antara muka pengguna IBM Quantum Platform dan `job.primitive_id` akan menunjukkan `executor` dan bukannya `sampler`.	Kemas kini sebarang kod yang merujuk `job.primitive_id`.
Pelaksanaan baharu memetakan input Sampler kepada input Executor, jadi `job.inputs` mengembalikan input Executor.	Kemas kini sebarang kod yang merujuk `job.inputs`. Lihat Input kerja.
Lebih banyak pemprosesan pra dan pasca kini berlaku pada sisi klien, jadi `sampler.run()` dan `job.result()` mungkin mengambil masa lebih lama daripada sebelum ini.	Dayakan pengelogan INFO untuk mengikuti kemajuan pemprosesan sisi klien. Lihat Dayakan pengelogan INFO.
Metadata litar disalin ke dalam metadata hasil. Jenis data yang dibenarkan dalam metadata hasil kini terhad kepada `str`, `float`, `int`, `bool`, dan senarai atau kamus jenis tersebut.	Jika anda memerlukan jenis data lain, kodkannya sebagai rentetan dahulu (contohnya, dengan base64).
Kelas pilihan (`options_models.SamplerOptions` dan sebagainya) kini adalah model Pydantic dan bukannya dataclass, jadi ia tidak lagi boleh ditukar kepada kamus Python dengan menggunakan `asdict()`.	Gunakan `options.model_dump()` sebaliknya.
Kelas pilihan yang sebelum ini mempunyai akhiran `V2` (`ExecutionOptionsV2` dan sebagainya) tidak lagi mempunyainya, memandangkan primitif V1 tidak lagi disokong.	Buang akhiran `V2` kelas pilihan ini: gantikan `ExecutionOptionsV2` dengan `ExecutionOptions`, `ResilienceOptionsV2` dengan `ResilienceOptions`, dan `SamplerExecutionOptionsV2` dengan `SamplerExecutionOptions`.
Jika `twirling` didayakan dan `shots` (dalam PUB atau dalam `run()`), `shots_per_randomization`, dan `num_randomizations` kesemuanya dinyatakan, maka `num_randomizations * shots_per_randomization` mengatasi `shots`.	Tinggalkan `num_randomizations` dan `shots_per_randomization` jika anda mahu nilai `shots` digunakan.
Sebahagian pengesahan input telah dipindahkan ke sisi pelayan dan kini menimbulkan `RuntimeError` dan bukannya `IBMInputValueError`.	Kemas kini jenis pengecualian yang ditangkap oleh kod anda.
Nilai shot yang bercampur dalam satu kerja tidak lagi disokong.	Hantar kerja berasingan untuk setiap nilai shot. Lihat Pemisahan kerja untuk pertimbangan.

Perubahan tidak serasi dalam Estimator baharu

Perubahan	Tindakan migrasi
Primitif asas kini adalah Executor. Kedua-dua antara muka pengguna IBM Quantum Platform dan `job.primitive_id` akan menunjukkan `executor` dan bukannya `estimator`.	Kemas kini sebarang kod yang merujuk `job.primitive_id`.
Pelaksanaan baharu memetakan input Estimator kepada input Executor, jadi `job.inputs` mengembalikan input Executor.	Kemas kini sebarang kod yang merujuk `job.inputs`. Lihat Input kerja.
Lebih banyak pemprosesan pra dan pasca kini berlaku pada sisi klien, jadi `estimator.run()` dan `job.result()` mungkin mengambil masa lebih lama daripada sebelum ini.	Dayakan pengelogan INFO untuk mengikuti kemajuan pemprosesan sisi klien. Lihat Dayakan pengelogan INFO.
Metadata litar disalin ke dalam metadata hasil. Jenis data yang dibenarkan dalam metadata hasil kini terhad kepada `str`, `float`, `int`, `bool`, dan senarai atau kamus jenis tersebut.	Jika anda memerlukan jenis data lain, kodkannya sebagai rentetan dahulu (contohnya, dengan base64).
Kelas pilihan (`options_models.EstimatorOptions` dan sebagainya) kini adalah model Pydantic dan bukannya dataclass, jadi ia tidak lagi boleh ditukar kepada kamus Python menggunakan `asdict()`.	Gunakan `options.model_dump()` sebaliknya.
Kelas pilihan yang sebelum ini mempunyai akhiran `V2` (`ExecutionOptionsV2` dan sebagainya) tidak lagi mempunyainya, memandangkan primitif V1 tidak lagi disokong.	Buang akhiran `V2` kelas pilihan ini: gantikan `ExecutionOptionsV2` dengan `ExecutionOptions` dan `ResilienceOptionsV2` dengan `ResilienceOptions`.
Semua pilihan input dikembalikan dalam metadata hasil, bukannya subset terpilih.	Tiada — ini adalah maklumat sahaja.
Sebahagian pengesahan input telah dipindahkan ke sisi pelayan dan kini menimbulkan `RuntimeError` dan bukannya `IBMInputValueError`.	Kemas kini jenis pengecualian yang ditangkap oleh kod anda.
Tiada lagi pembelajaran hingar tersirat untuk PEA dan PEC. Pembelajaran hingar pengukuran untuk TREX masih disokong.	Pelajari model hingar secara berasingan dan hantarkannya kepada Estimator. Lihat Lakukan pembelajaran hingar eksplisit untuk PEA dan PEC.
Jenis input `ResilienceOptions.layer_noise_model` adalah berbeza dan boleh dibina daripada hasil `NoiseLearnerV3`.	Lihat Lakukan pembelajaran hingar eksplisit untuk PEA dan PEC tentang cara mempelajari model hingar menggunakan `NoiseLearnerV3` dan menghantarkannya kepada Estimator.
`MeasureNoiseLearningOptions.shots_per_randomization` tidak lagi disokong.	Satu nilai shot digunakan untuk semua litar dalam kerja tersebut, termasuk litar pembelajaran hingar pengukuran. Jika anda perlu menggunakan nilai shot yang berbeza, gunakan TREX dengan `qiskit-mitigation` di luar Estimator.
Nilai ketepatan yang bercampur dalam satu kerja tidak lagi disokong.	Hantar kerja berasingan untuk setiap ketepatan yang dikehendaki. Lihat Pemisahan kerja untuk pertimbangan.
Pilihan `seed_estimator` tidak lagi disokong.	Buang sebarang penetapan `options.seed_estimator` (menetapkannya akan menimbulkan `ValidationError`). Tiada persamaan sisi klien, jadi hasil tidak lagi boleh dihasilkan semula melalui seed ini.

Dayakan pengelogan INFO

Kerana lebih banyak kerja kini berlaku pada sisi klien, adalah berguna untuk melihat kemajuan pemprosesan tersebut. Dayakan pengelogan peringkat INFO untuk pengelog qiskit_ibm_runtime:

import logging

logger = logging.getLogger("qiskit_ibm_runtime")
logger.setLevel(logging.INFO)

Lakukan pembelajaran hingar eksplisit untuk PEA dan PEC

Estimator baharu tidak lagi melakukan pembelajaran hingar tersirat apabila kaedah pengurangan ralat PEA atau PEC dipilih. Anda mesti mempelajari model hingar secara eksplisit dan menghantarnya masuk. Gunakan NoiseLearnerV3 baharu untuk mengawal cara litar distratakan ke dalam lapisan. Ia menerima senarai arahan litar berkotak (contohnya, lapisan unik) sebagai input.

Penting

PEA dan PEC kini memerlukan corak eksplisit ini. Jangan langkau langkah pembelajaran hingar kerana kod anda akan gagal. Pembelajaran hingar pengukuran untuk TREX tidak terjejas dan terus berfungsi seperti sebelum ini.

Begitu juga, jika kod anda menggunakan NoiseLearner dan menghantar model hingar yang terhasil kepada Estimator sisi pelayan, anda perlu migrasi ke NoiseLearnerV3. JANGAN gunakan NoiseLearner yang lebih lama, yang tidak serasi dengan Estimator baharu.

Semua pilihan pembelajaran hingar dalam Estimator sisi pelayan (LayerNoiseLearningOptions) dipetakan terus kepada pilihan NoiseLearnerV3 (NoiseLearnerV3Options), dengan pengecualian max_layers_to_learn. Bilangan lapisan yang perlu dipelajari sebaliknya berdasarkan bilangan lapisan yang dihantar kepada NoiseLearnerV3.

Sebagai contoh:

Estimator sisi pelayan (dengan PEC didayakan):

from qiskit_ibm_runtime import Estimator

pubs = [...]  # Your PUBs
estimator = Estimator(mode, options)
estimator.options.resilience.pec_mitigation = True  # or zne_mitigation + pea amplifier
estimator.options.resilience.layer_noise_learning.num_randomizations = 64

job = estimator.run(pubs)

Estimator sisi klien (dengan PEC didayakan):

from qiskit_ibm_runtime.executor_estimator import Estimator
from qiskit_ibm_runtime import NoiseLearnerV3

pubs = [...]  # Your PUBs
estimator = Estimator(mode, options)
estimator.options.resilience.pec_mitigation = True  # or zne_mitigation + pea amplifier

# Identify the unique layers to learn.
layers = estimator.find_unique_layers(pubs)

# Learn the noise model for those layers (runs as a separate job).
learner = NoiseLearnerV3(mode)
learner.options.num_randomizations = 64  # Same as layer_noise_learning.num_randomizations
learner_job = learner.run(layers)
learner_result = learner_job.result()

# Convert results to Pauli-Lindblad noise maps.
pauli_lindblad_maps = learner_result.to_pauli_lindblad_maps()

# Assign the learned noise maps so PEA/PEC uses them.
estimator.options.resilience.layer_noise_model = zip(layers, pauli_lindblad_maps)

# Now execute the target PUBs.
job = estimator.run(pubs)

Migrasi daripada `NoiseLearner` ke `NoiseLearnerV3`

NoiseLearner hanya berfungsi dengan pelaksanaan sisi pelayan Estimator. Oleh itu, jika kod anda menggunakan NoiseLearner untuk mempelajari model hingar dan menghantarnya kepada Estimator, anda perlu mengemas kini kod anda untuk menggunakan NoiseLearnerV3.

Lihat panduan Migrasi daripada NoiseLearner ke NoiseLearnerV3 untuk butiran.

Pemisahan kerja

Apabila anda perlu memisahkan satu kerja kepada beberapa kerja kerana nilai shot atau ketepatan yang bercampur dalam satu kerja tidak lagi disokong, pertimbangkan perkara berikut:

Kumpulkan PUB mengikut nilai sasaran mereka — satu kerja bagi setiap nilai berbeza, bukan satu kerja bagi setiap PUB. Pemisahan adalah pengumpulan semula, jadi jumlah bilangan PUB yang anda hantar tidak berubah. Sebagai contoh, diberi [A@0.01, B@0.05, C@0.01], hantar dua kerja: [A, C] pada precision=0.01 dan [B] pada precision=0.05. Menghantar A dan C sebagai kerja berasingan adalah kurang cekap, kerana setiap kerja datang dengan overhead tetap.
Pelajari sekali dan gunakan model hingar dalam semua kerja yang dipisahkan. Adalah lebih cekap untuk menjalankan satu kerja NoiseLearnerV3 ke atas gabungan semua lapisan. Hasil kerja pembelajar hingar mengandungi senarai objek NoiseLearnerV3Result, satu untuk setiap arahan input, dan mengikut susunan yang sama seperti senarai input. Anda boleh menggunakan output kerja pembelajar hingar ini dalam semua kerja (Estimator) yang dipisahkan, dan model hingar untuk lapisan yang tiada dalam PUB kerja yang dipisahkan akan diabaikan.
Hantar semua kerja yang dipisahkan dalam Batch terlebih dahulu, kemudian kumpulkan hasilnya. Mod pelaksanaan Batch menyediakan pelaksanaan selari yang cekap apabila terdapat pelbagai kerja. Walau bagaimanapun, job.result() adalah menyekat, jadi memanggilnya di dalam gelung penghantaran akan menyiri-alirkan kerja tersebut dan menghapuskan faedah menggunakan Batch. Pastikan anda menggunakan corak hantar-semua-kemudian-kumpul (ditunjukkan di bawah).

Dalam contoh berikut, pub1 dan pub2 memerlukan precision=0.5, manakala pub3 memerlukan precision=0.1:

group1_pubs = [pub1, pub2]
group2_pubs = [pub3]

with Batch(backend=backend) as batch:
    estimator = Estimator(mode=batch)
    estimator.options.resilience.pec_mitigation = True

    # Learn once, over the union of every job's layers.
    all_layers = estimator.find_unique_layers(group1_pubs + group2_pubs)
    learner_job = NoiseLearnerV3(mode=batch).run(all_layers)
    learner_result = learner_job.result()
    pauli_lindblad_maps = learner_result.to_pauli_lindblad_maps()

    # Assign the learned noise maps. Any layers not found in the input PUBs are ignored.
    estimator.options.resilience.layer_noise_model = zip(all_layers, pauli_lindblad_maps)

    # Submit every split job with different precision values.
    jobs = []
    jobs.append(estimator.run(group1_pubs, precision=0.5))
    jobs.append(estimator.run(group2_pubs, precision=0.1))

    # Block once, at the end — the jobs run in parallel.
    results = [job.result() for job in jobs]

Struktur input kerja

Pelaksanaan baharu memetakan input Sampler atau Estimator kepada input Executor, jadi job.inputs mengembalikan kamus yang mengandungi input Executor. Kamus ini mempunyai kekunci berikut:

options: Input ExecutorOption.
quantum_program: Input QuantumProgram
schema_version: Versi skema sisi pelayan yang digunakan.

Jika kod anda menggunakan job.inputs['options'] untuk mencari pilihan yang dinyatakan untuk kerja tersebut, kini anda boleh menggunakan job.result().metadata['options'] sebaliknya.

Uji secara tempatan dengan backend palsu

Sebelum menghantar ke perkakasan, anda boleh mengesahkan kod yang dimigrasi terhadap backend Fake* untuk mengesan sebarang ralat sintaks lebih awal. Ambil perhatian butiran berikut tentang mod ujian tempatan:

Ia tidak menghasilkan semula hasil perkakasan. Simulasi hingar tempatan tidak mereplikasi hingar peranti sebenar dengan sempurna, oleh itu output mungkin berbeza. Menjalankannya tetap mengesahkan bahawa laluan pilihan dan jenis nilai adalah betul.
NoiseLearnerV3 tiada mod ujian tempatan: mode-nya hanya menerima Backend, Session, atau Batch sebenar, jadi anda tidak boleh menjalankan langkah pembelajaran hingar terhadap backend palsu. Sahkan bahagian kod anda itu terhadap rujukan API NoiseLearnerV3 sebaliknya. Sahkan bahawa konstruktor, bentuk input run(instructions), dan sebarang pembantu (seperti pembantu lapisan unik) digunakan seperti yang didokumenkan.

Cliffordkan litar untuk simulasi tempatan yang cekap

Backend palsu menggunakan penstimulasi statevector (hingar), yang kosnya berkembang secara eksponen dengan bilangan qubit dan kedalaman. Oleh itu, litar beban kerja yang realistik boleh tergantung atau menghabiskan memori. Kerana ujian tempatan hanya perlu menjalankan laluan pilihan (bukan menghasilkan semula keputusan fizikal), kurangkan litar kepada litar Clifford terlebih dahulu dengan ConvertISAToClifford, yang membundarkan setiap sudut RZ/RZZ/RX kepada gandaan π/2 yang terdekat. Litar Clifford disimulasikan dengan cekap (simulasi penstabil) tanpa mengira saiz.

from qiskit.transpiler import PassManager
from qiskit_ibm_runtime.transpiler.passes import ConvertISAToClifford

clifford = PassManager([ConvertISAToClifford()]).run(isa_circuit)
# run `clifford` (not the original) through the fake-backend primitive

ConvertISAToClifford memerlukan litar ISA sebagai input (output daripada generate_preset_pass_manager(...).run(...) yang menyasarkan backend). Anda perlu mengambil kira akibat berikut apabila membina PUB tempatan:

Atribut .layout digugurkan. Litar yang telah di-Cliffordkan mengekalkan bilangan qubit yang sama, tetapi clifford.layout adalah None, jadi observable.apply_layout(clifford.layout) gagal. Susun observable tersebut daripada litar ISA pra-Clifford sebaliknya: isa_obs = observable.apply_layout(isa_circuit.layout), kemudian jalankan (clifford, isa_obs).
Parameter diikat terus. Membundarkan sudut putaran menukarkan litar ISA parametrik kepada litar Clifford konkrit, jadi clifford.num_parameters menjadi 0. PUB yang masih membawa array nilai-parameter gagal dipaksa. Untuk larian tempatan, buang array parameter daripada PUB; larian perkakasan mengekalkan litar parametrik asal dan nilainya.

Langkah seterusnya

Cadangan

Latar Belakang​

Kemas kini import​

Apa yang kekal sama​

Perubahan tidak serasi dalam Sampler baharu​

Perubahan tidak serasi dalam Estimator baharu​

Dayakan pengelogan INFO​

Lakukan pembelajaran hingar eksplisit untuk PEA dan PEC​

Migrasi daripada NoiseLearner ke NoiseLearnerV3​

Pemisahan kerja​

Struktur input kerja​

Uji secara tempatan dengan backend palsu​

Cliffordkan litar untuk simulasi tempatan yang cekap​

Langkah seterusnya​