AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

ML 反馈 连接器

ML 反馈 连接器使您可以更轻松地访问机器学习 (ML) 模型数据以进行模型重新训练和分析。该连接器:

  • 将您的 ML 模型使用的输入数据(样本)上传到 Amazon S3。模型输入可以是任何格式,如图像、JSON 或音频。在将样本上传到云后,您可以使用它们来重新训练模型,以提高其预测的准确性和精确性。例如,您可以使用 Amazon SageMaker Ground Truth 来标记您的样本,并使用 Amazon SageMaker 来重新培训模型。

  • 从模型将预测结果发布为 MQTT 消息。这可让您实时监控和分析模型的推理质量。您也可以存储预测结果,然后使用它们来分析随时间推移的趋势。

  • 将有关样本上传和样本数据的指标发布到 Amazon CloudWatch。

要配置此连接器,您以 JSON 格式描述支持的反馈配置。反馈配置定义诸如目标 Amazon S3 存储桶、内容类型和采样策略之类的属性。(采样策略用于确定要上传哪些样本。)

您可以在以下情况下使用 ML 反馈 连接器:

  • 与 SQL 用户定义的 Lambda 函数结合使用。您的本地推理 Lambda 函数使用 AWS IoT Greengrass机器学习 SDK 调用此连接器并传入目标反馈配置、模型输入和模型输出(预测结果)。有关示例,请参阅示例用法

  • ML 映像分类 连接器 (v2) 结合使用。要将此连接器与 ML 映像分类 连接器一起使用,请配置 ML 映像分类 连接器的 MLFeedbackConnectorConfigId 参数。

  • ML 对象检测连接器结合使用。要将此连接器与 ML 对象检测连接器一起使用,请配置 ML 对象检测连接器的 MLFeedbackConnectorConfigId 参数。

ARNarn:aws:greengrass:区域::/connectors/MLFeedback/versions/1

要求

