llama_cpp_local/docs/WSL2_CUDA_Installation.md

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

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

cat /etc/os-release

Instalación de CUDA Toolkit

1. Descargar e instalar el keyring de CUDA

# 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

# 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

# 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)

sudo apt install gcc-12 g++-12

2. Verificar versiones de compiladores

gcc-12 --version
g++-12 --version

Configuración de variables de entorno

1. Agregar variables al .bashrc

# 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

source ~/.bashrc

3. Verificar variables

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)

# 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

# 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)

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

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

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

# 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:

# 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:

   sudo apt install ccache
   

Problema: Error de compute capability

Solución: Verificar que tu GPU sea compatible:

# 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

#!/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
• llama-cpp-python GitHub
• WSL2 CUDA Installation Gist

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

# 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())"