DAL GRAFO AL MODELLOConfigurare il server

Backend locale e job su Slurm

NNModelling può inviare una copia immutabile del progetto al servizio FastAPI locale. Il servizio, l'API e la cronologia restano su questo computer. Puoi eseguire i job in un container locale oppure inviarli a Slurm via SSH: in quel caso solo il worker gira sul cluster; snapshot, metriche, log e risultati tornano al backend locale. La finestra Training mostra collegamento, cronologia, curve e comandi per annullare, ripristinare snapshot e scaricare risultati.

Pannello di connessione al backend
Pannello di connessione al backend

Clic sull'immagine per leggere i dettagli a dimensione originale.

  1. Indirizzo del backend
  2. Connetti e verifica lo stato del servizio
  3. Apri la configurazione separata del backend
Cronologia, curve di apprendimento e risultati
Cronologia, curve di apprendimento e risultati

Clic sull'immagine per leggere i dettagli a dimensione originale.

  1. Connessione al backend
  2. Configurazione dell’addestramento
  3. Cronologia e stato delle attività
  4. Curve della perdita di addestramento e validazione
  5. Visibilità e scala delle curve
  6. Perdita finale sul test
  7. Registro dell’addestramento e del worker
  8. Azioni per scaricare, ripristinare, annullare e chiudere

Preparare e avviare il servizio

Esegui questi comandi in Bash, dalla directory principale del repository. Gli esempi con read -s e array AUTH usano la sintassi di questa shell. Servono uv, just e un runtime Docker compatibile già installato e avviato (Docker o Podman). Il primo comando installa le dipendenze bloccate del workspace; il secondo crea l'immagine CPU usata per l'addestramento.

just backend-sync
just backend-image
just backend-run

backend-run resta in primo piano. L'indirizzo predefinito è http://127.0.0.1:8765; apri un altro terminale per interrogare l'API e usa Ctrl-C per fermare il servizio. Seleziona Training nell'app e premi Connect / check health. Il campo endpoint usa già l'indirizzo predefinito.

Configurazione JSON per utente

UI e backend leggono lo stesso file: ~/.config/nnmodelling/config.json. Se XDG_CONFIG_HOME è definita, il percorso diventa $XDG_CONFIG_HOME/nnmodelling/config.json. NNMODELLING_CONFIG sceglie un file alternativo. La finestra Configure backend… mostra il percorso e salva le impostazioni non segrete prima dell'avvio del servizio. Non usa più le vecchie preferenze Qt del launcher. Nessun host, account, percorso remoto o partizione è preconfigurato.

Puoi creare il file manualmente. Questo esempio contiene segnaposto: sostituisci host, percorsi assoluti e partizione con valori della tua installazione.

{
  "backend": {
    "executor": "docker",
    "job_root": "~/.local/share/nnmodelling/jobs",
    "container_runtime": "docker",
    "worker_image": "nnmodelling-worker:local"
  },
  "slurm": {
    "host": "my-cluster",
    "root": "/srv/nnmodelling/jobs",
    "image": "/srv/nnmodelling/worker.sif",
    "partition": "my-partition",
    "cpus": 2,
    "memory": "4G",
    "time": "00:30:00",
    "gpus": 0,
    "ssh_executable": "ssh"
  }
}

Per Slurm imposta "executor": "slurm". Il backend avviato da terminale usa prima le variabili NNMODELLING_* esplicite, poi JSON, poi i valori generici. La UI passa al servizio i valori scelti nei suoi campi. Il file predefinito assente permette l'uso locale; un file alternativo esplicito mancante o un JSON invalido produce un errore. Errori di lettura o salvataggio impediscono l'avvio gestito, senza sovrascrivere il file. Il salvataggio è atomico e conserva le altre impostazioni JSON. Password, chiavi SSH e bearer token non vanno nel file; il token resta in memoria e le credenziali SSH restano nell'agent/config SSH.

just backend-image usa runtime e tag dalle variabili d'ambiente: quando cambi questi due valori nel JSON, passa gli stessi valori al comando di build.

Profilo JSON e backend Docker locale
Profilo JSON e backend Docker locale

