Ultralytics HUB-SDK Model Management
Welcome to the Ultralytics HUB-SDK Model Management documentation! Whether you're just getting started with managing machine learning models or you're a seasoned data scientist looking for specific operation instructions, you've come to the right place. This guide provides a smooth journey through the HUB-SDK features, ensuring you gain the know-how to efficiently manage your models.
Retrieve a Model by its Unique Identifier
In machine learning workflows, accessing a specific model is a common requirement. With Ultralytics HUB-SDK, fetching a model by its ID is straightforward. This function sets up a model object based on the provided unique identifier, granting you full access to the model's details and operations.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
print(model.data) # Outputs the model's metadata and configuration
Access Project and Dataset Prerequisites
Before creating or training a model, it's crucial to ensure that both a project and a dataset are present. The following code snippet helps verify these components by initializing their objects. While utilizing a project and dataset to organize model training is beneficial, it's not mandatory. If either ID is missing, the object data (project.data, dataset.data) will be empty.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
project = client.project("<Project ID>")
dataset = client.dataset("<Dataset ID>")
Create a New Model with Custom Configuration
Creating a new model tailored to your project requirements is simple with this function. Specify the model's name and associate it with your project and dataset. You can also customize configurations, such as setting the batch size or device. Note that projectId and datasetId parameters are optional if you're not ready to tie the model to a project or dataset yet.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
data = {
"meta": {"name": "sdk model"}, # Model name
"projectId": project.id, # Optional: Associate with an existing project
"datasetId": dataset.id, # Optional: Associate with an existing dataset
"config": { # Define hyperparameters and settings
"batchSize": "-1",
"cache": "ram",
"device": "name",
"epochs": "5",
"imageSize": "640",
"patience": "5", # Stop training if validation doesn't improve
},
}
model = client.model()
model.create_model(data) # Creates the model with your specified details
Update an Existing Model's Metadata or Config
As projects evolve, you might need to update a model's metadata, such as renaming it for clarity. The SDK provides a method to refresh these details effortlessly, minimizing manual errors and saving time.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
model.update({"meta": {"name": "Updated Model Name"}}) # Renames the specified model
Delete a Model Safely
Deleting a model is irreversible, so use this function with caution. When you're sure you want to remove a model from the system, the following command will permanently delete the specified model, along with all its associated data.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
model.delete(hard=True) # Permanently deletes the specified model
By default, the delete method performs a soft delete, marking the model as inactive without removing it permanently. If you want to perform a hard delete and remove the model along with its associated data permanently, pass the argument hard=True as shown above. Exercise caution when using the hard delete option, as it is irreversible.
Listing All Your Models with Pagination
Ultralytics HUB-SDK streamlines fetching lists of models, implementing pagination to efficiently navigate through potentially large collections. By customizing arguments such as page_size, you can tailor the output to your needs, including the ability to view both private and public projects.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model_list = client.model_list(page_size=10) # Fetches the first page with 10 models
print("Current result:", model_list.results) # Displays the current page's models
model_list.next() # Move to the next page
print("Next page result:", model_list.results)
model_list.previous() # Return to the previous page
print("Previous page result:", model_list.results)
Upload and Visualize Training Metrics
To track and visualize your model's performance metrics throughout the training process, use this function to upload metrics such as loss and accuracy. This enables the continual monitoring of training progress and simplifies the analysis stage.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
# Define your metrics structure. Keys are steps, and values are JSON strings of metrics.
data = {
1: '{"loss/1": 0.5, "accuracy/1": 0.85}',
2: '{"loss/2": 0.4, "accuracy/2": 0.88}',
3: '{"loss/3": 0.3, "accuracy/3": 0.90}',
}
model.upload_metrics(data) # Uploads the specified metrics to the model
Export Your Model for Deployment or Analysis
Exporting models for various purposes, such as deployment or in-depth analysis, is straightforward. Specify the format you require, and this function will prepare the model accordingly. Whether you need a TensorFlow or PyTorch format, the SDK handles it seamlessly.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
model.export(format="pyTorch") # Exports the model as a PyTorch file
Retrieve a Direct Weight URL
Occasionally, you might require direct access to your model's remotely-stored artifacts. This function provides a URL to access specific files, like your best-performing model weights.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
weight_url = model.get_weights_url("best") # or "last"
print("Weight URL link:", weight_url)
Upload a Model Checkpoint
Uploading a model checkpoint is straightforward with the upload_model function. Indicate the significance of the checkpoint with the is_best flag and the training epoch for clarity.
from hub_sdk import HUBClient
credentials = {"api_key": "<YOUR-API-KEY>"}
client = HUBClient(credentials)
model = client.model("<Model ID>")
model.upload_model(is_best=True, epoch=5, weights="<Weight File>") # Uploads the specified model checkpoint
Conclusion
Ultralytics HUB-SDK offers a comprehensive set of operations for effective model management, enabling you to focus on achieving the best results in your machine learning endeavors. Should you have any further questions or require assistance, please reach out to our community or support team. Happy modeling! 🚀
