Takrifkan input dan output

Aliran kerja terurus berfungsi seperti fungsi Python yang berjalan pada pengiraan jauh. Bandingkan fungsi tempatan dengan kod yang sama sebagai aliran kerja:

Local Python

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

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

Dalam aliran kerja terurus, run() ialah panggilan, get_arguments() memberi aliran kerja parameternya, dan save_result() ialah pernyataan returnnya. Oleh sebab aliran kerja berjalan sebagai job berasingan pada pengiraan jauh, ia berbeza daripada panggilan fungsi tempatan dalam tiga cara:

• Klien mengekod argumen dan hasil. Setiap nilai mestilah nilai yang boleh dikodkan oleh klien, dan sesetengah jenis berubah. Lihat Baca argumen dalam aliran kerja anda.

• Panggilan tidak menunggu. run() mengembalikan job serta-merta, dan anda membaca hasil kemudian dengan job.result(). Lihat Simpan hasil.

• Tiada apa-apa yang menyemak panggilan. Fungsi Python menolak argumen kata kunci yang tidak dikenali, tetapi aliran kerja mengabaikannya melainkan anda melampirkan skema. Lihat Amalan terbaik: sahkan argumen dengan skema.

Baca argumen dalam aliran kerja anda

Hantar input ke aliran kerja anda daripada notebook tempatan anda:

run_workflow_remotely.ipynb

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

Untuk membolehkan ini, sunting kod aliran kerja anda untuk mengambil argumen dengan get_arguments(), yang mengembalikan kamus yang kuncinya ialah nama argumen:

source_files/my_workflow.py

from qiskit_serverless import get_arguments

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

Kamus hanya mengandungi argumen yang dihantar oleh larian, jadi gunakan arguments.get() dengan nilai lalai untuk argumen pilihan. Anda boleh menggunakan sebarang nama argumen kecuali kata kunci terlindung config dan function_size, kerana run() menggunakan kata kunci ini secara langsung. run() juga menolak compute_profile. Untuk memilih sumber pengiraan, hantar function_size.

Untuk membaca saiz yang digunakan job semasa berjalan, panggil get_function_size() dalam kod aliran kerja anda:

source_files/my_workflow.py

from qiskit_serverless import get_function_size

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

Jika larian tidak menghantar function_size, get_function_size() mengembalikan saiz lalai aliran kerja. Lihat Pilih saiz untuk setiap larian.

Jenis argumen yang disokong

Setiap nilai mestilah boleh bersiri JSON, atau objek yang boleh dikodkan oleh klien, seperti litar Qiskit atau tatasusunan NumPy. Oleh sebab klien mengekod setiap argumen sebelum menghantar job dan get_arguments() menyahkodnya di dalam aliran kerja, aliran kerja menerima objek Python yang asal.

Klien menghantar int, float, str, bool, None, dan senarai atau kamus bagi jenis ini tanpa perubahan. Ia mengekod objek lain, seperti QuantumCircuit, numpy.ndarray atau nombor complex, sebagai kamus dengan teg __type__ dan __value__. Anda memerlukan bentuk ini apabila menulis skema argumen.

Oleh sebab JSON tidak mempunyai setara untuk sesetengah jenis, jenis ini berubah semasa pengekodan. Tuple tiba sebagai senarai, kunci kamus tiba sebagai rentetan, dan integer NumPy seperti np.int64 tiba sebagai int. Jika klien tidak dapat mengekod sesuatu nilai, seperti bytes atau np.float32, run() menimbulkan TypeError dan tidak mencipta job.

Sesetengah objek tidak boleh dihantar sebagai argumen. Contohnya, hantar nama backend sebagai rentetan dan bukannya objek Backend, dan cipta backend di dalam aliran kerja. Lihat Jalankan job kuantum daripada aliran kerja.

Had saiz

Argumen bagi satu larian boleh mencecah 32 MB selepas pengekodan. Contohnya, satu litar 100-qubit dengan kedalaman 100 dikodkan kepada kira-kira 39 KB, jadi satu larian boleh menerima batch kira-kira 800 litar sedemikian. Untuk input yang lebih besar, muat naik fail dan hantar namanya sebagai argumen.

Simpan hasil

Gunakan save_result() di hujung aliran kerja anda untuk mengembalikan hasil ke notebook anda. Baca hasil dalam notebook anda dengan job.result():

run_workflow_remotely.ipynb

result = job.result()

Untuk membolehkan ini, panggil save_result() dalam kod aliran kerja anda:

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() mengekod hasil dengan cara yang sama klien mengekod argumen, dan job.result() menyahkodnya. Oleh itu, hasil boleh mengandungi jenis argumen yang disokong, seperti litar, tatasusunan NumPy dan hasil job primitif, dengan perubahan jenis yang sama.

• Semak nilai pulangan. Jika save_result() tidak dapat mengekod nilai itu, ia mencatat amaran dan mengembalikan False dan bukannya menimbulkan ralat. Tanpa semakan, job boleh berakhir dengan status DONE dan tanpa hasil.

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

• Kamus kosong bermakna tiada hasil. Jika aliran kerja tidak pernah memanggil save_result(), job.result() mengembalikan {}.

Untuk mengembalikan fail, seperti tatasusunan besar atau plot, simpan dalam storan fail dan kembalikan namanya dalam hasil.