Clic sull'immagine per leggere i dettagli a dimensione originale.

  1. Scegli l’esecutore locale
  2. Directory locale dei job, runtime dei container e immagine worker
  3. Percorso del profilo JSON portabile
  4. Stato di disponibilità del servizio locale
  5. Riavvia in sicurezza il backend locale

Eseguire i job su un cluster Slurm dalla UI

Preparare il worker dalla finestra di configurazione

Prepare and install worker… costruisce e installa l'immagine richiesta dal training usando profilo corrente. Servono workspace del repository, uv e Docker/Podman sul computer; SSH, Slurm e Singularity sul cluster. L'autenticazione usa agent/config SSH esistenti, senza raccogliere password o copiare chiavi.

La preparazione costruisce immagine dalle dipendenze uv bloccate, trasferisce archivio sul cluster, converte in SIF in una propria allocazione Slurm e verifica ambiente Python e worker. L'interfaccia mostra fasi, byte trasferiti, errori e Cancel. Nessun training parte durante preparazione. Un successo seleziona immagine verificata con nome basato sul suo hash; errore o annullamento conserva immagine precedente. Check worker controlla la SIF selezionata. Dopo successo avvia o riavvia backend con il comando abituale, quando non ci sono job attivi.

L'ambiente Python dell'immagine è in /opt/nnmodelling/venv, separato dal mount dei sorgenti. La ricetta standard ha PyTorch CPU: configurare GPU non trasforma quell'ambiente in CUDA; preparazione GPU richiede dipendenze CUDA bloccate compatibili e viene rifiutata se il worker è CPU-only. Il training resta senza rete; download e installazione dipendenze avvengono prima.

Usare un pacchetto Python senza installare la wheel

Per nuovi job completati, Download Python package scarica ZIP con la stessa cartella pubblica contenuta nella wheel. Estrai accanto allo script: per progetto tiny-decoder-llm ottieni cartella nnm_tiny_decoder_llm, quindi:

from nnm_tiny_decoder_llm import Model

model = Model()
prediction = model.infer("ROMEO:\n")

Python deve già avere torch, NumPy, safetensors e dipendenze dichiarate dalle risorse. Copiare soltanto file .whl non equivale a installarlo. ZIP include pesi, adapter e runtime privato; non include dati di training. I vecchi job che non possiedono ZIP conservano download wheel/pesi originali.

Il servizio FastAPI, il dashboard Training e l'archivio dei job restano su questo computer. La finestra Local backend service configuration sceglie Slurm come esecutore; solo i worker vengono inviati al cluster via SSH. Prima prepara una directory remota scrivibile e un'immagine Singularity (.sif) con Python, PyTorch, NumPy, safetensors e tutte le dipendenze dichiarate da dataset e pacchetti. Il cluster deve offrire sbatch, squeue, sacct, scancel, singularity e python3 via SSH. I job non accedono alla rete. Usa un alias SSH già configurato sul computer, con autenticazione e verifica delle chiavi host.

1. Prepara immagine e directory remota

Sostituisci alias e percorsi di esempio con valori validi per il tuo account. Crea la directory una volta:

ssh my-cluster 'mkdir -p /srv/nnmodelling/jobs && chmod 700 /srv/nnmodelling/jobs'

L'immagine deve già contenere ogni dipendenza Python richiesta dal progetto: durante il job non vengono installati pacchetti. La directory locale dei job conterrà snapshot, metriche, log e artefatti; quella sul cluster contiene solo file temporanei di esecuzione per singolo job.

2. Apri configurazione backend e scegli Slurm

Nel dashboard Training, premi Configure backend…. Si apre una finestra separata: il dashboard con endpoint, controlli di training, cronologia e curve resta disponibile. Imposta Executor su SSH / Slurm e compila alias SSH, directory locale, directory remota, immagine .sif, partizione, CPU, memoria e limite di tempo e GPU. Host, directory remota, immagine e partizione sono obbligatori e inizialmente vuoti. I valori generici sono 2 CPU, 4G, 00:30:00 e 0 GPU; usa i limiti assegnati dal tuo account. Time limit è il limite di ogni singola allocazione Slurm, non la durata massima del training.

