Despliegue de VLM Cosmos en Jetson con vLLM

Los Vision-Language Models (VLM) combinan percepción visual con razonamiento en lenguaje natural. ¿Por qué importa esto en el borde? Porque ahora puedes tener una IA que mira, interpreta y razona en tiempo real junto a tus robots o dispositivos embebidos, sin depender de la nube.

Qué vas a encontrar en este tutorial

Te muestro cómo desplegar el modelo NVIDIA Cosmos Reasoning 2B (FP8) en la familia Jetson usando el runtime vLLM. Veremos desde requisitos de hardware y software, hasta los comandos para descargar el modelo, lanzar el contenedor y conectar la interfaz Live VLM WebUI para análisis por webcam en tiempo real.

Dispositivos y requisitos mínimos

• Dispositivos soportados:

  • Jetson AGX Thor
  • Jetson AGX Orin (64GB / 32GB)
  • Jetson Orin Super Nano

• JetPack:

  • JetPack 6 (L4T r36.x) para Orin
  • JetPack 7 (L4T r38.x) para Thor

• Almacenamiento NVMe SSD recomendado:

  • ~5 GB para los pesos en FP8
  • ~8 GB para la imagen del contenedor vLLM

• Cuenta: crea una cuenta gratuita en NVIDIA NGC para descargar el modelo y el contenedor.

Preparación: descarga del NGC CLI y del modelo FP8

Crea un directorio de trabajo y descarga la herramienta NGC CLI para ARM64. Ejemplo rápido:

mkdir -p ~/Projects/CosmosReasoning
cd ~/Projects/CosmosReasoning
# Descargar el instalador ARM64 (ajusta la URL si cambia la versión)
wget -O ngccli_arm64.zip https://api.ngc.nvidia.com/v2/resources/nvidia/ngc-apps/ngc_cli/versions/4.13.0/files/ngccli_arm64.zip
unzip ngccli_arm64.zip
chmod u+x ngc-cli/ngc
export PATH="$PATH:$(pwd)/ngc-cli"
ngc config set

Durante ngc config set te pedirá tu API Key (genera una desde el portal NGC). Luego descarga el checkpoint cuantizado en FP8:

cd ~/Projects/CosmosReasoning
ngc registry model download-version "nim/nvidia/cosmos-reason2-2b:1208-fp8-static-kv8"

Esto crea una carpeta tipo cosmos-reason2-2b_v1208-fp8-static-kv8/. Guarda la ruta completa, la montarás en el contenedor.

Contenedores vLLM por dispositivo

• Jetson AGX Thor:
  • Imagen: ghcr.io/nvidia-ai-iot/vllm:r36.4-tegra-aarch64-cu126-22.04 (Thor usa la imagen optimizada para su entorno)
• Jetson AGX Orin y Orin Super Nano:
  • Imagen: nvcr.io/nvidia/vllm:26.01-py3

Flujo general:

• Descargar checkpoint FP8 desde NGC
• Pull del contenedor vLLM apropiado
• Lanzar el contenedor montando la carpeta del modelo
• Iniciar vllm serve y validar la API

Lanzar vLLM en Jetson AGX Thor (ejemplo)

Montar el modelo y lanzar el contenedor (Thor tiene memoria amplia, usamos contexto largo):

MODEL_PATH="$HOME/Projects/CosmosReasoning/cosmos-reason2-2b_v1208-fp8-static-kv8"
sudo sysctl -w vm.drop_caches=3

docker run --rm -it \
  --runtime nvidia \
  --network host \
  --ipc host \
  -v "$MODEL_PATH:/models/cosmos-reason2-2b:ro" \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  ghcr.io/nvidia-ai-iot/vllm:r36.4-tegra-aarch64-cu126-22.04 \
  bash

Dentro del contenedor:

vllm serve /models/cosmos-reason2-2b \
  --max-model-len 8192 \
  --media-io-kwargs '{"video": {"num_frames": -1}}' \
  --reasoning-parser qwen3 \
  --gpu-memory-utilization 0.8

--reasoning-parser qwen3 habilita extracción de chain-of-thought; --media-io-kwargs configura manejo de video.

Lanzar vLLM en Jetson AGX Orin

Orin tiene suficiente memoria para parámetros similares a Thor. Comandos de ejecución (fuera y dentro del contenedor) son parecidos:

# fuera del contenedor
MODEL_PATH="$HOME/Projects/CosmosReasoning/cosmos-reason2-2b_v1208-fp8-static-kv8"
sudo sysctl -w vm.drop_caches=3

docker run --rm -it \
  --runtime nvidia \
  --network host \
  -v "$MODEL_PATH:/models/cosmos-reason2-2b:ro" \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  nvcr.io/nvidia/vllm:26.01-py3 \
  bash

# dentro del contenedor
cd /opt/
source venv/bin/activate
vllm serve /models/cosmos-reason2-2b \
  --max-model-len 8192 \
  --media-io-kwargs '{"video": {"num_frames": -1}}' \
  --reasoning-parser qwen3 \
  --gpu-memory-utilization 0.8

