從本機 Python 程式碼建立混合任務安裝其他 Python 套件和原始程式碼將資料儲存並載入至混合式任務執行個體混合式任務裝飾器的最佳實務

將本機程式碼作為混合式任務執行

Amazon Braket Hybrid Jobs 提供混合量子傳統演算法的完整受管協調，將 Amazon EC2運算資源與 Amazon Braket Quantum Processing Unit （QPU）存取相結合。在混合式任務中建立的量子任務優先佇列超過個別量子任務，因此不會因為量子任務佇列中的波動而中斷演算法。每個會QPU維護個別的混合式任務佇列，確保在任何指定時間只能執行一個混合式任務。

在本節中：

從本機 Python 程式碼建立混合任務
安裝其他 Python 套件和原始程式碼
將資料儲存並載入至混合式任務執行個體
混合式任務裝飾器的最佳實務

從本機 Python 程式碼建立混合任務

您可以將本機 Python 程式碼作為 Amazon Braket Hybrid 任務執行。您可以用@hybrid_job裝飾器註釋程式碼來做到這一點，如下列程式碼範例所示。對於自訂環境，您可以選擇使用來自 Amazon Elastic Container Registry （）的自訂容器ECR。

注意

預設僅支援 Python 3.10。

您可以使用@hybrid_job裝飾器來註釋函數。Braket 會將裝飾器內的程式碼轉換為 Braket 混合式任務演算法指令碼。然後，混合任務會在 Amazon EC2執行個體的裝飾器內叫用函數。您可以使用 job.state()或 Braket 主控台監控任務的進度。下列程式碼範例示範如何在上執行 5 個狀態的序列 State Vector Simulator (SV1) device.


from braket.aws import AwsDevice
from braket.circuits import Circuit, FreeParameter, Observable
from braket.devices import Devices
from braket.jobs.hybrid_job import hybrid_job
from braket.jobs.metrics import log_metric

device_arn = Devices.Amazon.SV1


@hybrid_job(device=device_arn)  # choose priority device
def run_hybrid_job(num_tasks=1):
    device = AwsDevice(device_arn)  # declare AwsDevice within the hybrid job

    # create a parametric circuit
    circ = Circuit()
    circ.rx(0, FreeParameter("theta"))
    circ.cnot(0, 1)
    circ.expectation(observable=Observable.X(), target=0)

    theta = 0.0  # initial parameter

    for i in range(num_tasks):
        task = device.run(circ, shots=100, inputs={"theta": theta})  # input parameters
        exp_val = task.result().values[0]

        theta += exp_val  # modify the parameter (possibly gradient descent)

        log_metric(metric_name="exp_val", value=exp_val, iteration_number=i)

    return {"final_theta": theta, "final_exp_val": exp_val}

您可以像一般 Python 函數一樣叫用函數來建立混合式任務。不過，裝飾器函數會傳回混合式任務處理，而不是函數的結果。若要在結果完成後擷取結果，請使用 job.result()。


job = run_hybrid_job(num_tasks=1)
result = job.result()

@hybrid_job 裝飾器中的裝置引數會指定混合任務具有優先存取權的裝置，在此情況下，SV1 模擬器。若要取得QPU優先順序，您必須確保函數ARN中使用的裝置符合裝飾器中指定的裝置。為了方便起見，您可以使用協助程式函數get_job_device_arn()來擷取中ARN宣告的裝置@hybrid_job。

注意

每個混合式任務至少都有一分鐘的啟動時間，因為它會在 Amazon 上建立容器化環境EC2。因此，對於非常短的工作負載，例如單一電路或一批電路，它可能就足以讓您使用量子任務。

超參數

run_hybrid_job() 函數會取得引數num_tasks來控制建立的量子任務數目。混合任務會自動將此擷取為超參數。

注意

超參數在 Braket 主控台中顯示為字串，限制為 2500 個字元。

指標和記錄

在run_hybrid_job()函數中，來自迭代演算法的指標會以記錄log_metrics。指標會自動繪製在混合式任務索引標籤下的 Braket 主控台頁面中。您可以使用指標，在混合式任務執行期間，使用 Braket 成本追蹤器近乎即時地追蹤量子任務成本。上述範例使用指標名稱「機率」，記錄結果類型的第一個機率。

擷取結果