Configurare esecutore, percorsi e risorse Slurm
Configurare esecutore, percorsi e risorse Slurm

Clic sull'immagine per leggere i dettagli a dimensione originale.

  1. Selezione dell’esecutore
  2. Alias SSH, directory remota, immagine SIF e partizione
  3. CPU, memoria, limite di tempo e numero di GPU
  4. Eseguibile SSH
  5. Percorso del profilo JSON portabile
  6. Errore visibile di configurazione mancante
  7. Riavvia in sicurezza il backend locale

3. Avvia FastAPI in locale

Nella finestra di configurazione premi Save settings and start local backend. Lo screenshot mostra i campi remoti ancora vuoti: il tentativo di avvio è respinto prima di qualsiasi connessione al cluster. Quando un servizio gestito è attivo, il pulsante propone un riavvio sicuro. Viene avviato solo il servizio locale su loopback. L'app sceglie una porta libera e aggiorna automaticamente Endpoint nel dashboard. La riga di stato verifica avvio e disponibilità di Singularity; errori SSH, immagine o prerequisiti appaiono qui. Le preferenze non segrete vengono salvate per l'utente. Password SSH non vengono richieste o copiate.

4. Connetti dashboard e invia job

Torna al dashboard Training: Endpoint contiene già l'indirizzo loopback scelto dal servizio. Premi Connect / check health se vuoi aggiornare la verifica. Invia progetto e parametri come per il runtime locale: non servono flag Slurm nel progetto e la configurazione del modello non cambia. Snapshot e risultati restano locali; solo il worker viene eseguito dal cluster.

Quando un'allocazione si avvicina al limite, il worker salva automaticamente un checkpoint sicuro e invia un nuovo job Slurm che riparte da quel punto. La UI continua a mostrare un solo job e le sue metriche; gli ID Slurm delle singole allocazioni cambiano. Il servizio backend locale deve restare attivo durante questi passaggi. Se il cluster termina il job prima del segnale di preavviso o prima che il checkpoint sia completo, il job viene mostrato come fallito e non può riprendere automaticamente. Gli iteratori di training personalizzati devono poter essere ricreati in modo ripetibile per permettere il ripristino del punto salvato.

Controlli Training attuali
Controlli Training attuali

Clic sull'immagine per leggere i dettagli a dimensione originale.

  1. Indirizzo del backend e stato della connessione
  2. Basic training settings
  3. Dispositivo, precisione e ottimizzatore
  4. Controlli dell’arresto anticipato

I tutorial LLM e VAE seguono lo stesso percorso. Se manca una dipendenza nella .sif, il job fallisce in modo visibile: ricostruisci l'immagine prima di riprovare. Per tornare all'esecuzione Docker locale, apri Configure backend…, seleziona Docker-compatible runtime e avvia il servizio.

L'esportatore wheel è incluso nell'immagine worker. Dopo aver aggiornato il repository per usare i nomi leggibili, ricostruisci l'immagine worker e riavvia il backend gestito prima di inviare altri job. La ricostruzione non modifica wheel già archiviate: restano scaricabili con nome e contenuto originali. Non rinominarle manualmente.

Esempio: porta 8766 e archivio dedicato

Per tenere questa istanza separata, imposta un archivio locale dedicato e usa la stessa configurazione nel terminale del servizio:

export NNMODELLING_BACKEND_HOST=127.0.0.1
export NNMODELLING_BACKEND_PORT=8766
export NNMODELLING_JOB_ROOT="$HOME/.local/share/nnmodelling/jobs-8766"
export NNMODELLING_CONTAINER_RUNTIME=docker
export NNMODELLING_WORKER_IMAGE=nnmodelling-worker:local
just backend-image
just backend-run

In un secondo terminale verifica il servizio con:

curl -fsS http://127.0.0.1:8766/health

Nell'app apri Training, sostituisci l'endpoint con http://127.0.0.1:8766 e premi Connect / check health. Usa ~/.local/share/nnmodelling/jobs-8766 per trovare snapshot, log e artifact di questa istanza. Per arrestarla premi Ctrl-C nel primo terminale.

