Guía de Instalación en Linux

Configura AVA SDK en Linux nativo (Ubuntu 24.04) con Docker y NVIDIA Container Toolkit. Sin WSL2, sin Windows — Linux puro.

AVA SDK en Linux Nativo

Aunque la Lección 01 cubre la configuración vía WSL2 en Windows, ejecutar AVA SDK directamente en Linux ofrece mejor rendimiento, menor latencia y acceso directo al hardware. Esta guía cubre la instalación completa en Ubuntu 24.04 LTS, el sistema operativo recomendado para desarrollo con AVA SDK.

¿Vienes de Windows?

Si usas Windows, consulta la Lección 01: Entorno de Ejecución para la guía de configuración con WSL2.

Requisitos Previos

Ubuntu 24.04 LTS (también compatible con 22.04)

GPU NVIDIA con al menos 8 GB de VRAM

16 GB de RAM o más

50 GB de espacio libre en disco

Conexión a internet para descargar modelos

Acceso sudo (administrador del sistema)

Instalación Paso a Paso

Paso 1: Instalar Docker Engine

Instala Docker Engine directamente en Ubuntu. A diferencia de WSL2, no necesitas Docker Desktop ni configuraciones adicionales de red.

# Eliminar versiones antiguas si existen
sudo apt remove docker docker-engine docker.io containerd runc

# Instalar dependencias
sudo apt update
sudo apt install -y ca-certificates curl

# Añadir clave GPG oficial de Docker
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Añadir repositorio
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Añadir tu usuario al grupo docker (evita usar sudo en cada comando)
sudo usermod -aG docker $USER
newgrp docker

Paso 2: Instalar NVIDIA Container Toolkit

El NVIDIA Container Toolkit permite que Docker acceda a tu GPU NVIDIA. Esto es lo que hace posible ejecutar modelos de IA localmente con aceleración por hardware.

# Añadir repositorio NVIDIA
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Instalar
sudo apt update
sudo apt install -y nvidia-container-toolkit

# Configurar Docker para usar el runtime NVIDIA
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Verificar instalación
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

Paso 3: Clonar y Configurar AVA SDK

Descarga el repositorio del Razer AI Kit y prepara el entorno de ejecución con Docker Compose.

# Clonar el repositorio oficial
git clone https://github.com/razerofficial/aikit.git
cd aikit

# Construir y levantar los servicios con Docker Compose
docker compose up -d

# Verificar que los contenedores están corriendo
docker compose ps

Paso 4: Ejecutar tu Primera Inferencia

Una vez que los contenedores están activos, ejecuta el script de prueba para verificar que todo funciona correctamente.

# Entrar al contenedor de desarrollo
docker compose exec dev bash

# Dentro del contenedor, ejecutar inferencia de prueba
python scripts/inference_test.py

# Si todo funciona, verás la respuesta del modelo en la terminal

Linux Nativo vs WSL2

Ejecutar AVA SDK en Linux nativo ofrece varias ventajas sobre WSL2 en Windows. Si tienes la opción, Linux es el entorno recomendado para desarrollo y producción.

Acceso Directo a GPU

Sin capa de virtualización entre el sistema operativo y la GPU. Menor latencia y mejor rendimiento.

Gestión de Memoria

Linux gestiona la RAM sin la limitación del 50% que impone WSL2 por defecto. Los modelos grandes se benefician de esto.

Docker Nativo

Sin necesidad de Docker Desktop ni configuraciones de red puenteadas. Docker corre directamente sobre el kernel.

Menos Capas

Sin la traducción Windows→WSL→Linux→Docker. Cada capa eliminada es un punto de fallo menos y un aumento de rendimiento.

Solución de Problemas

Error: "could not select device driver"

Significa que el NVIDIA Container Toolkit no está correctamente configurado. Ejecuta sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker y vuelve a intentarlo.

Docker no arranca después de instalar

Verifica que el servicio está activo: sudo systemctl status docker. Si está inactivo, arráncalo con sudo systemctl enable --now docker.

Error de permisos al ejecutar docker sin sudo

Asegúrate de haber añadido tu usuario al grupo docker: sudo usermod -aG docker $USER. Cierra la sesión y vuelve a entrar para que los cambios surtan efecto.

La GPU no aparece en nvidia-smi dentro del contenedor

Comprueba que los drivers NVIDIA están instalados en el host: nvidia-smi. Si no funciona en el host, instala los drivers primero: sudo apt install nvidia-driver-550.

Error de espacio en disco durante la descarga de modelos

Los modelos de lenguaje pueden ocupar entre 5 y 30 GB cada uno. Asegúrate de tener al menos 50 GB libres. Puedes cambiar el directorio de descarga de modelos en la configuración de Docker Compose.

¿Todo listo?

Continúa con la documentación técnica y aprende a personalizar AVA SDK.

Explorar Documentación

Preguntas Frecuentes sobre Linux

¿Puedo usar otra distribución que no sea Ubuntu?

Sí, aunque Ubuntu 24.04 LTS es la distribución recomendada y sobre la que probamos. Fedora, Debian y Arch Linux también funcionan, pero los comandos de instalación de paquetes variarán. La parte de Docker y NVIDIA Container Toolkit es común a todas las distribuciones.

¿AVA SDK funciona en Linux sin GPU NVIDIA?

No de forma práctica. El Razer AI Kit requiere aceleración CUDA, que solo está disponible en GPUs NVIDIA. GPU AMD (ROCm) y Intel (OneAPI) no están soportadas actualmente.

¿Qué rendimiento puedo esperar en Linux vs WSL2?

En Linux nativo puedes esperar entre un 5-15% más de rendimiento en inferencia comparado con WSL2, principalmente por la eliminación de la capa de virtualización y la gestión de memoria más eficiente.

¿Puedo ejecutar AVA SDK en un VPS o servidor cloud?

Sí, siempre que el VPS tenga una GPU NVIDIA dedicada. Proveedores como Lambda Labs, Vast.ai y RunPod ofrecen instancias con GPU a precios competitivos. Solo necesitas instalar Docker y NVIDIA Container Toolkit siguiendo esta misma guía.