Espera la línea INFO: Uvicorn running on http://0.0.0.0:8000 antes de continuar.

Lanzar vLLM en Orin Super Nano (memoria limitada)

Aquí toca optimizar agresivamente. Parámetros recomendados:

MODEL_PATH="$HOME/Projects/CosmosReasoning/cosmos-reason2-2b_v1208-fp8-static-kv8"
sudo sysctl -w vm.drop_caches=3

docker run --rm -it \
  --runtime nvidia \
  --network host \
  -v "$MODEL_PATH:/models/cosmos-reason2-2b:ro" \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  nvcr.io/nvidia/vllm:26.01-py3 \
  bash

# dentro del contenedor
cd /opt/
source venv/bin/activate
vllm serve /models/cosmos-reason2-2b \
  --host 0.0.0.0 \
  --port 8000 \
  --trust-remote-code \
  --enforce-eager \
  --max-model-len 256 \
  --max-num-batched-tokens 256 \
  --gpu-memory-utilization 0.65 \
  --max-num-seqs 1 \
  --enable-chunked-prefill \
  --limit-mm-per-prompt '{"image":1,"video":1}' \
  --mm-processor-kwargs '{"num_frames":2,"max_pixels":150528}'

Estos flags ayudan a reducir uso de memoria y procesar multimedia con baja latencia. Ten en cuenta que el contexto se limita a 256 tokens por prompt.

Explicación rápida de flags claves (Orin Super Nano)

• --enforce-eager: desactiva CUDA graphs para ahorrar memoria.
• --max-model-len: limita el largo de contexto para caber en RAM.
• --gpu-memory-utilization: porcentaje de GPU que el proceso intentará usar; baja si hay OOM.
• --max-num-seqs 1: limita a una solicitud concurrente para reducir memoria máxima.
• --enable-chunked-prefill: procesa la prefill por partes, eficiente en memoria.
• --limit-mm-per-prompt: limita imágenes y videos por prompt para evitar explosión de memoria.
• --mm-processor-kwargs: reduce frames y resolución para video.

Verificación y conexión con Live VLM WebUI

1. En el Jetson, valida que el modelo esté expuesto:

curl http://localhost:8000/v1/models

2. Prueba una consulta simple:

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "/models/cosmos-reason2-2b","messages": [{"role": "user","content": "What capabilities do you have?"}],"max_tokens": 128}' | python3 -m json.tool

3. Instala y corre Live VLM WebUI para hacer streaming de webcam. Opción con uv/pip:

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
cd ~/Projects/CosmosReasoning
uv venv .live-vlm --python 3.12
source .live-vlm/bin/activate
uv pip install live-vlm-webui
live-vlm-webui

O usa el contenedor oficial de Live VLM WebUI:

git clone https://github.com/nvidia-ai-iot/live-vlm-webui.git
cd live-vlm-webui
./scripts/start_container.sh

En el navegador abre https://localhost:8090 y acepta el certificado. En la sección VLM API Config coloca http://localhost:8000/v1 y refresca para detectar el modelo.

Ajustes útiles en WebUI para Orin:

• Max Tokens: 100-150 para respuestas rápidas
• Frame Processing Interval: 60+ para dar tiempo entre frames

Problemas comunes y soluciones

• vLLM falla por OOM:

  • Ejecuta sudo sysctl -w vm.drop_caches=3 antes de arrancar.
  • Baja --gpu-memory-utilization a 0.55 o 0.50.
  • Reduce --max-model-len a 128 o menos.
  • Asegúrate de que no hay procesos GPU intensivos corriendo.

• Modelo no aparece en WebUI:

  • Verifica curl http://localhost:8000/v1/models.
  • Asegúrate de usar http:// y no https:// en la URL base.
  • Si WebUI y vLLM están en distintos contenedores, usa http://<jetson-ip>:8000/v1.

• Respuestas muy lentas:

  • Es normal en configuraciones con memoria ajustada, prioriza estabilidad sobre velocidad.
  • Reduce max_tokens y aumenta el interval de frames.

• Ruta del modelo no encontrada:

  • Verifica que la descarga de NGC completó y que la carpeta existe.
  • Revisa el -v del comando docker run y que la ruta dentro del contenedor coincida con la pasada a vllm serve.

¿Para qué sirve esto en la práctica?

Piensa en robots que describen lo que ven y justifican sus decisiones, cámaras industriales que detectan anomalías y explican por qué, o prototipos de asistencia visual que razonan sobre escenas complejas. Con Cosmos Reasoning 2B en FP8 y vLLM en Jetson puedes llevar prototipos razonadores al borde, con latencia y privacidad local.

La clave es equilibrar contexto y memoria: Thor y Orin permiten contextos largos; el Orin Super Nano requiere ajustes para caber, pero sigue siendo útil para pruebas y demos.

Fuente original

https://huggingface.co/blog/nvidia/cosmos-on-jetson