Tukuyin ang mga input at output

Gumagana ang managed workflow na parang Python function na tumatakbo sa remote compute. Ihambing ang isang local function sa parehong code bilang workflow:

Local Python

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

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

Sa isang managed workflow, ang run() ang tawag, ang get_arguments() ang nagbibigay sa workflow ng mga parameter nito, at ang save_result() ang return statement nito. Dahil tumatakbo ang workflow bilang hiwalay na job sa remote compute, naiiba ito sa local function call sa tatlong paraan:

• Ine-encode ng client ang mga argument at resulta. Dapat ang bawat value ay isang kayang i-encode ng client, at may mga type na nagbabago. Tingnan ang Basahin ang mga argument sa workflow mo.

• Hindi naghihintay ang tawag. Agad na nagbabalik ng job ang run(), at babasahin mo ang resulta sa ibang pagkakataon gamit ang job.result(). Tingnan ang I-save ang mga resulta.

• Walang sumusuri sa tawag. Tinatanggihan ng Python function ang hindi kilalang keyword argument, pero binabalewala ito ng workflow maliban kung maglakip ka ng schema. Tingnan ang Best practice: i-validate ang mga argument gamit ang schema.

Basahin ang mga argument sa workflow mo

Magpasa ng mga input sa workflow mo mula sa local notebook mo:

run_workflow_remotely.ipynb

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

Para magawa ito, i-edit ang code ng workflow mo para kunin ang mga argument gamit ang get_arguments(), na nagbabalik ng dictionary na ang mga key ay ang mga pangalan ng argument:

source_files/my_workflow.py

from qiskit_serverless import get_arguments

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

Naglalaman lang ang dictionary ng mga argument na ipinasa ng run, kaya gamitin ang arguments.get() na may default na value para sa mga opsyonal na argument. Puwede kang gumamit ng kahit anong pangalan ng argument maliban sa mga protektadong keyword na config at function_size, dahil direktang ginagamit ng run() ang mga keyword na ito. Tinatanggihan din ng run() ang compute_profile. Para pumili ng compute resources, ipasa ang function_size.

Para basahin ang laki kung saan tumatakbo ang job, tawagin ang get_function_size() sa code ng workflow mo:

source_files/my_workflow.py

from qiskit_serverless import get_function_size

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

Kung hindi nagpasa ng function_size ang run, ibinabalik ng get_function_size() ang default na laki ng workflow. Tingnan ang Pumili ng laki para sa bawat run.

Mga suportadong uri ng argument

Dapat JSON-serializable ang bawat value, o isang object na kayang i-encode ng client, gaya ng Qiskit circuit o NumPy array. Dahil ine-encode ng client ang bawat argument bago ipadala ang job at dine-decode ito ng get_arguments() sa loob ng workflow, natatanggap ng workflow ang orihinal na Python object.

Ipinapadala ng client nang walang pagbabago ang int, float, str, bool, None, at mga list o dictionary ng mga ito. Ine-encode nito ang iba pang object, gaya ng QuantumCircuit, numpy.ndarray, o complex na numero, bilang dictionary na may __type__ tag at __value__. Kailangan mo ang anyong ito kapag sumusulat ka ng argument schema.

Dahil walang katumbas sa JSON ang ilang type, nagbabago ang mga type na ito habang ine-encode. Dumarating bilang list ang mga tuple, dumarating bilang string ang mga dictionary key, at dumarating bilang int ang mga NumPy integer gaya ng np.int64. Kung hindi ma-encode ng client ang isang value, gaya ng bytes o np.float32, nagtataas ang run() ng TypeError at hindi gumagawa ng job.

Hindi maipapasa bilang argument ang ilang object. Halimbawa, ipasa ang pangalan ng backend bilang string sa halip na Backend object, at likhain ang backend sa loob ng workflow. Tingnan ang Magpatakbo ng mga quantum job mula sa workflow.

Mga limitasyon sa laki

Ang mga argument ng isang run ay hanggang 32 MB pagkatapos ma-encode. Halimbawa, ang isang 100-qubit na circuit na may depth na 100 ay nag-e-encode sa humigit-kumulang 39 KB, kaya ang isang run ay kayang kumuha ng batch ng humigit-kumulang 800 ganoong circuit. Para sa mas malalaking input, mag-upload ng file at ipasa ang pangalan nito bilang argument.

I-save ang mga resulta

Gamitin ang save_result() sa dulo ng workflow mo para magbalik ng resulta sa notebook mo. Basahin ang resulta sa notebook mo gamit ang job.result():

run_workflow_remotely.ipynb

result = job.result()

Para magawa ito, tawagin ang save_result() sa code ng workflow mo:

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

Ine-encode ng save_result() ang resulta sa parehong paraan ng pag-encode ng client sa mga argument, at dine-decode ito ng job.result(). Kaya ang resulta ay puwedeng maglaman ng mga suportadong uri ng argument, gaya ng mga circuit, NumPy array, at resulta ng primitive job, na may parehong pagbabago sa type.

• Suriin ang return value. Kung hindi ma-encode ng save_result() ang value, nagla-log ito ng babala at nagbabalik ng False sa halip na magtaas ng error. Kapag walang pagsusuri, puwedeng matapos ang job na may status na DONE at walang resulta.

• Ang huling save_result() lang ang iniimbak. Pinapalitan ng bawat tawag ang naka-save na resulta. Para magbalik ng maraming value, i-save ang mga ito sa iisang dictionary, o isulat ang mga ito sa mga log.

• Ang walang lamang dictionary ay nangangahulugang walang resulta. Kung hindi kailanman tinawag ng workflow ang save_result(), nagbabalik ang job.result() ng {}.

