—

NGC API Examples

Resource

—

NGC API Examples

Jupyter Notebook examples that illustrates the basic functionality of the NGC API for Private Registries

model-scripts.ipynb

Using the NGC Model Scripts Registry Via NGC API

This notebook walks you through the basics of using the NGC API to work with the NGC Model Scripts Registry. We'll go through the process of:

Configuring The API
Downloading Model Scripts
Creating New Model Script Entities
Creating New Versions
Uploading Files To Versions
Finishing Up

For the full API documentation please click here.

Configuring The API

Setup

The first thing we need to do is configure the NGC Authentication Service so that we can make requests to create assets in our private registry from our local system.

The following code cell sets up some parameters:

YOUR_API_KEY - Your NGC API Key. If you need instructions on how to generate a new API key, check out this video.
ORG_NAME - The name of the Private Registry Org where you'd like to create a new model script.

You'll also notice that we define an NGC_SCOPE, based on our ORG. We'll provide this context to the API later.

In [1]:

# NGC Authentication Endpoint
NGC_AUTH_URL = 'https://authn.nvidia.com/token'

# Your API Key/Private Registry ORG
YOUR_API_KEY = 'NGC_API_KEY'
ORG_NAME = 'ngcorg'

# NGC Scope/Access Token
NGC_SCOPE = 'group/ngc:' + ORG_NAME

Getting An Access Token

To get an NGC Access Token, that we'll need to provide to our subsequent API requests, execute the code cell below. We also print the generated token - not only to prove it works, but also because we wanted to show that we knew where the print command was in Python.

note - The access token generated below does expire, so if you're modifying this notebook and running into errors, it could well be worth running this block again. We've also wrapped it in a function, just to save you from scrolling around.

In [3]:

import requests, base64, json



# Helper Function to generate auth token

def get_ngc_auth_token():

    query_string = {'scope': NGC_SCOPE}

    auth_string = f'$oauthtoken:{YOUR_API_KEY}'

    # Generate authorisation based on your API Key (standard base64 encoding)
    encoded_bytes = base64.b64encode(auth_string.encode('utf-8'))
    encoded_auth_str = str(encoded_bytes, 'utf-8')

    # Request Headers
    headers = {
        'Authorization': f'Basic {encoded_auth_str}',
        'Accept': '*/*',
        'Cache-Control': 'no-cache',
        'Host': 'authn.nvidia.com',
        'Accept-Encoding': 'gzip, deflate',
        'Connection': 'keep-alive',
        'cache-control': 'no-cache'
        }

    # Execute request
    response = requests.request('GET', NGC_AUTH_URL, headers=headers, params=query_string)

    # Convert response to JSON
    json_response = json.loads(response.text)
    
    return json_response['token']

# Retrieve Auth Token
auth_token = get_ngc_auth_token()

# Print it
print(auth_token)

eyJraWQiOiJFUkNPOklCWFY6TjY2SDpOUEgyOjNMRlQ6SENVVToyRkFTOkJJTkw6WkxKRDpNWk9ZOkRVN0o6TVlVWSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJhY2Nlc3MiOlt7InR5cGUiOiJncm91cC9uZ2MiLCJuYW1lIjoibmdjdmlkZW9zIiwiYWN0aW9ucyI6WyJlZ3hfYWRtaW4iLCJyZWdpc3RyeS1yZWFkIiwicmVnaXN0cnktdXNlci1yZWFkIiwicmVnaXN0cnktdXNlci13cml0ZSIsInJlZ2lzdHJ5LXdyaXRlIiwicmVnaXN0cnlfdXNlcl91c2VyIiwidXNlci1yZWFkIiwidXNlci13cml0ZSJdLCJtZXRhZGF0YSI6bnVsbH1dLCJvcHRpb25zIjpbXSwic3ViIjoic3JsNzBpaDQ1bmtqMDJkZGF2cnVxdXFpNnAiLCJpc3MiOiJhdXRobi5udmlkaWEuY29tIiwiaWF0IjoxNTg1NjU2MjY5LCJleHAiOjE1ODU2NTY4NjksImp0aSI6IjNiNTEyMDA0LWQxOTctNDQ1MS1hNzQwLTVlNzU2NjhmNWI2NCJ9.hdoaK-VcmzrmBPSqLYujFlbHXEljPqV5MbaVvrLa5M_7fpiC4RrGDIIIqz7qZF3us6opketaLojfSEu07qrTCRW_XbV-tURTxDjhJt4D3Cg_6KmNQkU7YFjHLgt_PloGqEOcVjGD4jg6cCHJeQNtHZR6FKLEpN2wOOCu6ZD5EuXo4rwyspT0Z3dxsNk_Gmhful0rEkhQIhQr8gJdXkisaQ9Y94Wb-QuBnr-EsYXPdQ1BYFtWo9j24J2IEpZvdzSm9-Hxp5l0vL0_gDPs4SLspRWOEVtUU2DHpn09GmO5wq4HcG9yN9H3pPcKc3YB3dPfCl1KiGbGdSS4EQ2CAaIzmr_iRe3laHB9IaCmE25TyBIAcBciwgoyHsuXUhq-jpf1XhjrVmb1tQ-wscI0xfdV4q1VTcN0X4IazGDHWhz5Z511hucLpAaEX3Z5_hsimCcKK1mfCYaV1_yxL-JtUl7JD0EKFVImMW2yNrFhNqk_tEWxNFCxA44IK41KghHckkH2snGNi3tFZ-L0FkI2kXKVUm2aQkIet6odkE4CF65OeUVyc-zZ7h-0t5FHONyrXvlJ5iGBAqJfupb5OIVM8ouADRKG0zOamWPWF3ZUL4OSYb9OaXUYfsQXT1K87QyjSC28t-YZ1-HemAHd_60kw_Fs2rdTHDa0XWtJJyyADdttFU0

