Modèles au lancement

Choisissez un modèle au lancement d’une machine Node Lodge Secure. La session est prête dès que la machine l’est, et le modèle se télécharge en arrière-plan. Utilisez la machine pendant le téléchargement. La session est facturée dès qu’elle est prête, téléchargement compris.

Choisir un modèle

Dans Launch, choisissez une machine Node Lodge Secure. À l’étape Environment, saisissez le modèle dans Model (optional) :

• Utilisez le nom tel que Hugging Face l’affiche : org/name, par exemple Qwen/Qwen3-8B, pour les poids safetensors.
• Ajoutez :VERSION pour un seul fichier GGUF du dépôt : org/name:VERSION, par exemple unsloth/Qwen3-8B-GGUF:Q4_K_M. Voir Versions GGUF.
• Acceptez la licence du modèle. Le lancement transmet votre acceptation.
• Cochez Serve with pour obtenir un point d’accès compatible OpenAI sur le modèle. Voir Servir le modèle.
• Laissez le champ vide pour lancer sans modèle.

Avec l’API, envoyez model (id et licenseAccepted: true) dans POST /v1/sessions. Avec le SDK Python, passez model="Qwen/Qwen3-8B" à sessions.launch. Avec le SDK TypeScript, passez model: { id, licenseAccepted: true }. En ligne de commande, ajoutez --model <org/name[:VERSION]> --accept-license à nodelodge launch. Voir Référence de l’API et CLI et SDK.

POST /v1/models/lookup vérifie un modèle avant le lancement : sa révision, sa taille, la durée de son téléchargement et, pour une version GGUF, son format et son file.

Versions GGUF

Un dépôt GGUF contient un fichier par version (quantification), par exemple Qwen3-8B-Q4_K_M.gguf et Qwen3-8B-Q8_0.gguf. Écrivez la version après le nom, org/name:VERSION, et la machine télécharge ce seul fichier :

• La version se compare à la fin du nom de fichier, après un - ou un ., sans tenir compte des majuscules : Q4_K_M désigne Qwen3-8B-Q4_K_M.gguf.
• Quand plusieurs fichiers finissent ainsi, comme Q4_K_M et UD-Q4_K_M, le nom le plus court l’emporte. Écrivez UD-Q4_K_M pour l’autre.
• Un fichier découpé en parties, comme -00001-of-00002.gguf, se télécharge avec toutes ses parties.
• Chaque fichier est téléchargé en parallèle et vérifié par sa somme SHA-256.

Un lancement avec une version absente du dépôt est refusé avant tout démarrage, avec les versions que le dépôt contient :

This repository has no Q3_K_S version. Versions in this repository: Q4_K_M, Q6_K, Q8_0.

Un dépôt sans fichier GGUF est refusé de la même façon :

This repository has no GGUF files. Enter it without :Q4_K_M to download its safetensors weights.

La taille et la durée de téléchargement estimées, la vérification du budget et la place disque portent sur ce seul fichier.

Budget et durée du téléchargement

Le formulaire de lancement affiche la durée estimée du téléchargement du modèle. Un lancement est refusé quand votre budget ou votre durée maximale ne couvre pas l’estimation avec une marge. Le message indique ce qu’il faut augmenter, avec le montant qui couvre l’estimation au tarif de la machine. Par exemple, pour Qwen/Qwen3-32B :

Your budget covers about 20 minutes. Downloading Qwen/Qwen3-32B and starting the machine takes about 29 minutes. Raise the budget to at least US$X.XX, or launch without a model.

La durée réelle dépend de la charge du réseau. Une fois la session en marche, sa page affiche le temps restant, mesuré sur le téléchargement lui-même.

Votre jeton Hugging Face

Enregistrez une fois un jeton de lecture Hugging Face. Node Lodge s’en sert pour rechercher et résoudre chaque modèle que vous lancez, modèles publics compris. Un modèle à accès restreint ou privé en a besoin.

1. Dans la console, ouvrez Settings, puis Integrations.
2. Collez un jeton de lecture sous Hugging Face et choisissez Save token. Hugging Face doit l’accepter. Avec l’authentification à deux facteurs activée, saisissez un code récent ; sinon, saisissez votre mot de passe dans Account password.
3. Vous recevez un courriel chaque fois qu’un jeton est enregistré, remplacé ou supprimé.