Per usare Podman oppure un'immagine con dipendenze aggiuntive, usa lo stesso nome di runtime e immagine sia durante la creazione sia durante l'avvio:

NNMODELLING_CONTAINER_RUNTIME=podman just backend-image
NNMODELLING_CONTAINER_RUNTIME=podman just backend-run

NNMODELLING_WORKER_IMAGE cambia il tag dell'immagine (predefinito nnmodelling-worker:local). I container di addestramento non hanno accesso alla rete: installa le dipendenze Python dichiarate dalle risorse nell'immagine prima di inviare il job.

Se una risorsa richiede scikit-image, puoi preparare un'immagine aggiuntiva con una versione fissata. Salva questo testo come Dockerfile.worker-extra nella root del repository:

FROM nnmodelling-worker:local
USER 0
RUN uv pip install --python /opt/nnmodelling/venv/bin/python 'scikit-image==0.25.2'
USER 65532:65532

Costruisci prima l'immagine base con il tag da cui eredita il Dockerfile, costruisci poi l'estensione e selezionala per l'avvio del servizio:

export NNMODELLING_WORKER_IMAGE=nnmodelling-worker:local
just backend-image
docker build -f Dockerfile.worker-extra -t nnmodelling-worker:scikit-image .
export NNMODELLING_WORKER_IMAGE=nnmodelling-worker:scikit-image
just backend-run

Se usi Podman, sostituisci docker build con podman build e imposta NNMODELLING_CONTAINER_RUNTIME=podman prima di costruire la base e avviare il servizio. Mantieni le dipendenze dichiarate dalle risorse fissate nell'immagine e ricostruiscila quando cambiano.

Token facoltativo

Per una sessione locale a utente singolo il token è facoltativo. Per richiederlo, impostalo prima di avviare il servizio e inserisci lo stesso valore nel campo Bearer token della finestra Training. L'input della shell qui sotto non mostra il token mentre lo digiti:

read -r -s -p 'Token bearer: ' NNMODELLING_BEARER_TOKEN
printf '\n'
export NNMODELLING_BEARER_TOKEN
just backend-run

Il servizio mantiene il token solo in memoria. Il client Qt lo mantiene solo nella finestra corrente e non lo salva nel progetto o nello snapshot. Le richieste a /v1/jobs richiedono Authorization: Bearer … quando il token è configurato; /health restituisce solo lo stato del servizio e del runtime. Il servizio è destinato all'uso locale: mantieni l'indirizzo di ascolto su loopback, soprattutto quando non configuri un token.

Controllare il servizio

GET /health non richiede autenticazione. status: "ok" indica che l'API risponde; per addestrare, anche container.available deve essere true. runtime indica il comando Docker compatibile configurato e error contiene null oppure il motivo per cui il runtime non è disponibile.

curl -fsS http://127.0.0.1:8765/health

Esempio di risposta con runtime Docker:

{"status":"ok","container":{"available":true,"runtime":"docker","error":null}}

Con Slurm, il blocco container riporta anche "executor":"slurm" e "runtime":"singularity".

La documentazione OpenAPI è disponibile da http://127.0.0.1:8765/docs.

Inviare un progetto

Salva il progetto nell'app prima dell'invio. Nella finestra Training imposta epoche, batch, learning rate, seed e Publish every N steps, poi premi Save project and submit. I valori iniziali sono rispettivamente 10, 32, 0.001, 0 e 10. La cadenza determina ogni quanti aggiornamenti dell'ottimizzatore vengono pubblicate metriche abbinate di training e validazione; a ogni fine epoca viene pubblicata anche l'eventuale finestra residua.

L'API accetta questi intervalli: epoche 1–10000, batch 1–4096, learning rate finito maggiore di 0 e minore o uguale a 1, seed da -2147483648 a 4294967295, cadenza 1–100000. I campi JSON non previsti dal protocollo vengono rifiutati; le opzioni avanzate elencate nella guida client sono supportate. Il job registra la configurazione usata e lo snapshot dei file: le modifiche successive al progetto non cambiano un job già inviato.

