Modelle beim Start

Wählen Sie beim Start einer Node-Lodge-Secure-Maschine ein Modell. Die Sitzung ist bereit, sobald die Maschine es ist, und das Modell wird im Hintergrund heruntergeladen. Nutzen Sie die Maschine, während der Download läuft. Die Sitzung wird ab dem Moment berechnet, in dem sie bereit ist, Download eingeschlossen.

Ein Modell wählen

Wählen Sie in Launch eine Node-Lodge-Secure-Maschine. Geben Sie im Schritt Environment das Modell unter Model (optional) ein:

• Verwenden Sie den Namen so, wie Hugging Face ihn zeigt: org/name, zum Beispiel Qwen/Qwen3-8B, für die Safetensors-Gewichte.
• Hängen Sie :VERSION an, um eine einzelne GGUF-Datei des Repositorys zu laden: org/name:VERSION, zum Beispiel unsloth/Qwen3-8B-GGUF:Q4_K_M. Siehe GGUF-Versionen.
• Akzeptieren Sie die Lizenz des Modells. Der Start überträgt Ihre Zustimmung.
• Aktivieren Sie Serve with, um einen OpenAI-kompatiblen Endpunkt für das Modell zu erhalten. Siehe Das Modell bereitstellen.
• Lassen Sie das Feld leer, um ohne Modell zu starten.

Senden Sie mit der API model (id und licenseAccepted: true) in POST /v1/sessions. Übergeben Sie mit dem Python-SDK model="Qwen/Qwen3-8B" an sessions.launch. Übergeben Sie mit dem TypeScript-SDK model: { id, licenseAccepted: true }. Ergänzen Sie in der Befehlszeile nodelodge launch um --model <org/name[:VERSION]> --accept-license. Siehe API-Referenz und CLI und SDK.

POST /v1/models/lookup prüft ein Modell vor dem Start: Revision, Größe, Downloaddauer und, bei einer GGUF-Version, format und file.

GGUF-Versionen

Ein GGUF-Repository enthält eine Datei pro Version (Quantisierung), zum Beispiel Qwen3-8B-Q4_K_M.gguf und Qwen3-8B-Q8_0.gguf. Schreiben Sie die Version hinter den Namen, org/name:VERSION, und die Maschine lädt nur diese Datei herunter:

• Die Version wird mit dem Ende des Dateinamens verglichen, nach einem - oder einem ., ohne Unterschied zwischen Groß- und Kleinschreibung: Q4_K_M wählt Qwen3-8B-Q4_K_M.gguf.
• Enden mehrere Dateien so, etwa Q4_K_M und UD-Q4_K_M, gewinnt der kürzeste Name. Schreiben Sie UD-Q4_K_M für die andere.
• Eine in Teile zerlegte Datei, etwa -00001-of-00002.gguf, wird mit allen Teilen heruntergeladen.
• Jede Datei wird parallel heruntergeladen und anhand ihrer SHA-256-Prüfsumme geprüft.

Ein Start mit einer Version, die das Repository nicht hat, wird abgelehnt, bevor etwas beginnt, mit den vorhandenen Versionen:

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

Ein Repository ohne GGUF-Dateien wird ebenso abgelehnt:

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

Geschätzte Größe und Downloaddauer, Budgetprüfung und Speicherplatz beziehen sich auf diese eine Datei.

Budget und Downloaddauer

Das Startformular zeigt die geschätzte Downloaddauer des Modells. Ein Start wird abgelehnt, wenn Ihr Budget oder Ihre maximale Dauer die Schätzung samt Puffer nicht abdeckt. Die Meldung nennt, was Sie erhöhen müssen, mit dem Betrag, der die Schätzung zum Tarif der Maschine abdeckt. Zum Beispiel für 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.

Die tatsächliche Dauer hängt von der Auslastung des Netzes ab. Läuft die Sitzung, zeigt ihre Seite die verbleibende Zeit, gemessen am Download selbst.

Ihr Hugging-Face-Token

Speichern Sie einmal ein Hugging-Face-Lesetoken. Node Lodge verwendet es, um jedes Modell, das Sie starten, nachzuschlagen und aufzulösen, öffentliche Modelle eingeschlossen. Ein geschütztes (gated) oder privates Modell braucht es.

