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

# 在邊緣裝置上設定 Neo
<a name="neo-getting-started-edge"></a>

這份開始使用 Amazon SageMaker Neo 的指南說明如何編譯模型、設定裝置以及在裝置上進行推論。大多數程式碼範例使用 Boto3。我們提供 AWS CLI 適用的 命令，以及有關如何滿足 Neo 先決條件的指示。

**注意**  
您可以在本機機器、SageMaker 筆記本內、Amazon SageMaker Studio 中，或在邊緣裝置上執行下列程式碼片段 (視您的邊緣裝置而定)。設定步驟類似；不過，如果您在 SageMaker 筆記本執行個體或 SageMaker Studio 工作階段中執行本指南，則有兩個主要例外狀況：  
您不需要安裝 Boto3。
您不需要新增 `‘AmazonSageMakerFullAccess’` IAM 政策

 本指南假設您正在邊緣裝置上執行下列指示。

# 先決條件
<a name="neo-getting-started-edge-step0"></a>

SageMaker Neo 是一項功能，讓您只要訓練機器學習模型一次，就能在雲端和邊緣的任何位置執行該模型。您必須先設定幾個先決條件，才能使用 Neo 編譯和最佳化模型。您必須安裝必要的 Python 程式庫、設定您的 AWS 登入資料、建立具有必要許可的 IAM 角色，以及設定用於儲存模型成品的 S3 儲存貯體。您還必須準備好經過訓練的機器學習模型。該精靈會引導您完成設定：

1. **安裝 Boto3**

   如果您要在邊緣裝置上執行這些命令，則必須安裝 適用於 Python (Boto3) 的 AWS SDK。在 Python 環境 (最好是虛擬環境) 中，在邊緣裝置的終端或 Jupyter 筆記本執行個體中本機執行以下操作：

------
#### [ Terminal ]

   ```
   pip install boto3
   ```

------
#### [ Jupyter Notebook ]

   ```
   !pip install boto3
   ```

------

1.  **設定 AWS 登入資料** 

   您必須在裝置上設定 Amazon Web Services 憑證，以執行 SDK for Python (Boto3)。根據預設， AWS 登入資料應存放在邊緣裝置上的 `~/.aws/credentials`檔案中。在憑證檔案中，您應該會看到兩個環境變數：`aws_access_key_id` 和 `aws_secret_access_key`。

   在您的終端機中執行：

   ```
   $ more ~/.aws/credentials
   
   [default]
   aws_access_key_id = YOUR_ACCESS_KEY
   aws_secret_access_key = YOUR_SECRET_KEY
   ```

   [AWS 一般參考指南](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)提供有關如何獲得必要 `aws_access_key_id` 和 `aws_secret_access_key` 的指示。如需如何在裝置上設定憑證的詳細資訊，請參閱 [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration) 文件。

1.  **設定 IAM 角色並連接政策。**

   Neo 需要存取您的 S3 儲存貯體 URI。建立 IAM 角色以執行 SageMaker AI 且該 IAM 角色具有存取 S3 URI 的許可。您可以使用適用於 Python 的 SDK (Boto3)、主控台或 AWS CLI來建立 IAM 角色。下列範例使用了 SDK for Python (Boto3) 來說明如何建立 IAM 角色：

   ```
   import boto3
   
   AWS_REGION = 'aws-region'
   
   # Create an IAM client to interact with IAM
   iam_client = boto3.client('iam', region_name=AWS_REGION)
   role_name = 'role-name'
   ```

   如需如何使用主控台 AWS CLI或透過 AWS API 建立 IAM 角色的詳細資訊，請參閱[在 AWS 帳戶中建立 IAM 使用者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_api)。

    建立說明您要連接的 IAM 政策之字典。此政策用於建立新的 IAM 角色。

   ```
   policy = {
       'Statement': [
           {
               'Action': 'sts:AssumeRole',
               'Effect': 'Allow',
               'Principal': {'Service': 'sagemaker.amazonaws.com'},
           }],  
        'Version': '2012-10-17		 	 	 '
   }
   ```

   使用您上方定義的政策建立新的 IAM 角色：

   ```
   import json 
   
   new_role = iam_client.create_role(
       AssumeRolePolicyDocument=json.dumps(policy),
       Path='/',
       RoleName=role_name
   )
   ```

   在稍後的步驟中建立編譯任務時，您需要知道您的 Amazon Resource Name (ARN) 是什麼，因此也將其儲存在變數中。

   ```
   role_arn = new_role['Role']['Arn']
   ```

    現在您已經建立新角色，請連接與 Amazon SageMaker AI 和 Amazon S3 互動所需的許可：

   ```
   iam_client.attach_role_policy(
       RoleName=role_name,
       PolicyArn='arn:aws:iam::aws:policy/AmazonSageMakerFullAccess'
   )
   
   iam_client.attach_role_policy(
       RoleName=role_name,
       PolicyArn='arn:aws:iam::aws:policy/AmazonS3FullAccess'
   );
   ```