Per un invio riproducibile dal terminale, questo esempio usa solo la libreria standard di Python. Dalla root del repository crea in memoria il bundle del progetto examples/models/tiny-decoder-llm, poi invia una configurazione breve da un'epoca. Il contenuto, l'ordine dei file e i parametri sono fissi; lo script non crea file intermedi. Esclude link simbolici, directory env, .env, venv, .venv, cache e bytecode, oltre alle cartelle generate usate dall'app. Include anche gli asset d'inferenza elencati nei manifest delle risorse.

python3 - <<'PY'
import base64
import hashlib
import json
import os
from pathlib import Path, PurePosixPath
from urllib.request import Request, urlopen

base_url = os.environ.get("NNMODELLING_BACKEND_URL", "http://127.0.0.1:8765").rstrip("/")
root = Path.cwd() / "examples/models/tiny-decoder-llm"
if not root.is_dir() or root.is_symlink():
    raise FileNotFoundError(f"Example project directory does not exist: {root}")
model_bytes = (root / "model.json").read_bytes()
model = json.loads(model_bytes)
compiled_path = root / "execution-model.json"
if compiled_path.is_symlink():
    raise ValueError("Compiled example must not be a symlink")
compiled = json.loads(compiled_path.read_bytes())
if compiled["source_sha256"] != hashlib.sha256(model_bytes).hexdigest():
    raise ValueError("Example compilation is stale; submit edited models through Qt")
excluded = {
    ".venv", "venv", "env", ".env", "__pycache__", ".git", "build", "dist",
    "target", ".pytest_cache", ".nnmodelling-generated", "node_modules",
}
files = {}

def safe_relative(value):
    if not isinstance(value, str) or not value or "\\" in value or "\x00" in value:
        raise ValueError(f"Unsafe project-relative path: {value!r}")
    parts = value.split("/")
    if (PurePosixPath(value).is_absolute() or ":" in parts[0]
            or any(part in {"", ".", ".."} for part in parts)
            or value == "model.json"):
        raise ValueError(f"Unsafe project-relative path: {value!r}")
    return Path(*parts)

def excluded_path(relative):
    return (
        any(part in excluded for part in relative.parts)
        or relative.name == ".DS_Store"
        or relative.suffix in {".pyc", ".pyo"}
        or relative.name.endswith("~")
        or ".generated." in relative.name
    )

def add_tree(value, required=False):
    relative = safe_relative(value.as_posix() if isinstance(value, Path) else value)
    if excluded_path(relative):
        if required:
            raise ValueError(f"Required project resource is in an excluded directory: {relative}")
        return
    source = root / relative
    cursor = root
    for part in relative.parts:
        if part in {".", ".."}:
            raise ValueError(f"Unsafe project-relative path: {relative}")
        cursor = cursor / part
        if cursor.is_symlink():
            if required:
                raise ValueError(f"Required project resource uses a symlink: {relative}")
            return
    if source.is_symlink():
        if required:
            raise ValueError(f"Required project resource uses a symlink: {relative}")
        return
    if source.is_file():
        name = relative.as_posix()
        if name not in files:
            files[name] = base64.b64encode(source.read_bytes()).decode("ascii")
    elif source.is_dir():
        for child in sorted(source.iterdir(), key=lambda path: path.name):
            if not child.is_symlink():
                add_tree((relative / child.name).as_posix())
    elif required:
        raise FileNotFoundError(f"Project resource does not exist: {relative}")

for group in ("customPackages", "customDatasets"):
    for resource in model["manifest"].get(group, []):
        add_tree(resource["path"], required=True)
for folder in ("data", "resources"):
    add_tree(folder)

# A resource may declare inference assets outside the conventional directories.
for name, encoded in list(files.items()):
    if name.endswith("/manifest.json"):
        manifest = json.loads(base64.b64decode(encoded))
        for asset in manifest.get("inferenceAssets", []):
            add_tree(asset, required=True)

payload = {
    "project": model,
    "execution_project": compiled["execution_project"],
    "files": files,
    "training": {
        "epochs": 1,
        "batch_size": 8,
        "learning_rate": 0.001,
        "seed": 0,
        "publish_every_steps": 2,
    },
}
headers = {"Content-Type": "application/json", "Accept": "application/json"}
token = os.environ.get("NNMODELLING_BEARER_TOKEN")
if token:
    headers["Authorization"] = "Bearer " + token
