Importing a custom model from another AWS account - Amazon Comprehend
Before you beginImporting a custom model

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.

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.

  • 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.

    • 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.

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 in the IAM User Guide. For information about attaching an IAM policy, see Adding and removing IAM identity permissions in the IAM User Guide.

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 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, 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. 

{
  "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.

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/

  2. 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.

    2. If you are importing a custom entity recognizer, choose Custom entity recognition.

  3. Choose Import version.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

    2. 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.

  8. (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.

  9. Choose Confirm.

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.

To import a custom model by using the Amazon Comprehend API, use the ImportModel API action.