# Creating and managing custom models Amazon Comprehend includes built-in NLP (natural language processing) models that you can use for analyzing insights or topic modeling. You can also use Amazon Comprehend to create custom models for entity recognition and document classification. You can use model versioning to keep track of your model's history. When you create and train a new model version, you can make changes to the training dataset. Amazon Comprehend displays details (including model performance) for each model version on the model details page. Over time, you can see how model performance changes as you make changes to your training dataset. You can create model versions using the Amazon Comprehend console or API. As an alternative, Amazon Comprehend provides [Flywheels](flywheels.md) to simplify the tasks associated with training and evaluating new custom model versions. After you create a custom model, you can share the model with other users by allowing other AWS accounts to import a copy of your model. **Topics** + [Model versioning with Amazon Comprehend](model-versioning.md) + [Copying custom models between AWS accounts](custom-copy.md) # Model versioning with Amazon Comprehend Artificial intelligence and machine learning (AI/ML) is all about rapid experimentation. With Amazon Comprehend, you train and build out models which you use to gain insight on your data. With model versioning you can keep track of your modeling history and scores associated with running results of your models as you provide more or different sets of data. You can use versioning with your custom classification models or your custom entity recognition models. Taking a look at your different versions over time you can gain insight on how successful they've performed and gain insight on what parameters you used to get to your state of success. When you train a new version of an existing custom classifier model or entity recognition model, all you need to do is create a new version from the model details page and all the details populate for you. The new version will have the same name as your earlier model — what we call the versionID — although you will give it a unique version name during creation. As you add new versions to a model, you can see all the previous versions and their details in one view from the model details page. With versioning, you can see how model performance changes as you make changes to your training dataset. ![\[Graphic of a model with three versions, showing the F1 score for each version.\]](http://docs.aws.amazon.com/comprehend/latest/dg/images/model_versioning.png) **Create a new **Custom classifier** version (console)** 1. Sign in to the AWS Management Console and open the Amazon Comprehend console at [https://console.aws.amazon.com/comprehend/](https://console.aws.amazon.com/comprehend/) 1. From the left menu, choose **Customization** and then choose **Custom classification**. 1. From the **Classifiers** list, choose the name of the custom model from which you want to create a new version. The custom model details page is displayed. 1. On the top right, select **Create new model.** A screen opens with prepopulated details from the parent custom classification model. 1. Under **Version name** add a unique name to the new version. 1. Under version details, you can change the language and number of labels associated with your new model. 1. Under the **Data specifications** section configure how you want to provide the data to your new version— make sure to provide full data, which includes documents from your previous model and your new documents. You can change the **Classifier mode** (single-label, or multi-label), **Data format** (CSV file, Augmented manifest), your **Training dataset**, and your **Test dataset** (autosplit, or your custom test data configuration). 1. (Optional) update the S3 location for your output data 1. Under **Access permissions**, create or use an existing IAM role. 1. (Optional) Update your VPC settings 1. (Optional) Add tags to your new version to help keep track of the details. For more information about creating custom classifiers, see [Create a Custom Classifier](create-custom-classifier-console.md) **Create a new **Custom entity recognizer** version (console)** 1. Sign in to the AWS Management Console and open the Amazon Comprehend console at [https://console.aws.amazon.com/comprehend/](https://console.aws.amazon.com/comprehend/) 1. From the left menu, choose **Customization** and then choose **Custom entity recognition**. 1. From the **Recognizer model** list, choose the name of the recognizer from which you want to create a new version. The details page is displayed. 1. On the top right, select **Train new version.** A screen opens with prepopulated details from the parent entity recognizer. 1. Under **Version name** add a unique name to the new version. 1. Under Custom entity type, add the custom labels or label you want the recognizer to identify in your dataset and select **Add type**. Choose a custom entity type from the annotations or entity list you've provided. The recognizer will then use all of the included entity types to identify entities in the data set when running your job. Each entity type must be upper-case and separated by and underscore if it uses multiple words. A maximum of 25 types are allowed. 1. (Optional) Select **Recognizer encryption** to encrypt the data in the storage volume while your job is being processed. 1. Under the Training data section, specify the **Annotation and data format** details (CSV file, Augmented manifest)single-label, or multi-label), **Data format** (CSV, Augmented manifest), your **Training dataset**, and your **Test dataset** (autosplit, or your custom test data configuration). 1. (Optional) update the S3 location for your output data 1. Under **Access permissions**, create or use an existing IAM role. 1. (Optional) Update your VPC settings 1. (Optional) Add tags to your new version to help keep track of the details. To learn more about custom entity recognizers, see [Custom Entity Recognition](custom-entity-recognition.md) and [Creating a Custom Entity Recognizer Using the Console](realtime-analysis-cer.md). # Copying custom models between AWS accounts Amazon Comprehend users can copy trained custom models between AWS accounts in a two-step process. First, a user in one AWS account (account A), *shares* a custom model that's in their account. Then, a user in another AWS account (account B) *imports* the model into their account. The account B user does not need to train the model, and does not need to copy (or access) the original training data or test data. To share a custom model in account A, the user attaches an AWS Identity and Access Management (IAM) policy to a model version. This policy authorizes an entity in account B, such as a user or role, to import the model version into Amazon Comprehend in their AWS account. The account B user must import the model into the same AWS Region as the original model. To import the model in account B, the user of this account provides Amazon Comprehend with the necessary details, such as the Amazon Resource Name (ARN) of the model. By importing the model, this user creates a new custom model in their AWS account that replicates the model that they imported. This model is fully trained and ready for inference jobs, such as document classification or named entity recognition. Copying a custom model is useful if: + You belong to an organization that uses multiple AWS accounts. For example, your organization might have an AWS account for each phase of development, such as build, stage, test, and deploy. Or, it might have distinct AWS accounts for business functions, such as data science and engineering. + Your organization works with another, such as an AWS Partner, that trains custom models in Amazon Comprehend and provides them to you as their client. In scenarios like these, you can quickly copy a trained custom entity recognizer or document classifier from one AWS account to another. Copying a model in this way is easier than the alternative, where you copy training data between AWS accounts to train duplicate models. **Topics** + [Sharing a custom model with another AWS account](custom-copy-sharing.md) + [Importing a custom model from another AWS account](custom-copy-importing.md) # Sharing a custom model with another AWS account With Amazon Comprehend, you can share your custom models with others, so they can import your models into their AWS accounts. When a user imports one of your custom models, they create a new custom model in their account. Their new model duplicates the one that you shared. To share a custom model, you attach a policy to it that authorizes others to import it. Then, you provide those users with the details that they need. **Note** When other users import a custom model that you've shared, they must use the same AWS Region —for example, US East (N. Virginia)— that contains your model. **Topics** + [Before you begin](#custom-copy-sharing-prerequisites) + [Resource-based policies for custom models](#custom-copy-sharing-example-policy) + [Step 1: Add a resource-based policy to a custom model](#custom-copy-sharing-adding-policy) + [Step 2: Provide the details that others need to import](#custom-copy-sharing-details) ## Before you begin Before you can share a model, you must have a trained custom classifier or custom entity recognizer in Amazon Comprehend in your AWS account. For more information about training custom models, see [Custom classification](how-document-classification.md) or [Custom entity recognition](custom-entity-recognition.md). ### Required permissions #### IAM policy statement Before you can add a resource-based policy to a custom model, you require permissions in AWS Identity and Access Management (IAM). Your user, group, or role must have a policy attached so you can create, get, and delete model policies, as shown in the following example. **Example IAM policy to manage resource-based policies for custom models** ``` { "Effect": "Allow", "Action": [ "comprehend:PutResourcePolicy", "comprehend:DeleteResourcePolicy", "comprehend:DescribeResourcePolicy" ], "Resource": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/*" } ``` For information about creating an IAM policy, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*. For information about attaching an IAM policy, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *IAM User Guide*. #### AWS KMS key policy statement If you are sharing an encrypted model, then you might need to add permissions for AWS KMS. This requirement depends on the type of KMS key that you use to encrypt the model in Amazon Comprehend. An **AWS owned key** is owned and managed by an AWS service. If you use an AWS owned key, you do not need to add permissions for AWS KMS, and you can skip this section. A **Customer managed key** is a key that you create, own, and manage in your AWS account. If you use a customer managed key, you must add a statement to your KMS key policy. The policy statement authorizes one or more entities (such as users or accounts) to perform the AWS KMS operations required to decrypt the model. You use condition keys to help prevent the confused deputy problem. For more information, see [Cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md). Use the following condition keys in the policy to validate the entities that access your KMS key. When a user imports the model, AWS KMS checks that the ARN of the source model version matches the condition. If you do not include a condition in the policy, the specified principals can use your KMS key to decrypt any model version: + [aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) – Use this condition key with the `kms:GenerateDataKey` and `kms:Decrypt` actions. + [kms:EncryptionContext](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-encryption-context) – Use this condition key with the `kms:GenerateDataKey`, `kms:Decrypt`, and `kms:CreateGrant` actions. In the following example, the policy authorizes AWS account `444455556666` to use version 1 of the specified classifier model owned by AWS account `111122223333`. **Example KMS key policy to access a specific classifier model version** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": "*", "Condition": { "StringEquals": { "aws:SourceArn": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/classifierName/version/1" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:aws:comprehend:arn": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/classifierName/version/1" } } } ] } ``` The following example policy authorizes user **ExampleUser **from AWS account `444455556666` and **ExampleRole** from AWS account `123456789012` to access this KMS key via the Amazon Comprehend service. **Example KMS key policy to allow access to the Amazon Comprehend service (alternative 1).** The following example policy authorizes AWS account `444455556666` to access this KMS key via the Amazon Comprehend service, using an alternative syntax to the previous example. **Example KMS key policy to allow access to the Amazon Comprehend service (alternative 2).** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey", "kms:CreateGrant" ], "Resource": "*", "Condition": { "StringLike": { "kms:EncryptionContext:aws:comprehend:arn": "arn:aws:comprehend:*" } } } ] } ``` For more information, see [Key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*. ## Resource-based policies for custom models Before an Amazon Comprehend user in another AWS account can import a custom model from your AWS account, you must authorize them to do so. To authorize them, you add a *resource-based policy* to the model version that you want to share. A resource-based policy is an IAM policy that you attach to a resource in AWS. When you attach a resource policy to a custom model version, the policy authorizes users, groups, or roles to perform the `comprehend:ImportModel` action on the model version. **Example Resource-based policy for a custom model version** This example specifies the authorized entities in the `Principal` attribute. Resource "\$1" refers to the specific model version that you attach the policy to. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "comprehend:ImportModel", "Resource": "*", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root", "arn:aws:iam::444455556666:user/ExampleUser", "arn:aws:iam::123456789012:role/ExampleRole" ] } } ] } ``` For policies that you attach to custom models, `comprehend:ImportModel` is the only action that Amazon Comprehend supports. For more information about resource-based policies, see [Identity-based policies and resource-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html) in the *IAM User Guide*. ## Step 1: Add a resource-based policy to a custom model You can add a resource-based policy by using the AWS Management Console, AWS CLI, or Amazon Comprehend API. ### AWS Management Console You can use Amazon Comprehend in the AWS Management Console. **To add a resource-based policy** 1. Sign in to the AWS Management Console and open the Amazon Comprehend console at [https://console.aws.amazon.com/comprehend/](https://console.aws.amazon.com/comprehend/) 1. In the navigation menu on the left, under **Customization**, choose the page that contains your custom model: 1. If you are sharing a custom document classifier, choose **Custom classification**. 1. If you are sharing a custom entity recognizer, choose **Custom entity recognition**. 1. In the list of models, choose the model name to open its details page. 1. Under **Versions**, choose the name of the model version that you want to share. 1. On the version details page, choose the **Tags, VPC & Policy** tab. 1. In the **Resource-based policy** section, choose **Edit**. 1. On the **Edit resource-based policy page**, do the following: 1. For **Policy name**, enter a name that will help you recognize the policy after you create it. 1. Under **Authorize**, specify one or more of the following entities to authorize them to import your model: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/comprehend/latest/dg/custom-copy-sharing.html) 1. Under **Share**, you can copy the ARN of the model version to help you share it with the person who will import your model. When someone imports a custom model from a different AWS account, the model version ARN is required. 1. Choose **Save**. Amazon Comprehend creates your resource-based policy and attaches it to your model. ### AWS CLI To add a resource-based policy to a custom model with the AWS CLI, use the [PutResourcePolicy](https://docs.aws.amazon.com/comprehend/latest/dg/API_PutResourcePolicy.html) command. The command takes the following parameters: + `resource-arn` – The ARN of the custom model, including the model version. + `resource-policy` – A JSON file that defines the resource-based policy to attach to your custom model. You can also provide the policy as an inline JSON string. To provide valid JSON for your policy, enclose the attribute names and values in double quotes. If the JSON body is also enclosed in double quotes, you escape the double quotes that are inside the policy. + `policy-revision-id` – The revision ID that Amazon Comprehend assigned to the policy that you are updating. If you are creating a new policy that has no prior version, don't use this parameter. Amazon Comprehend creates the revision ID for you. **Example Add a resource-based policy to a custom model using the `put-resource-policy` command** This example defines a policy in a JSON file named **policyFile.json** and associates the policy to a model. The model is version **v2** of a classifier named **mycf1**. ``` $ aws comprehend put-resource-policy \ > --resource-arn arn:aws:comprehend:us-west-2:111122223333:document-classifier/mycf1/version/v2 \ > --resource-policy file://policyFile.json \ > --policy-revision-id revision-id ``` The JSON file for the resource policy contains the following contents: + *Action* – The policy authorizes the named principals to use `comprehend:ImportModel`. + *Resource* – The ARN of the custom model. Resource "\$1" refers to the model version that you specify in the `put-resource-policy` command. + *Principal* – The policy authorizes user `jane` from AWS account 444455556666 and all users from AWS account 123456789012. **** ``` { "Version":"2012-10-17", "Statement":[ {"Sid":"ResourcePolicyForImportModel", "Effect":"Allow", "Action":["comprehend:ImportModel"], "Resource":"*", "Principal": {"AWS": ["arn:aws:iam::444455556666:user/jane", "123456789012"] } } ] } ``` ### Amazon Comprehend API To add a resource-based policy to a custom model by using the Amazon Comprehend API, use the [PutResourcePolicy](https://docs.aws.amazon.com/comprehend/latest/dg/API_PutResourcePolicy.html) API operation. You can also add a policy to a custom model in the API request that creates the model. To do this, provide the policy JSON for the ModelPolicy parameter when you submit a [CreateDocumentClassifier](https://docs.aws.amazon.com/comprehend/latest/dg/API_CreateDocumentClassifier.html) or [CreateEntityRecognizer](https://docs.aws.amazon.com/comprehend/latest/dg/API_CreateEntityRecognizer.html) request. ## Step 2: Provide the details that others need to import Now that you have added the resource-based policy to your custom model, you have authorized other Amazon Comprehend users to import your model into their AWS accounts. However, before they can import, you must provide them with the following details: + The Amazon Resource Name (ARN) of the model version. + The AWS Region that contains the model. Anyone who imports your model must use the same AWS Region . + Whether the model is encrypted, and if it is, the type of AWS KMS key that you use: AWS owned key or customer managed key. + If your model is encrypted with a customer managed key, then you must provide the ARN of the KMS key. Anyone who imports your model must include the ARN in an IAM service role in their AWS account. This role authorizes Amazon Comprehend to use the KMS key to decrypt the model during the import. For more information about how other users import your model, see [Importing a custom model from another AWS account](custom-copy-importing.md). # Importing a custom model from another AWS account In Amazon Comprehend, you can import a custom model that's in another AWS account. When you import a model, you create a new custom model in your account. Your new custom model is a fully-trained duplicate of the model that you imported. **Topics** + [Before you begin](#custom-copy-importing-prerequisites) + [Importing a custom model](#custom-copy-importing-procedure) ## Before you begin Before you can import a custom model from another AWS account, ensure that the person who shared the model with you does the following: + Authorizes you to do the import. This authorization is granted in the resource-based policy that is attached to the model version. For more information, see [Resource-based policies for custom models](custom-copy-sharing.md#custom-copy-sharing-example-policy). + Provides you with the following information: + The Amazon Resource Name (ARN) of the model version. + The AWS Region that contains the model. You must use the same AWS Region when you import. + Whether the model is encrypted with an AWS KMS key and, if it is, the type of key that is used. If the model is encrypted, you might need to take additional steps, depending on the type of KMS key that is used: + **AWS owned key** – This type of KMS key is owned and managed by AWS. If the model is encrypted with an AWS owned key, no additional steps are needed. + **Customer managed key** – This type of KMS key is created, owned, and managed by an AWS customer in their AWS account. If the model is encrypted with a customer managed key, then the person who shared the model must: + Authorize you to decrypt the model. This authorization is granted in the KMS key policy for the customer managed key. For more information, see [AWS KMS key policy statement](custom-copy-sharing.md#custom-copy-sharing-prerequisites-permissions-kms). + Provide the ARN of the customer managed key. You use this ARN when you create an IAM service role. This role authorizes Amazon Comprehend to use the KMS key to decrypt the model. ### Required permissions Before you can import a custom model, you or your administrator must authorize the required actions in AWS Identity and Access Management (IAM). As an Amazon Comprehend user, you must be authorized to import by an IAM policy statement. If encryption or decryption is required during the import, then Amazon Comprehend must be authorized to use the necessary AWS KMS keys. ### IAM policy statement Your user, group or role must have a policy attached that allows the `ImportModel` action, as shown in the following example. **Example IAM policy to import a custom model** ``` { "Effect": "Allow", "Action": [ "comprehend:ImportModel" ], "Resource": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/*" } ``` For information about creating an IAM policy, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*. For information about attaching an IAM policy, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *IAM User Guide*. ### IAM service role for AWS KMS encryption When you import a custom model, you must authorize Amazon Comprehend to use AWS KMS keys in either of the following cases: + You are importing a custom model that is encrypted with a customer managed key in AWS KMS. In this case, Amazon Comprehend needs access to the KMS key so that it can decrypt the model during the import. + You want to encrypt the new custom model that you create with the import, and you want to use a customer managed key. In this case, Amazon Comprehend needs access to your KMS key so that it can encrypt the new model. To authorize Amazon Comprehend to use these AWS KMS keys, you create an *IAM service role*. This type of IAM role allows an AWS service to access resources in other services on your behalf. For more information about service roles, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*. If you use the Amazon Comprehend console to import, you can have Amazon Comprehend create the service role for you. Otherwise, you must create a service role in IAM before you import. The IAM service role must have a permissions policy and a trust policy, as shown by the following examples. **Example permissions policy** The following permissions policy allows the AWS KMS operations that Amazon Comprehend uses to encrypt and decrypt custom models. It grants access to two KMS keys: + One KMS key is in the AWS account that contains the model to import. It was used to encrypt the model, and Amazon Comprehend uses it to decrypt the model during the import. + The other KMS key is in the AWS account that imports the model. Amazon Comprehend uses this key to encrypt the new custom model that is created by the import. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:CreateGrant" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/key-id", "arn:aws:kms:us-west-2:444455556666:key/key-id" ] }, { "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDatakey" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/key-id", "arn:aws:kms:us-west-2:444455556666:key/key-id" ], "Condition": { "StringEquals": { "kms:ViaService": [ "s3.us-west-2.amazonaws.com" ] } } } ] } ``` **Example trust policy** The following trust policy allows Amazon Comprehend to assume the role and gain its permissions. It allows the `comprehend.amazonaws.com` service principal to perform the `sts:AssumeRole` operation. To help with [confused deputy prevention](cross-service-confused-deputy-prevention.md), you restrict the scope of the permission by using one or more global condition context keys. For `aws:SourceAccount`, specify the account Id of the user who is importing the model. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "comprehend.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "444455556666" } } } ] } ``` ------ ## Importing a custom model You can import a custom model by using the AWS Management Console, AWS CLI, or Amazon Comprehend API. ## AWS Management Console You can use Amazon Comprehend in the AWS Management Console. **To import a custom model** 1. Sign in to the AWS Management Console and open the Amazon Comprehend console at [https://console.aws.amazon.com/comprehend/](https://console.aws.amazon.com/comprehend/) 1. In the navigation menu on the left, under **Customization**, choose the page for the type of model that you are importing: 1. If you are importing a custom document classifier, choose **Custom classification**. 1. If you are importing a custom entity recognizer, choose **Custom entity recognition**. 1. Choose **Import version**. 1. On the **Import model version** page, enter the following details: + **Model version ARN** – The ARN of the model version to import. + **Model name** – A custom name for the new model that is created by the import. + **Version name** – A custom name for the new model version that is created by the import. 1. For **Model encryption**, choose the type of KMS key to use to encrypt the new custom model that you create with the import: + **Use AWS owned key** – Amazon Comprehend encrypts your model by using a key in AWS Key Management Service (AWS KMS) that is created, managed, and used on your behalf by AWS. + **Choose a different AWS KMS key (advanced)** – Amazon Comprehend encrypts your model by using a customer managed key that you manage in AWS KMS. If you choose this option, select a KMS key that's in your AWS account, or create a new one by choosing **Create an AWS KMS key**. 1. In the **Service access** section, grant Amazon Comprehend access to any AWS KMS keys that it needs to: + Decrypt the custom model that you import. + Encrypt that the new custom model that you create with the import. You grant access with an IAM service role that allows Amazon Comprehend to use the KMS keys. For **Service role**, do one of the following: + If you have an existing service role that you want to use, choose **Use an existing IAM role**. Then, select it under **Role name**. + If you want Amazon Comprehend to create a role for you, choose **Create an IAM role**. 1. If you chose to have Amazon Comprehend create the role for you, do the following: 1. For **Role name**, enter a role name suffix that will help you recognize the role later. 1. For **Source KMS key ARN**, enter the ARN of the KMS key that is used to encrypt the model that you're importing. Amazon Comprehend uses this key to decrypt the model during the import. 1. (Optional) In the **Tags** section, you can add tags to the new custom model that you create by importing. For more information about tagging custom models, see [Tagging a new resource](tagging-newtags.md). 1. Choose **Confirm**. ## AWS CLI You can use Amazon Comprehend by running commands with the AWS CLI. **Example Import-model command** To import a custom model, use the `import-model` command: ``` $ aws comprehend import-model \ > --source-model arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/bar \ > --model-name importedDocumentClassifier \ > --version-name versionOne \ > --data-access-role-arn arn:aws:iam::444455556666:role/comprehendAccessRole \ > --model-kms-key-id kms-key-id ``` This example uses the following parameters: + `source-model` – The ARN of the custom model to import. + `model-name` – A custom name for the new model that is created by the import. + `version-name` – A custom name for the new model version that is created by the import. + `data-access-role-arn` – The ARN of the IAM service role that allows Amazon Comprehend to use the necessary AWS KMS keys to encrypt or decrypt the custom model. + `model-kms-key-id` – The ARN or ID of the KMS key that Amazon Comprehend uses to encrypt the custom model that you create with this import. This key must be in AWS KMS in your AWS account. ## Amazon Comprehend API To import a custom model by using the Amazon Comprehend API, use the [ImportModel](https://docs.aws.amazon.com/comprehend/latest/dg/API_ImportModel.html) API action.