# Admin guide for private model hubs in Amazon SageMaker JumpStart There are actions that administrators can take related to curated model hubs that users within your organization can access. This includes creating, adding, deleting, and managing access of private hubs. This page also includes information about the supported AWS Regions for curated private hubs, as well as the prerequisites needed to use curated private model hubs. ## Supported AWS Regions Curated private hubs are currently generally available in the following AWS commercial Regions: + us-east-1 + us-east-2 + us-west-2 + eu-west-1 + eu-central-1 + ap-northeast-1 + ap-northeast-2 + ap-south-1 + ap-southeast-1 + ap-southeast-2 + il-central-1 (SDK only) The default maximum number of hubs allowed in a single Region is 50. ## Prerequisites To use a curated private hub in Studio, you must have the following prerequisites: + An AWS account with administrator access + An AWS Identity and Access Management (IAM) role with access to Amazon SageMaker Studio + An Amazon SageMaker AI domain with JumpStart enabled + If your users try to use proprietary models, they must have subscriptions to those models in AWS Marketplace. + AWS accounts that are deploying proprietary models must have subscriptions to those models in AWS Marketplace. For more information on getting started with Studio, see [Amazon SageMaker Studio](studio-updated.md). # Create a private model hub Use the following steps to create a private hub to manage access control for pretrained JumpStart foundation models for your organization. You must intstall the SageMaker Python SDK and configure the necessary IAM permissions before creating a model hub. **Create a private hub** 1. Install the SageMaker Python SDK and import the necessary Python packages. ``` # Install the SageMaker Python SDK !pip3 install sagemaker --force-reinstall --quiet # Import the necessary Python packages import boto3 from sagemaker import Session from sagemaker.jumpstart.hub.hub import Hub ``` 1. Initialize a SageMaker AI Session. ``` sm_client = boto3.client('sagemaker') session = Session(sagemaker_client=sm_client) session.get_caller_identity_arn() ``` 1. Configure the details of your private hub such as the internal hub name, UI display name, and UI hub description. **Note** If you do not specify an Amazon S3 bucket name when creating your hub, the SageMaker hub service creates a new bucket on your behalf. The new bucket has the following naming structure: `sagemaker-hubs-REGION-ACCOUNT_ID`. ``` HUB_NAME="Example-Hub" HUB_DISPLAY_NAME="Example Hub UI Name" HUB_DESCRIPTION="A description of the example private curated hub." REGION="us-west-2" ``` 1. Check that your **Admin** IAM role has the necessary Amazon S3 permissions to create a private hub. If your role does not have the necessary permissions, navigate to the **Roles** page in the IAM console. Choose the **Admin** role and then choose **Add permissions** in the **Permissions policies** pane to create an inline policy with the following permissions using the JSON editor: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:ListBucket", "s3:GetObject", "s3:GetObjectTagging" ], "Resource": [ "arn:aws:s3:::jumpstart-cache-prod-REGION", "arn:aws:s3:::jumpstart-cache-prod-REGION/*" ], "Effect": "Allow" } ] } ``` ------ 1. Create a private model hub using your configurations from **Step 3** using `hub.create()`. ``` hub = Hub(hub_name=HUB_NAME, sagemaker_session=session) try: # Create the private hub hub.create( description=HUB_DESCRIPTION, display_name=HUB_DISPLAY_NAME ) print(f"Successfully created Hub with name {HUB_NAME} in {REGION}") # Check that no other hubs with this internal name exist except Exception as e: if "ResourceInUse" in str(e): print(f"A hub with the name {HUB_NAME} already exists in your account.") else: raise e ``` 1. Verify the configuration of your new private hub with the following `describe` command: ``` hub.describe() ``` # Add models to a private hub After creating a private hub, you can then add allow-listed models. For the full list of available JumpStart models, see the [Built-in Algorithms with pre-trained Model Table](https://sagemaker.readthedocs.io/en/stable/doc_utils/pretrainedmodels.html) in the SageMaker Python SDK reference. 1. You can filter through the available models programmatically using the `hub.list_sagemaker_public_hub_models()` method. You can optionally filter by categories such as framework (`"framework == pytorch"`), tasks such as image classification (`"task == ic"`), and more. For more information about filters, see [https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/jumpstart/notebook_utils.py](https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/jumpstart/notebook_utils.py). The filter parameter in the `hub.list_sagemaker_public_hub_models()` method is optional. ``` filter_value = "framework == meta" response = hub.list_sagemaker_public_hub_models(filter=filter_value) models = response["hub_content_summaries"] while response["next_token"]: response = hub.list_sagemaker_public_hub_models(filter=filter_value, next_token=response["next_token"]) models.extend(response["hub_content_summaries"]) print(models) ``` 1. You can then add the filtered models by specifying the model ARN in the `hub.create_model_reference()` method. ``` for model in models: print(f"Adding {model.get('hub_content_name')} to Hub") hub.create_model_reference(model_arn=model.get("hub_content_arn"), model_name=model.get("hub_content_name")) ``` # Update resources in a private hub You can update resources in your private hub to make changes to their metadata. The resources that you can update include model references to Amazon SageMaker JumpStart models, custom models, notebooks, datasets, and JsonDoc. When updating model, notebook, datasets, or JsonDoc resources, you can update the content description, display name, keywords, and support status. When updating model references to JumpStart models, you can only update the field specifying the minimum model version that you'd like to use. + “Update model or notebook resources” to include DataSet/JsonDoc. In CLI command, DataSets/JsonDocs should added to the hub-content-type argument. Follow the section specific to the resource that you want to update. ## Update model or notebook resources To update a model or a notebook resource, use the [UpdateHubContent](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateHubContent.html) API. The valid metadata fields that you can update with this API are the following: + `HubContentDescription` – The description of the resource. + `HubContentDisplayName` – The display name of the resource. + `HubContentMarkdown` – The description of the resource, in Markdown formatting. + `HubContentSearchKeywords` – The searchable keywords of the resource. + `SupportStatus` – The current status of the resource. In your request, include a change for one or more of the preceding fields. If you attempt to update any other fields, such as the hub content type, you receive an error. ------ #### [ AWS SDK for Python (Boto3) ] The following example shows how you can use the AWS SDK for Python (Boto3) to submit an [ UpdateHubContent](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateHubContent.html) request. **Note** The `HubContentVersion` you specify in the request means that the specific version's metadata is updated. To find all of the available versions of your hub content, you can use the [ ListHubContentVersions](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListHubContentVersions.html) API. ``` import boto3 sagemaker_client = boto3.Session(region_name=).client("sagemaker") sagemaker_client.update_hub_contents( HubName=, HubContentName=, HubContentType=<"Model"|"Notebook">, HubContentVersion='1.0.0', # specify the correct version that you want to update HubContentDescription= ) ``` ------ #### [ AWS CLI ] The following example shows how you can use the AWS CLI to submit an [ update-hub-content](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-hub-content.html) request. ``` aws sagemaker update-hub-content \ --hub-name \ --hub-content-name \ --hub-content-type <"Model"|"Notebook"> \ --hub-content-version "1.0.0" \ --hub-content-description ``` ------ ## Update model references To update a model reference to a JumpStart model, use the [ UpdateHubContentReference](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateHubContentReference.html) API. You can only update the `MinVersion` field for model references. ------ #### [ AWS SDK for Python (Boto3) ] The following example shows how you can use the AWS SDK for Python (Boto3) to submit an [ UpdateHubContentReference](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateHubContentReference.html) request. ``` import boto3 sagemaker_client = boto3.Session(region_name=).client("sagemaker") update_response = sagemaker_client.update_hub_content_reference( HubName=, HubContentName=, HubContentType='ModelReference', MinVersion='1.0.0' ) ``` ------ #### [ AWS CLI ] The following example shows how you can use the AWS CLI to submit an [ update-hub-content-reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-hub-content-reference.html) request. ``` aws sagemaker update-hub-content-reference \ --hub-name \ --hub-content-name \ --hub-content-type "ModelReference" \ --min-version "1.0.0" ``` ------ # Cross-account sharing for private model hubs with AWS Resource Access Manager After creating a private model hub, you can share the hub to the necessary accounts using AWS Resource Access Manager (AWS RAM). For more information on creating a private hub, see [Create a private model hub](jumpstart-curated-hubs-admin-guide-create.md). The following page gives in-depth information about managed permissions related to private hubs within AWS RAM. For information about how to create a resource share within AWS RAM, see [Set up cross-account hub sharing](jumpstart-curated-hubs-ram-setup.md). ## Managed permissions for curated private hubs The available access permissions are read, read and use, and full access permissions. The permission name, description, and list of specific APIs available for each permission are listed in the following: + Read permission (`AWSRAMPermissionSageMaker AIHubRead`): The read privilege allows resource consumer accounts to read contents in the shared hubs and view details and metadata. + `DescribeHub`: Retrieves details about a hub and its configuration + `DescribeHubContent`: Retrieves details about a model available in a specific hub + `ListHubContent`: Lists all models available in a hub + `ListHubContentVersions`: Lists the version of all models available in a hub + Read and use permission (`AWSRAMPermissionSageMaker AIHubReadAndUse`): The read and use privilege allows resource consumer accounts to read contents in the shared hubs and deploy available models for inference. + `DescribeHub`: Retrieves details about a hub and its configuration + `DescribeHubContent`: Retrieves details about a model available in a specific hub + `ListHubContent`: Lists all models available in a hub + `ListHubContentVersions`: Lists the version of all models available in a hub + `DeployHubModel`: Allows access to deploy available open-weight hub models for inference + Full access permission (`AWSRAMPermissionSageMaker AIHubFullAccessPolicy`): The full access privilege allows resource consumer accounts to read contents in the shared hubs, add and remove hub content, and deploy available models for inference. + `DescribeHub`: Retrieves details about a hub and its configuration + `DescribeHubContent`: Retrieves details about a model available in a specific hub + `ListHubContent`: Lists all models available in a hub + `ListHubContentVersions`: Lists the version of all models available in a hub + `ImportHubContent`: Imports hub content + `DeleteHubContent`: Deletes hub content + `CreateHubContentReference`: Creates a hub content reference that shares a model from the SageMaker AI **Public models** hub to a private hub + `DeleteHubContentReference`: Delete a hub content reference that shares a model from the SageMaker AI **Public models** hub to a private hub + `DeployHubModel`: Allows access to deploy available open-weight hub models for inference `DeployHubModel` permissions are not required for proprietary models. # Set up cross-account hub sharing SageMaker uses [AWS Resource Access Manager (AWS RAM)](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html) to help you securely share your private hubs across accounts. Set up cross-account hub sharing using the following instructions along with the [Sharing your AWS resources](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) instructions in the *AWS RAM User Guide*. **Create a resource share** 1. Select **Create resource share** through the [AWS RAM console](https://console.aws.amazon.com/ram/home). 1. When specifying resource share details, choose the **SageMaker Hubs** resource type and select one more more private hubs that you want to share. When you share a hub with any other account, all of its contents are also shared implicitly. 1. Associate permissions with your resources share. For more information about managed permissions, see [Managed permissions for curated private hubs](jumpstart-curated-hubs-ram.md#jumpstart-curated-hubs-ram-permissions) 1. Use AWS account IDs to specify the accounts to which you want to grant access to your shared resources. 1. Review your resource share configuration and select **Create resource share**. It may take a few minutes for the resource share and principal associations to complete. For more information, see [Sharing your AWS resources](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS Resource Access Manager User Guide*. After the resource share and principal associations are set, the specified AWS accounts receive an invitation to join the resource share. The AWS accounts must accept the invite to gain access to any shared resources. For more information on accepting a resource share invite through AWS RAM, see [Using shared AWS resources ](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-shared.html)in the *AWS Resource Access Manager User Guide*. # Delete models from a private hub You can delete models from a private hub used by your organization by specifying the model ARN in the `hub.delete_model_reference()` method. This removes access to the model from the private hub. ``` hub.delete_model_reference(model-name) ``` # Restrict access to JumpStart gated models Amazon SageMaker JumpStart provides access to both publicly available and proprietary foundation models. There are certain gated models in private Amazon S3 buckets that require you to have accepted the model's EULA (end user license agreement) in order to access them. For more information, see [EULA acceptance with the SageMaker Python SDK](jumpstart-foundation-models-choose.md#jumpstart-foundation-models-choose-eula-python-sdk). The current default behavior is that if a user accepts a model's EULA, then the user can access the model and create [ fine-tuning training jobs](jumpstart-foundation-models-use-python-sdk-estimator-class.md). However, if you're an administrator and would like to restrict fine-tuning access to these gated models, you can set a policy that denies permissions to use the `CreateTrainingJob` action whenever the request is to a gated model. The following is an example AWS Identity and Access Management (IAM) policy that an administrator can add to a user's IAM role: ``` { "Effect": "Deny", "Action": "sagemaker:CreateTrainingJob", "Resource": "*", "Condition": { "Bool": { "sagemaker:DirectGatedModelAccess": "true" } } } ``` If you want to grant users access to specific models without providing unrestricted access to the gated models, set up a curated hub and add the specific models to the hub. For more information, see [Private curated hubs for foundation model access control in JumpStart](jumpstart-curated-hubs.md). # Remove access to the SageMaker **Public models** hub In addition to adding a private curated hub to JumpStart in Studio, you can also remove access to the SageMaker **Public models** hub for your users. The SageMaker **Public models** hub has access to all available JumpStart foundation models. If you remove access to the SageMaker **Public models** hub and a user has access to only one private hub, then the user is taken directly into that private hub when they choose **JumpStart** in the left navigation pane in Studio. If a user has access to multiple private hubs, then the user is taken to a **Hubs** menu page when they choose **JumpStart** in the left navigation pane in Studio. Remove access to the SageMaker **Public models** hub for your users with the following inline policy: **Note** You can specify any additional Amazon S3 buckets that you want your hub to access in the policy below. Be sure to replace *`REGION`* with the Region of your hub. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "s3:*", "Effect": "Deny", "NotResource": [ "arn:aws:s3:::jumpstart-cache-prod-us-east-1/*.ipynb", "arn:aws:s3:::jumpstart-cache-prod-us-east-1/*eula*", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] }, { "Action": "sagemaker:*", "Effect": "Deny", "Resource": [ "arn:aws:sagemaker:us-east-1:aws:hub/SageMakerPublicHub", "arn:aws:sagemaker:us-east-1:aws:hub-content/SageMakerPublicHub/*/*" ] } ] } ``` ------ # Delete a private hub You can delete a private hub from your admin account. Before deleting a private hub, you must first remove any content in that hub. Delete hub contents and hubs with the following commands: ``` # List the model references in the private hub response = hub.list_models() models = response["hub_content_summaries"] while response["next_token"]: response = hub.list_models(next_token=response["next_token"]) models.extend(response["hub_content_summaries"]) # Delete all model references in the hub for model in models: hub.delete_model_reference(model_name=model.get('HubContentName')) # Delete the private hub hub.delete() ``` # Troubleshooting The following sections give information about IAM permissions issues that might arise when creating a private model hub, as well as informationa bout how to resolve those issues. **`ValidationException` when calling the `CreateModel` operation: Could not access model data** This exception arises when you do not have the appropriate Amazon S3 permissions configured for your **Admin** role. For more information on the Amazon S3 permissions needed to create a private hub, see **Step 3** in [Create a private model hub](jumpstart-curated-hubs-admin-guide-create.md). **`Access Denied` or `Forbidden` when calling `create()`** You are denied access when creating a private hub if you do not have the appropriate permissions to access the Amazon S3 bucket associated with the SageMaker **Public models** hub. For more information on the Amazon S3 permissions needed to create a private hub, see **Step 3** in [Create a private model hub](jumpstart-curated-hubs-admin-guide-create.md).