1. **建立 Amazon S3 儲存貯體以儲存您的模型成品**

   SageMaker Neo 將從 Amazon S3 存取您的模型成品

------
#### [ Boto3 ]

   ```
   # Create an S3 client
   s3_client = boto3.client('s3', region_name=AWS_REGION)
   
   # Name buckets
   bucket='name-of-your-bucket'
   
   # Check if bucket exists
   if boto3.resource('s3').Bucket(bucket) not in boto3.resource('s3').buckets.all():
       s3_client.create_bucket(
           Bucket=bucket,
           CreateBucketConfiguration={
               'LocationConstraint': AWS_REGION
           }
       )
   else:
       print(f'Bucket {bucket} already exists. No action needed.')
   ```

------
#### [ CLI ]

   ```
   aws s3 mb s3://'name-of-your-bucket' --region specify-your-region 
   
   # Check your bucket exists
   aws s3 ls s3://'name-of-your-bucket'/
   ```

------

1. **訓練機器學習模型**

   如需有關如何使用 Amazon SageMaker AI 訓練機器學習模型的詳細資訊，請參閱[使用 Amazon SageMaker AI 訓練模型](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html)。您可以選擇性地將本機訓練的模型直接上傳到 Amazon S3 URI 儲存貯體。
**注意**  
 取決於您使用的架構，請確保模型格式正確。參閱 [SageMaker Neo 應有哪些輸入資料形狀？](https://docs.aws.amazon.com/sagemaker/latest/dg/neo-job-compilation.html#neo-job-compilation-expected-inputs) 

   如果您還沒有模型，請使用 `curl` 命令從 TensorFlow 的網站取得 `coco_ssd_mobilenet` 模型的本機複本。您剛複製的模型是源自 [COCO 資料集](https://cocodataset.org/#home)訓練的物件偵測模型。在 Jupyter 筆記本中輸入以下內容：

   ```
   model_zip_filename = './coco_ssd_mobilenet_v1_1.0.zip'
   !curl http://storage.googleapis.com/download.tensorflow.org/models/tflite/coco_ssd_mobilenet_v1_1.0_quant_2018_06_29.zip \
       --output {model_zip_filename}
   ```

   請注意，此特定範例以 .zip 檔案封裝。解壓縮此檔案並將其重新封裝為壓縮的 tarfile (`.tar.gz`)，然後再於稍後的步驟中使用它。在 Jupyter 筆記本中輸入以下內容：

   ```
   # Extract model from zip file
   !unzip -u {model_zip_filename}
   
   model_filename = 'detect.tflite'
   model_name = model_filename.split('.')[0]
   
   # Compress model into .tar.gz so SageMaker Neo can use it
   model_tar = model_name + '.tar.gz'
   !tar -czf {model_tar} {model_filename}
   ```

1. **將訓練過的模型上傳到 S3 儲存貯體**

   訓練完機器學習模式後，請將其儲存在 S3 儲存貯體中。

------
#### [ Boto3 ]

   ```
   # Upload model        
   s3_client.upload_file(Filename=model_filename, Bucket=bucket, Key=model_filename)
   ```

------
#### [ CLI ]

   將 `your-model-filename` 和 `amzn-s3-demo-bucket` 取代為您 Amazon S3 儲存貯體的名稱。

   ```
   aws s3 cp your-model-filename s3://amzn-s3-demo-bucket
   ```

------

# 編譯模型
<a name="neo-getting-started-edge-step1"></a>

一旦您滿足了[先決條件](https://docs.aws.amazon.com/sagemaker/latest/dg/neo-getting-started-edge.html#neo-getting-started-edge-step0)，就可以使用 Amazon SageMaker AI Neo 來編譯您的模型。您可以使用 AWS CLI、 主控台或 [Amazon Web Services SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) 編譯模型，請參閱[使用 Neo 編譯模型](https://docs.aws.amazon.com/sagemaker/latest/dg/neo-job-compilation.html)。在這個範例中，你會用 Boto3 編譯你的模型。

若要編譯模型，SageMaker Neo 需要下列資訊：

1.  **您儲存訓練模型的 Amazon S3 儲存貯體 URI。**

   如果您遵循先決條件，則儲存貯體的名稱會儲存在名為 `bucket` 的變數中。下列程式碼片段顯示如何使用 AWS CLI列出所有您的儲存貯體：

   ```
   aws s3 ls
   ```

   例如：

   ```
   $ aws s3 ls
   2020-11-02 17:08:50 bucket
   ```

1.  **您要在其中儲存編譯模型的 Amazon S3 儲存貯體 URI。**

   下列程式碼片段將您的 Amazon S3 儲存貯體 URI 與名為 `output` 的輸出目錄名稱串連一起：

   ```
   s3_output_location = f's3://{bucket}/output'
   ```

1.  **您用來訓練模型的機器學習架構。**

   定義您用來訓練模型的架構。

   ```
   framework = 'framework-name'
   ```

   例如，如果您想要編譯使用 TensorFlow 訓練的模型，您可以使用 `tflite` 或 `tensorflow`。如果您想要使用較少儲存記憶體的較輕量型 TensorFlow 版本，請使用 `tflite`。

   ```
   framework = 'tflite'
   ```

   有關 Neo 支援的架構之完整清單，請參閱[支援的架構、裝置、系統和架構](https://docs.aws.amazon.com/sagemaker/latest/dg/neo-supported-devices-edge.html)。

1.  **模型輸入的形狀。**

    Neo 需要輸入張量的名稱和形狀。名稱和形狀會以鍵值對的形式傳遞。`value` 是輸入張量的整數維度清單，`key` 是模型中輸入張量的確切名稱。

   ```
   data_shape = '{"name": [tensor-shape]}'
   ```

   例如：

   ```
   data_shape = '{"normalized_input_image_tensor":[1, 300, 300, 3]}'
   ```
**注意**  
取決於您使用的架構，請確保模型格式正確。參閱 [SageMaker Neo 應有哪些輸入資料形狀？](https://docs.aws.amazon.com/sagemaker/latest/dg/neo-job-compilation.html#neo-job-compilation-expected-inputs) 此字典中的金鑰必須變更為新的輸入張量名稱。

1.  **要編譯的目標裝置名稱或硬體平台的一般詳細資訊** 

   ```
   target_device = 'target-device-name'
   ```

   例如，如果您想要部署到 Raspberry Pi 3，請使用：

   ```
   target_device = 'rasp3b'
   ```

   您可以在[支援的架構、裝置、系統和架構](https://docs.aws.amazon.com/sagemaker/latest/dg/neo-supported-devices-edge.html)中找到系統支援的邊緣裝置完整清單。

 現在您已完成前面的步驟，可以將編譯任務提交給 Neo。

```
# Create a SageMaker client so you can submit a compilation job
sagemaker_client = boto3.client('sagemaker', region_name=AWS_REGION)

# Give your compilation job a name
compilation_job_name = 'getting-started-demo'
print(f'Compilation job for {compilation_job_name} started')

response = sagemaker_client.create_compilation_job(
    CompilationJobName=compilation_job_name,
    RoleArn=role_arn,
    InputConfig={
        'S3Uri': s3_input_location,
        'DataInputConfig': data_shape,
        'Framework': framework.upper()
    },
    OutputConfig={
        'S3OutputLocation': s3_output_location,
        'TargetDevice': target_device 
    },
    StoppingCondition={
        'MaxRuntimeInSeconds': 900
    }
)

# Optional - Poll every 30 sec to check completion status
import time

while True:
    response = sagemaker_client.describe_compilation_job(CompilationJobName=compilation_job_name)
    if response['CompilationJobStatus'] == 'COMPLETED':
        break
    elif response['CompilationJobStatus'] == 'FAILED':
        raise RuntimeError('Compilation failed')
    print('Compiling ...')
    time.sleep(30)
print('Done!')
```

如果您想要偵錯的其他資訊，請包含下列列印陳述式：

```
print(response)
```

如果編譯任務成功，編譯過的模型會儲存在先前指定的輸出 Amazon S3 儲存貯體中 (`s3_output_location`)。在本機下載已編譯的模型：

```
object_path = f'output/{model}-{target_device}.tar.gz'
neo_compiled_model = f'compiled-{model}.tar.gz'
s3_client.download_file(bucket, object_path, neo_compiled_model)
```

# 設定您的 裝置
<a name="neo-getting-started-edge-step2"></a>

您將需要在邊緣裝置上安裝套件，以便裝置進行推論。您還需要安裝 [AWS IoT Greengrass](https://docs.aws.amazon.com/greengrass/latest/developerguide/what-is-gg.html) 核心或[深度學習執行期 (DLR)](https://github.com/neo-ai/neo-ai-dlr)。在此範例中，您將安裝用於對 `coco_ssd_mobilenet` 物件偵測演算法進行推論所需的套件，並使用 DLR。

1. **安裝其他套件**

   除了 Boto3 之外，您還必須在邊緣裝置上安裝某些程式庫。您安裝的程式庫會依使用案例而定。

   例如，對於您之前下載的 `coco_ssd_mobilenet` 物件偵測演算法，您需要安裝 [NumPy](https://numpy.org/) 以進行資料處理和統計資料、[PIL](https://pillow.readthedocs.io/en/stable/) 來載入影像，以及安裝 [Matplotlib](https://matplotlib.org/) 來產生繪圖。如果您想評估使用 Neo 編譯與基準線的影響，還需要 TensorFlow 副本。

   ```
   !pip3 install numpy pillow tensorflow matplotlib 
   ```

1. **在您的裝置上安裝推論引擎**

   若要執行 Neo 編譯的模型，請在裝置上安裝[深度學習執行期 (DLR)](https://github.com/neo-ai/neo-ai-dlr)。DLR 是適用於深度學習模型和決策樹模型的常見緊湊執行期。在執行 Linux 的 x86\$164 CPU 目標上，您可以使用下列 `pip` 命令來安裝最新版本的 DLR 套件：

   ```
   !pip install dlr
   ```

   如需在 GPU 目標或非 x86 Edge 裝置上安裝 DLR，請參閱預先建置二進位的[版本](https://github.com/neo-ai/neo-ai-dlr/releases)，或參閱[安裝適用於從來源建置 DLR 的 DLR](https://neo-ai-dlr.readthedocs.io/en/latest/install.html)。例如，若要安裝適用於 Raspberry Pi 3 的 DLR，您可以使用：

   ```
   !pip install https://neo-ai-dlr-release.s3-us-west-2.amazonaws.com/v1.3.0/pi-armv7l-raspbian4.14.71-glibc2_24-libstdcpp3_4/dlr-1.3.0-py3-none-any.whl
   ```

# 在裝置上進行推論
<a name="neo-getting-started-edge-step3"></a>

在此範例中，您會使用 Boto3 將編譯任務的輸出下載到您的邊緣裝置上。接著，您將匯入 DLR，從資料集中下載範例圖像，調整此圖像的大小以符合模型的原始輸入，然後進行預測。

1. **將已編譯的模型從 Amazon S3 下載到您的裝置，並從壓縮過的 tarfile 中擷取該模型。**

   ```
   # Download compiled model locally to edge device
   object_path = f'output/{model_name}-{target_device}.tar.gz'
   neo_compiled_model = f'compiled-{model_name}.tar.gz'
   s3_client.download_file(bucket_name, object_path, neo_compiled_model)
   
   # Extract model from .tar.gz so DLR can use it
   !mkdir ./dlr_model # make a directory to store your model (optional)
   !tar -xzvf ./compiled-detect.tar.gz --directory ./dlr_model
   ```

1. **匯入 DLR 和初始化的 `DLRModel` 物件。**

   ```
   import dlr
   
   device = 'cpu'
   model = dlr.DLRModel('./dlr_model', device)
   ```

1. **下載用於推論的圖像，並根據模型的訓練方式對其進行格式化**。

   舉 `coco_ssd_mobilenet` 為例，您可以從 [COCO 資料集](https://cocodataset.org/#home)下載圖像，然後將圖像改造為 `300x300`：

   ```
   from PIL import Image
   
   # Download an image for model to make a prediction
   input_image_filename = './input_image.jpg'
   !curl https://farm9.staticflickr.com/8325/8077197378_79efb4805e_z.jpg --output {input_image_filename}
   
   # Format image so model can make predictions
   resized_image = image.resize((300, 300))
   
   # Model is quantized, so convert the image to uint8
   x = np.array(resized_image).astype('uint8')
   ```

1. **使用 DLR 進行推論**。

   最後，您可以使用 DLR 對剛下載的圖像進行預測：

   ```
   out = model.run(x)
   ```

有關使用 DLR 從邊緣裝置上的 Neo 編譯模型進行推論的更多範例，請參閱新 [neo-ai-dlr GitHub 儲存器](https://github.com/neo-ai/neo-ai-dlr)。