# Reinstalar ia-lab desde cero

Este manual recupera la instalación del laboratorio y explica cómo reconstruirla en una máquina nueva. El inventario se volvió a leer el **23 de septiembre de 2026**. Los comandos de instalación son para esa réplica: ejecutarlos sobre ia-lab activo interrumpiría servicios o ocuparía sus GPUs. La comprobación de esta entrega consistió en lectura del host, recuperación de scripts, pruebas CPU y canarios pequeños; no se reinstaló el sistema operativo ni se recompilaron los motores.

**Descarga el [kit de réplica](../downloads/ia-lab-replica-v4.7.zip).** Contiene este manual, bibliotecas fijadas, scripts históricos, ejemplos nuevos y manifiesto. Dentro del kit, `evidence/` conserva la procedencia; `examples/` contiene utilidades del tutorial. Los scripts históricos que reinician motores están identificados como tales. Lee cada etapa antes de ejecutarla.

[TOC]

El [catálogo de perfiles y resultados](/operar-ia-lab/perfiles/) reúne las corridas P1–P4 y matrices históricas. [Buscar archivos y rutas](/archivos/) distingue servidor, ZIP y descarga directa. [Descargas y restauración del Atlas](/descargas/) explica cómo conservar también esta web.

## 1. Qué máquina construimos y qué hay que preparar

ia-lab es una **máquina virtual KVM**, no un Linux bare-metal según la inspección del invitado. Se observan Ubuntu 24.04.4 LTS, kernel `6.8.0-139-generic`, 24 CPU virtuales (modelo expuesto Xeon E5-2680 v4), 188 GiB de RAM utilizable, sin swap y disco de 850 GiB. Aparecen cuatro RTX 3090, cada una de 24 GiB, accesibles mediante el driver NVIDIA.

Antes de reinstalar, conserva fuera del disco de destino: imágenes propias, GGUF, checkpoints originales y cuantizados, `bench/ornith`, revisiones Git, configuraciones del panel y los locks. Las claves se respaldan en almacenamiento privado; no forman parte de este sitio ni del ZIP. La web está en otro host, bajo `/srv/ornith-atlas-v3/`; restaurar ia-lab no restaura automáticamente Atlas. Ahora puedes conservarla con el [respaldo web restaurable](/descargas/), separado del kit de máquina.

Para recrear el invitado: crea una VM x86-64 con firmware y passthrough de GPU adecuados a tu hipervisor, instala Ubuntu Server 24.04 LTS en su disco nuevo, crea el usuario `lab`, habilita OpenSSH y termina las actualizaciones del sistema. Conserva al menos el almacenamiento y la RAM que demande tu selección de modelos; 4×24 GiB no se convierten en un único bloque automático de 96 GiB. Hay que distribuir explícitamente los pesos o las tareas.

**Hipervisor recuperado y verificado:** `pve-x99`, VM **101** (`ia-lab`). Se comparó el UUID SMBIOS de `qm config 101` con el UUID leído dentro del invitado: coinciden. No se cambió ninguna VM. La configuración sanitizada y la ayuda instalada de Proxmox están en `evidence/proxmox/`; se excluyeron contraseña cloud-init, clave SSH, MAC e identificadores personales.

```bash
cat /etc/os-release
uname -r
systemd-detect-virt
lscpu
free -h
lsblk -o NAME,SIZE,TYPE,MOUNTPOINTS
lspci -nn | grep -i nvidia
```

### 1.1 La máquina física y la VM que realmente tenemos

| Capa | Configuración observada el 23-09-2026 |
|---|---|
| Placa física | HUANANZHI X99-F8D PLUS |
| CPU física | Dos Xeon E5-2680 v4, 14 núcleos por socket, 56 hilos en total |
| Hipervisor | Proxmox VE 9.2.11; kernel activo `7.0.14-15-pve` |
| VM | ID 101, `q35`, **SeaBIOS**, CPU `host`, 1 socket × 24 cores, NUMA activo |
| Memoria VM | 196608 MiB configurados; balloon desactivado (`0`) |
| Disco VM | 850 GiB, VirtIO SCSI PCI, storage `vg-ia-lvmthin` |
| Storage físico | NVMe del sistema de 476.9 GiB; segundo NVMe de 931.5 GiB con VG `vg-ia` y thinpool `thinpool` de 900 GiB |
| Red | Adaptador VirtIO conectado a `vmbr0`; dirección del invitado administrada por cloud-init |
| Consola y agente | `serial0: socket`, `vga: serial0`, QEMU Guest Agent habilitado |
| Cloud-init actual | `ide2` contiene `vm-101-cloudinit`; usuario `lab`; invitado informa `DataSourceNoCloud [seed=/dev/sr0]`, sin errores |

La VM conserva un volumen EFI **sin usar**, pero el firmware activo es **SeaBIOS**. No cambies a OVMF ni conectes ese volumen porque su nombre parezca indicar la configuración correcta. El historial de creación y la configuración activa no son lo mismo.

En el host aún existen `ubuntu-24.04.3-live-server-amd64.iso` y `seed-ia.iso`. Su presencia **no demuestra** cuál fue la imagen de arranque original. No se exportó `seed-ia.iso`: puede contener configuración privada. La receta siguiente reconstruye una instalación equivalente desde ISO; no se presenta como una transcripción exacta del instalador original.

### 1.2 Preparar un Proxmox nuevo, sin tocar el que está trabajando