1. Öffnen Sie in der Konsole Settings, dann Integrations.
2. Fügen Sie unter Hugging Face ein Lesetoken ein und wählen Sie Save token. Hugging Face muss es akzeptieren. Bei aktivierter Zwei-Faktor-Authentifizierung geben Sie einen kürzlich erzeugten Code ein, sonst Ihr Passwort unter Account password.
3. Sie erhalten jedes Mal eine E-Mail, wenn ein Token gespeichert, ersetzt oder entfernt wird.

• Ein Lesetoken genügt.
• Akzeptieren Sie bei einem geschützten Modell zuerst seine Lizenz auf Hugging Face, mit dem Konto des Tokens.
• Das Token wird verschlüsselt gespeichert und nie wieder angezeigt: Die Seite zeigt seine letzten 4 Zeichen und das Datum, an dem es gespeichert wurde. Replace und Remove finden Sie auf derselben Seite. Bereits gestartete Sitzungen behalten ihres.
• Es erscheint nicht in Ihren Sitzungsdetails.

Bei einem geschützten oder privaten Modell wird das Token auf die Maschine gelegt: in $HF_HOME/token, nur für den Benutzer ubuntu lesbar, und in jeder Login-Shell als HF_TOKEN gesetzt. hf, vLLM und transformers finden es ohne hf auth login. Eine Maschine, die mit einem öffentlichen Modell startet, erhält kein Token.

Um von Ihren Maschinen aus Dateien in den Hub hochzuladen, aktivieren Sie in Integrations die Option Also put my token on every machine I launch (for uploads to the Hub). Sie ist standardmäßig ausgeschaltet. Dann erhält jede Maschine, die Sie mit einem Modell starten, das Token, und jeder, der diese Maschinen öffnen kann, kann es lesen. Das Einschalten verlangt einen kürzlich erzeugten Zwei-Faktor-Code, ohne Zwei-Faktor-Authentifizierung Ihr Passwort. On machines zeigt die Einstellung: Gated and private models only oder Every machine you launch with a model. Senden Sie mit der API shareOnMachines in PUT /v1/integrations/hugging-face oder { "shareOnMachines": true } in PATCH /v1/integrations/hugging-face.

Um für einen einzelnen Start ein anderes Token zu verwenden, senden Sie es als modelToken in POST /v1/sessions. Übergeben Sie mit dem Python-SDK model_token an sessions.launch, mit dem TypeScript-SDK modelToken. Es ersetzt das gespeicherte Token nur für diesen Start und wird unabhängig vom Modell auf die Maschine gelegt. Ohne gespeichertes Token fragt das Startformular unter Hugging Face token (gated and private models) nach einem, für diesen Start. POST /v1/models/lookup nimmt ein token auf dieselbe Weise; Abfragen mit einem token sind auf 10 pro Minute und Organisation begrenzt.

Mit einem API-Schlüssel (CLI, SDKs, MCP-Server, GitHub Action) verwendet ein Start Ihr gespeichertes Token nur, wenn der Schlüssel unter API keys mit aktiviertem Launches use my saved Hugging Face token erstellt wurde. Wer einen solchen Schlüssel besitzt, kann das Token auf den damit gestarteten Maschinen lesen. Mit jedem anderen Schlüssel senden Sie das Token mit dem Start (modelToken) oder erstellen einen Schlüssel mit aktiviertem Kästchen.

Was geladen wird

Für org/name: die Gewichte im Safetensors-Format mit den zugehörigen Dateien: Konfiguration, Tokenizer und Lizenz. Andere Formate desselben Modells, etwa GGUF oder ONNX, bleiben außen vor. Ein Modell ohne Safetensors-Gewichte wird beim Start abgelehnt: Wählen Sie mit org/name:VERSION eine GGUF-Version, wenn das Repository eine hat.

Für org/name:VERSION: die eine GGUF-Datei dieser Version oder alle ihre Teile.

Die geladene Revision wird beim Start festgelegt: Ein später auf Hugging Face aktualisiertes Modell ändert sich nicht unter Ihrer Sitzung. Die Sitzungsseite zeigt das Modell und seinen Speicherort auf der Maschine.

Wo die Dateien liegen

Auf der Maschine liegt das Modell im Hugging-Face-Cache:

• /data/huggingface, wenn die Maschine einen Datenträger hat,
• sonst ~/.cache/huggingface.

HF_HOME ist für alle Benutzer und alle Shells ab der ersten Verbindung gesetzt, damit Werkzeuge den Cache ohne weitere Einrichtung finden. Die Zeile Model der Sitzungsseite zeigt den vollständigen Pfad mit Kopierschaltfläche.

