# Instalación de CUDA y llama-cpp-python en WSL2

Esta guía explica cómo instalar CUDA Toolkit y llama-cpp-python con soporte GPU en WSL2 (Windows Subsystem for Linux 2).

## Prerrequisitos

- WSL2 instalado y funcionando
- GPU NVIDIA compatible con CUDA
- Drivers de NVIDIA instalados en Windows (versión 452.39 o superior)

## Verificación inicial

### 1. Verificar GPU disponible

```bash
nvidia-smi
```

Esto debería mostrar tu GPU y la versión de CUDA disponible. Por ejemplo:
```
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.76.04              Driver Version: 580.97         CUDA Version: 13.0     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
|   0  NVIDIA GeForce RTX 3070        On  |   00000000:01:00.0  On |                  N/A |
```

### 2. Verificar distribución de Linux

```bash
cat /etc/os-release
```

## Instalación de CUDA Toolkit

### 1. Descargar e instalar el keyring de CUDA

```bash
# Descargar keyring oficial de NVIDIA
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb

# Instalar keyring
sudo dpkg -i cuda-keyring_1.1-1_all.deb
```

### 2. Actualizar repositorios e instalar CUDA

```bash
# Actualizar lista de paquetes
sudo apt update

# Instalar CUDA Toolkit (versión 12.0 recomendada para compatibilidad)
sudo apt install cuda-toolkit-12-0

# Opcional: Instalar paquetes adicionales
sudo apt install cuda cuda-toolkit cuda-tools
```

### 3. Verificar instalación de CUDA

```bash
# Verificar que nvcc esté disponible
/usr/local/cuda/bin/nvcc --version

# Debería mostrar algo como:
# nvcc: NVIDIA (R) Cuda compiler driver
# Copyright (c) 2005-2023 NVIDIA Corporation
# Built on Fri_Jan__6_16:45:21_PST_2023
# Cuda compilation tools, release 12.0, V12.0.140
```

## Instalación de compiladores necesarios

### 1. Instalar GCC-12 (requerido para WSL2)

```bash
sudo apt install gcc-12 g++-12
```

### 2. Verificar versiones de compiladores

```bash
gcc-12 --version
g++-12 --version
```

## Configuración de variables de entorno

### 1. Agregar variables al .bashrc

```bash
# Editar .bashrc
nano ~/.bashrc

# Agregar al final del archivo:
# CUDA Configuration for llama-cpp-python
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
export CC=/usr/bin/gcc-12
export CXX=/usr/bin/g++-12
export CUDAHOSTCXX=/usr/bin/g++-12
export CMAKE_ARGS="-DGGML_CUDA=on -DCMAKE_CUDA_ARCHITECTURES=all-major -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc"
export FORCE_CMAKE=1
```

### 2. Recargar configuración

```bash
source ~/.bashrc
```

### 3. Verificar variables

```bash
echo $CMAKE_ARGS
echo $PATH | grep cuda
nvcc --version
```

## Instalación de llama-cpp-python con CUDA

### Método 1: Con uv (recomendado si usas uv)

```bash
# Configurar variables en la sesión actual
export CC=/usr/bin/gcc-12
export CXX=/usr/bin/g++-12
export CUDAHOSTCXX=/usr/bin/g++-12
export CMAKE_ARGS="-DGGML_CUDA=on -DCMAKE_CUDA_ARCHITECTURES=all-major"
export FORCE_CMAKE=1

# Desinstalar versión anterior (si existe)
uv pip uninstall llama-cpp-python

# Instalar con soporte CUDA
CC=gcc-12 CXX=g++-12 uv pip install llama-cpp-python --no-cache --force-reinstall --verbose
```

### Método 2: Con pip estándar

```bash
# Configurar variables
export CC=/usr/bin/gcc-12
export CXX=/usr/bin/g++-12
export CUDAHOSTCXX=/usr/bin/g++-12
export CMAKE_ARGS="-DGGML_CUDA=on -DCMAKE_CUDA_ARCHITECTURES=all-major"
export FORCE_CMAKE=1

# Instalar
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade --verbose
```

### Método 3: Configuración específica para WSL2 (más confiable)

```bash
CMAKE_ARGS="-DGGML_CUDA=on -DCMAKE_CUDA_ARCHITECTURES=all-major" \
CC=gcc-12 \
CXX=g++-12 \
CUDAHOSTCXX=/usr/bin/g++-12 \
FORCE_CMAKE=1 \
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade
```

## Verificación de la instalación

### 1. Verificar que llama-cpp-python tiene soporte CUDA

```bash
python -c "
import llama_cpp
print('llama-cpp-python version:', llama_cpp.__version__)
print('Build info:', llama_cpp.llama_print_system_info())
"
```

**Sin CUDA** verás solo:
```
CPU : SSE3 = 1 | SSSE3 = 1 | AVX = 1 | ...
```

