本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 混合任務的主要概念
<a name="braket-jobs-concepts"></a>

本節說明 Amazon Braket Python SDK 所提供`AwsQuantumJob.create`函數的主要概念，以及與容器檔案結構的映射。

除了構成完整演算法指令碼的檔案之外，您的混合任務還可以有額外的輸入和輸出。當您的混合任務開始時，AmazonRaket 會將作為混合任務建立一部分而提供的輸入複製到執行演算法指令碼的容器中。當混合任務完成時，演算法期間定義的所有輸出都會複製到指定的 Amazon S3 位置。

**注意**  
 *演算法指標*會即時回報，且不遵循此輸出程序。

Amazon Braket 也提供數個環境變數和協助程式函數，以簡化與容器輸入和輸出的互動。如需詳細資訊，請參閱 [Amazon Braket SDK 中的 braket.jobs 套件](https://amazon-braket-sdk-python.readthedocs.io/en/latest/_apidoc/braket.jobs.html)。 *Amazon Braket * 

**Topics**
+ [輸入](#braket-jobs-inputs)
+ [輸出](#braket-jobs-outputs)
+ [環境變數](#braket-jobs-environmental-variables)
+ [協助程式函數](#braket-jobs-helper-functions)

## 輸入
<a name="braket-jobs-inputs"></a>

 **輸入資料**：使用 `input_data`引數指定設定為字典的輸入資料檔案，即可將輸入資料提供給混合式演算法。使用者在 SDK 的 `AwsQuantumJob.create`函數中定義`input_data`引數。這會將輸入資料複製到環境變數 提供的位置的容器檔案系統`"AMZN_BRAKET_INPUT_DIR"`。如需如何在混合式演算法中使用輸入資料的幾個範例，請參閱 [Amazon Braket 混合式任務中的 QAOA，以及 Amazon Braket 混合式任務 Jupyter 筆記本中的 PennyLane](https://github.com/amazon-braket/amazon-braket-examples/blob/main/examples/hybrid_jobs/2_Using_PennyLane_with_Braket_Hybrid_Jobs/Using_PennyLane_with_Braket_Hybrid_Jobs.ipynb) 和 Quantum 機器學習。 [ Amazon Braket ](https://github.com/amazon-braket/amazon-braket-examples/blob/main/examples/hybrid_jobs/1_Quantum_machine_learning_in_Amazon_Braket_Hybrid_Jobs/Quantum_machine_learning_in_Amazon_Braket_Hybrid_Jobs.ipynb) 

**注意**  
當輸入資料很大 (>1GB) 時，提交混合任務之前會有很長的等待時間。這是因為本機輸入資料會先上傳至 S3 儲存貯體，然後將 S3 路徑新增至混合式任務請求，最後將混合式任務請求提交至 Braket 服務。

 **超參數**：如果您傳入 `hyperparameters`，它們可在環境變數 下使用`"AMZN_BRAKET_HP_FILE"`。

**注意**  
如需如何建立超參數和輸入資料，然後將此資訊傳遞至混合式任務指令碼的詳細資訊，請參閱[使用超參數](braket-jobs-hyperparameters.md)區段和此 github [頁面](https://github.com/amazon-braket/amazon-braket-examples/blob/main/examples/hybrid_jobs/1_Quantum_machine_learning_in_Amazon_Braket_Hybrid_Jobs/qcbm/qcbm.py)。

 **檢查點**：若要指定您想要在新混合任務中使用的`job-arn`檢查點，請使用 `copy_checkpoints_from_job`命令。此命令會透過檢查點資料複製到新混合任務`checkpoint_configs3Uri`的 ，使其可在任務執行`AMZN_BRAKET_CHECKPOINT_DIR`時環境變數指定的路徑中使用。預設值為 `None`，表示來自另一個混合任務的檢查點資料不會用於新的混合任務。

## 輸出
<a name="braket-jobs-outputs"></a>

 **Quantum 任務**：Quantum 任務結果存放在 S3 位置 `s3://amazon-braket-<region>-<accountID>/jobs/<job-name>/tasks`。

 **任務結果**：您的演算法指令碼儲存至環境變數所提供目錄的所有內容`"AMZN_BRAKET_JOB_RESULTS_DIR"`都會複製到 中指定的 S3 位置`output_data_config`。如果未指定值，則預設為 `s3://amazon-braket-<region>-<accountID>/jobs/<job-name>/<timestamp>/data`。我們提供 SDK 協助程式函數 ** `save_job_result` **，當您從演算法指令碼呼叫 時，您可以使用它以字典的形式方便地存放結果。

 **檢查點**：如果您想要使用檢查點，您可以將它們儲存在環境變數 提供的目錄中`"AMZN_BRAKET_CHECKPOINT_DIR"`。您也可以`save_job_checkpoint`改用 SDK 協助程式函數。

 **演算法指標**：您可以將演算法指標定義為演算法指令碼的一部分，該指令碼會在混合任務執行時即時傳送到 Amazon CloudWatch，並在 Amazon Braket 主控台中顯示。如需如何使用演算法指標的範例，請參閱[使用 Amazon Braket 混合任務來執行 QAOA 演算法](braket-jobs-run-qaoa-algorithm.md)。

如需儲存任務輸出的詳細資訊，請參閱混合任務文件中的[儲存結果](https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-first.html#braket-jobs-save-results)。

## 環境變數
<a name="braket-jobs-environmental-variables"></a>

Amazon Braket 提供數個環境變數，以簡化與容器輸入和輸出的互動。以下程式碼列出 Braket 使用的環境變數。
+ `AMZN_BRAKET_INPUT_DIR` – 輸入資料目錄 opt/braket/input/data。
+ `AMZN_BRAKET_JOB_RESULTS_DIR` – 要寫入任務結果的輸出目錄 opt/braket/model。
+ `AMZN_BRAKET_JOB_NAME` – 任務的名稱。
+ `AMZN_BRAKET_CHECKPOINT_DIR` – 檢查點目錄。
+ `AMZN_BRAKET_HP_FILE` – 包含超參數的檔案。
+ `AMZN_BRAKET_DEVICE_ARN` – 裝置 ARN (AWS 資源名稱）。
+ `AMZN_BRAKET_OUT_S3_BUCKET` – 輸出 Amazon S3 儲存貯體，如`CreateJob`請求的 中所指定`OutputDataConfig`。
+ `AMZN_BRAKET_SCRIPT_ENTRY_POINT` – `CreateJob`請求的 中指定的進入點`ScriptModeConfig`。
+ `AMZN_BRAKET_SCRIPT_COMPRESSION_TYPE` – `CreateJob`請求的 中指定的壓縮類型`ScriptModeConfig`。
+ `AMZN_BRAKET_SCRIPT_S3_URI` – 使用者指令碼的 Amazon S3 位置，如`CreateJob`請求的 中所指定`ScriptModeConfig`。
+ `AMZN_BRAKET_TASK_RESULTS_S3_URI` – SDK 預設會存放任務量子任務結果的 Amazon S3 位置。
+ `AMZN_BRAKET_JOB_RESULTS_S3_PATH` – 存放任務結果的 Amazon S3 位置，如`CreateJob`請求的 中所指定`OutputDataConfig`。
+ `AMZN_BRAKET_JOB_TOKEN` – 對於任務容器中建立的量子任務，應該傳遞至 `CreateQuantumTask`的 `jobToken` 參數的字串。

## 協助程式函數
<a name="braket-jobs-helper-functions"></a>

Amazon Braket 提供多種協助程式函數，可簡化與容器輸入和輸出的互動。這些協助程式函數會從用來執行混合任務的演算法指令碼中呼叫。下列範例示範如何使用它們。

```
from braket.jobs import get_checkpoint_dir, get_hyperparameters, get_input_data_dir, get_job_device_arn, get_job_name, get_results_dir, save_job_result, save_job_checkpoint, load_job_checkpoint

get_checkpoint_dir() # Get the checkpoint directory
get_hyperparameters() # Get the hyperparameters as strings
get_input_data_dir() # Get the input data directory
get_job_device_arn() # Get the device specified by the hybrid job
get_job_name() # Get the name of the hybrid job.
get_results_dir() # Get the path to a results directory
save_job_result(result_data='data') # Save hybrid job results
save_job_checkpoint(checkpoint_data={'key': 'value'}) # Save a checkpoint
load_job_checkpoint() # Load a previously saved checkpoint
```