1. Respalda la VM y tus modelos fuera de los discos que vayas a reinstalar. Prueba que el respaldo puede leerse. Instalar Proxmox sobre un disco borra su contenido: identifica el dispositivo por modelo y número de serie, no sólo por `nvme0n1`, que puede cambiar.
2. Instala Proxmox VE en el disco destinado al sistema. Configura su administración y verifica que puedes entrar a la consola web y por SSH antes de continuar. La placa debe tener virtualización Intel y VT-d/IOMMU habilitados; no recuperamos fotos de sus menús BIOS para fingir sus nombres exactos.
3. Crea un puente `vmbr0` sobre la interfaz de red física de esa máquina. La interfaz observada se llama `nic0`; una réplica puede llamarse distinto. No dupliques la IP de `pve-x99` ni la IP del invitado en la misma red.
4. En **Disks → LVM / LVM-Thin** prepara **un disco nuevo y vacío** para VG `vg-ia` y thinpool `thinpool`. Añádelo como storage `vg-ia-lvmthin`. El proceso es destructivo para el disco elegido: no formatees el NVMe actual para seguir este tutorial. En una réplica menor puedes usar otro storage y un disco virtual menor si tus modelos caben.
5. Verifica `pvesm status`, `lsblk` y el espacio real del thinpool. Una asignación thin no reserva todo el espacio físico; deja margen para crecimiento y evita llenarlo.