• Un jeton de lecture suffit.
• Pour un modèle à accès restreint, acceptez d’abord sa licence sur Hugging Face avec le compte du jeton.
• Le jeton est stocké chiffré et n’est plus jamais affiché : la page montre ses 4 derniers caractères et sa date d’enregistrement. Replace et Remove sont sur la même page. Les sessions déjà démarrées conservent le leur.
• Il n’apparaît pas dans les détails de votre session.

Pour un modèle à accès restreint ou privé, le jeton est posé sur la machine : dans $HF_HOME/token, lisible par le seul utilisateur ubuntu, et défini comme HF_TOKEN dans chaque shell de connexion. hf, vLLM et transformers le trouvent sans hf auth login. Une machine lancée avec un modèle public ne reçoit pas de jeton.

Pour envoyer des fichiers vers le Hub depuis vos machines, activez Also put my token on every machine I launch (for uploads to the Hub) dans Integrations. L’option est désactivée par défaut. Chaque machine lancée avec un modèle reçoit alors le jeton, et toute personne qui peut ouvrir ces machines peut le lire. L’activer demande un code à deux facteurs récent, ou votre mot de passe sans double authentification. On machines affiche le réglage : Gated and private models only ou Every machine you launch with a model. Avec l’API, envoyez shareOnMachines dans PUT /v1/integrations/hugging-face, ou { "shareOnMachines": true } dans PATCH /v1/integrations/hugging-face.

Pour utiliser un autre jeton le temps d’un lancement, envoyez-le dans modelToken avec POST /v1/sessions. Avec le SDK Python, passez model_token à sessions.launch ; avec le SDK TypeScript, passez modelToken. Il remplace le jeton enregistré pour ce lancement seulement, et il est posé sur la machine quel que soit le modèle. Sans jeton enregistré, le formulaire de lancement en demande un sous Hugging Face token (gated and private models), pour ce lancement. POST /v1/models/lookup accepte un token de la même façon ; les recherches avec un token sont limitées à 10 par minute et par organisation.

Avec une clé API (CLI, SDK, serveur MCP, action GitHub), un lancement utilise votre jeton enregistré seulement si la clé a été créée avec Launches use my saved Hugging Face token coché, dans API keys. Quiconque détient une telle clé peut lire le jeton sur les machines qu’elle lance. Avec une autre clé, envoyez le jeton avec le lancement (modelToken) ou créez une clé avec la case cochée.

Ce qui est chargé

Pour org/name : les poids au format safetensors, avec les fichiers qui les accompagnent : configuration, tokenizer et licence. Les autres formats du même modèle, comme GGUF ou ONNX, sont laissés de côté. Un modèle publié sans poids safetensors est refusé au lancement : choisissez une version GGUF avec org/name:VERSION quand le dépôt en propose.

Pour org/name:VERSION : le seul fichier GGUF de cette version, ou toutes ses parties.

La révision chargée est figée au lancement : un modèle mis à jour plus tard sur Hugging Face ne change pas sous votre session. La page de la session affiche le modèle et son emplacement sur la machine.

Où sont les fichiers

Sur la machine, le modèle se trouve dans le cache Hugging Face :

• /data/huggingface quand la machine a un disque de données,
• ~/.cache/huggingface sinon.

HF_HOME est défini pour tous les utilisateurs et tous les shells dès la première connexion : les outils trouvent le cache sans réglage. La ligne Model de la page de session affiche le chemin complet, avec un bouton de copie.

Pour des poids safetensors, le model.localPath de la session est le dossier du snapshot du modèle. Chargez-le par son nom. Rien n’est téléchargé de nouveau :

vllm serve Qwen/Qwen3-8B

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")

Exécuter un fichier GGUF

Pour une version GGUF, model.localPath est le fichier GGUF lui-même, par exemple :

/data/huggingface/hub/models--unsloth--Qwen3-8B-GGUF/snapshots/<revision>/Qwen3-8B-Q4_K_M.gguf

