Tentukan input dan output

Managed workflow bekerja seperti fungsi Python yang berjalan di compute jarak jauh. Bandingkan fungsi lokal dengan kode yang sama sebagai workflow:

Local Python

def my_workflow(circuits, shots=4096):
    ...
    return {"counts": counts}

result = my_workflow(circuits=circuits, shots=1024)

Di managed workflow, run() adalah pemanggilnya, get_arguments() memberi workflow parameternya, dan save_result() adalah pernyataan return-nya. Karena workflow berjalan sebagai job terpisah di compute jarak jauh, ia berbeda dari pemanggilan fungsi lokal dalam tiga hal:

• Client meng-encode argumen dan hasil. Setiap nilai harus berupa nilai yang bisa di-encode oleh client, dan beberapa tipe berubah. Lihat Baca argumen di workflow-mu.

• Pemanggilan tidak menunggu. run() langsung mengembalikan job, dan kamu membaca hasilnya nanti dengan job.result(). Lihat Simpan hasil.

• Tidak ada yang memeriksa pemanggilan. Fungsi Python menolak keyword argument yang tidak dikenal, tetapi workflow mengabaikannya kecuali kamu memasang schema. Lihat Praktik terbaik: validasi argumen dengan schema.

Baca argumen di workflow-mu

Kirim input ke workflow-mu dari notebook lokalmu:

run_workflow_remotely.ipynb

job = my_workflow.run(circuits=circuits, shots=1024)

Agar ini berfungsi, ubah kode workflow-mu untuk mengambil argumen dengan get_arguments(), yang mengembalikan dictionary dengan nama argumen sebagai key:

source_files/my_workflow.py

from qiskit_serverless import get_arguments

arguments = get_arguments()
circuits = arguments["circuits"]
shots = arguments.get("shots", 4096)

Dictionary hanya berisi argumen yang diberikan oleh run, jadi gunakan arguments.get() dengan nilai default untuk argumen opsional. Kamu bisa memakai nama argumen apa pun kecuali keyword yang dilindungi config dan function_size, karena run() memakai keyword ini secara langsung. run() juga menolak compute_profile. Untuk memilih resource compute, berikan function_size.

Untuk membaca ukuran yang dipakai job saat berjalan, panggil get_function_size() di kode workflow-mu:

source_files/my_workflow.py

from qiskit_serverless import get_function_size

size = get_function_size()  # For example, "M"

Kalau run tidak memberikan function_size, get_function_size() mengembalikan ukuran default workflow. Lihat Pilih ukuran untuk setiap run.

Tipe argumen yang didukung

Setiap nilai harus bisa di-serialisasi ke JSON, atau berupa objek yang bisa di-encode oleh client, seperti circuit Qiskit atau array NumPy. Karena client meng-encode setiap argumen sebelum mengirim job dan get_arguments() men-decode-nya di dalam workflow, workflow menerima objek Python aslinya.

Client mengirim int, float, str, bool, None, serta list atau dictionary dari tipe-tipe ini tanpa perubahan. Objek lain, seperti QuantumCircuit, numpy.ndarray, atau bilangan complex, di-encode sebagai dictionary dengan tag __type__ dan __value__. Kamu membutuhkan bentuk ini saat menulis schema argumen.

Karena JSON tidak punya padanan untuk beberapa tipe, tipe-tipe ini berubah saat di-encode. Tuple tiba sebagai list, key dictionary tiba sebagai string, dan integer NumPy seperti np.int64 tiba sebagai int. Kalau client tidak bisa meng-encode sebuah nilai, seperti bytes atau np.float32, run() memunculkan TypeError dan tidak membuat job.

Beberapa objek tidak bisa diberikan sebagai argumen. Misalnya, berikan nama backend sebagai string, bukan objek Backend, dan buat backend-nya di dalam workflow. Lihat Jalankan job kuantum dari workflow.

Batas ukuran

