Modelos al lanzar

Elija un modelo al lanzar una máquina Node Lodge Secure. La sesión está lista en cuanto lo está la máquina, y el modelo se descarga en segundo plano. Use la máquina mientras se descarga. La sesión se factura desde que está lista, descarga incluida.

Elegir un modelo

En Launch, elija una máquina Node Lodge Secure. En el paso Environment, escriba el modelo en Model (optional):

• Use el nombre como lo muestra Hugging Face: org/name, por ejemplo Qwen/Qwen3-8B, para los pesos safetensors.
• Añada :VERSION para un solo archivo GGUF del repositorio: org/name:VERSION, por ejemplo unsloth/Qwen3-8B-GGUF:Q4_K_M. Consulte Versiones GGUF.
• Acepte la licencia del modelo. El lanzamiento envía su aceptación.
• Marque Serve with para obtener un endpoint compatible con OpenAI sobre el modelo. Consulte Servir el modelo.
• Deje el campo vacío para lanzar sin modelo.

Con la API, envíe model (id y licenseAccepted: true) en POST /v1/sessions. Con el SDK de Python, pase model="Qwen/Qwen3-8B" a sessions.launch. Con el SDK de TypeScript, pase model: { id, licenseAccepted: true }. Con la línea de comandos, añada --model <org/name[:VERSION]> --accept-license a nodelodge launch. Consulte Referencia de la API y CLI y SDK.

POST /v1/models/lookup comprueba un modelo antes del lanzamiento: su revisión, su tamaño, el tiempo de descarga y, para una versión GGUF, su format y su file.

Versiones GGUF

Un repositorio GGUF contiene un archivo por versión (cuantización), por ejemplo Qwen3-8B-Q4_K_M.gguf y Qwen3-8B-Q8_0.gguf. Escriba la versión después del nombre, org/name:VERSION, y la máquina descarga solo ese archivo:

• La versión se compara con el final del nombre del archivo, después de un - o un ., sin distinguir mayúsculas de minúsculas: Q4_K_M elige Qwen3-8B-Q4_K_M.gguf.
• Cuando varios archivos terminan igual, como Q4_K_M y UD-Q4_K_M, gana el nombre más corto. Escriba UD-Q4_K_M para el otro.
• Un archivo dividido en partes, como -00001-of-00002.gguf, se descarga con todas sus partes.
• Cada archivo se descarga en paralelo y se verifica con su suma SHA-256.

Un lanzamiento con una versión que el repositorio no tiene se rechaza antes de que empiece nada, con las versiones que tiene:

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

Un repositorio sin archivos GGUF se rechaza del mismo modo:

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

El tamaño y el tiempo de descarga estimados, la comprobación del presupuesto y el espacio en disco cuentan solo ese archivo.

Presupuesto y duración de la descarga

El formulario de lanzamiento muestra la duración estimada de la descarga del modelo. Un lanzamiento se rechaza cuando su presupuesto o su duración máxima no cubre la estimación con un margen. El mensaje indica qué debe aumentar, con el importe que cubre la estimación a la tarifa de la máquina. Por ejemplo, para 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 duración real depende de la carga de la red. Con la sesión en marcha, su página muestra el tiempo restante, medido sobre la propia descarga.

Su token de Hugging Face

Guarde una vez un token de lectura de Hugging Face. Node Lodge lo usa para consultar y resolver cada modelo que lanza, modelos públicos incluidos. Un modelo con acceso restringido o privado lo necesita.

1. En la consola, abra Settings y luego Integrations.
2. Pegue un token de lectura en Hugging Face y elija Save token. Hugging Face debe aceptarlo. Con la autenticación de dos factores activada, introduzca un código reciente; si no, introduzca su contraseña en Account password.
3. Recibe un correo electrónico cada vez que se guarda, se reemplaza o se elimina un token.

• Un token de lectura basta.
• Para un modelo con acceso restringido, acepte antes su licencia en Hugging Face con la cuenta del token.
• El token se guarda cifrado y no vuelve a mostrarse: la página muestra sus 4 últimos caracteres y la fecha en que se guardó. Replace y Remove están en la misma página. Las sesiones ya iniciadas conservan el suyo.
• No aparece en los detalles de su sesión.

Para un modelo con acceso restringido o privado, el token se coloca en la máquina: en $HF_HOME/token, legible solo por el usuario ubuntu, y definido como HF_TOKEN en cada shell de inicio de sesión. hf, vLLM y transformers lo encuentran sin hf auth login. Una máquina lanzada con un modelo público no recibe token.

Para subir archivos al Hub desde sus máquinas, active Also put my token on every machine I launch (for uploads to the Hub) en Integrations. La opción está desactivada por defecto. Cada máquina lanzada con un modelo recibe entonces el token, y cualquier persona que pueda abrir esas máquinas puede leerlo. Activarla pide un código de dos factores reciente, o su contraseña sin autenticación de dos factores. On machines muestra el ajuste: Gated and private models only o Every machine you launch with a model. Con la API, envíe shareOnMachines en PUT /v1/integrations/hugging-face, o { "shareOnMachines": true } en PATCH /v1/integrations/hugging-face.

