Guides
Vi Dashboard
  1. Developer Tools
  2. Vi SDK
  3. API Resources

Models

Access models through client.models in the Datature Vi SDK.

Models are the checkpoint artifacts produced by completed training runs. Each run can produce multiple checkpoints (one per epoch or at configured intervals). You can list all checkpoints for a run, retrieve a specific epoch, and download the weights to a local directory for inference.

Before You Start

Get started with the Vi SDK →

Methods

list()

List model checkpoints for a training run.

models = client.models.list("run_abc123")

for model in models.items:
    print(f"Model: {model.model_id}")
    print(f"Epoch: {model.spec.epoch}")
from vi.api.types import PaginationParams

models = client.models.list(
    run_id_or_link="run_abc123",
    pagination=PaginationParams(page_size=50)
)

for model in models.items:
    print(f"{model.model_id}")
models = client.models.list("run_abc123")

print("Available models:")
for model in models.items:
    epoch = model.spec.epoch or "N/A"
    metrics_str = "No metrics"

    if model.spec.evaluation_metrics:
        metrics = model.spec.evaluation_metrics
        metrics_str = ", ".join(f"{k}: {v:.4f}" for k, v in metrics.items())

    print(f"  Epoch {epoch}: {metrics_str}")
from vi.api.resources.models.responses import Model

def find_best_model(run_id: str, metric_name: str = "accuracy") -> tuple[Model | None, float]:
    """Find the checkpoint with the best metric value."""
    models = client.models.list(run_id)

    best_model: Model | None = None
    best_value = float('-inf')

    for model in models.items:
        if not model.spec.evaluation_metrics:
            continue

        value = model.spec.evaluation_metrics.get(metric_name, 0)
        if value > best_value:
            best_value = value
            best_model = model

    return best_model, best_value

best, value = find_best_model("run_abc123", "accuracy")
if best:
    print(f"Best model: {best.model_id}")
    print(f"Accuracy: {value}")

Parameters

Name
Type
Description
Required
Default
run_id_or_link
string
Run identifier or API link.
Required
—
pagination
object
Pagination settings. Accepts PaginationParams or a dict.
Optional
PaginationParams()

Returns: PaginatedResponse[Model]

get()

Get a specific model checkpoint.

model = client.models.get(run_id_or_link="run_abc123")

print(f"Model ID: {model.model_id}")
print(f"Epoch: {model.spec.epoch}")
model = client.models.get(
    run_id_or_link="run_abc123",
    ckpt="epoch_10"
)

print(f"Model ID: {model.model_id}")
print(f"Epoch: {model.spec.epoch}")
model = client.models.get(run_id_or_link="run_abc123")

if model.spec.evaluation_metrics:
    for metric, value in model.spec.evaluation_metrics.items():
        print(f"{metric}: {value}")
model = client.models.get(run_id_or_link="run_abc123")
model.info()  # Prints formatted model summary

Parameters

Name
Type
Description
Required
Default
run_id_or_link
string
Run identifier or API link.
Required
—
ckpt
string
Checkpoint name. Defaults to the latest checkpoint.
Optional
None

Returns: Model

download()

Download a model checkpoint to a local directory.

downloaded = client.models.download(
    run_id_or_link="run_abc123",
    save_dir="./models"
)

print(f"Model path: {downloaded.model_path}")
downloaded = client.models.download(
    run_id_or_link="run_abc123",
    ckpt="epoch_10",
    save_dir="./models"
)

print(f"Model: {downloaded.model_path}")
print(f"Config: {downloaded.run_config_path}")
downloaded = client.get_model(
    run_id="run_abc123",
    save_path="./models"
)

print(f"Model: {downloaded.model_path}")
print(f"Config: {downloaded.run_config_path}")
from pathlib import Path

def get_or_download_model(run_id: str, save_dir: str = "./models") -> dict[str, str]:
    """Download model if not already cached locally."""
    model_dir = Path(save_dir) / run_id

    if model_dir.exists() and (model_dir / "model_full").exists():
        print(f"Using cached model at {model_dir}")
        return {
            "model_path": str(model_dir / "model_full"),
            "run_config_path": str(model_dir / "run_config.json")
        }

    return client.get_model(run_id=run_id, save_path=save_dir)

result = get_or_download_model("run_abc123")
from vi.inference import ViModel

downloaded = client.get_model(
    run_id="run_abc123",
    save_path="./models"
)

model = ViModel(
    secret_key="your-secret-key",
    organization_id="your-organization-id",
    run_id="run_abc123"
)

result, error = model(
    source="test.jpg",
    user_prompt="Describe this image"
)

if error is None:
    print(result.caption)

Parameters

Name
Type
Description
Required
Default
run_id_or_link
string
Run identifier or API link.
Required
—
ckpt
string
Checkpoint name. Defaults to the latest checkpoint.
Optional
None
save_dir
string
Local directory to save the downloaded model files.
Required
—

Returns: ModelDownloadResult

Downloaded model structure

After downloading, the model files are organized under the run ID:

models/
└── run_abc123/
    ├── model_full/          # Full model weights
    │   ├── config.json
    │   ├── model.safetensors
    │   └── ...
    ├── adapter/             # Adapter weights (if available)
    │   ├── adapter_config.json
    │   ├── adapter_model.safetensors
    │   └── ...
    └── run_config.json      # Run configuration

Response types

Model

from vi.api.resources.models.responses import Model

Properties

Name
Type
Description
Required
Default
kind
string
Resource kind
Optional
—
run_id
string
Parent run ID
Optional
—
organization_id
string
Organization ID
Optional
—
model_id
string
Unique model identifier
Optional
—
spec
object
Model specification (ModelSpec)
Optional
—
status
object
Model status (ModelStatus)
Optional
—
metadata
object
Metadata
Optional
—
self_link
string
API link
Optional
—
etag
string
Entity tag
Optional
—

Methods: info() → prints a formatted model summary.

ModelSpec

from vi.api.resources.models.responses import ModelSpec

Properties

Name
Type
Description
Required
Default
kind
string
Model kind identifier
Optional
—
epoch
integer
Training epoch number
Optional
—
evaluation_metrics
object
Evaluation metrics (accuracy, loss, etc.)
Optional
—

ModelStatus

from vi.api.resources.models.responses import ModelStatus

Properties

Name
Type
Description
Required
Default
observed_generation
integer
Observed generation number
Optional
—
conditions
array
Status conditions
Optional
—
storage_object
string
Storage location
Optional
—
contents
object
Download info when available (ModelContents)
Optional
—

ModelContents

from vi.api.resources.models.responses import ModelContents

Properties

Name
Type
Description
Required
Default
download_url
object
Download URL info (ModelDownloadUrl)
Optional
—

ModelDownloadUrl

from vi.api.resources.models.responses import ModelDownloadUrl

Properties

Name
Type
Description
Required
Default
url
string
Pre-signed download URL
Optional
—
expires_at
integer
Expiration timestamp
Optional
—

ModelDownloadResult

Properties

Name
Type
Description
Required
Default
model_path
string
Path to model weights
Optional
—
adapter_path
string
Path to adapter weights (if available)
Optional
—
run_config_path
string
Path to run configuration
Optional
—

Related resources

Runs API

List and get the training runs that produce model checkpoints.

Vi SDK Inference

Load downloaded models and run predictions on images.

Download A Model

UI guide for downloading trained models in Datature Vi.

Evaluate A Model

Interpret training metrics and compare run results.

Updated 6 months ago

Did this page help you?