> This page is for version 0.8.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.8.0: https://docs.nvidia.com/nemo-helix/v0.8.0/llms.txt
> - 0.7.1: https://docs.nvidia.com/nemo-helix/v0.7.1/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo-helix/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo-helix/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo-helix/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo-helix/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo-helix/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo-helix/v0.3.0/llms.txt
> - 0.2.0: https://docs.nvidia.com/nemo-helix/v0.2.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server.

# Create a Model Entity

Create a Model Entity that references your FileSet to enable customization jobs.

## Prerequisites

* Created a FileSet containing your model checkpoint (refer to [Create a Model FileSet](/documentation/customizer-reference/manage-model-entities/create-a-model-file-set)).
* Configured a CLI context that points at your NeMo Helix deployment. Refer to [Connect with CLI Contexts](/documentation/reference/cli-reference/connect-to-deployments).

---

## Create the Model Entity

```python
from nemo_helix_plugin.client.client import NemoClient
from nemo_helix_plugin.client.errors import ConflictError
from nemo_helix_plugin.models.types import CreateModelEntityRequest
from nemo_customizer.sdk import Customization

client = NemoClient.from_config()
customization = Customization.from_client(client)

try:
    model = client.models.create_model(
        body=CreateModelEntityRequest(
            name="nemotron-3-5-lightning-30b-a3b",
            fileset="default/nemotron-3-5-lightning-30b-a3b",  # Reference: workspace/fileset-name
            description="Nemotron 3.5 Lightning 30B A3B base model for customization",
        ),
    ).data()
    print(f"Created Model Entity: {model.name}")
except ConflictError:
    print("Model Entity already exists")
    model = client.models.get_model(name="nemotron-3-5-lightning-30b-a3b").data()
```

> **Note**
>
> 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`.

#### Example Response

```json
{
  "id": "model-abc123def456",
  "name": "nemotron-3-5-lightning-30b-a3b",
  "workspace": "default",
  "description": "Nemotron 3.5 Lightning 30B A3B base model for customization",
  "fileset": "default/nemotron-3-5-lightning-30b-a3b",
  "spec": null,
  "adapters": [],
  "created_at": "2026-02-09T10:30:00Z",
  "updated_at": "2026-02-09T10:30:00Z"
}
```

Note: `spec` is initially `null` and will be auto-populated by the Models Controller.

---

## Wait for Model Spec Auto-Population

The platform's **Models Controller** automatically analyzes your model files and populates the `spec` field with metadata like architecture, parameter count, and layer information. This is required before running customization jobs.

```python
import time

# Poll until spec is populated
print("Waiting for model spec to be auto-populated...")
while True:
    model = client.models.get_model(name="nemotron-3-5-lightning-30b-a3b").data()
    if model.spec:
        break
    print(" Still waiting...")
    time.sleep(5)

print(f"\nModel ready for customization!")
print(f" Family: {model.spec.family}")
print(f" Parameters: {model.spec.base_num_parameters:,}")
print(f" Hidden Size: {model.spec.hidden_size}")
print(f" Layers: {model.spec.num_layers}")
print(f" Attention Heads: {model.spec.num_attention_heads}")
```

#### Example Model Spec

```json
{
  "spec": {
    "family": "nemotron_h",
    "base_num_parameters": 31577937344,
    "hidden_size": 2688,
    "num_layers": 52,
    "num_attention_heads": 32,
    "num_kv_heads": 2,
    "vocab_size": 131072,
    "context_size": 262144
  }
}
```

---

## Verify the Model Entity

Before using in a customization job, verify everything is set up correctly:

```python
model = client.models.get_model(name="nemotron-3-5-lightning-30b-a3b").data()

# Verification checks
assert model.spec is not None, "Model spec not yet populated - wait longer"
assert model.fileset, "FileSet reference missing"

print("Model Entity is ready for customization.")
print(f"\nUse in customization jobs as:")
print(f' model: "{model.workspace}/{model.name}"')
```

---

## Using the Model Entity in Customization Jobs

After your Model Entity is ready (has a populated `spec`), reference it in a customization job. Jobs are submitted to a backend (`automodel` shown here; `unsloth` is also available):

```python
from nemo_automodel_plugin.schema import AutomodelJobInput

# Create a customization job using the Model Entity
spec = AutomodelJobInput(
    model="default/nemotron-3-5-lightning-30b-a3b",  # Created above
    dataset={"training": "default/my-training-dataset"},
    training={
        "training_type": "sft",
        "finetuning_type": "lora",
        "lora": {"rank": 16, "alpha": 32, "exclude_modules": ["*.out_proj"]},
    },
    schedule={"epochs": 1},
    parallelism={"num_gpus_per_node": 4, "expert_parallel_size": 4},
)
job = customization.automodel.jobs.create(spec=spec, workspace="default", name="my-lora-job")
```

Refer to [create-job](/documentation/customizer-reference/manage-customization-jobs/create-a-customization-job) for complete job creation details.

---

## Post-Training Output

After a customization job completes, the output depends on the fine-tuning regime (`training.finetuning_type`):

* **LoRA training** (`finetuning_type: "lora"`): An **adapter** is attached to this Model Entity. The adapter contains only the trained LoRA weights.
* **Full-weight training** (`finetuning_type: "all_weights"`): A **new Model Entity** is created containing the complete fine-tuned model weights. This new entity has a `base_model` field linking back to the original.

For LoRA jobs, you can list adapters attached to a model:

```python
model = client.models.get_model(name="nemotron-3-5-lightning-30b-a3b").data()

if model.adapters:
    print(f"Adapters attached to {model.name}:")
    for adapter in model.adapters:
        print(f" - {adapter.name} (enabled: {adapter.enabled})")
else:
    print("No adapters attached yet")
```

---

## Next Steps

* [Create a customization job](/documentation/customizer-reference/manage-customization-jobs/create-a-customization-job)
* [Understand hyperparameters](/documentation/customizer-reference/manage-customization-jobs/training-configuration)