支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # ML 回饋連接器 **警告** 此連接器已進入*延長的生命週期階段*，並且 AWS IoT Greengrass 不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。 ML Feedback 連接器可讓您更輕鬆地存取機器學習 (ML) 模型資料，以進行模型重新訓練和分析。連接器： + 將 ML 模型使用的輸入資料 （範例） 上傳至 Amazon S3。模型輸入可以採用任何格式，例如影像、JSON 或音訊。在範例上傳至雲端之後，您可以使用它們來重新訓練模型，以改善其預測的精確性和準確性。例如，您可以使用 [SageMaker AI Ground Truth](https://docs.aws.amazon.com/sagemaker/latest/dg/sms.html) 來標記範例，並使用 [SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/whatis.html) 來重新訓練模型。 + 以 MQTT 訊息形式發佈模型的預測結果。這可讓您即時監控和分析模型的推論品質。您也可以存放預測結果，並使用它們來分析隨時間變化的趨勢。 + 將範例上傳和範例資料的指標發佈至 Amazon CloudWatch。 若要設定此連接器，請以 JSON 格式描述支援的*意見回饋組態*。意見回饋組態會定義屬性，例如目的地 Amazon S3 儲存貯體、內容類型和[抽樣策略](#ml-feedback-connector-sampling-strategies)。(抽樣策略用來決定要上傳哪些範例。) 您可以在下列案例中使用 ML Feedback 連接器： + 使用使用者定義的 Lambda 函數。您的本機推論 Lambda 函數使用 AWS IoT Greengrass Machine Learning SDK 來叫用此連接器，並傳入目標意見回饋組態、模型輸入和模型輸出 （預測結果）。如需範例，請參閱 [用量範例](#ml-feedback-connector-usage)。 + 使用 [ML Image Classification 連接器](image-classification-connector.md) (v2)。若要搭配 ML Image Classification 連接器使用此連接器，請設定 ML Image Classification 連接器的 `MLFeedbackConnectorConfigId` 參數。 + 使用 [ML 物件偵測連接器](obj-detection-connector.md)。若要搭配 ML 物件偵測連接器使用此連接器，請設定 ML 物件偵測連接器的 `MLFeedbackConnectorConfigId` 參數。 **ARN**：`arn:aws:greengrass:{{region}}::/connectors/MLFeedback/versions/1` ## 要求 此連接器有下列要求： + AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 或 3.8 版。 **注意** 若要使用 Python 3.8，請執行下列命令，以建立從預設 Python 3.7 安裝資料夾到已安裝 Python 3.8 二進位檔的符號連結。 ``` sudo ln -s {{path-to-python-3.8}}/python3.8 /usr/bin/python3.7 ``` 這會設定您的裝置以符合 AWS IoT Greengrass的 Python 需求。 + 一或多個 Amazon S3 儲存貯體。您使用的儲存貯體數量取決於您的取樣策略。 + [Greengrass 群組角色](group-role.md)設定為允許對目的地 Amazon S3 儲存貯體中的物件`s3:PutObject`執行動作，如下列範例 IAM 政策所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:PutObject", "Resource": [ "arn:aws:s3:::{{bucket-name}}/*" ] } ] } ``` ------ 政策應該包含所有目的地儲存貯體做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \* 命名配置)。 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 + 已將 [CloudWatch Metrics 連接器](cloudwatch-metrics-connector.md)新增至 Greengrass 群組並設定。只有在您想要使用指標報告功能時，才需要此項目。 + 需要[AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 1.1.0 版才能與此連接器互動。 ## Parameters `FeedbackConfigurationMap` 連接器可用來將範例上傳至 Amazon S3 的一組或多個意見回饋組態。意見回饋組態會定義目的地儲存貯體、內容類型和[抽樣策略](#ml-feedback-connector-sampling-strategies)之類的屬性。叫用此連接器時，呼叫 Lambda 函數或連接器會指定目標回饋組態。 AWS IoT 主控台中的顯示名稱：**意見回饋組態映射** 必要：`true` 類型：格式正確的 JSON 字串，定義一組支援的意見回饋組態。如需範例，請參閱 [FeedbackConfigurationMap 範例](#ml-feedback-connector-feedbackconfigmap)。 意見回饋組態物件的 ID 具有下列要求。 ID： + 在組態物件之間必須是唯一的。 + 開頭必須為字母或數字。可以包含大小寫字母、數字與連字號。 + 長度必須為 2 到 63 個字元。 必要：`true` 類型：`string` 有效模式： `^[a-zA-Z0-9][a-zA-Z0-9-]{1,62}$` 範例：`MyConfig0`、`config-a`、`12id` 意見回饋組態物件的內文包含下列屬性。 `s3-bucket-name` 目的地 Amazon S3 儲存貯體的名稱。 群組角色必須允許在所有目的地儲存貯體上執行 `s3:PutObject` 動作。如需詳細資訊，請參閱[要求](#ml-feedback-connector-req)。 必要：`true` 類型：`string` 有效模式： `^[a-z0-9\.\-]{3,63}$` `content-type` 要上傳之範例的內容類型。個別意見回饋組態的所有內容必須是相同類型。 必要：`true` 類型：`string` 範例：`image/jpeg`、`application/json`、`audio/ogg` `s3-prefix` 用於所上傳範例的金鑰前綴。前綴類似於目錄名稱。它可讓您將類似的資料存放在儲存貯體的相同目錄下。如需詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 必要：`false` 類型：`string` `file-ext` 用於所上傳範例的副檔名。必須是內容類型的有效副檔名。 必要：`false` 類型：`string` 範例：`jpg`、`json`、`ogg` `sampling-strategy` 用來篩選要上傳之範例的[抽樣策略](#ml-feedback-connector-sampling-strategies)。如果省略，連接器會嘗試上傳它收到的所有範例。 必要：`false` 類型：格式正確的 JSON 字串，其中包含下列屬性。 `strategy-name` 抽樣策略的名稱。 必要：`true` 類型：`string` 有效值：`RANDOM_SAMPLING`、`LEAST_CONFIDENCE`、`MARGIN` 或 `ENTROPY` `rate` [隨機](#ml-feedback-connector-sampling-strategies-random)取樣策略的速率。 必要：`true`如果 `strategy-name`為 `RANDOM_SAMPLING`。 類型：`number` 有效值：`0.0 - 1.0` `threshold` [最低可信度](#ml-feedback-connector-sampling-strategies-least-confidence)、[邊界](#ml-feedback-connector-sampling-strategies-margin)或[熵](#ml-feedback-connector-sampling-strategies-entropy)取樣策略的閾值。 必要：`true`如果 `strategy-name`是 `LEAST_CONFIDENCE`、 `MARGIN`或 `ENTROPY`。 類型：`number` 有效值： + `0.0 - 1.0`，適用於 `LEAST_CONFIDENCE` 或 `MARGIN` 策略。 + `0.0 - no limit`，適用於 `ENTROPY` 策略。 `RequestLimit` 連接器一次可處理的請求數量上限。 您可以使用此參數來限制連接器同時處理的要求數量，以限制記憶體消耗。超過此限制的請求會被忽略。 在 AWS IoT 主控台中顯示名稱：**請求限制** 必要：`false` 類型：`string` 有效值：`0 - 999` 有效模式： `^$|^[0-9]{1,3}$` ### 建立範例連接器 (AWS CLI) 下列 CLI 命令會使用包含 ML Feedback 連接器的初始版本`ConnectorDefinition`來建立 。 ``` aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyMLFeedbackConnector", "ConnectorArn": "arn:aws:greengrass:{{region}}::/connectors/MLFeedback/versions/1", "Parameters": { "FeedbackConfigurationMap": "{ \"RandomSamplingConfiguration\": { \"s3-bucket-name\": \"my-aws-bucket-random-sampling\", \"content-type\": \"image/png\", \"file-ext\": \"png\", \"sampling-strategy\": { \"strategy-name\": \"RANDOM_SAMPLING\", \"rate\": 0.5 } }, \"LeastConfidenceConfiguration\": { \"s3-bucket-name\": \"my-aws-bucket-least-confidence-sampling\", \"content-type\": \"image/png\", \"file-ext\": \"png\", \"sampling-strategy\": { \"strategy-name\": \"LEAST_CONFIDENCE\", \"threshold\": 0.4 } } }", "RequestLimit": "10" } } ] }' ``` ### FeedbackConfigurationMap 範例 以下是 `FeedbackConfigurationMap` 參數的擴展範例值。此範例包含數個使用不同取樣策略的意見回饋組態。 ``` { "ConfigID1": { "s3-bucket-name": "my-aws-bucket-random-sampling", "content-type": "image/png", "file-ext": "png", "sampling-strategy": { "strategy-name": "RANDOM_SAMPLING", "rate": 0.5 } }, "ConfigID2": { "s3-bucket-name": "my-aws-bucket-margin-sampling", "content-type": "image/png", "file-ext": "png", "sampling-strategy": { "strategy-name": "MARGIN", "threshold": 0.4 } }, "ConfigID3": { "s3-bucket-name": "my-aws-bucket-least-confidence-sampling", "content-type": "image/png", "file-ext": "png", "sampling-strategy": { "strategy-name": "LEAST_CONFIDENCE", "threshold": 0.4 } }, "ConfigID4": { "s3-bucket-name": "my-aws-bucket-entropy-sampling", "content-type": "image/png", "file-ext": "png", "sampling-strategy": { "strategy-name": "ENTROPY", "threshold": 2 } }, "ConfigID5": { "s3-bucket-name": "my-aws-bucket-no-sampling", "s3-prefix": "DeviceA", "content-type": "application/json" } } ``` ### 抽樣策略 連接器支援四種抽樣策略，這些抽樣策略會決定是否要上傳已傳遞至連接器的範例。範例是模型用於預測的離散資料執行個體。您可以使用取樣策略來篩選出最有可能提高模型準確性的範例。 `RANDOM_SAMPLING` 根據提供的速率隨機上傳範例。如果隨機產生的值小於此速率，它會上傳範例。速率越高，上傳的範例越多。 此策略會忽略任何提供的模型預測。 `LEAST_CONFIDENCE` 上傳其最大可信度機率低於所提供閾值的範例。 範例案例： 閾值：`.6` 模型預測：`[.2, .2, .4, .2]` 最大可信度機率：`.4` 結果： 使用範例，因為最大可信度機率 (`.4`) <= 閾值 (`.6`)。 `MARGIN` 如果前兩個可信度機率之間的邊界落在所提供閾值內，則上傳範例。邊界是前兩個機率之間的差異。 範例案例： 閾值：`.02` 模型預測：`[.3, .35, .34, .01]` 前兩個可信度機率：`[.35, .34]` 邊界：`.01` (`.35 - .34`) 結果： 使用範例，因為邊界1 (`.01`) <= 閾值 (`.02`)。 `ENTROPY` 上傳其熵大於所提供閾值的範例。使用模型預測的標準化熵。 範例案例： 閾值：`0.75` 模型預測：`[.5, .25, .25]` 預測的熵：`1.03972` 結果： 使用範例：因為熵 (`1.03972`) > 閾值 (`0.75`)。 ## 輸入資料 使用者定義的 Lambda 函數使用 AWS IoT Greengrass Machine Learning SDK 中的 `feedback`用戶端`publish`函數來叫用連接器。如需範例，請參閱 [用量範例](#ml-feedback-connector-usage)。 **注意** 此連接器不接受 MQTT 訊息做為輸入資料。 `publish` 函數採用下列引數： ConfigId 目標意見回饋組態的 ID。這必須符合 ML 意見回饋連接器的 [FeedbackConfigurationMap](#ml-feedback-connector-param) 參數中定義的意見回饋組態 ID。 必要： true 類型：字串 ModelInput 傳遞至模型以進行推論的輸入資料。除非根據取樣策略將此輸入資料篩選掉， 否則會使用目標組態來上傳此輸入資料。 必要： true 類型：位元組 ModelPrediction 來自模型的預測結果。結果類型可以是字典或清單。例如，ML Image Classification 連接器的預測結果是機率清單 （例如 `[0.25, 0.60, 0.15]`)。此資料會發佈至 `/feedback/message/prediction` 主題。 必要： true 類型：字典或`float`值清單 中繼資料 客戶定義的應用程式特定中繼資料，其會附加至上傳的範例並發佈至 `/feedback/message/prediction` 主題。連接器也會將具有時間戳記值的 `publish-ts` 金鑰插入至中繼資料。 必要：false 類型：字典 範例：`{"some-key": "some value"}` ## 輸出資料 此連接器會將資料發佈至三個 MQTT 主題： + 在 `feedback/message/status` 主題上來自連接器的狀態資訊。 + `feedback/message/prediction` 主題上的預測結果。 + 主題的 CloudWatch 指標`cloudwatch/metric/put`。 您必須設定訂閱，以允許連接器在 MQTT 主題上進行通訊。如需詳細資訊，請參閱[輸入和輸出](connectors.md#connectors-inputs-outputs)。 **主題篩選條件：** `feedback/message/status` 使用此主題來監控範例上傳和所捨棄範例的狀態。每次收到請求時，連接器就會發佈至此主題。 **範例輸出：範例上傳成功** ``` { "response": { "status": "success", "s3_response": { "ResponseMetadata": { "HostId": "IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km", "RetryAttempts": 1, "HTTPStatusCode": 200, "RequestId": "79104EXAMPLEB723", "HTTPHeaders": { "content-length": "0", "x-amz-id-2": "lbbqaDVFOhMlyU3gRvAX1ZIdg8P0WkGkCSSFsYFvSwLZk3j7QZhG5EXAMPLEdd4/pEXAMPLEUqU=", "server": "AmazonS3", "x-amz-expiration": "expiry-date=\"Wed, 17 Jul 2019 00:00:00 GMT\", rule-id=\"OGZjYWY3OTgtYWI2Zi00ZDllLWE4YmQtNzMyYzEXAMPLEoUw\"", "x-amz-request-id": "79104EXAMPLEB723", "etag": "\"b9c4f172e64458a5fd674EXAMPLE5628\"", "date": "Thu, 11 Jul 2019 00:12:50 GMT", "x-amz-server-side-encryption": "AES256" } }, "bucket": "greengrass-feedback-connector-data-us-west-2", "ETag": "\"b9c4f172e64458a5fd674EXAMPLE5628\"", "Expiration": "expiry-date=\"Wed, 17 Jul 2019 00:00:00 GMT\", rule-id=\"OGZjYWY3OTgtYWI2Zi00ZDllLWE4YmQtNzMyYzEXAMPLEoUw\"", "key": "s3-key-prefix/UUID.file_ext", "ServerSideEncryption": "AES256" } }, "id": "5aaa913f-97a3-48ac-5907-18cd96b89eeb" } ``` 連接器會將 `bucket`和 `key` 欄位新增至來自 Amazon S3 的回應。如需 Amazon S3 回應的詳細資訊，請參閱《*Amazon Simple Storage Service API 參考*》中的 [PUT 物件](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html#RESTObjectPUT-responses)。 **範例輸出：由於取樣策略而捨棄的範例** ``` { "response": { "status": "sample_dropped_by_strategy" }, "id": "4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3" } ``` **範例輸出：範例上傳失敗** 失敗狀態包含錯誤訊息做為 `error_message` 值，以及例外類別做為 `error` 值。 ``` { "response": { "status": "fail", "error_message": "[RequestId: 4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3] Failed to upload model input data due to exception. Model prediction will not be published. Exception type: NoSuchBucket, error: An error occurred (NoSuchBucket) when calling the PutObject operation: The specified bucket does not exist", "error": "NoSuchBucket" }, "id": "4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3" } ``` **範例輸出：由於請求限制而請求調節** ``` { "response": { "status": "fail", "error_message": "Request limit has been reached (max request: 10 ). Dropping request.", "error": "Queue.Full" }, "id": "4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3" } ``` **主題篩選條件：** `feedback/message/prediction` 使用此主題，根據上傳的範例資料接聽預測。這可讓您即時分析您的模型效能。只有當資料成功上傳至 Amazon S3 時，模型預測才會發佈至此主題。在此主題發佈的訊息採用 JSON 格式。它們包含所上傳資料物件的連結、模型的預測，以及請求中包含的中繼資料。 您也可以存放預測結果，並使用它們來報告和分析隨時間變化的趨勢。趨勢可提供寶貴的洞見。例如，*隨著時間準確度降低*趨勢可協助您決定是否需要重新訓練模型。 **範例輸出** ``` { "source-ref": "s3://greengrass-feedback-connector-data-us-west-2/s3-key-prefix/UUID.file_ext", "model-prediction": [ 0.5, 0.2, 0.2, 0.1 ], "config-id": "ConfigID2", "metadata": { "publish-ts": "2019-07-11 00:12:48.816752" } } ``` 您可以設定 [IoT Analytics 連接器](iot-analytics-connector.md)來訂閱此主題，並將資訊傳送至 AWS IoT Analytics 以進行進一步或歷史分析。 **主題篩選條件：** `cloudwatch/metric/put` 這是用來將指標發佈至 CloudWatch 的輸出主題。此功能需要您安裝和設定 [CloudWatch 指標連接器](cloudwatch-metrics-connector.md)。 指標包括： + 上傳的範例數量。 + 上傳的範例大小。 + 從上傳到 Amazon S3 的錯誤數目。 + 根據抽樣策略捨棄的範例數量。 + 已調節的請求數目。 **範例輸出：資料範例的大小 (在實際上傳之前發佈)** ``` { "request": { "namespace": "GreengrassFeedbackConnector", "metricData": { "value": 47592, "unit": "Bytes", "metricName": "SampleSize" } } } ``` **範例輸出：範例上傳成功** ``` { "request": { "namespace": "GreengrassFeedbackConnector", "metricData": { "value": 1, "unit": "Count", "metricName": "SampleUploadSuccess" } } } ``` **範例輸出：範例上傳成功，並發佈預測結果** ``` { "request": { "namespace": "GreengrassFeedbackConnector", "metricData": { "value": 1, "unit": "Count", "metricName": "SampleAndPredictionPublished" } } } ``` **範例輸出：範例上傳失敗** ``` { "request": { "namespace": "GreengrassFeedbackConnector", "metricData": { "value": 1, "unit": "Count", "metricName": "SampleUploadFailure" } } } ``` **範例輸出：由於取樣策略而捨棄的範例** ``` { "request": { "namespace": "GreengrassFeedbackConnector", "metricData": { "value": 1, "unit": "Count", "metricName": "SampleNotUsed" } } } ``` **範例輸出：由於請求限制而請求調節** ``` { "request": { "namespace": "GreengrassFeedbackConnector", "metricData": { "value": 1, "unit": "Count", "metricName": "ErrorRequestThrottled" } } } ``` ## 用量範例 下列範例是使用者定義的 Lambda 函數，使用 [AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 將資料傳送至 ML Feedback 連接器。 **注意** 您可以從 AWS IoT Greengrass [下載頁面](what-is-gg.md#gg-ml-sdk-download)下載 AWS IoT Greengrass Machine Learning SDK。 ``` import json import logging import os import sys import greengrass_machine_learning_sdk as ml client = ml.client('feedback') try: feedback_config_id = os.environ["FEEDBACK_CONFIG_ID"] model_input_data_dir = os.environ["MODEL_INPUT_DIR"] model_prediction_str = os.environ["MODEL_PREDICTIONS"] model_prediction = json.loads(model_prediction_str) except Exception as e: logging.info("Failed to open environment variables. Failed with exception:{}".format(e)) sys.exit(1) try: with open(os.path.join(model_input_data_dir, os.listdir(model_input_data_dir)[0]), 'rb') as f: content = f.read() except Exception as e: logging.info("Failed to open model input directory. Failed with exception:{}".format(e)) sys.exit(1) def invoke_feedback_connector(): logging.info("Invoking feedback connector.") try: client.publish( ConfigId=feedback_config_id, ModelInput=content, ModelPrediction=model_prediction ) except Exception as e: logging.info("Exception raised when invoking feedback connector:{}".format(e)) sys.exit(1) invoke_feedback_connector() def function_handler(event, context): return ``` ## 授權 ML 意見回饋連接器包含下列第三方軟體/授權： + [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache License 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License + [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域 + [jmespath](https://pypi.org/project/jmespath/)/MIT License + [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT License + [six](https://github.com/benjaminp/six)/MIT 此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。 ## 另請參閱 + [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md) + [Greengrass 連接器入門 (主控台)](connectors-console.md) + [Greengrass 連接器入門 (CLI)](connectors-cli.md)