Amalan terbaik: sahkan argumen dengan skema

Sebagai amalan terbaik, lampirkan JSON Schema pada setiap aliran kerja yang menerima argumen. Skema menerangkan argumen yang diterima aliran kerja, dan aliran kerja menyemak argumen setiap larian terhadapnya sebelum mencipta job. Jika argumen tidak sepadan, run() gagal serta-merta dengan ralat yang menamakan medan yang salah, dan aliran kerja tidak mencipta job. Tanpa skema, argumen yang salah sampai ke aliran kerja selepas job bermula, dan aliran kerja mengabaikan nama argumen yang salah eja.

Tetapkan skema dengan arguments_schema apabila anda memuat naik aliran kerja. Hantar kamus, bukan rentetan 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 perkara berikut apabila anda menulis skema:

• Terangkan bentuk terkod bagi objek Qiskit dan NumPy. Skema menyemak argumen seperti yang dihantar oleh klien, jadi litar ialah objek seperti {"__type__": "QuantumCircuit", "__value__": "<base64-encoded QPY>"}, bukan rentetan atau tatasusunan. Semak teg __type__, dan anggap __value__ sebagai rentetan legap. Skema yang menerangkan litar sebagai rentetan menolak setiap larian yang sah.

• Tetapkan "additionalProperties": false. Tanpa tetapan ini, aliran kerja mengabaikan nama argumen yang salah eja, seperti shotz, tanpa amaran, dan berjalan dengan nilai lalainya. Isytiharkan setiap argumen yang diterima aliran kerja sebelum anda mendayakan tetapan ini.

• Tandakan argumen sebagai wajib. Tambahkan setiap argumen yang dibaca aliran kerja tanpa nilai lalai ke dalam required.

Jika argumen tidak sepadan dengan skema, mesej ralat menamakan peraturan dan lokasi nilai yang salah:

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

Skema menyemak jenis, bentuk dan julat setiap argumen. Skema tidak dapat menyemak sama ada dua argumen yang sah saling bercanggah, atau sama ada litar muat pada backend. Simpan semakan itu dalam kod aliran kerja.

Kemas kini atau alih keluar skema

• Untuk menggantikan skema, tetapkan arguments_schema baharu dan muat naik aliran kerja sekali lagi.

• Untuk mengalih keluar skema, muat naik aliran kerja dengan arguments_schema={}.

• Jika anda memuat naik aliran kerja tanpa arguments_schema, aliran kerja mengekalkan skema yang tersimpan.

Untuk melihat skema yang berkuat kuasa, baca my_workflow.arguments_schema. Nilai None bermakna aliran kerja tiada skema.

Semak argumen sebelum anda menjalankan

Panggil validate_arguments() untuk menyemak satu set argumen terhadap skema tanpa memulakan job:

run_workflow_remotely.ipynb

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

Jika argumen tidak sah, validate_arguments() menimbulkan QiskitServerlessException dengan mesej yang sama seperti yang dikembalikan run() untuk argumen tersebut. Jika aliran kerja tiada skema, sebarang argumen adalah sah. Hasil yang sah tidak menjamin run() berjaya, kerana run() juga menyemak had lain, seperti bilangan job aktif.

Peraturan skema

Aliran kerja terurus menolak muat naik jika skema melanggar mana-mana peraturan berikut:

• Skema boleh sehingga 64 KiB, dengan sehingga 64 tahap sarang dan sehingga 200 subskema.

• Rujukan mestilah menunjuk ke dalam skema yang sama, seperti #/$defs/circuit, dan setiap rujukan mesti dapat diselesaikan. Rujukan kepada URL atau fail tidak dibenarkan.

• Skema mestilah objek atau boolean.

Elakkan juga masalah berikut, yang tidak dikesan oleh muat naik:

• Pengkuantiti bersarang dalam pattern. Corak seperti ^(a+)+$ boleh mengambil masa yang sangat lama untuk dinilai. Aliran kerja menghentikan pengesahan selepas had masa CPU dan menolak larian. Tulis corak tanpa pengkuantiti di sekeliling kumpulan yang sudah mengandunginya, seperti ^ibm_[a-z0-9_]{1,40}$.

• false sebagai skema. Skema false menolak setiap larian. Untuk mengalih keluar pengesahan, gunakan {}.

Selesaikan masalah skema

Masalah	Punca
Setiap larian ditolak pada argumen litar.	Skema menerangkan litar sebagai rentetan atau tatasusunan. Terangkan ia sebagai objek dengan teg __type__.
Larian yang sah ditolak.	additionalProperties ialah false, dan skema tidak mengisytiharkan argumen yang dihantar oleh larian. path ralat menamakan argumen itu.
Larian yang tidak sah tidak ditolak.	Aliran kerja tiada skema. Semak my_workflow.arguments_schema.
Tiada larian disemak, walaupun anda menetapkan skema.	Skema dihantar sebagai rentetan JSON. Hantar kamus.
Muat naik gagal dengan ralat 400.	Skema melanggar salah satu peraturan skema.
Ralat menyatakan bahawa pengesahan mengambil terlalu banyak masa CPU.	pattern mempunyai pengkuantiti bersarang. Tulis semula corak itu.