混合任務完成後，您可以使用 job.result() 來擷取混合任務結果。傳回陳述式中的任何物件都會由 Braket 自動擷取。請注意，函數傳回的物件必須是可序列化每個元素的組合。例如，下列程式碼顯示運作中和失敗的範例。


@hybrid_job(device=Devices.Amazon.SV1)
def passing():
    np_array = np.random.rand(5)
    return np_array  # serializable
    
@hybrid_job(device=Devices.Amazon.SV1)
def failing():
    return MyObject() # not serializable

任務名稱

根據預設，此混合任務的名稱會從函數名稱推斷。您也可以指定最長 50 個字元的自訂名稱。例如，在以下程式碼中，任務名稱為 "my-job-name"。


@hybrid_job(device=Devices.Amazon.SV1, job_name="my-job-name")
def function():
    pass

本機模式

本機任務是透過將引數新增至裝飾器local=True來建立。這會在本機運算環境的容器化環境中執行混合作業，例如您的筆記型電腦。本機任務沒有量子任務的優先順序佇列。對於多節點或等進階案例MPI，本機任務可能會存取必要的 Braket 環境變數。下列程式碼會使用裝置作為SV1模擬器來建立本機混合工作。


@hybrid_job(device=Devices.Amazon.SV1, local=True)
def run_hybrid_job(num_tasks = 1):
    return ...

支援所有其他混合式任務選項。如需選項清單，請參閱 braket.jobs.quantum_job_creation 模組。

安裝其他 Python 套件和原始程式碼

您可以自訂執行期環境，以使用您偏好的 Python 套件。您可以使用requirements.txt檔案、套件名稱清單或自帶容器（BYOC）。若要使用 requirements.txt 檔案自訂執行期環境，請參閱下列程式碼範例。


@hybrid_job(device=Devices.Amazon.SV1, dependencies="requirements.txt")
def run_hybrid_job(num_tasks = 1):
    return ...

例如， requirements.txt 檔案可能包含其他要安裝的套件。


qiskit 
pennylane >= 0.31
mitiq == 0.29

或者，您可以提供套件名稱作為 Python 清單，如下所示。


@hybrid_job(device=Devices.Amazon.SV1, dependencies=["qiskit", "pennylane>=0.31", "mitiq==0.29"])
def run_hybrid_job(num_tasks = 1):
    return ...

其他原始程式碼可以指定為模組清單，也可以指定單一模組，如下列程式碼範例所示。


@hybrid_job(device=Devices.Amazon.SV1, include_modules=["my_module1", "my_module2"])
def run_hybrid_job(num_tasks = 1):
    return ...

將資料儲存並載入至混合式任務執行個體

指定輸入訓練資料

當您建立混合式工作時，您可以指定 Amazon Simple Storage Service （Amazon S3）儲存貯體來提供輸入訓練資料集。您也可以指定本機路徑，然後 Braket 會自動將資料上傳至 s3://<default_bucket_name>/jobs/<job_name>/<timestamp>/data/<channel_name> Amazon S3。如果您指定本機路徑，則頻道名稱預設為「輸入」。下列程式碼顯示來自本機路徑的 numpy 檔案data/file.npy。


@hybrid_job(device=Devices.Amazon.SV1, input_data="data/file.npy")
def run_hybrid_job(num_tasks = 1):
    data = np.load("data/file.npy")
    return ...

對於 S3，您必須使用 get_input_data_dir() Helper funciton。


s3_path = "s3://amazon-braket-us-west-1-961591465522/job-data/file.npy"

@hybrid_job(device=None, input_data=s3_path)
def job_s3_input():
    np.load(get_input_data_dir() + "/file.npy")
    
@hybrid_job(device=None, input_data={"channel": s3_path})
def job_s3_input_channel():
    np.load(get_input_data_dir("channel") + "/file.npy")

您可以透過提供通道值和 S3 URIs或本機路徑的字典來指定多個輸入資料來源。


input_data = {
    "input": "data/file.npy",
    "input_2": "s3://amzn-s3-demo-bucket/data.json"
} 


@hybrid_job(device=None, input_data=input_data)
def multiple_input_job():
    np.load(get_input_data_dir("input") + "/file.npy")
    np.load(get_input_data_dir("input_2") + "/data.json")

注意