request = Request(
    base_url + "/v1/jobs",
    data=json.dumps(payload, separators=(",", ":")).encode("utf-8"),
    headers=headers,
    method="POST",
)
with urlopen(request, timeout=30) as response:
    job = json.load(response)
    print("HTTP", response.status, "job", job["id"], "status", job["status"])
    print("Bundle files:", len(files))
PY

La risposta 202 contiene id, status (queued all'invio), created_at, error e metrics. Copia l'ID restituito per i comandi successivi:

JOB_ID='incolla-qui-l-id-restituito'

Seguire, annullare e recuperare un job

La cronologia nell'app si aggiorna automaticamente. Da terminale puoi elencare i job e leggere quello selezionato. Se hai configurato un token, il terminale che esegue le richieste è separato da quello del servizio: immettilo anche lì, senza mostrarlo, quindi prepara l'header:

read -r -s -p 'Token bearer: ' NNMODELLING_BEARER_TOKEN
printf '\n'
export NNMODELLING_BEARER_TOKEN

Poi, nello stesso terminale, prepara l'header da riusare nei comandi seguenti:

AUTH=()
if [[ -n "${NNMODELLING_BEARER_TOKEN:-}" ]]; then
  AUTH=(-H "Authorization: Bearer $NNMODELLING_BEARER_TOKEN")
fi

Se non hai configurato un token sul servizio, salta la richiesta nascosta e inizializza solo AUTH=(); le richieste locali sono anonime.

curl -fsS "${AUTH[@]}" http://127.0.0.1:8765/v1/jobs
curl -fsS "${AUTH[@]}" "http://127.0.0.1:8765/v1/jobs/$JOB_ID"

Lo stato può essere queued, running, completed, failed o cancelled. metrics.epochs contiene i riepiloghi per epoca; metrics.steps contiene i punti pubblicati per passo, con numero di passo, epoca e loss di training e validazione. metrics.test_loss resta null finché la valutazione finale non è disponibile. error riporta il problema per un job fallito.

Annullare un job è un'azione sul job e non ferma l'API:

curl -fsS "${AUTH[@]}" -X POST -H 'Content-Type: application/json' -d '{}' \
  "http://127.0.0.1:8765/v1/jobs/$JOB_ID/cancel"

Un job in coda passa subito a cancelled; per un job in esecuzione la risposta può mostrare ancora running mentre il container si arresta. Aggiorna il job per leggere lo stato finale. Ripetere la richiesta per un job già cancelled è idempotente; i job completati o falliti rispondono 409 e non possono essere annullati.

Ctrl-C nel terminale di just backend-run ferma il servizio API e avvia lo spegnimento dei container gestiti; non invia la richiesta di annullamento del singolo job. Se l'API si riavvia mentre un job risulta ancora running, quel job viene registrato come failed con un errore di interruzione. I job in coda vengono recuperati dal servizio.

Lo snapshot restituisce il modello e i file originali del job, con i file codificati in Base64. Puoi salvarlo per ispezionarlo o ripristinarlo dall'app:

curl -fsS "${AUTH[@]}" "http://127.0.0.1:8765/v1/jobs/$JOB_ID/snapshot" -o snapshot.json

Scaricare i risultati

Pesi e wheel standalone sono disponibili solo quando lo stato è completed:

curl -fS "${AUTH[@]}" "http://127.0.0.1:8765/v1/jobs/$JOB_ID/weights" -o weights.safetensors
mkdir -p artifacts
curl -fS --remote-name --remote-header-name --output-dir artifacts \
  "${AUTH[@]}" "http://127.0.0.1:8765/v1/jobs/$JOB_ID/wheel"

L'app offre gli stessi comandi Download weights e Download wheel. Per i nuovi job, il nome della distribuzione è nnm_<id-progetto-normalizzato>; ad esempio, ID llm produce nnm_llm-0.1.0-py3-none-any.whl. Per normalizzare, sequenze diverse da lettere e cifre ASCII diventano _, gli underscore iniziali e finali sono rimossi e il risultato è minuscolo. Il client Qt conserva il nome completo inviato dal server, che include distribuzione, versione e tag. Il modulo Python delle nuove wheel è nnm_<id-progetto-normalizzato>: per ID llm, usa from nnm_llm import Model. Un alias specifico del job resta disponibile per compatibilità. Per wheel storiche, leggi il modulo al loro interno. Job generati dallo stesso progetto, o da progetti con lo stesso ID normalizzato, condividono distribuzione e versione: installali in ambienti Python separati. Le wheel archiviate prima della modifica mantengono nome e contenuto originali; non rinominarle manualmente. La wheel include il modello, l'adapter necessario all'inferenza e i pesi; non richiede il servizio né il progetto sorgente per eseguire l'inferenza, ma richiede Python, PyTorch, safetensors e le dipendenze dichiarate dalla risorsa.

Configurazione

Le variabili seguenti si impostano prima di avviare just backend-run.

Variabile Predefinito Funzione e limiti effettivi
NNMODELLING_CONFIG percorso XDG o ~/.config/nnmodelling/config.json File JSON condiviso; un percorso esplicito mancante produce errore.
NNMODELLING_EXECUTOR docker docker oppure slurm; sovrascrive backend.executor.
NNMODELLING_SLURM_HOST, NNMODELLING_SLURM_ROOT, NNMODELLING_SLURM_IMAGE, NNMODELLING_SLURM_PARTITION vuoti Alias SSH, root remota, SIF e partizione: obbligatori per Slurm.
NNMODELLING_SLURM_CPUS, NNMODELLING_SLURM_MEMORY, NNMODELLING_SLURM_TIME, NNMODELLING_SLURM_GPUS 2, 4G, 00:30:00, 0 Risorse per allocazione; GPU da 0 a 8.
NNMODELLING_SSH_EXECUTABLE ssh Comando SSH usato dal servizio.
NNMODELLING_MAX_ARTIFACT_BYTES 64 GiB Limite configurabile degli artifact, separato da bundle e corpus.
NNMODELLING_BACKEND_HOST 127.0.0.1 Indirizzo di bind passato a Uvicorn. Mantienilo su loopback per uso locale.
NNMODELLING_BACKEND_PORT 8765 Porta passata a Uvicorn.
NNMODELLING_JOB_ROOT ~/.local/share/nnmodelling/jobs Directory persistente di job, snapshot, log e risultati.
NNMODELLING_BEARER_TOKEN non impostato Se presente, protegge le rotte /v1/jobs. Il token non viene scritto nei record dei job.
NNMODELLING_CONTAINER_RUNTIME docker Nome o percorso dell'eseguibile compatibile Docker; deve essere sul PATH.
NNMODELLING_WORKER_IMAGE nnmodelling-worker:local Immagine usata per just backend-image e per i job; i due tag devono coincidere.
NNMODELLING_CORE_ROOT stereotype-packages/core nella root del repository Directory dei pacchetti core; in genere non serve modificarla.
NNMODELLING_MAX_BUNDLE_BYTES 46 MiB Limite totale dei byte decodificati dei file inviati.
NNMODELLING_MAX_PROJECT_BYTES 8 MiB Limite del JSON del modello.
NNMODELLING_MAX_FILES 10000 Numero massimo di file nel bundle.
NNMODELLING_MAX_FILE_BYTES 128 MiB Dimensione massima di un singolo file.

I limiti del bundle MAX_* sono convertiti da stringa a intero all'avvio; il servizio non applica un ulteriore intervallo o valore minimo a queste impostazioni. I valori standard sono allineati ai controlli dell'API; il client Qt applica inoltre un massimo complessivo di 256 MiB ai file locali prima della codifica Base64. Il limite predefinito del server per i file decodificati è 46 MiB e quindi può rifiutare bundle più grandi anche se il client li ha accettati. Le metriche serializzate hanno un limite fisso di 64 MiB.

Il worker usa un container senza rete, con mount dello snapshot in sola lettura, output separato in scrittura, due CPU e memoria limitata a 4 GiB. Il log di worker del job si trova in <NNMODELLING_JOB_ROOT>/<id>/output/worker.log.

Problemi comuni