本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立模型裝置
**重要**
允許 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 建立 Amazon SageMaker 資源的自訂 IAM 政策也必須授與許可，才能將標籤新增至這些資源。需要將標籤新增至資源的許可，因為 Studio 和 Studio Classic 會自動標記它們建立的任何資源。如果 IAM 政策允許 Studio 和 Studio Classic 建立資源，但不允許標記，則在嘗試建立資源時可能會發生 "AccessDenied" 錯誤。如需詳細資訊，請參閱[提供標記 SageMaker AI 資源的許可](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。
提供許可來建立 SageMaker 資源的 [AWS Amazon SageMaker AI 的 受管政策](security-iam-awsmanpol.md) 已包含建立這些資源時新增標籤的許可。
您可以使用 SageMaker AI 主控台或 SageMaker Python SDK 來建立 Amazon SageMaker 模型卡。您也可以直接使用 API 作業。如需有關這些 API 作業的更多相關資訊，請參閱[適用於模型卡的低階 SageMaker API](model-cards-apis.md)。
## 使用 SageMaker AI 主控台建立模型卡
前往 Amazon SageMaker AI 主控台。在瀏覽窗格的 **控管** 下，請選擇 **模型卡**。選擇右上角的 **建立模型卡**。
遵循**建立模型卡**提示中的四個步驟，記錄有關您模型的詳細資訊。
### 步驟 1：輸入模型詳細資訊和預定用途
如果您的模型是 AWS 資源，請在此欄位中指定確切的模型名稱，以自動填入模型詳細資訊。若要瀏覽現有的模型名稱，請參閱 Amazon SageMaker AI 主控台中的**模型**。每個唯一的模型名稱只能有一個關聯的模型卡。
如果您的模型不是 AWS 資源，請提供模型的唯一名稱。若要將模型新增為 AWS 資源，請參閱《*Amazon SageMaker AI 開發人員指南*》中的[建立模型](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-deployment.html#realtime-endpoints-deployment-create-model)。或者，您可以使用 [SageMaker AI Marketplace](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-marketplace.html) 或 [SageMaker AI 模型註冊庫](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：輸入訓練詳細資訊
將任何訓練詳細資訊、訓練觀察、資料集、超參數，以及有關模型目標函式的詳細資訊新增至模型卡。
模型卡中的目標函式可以是訓練期間最佳化的任何特徵。這可以包括但不限於成本函式、損失函式或目標指標。在本節中，記錄對訓練您的模型而言最重要的目標函式。
我們建議您將您目標函式的以下屬性編入目錄：
+ 最佳化方向
+ 指標
+ Description
例如，您可以將二進位分類問題 (描述) 的交叉熵損失 (指標) 最小化 (最佳化方向)，或將邏輯迴歸的可能性最大化。此外，您可以提供有關為什麼選擇此目標函式而不是其他特徵的附註。
#### 步驟 3：輸入評估詳細資訊
如果您有 SageMaker Clarify 或模型監控產生的現有評估報告，請為這些報表提供 S3 URI，或手動上傳它們，將其新增至模型卡。
如需有關 SageMaker Clarify 的更多資訊，請參閱[執行 SageMaker Clarify 處理任務以進行偏差分析和達成可解釋性](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)。
若要新增您自己的評估報告，請選擇**一般模型卡評估**。所有模型卡評估報告都必須在[模型卡 JSON 結構描述](model-cards.md#model-cards-json-schema)。
#### 步驟 4：輸入其他詳細資訊
新增自訂模型卡詳細資訊欄位欄位，以取得您要在模型卡上解釋的任何其他資訊。例如，您可能會包含具有*個人理財*值*的企業營運*自訂欄位。
#### 儲存模型卡
檢視模型卡中的資訊後，請選擇右下角的**儲存**，以儲存您的模型卡。
## 使用 SageMaker Python SDK 建立模型卡
在建立模型卡之前，您必須先定義您模型卡的內容。使用 SageMaker Python SDK 時，模型內容包含模型概觀、訓練詳細資訊、預定用途、評估詳細資訊和其他資訊。
您可以為下列項目建立模型卡：
+ 在 SageMaker AI 內託管的模型
+ SageMaker 模型註冊表中的模型套件 (模型)
+ 在 SageMaker AI 外部託管或註冊的模型
您也可以建立模型卡，而不將任何模型與其關聯。
我們建議您將已訓練過的模型新增至 SageMaker 模型註冊表。模型註冊表可協助您將模型編入目錄並追蹤模型版本。建立模型卡時，模型註冊表中有關模型的資訊會自動填入模型卡。建立模型卡後，您可以編輯模型卡或新增資訊。
如需使用模型註冊表的更多資訊，請參閱[使用模型註冊庫進行模型註冊部署](model-registry.md)。如需有關從模型註冊表建立模型卡的資訊，請參閱[在 SageMaker 模型註冊表中為您的模型建立模型卡](#model-cards-sdk-create-model-registry)。
**注意**
若要使用模型卡搭配 SageMaker Python SDK，您必須先建立 SageMaker AI 工作階段。如需更多資訊，請參閱 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](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-run.html) 或 [SageMaker AI Model Monitor](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 模型註冊表中的 SageMaker Python SDK 來建立模型套件的模型卡。模型套件是您訓練過的模型。當您建立模型卡時，Amazon SageMaker 模型卡會自動將資料從模型套件匯入模型卡中。
當您為模型套件建立模型卡時，Amazon SageMaker 模型卡會使用[描述模型套件](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`的預設值。如果您未指定 SageMaker AI 工作階段，SageMaker 模型卡會使用預設的 SageMaker AI 工作階段。
您必須指定模型的名稱和模型套件的 Amazon Resource Name (ARN)。如需取得模型套件的 Amazon Resource Name (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 的模型卡。
**注意**
您也可以為不使用版本控制的模型套件建立模型卡。但是，大多數機器學習的工作流程都涉及相同模型的多個版本，因此我們建議您進行以下操作：
為每個模型套件建立一個版本
為模型套件的每個版本建立模型卡