當輸入資料很大（>1GB）時，在建立任務之前會有很長的等待時間。這是由於本機輸入資料第一次上傳至 S3 儲存貯體時，S3 路徑會新增至任務請求。最後，任務請求會提交至 Braket 服務。

將結果儲存至 S3

若要儲存裝飾函數的傳回陳述式中未包含的結果，您必須將正確的目錄附加至所有檔案寫入操作。下列範例顯示儲存 numpy 陣列和 matplotlib 圖形。


@hybrid_job(device=Devices.Amazon.SV1)
def run_hybrid_job(num_tasks = 1):
    result = np.random.rand(5)
    
    # save a numpy array
    np.save("result.npy", result)
    
    # save a matplotlib figure
    plt.plot(result)
    plt.savefig("fig.png")
    return ...

所有結果都會壓縮為名為的檔案model.tar.gz。您可以使用 Python job.result() 函數下載結果，或從 Braket 管理主控台的混合式任務頁面導覽至結果資料夾。

從檢查點儲存和繼續

對於長時間執行的混合任務，建議定期儲存演算法的中繼狀態。您可以使用內建save_job_checkpoint()協助程式函數，或將檔案儲存至AMZN_BRAKET_JOB_RESULTS_DIR路徑。較新版本可在協助程式函數上使用get_job_results_dir()。

以下是使用混合式任務裝飾程式儲存和載入檢查點的最小工作範例：


from braket.jobs import save_job_checkpoint, load_job_checkpoint, hybrid_job

@hybrid_job(device=None, wait_until_complete=True)
def function():
    save_job_checkpoint({"a": 1})

job = function()
job_name = job.name
job_arn = job.arn

@hybrid_job(device=None, wait_until_complete=True, copy_checkpoints_from_job=job_arn)
def continued_function():
    load_job_checkpoint(job_name)

continued_job = continued_function()

在第一個混合任務中， save_job_checkpoint() 會使用包含要儲存資料的字典來呼叫。根據預設，每個值都必須可序列化為文字。若要檢查更複雜的 Python 物件，例如 numpy 陣列，您可以設定 data_format = PersistedJobDataFormat.PICKLED_V4。此程式碼會在名為「檢查點」的子資料夾下，建立並覆寫混合任務成品<jobname>.json中預設名稱的檢查點檔案。

若要建立新的混合任務，以便從檢查點繼續，我們需要傳遞前一個任務ARN的混合任務copy_checkpoints_from_job=job_arn，其中 job_arn 是混合任務。然後，我們使用 load_job_checkpoint(job_name)從檢查點載入。

混合式任務裝飾器的最佳實務

接受非同步性

使用裝飾器註釋建立的混合式任務是非同步的 - 它們會在傳統和量子資源可用時執行。您可以使用監控演算法的進度 Braket Management Console 或 Amazon CloudWatch。當您提交演算法以執行時，Raket 會在可擴展的容器化環境中執行演算法，並在演算法完成時擷取結果。

執行迭代變化演算法

混合任務為您提供執行反覆量子-傳統演算法的工具。對於純量子問題，請使用量子任務或一批量子任務。對某些的優先存取對於需要對進行多次迭代呼叫，且兩者之間QPUs進行傳統處理的長期變動演算法QPUs最有利。

使用本機模式進行偵錯

在上執行混合式任務之前QPU，建議您先在模擬器上執行SV1，以確認其如預期般執行。對於小規模測試，您可以使用本機模式執行，以進行快速迭代和偵錯。

使用自備容器（BYOC）改善可複製性

在容器化環境中封裝您的軟體及其相依性，以建立可重複的實驗。透過將所有程式碼、相依性和設定封裝到容器中，您可以防止潛在的衝突和版本控制問題。

多執行個體分散式模擬器

若要執行大量電路，請考慮使用內建MPI支援，在單一混合任務中的多個執行個體上執行本機模擬器。如需詳細資訊，請參閱內嵌模擬器。

使用參數電路

您從混合任務提交的參數電路會在某些上自動編譯，QPUs使用參數編譯來改善演算法的執行時間。

定期檢查點

對於長時間執行的混合任務，建議定期儲存演算法的中繼狀態。

如需更多範例、使用案例和最佳實務，請參閱 Amazon Braket 範例 GitHub。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

（進階）使用 Amazon Braket Hybrid 任務

使用 Amazon Braket 混合任務執行混合任務