Create a Model FileSet | NVIDIA NeMo Helix

Create a FileSet containing your base model checkpoint before creating a Model Entity.

Prerequisites

Configured a CLI context that points at your NeMo Helix deployment. Refer to Connect with CLI Contexts.
For gated or private Hugging Face models: Created a secret with your HF token. Refer to Manage Secrets.

From Hugging Face Hub

The most common method is downloading directly from Hugging Face. The example below uses nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16, a public model that requires no token:

from nemo_helix_plugin.client.client import NemoClient
from nemo_helix_plugin.client.errors import ConflictError
from nemo_helix_plugin.files.storage_config import HuggingfaceStorageConfig
from nemo_helix_plugin.files.types import CreateFilesetRequest, FilesetPurpose
from nemo_helix_plugin.schema import SecretRef
client = NemoClient.from_config()
HF_REPO_ID = "nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16"
MODEL_NAME = "nemotron-3-5-lightning-30b-a3b"
# Create FileSet from Hugging Face
try:
    fileset = client.files.create_fileset(
        body=CreateFilesetRequest(
            name=MODEL_NAME,
            description="Nemotron 3.5 Lightning 30B A3B from Hugging Face",
            purpose=FilesetPurpose.MODEL,
            storage=HuggingfaceStorageConfig(
                repo_id=HF_REPO_ID,
                repo_type="model",
            ),
        )
    ).data()
    print(f"Created FileSet: {fileset.name}")
except ConflictError:
    print(f"FileSet '{MODEL_NAME}' already exists, retrieving...")
    fileset = client.files.get_fileset(name=MODEL_NAME).data()
print(f"FileSet ready: {fileset.name}")

These examples use the default workspace. If your current CLI context uses a different workspace, run nemo config set --workspace default first. To check, run nemo config view.

Gated Hugging Face repositories require a Hugging Face token. To use one:

Accept the model license on the Hugging Face model page.
Create a Hugging Face token with read access.
Store the token as a secret in the platform (see Manage Secrets), then pass it as token_secret in the storage config:

storage=HuggingfaceStorageConfig(
    repo_id="<org>/<gated-model>",
    repo_type="model",
    token_secret=SecretRef("my-hf-token"),
)

From NGC

For models from NVIDIA NGC:

import os
from nemo_helix_plugin.client.client import NemoClient
from nemo_helix_plugin.client.errors import ConflictError
from nemo_helix_plugin.files.storage_config import NGCStorageConfig
from nemo_helix_plugin.files.types import CreateFilesetRequest, FilesetPurpose
from nemo_helix_plugin.schema import SecretRef
from nemo_helix_plugin.secrets.types import HelixSecretCreateRequest
from pydantic import SecretStr
client = NemoClient.from_config()
MODEL_NAME = "nemotron-mini-4b"
NGC_TARGET = "nemotron-mini-4b-instruct"
NGC_ORG = "nvidia"
NGC_TEAM = "nemo"
NGC_VERSION = "1.0"
NGC_API_KEY_SECRET = "my-ngc-key"
NGC_API_KEY = os.environ.get("NGC_API_KEY")
if not NGC_API_KEY:
    raise RuntimeError("Set NGC_API_KEY before creating the NGC secret.")
# First, create a secret for your NGC API key (if not already created)
try:
    ngc_secret = client.secrets.create_secret(
        body=HelixSecretCreateRequest(name=NGC_API_KEY_SECRET, value=SecretStr(NGC_API_KEY)),
    ).data()
    print(f"Created secret: {NGC_API_KEY_SECRET}")
except ConflictError:
    print(f"Secret '{NGC_API_KEY_SECRET}' already exists, continuing...")
    ngc_secret = client.secrets.get_secret(name=NGC_API_KEY_SECRET).data()
# Create FileSet from NGC
try:
    fileset = client.files.create_fileset(
        body=CreateFilesetRequest(
            name=MODEL_NAME,
            description="Nemotron Mini 4B from NGC",
            purpose=FilesetPurpose.MODEL,
            storage=NGCStorageConfig(
                org=NGC_ORG,
                team=NGC_TEAM,
                target=NGC_TARGET,  # NGC asset name
                target_type="resource",
                version=NGC_VERSION,
                api_key_secret=SecretRef(ngc_secret.name),
            ),
        )
    ).data()
    print(f"Created FileSet: {fileset.name}")
except ConflictError:
    print("FileSet already exists, retrieving...")
    fileset = client.files.get_fileset(name=MODEL_NAME).data()

Check FileSet Status

Files are downloaded in the background after you create a FileSet. Check the status:

# List files in the FileSet
response = client.files.list_files(
    workspace="default",
    name="nemotron-3-5-lightning-30b-a3b",
)
files = response.data().data
print(f"Files in FileSet ({len(files)} total):")
for f in files[:10]:  # Show first 10
    print(f" - {f.path} ({f.size:,} bytes)")

Example Response

{
  "data": [
    {
      "file_ref": "/v2/workspaces/default/filesets/nemotron-3-5-lightning-30b-a3b/-/config.json",
      "path": "config.json",
      "size": 3254,
      "cache_status": null
    },
    {
      "file_ref": "/v2/workspaces/default/filesets/nemotron-3-5-lightning-30b-a3b/-/model-00001-of-00014.safetensors",
      "path": "model-00001-of-00014.safetensors",
      "size": 4900000000,
      "cache_status": null
    },
    {
      "file_ref": "/v2/workspaces/default/filesets/nemotron-3-5-lightning-30b-a3b/-/model.safetensors.index.json",
      "path": "model.safetensors.index.json",
      "size": 1500000,
      "cache_status": null
    },
    {
      "file_ref": "/v2/workspaces/default/filesets/nemotron-3-5-lightning-30b-a3b/-/tokenizer.json",
      "path": "tokenizer.json",
      "size": 17078110,
      "cache_status": null
    }
  ]
}

Next Steps

Proceed to create a Model Entity.