Bei Safetensors-Gewichten ist model.localPath der Sitzung der Snapshot-Ordner des Modells. Laden Sie es über den Namen. Es wird nichts erneut heruntergeladen:

vllm serve Qwen/Qwen3-8B

from transformers import AutoModelForCausalLM

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

Eine GGUF-Datei ausführen

Bei einer GGUF-Version ist model.localPath die GGUF-Datei selbst, zum Beispiel:

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

model.format ist gguf und model.id ist unsloth/Qwen3-8B-GGUF:Q4_K_M. Kopieren Sie den Pfad aus der Zeile Model der Sitzungsseite in MODEL_PATH und übergeben Sie ihn an llama.cpp:

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

Oder an Ollama, mit einem Modelfile aus einer Zeile, FROM und dem Pfad:

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

Bei einer in Teile zerlegten Datei zeigt der Pfad auf den ersten Teil. llama.cpp lädt die übrigen Teile aus demselben Ordner.

Das Modell bereitstellen

Aktivieren Sie Serve with unter dem Modell: Sobald das Modell heruntergeladen ist, startet ein Server darauf, hinter einem OpenAI-kompatiblen Endpunkt mit eigenem Schlüssel.

• vLLM für org/name (Safetensors-Gewichte). Anfragen nennen das Modell org/name, zum Beispiel Qwen/Qwen3-8B.
• Ollama für org/name:VERSION (eine GGUF-Datei). Die Datei wird unter einem kurzen Namen importiert, zum Beispiel qwen3-8b:q4_k_m für unsloth/Qwen3-8B-GGUF:Q4_K_M. Ollama nimmt eine GGUF-Datei aus einem einzigen Teil: Eine in Teile zerlegte Version wird beim Start abgelehnt.

Senden Sie mit der API serveWith (vllm oder ollama) in POST /v1/sessions, mit einem model in der passenden Schreibweise. Ergänzen Sie in der Befehlszeile --model um --serve. Übergeben Sie mit den SDKs serveWith: 'vllm' (TypeScript) oder serve_with="vllm" (Python). Übergeben Sie mit dem MCP-Server serve: true. Siehe CLI und SDK und MCP-Server.

Serve with läuft auf Sitzungen über das Node-Lodge-Relay. Bei anderen Sitzungen wird der Start abgelehnt:

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

Der Endpunkt

Der Server lauscht nur auf der Maschine. Sein Endpunkt wird unter der Adresse der Sitzung auf dem Relay veröffentlicht:

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

• Auf die Domain kann ein Port folgen: Kopieren Sie die Basis-URL so, wie Node Lodge sie angibt.
• TLS reicht bis zur Maschine. Das Relay sieht weder den Schlüssel noch die Anfragen.
• Jede Sitzung hat ihren eigenen Schlüssel, der mit nls_ beginnt. Senden Sie ihn als Authorization: Bearer <key>. Eine Anfrage ohne gültigen Schlüssel erhält 401.
• Pfade unter /v1/ werden beantwortet. Jeder andere Pfad wird abgelehnt.
• Server und Endpunkt laufen unter einem eigenen Systembenutzer, nodelodge-serve, ohne Shell, nie als root.
• Das Relay begrenzt die gleichzeitigen und die neuen Verbindungen pro Sekunde jedes Sitzungsursprungs.
• Der Endpunkt endet mit der Sitzung, auch wenn ihr Budget erreicht ist.

Wo Sie den Endpunkt finden:

• In der Konsole, auf der Sitzungsseite, zeigt das Feld OpenAI-compatible endpoint Base URL, Model, API key (verdeckt, mit Copy key und New key) und ein curl-Beispiel.
• Mit der API liefert GET /v1/sessions/{id}/access inference: baseUrl, apiKey, model, engine und status.
• In der Befehlszeile gibt nodelodge endpoint <session-id> die Basis-URL, das Modell und den Schlüssel aus.
• Mit dem MCP-Server liefert get_session endpoint.

Status des Servers

Die Sitzung gibt den Status des Servers in serve.status an:

Verbinden Sie sich nach einem Fehler per SSH und starten Sie selbst einen Server mit dem Modell. Siehe Ohne Serve with.

Eine Anfrage senden

Setzen Sie BASE_URL auf die Basis-URL und NODELODGE_ENDPOINT_KEY auf den Schlüssel, dann:

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"}]}'

Jeder OpenAI-Client funktioniert. Mit der Python-Bibliothek von 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)

Nennen Sie bei Ollama den kurzen Modellnamen, zum Beispiel qwen3-8b:q4_k_m. Der Schlüssel ist ein Geheimnis: Halten Sie ihn aus geteilten Dateien, Adressen und Protokollen heraus.

