本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 亚马逊 SageMaker 模型卡 **重要** Amazon SageMaker 模型卡已与 SageMaker 模型注册表集成。如果要在模型注册中心注册模型，可以使用集成来添加审核信息。有关更多信息，请参阅 [更新模型版本的详细信息](model-registry-details.md)。 使用 Amazon SageMaker 模型卡片在一个地方记录有关您的机器学习 (ML) 模型的关键细节，以简化管理和报告。模型卡可以帮助您在模型的整个生命周期中捕捉有关模型的关键信息，并实施负责任的人工智能实践。 编目详细信息，例如模型的预期用途和风险评级、训练详细信息和指标、评估结果和观测结果，以及额外的标注，例如注意事项、建议和自定义信息。通过创建模型卡，您可以执行以下操作： + 提供有关如何使用模型的指导。 + 通过详细描述模型训练和性能，为审计活动提供支持。 + 说明模型如何支持业务目标。 模型卡为记录哪些信息提供了规范性指导，并包含自定义信息字段。创建模型卡后，您可以将其导出为 PDF 或下载，以与相关的利益相关者共享。除批准状态更新外，对模型卡的任何编辑都会导致额外的模型卡版本，以便具有不可改变的模型更改记录。 **Topics** + [先决条件](#model-cards-prerequisites) + [模型的预期用途](#model-cards-intended-uses) + [风险评级](#model-cards-risk-rating) + [模型卡 JSON 架构](#model-cards-json-schema) + [创建模型卡](model-cards-create.md) + [模型卡操作](model-cards-manage.md) + [为 Amazon SageMaker 模型卡设置跨账户支持](model-cards-xaccount.md) + [模型卡牌 SageMaker APIs 的低等级](model-cards-apis.md) + [模型卡 FAQs](model-cards-faqs.md) ## 先决条件 要开始使用 Amazon SageMaker 模型卡，您必须拥有创建、编辑、查看和导出模型卡的权限。 ## 模型的预期用途 指定模型的预期用途有助于确保模型开发人员和用户获得负责任地训练或部署模型所需的信息。模型的预期用途应说明适合使用该模型的场景，以及不建议使用该模型的场景。 我们建议包括： + 模型的一般用途 + 模型适用的使用案例 + 模型不适用的使用案例 + 开发模型时做出的假设 模型的预期用途不仅限于技术细节，还描述了应如何在生产中使用模型、适合使用模型的场景以及其他注意事项，例如模型使用的数据类型或开发过程中做出的任何假设。 ## 风险评级 开发人员为具有不同风险级别的使用案例创建机器学习模型。例如，批准贷款申请的模型可能比检测电子邮件类别的模型风险更高。鉴于模型的风险状况各不相同，模型卡为您提供了一个对模型的风险评级进行分类的字段。 此风险评级可以是 `unknown`、`low`、`medium` 或 `high`。使用这些风险评级字段来标注未知、低、中或高风险模型，并帮助您的组织遵守有关将某些模型投入生产的任何现有规则。 ## 模型卡 JSON 架构 模型卡的评估详细信息必须以 JSON 格式提供。[如果您有由 Clarify 或 [SageMaker AI 模型监控器](https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor-model-quality.html)生成的 SageMaker JSON 格式评估报告，请将其上传到 Amazon S3 并提供 S3 URI 以自动解析评估指标。](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-run.html)有关更多信息和示例报告，请参阅 *Amazon SageMaker 模型治理——模型卡*示例笔记本中的示例[指标](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker_model_governance/example_metrics)文件夹。 使用 SageMaker Python SDK 创建模型卡片时，模型内容必须位于模型卡 JSON 架构中并以字符串形式提供。提供类似于以下示例的模型内容。 ### 模型卡 JSON 架构示例文件 ``` { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://json-schema.org/draft-07/schema#", "title": "SageMakerModelCardSchema", "description": "Internal model card schema for SageMakerRepositoryService without model_package_details", "version": "0.1.0", "type": "object", "additionalProperties": false, "properties": { "model_overview": { "description": "Overview about the model", "type": "object", "additionalProperties": false, "properties": { "model_description": { "description": "description of model", "type": "string", "maxLength": 1024 }, "model_creator": { "description": "Creator of model", "type": "string", "maxLength": 1024 }, "model_artifact": { "description": "Location of the model artifact", "type": "array", "maxContains": 15, "items": { "type": "string", "maxLength": 1024 } }, "algorithm_type": { "description": "Algorithm used to solve the problem", "type": "string", "maxLength": 1024 }, "problem_type": { "description": "Problem being solved with the model", "type": "string" }, "model_owner": { "description": "Owner of model", "type": "string", "maxLength": 1024 } } }, "intended_uses": { "description": "Intended usage of model", "type": "object", "additionalProperties": false, "properties": { "purpose_of_model": { "description": "Why the model was developed?", "type": "string", "maxLength": 2048 }, "intended_uses": { "description": "intended use cases", "type": "string", "maxLength": 2048 }, "factors_affecting_model_efficiency": { "type": "string", "maxLength": 2048 }, "risk_rating": { "description": "Risk rating for model card", "$ref": "#/definitions/risk_rating" }, "explanations_for_risk_rating": { "type": "string", "maxLength": 2048 } } }, "business_details": { "description": "Business details of model", "type": "object", "additionalProperties": false, "properties": { "business_problem": { "description": "What business problem does the model solve?", "type": "string", "maxLength": 2048 }, "business_stakeholders": { "description": "Business stakeholders", "type": "string", "maxLength": 2048 }, "line_of_business": { "type": "string", "maxLength": 2048 } } }, "training_details": { "description": "Overview about the training", "type": "object", "additionalProperties": false, "properties": { "objective_function": { "description": "the objective function the model will optimize for", "function": { "$ref": "#/definitions/objective_function" }, "notes": { "type": "string", "maxLength": 1024 } }, "training_observations": { "type": "string", "maxLength": 1024 }, "training_job_details": { "type": "object", "additionalProperties": false, "properties": { "training_arn": { "description": "SageMaker Training job arn", "type": "string", "maxLength": 1024 }, "training_datasets": { "description": "Location of the model datasets", "type": "array", "maxContains": 15, "items": { "type": "string", "maxLength": 1024 } }, "training_environment": { "type": "object", "additionalProperties": false, "properties": { "container_image": { "description": "SageMaker training image uri", "type": "array", "maxContains": 15, "items": { "type": "string", "maxLength": 1024 } } } }, "training_metrics": { "type": "array", "items": { "maxItems": 50, "$ref": "#/definitions/training_metric" } }, "user_provided_training_metrics": { "type": "array", "items": { "maxItems": 50, "$ref": "#/definitions/training_metric" } }, "hyper_parameters": { "type": "array", "items": { "maxItems": 100, "$ref": "#/definitions/training_hyper_parameter" } }, "user_provided_hyper_parameters": { "type": "array", "items": { "maxItems": 100, "$ref": "#/definitions/training_hyper_parameter" } } } } } }, "evaluation_details": { "type": "array", "default": [], "items": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,63}" }, "evaluation_observation": { "type": "string", "maxLength": 2096 }, "evaluation_job_arn": { "type": "string", "maxLength": 256 }, "datasets": { "type": "array", "items": { "type": "string", "maxLength": 1024 }, "maxItems": 10 }, "metadata": { "description": "additional attributes associated with the evaluation results", "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 } }, "metric_groups": { "type": "array", "default": [], "items": { "type": "object", "required": [ "name", "metric_data" ], "properties": { "name": { "type": "string", "pattern": ".{1,63}" }, "metric_data": { "type": "array", "items": { "anyOf": [ { "$ref": "#/definitions/simple_metric" }, { "$ref": "#/definitions/linear_graph_metric" }, { "$ref": "#/definitions/bar_chart_metric" }, { "$ref": "#/definitions/matrix_metric" } ] } } } } } } } }, "additional_information": { "additionalProperties": false, "type": "object", "properties": { "ethical_considerations": { "description": "Any ethical considerations that the author wants to provide", "type": "string", "maxLength": 2048 }, "caveats_and_recommendations": { "description": "Caveats and recommendations for people who might use this model in their applications.", "type": "string", "maxLength": 2048 }, "custom_details": { "type": "object", "additionalProperties": { "$ref": "#/definitions/custom_property" } } } } }, "definitions": { "source_algorithms": { "type": "array", "minContains": 1, "maxContains": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "algorithm_name" ], "properties": { "algorithm_name": { "description": "The name of an algorithm that was used to create the model package. The algorithm must be either an algorithm resource in your SageMaker account or an algorithm in AWS Marketplace that you are subscribed to.", "type": "string", "maxLength": 170 }, "model_data_url": { "description": "The Amazon S3 path where the model artifacts, which result from model training, are stored.", "type": "string", "maxLength": 1024 } } } }, "inference_specification": { "type": "object", "additionalProperties": false, "required": [ "containers" ], "properties": { "containers": { "description": "Contains inference related information which were used to create model package.", "type": "array", "minContains": 1, "maxContains": 15, "items": { "type": "object", "additionalProperties": false, "required": [ "image" ], "properties": { "model_data_url": { "description": "The Amazon S3 path where the model artifacts, which result from model training, are stored.", "type": "string", "maxLength": 1024 }, "image": { "description": "Inference environment path. The Amazon EC2 Container Registry (Amazon ECR) path where inference code is stored.", "type": "string", "maxLength": 255 }, "nearest_model_name": { "description": "The name of a pre-trained machine learning benchmarked by Amazon SageMaker Inference Recommender model that matches your model.", "type": "string" } } } } } }, "risk_rating": { "description": "Risk rating of model", "type": "string", "enum": [ "High", "Medium", "Low", "Unknown" ] }, "custom_property": { "description": "Additional property in section", "type": "string", "maxLength": 1024 }, "objective_function": { "description": "objective function that training job is optimized for", "additionalProperties": false, "properties": { "function": { "type": "string", "enum": [ "Maximize", "Minimize" ] }, "facet": { "type": "string", "maxLength": 63 }, "condition": { "type": "string", "maxLength": 63 } } }, "training_metric": { "description": "training metric data", "type": "object", "required": [ "name", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,255}" }, "notes": { "type": "string", "maxLength": 1024 }, "value": { "type": "number" } } }, "training_hyper_parameter": { "description": "training hyper parameter", "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,255}" }, "value": { "type": "string", "pattern": ".{0,255}" } } }, "linear_graph_metric": { "type": "object", "required": [ "name", "type", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,255}" }, "notes": { "type": "string", "maxLength": 1024 }, "type": { "type": "string", "enum": [ "linear_graph" ] }, "value": { "anyOf": [ { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "minItems": 1 } ] }, "x_axis_name": { "$ref": "#/definitions/axis_name_string" }, "y_axis_name": { "$ref": "#/definitions/axis_name_string" } } }, "bar_chart_metric": { "type": "object", "required": [ "name", "type", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,255}" }, "notes": { "type": "string", "maxLength": 1024 }, "type": { "type": "string", "enum": [ "bar_chart" ] }, "value": { "anyOf": [ { "type": "array", "items": { "type": "number" }, "minItems": 1 } ] }, "x_axis_name": { "$ref": "#/definitions/axis_name_array" }, "y_axis_name": { "$ref": "#/definitions/axis_name_string" } } }, "matrix_metric": { "type": "object", "required": [ "name", "type", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,255}" }, "notes": { "type": "string", "maxLength": 1024 }, "type": { "type": "string", "enum": [ "matrix" ] }, "value": { "anyOf": [ { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 1, "maxItems": 20 }, "minItems": 1, "maxItems": 20 } ] }, "x_axis_name": { "$ref": "#/definitions/axis_name_array" }, "y_axis_name": { "$ref": "#/definitions/axis_name_array" } } }, "simple_metric": { "description": "metric data", "type": "object", "required": [ "name", "type", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".{1,255}" }, "notes": { "type": "string", "maxLength": 1024 }, "type": { "type": "string", "enum": [ "number", "string", "boolean" ] }, "value": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 63 }, { "type": "boolean" } ] }, "x_axis_name": { "$ref": "#/definitions/axis_name_string" }, "y_axis_name": { "$ref": "#/definitions/axis_name_string" } } }, "axis_name_array": { "type": "array", "items": { "type": "string", "maxLength": 63 } }, "axis_name_string": { "type": "string", "maxLength": 63 } } } ``` # 创建模型卡 **重要** 允许 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 创建亚马逊 SageMaker资源的自定义 IAM 策略还必须授予向这些资源添加标签的权限。之所以需要为资源添加标签的权限，是因为 Studio 和 Studio Classic 会自动为创建的任何资源添加标签。如果 IAM 策略允许 Studio 和 Studio Classic 创建资源但不允许标记，则在尝试创建资源时可能会出现 AccessDenied “” 错误。有关更多信息，请参阅 [提供标记 A SageMaker I 资源的权限](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。 [AWS 亚马逊 A SageMaker I 的托管策略](security-iam-awsmanpol.md)授予创建 SageMaker 资源的权限已经包括在创建这些资源时添加标签的权限。 你可以使用 A SageMaker I 控制台或 SageMaker Python 软件开发工具包创建亚马逊 SageMaker 模型卡。还可以直接使用 API 操作。有关这些 API 操作的更多信息，请参阅[模型卡牌 SageMaker APIs 的低等级](model-cards-apis.md)。 ## 使用 SageMaker AI 控制台创建模型卡片 前往 Amazon SageMaker AI 控制台。在导航窗格的**治理**下，选择**模型卡**。在右上角，选择**创建模型卡**。 完成**创建模型卡**提示中的四个步骤，记录有关模型的详细信息。 ### 步骤 1：输入模型详细信息和预期用途 如果您的模型是一种 AWS 资源，请在此字段中指定确切的模型名称以自动填充模型详细信息。要浏览现有模型名称，请参阅 Amazon A SageMaker I 控制台中的**模型**。每个唯一的模型名称只能有一张关联的模型卡。 如果您的模型不是 AWS 资源，请为您的模型提供一个唯一的名称。要将模型添加为 AWS 资源，请参阅 *Amazon A SageMaker I 开发者指南*中的[创建模型](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-deployment.html#realtime-endpoints-deployment-create-model)。或者，您可以使用 [SageMaker AI Marketplace 或 SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-marketplace.html) 模型[注册表将您的模型添加为模型](https://docs.aws.amazon.com/sagemaker/latest/dg/model-registry.html)包。 有关预期用途的更多信息，请参阅[模型的预期用途](model-cards.md#model-cards-intended-uses)。有关风险评级的更多信息，请参阅[风险评级](model-cards.md#model-cards-risk-rating)。 #### 步骤 2：输入训练详细信息 将任何训练详细信息、训练观测值、数据集、超参数以及有关模型目标函数的详细信息添加到模型卡中。 模型卡中的目标函数可以是训练期间经过优化的任何函数。这可能包括但不限于成本函数、损失函数或目标指标。在本节中，记录对训练模型最重要的目标函数。 我们建议您对目标函数的以下属性进行编目： + 优化方向 + 指标 + 说明 例如，您可以尽可能减小（优化方向）二进制分类问题（描述）的交叉熵损失（指标），也可以尽可能提高逻辑回归的可能性。此外，您可以提供注释，说明为什么选择此目标函数而不是其他目标函数。 #### 步骤 3：输入评估详细信息 如果您有由 SageMaker Clarify 或 Model Monitor 生成的现有评估报告，请为这些报告提供 S3 URI，或者手动上传这些报告以将其添加到模型卡片中。 有关 Clarify 的 SageMaker 更多信息，请参阅[运行 Clar SageMaker ify 处理作业以进行偏见分析和可解释性](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-run.html)。 有关使用 Model Monitor 监控模型质量指标中偏差的更多信息，请参阅[监控模型质量](https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor-model-quality.html)。 要添加自己的评估报告，请选择**通用模型卡评估**。所有模型卡评估报告都必须采用[模型卡 JSON 架构](model-cards.md#model-cards-json-schema)。 #### 步骤 4：输入其他详细信息 添加自定义的模型卡详细信息字段，以便在模型卡上显示任何其他信息。例如，您可以添加值为*个人理财* 的自定义字段*业务线*。 #### 保存模型卡 查看模型卡中的信息后，选择右下角的**保存**以保存模型卡。 ## 使用 SageMaker Python 软件开发工具包创建模型卡片 创建模型卡之前，必须先定义模型卡的内容。使用 SageMaker Python SDK 时，模型内容包括模型概述、训练详情、预期用途、评估详情和其他信息。 可以为以下对象创建模型卡： + 托管在 SageMaker AI 中的模型 + 模型注册表中的模型包（ SageMaker 模型） + 在 SageMaker AI 之外托管或注册的模型 您也可以在不关联任何模型的情况下创建模型卡。 我们建议将您训练过的模型添加到 SageMaker 模型注册表中。模型注册表可帮助您对模型进行编目和跟踪模型版本。创建模型卡时，模型注册表中有关该模型的信息会自动填充到模型卡中。创建模型卡后，您可以对其进行编辑或向其添加信息。 有关使用模型注册表的信息，请参阅[利用模型注册中心进行模型注册部署](model-registry.md)。有关从模型注册表创建模型卡的信息，请参阅[在模型注册表中为您的模型创建 SageMaker 模型卡](#model-cards-sdk-create-model-registry)。 **注意** 要将模型卡与 SageMaker Python SDK 配合使用，您首先需要建立 A SageMaker I 会话。有关更多信息，请参阅 SageMaker Python SDK API 参考中的[会话](https://sagemaker.readthedocs.io/en/stable/api/utility/session.html)。 要为不在模型注册表中的模型创建 SageMaker 模型卡，请参阅[创建模型注册表中没有的模型](#model-card-sdk-create-model-non-model-registry)。 ### 创建模型注册表中没有的模型 使用以下几节中的信息为尚未添加到模型注册表的模型创建模型卡。 #### 步骤 1：定义模型概述 定义模型的概述。 ``` model_overview = ModelOverview.from_model_name( model_name=model_name, sagemaker_session=sagemaker_session, model_description="A-description-of-your-model", problem_type="Problem-type", # For example, "Binary Classification" algorithm_type="Algorithm-type", # For example, "Logistic Regression" model_creator="Name-of-model-creator", model_owner="Name-of-model-owner", ) ``` 如果您的模型是一种 AWS 资源，则可以自动检索模型 ARN、推理容器 URI 和模型工件的 S3 位置等概述信息。使用以下命令打印关联的 AWS 元数据： ``` print(model_overview.model_id) print(model_overview.inference_environment.container_image) print(model_overview.model_artifact) ``` #### 步骤 2：定义训练详细信息 要定义模型的训练详细信息，必须先定义其目标函数。 ``` objective_function = ObjectiveFunction( function=Function( function=ObjectiveFunctionEnum.MINIMIZE, facet=FacetEnum.LOSS, ), notes="An-explanation-about-objective-function", ) ``` 接下来，您可以使用现有的模型概述、会话和目标函数来定义训练详细信息。在此处添加任何训练观测值。 ``` training_details = TrainingDetails.from_model_overview( model_overview=model_overview, sagemaker_session=sagemaker_session, objective_function=objective_function, training_observations="Model-training-observations", ) ``` 同样，如果您的模型是一种 AWS 资源，则某些训练详细信息会自动填充。使用以下命令打印训练作业 ARN、训练容器 URI 和训练指标： ``` print(training_details.training_job_details.training_arn) print(training_details.training_job_details.training_environment.container_image) print([{"name": i.name, "value": i.value} for i in training_details.training_job_details.training_metrics]) ``` #### 定义评估详细信息 要定义模型的评估详细信息，必须先定义一个或多个指标组来描述用于任何评估作业的指标。 ``` my_metric_group = MetricGroup( name="binary classification metrics", metric_data=[Metric(name="accuracy", type=MetricTypeEnum.NUMBER, value=0.5)] ) ``` 接下来，您可以使用每项评估作业的评估指标和数据集来定义评估详细信息。在此处添加任何评估观测值，并为评估作业提供唯一名称。 ``` evaluation_details = [ EvaluationJob( name="Example-evaluation-job", evaluation_observation="Evaluation-observations", datasets=["s3://path/to/evaluation/data"], metric_groups=[my_metric_group], ) ] ``` 如果您有由 [SageMaker AI Clarify 或 A SageMaker I](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-run.html) [模型监控器](https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor-model-quality.html)生成的现有评估报告，请将其上传到 Amazon S3 并提供 S3 URI 以自动解析评估指标。要添加自己的通用模型卡评估报告，请提供采用[评估结果 JSON 格式](https://docs.aws.amazon.com/sagemaker/latest/dg/model-cards-json-schema.html)的报告。 ``` report_type = "clarify_bias.json" example_evaluation_job.add_metric_group_from_json( f"example_metrics/{report_type}", EvaluationMetricTypeEnum.CLARIFY_BIAS ) ``` #### 第 3 步：定义预期用途 定义模型的预期用途，包括模型的一般用途及其预期使用案例。此外，还建议将可能影响此模型在特定使用案例中功效的任何因素以及贵组织对该模型的风险评级包括在内。有关更多信息，请参阅[模型的预期用途](model-cards.md#model-cards-intended-uses)和[风险评级](model-cards.md#model-cards-risk-rating)。 ``` intended_uses = IntendedUses( purpose_of_model="Purpose-of-the-model", intended_uses="The-intended-uses-of-this-model", factors_affecting_model_efficiency="Any-factors-effecting-model-efficacy", risk_rating=RiskRatingEnum.LOW, explanations_for_risk_rating="Explanation-for-low-risk-rating", ) ``` #### 定义其他信息 最后，您可以向模型卡添加其他自定义信息。您可以记录有关模型的任何道德考虑、注意事项和建议。还可以以键值对的形式添加所需的任何自定义详细信息。 ``` additional_information = AdditionalInformation( ethical_considerations="Any-ethical-considerations", caveats_and_recommendations="Any-caveats-and-recommendations", custom_details={"custom details1": "details-value"}, ) ``` #### 第 4 步：创建模型卡 为模型卡命名，定义模型卡片，然后使用该定义使用 SageMaker Python SDK 创建模型卡片。 ``` model_card_name = "my-model-card" my_card = ModelCard( name=model_card_name, status=ModelCardStatusEnum.DRAFT, model_overview=model_overview, training_details=training_details, intended_uses=intended_uses, evaluation_details=evaluation_details, additional_information=additional_information, sagemaker_session=sagemaker_session, ) my_card.create() ``` ### 在模型注册表中为您的模型创建 SageMaker 模型卡 开始创建模型卡之前，请确保已创建模型包组和模型包。有关使用模型注册表的更多信息，请参阅[利用模型注册中心进行模型注册部署](model-registry.md)。 **重要** 您必须拥有使用 “ SageMaker 模型注册表” 中操作的权限。我们建议使用`AmazonSageMakerModelRegistryFullAccess` AWS 托管策略。有关托管策略的更多信息，请参阅 [AWS 模型注册管理机构的托管策略](security-iam-awsmanpol-model-registry.md)。 使用 SageMaker Python SDK 在模型注册表中为模型包创建 SageMaker 模型卡。模型包是您训练过的模型。当您创建模型卡时，Amazon SageMaker 模型卡会自动将模型包中的数据导入模型卡片中。 当您为模型包创建模型卡时，Amazon SageMaker 模型卡使用该[DescribeModelPackage](https://docs.aws.amazon.com/APIReference/API_DescribeModelPackage.html#API_DescribeModelPackage_ResponseSyntax)操作将模型包中的数据添加到模型卡中。以下是可从模型包导入模型卡的字段的示例： + [ModelDataUrl](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelPackageContainerDefinition.html#sagemaker-Type-ModelPackageContainerDefinition-ModelDataUrl) + [ModelPackageDescription](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html#sagemaker-DescribeModelPackage-response-ModelPackageDescription) + [ModelPackageGroupName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html#sagemaker-DescribeModelPackage-response-ModelPackageGroupName) + [ModelPackageStatus](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html#sagemaker-DescribeModelPackage-response-ModelPackageStatus) + [ModelPackageVersion](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html#sagemaker-DescribeModelPackage-response-ModelPackageVersion) 使用以下代码来定义模型包并从中创建模型卡： ``` mp_details = ModelPackage.from_model_package_arn( model_package_arn="example_model_package_arn", sagemaker_session=sagemaker_session, ) model_card_name = "example-model-card" my_card = ModelCard( name=model_card_name, status=ModelCardStatusEnum.status, model_package_details=mp_details, sagemaker_session=sagemaker_session, ) my_card.create() ``` 对于 `status`，您要指定模型卡的批准状态。如果您未指定状态，则 SageMaker 模型卡片将使用默认值`DRAFT`。如果您未指定 A SageMaker I 会话，则 SageMaker 模型卡片将使用默认 SageMaker AI 会话。 必须指定模型名称和模型包的 Amazon 资源名称 (ARN)。有关获取模型包的 Amazon 资源名称 (ARN) 的信息，请参阅[查看和更新模型版本的详细信息 (Boto3)](model-registry-details.md#model-registry-details-api)。 您从模型包中创建的模型卡可能存在信息缺失或不准确的情况。您可以向模型卡添加信息或对其进行编辑。有关管理模型卡的更多信息，请参阅[模型卡操作](model-cards-manage.md)。 SageMaker 模型注册表支持模型包的版本控制。您可以对模型包进行版本控制，并为每个版本创建模型卡。先前版本模型卡中的信息会延续到后续版本创建的模型卡中。例如，一个模型包可以有版本 1、版本 2 和版本 3。假设您已为版本 1 创建了模型卡，但还没有为版本 2 创建模型卡。如果您为版本 3 创建模型卡，Amazon SageMaker 模型卡片会自动将版本 1 的模型卡中的信息传送到版本 3 的模型卡。 **注意** 您也可以为不使用版本控制的模型包创建模型卡。但是，大多数机器学习工作流都涉及同一模型的多个版本，因此我们建议您执行以下操作： 为每个模型包创建版本 为模型包的每个版本创建模型卡 # 模型卡操作 创建模型卡后，您可以对其进行管理。管理模型卡包括以下操作： + 编辑模型卡 + 删除模型卡 + 将模型卡导出为 PDF 您可以使用亚马逊 A SageMaker I 控制台或 SageMaker Python 软件开发工具包进行管理。有关使用 Python 开发工具包的更多信息，请参阅 Py SageMaker thon SDK API 参考中的[亚马逊 SageMaker 模型卡](https://sagemaker.readthedocs.io/en/stable/api/governance/model_card.html)。 有关使用 SageMaker Python SDK 的笔记本示例，请参阅 *[Amazon SageMaker 模型治理——模型卡](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker_model_governance/model_card.ipynb)*示例笔记本。 **Topics** + [编辑模型卡](model-cards-console-edit.md) + [导出模型卡](model-cards-console-export.md) + [删除模型卡](model-cards-console-delete.md) # 编辑模型卡 要编辑模型卡，请在 Amazon 模型卡控制台中选择模型卡的名称，导航到您选择的 SageMaker 模型卡，然后选择**编辑**。 保存模型卡后，将无法编辑该模型卡的名称。保存模型卡版本后，将无法更新该版本的模型卡。您需要进行的任何编辑都将保存为后续版本，以便拥有不可改变的模型更改记录。 要查看模型卡的不同版本，请选择**操作**、**选择版本**，然后选择要查看的版本。 您可以使用 `model_card.update()` 方法编辑模型卡。更新模型卡会创建新的模型卡版本，以便拥有不可改变的模型更改记录。您无法更新模型卡的名称。 ``` my_card.model_overview.model_description = "updated-model-decription" my_card.update() ``` # 导出模型卡 按照以下步骤导出模型卡。 1. 前往 Amazon SageMaker 模型卡控制台。 1. 选择要导出的模型卡的名称。 1. 在模型卡概述中，选择**操作**，然后选择**导出 PDF**。 1. 输入 S3 URI 或浏览模型卡 PDF 的可用 S3 存储桶。 1. 如果模型卡成功导出，则可在生成的横幅中选择**下载 PDF**，也可以直接从 Amazon S3 下载 PDF。 您可以通过指定 S3 输出路径在 SageMaker Python SDK 中导出模型卡，然后使用以下命令将模型卡 PDF 导出到该卡片中： ``` s3_output_path = f"s3://{bucket}/{prefix}/export" pdf_s3_url = my_card.export_pdf(s3_output_path=s3_output_path).delete() ``` # 删除模型卡 按照以下步骤永久删除一张或多张模型卡。 1. 前往 Amazon SageMaker Model Cards 控制台。 1. 选中要删除的卡名称左侧的框。 1. 选择右上角的**删除**。 1. 确认您的请求，永久删除一张或多张卡。 在控制台中查看模型卡概览时，也可以删除模型卡，方法是选择**操作**，然后选择**删除模型卡**。 在 SageMaker Python SDK 中，您可以使用以下命令永久删除模型卡片： ``` my_card.delete() ``` # 为 Amazon SageMaker 模型卡设置跨账户支持 使用 Amazon SageMaker 模型卡片中的跨账户支持在 AWS 账户之间共享模型卡。创建模型卡的账户是*模型卡账户*。模型卡账户中的用户与*共享账户* 共享模型卡。共享账户中的用户可以更新模型卡片或创建 PDFs 模型卡。 模型卡账户中的用户通过 AWS Resource Access Manager (AWS RAM) 共享他们的模型卡。 AWS RAM 帮助您跨 AWS 账户共享资源。有关简介 AWS RAM，请参阅[什么是 AWS Resource Access Manager？](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html) 以下是共享模型卡的过程： 1. 模型卡账户中的用户使用 AWS Resource Access Manager设置跨账户模型卡共享。 1. 如果模型卡使用 AWS KMS 密钥加密，则设置模型共享的用户还必须为共享账户中的用户提供 AWS KMS 权限。 1. 共享账户中的用户接受资源共享的邀请。 1. 共享账户中的用户向其他用户提供访问模型卡的权限。 如果您是模型卡账户中的用户，请参阅以下章节： + [设置跨账户模型卡共享](#model-cards-xaccount-set-up) + [为共享账户设置 AWS KMS 权限](#model-cards-xaccount-kms) + [获取对资源共享邀请的回复](#model-cards-xaccount-set-up-responses) 如果您是共享账户中的用户，请参阅[在共享账户中设置 IAM 用户权限](#model-cards-xaccount-shared-account-permissions)，了解如何为自己和账户中的其他用户设置权限。 ## 设置跨账户模型卡共享 使用 AWS Resource Access Manager (AWS RAM) 授予您 AWS 账户中的用户查看或更新在其他 AWS 账户中创建的模型卡片的权限。 要设置模型卡共享，必须创建资源共享。资源共享指定： + 所共享的资源 + 有权访问资源的人或物 + 资源的托管权限 有关资源共享的更多信息，请参阅 [AWS RAM的术语和概念](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-terms-and-concepts.html)。我们建议您在完成创建资源共享的过程之前，花点时间 AWS RAM 从概念上进行理解。 **重要** 您必须拥有创建资源共享的权限。有关权限的更多信息，请参阅[如何 AWS RAM 使用 IAM](https://docs.aws.amazon.com/ram/latest/userguide/security-iam-policies.html)。 有关创建资源共享的过程以及有关这些过程的其他信息，请参阅[创建资源共享](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create)。 在创建资源共享的过程中，您需要指定 `sagemaker:ModelCard` 作为资源类型。您还必须指定基于资源的策略的 Amazon 资源编号 (ARN)。 AWS RAM 您可以指定默认策略，也可以指定具有创建模型卡 PDF 的其他权限的策略。 使用默认的基于 `AWSRAMPermissionSageMakerModelCards` 资源的策略，共享账户中的用户有权执行以下操作： + [DescribeModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelCard.html) + [ListModelCardVersions](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListModelCardVersions.html) + [UpdateModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelCard.html) 使用基于 `AWSRAMPermissionSageMakerModelCardsAllowExport` 资源的策略，共享账户中的用户有权执行上述所有操作。他们还有权创建模型卡导出作业并通过以下操作对其进行描述： + [CreateModelCardExportJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelCardExportJob.html) + [DescribeModelCardExportJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelCardExportJob.html) 共享账户中的用户可以创建导出作业以生成模型卡的 PDF。他们还可以描述为查找 PDF 的 Amazon S3 URI 而创建的导出作业。 模型卡和导出作业是资源。模型卡账户拥有共享账户中的用户创建的导出作业。例如，账户 A 中的用户与共享账户 B 共享模型卡 X。账户 B 中的用户为模型卡 X 创建导出作业 Y，将输出结果存储在账户 B 中用户指定的 Amazon S3 位置。尽管账户 B 创建了导出作业 Y，但它属于账户 A。 每个 AWS 账户都有资源配额。有关与模型卡相关的配额的信息，请参阅 [Amazon A SageMaker I 终端节点和配额](https://docs.aws.amazon.com/general/latest/gr/sagemaker.html#limits_sagemaker)。 ### 为共享账户设置 AWS KMS 权限 如果您共享的模型卡已使用 AWS Key Management Service 密钥加密，则还需要与共享帐户共享对密钥的访问权限。否则，共享账户中的用户将无法查看、更新或导出模型卡。有关概述 AWS KMS，请参阅[AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)。 要向共享账户中的用户提供 AWS KMS 权限，请使用以下声明更新您的密钥策略： ``` { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::shared-account-id::role/example-IAM-role" ] }, "Action": [ "kms:GenerateDataKey", "kms:Decrypt", ] "Resource": "arn:aws:kms:AWS-Region-of-model-card-account:model-card-account-id:key/AWS KMS-key-id" "Condition": { "Bool": {"kms:GrantIsForAWSResource": true }, "StringEquals": { "kms:ViaService": [ "sagemaker.AWS-Region.amazonaws.com", "s3.AWS-Region.amazonaws.com" ], }, "StringLike": { "kms:EncryptionContext:aws:sagemaker:model-card-arn": "arn:aws:sagemaker:AWS-Region:model-card-account-id:model-card/model-card-name" } } } ``` 上述语句为共享账户中的用户提供了 `kms:Decrypt` 和 `kms:GenerateDataKey` 权限。使用 `kms:Decrypt`，用户可以解密模型卡。使用`kms:GenerateDataKey`，用户可以加密他们更新的或他们创建 PDFs 的模型卡。 ### 获取对资源共享邀请的回复 创建资源共享后，您在资源共享中指定的共享账户会收到加入该共享的邀请。这些账户必须接受邀请才能访问资源。 有关接受资源共享邀请的信息，请参阅 [Resource Acc *ess Manager 用户指南*中的使用共享 AWS 资源](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-shared.html)。AWS ### 在共享账户中设置 IAM 用户权限 以下信息假设您已接受模型卡账户发出的资源共享邀请。有关接受资源共享邀请的更多信息，请参阅[使用共享 AWS 资源](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-shared.html)。 您和您账户中的其他用户使用 IAM 角色访问从模型卡账户共享的模型卡。使用以下模板更改 IAM 角色的策略。您可以根据自己的使用案例修改模板。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sagemaker:DescribeModelCard", "sagemaker:UpdateModelCard", "sagemaker:CreateModelCardExportJob", "sagemaker:ListModelCardVersions", "sagemaker:DescribeModelCardExportJob" ], "Resource": [ "arn:aws:sagemaker:us-east-1:111122223333:model-card/example-model-card-name-0", "arn:aws:sagemaker:us-east-1:111122223333:model-card/example-model-card-name-1/*" ] }, { "Effect": "Allow", "Action": "s3:PutObject", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket-storing-the-pdf-of-the-model-card/model-card-name/*" } ] } ``` ------ 要访问使用加密的模型卡 AWS KMS，您必须为账户中的用户提供以下 AWS KMS 权限。 ``` { "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt", ], "Resource": "arn:aws:kms:AWS-Region:AWS-account-id-where-the-model-card-is-created:key/AWS Key Management Service-key-id" } ``` # 模型卡牌 SageMaker APIs 的低等级 您可以直接通过 SageMaker API 或 AWS 命令行界面 (AWS CLI) 创建 Amazon SageMaker 模型卡。 **注意** 使用低级创建模型卡片时 APIs，内容必须位于模型卡片 JSON 架构中并以字符串形式提供。有关更多信息，请参阅 [模型卡 JSON 架构](model-cards.md#model-cards-json-schema)。 ## SageMaker API 使用以下 SageMaker API 命令使用亚马逊 SageMaker 模型卡： + [CreateModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelCard.html) + [DescribeModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelCard.html) + [ListModelCards](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListModelCards.html) + [ListModelCardVersions](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListModelCardVersions.html) + [UpdateModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelCard.html) + [CreateModelCardExportJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelCardExportJob.html) + [DescribeModelCardExportJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelCardExportJob.html) + [ListModelCardExportJobs](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListModelCardExportJobs.html) + [DeleteModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteModelCard.html) ## AWS CLI 使用以下 AWS CLI 命令使用亚马逊 SageMaker 模型卡： + [create-model-card](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model-card.html) + [describe-model-card](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/describe-model-card.html) + [list-model-cards](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/list-model-cards.html) + [list-model-card-versions](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/list-model-card-versions.html) + [update-model-card](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/update-model-card.html) + [create-model-card-export-工作](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model-card-export-job.html) + [describe-model-card-export-工作](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/describe-model-card-export-job.html) + [list-model-card-export-工作](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/list-model-card-export-jobs.html) + [delete-model-card](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-model-card.html) # 模型卡 FAQs 有关亚马逊 SageMaker 模型卡的常见问题解答，请参阅以下常见问题解答。 ## 问：什么是模型风险？ 答：您可以将模型用于各种业务应用，从预测网络攻击、审批贷款申请到检测电子邮件的类别。每种应用都承担着不同程度的风险。例如，错误地检测网络攻击比错误地对电子邮件进行分类对业务的影响要大得多。鉴于模型的风险状况各不相同，您可以使用模型卡为模型提供 `low`、`medium` 或 `high` 风险评级。如果您不知道模型的风险，可将状态设置为 `unknown`。客户有责任为每个模型分配风险状况。根据风险评级，组织在将这些模型部署到生产环境时可能需要遵循不同的规则。有关更多信息，请参阅 [风险评级](model-cards.md#model-cards-risk-rating)。 ## 问：模型的预期用途是什么？ 模型的预期用途描述了在生产应用中应如何使用该模型。这已不仅仅是技术要求（例如应将模型部署到的实例类型），而是指要使用模型创建的应用类型、可以期望从模型获得合理性能的场景或用于模型的数据类型。我们建议在模型卡中提供这些信息，以便更好地治理模型。您可以在“预期用途”字段中定义一种模型规范，并确保模型开发人员和使用者在训练和部署模型时遵循此规范。有关更多信息，请参阅 [模型的预期用途](model-cards.md#model-cards-intended-uses)。 ## 问： SageMaker AI 会自动填充我的模型卡片中的信息吗？ 使用 SageMaker Python SDK 或 AWS 控制台创建模型卡片时， SageMaker AI 会自动填充有关您训练过的模型的信息。这包括全面的训练详细信息以及通过 `describe-model` API 调用提供的所有模型信息。如果您在 Amazon SageMaker Studio 工作，则可以通过调用 API 自动填充模型卡片。[DescribeModelPackage](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html) ## 问：我可以自定义模型卡吗？ Amazon SageMaker 模型卡具有定义的结构，无法修改。此结构为您提供有关在模型卡中应捕获哪些信息的指导。虽然无法更改模型卡的结构，但通过模型卡**附加信息**部分中的自定义属性，可以实现一定的灵活性。 ## 问：创建模型卡后可以对其进行编辑吗？ 模型卡具有与之关联的版本。除模型卡状态外，给定模型版本的所有属性均不可改变。如果您对模型卡进行任何其他更改，例如评估指标、描述或预期用途， SageMaker AI 会创建模型卡片的新版本以反映更新的信息。这样做是为了确保模型卡一旦创建就无法篡改。 每当您在模型注册表中更改模型包版本时，模型卡片都会自动更新。 ## 问：我能否为未使用 SageMaker AI 训练的模型创建模型卡？ 答：能。您可以为未接受过 SageMaker AI 训练的模型创建模型卡片，但卡片中不会自动填充任何信息。对于非 SageMaker AI 模型，您必须在模型卡中提供所需的所有信息。 ## 问：我可以导出或共享模型卡吗？ 答：能。您可以将模型卡的每个版本导出为 PDF，然后下载并共享。 ## 问：是否需要在模型注册表中注册我的模型才能使用模型卡？ 答：可通过 SageMaker AI 控制台和模型注册表访问模型卡。使用模型注册表时，系统会自动向您发送模型的每个版本的模型卡片。 ## 问：模型卡和模型注册表之间有何区别？ 答：模型卡旨在为组织提供一种机制，通过遵循 SageMaker 人工智能的规范性指导并提供自己的自定义信息，随心所欲地记录有关其模型的详细信息。您可以在机器学习流程一开始就引入模型卡，并使用它们来定义模型应解决的业务问题以及使用模型时需要考虑的任何注意事项。模型训练完成后，可以在与该模型关联的模型卡中填充有关该模型及其训练方式的信息。模型卡与模型关联，一旦与模型关联便不可改变。这可确保模型卡是与模型相关的所有信息（包括模型训练方式和使用方式）的唯一真实来源。 模型注册表是一个目录，用于存储有关模型的元数据。模型注册表中的每个条目都对应一个唯一的模型版本。该模型版本包含有关模型的信息，例如模型构件在 Amazon S3 中的存储位置、部署模型所需的容器以及应附加到模型的自定义元数据。每个模型包版本都有一个关联的模型卡片。 ## 问：模型卡片和模型注册表之间有何关系？ 答：模型卡片已集成到模型注册表对象中。模型注册表中模型包的每个版本均链接到其相应的模型卡片。您可以使用 [ModelPackageModelCard](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelPackageModelCard.html)API 访问每个版本的模型卡架构。 ## 问：模型卡版本与模型注册表中的模型版本是否相关？ 答：是的，模型卡和模型注册表中的模型之间存在 one-to-one关系。存储在模型注册表中的每个模型版本都有与之关联的相应模型卡片。 ## 问：模型卡是否与 SageMaker 模型监视器集成？ 答：不是。 您可以将指标文件上传到 Amazon S3 并将其链接到模型卡，将模型监控器计算的性能指标上传到模型卡，但是模型监控器和模型卡之间没有原生集成。 SageMaker 模型控制面板与 Model Monitor 集成。有关模型控制面板的更多信息，请参阅 [Amazon SageMaker 模型控制面板](https://docs.aws.amazon.com/sagemaker/latest/dg/model_dashboard.html)。