Para usar otro token en un solo lanzamiento, envíelo como modelToken en POST /v1/sessions. Con el SDK de Python, pase model_token a sessions.launch; con el SDK de TypeScript, pase modelToken. Sustituye al token guardado solo para ese lanzamiento, y se coloca en la máquina sea cual sea el modelo. Sin token guardado, el formulario de lanzamiento pide uno en Hugging Face token (gated and private models), para ese lanzamiento. POST /v1/models/lookup acepta un token del mismo modo; las consultas con un token están limitadas a 10 por minuto y por organización.

Con una clave API (CLI, SDK, servidor MCP, GitHub Action), un lanzamiento usa su token guardado solo si la clave se creó con Launches use my saved Hugging Face token marcado, en API keys. Quien tenga esa clave puede leer el token en las máquinas que lanza. Con cualquier otra clave, envíe el token con el lanzamiento (modelToken) o cree una clave con la casilla marcada.

Qué se carga

Para org/name: los pesos en formato safetensors, con los archivos que los acompañan: configuración, tokenizer y licencia. Los otros formatos del mismo modelo, como GGUF u ONNX, se dejan fuera. Un modelo publicado sin pesos safetensors se rechaza al lanzar: elija una versión GGUF con org/name:VERSION cuando el repositorio la tenga.

Para org/name:VERSION: el único archivo GGUF de esa versión, o todas sus partes.

La revisión cargada se fija al lanzar: un modelo actualizado después en Hugging Face no cambia bajo su sesión. La página de la sesión muestra el modelo y dónde está en la máquina.

Dónde están los archivos

En la máquina, el modelo está en la caché de Hugging Face:

• /data/huggingface cuando la máquina tiene un disco de datos,
• ~/.cache/huggingface en caso contrario.

HF_HOME está definida para todos los usuarios y todas las shells desde la primera conexión, así que las herramientas encuentran la caché sin más ajustes. La fila Model de la página de la sesión muestra la ruta completa, con un botón de copiar.

Para pesos safetensors, el model.localPath de la sesión es la carpeta del snapshot del modelo. Cárguelo por su nombre. No se descarga nada de nuevo:

vllm serve Qwen/Qwen3-8B

from transformers import AutoModelForCausalLM

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

Ejecutar un archivo GGUF

Para una versión GGUF, model.localPath es el propio archivo GGUF, por ejemplo:

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

model.format vale gguf y model.id vale unsloth/Qwen3-8B-GGUF:Q4_K_M. Copie la ruta de la fila Model de la página de la sesión en MODEL_PATH y pásela a llama.cpp:

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

O a Ollama, con un Modelfile de una sola línea, FROM seguido de la ruta:

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

Para un archivo dividido en partes, la ruta es la de la primera parte. llama.cpp carga las demás desde la misma carpeta.

Servir el modelo

Marque Serve with bajo el modelo: un servidor arranca sobre el modelo en cuanto termina de descargarse, detrás de un endpoint compatible con OpenAI con su propia clave.

• vLLM para org/name (pesos safetensors). Las solicitudes nombran el modelo org/name, por ejemplo Qwen/Qwen3-8B.
• Ollama para org/name:VERSION (un archivo GGUF). El archivo se importa con un nombre corto, por ejemplo qwen3-8b:q4_k_m para unsloth/Qwen3-8B-GGUF:Q4_K_M. Ollama acepta un archivo GGUF de una sola parte: una versión dividida en partes se rechaza al lanzar.

Con la API, envíe serveWith (vllm u ollama) en POST /v1/sessions, con un model escrito en la sintaxis que corresponde. Con la línea de comandos, añada --serve a --model. Con los SDK, pase serveWith: 'vllm' (TypeScript) o serve_with="vllm" (Python). Con el servidor MCP, pase serve: true. Consulte CLI y SDK y Servidor MCP.

Serve with funciona en las sesiones que pasan por el relé de Node Lodge. En las demás sesiones, el lanzamiento se rechaza:

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

El endpoint

El servidor escucha solo en la máquina. Su endpoint se publica en la dirección de la sesión en el relé:

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

• Puede haber un puerto después del dominio: copie la URL base tal como la da Node Lodge.
• TLS llega hasta la máquina. El relé no ve ni la clave ni las solicitudes.
• Cada sesión tiene su propia clave, que empieza por nls_. Envíela como Authorization: Bearer <key>. Una solicitud sin una clave válida recibe 401.
• Las rutas bajo /v1/ reciben respuesta. Cualquier otra ruta se rechaza.
• El servidor y el endpoint se ejecutan con un usuario del sistema dedicado, nodelodge-serve, sin shell, nunca como root.
• El relé limita las conexiones simultáneas y las conexiones nuevas por segundo de cada origen de sesión.
• El endpoint se detiene con la sesión, también cuando se alcanza su presupuesto.