**Con CUDA** deberías ver:
```
CPU : SSE3 = 1 | SSSE3 = 1 | AVX = 1 | ...
GPU : CUDA = 1 | ...
```

### 2. Probar carga de modelo con GPU

```python
from llama_cpp import Llama

# Intentar cargar modelo con GPU
llama = Llama(
    model_path="./models/tu-modelo.gguf",
    n_ctx=512,
    n_gpu_layers=-1,  # Todas las capas en GPU
    verbose=True
)

# Si funciona, deberías ver en los logs:
# "load_tensors: layer X assigned to device GPU"
```

## Uso con la API

### Comandos de ejemplo

```bash
# Máximo rendimiento (todas las capas en GPU)
python main.py --model-path ./models/modelo.gguf --port 8000 --n-ctx 4096 --n-gpu-layers -1

# Solo algunas capas en GPU (para GPUs con poca memoria)
python main.py --model-path ./models/modelo.gguf --port 8000 --n-ctx 4096 --n-gpu-layers 20

# Solo CPU
python main.py --model-path ./models/modelo.gguf --port 8000 --n-ctx 4096 --n-gpu-layers 0
```

## Troubleshooting

### Problema: "CUDA not found" durante compilación

**Solución:**
1. Verificar que nvcc esté en el PATH: `which nvcc`
2. Reinstalar CUDA Toolkit si es necesario
3. Verificar variables de entorno: `echo $CMAKE_ARGS`

### Problema: Capas se asignan a CPU en lugar de GPU

**Posibles causas:**
1. llama-cpp-python compilado sin soporte CUDA
2. Memoria GPU insuficiente
3. Modelo no compatible

**Soluciones:**
1. Recompilar con variables CUDA correctas
2. Reducir `--n-gpu-layers` a un número menor
3. Verificar compatibilidad del modelo

### Problema: Error "libcudart.so not found"

**Solución:**
```bash
# Agregar librerías CUDA al path
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
sudo ldconfig
```

### Problema: Compilación muy lenta o falla

**Soluciones:**
1. Usar `FORCE_CMAKE=1` para forzar recompilación
2. Limpiar caché: `--no-cache-dir`
3. Verificar espacio en disco disponible
4. Instalar ccache para compilaciones más rápidas:
   ```bash
   sudo apt install ccache
   ```

### Problema: Error de compute capability

**Solución:**
Verificar que tu GPU sea compatible:
```bash
# Para RTX 30xx series: compute capability 8.6
# Para RTX 40xx series: compute capability 8.9
# Mínimo requerido: 3.5
```

## Verificación final

### Script de prueba completo

```python
#!/usr/bin/env python3
"""Script de verificación CUDA para llama-cpp-python"""

import llama_cpp
from pathlib import Path

def test_cuda():
    print("=== Verificación CUDA ===")
    print(f"llama-cpp-python version: {llama_cpp.__version__}")
    print(f"Build info: {llama_cpp.llama_print_system_info()}")

    # Verificar si hay referencias a CUDA/GPU
    build_info = str(llama_cpp.llama_print_system_info())
    if 'CUDA' in build_info or 'GPU' in build_info:
        print("✅ CUDA support detected!")
        return True
    else:
        print("❌ No CUDA support found")
        return False

if __name__ == "__main__":
    has_cuda = test_cuda()
    if has_cuda:
        print("\n🎉 ¡Configuración CUDA exitosa!")
    else:
        print("\n⚠️ Recompilación necesaria con soporte CUDA")
```

## Referencias

- [NVIDIA CUDA WSL Guide](https://docs.nvidia.com/cuda/wsl-user-guide/index.html)
- [llama-cpp-python GitHub](https://github.com/abetlen/llama-cpp-python)
- [WSL2 CUDA Installation Gist](https://gist.github.com/chrisbu/687cafefb87e0ddb3cb2d73301a9c64d)

## Notas importantes

1. **WSL2 específico**: Usar GCC-12 es crucial para WSL2
2. **Variables de entorno**: Deben estar configuradas antes de la compilación
3. **Paciencia**: La compilación puede tardar 10-30 minutos
4. **Memoria**: Asegúrate de tener suficiente RAM y espacio en disco
5. **Versiones**: CUDA 12.0 es la más estable para WSL2 con llama.cpp

## Comandos útiles de diagnóstico

```bash
# Verificar GPU
nvidia-smi

# Verificar CUDA
nvcc --version

# Verificar compiladores
gcc-12 --version
g++-12 --version

# Verificar variables
env | grep -E "(CUDA|CMAKE|CC|CXX)"

# Verificar librerías CUDA
ldd /usr/local/cuda/lib64/libcudart.so

# Verificar llama-cpp-python
python -c "import llama_cpp; print(llama_cpp.llama_print_system_info())"
```