Downloading Models

These instructions walk you through the process of downloading model scripts from an org in NGC. To download from a team you'll need to modify the model_url below to match the endpoint.

The format would change to:

https://api.ngc.nvidia.com/v2/org/<org-name>/team/<team-name>/recipes/<model-name>/versions/<model-version>/zip

Setup

In order to download a model script from a private registry, you need to specify two additional parameters:

model_script_name - The name of the model script you wish to download. Please note this must be the full name from the URL in NGC, not the display name visible through the GUI. So we're looking for some_model_script_name not Some Model Script Name.
model_script_version - This is the version you wish to download! Once again, this needs to be the full version name from NGC. You can get this from the URL of the "Version History" tab in NGC.

The following code cell lets you set those parameters:

In [4]:

model_script_name = 'ngc_model_api_examples'
model_script_version = '1.0.0'

Model Script Download

We're nearly ready to download model script! As we're using Python's requests library to make the API requests to NGC, we need a way of downloading model scripts.

The "helper function" below takes a URL and a header file (containing a bearer token) and will retrieve the .zip of a model script in NGC and download it to the local directory (wherever this notebook is running). We've enabled streaming for large files and by default the filename will be created as follows:

<model_script_name>_<model_script_version>.zip

In [6]:

# Helper function for downloading files
def download_asset_from_ngc(url, headers):
    #cleans up local filename
    split_url = url.split('/')
    local_filename = f'{split_url[-4]}_{split_url[-2]}.{split_url[-1]}'
    # Streaming enabled for large files...
    with requests.get(url, headers=headers, stream=True) as r:
        r.raise_for_status()
        with open(local_filename, 'wb') as f:
            for chunk in r.iter_content(chunk_size=8192): 
                if chunk: # filter out keep-alive new chunks
                    f.write(chunk)
    return local_filename

Now we've done all the hard work of getting an auth/bearer token from NGC and written a simple helper function to download model scripts, all we need to do is run the code cell below to download our content.

You'll see this has worked when the output displays the name of the model script we just downloaded...

In [7]:

# Retrieve Auth Token
auth_token = get_ngc_auth_token()

# Get Model URL
model_script_api_url = f"https://api.ngc.nvidia.com/v2/org/{ORG_NAME}/recipes/{model_script_name}/versions/{model_script_version}/zip"

headers = {
    'Authorization': f'Bearer {auth_token}',
    'Accept': '*/*',
    'Cache-Control': 'no-cache',
    'Accept-Encoding': 'gzip, deflate',
    'Referer': model_script_api_url,
    'Connection': 'keep-alive',
    'cache-control': 'no-cache'
    }

# Use Helper Function to download a model
download_model_from_ngc(model_script_api_url, headers)

Out[7]:

'ngc_model_api_examples_1.0.0.zip'

Creating Model Scripts

In this section we'll walk you through the process of creating a new model script in a private registry using the NGC API. We're only covering the basics here, so if you'd like to see the full range of options please check out the API Docs.

Here's a list of the required properties you must set on your new model script:

application - string - The intended use case for your model (OTHER, NLP, Computer Vision etc.)
format - string - The format of any weights/model files.
framework - string - Training framework used (TensorFlow, PyTorch, Other etc.).
precision - string - Training precision used (AMP, FP16, OTHER etc.).
shortDescription - string - A short description of your model script

In the code cell below we set up the properties for the model we're going to upload...

In [55]:

new_model_script_data = {
      'application': 'OTHER',
      'builtBy': 'Chris Parsons',
      'shortDescription': 'This is a model script',
      'description': '# A model script to prove the API works', # This can be markdown...
      'displayName': 'Model Script Uploaded Via API',
      'trainingFramework': 'Other',
      'modelFormat': 'TensorFlow .ckpt',
      'labels': ['Docs'],
      'name': 'model_script_api_upload',
      'precision': 'OTHER',
      'publicDatasetUsed': {
          'license': 'None',
          'link': 'None',
          'name': 'None'
      }
}

#We need to pass a string to the API so let's convert it here
payload = json.dumps(new_model_script_data, indent=4)

With the properties/metadata for our new model script set we can now make the request to create a model via the NGC API. Simply run this code block to create the entity. We'll also print the API response so we can see that it was successful.

In [56]:

# Retrieve Auth Token
auth_token = get_ngc_auth_token()

# URL with the Org we'd like to create the new model in
upload_model_url = f"https://models.ngc.nvidia.com/v1/org/{ORG_NAME}/recipes"

# Payload with model metadata
payload = payload

headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': f'Bearer {auth_token}',
    'Cache-Control': 'no-cache',
    'Host': 'models.ngc.nvidia.com',
    'Accept-Encoding': 'gzip, deflate',
    'Connection': 'keep-alive',
    'cache-control': 'no-cache'
    }

response = requests.request('POST', upload_model_url, data=payload, headers=headers)

# Print the response so we can see the model was created correctly
print(response.text)

{"recipe":{"orgName":"ngcvideos","labels":["Docs"],"builtBy":"Chris Parsons","shortDescription":"This is a model script","isReadOnly":false,"publicDatasetUsed":{"link":"None","name":"None","license":"None"},"application":"OTHER","description":"# A model script to prove the API works","canGuestDownload":false,"isPublic":false,"precision":"OTHER","createdDate":"2020-03-31T14:33:07.080Z","trainingFramework":"Other","name":"model_script_api_upload","displayName":"Model Script Uploaded Via API","modelFormat":"TensorFlow .ckpt","updatedDate":"2020-03-31T14:33:07.080Z"},"requestStatus":{"statusCode":"SUCCESS","requestId":"f2ce5928-0e2a-42c2-b1f5-8e787342a4ac"}}

Awesome!!!

So we've done it. Those are all the steps we need to follow to create a model script in NGC via the API.

Ok, so there aren't any files in it yet, but we can fix that next...

Creating Versions

Just like earlier, when we created a model script asset in NGC, we're going to walk you through the process of uploading a new version of that script.

Once again, this isn't exhaustive, and if you're looking for full documentations of our features, please check out our docs.

Here's a list of the required properties you must set on your model script version:

accuracyReached - The accuracy of the model (or N/A)
batchSize - The batch size of the model (or N/A)
gpuModel - The GPU type used for the model (V100, T4, or N/A)
memoryFootprint - The model script memory footprint.
numEpochs - The number of epochs used in training
versionId - The string identifier of the version

In the code cell below we set up the properties for the version we're going to upload...

In [59]:

# Name of model script to add version to
model_script_name = 'model_script_api_upload' # Just like when we downloaded a model script, this is the name from the URL

# Version Metadata
new_model_script_version_metadata = {
    'accuracyReached': 100,
    'batchSize': 10,
    'gpuModel': 'V100',
    'id': 1,
    'memoryFootprint': '15b',
    'numberOfEpochs': 100,
    'ownerName': 'Chris Parsons',
    'versionId': 'Version Uploaded Via API'
}

# We need to pass a string to the API so let's convert it here
payload = json.dumps(new_model_script_version_metadata, indent=4)

Now we've created all our version metadata, we can run the code cell below to upload via the API.

In [60]:

# Retrieve Auth Token
auth_token = get_ngc_auth_token()

model_script_version_url = f'https://models.ngc.nvidia.com/v1/org/{ORG_NAME}/recipes/{model_script_name}/versions'


payload = payload

headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': f'Bearer {auth_token}',
    'Cache-Control': 'no-cache',
    'Host': 'models.ngc.nvidia.com',
    'Accept-Encoding': 'gzip, deflate',
    'Connection': 'keep-alive',
    'cache-control': 'no-cache'
    }

response = requests.request('POST', model_script_version_url, data=payload, headers=headers)

print(response.text)

{"recipe":{"orgName":"ngcvideos","labels":["Docs"],"builtBy":"Chris Parsons","shortDescription":"This is a model script","isReadOnly":true,"publicDatasetUsed":{"link":"None","name":"None","license":"None"},"application":"OTHER","description":"# A model script to prove the API works","canGuestDownload":false,"isPublic":false,"precision":"OTHER","createdDate":"2020-03-31T14:33:07.080Z","trainingFramework":"Other","name":"model_script_api_upload","displayName":"Model Script Uploaded Via API","modelFormat":"TensorFlow .ckpt","updatedDate":"2020-03-31T14:33:07.080Z"},"recipeVersion":{"status":"UPLOAD_PENDING","memoryFootprint":"15b","batchSize":10,"accuracyReached":100.0,"totalSizeInBytes":0,"totalFileCount":0,"gpuModel":"V100","versionId":"Version Uploaded Via API","createdByUser":"srl70ih45nkj02ddavruquqi6p","createdDate":"2020-03-31T14:34:53.976Z","numberOfEpochs":100},"requestStatus":{"statusCode":"SUCCESS","requestId":"85f113da-6f4a-4d19-9da8-b3a87f19c87e"}}

Uploading Files

Now the version is created, we need to upload files. The next few steps cover specifying the file you'd like to upload and submitting an API request to upload the files to the version you created previously.

The full API documentation for uploadArtifactFileInOrgUsingPUT can be seen here

To get started, specify the following in the code cell below:

model_script_version you'd like to upload files to
file_path the path to the file you'd like to upload

In [61]:

# Set the model version you'd like to upload files to 
model_script_version = 'Version%20Uploaded%20Via%20API'

file_path = 'path/to/file/files.txt'

# The name of the file you'd like to upload
file_name = 'model_script.txt'

As you can see, in this simple example we're just uploading a text file to NGC. I hope you're doing something much more exciting than that...

Running the following code cell will upload those files to the NGC Model Version via the API.

In [62]:

# Refresh Auth Token
auth_token = get_ngc_auth_token()

model_file_url = f"https://models.ngc.nvidia.com/v1/org/{ORG_NAME}/recipes/{model_script_name}/versions/{model_script_version}/files/{file_name}"

headers = {
    'Accept': "application/json",
    'Expect': "100-continue",
    'Authorization': f"Bearer {auth_token}",
    'Cache-Control': "no-cache",
    'Host': "models.ngc.nvidia.com",
    'Accept-Encoding': "gzip, deflate",
    'Connection': "keep-alive"
    }

files = {
    'file': (file_name, open(file_path, 'rb')),
}

response = requests.request("PUT", model_file_url, files=files, headers=headers)



print(response.text)

{"requestStatus":{"statusCode":"SUCCESS","requestId":"af1ef67f-6b18-4ab7-88bf-dfca6ff751a0"}}

Repeat these two steps to upload multiple files to the same version in NGC.

Once you're happy you've uploaded all of your files, simply update the version to confirm uploading is complete.

In [65]:

# Refresh Auth Token
auth_token = get_ngc_auth_token()

update_model_script_version_url = f"https://models.ngc.nvidia.com/v1/org/{ORG_NAME}/recipes/{model_script_name}/versions/{model_script_version}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': f"Bearer {auth_token}",
    'Cache-Control': "no-cache",
    'Host': "models.ngc.nvidia.com",
    'Accept-Encoding': "gzip, deflate",
    'Connection': "keep-alive",
    'cache-control': "no-cache"
    }

# Version Metadata
version_upload_complete_data = {
    "status": "UPLOAD_COMPLETE",
}

#We need to pass a string to the API so let's convert it here
payload = json.dumps(version_upload_complete_data, indent=4)

response = requests.request("PATCH", update_model_script_version_url, data=payload, headers=headers)

print(response.text)

<Response [200]>

The End

That's it!! While there's a whole lot more that you can do with our NGC API - we've covered the basics and given you enough knowledge to get you up and running with Models in NGC. From here on in the possiblities are endless.

If you've got any questions email me at chrisp@nvidia.com