Argumen untuk satu run bisa sampai 32 MB setelah di-encode. Misalnya, satu circuit 100-qubit dengan depth 100 di-encode menjadi sekitar 39 KB, sehingga satu run bisa menerima batch sekitar 800 circuit seperti itu. Untuk input yang lebih besar, unggah file dan berikan namanya sebagai argumen.

Simpan hasil

Gunakan save_result() di akhir workflow-mu untuk mengembalikan hasil ke notebook-mu. Baca hasilnya di notebook dengan job.result():

run_workflow_remotely.ipynb

result = job.result()

Agar ini berfungsi, panggil save_result() di kode workflow-mu:

source_files/my_workflow.py

from qiskit_serverless import save_result

if not save_result({"counts": counts, "circuit": isa_circuit}):
    raise ValueError("The result could not be encoded.")

save_result() meng-encode hasil dengan cara yang sama seperti client meng-encode argumen, dan job.result() men-decode-nya. Jadi hasil bisa berisi tipe argumen yang didukung, seperti circuit, array NumPy, dan hasil dari primitive job, dengan perubahan tipe yang sama.

• Periksa nilai kembaliannya. Kalau save_result() tidak bisa meng-encode nilainya, ia mencatat warning dan mengembalikan False, bukan memunculkan error. Tanpa pemeriksaan, job bisa berakhir dengan status DONE tanpa hasil.

• Hanya save_result() yang terakhir yang disimpan. Setiap pemanggilan menggantikan hasil yang tersimpan. Untuk mengembalikan beberapa nilai, simpan dalam satu dictionary, atau tulis ke log.

• Dictionary kosong berarti tidak ada hasil. Kalau workflow tidak pernah memanggil save_result(), job.result() mengembalikan {}.

Untuk mengembalikan file, seperti array besar atau plot, simpan ke penyimpanan file dan kembalikan namanya di hasil.

Praktik terbaik: validasi argumen dengan schema

Sebagai praktik terbaik, pasang JSON Schema ke setiap workflow yang menerima argumen. Schema menjelaskan argumen yang diterima workflow, dan workflow memeriksa argumen setiap run terhadapnya sebelum membuat job. Kalau argumen tidak cocok, run() langsung gagal dengan error yang menyebut field yang salah, dan workflow tidak membuat job. Tanpa schema, argumen yang salah baru sampai ke workflow setelah job dimulai, dan workflow mengabaikan nama argumen yang salah eja.

Atur schema dengan arguments_schema saat kamu mengunggah workflow. Berikan dictionary, bukan string JSON:

run_workflow_remotely.ipynb

from qiskit_ibm_catalog import ManagedWorkflow, ManagedWorkflowClient

arguments_schema = {
    "type": "object",
    "additionalProperties": False,
    "required": ["circuits"],
    "properties": {
        "circuits": {
            "type": "array",
            "minItems": 1,
            "items": {"$ref": "#/$defs/circuit"},
        },
        "shots": {"type": "integer", "minimum": 1, "maximum": 100000},
        "backend_name": {"type": "string", "minLength": 1},
    },
    "$defs": {
        "circuit": {
            "type": "object",
            "required": ["__type__", "__value__"],
            "properties": {
                "__type__": {"const": "QuantumCircuit"},
                "__value__": {"type": "string"},
            },
        }
    },
}

client = ManagedWorkflowClient()

my_workflow = client.upload(
    ManagedWorkflow(
        title="my-workflow",
        entrypoint="my_workflow.py",
        working_dir="./source_files/",
        arguments_schema=arguments_schema,
    )
)

Ingat poin-poin berikut saat menulis schema:

• Jelaskan bentuk ter-encode dari objek Qiskit dan NumPy. Schema memeriksa argumen sebagaimana dikirim client, jadi sebuah circuit adalah objek seperti {"__type__": "QuantumCircuit", "__value__": "<base64-encoded QPY>"}, bukan string atau array. Periksa tag __type__, dan perlakukan __value__ sebagai string buram. Schema yang menjelaskan circuit sebagai string akan menolak setiap run yang valid.