model.format vaut gguf et model.id vaut unsloth/Qwen3-8B-GGUF:Q4_K_M. Copiez le chemin depuis la ligne Model de la page de session dans MODEL_PATH, puis donnez-le à llama.cpp :

nodelodge-model wait && llama-server -m "$MODEL_PATH" --host 127.0.0.1 --port 8080

Ou à Ollama, avec un Modelfile d’une seule ligne, FROM suivi du chemin :

echo "FROM $MODEL_PATH" > Modelfile
ollama create qwen3-8b -f Modelfile

Pour un fichier découpé en parties, le chemin désigne la première partie. llama.cpp charge les autres depuis le même dossier.

Servir le modèle

Cochez Serve with sous le modèle : un serveur démarre sur le modèle une fois téléchargé, derrière un point d’accès compatible OpenAI doté de sa propre clé.

• vLLM pour org/name (poids safetensors). Les requêtes nomment le modèle org/name, par exemple Qwen/Qwen3-8B.
• Ollama pour org/name:VERSION (un fichier GGUF). Le fichier est importé sous un nom court, par exemple qwen3-8b:q4_k_m pour unsloth/Qwen3-8B-GGUF:Q4_K_M. Ollama prend un fichier GGUF en une seule partie : une version découpée en parties est refusée au lancement.

Avec l’API, envoyez serveWith (vllm ou ollama) dans POST /v1/sessions, avec un model écrit dans la syntaxe correspondante. En ligne de commande, ajoutez --serve à --model. Avec les SDK, passez serveWith: 'vllm' (TypeScript) ou serve_with="vllm" (Python). Avec le serveur MCP, passez serve: true. Voir CLI et SDK et Serveur MCP.

Serve with fonctionne sur les sessions qui passent par le relais Node Lodge. Sur les autres sessions, le lancement est refusé :

Serve with runs on sessions through the Node Lodge relay. Launch without it, then start the server over SSH.

Le point d’accès

Le serveur écoute sur la machine seulement. Son point d’accès est publié à l’adresse de la session sur le relais :

https://<session>.<relay domain>/v1

• Un port peut suivre le domaine : copiez l’URL de base telle que Node Lodge la donne.
• TLS va jusqu’à la machine. Le relais ne voit ni la clé ni les requêtes.
• Chaque session a sa propre clé, qui commence par nls_. Envoyez-la en Authorization: Bearer <key>. Une requête sans clé valide reçoit 401.
• Les chemins sous /v1/ reçoivent une réponse. Tout autre chemin est refusé.
• Le serveur et le point d’accès tournent sous un utilisateur système dédié, nodelodge-serve, sans shell, jamais en root.
• Le relais limite les connexions simultanées et les nouvelles connexions par seconde de chaque origine de session.
• Le point d’accès s’arrête avec la session, y compris quand son budget est atteint.

Où lire le point d’accès :

• Dans la console, sur la page de la session, le panneau OpenAI-compatible endpoint affiche Base URL, Model, API key (masquée, avec Copy key et New key) et un exemple curl.
• Avec l’API, GET /v1/sessions/{id}/access renvoie inference : baseUrl, apiKey, model, engine et status.
• En ligne de commande, nodelodge endpoint <session-id> affiche l’URL de base, le modèle et la clé.
• Avec le serveur MCP, get_session renvoie endpoint.

État du serveur

La session donne l’état du serveur dans serve.status :

Après un échec, connectez-vous en SSH et démarrez vous-même un serveur sur le modèle. Voir Sans Serve with.

Envoyer une requête

Placez l’URL de base dans BASE_URL et la clé dans NODELODGE_ENDPOINT_KEY, puis :

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $NODELODGE_ENDPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen3-8B", "messages": [{"role": "user", "content": "Hello"}]}'

Tout client OpenAI convient. Avec la bibliothèque Python d’OpenAI :

import os

from openai import OpenAI

client = OpenAI(base_url=os.environ["BASE_URL"], api_key=os.environ["NODELODGE_ENDPOINT_KEY"])
reply = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

