Guía Llama.cpp: Capítulo 1 — Introducción e instalación

En este primer capítulo sientamos las bases: qué es llama.cpp, por qué el formato GGUF ha conquistado la inferencia local y cómo instalar el proyecto correctamente en Windows y Linux, tanto desde código fuente como con binarios precompilados.

1. ¿Qué es llama.cpp?

llama.cpp es un motor de inferencia escrito en C/C++ sin dependencias externas, pensado originalmente para ejecutar modelos de la familia LLaMA en hardware de consumo. Hoy soporta la práctica totalidad de arquitecturas abiertas: Llama 2/3, Mistral/Mixtral, Phi, Gemma, Qwen, DeepSeek, Falcon, StableLM y muchos más.

Sus señas de identidad:

• Simplicidad radical: un solo binario es capaz de ejecutar cualquier GGUF.
• Subconfiguración de hardware: CPU, GPU NVIDIA (CUDA), AMD/Intel (Vulkan, SYCL), Apple Silicon (Metal), incluso aceleradores exóticos.
• Servidor integrado: llama-server expone una API compatible con OpenAI, lista para consumir desde cualquier cliente.
• Comunidad brutal: es la base sobre la que funcionan herramientas como Ollama, LM Studio o GPT4All.

2. El formato GGUF

GGUF (GPT-Generated Unified Format) es el formato de archivo que empaqueta los pesos del modelo junto a su tokenizador, configuración y metadatos. Es lo que hace posible que un árbol de pesos de decenas de GB se convierta en un único archivo portable y cuantizado.

Conceptos clave:

• Cuantización: reducir la precisión de los pesos (de FP16 a 4 bits, por ejemplo) para ahorrar memoria a cambio de una pérdida mínima de calidad.
• Ejemplos de niveles: Q4_K_M (recomendado como equilibrio general), Q5_K_M, Q8_0 (casi sin pérdida), IQ4_XS (buena calidad en menos espacio).
• Fórmula aproximada de tamaño: tamaño ≈ parámetros × bits de la cuantización ÷ 8, más el overhead de contexto y mapeados.

💡 Cuando descargues modelos GGUF, buenos repositorios son HuggingFace - Bartowski o HuggingFace - MaziyarPanahi, que publican cuantizaciones de casi todos los modelos de moda.

3. Instalación en Windows

3.1 Opción A: binarios precompilados (recomendado para empezar)

1. Ve a la sección Releases del repositorio oficial.
2. Descarga el paquete adecuado a tu plataforma: llama-bXXXX-bin-win-cuda-x64.zip para NVIDIA o ...-win-vulkan-arm64/x64.zip para Vulkan.
3. Descomprime en una carpeta sin espacios en el nombre, p. ej. C:\llama.cpp\.
4. Verifica abriendo una terminal en esa carpeta:

.\llama-cli.exe --version

3.2 Opción B: compilar desde código fuente con Visual Studio

Requisitos: Visual Studio 2022 (workload Desktop development with C++), Git, CMake y el driver adecuado (CUDA Toolkit si vas a usar NVIDIA).

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
cmake -B build -DGGML_NATIVE=ON
cmake --build build --config Release -j

El resultado queda en build\bin\Release\.

4. Instalación en Linux

4.1 Preparar dependencias (Debian/Ubuntu)

sudo apt update
sudo apt install -y build-essential git cmake curl libcurl4-openssl-dev

4.2 Clonar y compilar

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
cmake -B build -DGGML_NATIVE=ON
cmake --build build --config Release -j$(nproc)

Ejecutables generados en build/bin/: llama-cli, llama-server, llama-quantize, etc.

💡 Consejo: instala con sudo cmake --install build o crea enlaces en ~/.local/bin para tener los binarios en el PATH.

5. Primer arranque: prueba de humo

Descarga un modelo pequeño para verificar que todo funciona:

huggingface-cli download bartowski/Llama-3.2-1B-Instruct-GGUF Llama-3.2-1B-Instruct-Q4_K_M.gguf --local-dir models/

Y lanza una generación en CLI:

./llama-cli -m models/Llama-3.2-1B-Instruct-Q4_K_M.gguf -n 128 -p "Explica qué es una red neuronal en dos frases."

Si obtienes texto coherente, tu instalación está operativa y puedes pasar al capítulo 2 para activar la GPU.

6. Errores frecuentes en la instalación

Recursos adicionales

• HuggingFace - Bartowski
• HuggingFace - MaziyarPanahi
• Documentación oficial llama.cpp