# User guide
<a name="jumpstart-curated-hubs-user-guide"></a>

The following topics cover accessing and using models in your Amazon SageMaker JumpStart curated model hubs. Learn how to access your curated hub models through the Amazon SageMaker Studio interface or programmatically with the SageMaker Python SDK. Additionally, learn how to fine-tune curated hub models to adapt them for your specific use cases and business needs.

**Topics**
+ [Access curated model hubs in Amazon SageMaker JumpStart](jumpstart-curated-hubs-access-hubs.md)
+ [Fine-tune curated hub models](jumpstart-curated-hubs-fine-tune.md)

# Access curated model hubs in Amazon SageMaker JumpStart
<a name="jumpstart-curated-hubs-access-hubs"></a>

You can access a private model hub either through Studio or through the SageMaker Python SDK.

## Access your private model hub in Studio
<a name="jumpstart-curated-hubs-user-guide-studio"></a>

**Important**  
As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md).

In Amazon SageMaker Studio, open the JumpStart landing page either through the **Home** page or the **Home** menu on the left-side panel. This opens the **SageMaker JumpStart** landing page where you can explore model hubs and search for models.
+ From the **Home** page, choose **JumpStart** in the **Prebuilt and automated solutions** pane. 
+ From the **Home** menu in the left panel, navigate to the **JumpStart** node.

For more information on getting started with Amazon SageMaker Studio, see [Amazon SageMaker Studio](studio-updated.md).

From the **SageMaker JumpStart** landing page in Studio, you can explore any private model hubs that include allow-listed models for your organization. If you only have access to one model hub, then the **SageMaker JumpStart** landing page takes you directly into that hub. If you have access to multiple hubs, you are taken to the **Hubs **page. 

For more information on fine-tuning, deploying, and evaluating models that you have access to in Studio, see [Use foundation models in Studio](jumpstart-foundation-models-use-studio-updated.md).

## Access your private model hub using the SageMaker Python SDK
<a name="jumpstart-curated-hubs-user-guide-sdk"></a>

You can access your private model hub using the SageMaker Python SDK. Your access to read, use, or edit your curated hub is provided by your administrator.

**Note**  
If a hub is shared across accounts, then the `HUB_NAME` must be the hub ARN. If a hub is not shared across accounts, then the `HUB_NAME` can be the hub name.

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
       from sagemaker.jumpstart.model import JumpStartModel
       from sagemaker.jumpstart.estimator import JumpStartEstimator
   ```

1. Initalize a SageMaker AI session and connect to your private hub using the hub name and Region.

   ```
   # If a hub is shared across accounts, then the HUB_NAME must be the hub ARN
       HUB_NAME="Example-Hub-ARN" 
       REGION="us-west-2" 
       
       # Initialize a SageMaker session
       sm_client = boto3.client('sagemaker') 
       sm_runtime_client = boto3.client('sagemaker-runtime') 
       session = Session(sagemaker_client=sm_client, 
                           sagemaker_runtime_client=sm_runtime_client)
       
       # Initialize the private hub
       hub = Hub(hub_name=HUB_NAME, sagemaker_session=session)
   ```

1. After connecting to a private hub, you can list all available models in that hub using the following commands:

   ```
   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"])
           
       print(models)
   ```

1. You can get more information about a specific model using the model name with the following command:

   ```
   response = hub.describe_model(model_name="example-model")
       print(response)
   ```

For more information on fine-tuning and deploying models that you have access to using the SageMaker Python SDK, see [Use foundation models with the SageMaker Python SDK](jumpstart-foundation-models-use-python-sdk.md).

# Fine-tune curated hub models
<a name="jumpstart-curated-hubs-fine-tune"></a>

In your private curated model hub, you can run fine-tuning training jobs using your model references. Model references point to a publicly available JumpStart model in the SageMaker AI public hub, but you can fine-tune the model on your own data for your specific use case. After the fine-tuning job, you have access to the model weights that you can then use or deploy to an endpoint.

You can fine-tune curated hub models in just a few lines of code using the SageMaker Python SDK. For more general information on fine-tuning publicly available JumpStart models, see [Foundation models and hyperparameters for fine-tuning](jumpstart-foundation-models-fine-tuning.md).

## Prerequisites
<a name="jumpstart-curated-hubs-fine-tune-prereqs"></a>

In order to fine-tune a JumpStart model reference in your curated hub, do the following:

1. Make sure that your user's IAM role has the SageMaker AI `TrainHubModel` permission attached. For more information, see [ Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *AWS IAM User Guide*.

   You should attach a policy like the following example to your user's IAM role:

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": "sagemaker:TrainHubModel",
               "Resource": "arn:aws:sagemaker:*:111122223333:hub/*"
           }
       ]
   }
   ```