Dónde leer el endpoint:

• En la consola, en la página de la sesión, el panel OpenAI-compatible endpoint muestra Base URL, Model, API key (oculta, con Copy key y New key) y un ejemplo con curl.
• Con la API, GET /v1/sessions/{id}/access devuelve inference: baseUrl, apiKey, model, engine y status.
• Con la línea de comandos, nodelodge endpoint <session-id> muestra la URL base, el modelo y la clave.
• Con el servidor MCP, get_session devuelve endpoint.

Estado del servidor

La sesión da el estado del servidor en serve.status:

Tras un fallo, conéctese por SSH y arranque usted mismo un servidor sobre el modelo. Consulte Sin Serve with.

Enviar una solicitud

Ponga la URL base en BASE_URL y la clave en NODELODGE_ENDPOINT_KEY, y luego:

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

Sirve cualquier cliente de OpenAI. Con la biblioteca de Python de 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)

Con Ollama, nombre el modelo corto, por ejemplo qwen3-8b:q4_k_m. La clave es un secreto: manténgala fuera de archivos compartidos, direcciones y registros.

Obtener una clave nueva

Elija New key en el panel, o llame a POST /v1/sessions/{id}/serve-key (sessions.newServeKey(id) en TypeScript, sessions.new_serve_key(id) en Python). La llamada devuelve la clave nueva. La anterior deja de funcionar en 15 segundos como máximo, y sus conexiones abiertas se cierran.

Sin Serve with

No arranca nada sobre el modelo. Conéctese con ssh y arranque usted mismo el servidor, sobre pesos safetensors:

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

Sobre un archivo GGUF, con Ollama o llama.cpp: consulte Ejecutar un archivo GGUF.

Espacio en disco

La máquina necesita sitio para los pesos (para una versión GGUF, su archivo) más un margen. Si no lo tiene, el lanzamiento se rechaza antes de que empiece nada, con el espacio que necesita el modelo y el que la máquina tiene para modelos. Elija una máquina con más disco, o un modelo más pequeño.

Seguir la descarga

La fila Model de la página de la sesión muestra el progreso y el tiempo restante. En la máquina:

• nodelodge-model status muestra el porcentaje descargado y el tamaño del modelo.
• nodelodge-model wait termina cuando el modelo está cargado, con código de salida 0. Cualquier otro código de salida significa que el modelo no se cargó.
• Un mensaje al abrir una shell indica cómo va la descarga.

Ejecute nodelodge-model wait antes de cargar el modelo o el archivo GGUF: así el servidor arranca con los archivos completos.

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

Reinicios e interrupciones

Un reinicio de la máquina reanuda la descarga. Para reanudar una descarga detenida, ejecute:

sudo nodelodge-model resume

Los archivos ya verificados se conservan y no se descargan de nuevo.

Cuando el modelo no se cargó

Cuando la descarga no termina, la sesión sigue en marcha y su página indica The model was not loaded. Da el motivo, por ejemplo:

• Hugging Face no sirvió los archivos.
• La descarga duró más de 6 horas.
• Un archivo descargado no coincidía con su suma de comprobación.
• El disco se quedó sin espacio.
• La descarga falló.
• La descarga no avanzó durante 10 minutos.

La página muestra el comando que descarga el modelo. Cuando la sesión ya está en marcha, también recibe un correo electrónico con el motivo y el comando. Abra un terminal en la máquina y ejecútelo, o ejecute sudo nodelodge-model resume. Los archivos llegan a la misma caché.

Para un modelo con acceso restringido o privado, el comando inicia su sesión en Hugging Face antes de descargar: pegue su token de lectura cuando lo pida. Para una versión GGUF, el comando nombra su archivo: hf download org/name <file> --revision <revision>. sudo nodelodge-model resume usa el token de $HF_HOME/token. Si ese archivo falta, inicie sesión primero y después reanude:

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

El aviso se muestra mientras la sesión está en marcha. Una sesión terminada o que no arrancó no tiene máquina donde descargar.

Correos electrónicos

Recibe un correo cuando el modelo está listo, salvo que llegue en los 5 minutos siguientes al momento en que la sesión está lista: la consola lo muestra. Cuando la sesión ya está en marcha, también recibe un correo cuando el modelo no se pudo descargar. Desactive cualquiera de los dos en Notification settings. Consulte Notificaciones.

Máquinas Community

Los entornos Community que descargan un modelo lo hacen en el primer lanzamiento, a su nombre, en /workspace. Los modelos que Node Lodge descarga en segundo plano están en las máquinas Node Lodge Secure. Consulte Secure y Community.