终止支持通知：2026 年 10 月 7 日， Amazon 将停止对的支持。 Amazon IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 Amazon IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 Amazon IoT Greengrass Version 1](https://docs.amazonaws.cn/greengrass/v2/developerguide/migrate-from-v1.html)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # ML 反馈连接器 **警告** 此连接器已进入*生命周期延长阶段*， Amazon IoT Greengrass 不会发布更新来提供功能、现有功能增强、安全补丁或错误修复。有关更多信息，请参阅 [Amazon IoT Greengrass Version 1 维护政策](maintenance-policy.md)。 ML 反馈连接器使您可以更轻松地访问机器学习 (ML) 模型数据以进行模型重新训练和分析。该连接器： + 将您的 ML 模型使用的输入数据（样本）上传到 Amazon S3。模型输入可以是任何格式，如图像、JSON 或音频。在将样本上传到云后，您可以使用它们来重新训练模型，以提高其预测的准确性和精确性。例如，你可以使用 [SageMaker AI Ground Trut](https://docs.amazonaws.cn/sagemaker/latest/dg/sms.html) h 来标记你的样本，使用 [SageMaker AI](https://docs.amazonaws.cn/sagemaker/latest/dg/whatis.html) 来重新训练模型。 + 从模型将预测结果发布为 MQTT 消息。这可让您实时监控和分析模型的推理质量。您也可以存储预测结果，然后使用它们来分析随时间推移的趋势。 + 向 Amazon CloudWatch 发布有关示例上传和示例数据的指标。 要配置此连接器，您以 JSON 格式描述支持的*反馈配置*。反馈配置定义诸如目标 Amazon S3 存储桶、内容类型和[采样策略](#ml-feedback-connector-sampling-strategies)之类的属性。（采样策略用于确定要上传哪些样本。） 您可以在以下情况下使用 ML 反馈连接器： + 用户定义的 Lambda 函数。您的本地推理 Lambda 函数使用 Amazon IoT Greengrass Machine Learning SDK 调用此连接器并传入目标反馈配置、模型输入和模型输出（预测结果）。有关示例，请参阅[用法示例](#ml-feedback-connector-usage)。 + 使用 [ML 图像分类连接器](image-classification-connector.md) (v2)。要将此连接器与 ML 图像分类连接器一起使用，请配置 ML 图像分类连接器的 `MLFeedbackConnectorConfigId` 参数。 + 使用 [ML 对象检测连接器](obj-detection-connector.md)。要将此连接器与 ML 对象检测连接器一起使用，请配置 ML 对象检测连接器的 `MLFeedbackConnectorConfigId` 参数。 **ARN**：`arn:aws:greengrass:{{region}}::/connectors/MLFeedback/versions/1` ## 要求 此连接器具有以下要求： + Amazon IoT Greengrass 核心软件 v1.9.3 或更高版本。 + [Python](https://www.python.org/) 版本 3.7 或 3.8 已安装在核心设备上，并已添加到 PATH 环境变量中。 **注意** 要使用 Python 3.8，请运行以下命令来创建从默认 Python 3.7 安装文件夹到已安装的 Python 3.8 二进制文件的符号链接。 ``` sudo ln -s {{path-to-python-3.8}}/python3.8 /usr/bin/python3.7 ``` 这会将设备配置为满足 Amazon IoT Greengrass的 Python 要求。 + 一个或多个 Amazon S3 桶。您使用的存储桶数量取决于您的采样策略。 + [Greengrass 组角色](group-role.md)，配置为允许对目标 Amazon S3 存储桶中的对象执行 `s3:PutObject` 操作，如以下示例 IAM policy 所示。 ------ #### [ 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 指标连接器](cloudwatch-metrics-connector.md)已添加到 Greengrass 组中并进行了配置。仅当您要使用指标报告功能时才需要它。 + Amazon IoT Greengrass 需要使用 M@@ [achine Learning SDK](lambda-functions.md#lambda-sdks-ml) v1.1.0 才能与此连接器进行交互。 ## 参数 `FeedbackConfigurationMap` 此连接器可用于将样本上传到 Amazon S3 的一组一个或多个反馈配置。反馈配置定义诸如目标存储桶、内容类型和[采样策略](#ml-feedback-connector-sampling-strategies)之类的参数。调用此连接器时，调用 Lambda 函数或连接器将指定目标反馈配置。 Amazon 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.amazonaws.cn/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)采样策略的速率。 如果 `strategy-name` 为 `RANDOM_SAMPLING`，则 `true` 是必需的。 类型：`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)采样策略的阈值。 如果 `strategy-name` 为 `LEAST_CONFIDENCE`、`MARGIN` 或 `ENTROPY`，则 `true` 是必需的。 类型：`number` 有效值： + 对于 `LEAST_CONFIDENCE` 或 `MARGIN` 策略，为 `0.0 - 1.0`。 + 对于 `ENTROPY` 策略，为 `0.0 - no limit`。 `RequestLimit` 连接器一次可以处理的最大请求数。 您可以使用此参数，通过限制连接器同时处理的请求数来限制内存消耗。超过此限制的请求将被忽略。 Amazon IoT 控制台中的显示名称：**请求限制** 必需：`false` 类型：`string` 有效值：`0 - 999` 有效模式：`^$|^[0-9]{1,3}$` ### 创建连接器示例 (Amazon CLI) 以下 CLI 命令创建一个 `ConnectorDefinition`，其初始版本包含 ML 反馈连接器。 ``` 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`) 结果： 使用此样本，因为裕度 (`.01`) <= 阈值 (`.02`)。 `ENTROPY` 上传其熵大于提供的阈值的样本。使用模型预测的标准化熵。 示例方案： 阈值：`0.75` 模型预测：`[.5, .25, .25]` 预测的熵：`1.03972` 结果： 使用此样本，因为熵 `1.03972`> 阈值`0.75`。 ## 输入数据 User-defined Lambda `publish` 函数使用 Machine Learning SDK 中`feedback`客户端的函数来调用连接 Amazon IoT Greengrass 器。有关示例，请参阅[用法示例](#ml-feedback-connector-usage)。 **注意** 该连接器不接受 MQTT 消息作为输入数据。 `publish` 函数采用下列参数： ConfigId 目标反馈配置的 ID。这必须与 ML 反馈连接器的[FeedbackConfigurationMap](#ml-feedback-connector-param)参数中定义的反馈配置的 ID 相匹配。 所需：是 类型：字符串 ModelInput 传递给模型以进行推理的输入数据。除非根据采样策略将此输入数据过滤掉，否则将使用目标配置上传此数据。 所需：是 类型：字节 ModelPrediction 来自模型的预测结果。结果类型可以是词典或列表。例如，来自 ML 图像分类连接器的预测结果是概率列表（例如 `[0.25, 0.60, 0.15]`）。此数据发布到 `/feedback/message/prediction` 主题。 所需：是 类型：词典或 `float` 值的列表 元数据 Customer-defined，应用程序特定的元数据，该元数据附加到已上传的示例并发布到主题中。`/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.amazonaws.cn/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)配置为订阅此主题并将信息发送到以 Amazon IoT Analytics 进行进一步分析或历史分析。 **主题筛选条件**：`cloudwatch/metric/put` 这是用于将指标发布到 CloudWatch 的输出主题。此功能要求您安装和配置 M [CloudWatch etrics 连接器](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 函数，该函数使用 [Amazon IoT Greengrass 机器学习开发工具包](lambda-functions.md#lambda-sdks-ml)将数据发送到 ML 反馈连接器。 **注意** 你可以从下载[页面 Amazon IoT Greengrass 下载](what-is-gg.md#gg-ml-sdk-download) Mac Amazon IoT Greengrass hine 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 ``` ## 许可证 机器学习反馈连接器包括以下第三方 software/licensing： + [适用于 Python (Boto3) 的 Amazon SDK](https://pypi.org/project/boto3/)/Apache 许可证 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache 许可证 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF 许可证 + [docutils](https://pypi.org/project/docutils/)/BSD 许可证，GNU 通用公共许可证 (GPL)，Python 软件基金会许可证，公共领域 + [jmespath](https://pypi.org/project/jmespath/)/MIT 许可证 + [s3transfer](https://pypi.org/project/s3transfer/)/Apache 许可证 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT 许可证 + [six](https://github.com/benjaminp/six)/MIT 该连接器在 [Greengrass Core 软件许可协议](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)