Avec Ollama, nommez le modèle court, par exemple qwen3-8b:q4_k_m. La clé est un secret : gardez-la hors des fichiers partagés, des adresses et des journaux.

Obtenir une nouvelle clé

Choisissez New key dans le panneau, ou appelez POST /v1/sessions/{id}/serve-key (sessions.newServeKey(id) en TypeScript, sessions.new_serve_key(id) en Python). L’appel renvoie la nouvelle clé. L’ancienne cesse de fonctionner en 15 secondes au plus, et ses connexions ouvertes sont coupées.

Sans Serve with

Rien ne démarre sur le modèle. Connectez-vous avec ssh et démarrez vous-même le serveur, sur des poids safetensors :

nodelodge-model wait && vllm serve Qwen/Qwen3-8B

Sur un fichier GGUF, avec Ollama ou llama.cpp : voir Exécuter un fichier GGUF.

Place disque

La machine doit avoir la place des poids (pour une version GGUF, de son fichier), plus une marge. Si elle n’en a pas assez, le lancement est refusé avant tout démarrage, avec la place dont le modèle a besoin et celle dont la machine dispose pour les modèles. Choisissez une machine avec plus de disque, ou un modèle plus petit.

Suivre le téléchargement

La ligne Model de la page de session affiche la progression et le temps restant. Sur la machine :

• nodelodge-model status affiche le pourcentage téléchargé et la taille du modèle.
• nodelodge-model wait rend la main quand le modèle est chargé, avec le code de sortie 0. Tout autre code de sortie signifie que le modèle n’a pas été chargé.
• Un message à l’ouverture d’un shell indique où en est le téléchargement.

Exécutez nodelodge-model wait avant de charger le modèle ou le fichier GGUF : le serveur démarre ainsi sur des fichiers complets.

nodelodge-model wait && vllm serve Qwen/Qwen3-8B

Redémarrages et interruptions

Un redémarrage de la machine reprend le téléchargement. Pour reprendre un téléchargement arrêté, exécutez :

sudo nodelodge-model resume

Les fichiers déjà vérifiés restent en place et ne sont pas téléchargés de nouveau.

Quand le modèle n’a pas été chargé

Quand le téléchargement ne se termine pas, la session continue et sa page indique The model was not loaded. Elle donne la raison, par exemple :

• Hugging Face n’a pas servi les fichiers.
• Le téléchargement a duré plus de 6 heures.
• Un fichier téléchargé ne correspondait pas à sa somme de contrôle.
• Le disque est plein.
• Le téléchargement a échoué.
• Le téléchargement n’a pas progressé pendant 10 minutes.

La page affiche la commande qui télécharge le modèle. Quand la session tourne déjà, vous recevez aussi un courriel avec la raison et la commande. Ouvrez un terminal sur la machine et exécutez-la, ou exécutez sudo nodelodge-model resume. Les fichiers arrivent dans le même cache.

Pour un modèle à accès restreint ou privé, la commande vous connecte à Hugging Face avant de télécharger : collez votre jeton de lecture quand elle le demande. Pour une version GGUF, la commande nomme son fichier : hf download org/name <file> --revision <revision>. sudo nodelodge-model resume utilise le jeton de $HF_HOME/token. Si ce fichier manque, connectez-vous d’abord, puis reprenez :

/opt/nodelodge/jupyter/bin/pip install -q -U huggingface_hub && /opt/nodelodge/jupyter/bin/hf auth login
sudo nodelodge-model resume

L’avertissement s’affiche tant que la session tourne. Une session terminée ou qui n’a pas démarré n’a pas de machine où télécharger.

Courriels

Vous recevez un courriel quand le modèle est prêt, sauf s’il arrive dans les 5 minutes qui suivent le moment où la session est prête : la console l’affiche. Quand la session tourne déjà, vous recevez aussi un courriel quand le modèle n’a pas pu être téléchargé. Désactivez l’un ou l’autre dans Notification settings. Voir Notifications.

Machines Community

Les environnements Community qui téléchargent un modèle le font au premier lancement, sous votre nom, dans /workspace. Le téléchargement d’un modèle en arrière-plan par Node Lodge concerne les machines Node Lodge Secure. Voir Secure et Community.