La ayuda consultada fue la instalada en Proxmox (`qm help create`, `qm help set` y `qm help importdisk`); está incluida completa en el kit. Los enlaces oficiales de [PCI passthrough](https://pve.proxmox.com/wiki/PCI_Passthrough) y [Cloud-init](https://pve.proxmox.com/wiki/Cloud-Init_Support) devolvieron 403 al lector web en esta revisión; no se atribuye a esas páginas una lectura que no ocurrió.

### 1.3 IOMMU y VFIO: separar host e invitado

En **el hipervisor**, las ocho funciones PCI de las cuatro GPU usan `vfio-pci`. Allí no se carga el driver NVIDIA para inferencia. Dentro de **Ubuntu ia-lab**, sí se instala el driver NVIDIA de la sección 3. Confundir ambas capas rompe el passthrough.

El arranque observado del host usa `intel_iommu=on iommu=pt`. En una réplica que arranque con GRUB, conserva las opciones existentes y añade esas dos en `GRUB_CMDLINE_LINUX_DEFAULT` de `/etc/default/grub`; después ejecuta `update-grub`. Si tu nueva instalación usa otro cargador, identifica primero su método de actualización: no apliques instrucciones de GRUB a ciegas.

Contenido de referencia para una réplica con las mismas RTX 3090:

```text
# /etc/modules-load.d/vfio.conf
vfio
vfio_iommu_type1
vfio_pci

# /etc/modprobe.d/vfio.conf — IDs GPU y audio RTX 3090 observados
options vfio-pci ids=10de:2204,10de:1aef disable_vga=1
softdep nouveau pre: vfio-pci

# /etc/modprobe.d/blacklist-nvidia.conf — sólo en el host de passthrough
blacklist nouveau
blacklist nvidia
blacklist nvidiafb
blacklist nvidia_drm
```

El archivo real contiene además IDs de otras tarjetas (`2487/228b/2503/228e`); se conserva como evidencia, pero no hace falta copiarlos a una réplica de cuatro 3090. Vincular por ID afecta **todas** las tarjetas con ese ID en el host. Conserva otra vía de consola si tu pantalla depende de una de ellas. No uses ACS override para aparentar aislamiento que el hardware no da.

Sólo en el host nuevo, después de revisar estos archivos, ejecuta `update-initramfs -u -k all` y reinicia en una ventana de mantenimiento. Revisa:

```bash
cat /proc/cmdline
find /sys/kernel/iommu_groups -type l
lspci -nnk -s 05:00
lspci -nnk -s 82:00
lspci -nnk -s 83:00
lspci -nnk -s 84:00
```

| GPU por PCI del host | Funciones pasadas juntas | Grupo IOMMU observado |
|---|---|---:|
| `0000:05:00` | `.0` GPU + `.1` audio | 92 |
| `0000:82:00` | `.0` GPU + `.1` audio | 5 |
| `0000:83:00` | `.0` GPU + `.1` audio | 6 |
| `0000:84:00` | `.0` GPU + `.1` audio | 7 |

Estos BDF y grupos son los de `pve-x99`, no valores universales. El índice `GPU 0` dentro de Ubuntu no demuestra por sí solo a qué ranura física corresponde. Usa UUID de NVIDIA dentro del invitado y BDF del hipervisor para mantener ambas identidades separadas.

### 1.4 Crear el invitado desde una ISO, paso por paso

Usa **un VMID nuevo, no 101**, y una red/IP que no duplique ia-lab. En [Ubuntu Releases](https://releases.ubuntu.com/24.04/) elige la ISO **Server AMD64** de la versión que fijes, guarda su nombre, checksum y firma. Verifica el checksum contra el manifiesto oficial autenticado antes de importarla al storage `local`. La ISO histórica inventariada es 24.04.3; el sistema invitado observado es 24.04.4 después de actualizaciones. Una imagen nueva debe quedar registrada como nueva, no como idéntica.

En la interfaz de Proxmox: **Create VM → nombre ia-lab-replica → ISO Ubuntu Server → System q35/SeaBIOS → SCSI Controller VirtIO SCSI → disco nuevo en vg-ia-lvmthin → CPU host, 1 socket/24 cores → memoria 196608 MiB, balloon desactivado → VirtIO/vmbr0**. Si la réplica no tiene esos recursos, comienza menor y no uses luego los perfiles de contexto completo como si la geometría fuera igual.

Equivalente CLI para crear **sólo la VM nueva y su disco vacío**, después de cargar la ISO; no se ejecutó en esta entrega:

```bash
# En Proxmox nuevo. Define explícitamente estos valores antes.
: "${REPLICA_VMID:?VMID nuevo y libre, nunca 101}"
: "${REPLICA_STORAGE:?Storage existente, por ejemplo vg-ia-lvmthin}"
: "${REPLICA_ISO_VOLUME:?Volumen ISO cargado, local:iso/NOMBRE.iso}"
case "$REPLICA_VMID" in ''|*[!0-9]*) exit 1;; esac
[ "$REPLICA_VMID" != 101 ] || exit 1
if qm status "$REPLICA_VMID" >/dev/null 2>&1; then
  echo 'VMID ocupado: no se modifica'; exit 1
fi
qm create "$REPLICA_VMID" --name ia-lab-replica --machine q35 \
  --bios seabios --cpu host --sockets 1 --cores 24 --numa 1 \
  --memory 196608 --balloon 0 --hotplug 0 --agent enabled=1 \
  --scsihw virtio-scsi-pci --scsi0 "${REPLICA_STORAGE}:850" \
  --net0 virtio,bridge=vmbr0 --ide2 "${REPLICA_ISO_VOLUME},media=cdrom" \
  --serial0 socket --boot 'order=ide2;scsi0'
qm config "$REPLICA_VMID"
```

No se pasa ninguna GPU en esa orden. Arranca desde la consola web, instala Ubuntu en **el disco virtual nuevo**, elige usuario `lab` y habilita OpenSSH. Al terminar, retira la ISO y deja `scsi0` primero en el orden de arranque. Instala `qemu-guest-agent`, comprueba su servicio y verifica SSH. La consola de instalación predeterminada se conserva para este primer paso; cambia a `vga: serial0` sólo después de configurar/verificar la consola serie dentro de Ubuntu.

Para reproducir además cloud-init en una instalación desde ISO, configura explícitamente cloud-init/NoCloud y prueba la creación del usuario y la red; agregar un CD cloud-init por sí solo no prueba que el sistema lo consuma. Como alternativa existen [imágenes cloud de Ubuntu](https://cloud-images.ubuntu.com/noble/current/): se importan con `qm disk import`, se conecta el disco importado como `scsi0`, se añade el disco Cloud-init y se configura una **clave pública propia**. Comprueba el firmware requerido por esa imagen: no impongas SeaBIOS si declara sólo UEFI. No se afirma que esa alternativa sea la imagen original de 101.

### 1.5 Conectar las cuatro GPU y validar antes de instalar modelos

Con la **réplica apagada**, en Hardware → Add → PCI Device elige cada BDF verificado, marca **All Functions**, PCI Express y desactiva ROM-Bar para reproducir estos valores:

```text
hostpci2: 0000:05:00,pcie=1,rombar=0
hostpci3: 0000:82:00,pcie=1,rombar=0
hostpci4: 0000:83:00,pcie=1,rombar=0
hostpci5: 0000:84:00,pcie=1,rombar=0
```

Son líneas **de referencia de 101**, no órdenes para pegar en producción. No asignes una GPU que está conectada a otra VM activa: una réplica simultánea necesita tarjetas libres o un host diferente. No habilites “Primary GPU” para este servidor headless por costumbre. Comprueba que cada grupo contiene sólo las funciones esperadas antes de arrancar.

Dentro del nuevo Ubuntu, `lspci -nn` debe mostrar cuatro GPU y sus funciones de audio. Después de instalar el driver, `nvidia-smi` debe mostrar cuatro 3090. Comprueba también `nvidia-smi topo -m` y `nvidia-smi topo -p2p r`: cuatro GPU visibles **no prueban P2P** ni garantizan rendimiento multi-GPU. Sólo entonces continúa con paquetes, CUDA y motores.

**Límite restante:** ya recuperamos VMID, hipervisor, placa, CPU, discos, firmware, cloud-init activo, VFIO y grupos PCI. No se recreó la VM ni se probó restauración completa; tampoco se recuperó el medio/seed original con su procedencia criptográfica. Esas diferencias quedan explícitas, no se sustituyen por recuerdos inventados.

## 2. Paquetes base y acceso remoto

En la máquina nueva, después de entrar por SSH como `lab`:

```bash
sudo apt-get update
sudo apt-get install -y build-essential git git-lfs cmake ninja-build \
  python3 python3-venv python3-pip curl wget jq unzip zip tmux \
  ca-certificates gnupg pkg-config libssl-dev libcurl4-openssl-dev \
  linux-headers-$(uname -r)
git lfs install
mkdir -p /home/lab/models /home/lab/venvs /home/lab/bench/ornith
```

Git guarda el código; Git LFS/Hugging Face gestiona archivos grandes; CMake y Ninja construyen llama.cpp; los entornos virtuales aíslan dependencias de Python. El paquete `tmux` mantiene sesiones vivas cuando se desconecta SSH. El archivo `evidence/observed/host-packages.txt` conserva las versiones observadas de paquetes del sistema, no sólo los nombres de esta lista.

Accede por la red privada que hayas configurado. En el cliente puedes hacer un túnel `ssh -L 18120:127.0.0.1:8120 lab@HOST_IA_LAB` y abrir `http://127.0.0.1:18120`. Sustituye `HOST_IA_LAB` por la dirección de tu réplica. No copies las UUID de GPU de otra máquina como si fueran universales.

## 3. Driver NVIDIA: lo instalado y la comprobación

El historial de APT conserva `apt-get install -y nvidia-driver-580`. El paquete cargado al inspeccionar era `580.173.02-0ubuntu0.24.04.1`; `nvidia-smi` informa `580.173.02`. Es el driver propietario `nvidia-dkms-580` observado, no una inferencia basada en el nombre de CUDA.

```bash
# Sólo en la réplica; revisar las versiones disponibles primero.
apt-cache policy nvidia-driver-580
sudo apt-get install -y nvidia-driver-580
sudo reboot
```

Después de reconectar:

```bash
nvidia-smi
nvidia-smi --query-gpu=index,name,uuid,driver_version,memory.total --format=csv
dkms status
lsmod | grep nvidia
```

Éxito: aparecen las cuatro 3090 y no hay un error de comunicación con el driver. Si Secure Boot rechaza el módulo, resuelve la firma/inscripción MOK según la instalación de Ubuntu; reinstalar repetidamente CUDA no arregla un módulo bloqueado. Para una reproducción estricta usa las versiones guardadas **si todavía están disponibles**; un driver posterior compatible requiere repetir las pruebas. [Guía oficial de drivers de Ubuntu](https://documentation.ubuntu.com/server/how-to/graphics/install-nvidia-drivers/).

## 4. CUDA 13 y NCCL: tres versiones diferentes

En ia-lab sí existe `/usr/local/cuda-13.0`. El compilador devuelve CUDA **13.0 / nvcc 13.0.88** y APT registra `cuda-toolkit-13-0=13.0.3-1`. El historial también muestra una instalación inicial del paquete de Ubuntu `nvidia-cuda-toolkit`, seguida de su retirada al pasar a CUDA 13. En una instalación limpia se evita ese rodeo y se instala el toolkit seleccionado directamente.

No confundas: la versión máxima que muestra `nvidia-smi` corresponde al driver; `nvcc --version` corresponde al compilador del host; `torch.version.cuda` corresponde al runtime con el que se construyó la rueda de PyTorch. Pueden ser distintas y convivir.

```bash
mkdir -p /home/lab/installers
cd /home/lab/installers
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
apt-cache policy cuda-toolkit-13-0
sudo apt-get install -y cuda-toolkit-13-0
export PATH=/usr/local/cuda-13.0/bin:$PATH
nvcc --version
```

Añade la línea `export PATH=...` a la configuración de tu shell si quieres usar `nvcc` sin ruta absoluta. No hace falta reemplazar globalmente todas las librerías de los entornos Python. La documentación de NVIDIA describe la instalación mediante repositorio y las comprobaciones; aquí fijamos la familia **13.0** para corresponder al laboratorio, en vez de seguir silenciosamente la última versión. [CUDA Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/).

Para la compilación nativa, se instaló NCCL `2.28.9-1+cuda13.0`:

```bash
apt-cache policy libnccl2 libnccl-dev
sudo apt-get install -y libnccl2=2.28.9-1+cuda13.0 libnccl-dev=2.28.9-1+cuda13.0
dpkg-query -W libnccl2 libnccl-dev
```

Si APT ya no ofrece esa versión, conserva el resultado y decide una nueva combinación verificable; no continúes etiquetándola como la misma instalación. La imagen Docker histórica usa su propio runtime y su NCCL; en sus capas aparece `2.28.3-1+cuda13.0`. El NCCL del host no describe automáticamente el del contenedor.

## 5. Docker y acceso de los contenedores a las GPU

Se observan Docker CE 29.8.0, Containerd 2.3.4 y NVIDIA Container Toolkit 1.20.0. Docker no recibe CUDA por instalar PyTorch: requiere el runtime NVIDIA.

En una máquina nueva Ubuntu 24.04 x86-64, añade ambos repositorios. Este paso escribe archivos de configuración de APT; no se ejecutó en el laboratorio activo:

```bash
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
printf '%s\n' 'deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu noble stable' | sudo tee /etc/apt/sources.list.d/docker.list
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/nvidia-container-toolkit.gpg
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/etc/apt/keyrings/nvidia-container-toolkit.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
apt-cache policy docker-ce nvidia-container-toolkit
```

Luego instala/configura:

```bash
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
sudo usermod -aG docker lab
```

Cierra y abre la sesión para que se aplique el grupo. Pertenecer a `docker` da control administrativo del host; usa sólo tu cuenta administradora. Las instrucciones completas de repositorio están en [Docker Ubuntu](https://docs.docker.com/engine/install/ubuntu/) y [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).

```bash
docker version
docker run --rm --gpus all nvidia/cuda:13.0.2-runtime-ubuntu24.04 nvidia-smi
```

Éxito: el contenedor ve las GPU. Si el host las ve y Docker no, revisa el runtime de Docker. Si ninguno las ve, vuelve a driver/passthrough. El reinicio de Docker corresponde a la instalación de la réplica: no lo ejecutes durante cargas activas.

## 6. Recuperar el fork y entender sus cambios

Se encontró el checkout real en `/opt/llama.cpp`, limpio, rama `master`, remoto `https://github.com/lomeliDev/llama.cpp.git`, commit **`82490b9d43954a82d659890a2d6c74dd68cf5653`**.

```bash
mkdir -p /home/lab/src
cd /home/lab/src
git clone https://github.com/lomeliDev/llama.cpp.git
cd llama.cpp
git checkout --detach 82490b9d43954a82d659890a2d6c74dd68cf5653
git status --short
git show --stat HEAD
```

Ese commit añade un `return true` al terminar normalmente el stream en `tools/server/server-http.cpp`. El propósito es permitir reutilizar la conexión HTTP después de `sink.done()`; devolver `false` se interpreta como una cancelación por el servidor HTTP subyacente. El mensaje del commit describe pruebas de reutilización, pero sus cifras no son un benchmark de latencia repetido en esta entrega. El parche completo está en `evidence/observed/fork-sse.patch`.

FlashAttention con todos los tipos de cuantización y NCCL son además **opciones de compilación**. No todo lo que aparece en el nombre `nccl-sse-faall` es un plugin Python. No vuelvas a aplicar el parche SSE después de hacer checkout del commit: ya está incluido.

## 7. llama.cpp: imagen exacta y compilación propia

La vía más fiel para ejecutar el binario histórico es conservar o recuperar la imagen por digest:

```bash
docker pull lomelidev/llama.cpp@sha256:437ae974458c543cfa8c3566de5146e2b253d0e17ed8bf8fcfd64c250cc9e5bc
docker image inspect lomelidev/llama.cpp@sha256:437ae974458c543cfa8c3566de5146e2b253d0e17ed8bf8fcfd64c250cc9e5bc
```

Etiqueta histórica: `lomelidev/llama.cpp:cu130-nccl-sse-faall-10974`. Si el registro requiere autenticación, haz `docker login` desde tu terminal privada. También puedes guardar la imagen existente con `docker save -o llama-cu130-faall.tar IMAGEN` y restaurarla con `docker load -i llama-cu130-faall.tar`. El tar no se incluye en el kit por tamaño.

Para construir un nuevo binario nativo desde ese código:

```bash
cd /home/lab/src/llama.cpp
cmake -S . -B build-replica -DCMAKE_BUILD_TYPE=Release \
  -DGGML_CUDA=ON -DCMAKE_CUDA_COMPILER=/usr/local/cuda-13.0/bin/nvcc \
  -DCMAKE_CUDA_ARCHITECTURES=86 -DGGML_CUDA_FA=ON \
  -DGGML_CUDA_FA_QUANTS=all -DGGML_CUDA_GRAPHS=ON \
  -DGGML_CUDA_NCCL=ON -DGGML_NATIVE=ON
cmake --build build-replica -j 8 --target llama-server llama-cli llama-quantize
build-replica/bin/llama-server --version
build-replica/bin/llama-server --help
```

Arquitectura `86` corresponde a las RTX 3090. Para otra GPU cambia este objetivo según su compute capability. El CMakeCache recuperado confirma esas opciones, incluyendo `GGML_CUDA_FA_QUANTS=all`. El nombre antiguo `GGML_CUDA_FA_ALL_QUANTS` está deprecado en ese código. `-j 8` reduce la presión de RAM al compilar; no mide rendimiento de inferencia.

El log histórico de Docker registra bases CUDA `13.0.2-devel/runtime-ubuntu24.04`, Node 24 para la web, GCC/G++ 14 y build con `GGML_NATIVE=OFF`, backends dinámicos y variantes de CPU. El kit incluye el Dockerfile upstream recuperado y `examples/prepare_dockerfile.py`, que añade los flags FA/NCCL observados y fija CUDA 13.0.2:

```bash
python3 /RUTA/AL/KIT/examples/prepare_dockerfile.py /home/lab/src/llama.cpp
cd /home/lab/src/llama.cpp
docker build -f cuda-faall-replica.Dockerfile --target server \
  --build-arg CUDA_DOCKER_ARCH=86 --build-arg APP_VERSION=10974-faall \
  --build-arg APP_REVISION=82490b9d43954a82d659890a2d6c74dd68cf5653 \
  -t ornith-llama-replica:cu130-faall .
```

Esta receta reconstruida **no promete el mismo digest**: no se conservó el Dockerfile temporal original y los repositorios APT/base tags pueden cambiar. La conversación anterior permitió recuperar su ruta (`/tmp/llama-cuda-faall.Dockerfile`), la transformación del fuente y el comando de build, pero no el archivo completo ni su hash. Allí se usaba el nombre antiguo `GGML_CUDA_FA_ALL_QUANTS`; el helper usa el efectivo `GGML_CUDA_FA_QUANTS=all` contrastado con CMakeCache. El digest anterior conserva la identidad de la imagen que sí estaba en uso. [Build de llama.cpp](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md).

## 8. Descargar modelos y comprobar que son los correctos

Instala la CLI en un entorno aislado:

```bash
python3 -m venv /home/lab/venvs/hub
/home/lab/venvs/hub/bin/pip install huggingface_hub
/home/lab/venvs/hub/bin/hf download --help
```

El original HF registrado en nuestros scripts:

```bash
/home/lab/venvs/hub/bin/hf download ornith-ai/Ornith-1.5-9B \
  --revision 489cb97981b8654bcfcf30ce1f94ed1b62e07b53 \
  --local-dir /home/lab/models/Ornith-1.5-9B-original
```

Para llama.cpp, el archivo exacto por nombre existe en el repositorio comunitario de Bartowski:

```bash
/home/lab/venvs/hub/bin/hf download bartowski/Ornith-1.5-9B-GGUF \
  Ornith-1.5-9B-Q4_K_L.gguf \
  --local-dir /home/lab/models/ornith15-9b
sha256sum /home/lab/models/ornith15-9b/Ornith-1.5-9B-Q4_K_L.gguf
```

El hash del GGUF **leído de nuestro disco coincide** con el publicado: SHA-256 `545bc9901b63c09765e59a594dc782e2de5ed10b8f6095fa957d9a05a55e6b16`. Compara el resultado; si cambia, detente y registra una nueva revisión. Fija también el commit HF en tus futuras descargas. Q4_K_L no debe sustituirse por Q4_K_M sin cambiar el perfil y repetir calidad. [Archivo GGUF](https://huggingface.co/bartowski/Ornith-1.5-9B-GGUF/blob/main/Ornith-1.5-9B-Q4_K_L.gguf).

Los archivos originales HF sirven para adaptar/entrenar; el GGUF sirve para el motor de inferencia. Conserva tokenizer, plantilla, configuración y licencia. La [CLI de Hugging Face](https://huggingface.co/docs/huggingface_hub/guides/cli) permite fijar revisiones; usa `HF_TOKEN` sólo en tu entorno privado si un repositorio exige autenticación.

## 9. Lanzar llama.cpp: primero pequeño, luego el perfil de GPU 0

Antes de lanzar en una GPU, mira sus UUID, memoria utilizada y procesos. El tutorial `examples/launch_llama.sh` exige una GPU libre y un puerto libre; no mata contenedores existentes. En la réplica:

```bash
nvidia-smi --query-gpu=index,uuid,memory.used --format=csv
export ATLAS_GPU_UUID=GPU_UUID_DE_TU_REPLICA
export ATLAS_MODEL_DIR=/home/lab/models/ornith15-9b
bash /RUTA/AL/KIT/examples/launch_llama.sh small
```

Prueba inicial: 8192 tokens y un slot. Comprueba logs, salud y modelo servido:

```bash
docker logs --tail 80 ornith-replica
curl --fail http://127.0.0.1:8120/health
curl --fail http://127.0.0.1:8120/v1/models
curl --fail http://127.0.0.1:8120/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"ornith-local","messages":[{"role":"user","content":"Responde CANARIO_OK"}],"max_tokens":128,"temperature":0}'
```

Espera contenido final útil. Un HTTP 200 con `finish_reason=length` y contenido vacío no equivale a un canario correcto. El caso histórico con 32 tokens se corrigió al ampliar el presupuesto a 128; no probó incapacidad general del modelo.

La captura de GPU 0 del 23-09-2026 usa (no es el catálogo completo de perfiles): `-ngl 999 -fa on -ctk q4_0 -ctv q4_0 -c 786432 -np 3 --no-kv-unified --cont-batching --no-mmproj --n-predict 4096 -b 4096 -ub 2048 --cache-ram 32768 --cache-prompt --ctx-checkpoints 4 --jinja --metrics`. Esa configuración asigna contexto total para tres slots, 262144 por slot según el esquema usado, pero no prueba tres generaciones exitosas de contexto máximo.

El contenedor actual `ornith` monta `/home/lab/models/ornith15-9b` como **sólo lectura**, y Docker publica **0.0.0.0:8120 e IPv6**. Eso no demuestra accesibilidad por Internet: depende de la red y firewall. El launcher nuevo usa localhost para una réplica privada. La versión anterior del manual decía incorrectamente que el mapeo actual era sólo localhost; queda corregido.

## 10. Instalar vLLM con su entorno y plugin

La instalación existente está en `/home/lab/venvs/vllm`. Versiones leídas: vLLM 0.29.0, PyTorch 2.13.0+cu130, Transformers 5.17.0, bitsandbytes 0.50.2, `vllm-bnb-plugin` 0.0.3, compressed-tensors 0.17.0 y FlashInfer 0.6.18. `pip check` pasó al inspeccionar. El lock completo está en `evidence/locks/vllm-freeze.txt`.

```bash
python3 -m venv /home/lab/venvs/vllm
/home/lab/venvs/vllm/bin/pip install --upgrade pip
/home/lab/venvs/vllm/bin/pip install torch==2.13.0+cu130 \
  --index-url https://download.pytorch.org/whl/cu130
/home/lab/venvs/vllm/bin/pip install vllm==0.29.0 transformers==5.17.0 \
  bitsandbytes==0.50.2 vllm-bnb-plugin==0.0.3
/home/lab/venvs/vllm/bin/pip check
/home/lab/venvs/vllm/bin/python -c 'import torch,vllm; print(torch.__version__,torch.version.cuda,vllm.__version__)'
```

Esta secuencia es un **bootstrap con versiones principales**, no una reinstalación ya validada. Para restaurar las dependencias transitivas, usa el lock después de instalar la rueda PyTorch CUDA anterior:

```bash
/home/lab/venvs/vllm/bin/pip install --dry-run -r /RUTA/AL/KIT/evidence/locks/vllm-freeze.txt
# Si el resolver encuentra todas las versiones, en la réplica:
/home/lab/venvs/vllm/bin/pip install -r /RUTA/AL/KIT/evidence/locks/vllm-freeze.txt
/home/lab/venvs/vllm/bin/pip check
/home/lab/venvs/vllm/bin/pip freeze > /home/lab/vllm-replica-freeze.txt
diff -u /RUTA/AL/KIT/evidence/locks/vllm-freeze.txt /home/lab/vllm-replica-freeze.txt
```

Si una rueda histórica ya no está disponible, necesitas tu wheelhouse/respaldo o una combinación nueva explícitamente evaluada. No rebajes silenciosamente versiones para aparentar una reproducción exacta. [Instalación vLLM](https://docs.vllm.ai/en/latest/getting_started/installation/gpu/) y [plugin BitsAndBytes](https://github.com/vllm-project/vllm-bnb-plugin).

El perfil inicial histórico utilizó el original BF16 con carga NF4 BitsAndBytes, GPU física 2, puerto 8140, contexto 8192, dos secuencias y eager. Sus scripts `historical/vllm/setup.sh`, `start.sh` y `service.sh` se incluyen. En una réplica, cambia la UUID fija antes de lanzarlos; lee `start.sh` para ver todos los flags.

El kit trae un launcher nuevo que conserva esos argumentos pero exige la UUID de tu réplica y rechaza GPU/puerto ocupados. No necesita los wrappers que reinician procesos:

```bash
export ATLAS_GPU_UUID=GPU_UUID_LIBRE_DE_TU_REPLICA
export ATLAS_MODEL_DIR=/home/lab/models/Ornith-1.5-9B-original
bash /RUTA/AL/KIT/examples/launch_engine.sh vllm-nf4
# En otra terminal, cuando termine la carga:
python3 /RUTA/AL/KIT/examples/canary.py --base http://127.0.0.1:8140/v1 \
  --model ornith-vllm --out canario-vllm-replica.json
```

**Estado actual distinto:** el proceso observado es un vLLM nativo activo en GPU 2, puerto **8122**, modelo `/home/lab/models/Ornith-1.5-9B-AWQ-W4A16`, nombre `Ornith-1.5-9B-Sohail-AWQ-Q4KV-256K`, KV `int4_per_token_head`, contexto configurado 262144, tres secuencias y memoria 0.68. El comando está en `evidence/observed/vllm-process.txt`. No corresponde al antiguo perfil NF4/8140 y no debe duplicarse en la misma GPU.

La configuración actual apunta a pesos comunitarios distintos. El manual no descarga ni sobrescribe esos pesos. Para repetir ese perfil, registra primero su repositorio, revisión y checksum; después el comando observado. Para aprender el motor desde cero, empieza por el original fijado y el perfil 8K. Un servicio activo no equivale a superar el benchmark completo de calidad, 256K o concurrencia.

## 11. Instalar SGLang y recuperar el perfil que sí pasó las pruebas pequeñas

Entorno: `/home/lab/venvs/sglang`. SGLang 0.5.19, PyTorch informa **2.13.0+cu130 / CUDA 13.0**, Transformers 5.12.1 y compressed-tensors 0.18.0. `pip check` pasó. El lock completo está en `evidence/locks/sglang-freeze.txt`. Hay una diferencia de representación comprobada: metadata/pip dice `torch==2.13.0`, mientras el módulo importado dice `2.13.0+cu130`; ambas salidas se guardaron en `evidence/observed/sglang-torch.txt`. No deducir CPU/CUDA sólo del sufijo del freeze.

```bash
python3 -m venv /home/lab/venvs/sglang
/home/lab/venvs/sglang/bin/pip install --upgrade pip
/home/lab/venvs/sglang/bin/pip install torch==2.13.0+cu130 \
  --index-url https://download.pytorch.org/whl/cu130
/home/lab/venvs/sglang/bin/pip install sglang==0.5.19 \
  transformers==5.12.1 compressed-tensors==0.18.0
/home/lab/venvs/sglang/bin/pip check
/home/lab/venvs/sglang/bin/python -m sglang.launch_server --help
```

Comprueba dependencias completas con el lock y las instrucciones de [SGLang](https://docs.sglang.io/docs/get-started/install). Las ruedas y kernels deben corresponder a CUDA/SM86. No hace falta compilar FlashAttention por separado si el perfil probado usa Triton; instalar un backend adicional no prueba que el launcher lo seleccione.

Para fijar transitivas repite el procedimiento de `pip install --dry-run -r`, instalación, `pip check` y diff de la sección anterior, sustituyendo `vllm` por `sglang`. Después verifica también `torch.version.cuda`, no únicamente metadata.

El arranque inicial FP8 Marlin W8A16 en GPU 1 pasó canarios muy cortos, pero pruebas posteriores detectaron errores aritméticos. Por eso **no** se presenta como el mejor perfil. El registro local promovió `int8-bf16-8k`: INT8 propio por grupos 128, activaciones/KV BF16, tres solicitudes, Triton para atención y Mamba, contexto configurado 8192. El archivo congelado es `evidence/historical/modular/sglang/frozen/int8-bf16-8k.sh`. Cambia la UUID antes de usarlo en otra máquina.

Sus datos documentan 6/7 en la batería corta y recuperación 4K con concurrencias 1 y 3. “Validado” se limita a esas pruebas; el perfil 256K continuó experimental. En la inspección actual no había listener SGLang en 8130 y GPU 1 estaba libre. El servicio podría cambiar después de esa fecha.

Después de preparar los pesos INT8 de la sección siguiente, arráncalo en primer plano. Ctrl+C detiene sólo esa instancia:

```bash
export ATLAS_GPU_UUID=GPU_UUID_LIBRE_DE_TU_REPLICA
export ATLAS_MODEL_DIR=/home/lab/models/ornith-modular/full-int8-text
export ATLAS_TOKENIZER_DIR=/home/lab/models/Ornith-1.5-9B-original
bash /RUTA/AL/KIT/examples/launch_engine.sh sglang-int8
# En otra terminal:
python3 /RUTA/AL/KIT/examples/canary.py --base http://127.0.0.1:8130/v1 \
  --model ornith-sglang --out canario-sglang-replica.json
```

## 12. Cómo creamos las variantes INT8 y texto

Los scripts originales están en `evidence/historical/modular/ptq/` y `evidence/historical/modular/shared/strip_vision.py`. El original oficial fijado se conservó. `strip_vision.py` creó una copia sin tensores visuales y comparó hashes de los tensores retenidos; no fue entrenamiento ni poda de idiomas. El informe registra 912020960 bytes de visión retirados. Retirar archivos no implica ese mismo ahorro de VRAM si el runtime no los cargaba antes.

Después se crearon variantes INT8 W8A16 simétricas, grupos 128, con LLMCompressor 0.13.0 y compressed-tensors 0.18.0: `mlp_int8.py` para matrices MLP y `full_int8.py` para las lineales del texto. Lee los paths y destinos del script antes de ejecutarlo: son herramientas de conversión que escriben checkpoints grandes. Crea un directorio nuevo por experimento; no apuntes la salida al modelo original.

Una réplica del entorno de conversión empieza así:

```bash
python3 -m venv /home/lab/venvs/ornith-ptq
/home/lab/venvs/ornith-ptq/bin/pip install torch==2.13.0+cpu \
  --index-url https://download.pytorch.org/whl/cpu
/home/lab/venvs/ornith-ptq/bin/pip install \
  llmcompressor==0.13.0 compressed-tensors==0.18.0 \
  safetensors==0.8.0 transformers==5.14.1
/home/lab/venvs/ornith-ptq/bin/pip check
/home/lab/venvs/ornith-ptq/bin/python -c 'import torch; assert torch.version.cuda is None; print(torch.__version__)'
```

Este entorno usa deliberadamente **PyTorch CPU**: `full_int8.py` lo exige para no ocupar las GPU activas. El script y los manifiestos de pesos son la referencia para el resultado; esta instalación propuesta debe contrastarse con dependencias resueltas antes de una nueva conversión. El kit no contiene los gigabytes de pesos resultantes. Consulta además el [curso de compresión MoE](../laboratorio/moe/): los expertos pertenecen al 35B-A3B, no al 9B denso de estos scripts.

Pasos reales de conversión para la réplica, con suficiente disco libre para original, texto e INT8. **Escriben decenas de GB y pueden tardar; no son un canario.** Los destinos deben ser nuevos:

```bash
python3 /RUTA/AL/KIT/evidence/historical/modular/shared/strip_vision.py \
  /home/lab/models/Ornith-1.5-9B-original \
  /home/lab/models/ornith-modular/original-text
/home/lab/venvs/ornith-ptq/bin/python \
  /RUTA/AL/KIT/evidence/historical/modular/ptq/full_int8.py
```

`full_int8.py` importa su auxiliar `mlp_int8.py`, por eso ambos deben seguir juntos. Sus paths de entrada/salida están fijados a los que acabamos de preparar. Al terminar, inspecciona `component-manifest.json` y `ptq-manifest.json` y sólo entonces carga el resultado en el perfil SGLang. El estado `artifact-verified-not-runtime-tested` verifica el archivo, no que el motor haya ejecutado calidad. Para crear la variante MLP únicamente, ejecuta `mlp_int8.py` en lugar de `full_int8.py`, con otro destino ya definido en el script.

## 13. Repetir los tests: calidad, contexto, concurrencia y velocidad

Primero ejecuta pruebas CPU de las utilidades, sin arrancar modelos:

```bash
cd /RUTA/AL/KIT/evidence/historical/modular/control
python3 -m unittest -v test_control.py
cd /RUTA/AL/KIT/evidence/historical/modular/shared
python3 -m unittest -v test_bench.py
```

El controlador tiene fixtures de cambio de perfil, rollback, drenaje, puertos ocupados y SSE. Superarlos prueba el controlador con procesos simulados; no demuestra una migración real del motor. Algunas fixtures usan APIs de Linux y deben ejecutarse allí.

Para el endpoint propio: prueba salud, modelo, chat, emisión JSON de herramienta, resultado de la herramienta, segunda llamada, respuesta final, historial y streaming terminado. `examples/canary.py` aporta una prueba acotada sin ejecutar código generado. Una llamada estructurada utiliza `finish_reason=tool_calls`; el chat y la continuación final normalmente terminan en `stop`. El manual anterior confundía ambas terminaciones.

```bash
python3 /RUTA/AL/KIT/examples/canary.py --base http://127.0.0.1:8120/v1 \
  --model ornith-local --out canario-local.json
```

La batería histórica `quality.py` conserva siete casos: multiplicación, expresión aritmética, JSON estricto, extracción, `square`, suma de lista y tool call. Para evaluar código generado usa una máquina de pruebas o sandbox aislado: el filtro AST/timeout del script histórico reduce riesgos, pero no es una frontera de seguridad completa para código arbitrario.

```bash
python3 /RUTA/AL/KIT/evidence/historical/modular/shared/quality.py \
  --base http://127.0.0.1:8120/v1 --model ornith-local --out quality-local.json
```

Para recuperar marcadores a 5/50/95% de un contexto, usa `bench.py` y un tokenizer local. Instala `transformers` en el entorno de pruebas, y comienza con una sola solicitud corta:

```bash
python3 /RUTA/AL/KIT/evidence/historical/modular/shared/bench.py \
  --base http://127.0.0.1:8120/v1 --model ornith-local \
  --out /home/lab/results/retrieval-4k-r1 \
  --lengths 4096 --concurrency 1 --repeats 1 --max-output 256 \
  --tokenizer /home/lab/models/Ornith-1.5-9B-original \
  --gpu GPU_UUID_DE_TU_REPLICA
```

Después amplía 8K, 16K, 32K, 128K y 256K **sólo si** configuración, calidad y temperatura lo permiten. Usa directorios nuevos: el script rechaza resultados reutilizados. Repite varias veces y luego mide concurrencia `1,3`. Una solicitud 256K necesita margen para plantilla y salida. Tres HTTP en paralelo no prueban tres contextos residentes en GPU.

`--task throughput --max-output 512` mide otra carga; no mezcles su velocidad con recuperación corta. Registra tiempo al primer token visible, tiempo total, tokens de salida, tasa de errores y pico de VRAM. El TTFT de reasoning y el de texto visible pueden diferir. La tasa estimada entre eventos SSE no siempre equivale a tokens individuales porque un evento puede agrupar varios.

## 14. Qué resultados conservamos y cuáles no conviene promocionar

| Perfil / prueba | Evidencia recuperada | Interpretación |
|---|---|---|
| llama.cpp GPU 0 | Canario nuevo: chat, dos llamadas forzadas, continuación, historial y SSE completo, 6/6 | Contrato básico ejercitado; no es todo OpenCode/Codex |
| SGLang inicial FP8 | Smoke y aritmética iniciales correctos; recheck posterior con regresión | Sirve para estudiar instalación; no aprobar sólo por arrancar |
| SGLang INT8/BF16 8K | Registro 6/7, conserva los casos aprobados por llama; recuperación 4K c1/c3 | Aprobación acotada, no 256K general |
| SGLang INT8 E5M2 256K | Registro experimental; no aceptación completa | Mantener experimental |
| vLLM NF4 inicial | Chat, código y dos solicitudes cortas | Instalación funcional histórica |
| vLLM Q4 bajo 17 GiB | Registro 16492 MiB, 5/7; falló multiplicación y formato | Ahorro de memoria con regresión; no promocionar |
| vLLM AWQ+KV4 en 8122 | Proceso activo observado | Configuración actual, distinta del NF4 histórico |
| MTP / DFlash / visión | Scripts y resultados propios por componente | Leer cada caso; no inferir que estén activos por existir pesos |

El kit conserva `current-summary.json`, casos por motor y resultados de calidad. Algunos resultados antiguos no registraron el terminador SSE; ese dato no puede reconstruirse a posteriori. La prueba SGLang Q4 bajo 17 GiB también tuvo una corrida inválida por puerto ocupado por otro perfil: una respuesta de un proceso distinto no valida el candidato.

## 15. Panel, perfiles, mantenimiento y restauración

Continúa en [Terminales y panel](/operar-ia-lab/terminales/): sesiones `llama`, `harness`, `sglang`, `vllm`; ventanas General, Log, Check, Test, Monitor, OpenCode y Codex; teclas, servicios de Herdr/Moshi y su reinstalación.

Para listar perfiles sin activarlos: `ornithctl sglang list` y `ornithctl sglang status`. Se encontró un registro SGLang; no se encontró un registro equivalente vLLM en `modular/profiles/`. El código del controlador puede existir sin que un motor haya sido migrado a él. `use` y `rollback` cambian procesos, por eso pertenecen a una réplica o ventana de mantenimiento controlada.

En ia-lab, el entrypoint fuente recuperado es `/home/lab/bench/ornith/modular/control/ornithctl.py`; puedes usar `python3 /home/lab/bench/ornith/modular/control/ornithctl.py sglang list` si no existe el acceso corto. Sus registros y directorios auxiliares deben estar restaurados con sus paths correctos antes de utilizarlo. Para aprender sin restaurar servicios, ejecuta los tests CPU del kit; no uses `use` como prueba inocua de instalación.

Conserva un respaldo verificable de modelos, locks, scripts y la imagen Docker. Para cada cambio, escribe versión anterior, versión nueva, comandos, hashes y resultado de calidad. Si un perfil nuevo falla, arranca el anterior desde sus artefactos conservados; no reconstruyas el baseline de memoria. Nunca ejecutes como rutina de diagnóstico `ornith-opencode-final.sh`: el wrapper histórico incluye limpieza de procesos y recreación del contenedor. Se incluye para entender el trabajo previo, no como botón de salud.

**Criterio de una reinstalación terminada:** GPU visibles en host y Docker; compilación/imagen identificada; checkpoint verificado; un perfil por GPU con puerto conocido; salud y canario correctos; pruebas de calidad comparables; panel reconectable; resultados guardados. Lo que sigue pendiente debe figurar con su nombre, especialmente la reproducción del hipervisor y una reconstrucción binaria idéntica de la imagen histórica.