Einen neuen Schlüssel erhalten

Wählen Sie New key im Feld, oder rufen Sie POST /v1/sessions/{id}/serve-key auf (sessions.newServeKey(id) in TypeScript, sessions.new_serve_key(id) in Python). Der Aufruf liefert den neuen Schlüssel. Der vorherige funktioniert nach spätestens 15 Sekunden nicht mehr, und seine offenen Verbindungen werden getrennt.

Ohne Serve with

Auf dem Modell startet nichts. Verbinden Sie sich mit ssh und starten Sie den Server selbst, bei Safetensors-Gewichten:

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

Bei einer GGUF-Datei, mit Ollama oder llama.cpp: siehe Eine GGUF-Datei ausführen.

Speicherplatz

Die Maschine braucht Platz für die Gewichte (bei einer GGUF-Version für ihre Datei) plus einen Puffer. Reicht er nicht, wird der Start abgelehnt, bevor etwas beginnt, mit dem Platzbedarf des Modells und dem Platz, den die Maschine für Modelle hat. Wählen Sie eine Maschine mit mehr Speicher oder ein kleineres Modell.

Den Download verfolgen

Die Zeile Model der Sitzungsseite zeigt Fortschritt und verbleibende Zeit. Auf der Maschine:

• nodelodge-model status zeigt den heruntergeladenen Anteil in Prozent und die Größe des Modells.
• nodelodge-model wait kehrt zurück, sobald das Modell geladen ist, mit Exit-Code 0. Jeder andere Exit-Code bedeutet, dass das Modell nicht geladen wurde.
• Eine Meldung beim Öffnen einer Shell zeigt den Stand des Downloads.

Führen Sie nodelodge-model wait aus, bevor Sie das Modell oder die GGUF-Datei laden: So startet der Server mit vollständigen Dateien.

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

Neustarts und Unterbrechungen

Ein Neustart der Maschine setzt den Download fort. Um einen gestoppten Download fortzusetzen, führen Sie aus:

sudo nodelodge-model resume

Bereits geprüfte Dateien bleiben erhalten und werden nicht erneut heruntergeladen.

Wenn das Modell nicht geladen wurde

Endet der Download nicht, läuft die Sitzung weiter, und ihre Seite zeigt The model was not loaded. Sie nennt den Grund, zum Beispiel:

• Hugging Face hat die Dateien nicht geliefert.
• Der Download dauerte länger als 6 Stunden.
• Eine heruntergeladene Datei stimmte nicht mit ihrer Prüfsumme überein.
• Der Datenträger ist voll.
• Der Download ist fehlgeschlagen.
• Der Download machte 10 Minuten lang keine Fortschritte.

Die Seite zeigt den Befehl, der das Modell herunterlädt. Läuft die Sitzung bereits, erhalten Sie zusätzlich eine E-Mail mit Grund und Befehl. Öffnen Sie ein Terminal auf der Maschine und führen Sie ihn aus, oder führen Sie sudo nodelodge-model resume aus. Die Dateien landen im selben Cache.

Bei einem geschützten oder privaten Modell meldet der Befehl Sie vor dem Download bei Hugging Face an: Fügen Sie Ihr Lese-Token ein, wenn er danach fragt. Bei einer GGUF-Version nennt der Befehl ihre Datei: hf download org/name <file> --revision <revision>. sudo nodelodge-model resume verwendet das Token aus $HF_HOME/token. Fehlt diese Datei, melden Sie sich zuerst an und setzen dann fort:

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

Die Warnung erscheint, solange die Sitzung läuft. Eine beendete oder nicht gestartete Sitzung hat keine Maschine, auf die geladen werden könnte.

E-Mails

Sie erhalten eine E-Mail, wenn das Modell bereit ist, außer es trifft innerhalb von 5 Minuten, nachdem die Sitzung bereit ist, ein: Die Konsole zeigt es an. Läuft die Sitzung bereits, erhalten Sie auch eine E-Mail, wenn das Modell nicht heruntergeladen werden konnte. Schalten Sie beide in Notification settings ab. Siehe Benachrichtigungen.

Community-Maschinen

Community-Umgebungen, die ein Modell herunterladen, tun dies beim ersten Start unter Ihrem Namen nach /workspace. Modelle, die Node Lodge im Hintergrund herunterlädt, gibt es auf Node-Lodge-Secure-Maschinen. Siehe Secure und Community.