------
**Note**  
If your curated hub is shared across accounts and the hub content is owned by another account, make sure that your `HubContent` (the model reference resource) has a resource-based IAM policy that also grants the `TrainHubModel` permission to the requesting account, as shown in the following example.  

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "AllowCrossAccountSageMakerAccess",
               "Effect": "Allow",
               "Principal": {
                   "AWS": "arn:aws:iam::111122223333:root"
               },
               "Action": [
                   "sagemaker:TrainHubModel"
               ],
               "Resource": [
                   "arn:aws:sagemaker:*:111122223333:hub/*"
               ]
           }
       ]
   }
   ```

1. Have a private curated hub with a model reference to a JumpStart model that you want to fine-tune. For more information about creating a private hub, see [Create a private model hub](jumpstart-curated-hubs-admin-guide-create.md). To learn how to add publicly available JumpStart models to your private hub, see [Add models to a private hub](jumpstart-curated-hubs-admin-guide-add-models.md).
**Note**  
The JumpStart model you choose should be fine-tunable. You can verify whether a model is fine-tunable by checking the [ Built-in Algorithms with Pre-trained Models Table](https://sagemaker.readthedocs.io/en/stable/doc_utils/pretrainedmodels.html).

1. Have a training dataset that you want to use for fine-tuning the model. The dataset should be in the appropriate training format for the model that you want to fine-tune.

## Fine-tune a curated hub model reference
<a name="jumpstart-curated-hubs-fine-tune-pysdk"></a>

The following procedure shows you how to fine-tune a model reference in your private curated hub using the SageMaker Python SDK.

1. Make sure that you have the latest version (at least `2.242.0`) of the SageMaker Python SDK installed. For more information, see [ Use Version 2.x of the SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable/v2.html).

   ```
   !pip install --upgrade sagemaker
   ```

1. Import the AWS SDK for Python (Boto3) and the modules you'll need from the SageMaker Python SDK.

   ```
   import boto3
   from sagemaker.jumpstart.estimator import JumpStartEstimator
   from sagemaker.session import Session
   ```

1. Initialize a Boto3 session, a SageMaker AI client, and a SageMaker Python SDK session.

   ```
   sagemaker_client = boto3.Session(region_name=<AWS-region>).client("sagemaker")
   sm_session = Session(sagemaker_client=sagemaker_client)
   ```

1. Create a `JumpStartEstimator` and provide the JumpStart model ID, the name of your hub that contains the model reference, and your SageMaker Python SDK session. For a list of model IDs, see the [ Built-in Algorithms with Pre-trained Models Table](https://sagemaker.readthedocs.io/en/stable/doc_utils/pretrainedmodels.html).

   Optionally, you can specify the `instance_type` and `instance_count` fields when creating the estimator. If you don't, the training job uses the default instance type and count for the model you're using.

   You can also optionally specify the `output_path` to the Amazon S3 location where you want to store the fine-tuned model weights. If you don't specify the `output_path`, then uses a default SageMaker AI Amazon S3 bucket for the region in your account, named with the following format: `sagemaker-<region>-<account-id>`.

   ```
   estimator = JumpStartEstimator(
       model_id="meta-textgeneration-llama-3-2-1b",
       hub_name=<your-hub-name>,
       sagemaker_session=sm_session, # If you don't specify an existing session, a default one is created for you
       # Optional: specify your desired instance type and count for the training job
       # instance_type = "ml.g5.2xlarge"
       # instance_count = 1
       # Optional: specify a custom S3 location to store the fine-tuned model artifacts
       # output_path: "s3://<output-path-for-model-artifacts>"
   )
   ```

1. Create a dictionary with the `training` key where you specify the location of your fine-tuning dataset. This example points to an Amazon S3 URI. If you have additional considerations, such as using local mode or multiple training data channels, see [ JumpStartEstimator.fit()](https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html#sagemaker.jumpstart.estimator.JumpStartEstimator.fit) in the SageMaker Python SDK documentation for more information.

   ```
   training_input = {
       "training": "s3://<your-fine-tuning-dataset>"
   }
   ```

1. Call the estimator's `fit()` method and pass in your training data and your EULA acceptance (if applicable).
**Note**  
The following example sets `accept_eula=False.` You should manually change the value to `True` in order to accept the EULA.

   ```
   estimator.fit(inputs=training_input, accept_eula=False)
   ```

Your fine-tuning job should now begin.

You can check on your fine-tuning job by viewing your training jobs, either in the SageMaker AI console or by using the [ListTrainingJobs](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingJobs.html) API.

You can access your fine-tuned model artifacts at the Amazon S3 `output_path` that was specified in the `JumpStartEstimator` object (either the default SageMaker AI Amazon S3 bucket for the region, or a custom Amazon S3 path you specified, if applicable).