此连接器具有以下要求:

  • AWS IoT Greengrass 核心软件 v1.9.3。

  • Python 版本 3.7 已安装在核心设备上并且已添加到 PATH 环境变量。

  • 一个或多个 Amazon S3 存储桶。您使用的存储桶数量取决于您的采样策略。

  • 添加到 Greengrass 组角色的 IAM 策略,该策略允许对目标 Amazon S3 存储桶中的对象执行 s3:PutObject 操作,如以下示例所示。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:PutObject", "Resource": [ "arn:aws:s3:::bucket-name/*" ] } ] }

    该策略应包括所有目标存储桶作为资源。您可以授予对资源的具体或条件访问权限(例如,通过使用通配符*命名方案)。有关更多信息,请参阅IAM 用户指南中的添加和删除 IAM 策略

  • 添加到 Greengrass 组且已配置的 CloudWatch 指标 连接器。仅当您要使用指标报告功能时才需要它。

  • 与此连接器进行交互时需要 AWS IoT Greengrass机器学习 SDK v1.1.0。

参数

FeedbackConfigurationMap

此连接器可用于将样本上传到 Amazon S3 的一组一个或多个反馈配置。反馈配置定义诸如目标存储桶、内容类型和采样策略之类的参数。调用此连接器时,调用 Lambda 函数或连接器将指定目标反馈配置。

在控制台中显示名称:反馈配置映射

必需: true

类型:一个格式正确的 JSON 字符串,用于定义支持的反馈配置集。有关示例,请参阅FeedbackConfigurationMap 示例

反馈配置对象的 ID 具有以下要求。

该 ID:

  • 在配置对象间必须唯一。

  • 必须以字母或数字开头。可以包含大小写字母、数字和连字符。

  • 长度必须介于 2 - 63 个字符之间。

必需: true

类型:string

有效模式: ^[a-zA-Z0-9][a-zA-Z0-9-]{1,62}$

示例:MyConfig0config-a12id

 

反馈配置对象的主体包含以下属性。

s3-bucket-name

目标 Amazon S3 存储桶的名称。

注意

组角色必须允许对所有目标存储桶执行 s3:PutObject 操作。有关更多信息,请参阅 要求

必需: true

类型:string

有效模式: ^[a-z0-9\.\-]{3,63}$

content-type

要上传的样本的内容类型。单个反馈配置的所有内容必须属于同一类型。

必需: true

类型: string

示例:image/jpegapplication/jsonaudio/ogg

s3-prefix

用于上传的样本的键前缀。前缀类似于目录名称。它使您能够在存储桶的同一目录下存储相似的数据。有关更多信息,请参阅 Amazon Simple Storage Service 开发人员指南 中的对象键和元数据

必需: false

类型:string

file-ext

要用于上传的样本的文件扩展名。必须是内容类型的有效文件扩展名。

必需: false

类型: string

示例:jpgjsonogg

sampling-strategy

用于过滤要上传的样本的采样策略。如果省略,连接器尝试上传它收到的所有样本。

必需: false

类型:一个格式正确的 JSON 字符串,其中包含以下属性。

strategy-name

采样策略的名称。

必需: true

类型: string

有效值:RANDOM_SAMPLINGLEAST_CONFIDENCEMARGINENTROPY

rate

随机采样策略的速率。

必需:如果 strategy-nameRANDOM_SAMPLING,则为 true

类型: number

有效值: 0.0 - 1.0

threshold

最小置信度裕度采样策略的阈值。

必需:如果 strategy-nameLEAST_CONFIDENCEMARGINENTROPY,则为 true

类型: number

有效值:

  • 对于 LEAST_CONFIDENCEMARGIN 策略,为 0.0 - 1.0

  • 对于 ENTROPY 策略,为 0.0 - no limit

RequestLimit

连接器一次可以处理的最大请求数。

您可以使用此参数,通过限制连接器同时处理的请求数来限制内存消耗。超过此限制的请求将被忽略。

在控制台中显示名称:请求限制

必需: false

类型:string

有效值: 0 - 999

有效模式: ^$|^[0-9]{1,3}$

创建连接器示例 (CLI)

以下 CLI 命令创建一个 ConnectorDefinition,其初始版本包含 ML 反馈 连接器。

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyMLFeedbackConnector", "ConnectorArn": "arn:aws:greengrass:区域::/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

输入数据

用户定义的 Lambda 函数使用 AWS IoT Greengrass机器学习 SDK 中的 feedback 客户端的 publish 函数来调用连接器。有关示例,请参阅示例用法

注意

该连接器不接受 MQTT 消息作为输入数据。

publish 函数采用下列参数:

ConfigId

目标反馈配置的 ID。这必须与在 ML 反馈 连接器的 FeedbackConfigurationMap 参数中定义的反馈配置的 ID 匹配。

必需:true

类型:字符串

ModelInput

传递给模型以进行推理的输入数据。除非根据采样策略将此输入数据过滤掉,否则将使用目标配置上传此数据。

必需:true

类型:字节

ModelPrediction

来自模型的预测结果。结果类型可以是词典或列表。例如,来自 ML 映像分类 连接器的预测结果是概率列表(例如 [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/metric/put 主题上的 CloudWatch 的指标。

您必须配置订阅以允许连接器就 MQTT 主题进行通信。有关更多信息,请参阅 输入和输出

主题筛选条件: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" }

连接器将 bucketkey 字段添加到来自 Amazon S3 的响应中。有关 Amazon S3 响应的更多信息,请参阅 Amazon Simple Storage Service API Reference 中的 PUT 对象

示例输出:由于采样策略而丢弃的样本示例
{ "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 连接器配置为订阅该主题,并将信息发送给 AWS IoT Analytics 以进行进一步分析或历史分析。

主题筛选条件:cloudwatch/metric/put

这是用于将指标发布到 CloudWatch 的输出主题。此功能要求您安装并配置 CloudWatch 指标 连接器

指标包括:

  • 上传的样本的数量。

  • 上传的样本的大小。

  • 上传到 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机器学习 SDK 将数据发送到 ML 反馈 连接器。

注意

您可以从 AWS IoT Greengrass 下载页面下载 AWS IoT Greengrass机器学习 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 反馈 连接器包含以下第三方软件/许可:

此连接器按照 Greengrass 核心软件许可协议发布。

另请参阅