• Atur "additionalProperties": false. Tanpa pengaturan ini, workflow mengabaikan nama argumen yang salah eja, seperti shotz, tanpa peringatan, dan berjalan dengan nilai defaultnya. Deklarasikan setiap argumen yang diterima workflow sebelum kamu mengaktifkan pengaturan ini.

• Tandai argumen sebagai wajib. Tambahkan setiap argumen yang dibaca workflow tanpa nilai default ke required.

Kalau argumen tidak cocok dengan schema, pesan error menyebut aturan dan lokasi nilai yang salah:

'type' validation failed, schema requires 'integer': rejected value '4096'
path: ['shots']

Schema memeriksa tipe, bentuk, dan rentang setiap argumen. Schema tidak bisa memeriksa apakah dua argumen yang valid saling bertentangan, atau apakah sebuah circuit cocok dengan backend. Simpan pemeriksaan semacam itu di kode workflow.

Perbarui atau hapus schema

• Untuk mengganti schema, atur arguments_schema yang baru dan unggah workflow lagi.

• Untuk menghapus schema, unggah workflow dengan arguments_schema={}.

• Kalau kamu mengunggah workflow tanpa arguments_schema, workflow mempertahankan schema yang tersimpan.

Untuk melihat schema yang sedang berlaku, baca my_workflow.arguments_schema. Nilai None berarti workflow tidak punya schema.

Periksa argumen sebelum menjalankan

Panggil validate_arguments() untuk memeriksa sekumpulan argumen terhadap schema tanpa memulai job:

run_workflow_remotely.ipynb

my_workflow.validate_arguments({"circuits": [circuit], "shots": 1024})
# {'valid': True}

Kalau argumen tidak valid, validate_arguments() memunculkan QiskitServerlessException dengan pesan yang sama seperti yang dikembalikan run() untuk argumen tersebut. Kalau workflow tidak punya schema, argumen apa pun valid. Hasil valid tidak menjamin run() berhasil, karena run() juga memeriksa batas lain, seperti jumlah job aktif.

Aturan schema

Managed workflow menolak unggahan kalau schema melanggar salah satu aturan berikut:

• Schema bisa berukuran sampai 64 KiB, dengan sampai 64 level nesting dan sampai 200 subschema.

• Referensi harus menunjuk ke dalam schema yang sama, seperti #/$defs/circuit, dan setiap referensi harus bisa di-resolve. Referensi ke URL atau file tidak diizinkan.

• Schema harus berupa objek atau boolean.

Hindari juga masalah berikut, yang tidak terdeteksi saat unggah:

• Quantifier bersarang di pattern. Pola seperti ^(a+)+$ bisa memakan waktu sangat lama untuk dievaluasi. Workflow menghentikan validasi setelah batas waktu CPU dan menolak run. Tulis pola tanpa quantifier di sekitar grup yang sudah berisi quantifier, seperti ^ibm_[a-z0-9_]{1,40}$.

• false sebagai schema. Schema false menolak setiap run. Untuk menghapus validasi, gunakan {}.

Atasi masalah schema

Masalah	Penyebab
Setiap run ditolak pada argumen circuit.	Schema menjelaskan circuit sebagai string atau array. Jelaskan sebagai objek dengan tag __type__.
Run yang valid ditolak.	additionalProperties bernilai false, dan schema tidak mendeklarasikan argumen yang diberikan run. path pada error menyebut argumennya.
Run yang tidak valid tidak ditolak.	Workflow tidak punya schema. Periksa my_workflow.arguments_schema.
Tidak ada run yang diperiksa, padahal kamu sudah mengatur schema.	Schema diberikan sebagai string JSON. Berikan dictionary.
Unggahan gagal dengan error 400.	Schema melanggar salah satu aturan schema.
Error menyebut validasi memakan terlalu banyak waktu CPU.	pattern punya quantifier bersarang. Tulis ulang polanya.