Para magbalik ng mga file, gaya ng malalaking array o plot, i-save ang mga ito sa file storage at ibalik ang mga pangalan nito sa resulta.

Best practice: i-validate ang mga argument gamit ang schema

Bilang best practice, maglakip ng JSON Schema sa bawat workflow na tumatanggap ng mga argument. Inilalarawan ng schema ang mga argument na tinatanggap ng workflow, at sinusuri ng workflow ang mga argument ng bawat run laban dito bago gumawa ng job. Kung hindi tumutugma ang mga argument, agad na pumapalya ang run() na may error na pinangangalanan ang maling field, at hindi gumagawa ng job ang workflow. Kapag walang schema, makararating ang maling mga argument sa workflow pagkatapos magsimula ang job, at binabalewala ng workflow ang maling baybay na pangalan ng argument.

Itakda ang schema gamit ang arguments_schema kapag ina-upload mo ang workflow. Magpasa ng dictionary, hindi JSON string:

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

Tandaan ang mga sumusunod na punto kapag sumusulat ka ng schema:

• Ilarawan ang encoded na anyo ng mga Qiskit at NumPy object. Sinusuri ng schema ang mga argument ayon sa pagpapadala ng client, kaya ang circuit ay isang object gaya ng {"__type__": "QuantumCircuit", "__value__": "<base64-encoded QPY>"}, hindi string o array. Suriin ang __type__ tag, at ituring ang __value__ bilang opaque na string. Tinatanggihan ng schema na naglalarawan sa circuit bilang string ang bawat wastong run.

• Itakda ang "additionalProperties": false. Kapag wala ang setting na ito, binabalewala ng workflow ang maling baybay na pangalan ng argument, gaya ng shotz, nang walang babala, at tumatakbo ito gamit ang default na value. Ideklara ang bawat argument na tinatanggap ng workflow bago mo i-enable ang setting na ito.

• Markahan ang mga argument bilang required. Idagdag sa required ang bawat argument na binabasa ng workflow nang walang default na value.

Kung hindi tumutugma ang mga argument sa schema, pinangangalanan ng mensahe ng error ang rule at ang lokasyon ng maling value:

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

Sinusuri ng schema ang type, hugis, at saklaw ng bawat argument. Hindi masusuri ng schema kung nagbabanggaan ang dalawang wastong argument, o kung kasya ang circuit sa isang backend. Panatilihin ang mga pagsusuring iyon sa code ng workflow.

I-update o alisin ang schema

• Para palitan ang schema, magtakda ng bagong arguments_schema at i-upload muli ang workflow.

• Para alisin ang schema, i-upload ang workflow na may arguments_schema={}.

• Kung ia-upload mo ang workflow nang walang arguments_schema, pinananatili ng workflow ang naka-imbak na schema.

Para makita ang schema na may bisa, basahin ang my_workflow.arguments_schema. Ang value na None ay nangangahulugang walang schema ang workflow.

Suriin ang mga argument bago ka magpatakbo

Tawagin ang validate_arguments() para suriin ang isang set ng mga argument laban sa schema nang hindi nagsisimula ng job:

run_workflow_remotely.ipynb

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

Kung hindi wasto ang mga argument, nagtataas ang validate_arguments() ng QiskitServerlessException na may parehong mensahe na ibinabalik ng run() para sa mga argument na iyon. Kung walang schema ang workflow, wasto ang anumang argument. Hindi ginagarantiya ng wastong resulta na magtatagumpay ang run(), dahil sinusuri rin ng run() ang iba pang limitasyon, gaya ng bilang ng mga aktibong job.

Mga rule ng schema

Tinatanggihan ng managed workflow ang upload kung nilalabag ng schema ang alinman sa mga sumusunod na rule:

• Ang schema ay puwedeng hanggang 64 KiB, na may hanggang 64 na antas ng nesting at hanggang 200 subschema.

• Dapat tumuro sa loob ng parehong schema ang mga reference, gaya ng #/$defs/circuit, at dapat ma-resolve ang bawat reference. Hindi pinapayagan ang mga reference sa mga URL o file.

• Dapat object o boolean ang schema.

Iwasan din ang mga sumusunod na problema, na hindi nahuhuli ng upload:

• Nested na quantifier sa pattern. Ang pattern na gaya ng ^(a+)+$ ay puwedeng tumagal nang napakatagal bago ma-evaluate. Humihinto ang workflow sa pag-validate pagkatapos ng limitasyon sa CPU time at tinatanggihan ang run. Sumulat ng mga pattern na walang quantifier sa paligid ng grupong may laman nang quantifier, gaya ng ^ibm_[a-z0-9_]{1,40}$.

• Ang false bilang schema. Tinatanggihan ng schema na false ang bawat run. Para tanggalin ang validation, gamitin ang {}.

I-troubleshoot ang schema

Problema	Sanhi
Tinatanggihan ang bawat run sa isang circuit argument.	Inilalarawan ng schema ang circuit bilang string o array. Ilarawan ito bilang object na may __type__ tag.
Tinatanggihan ang mga wastong run.	Ang additionalProperties ay false, at hindi idineklara ng schema ang isang argument na ipinapasa ng run. Pinangangalanan ng path ng error ang argument.
Hindi tinatanggihan ang mga di-wastong run.	Walang schema ang workflow. Suriin ang my_workflow.arguments_schema.
Walang run na sinusuri, kahit nagtakda ka ng schema.	Ipinasa ang schema bilang JSON string. Magpasa ng dictionary.
Pumapalya ang upload na may 400 error.	Nilalabag ng schema ang isa sa mga rule ng schema.
Sinasabi ng error na masyadong maraming CPU time ang kinuha ng validation.	May nested na quantifier ang isang pattern. Isulat muli ang pattern.