Quickstart de llama.cpp con CLI y servidor

Sigo volviendo a llama.cpp para la inferencia local, ya que me da el control que Ollama y otros abstraen, y simplemente funciona. Fácil de ejecutar modelos GGUF de forma interactiva con llama-cli o exponer una API HTTP OpenAI-compatible con llama-server.

Si aún estás decidiendo entre enfoques locales, autohospedados y en la nube, empieza con la guía de pilares LLM Hosting en 2026: Comparación de infraestructura local, autohospedada y en la nube.

¿Por qué llama.cpp en 2026

llama.cpp es un motor de inferencia ligero con un sesgo hacia:

• portabilidad entre CPUs y múltiples backends de GPU,
• latencia predecible en una sola máquina,
• flexibilidad de despliegue, desde laptops hasta nodos on-prem.

Brilla cuando deseas privacidad y operación offline, cuando necesitas control determinístico sobre las banderas de tiempo de ejecución, o cuando quieres incrustar la inferencia en un sistema más grande sin ejecutar una pila pesada en Python.

También es útil comprender llama.cpp incluso si luego elijes un entorno de tiempo de ejecución de servidor de mayor throughput. Por ejemplo, si tu objetivo es el máximo throughput de servicio en GPUs, también podrías querer compararlo con vLLM usando: vLLM Quickstart: LLM Serving de Alto Rendimiento y puedes evaluar opciones de herramientas en: Ollama vs vLLM vs LM Studio: Mejor forma de ejecutar LLMs localmente en 2026?.

Instalación de llama.cpp en Windows, macOS y Linux

Hay tres caminos prácticos de instalación, dependiendo de si deseas conveniencia, portabilidad o máximo rendimiento.

Instalar mediante gestores de paquetes

Esta es la opción más rápida para “ponerlo en marcha”.

# macOS o Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS o Linux (Nix)
nix profile install nixpkgs#llama-cpp

Consejo: después de instalar, verifica que las herramientas existan:

llama-cli --version
llama-server --version

Instalar mediante binarios precompilados

Si deseas una instalación limpia sin compiladores, usa los binarios precompilados oficiales publicados en los lanzamientos de llama.cpp en GitHub. Normalmente cubren múltiples objetivos de OS y múltiples backends (variantes solo CPU y con GPU).

Un flujo de trabajo común:

# 1) Descargar el archivo correcto para tu OS y backend
# 2) Extraerlo
# 3) Ejecutar desde la carpeta extraída

./llama-cli --help
./llama-server --help

Compilar desde la fuente para tu hardware exacto

Si te importa sacar el máximo rendimiento de tu backend de CPU/GPU, compila desde la fuente con CMake.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# Compilación para CPU
cmake -B build
cmake --build build --config Release

Después de compilar, los binarios suelen estar aquí:

ls -la ./build/bin/

Compilación para GPU en un solo comando

Habilita el backend que coincida con tu hardware (ejemplos mostrados para CUDA y Vulkan):

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + NVIDIA GPU: recorrido completo de compilación

En Ubuntu 24.04 con una GPU NVIDIA, necesitas el kit de herramientas CUDA y OpenSSL antes de compilar. Aquí hay una secuencia probada:

1. Instalar el kit de herramientas CUDA 13.1

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. Añadir CUDA a tu entorno (añade al final de ~/.bashrc):

# kit de herramientas CUDA
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

Luego ejecuta source ~/.bashrc o abre un nuevo terminal.

3. Instalar encabezados de desarrollo de OpenSSL (requeridos para una compilación limpia):

sudo apt update
sudo apt install libssl-dev

4. Compilar llama.cpp (desde el directorio que contiene tu clon de llama.cpp, con CUDA habilitado):

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

Esto genera llama-cli, llama-mtmd-cli, llama-server y llama-gguf-split en el directorio llama.cpp.

También puedes compilar múltiples backends y elegir dispositivos en tiempo de ejecución. Esto es útil si despliegas el mismo build en máquinas heterogéneas.

Elige un modelo GGUF y una cuantización

Para ejecutar inferencia, necesitas un archivo de modelo GGUF (*.gguf). GGUF es un formato de archivo único que combina pesos del modelo más metadatos estandarizados necesarios para motores como llama.cpp.

Dos formas de obtener un modelo

Opción A: Usa un archivo GGUF local

Descarga o copia un GGUF en ./models/:

mkdir -p models
# Coloca tu GGUF en models/my-model.gguf

Luego ejecútalo por ruta:

llama-cli -m models/my-model.gguf -p "¡Hola! Explica qué es llama.cpp." -n 128

Opción B: Deja que llama.cpp descargue desde Hugging Face

Las construcciones modernas de llama.cpp pueden descargar desde Hugging Face y mantener los archivos en un caché local. Esto suele ser el flujo de trabajo más fácil para experimentos rápidos.

# Descargar un modelo desde HF y ejecutar un prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Había una vez," \
  -n 200

También puedes especificar la cuantización en el selector de repositorio y dejar que la herramienta elija un archivo coincidente:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Resuma el concepto de cuantización en un párrafo." \
  -n 160

Si necesitas un flujo de trabajo completamente offline después, --offline fuerza el uso del caché y evita el acceso a la red.

Elección de cuantización para inferencia local

La cuantización es la respuesta práctica a la pregunta “¿Cuál cuantización GGUF debería elegir para inferencia local” porque intercambia directamente calidad, tamaño del modelo y velocidad.

Un punto de partida pragmático:

• empieza con una variante Q4 o Q5 para máquinas centradas en CPU,
• mueve a una precisión mayor (o menos agresiva) cuando puedas permitirte la RAM o VRAM,
• cuando el modelo “se sienta tonto” para tu tarea, la solución suele ser ya sea un mejor modelo o una cuantización menos agresiva, no solo ajustes de muestreo.

También recuerda que el tamaño del contexto importa: los tamaños de contexto más grandes aumentan el uso de memoria (a veces drásticamente), incluso cuando el archivo GGUF en sí mismo se ajuste.

Inicio rápido de llama-cli y parámetros clave

llama-cli es la forma más rápida de validar que tu modelo se carga, tu backend funciona y tus prompts se comportan.

Ejecución mínima

llama-cli \
  -m models/my-model.gguf \
  -p "Escribe una comparación breve entre TCP y UDP." \
  -n 200

Ejecución de chat interactivo

El modo de conversación está diseñado para plantillas de chat. Normalmente habilita comportamiento interactivo y formatea los prompts según la plantilla del modelo.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Eres un asistente de ingeniería de sistemas conciso." \
  --ctx-size 4096

Para finalizar la generación cuando el modelo imprime una secuencia específica, usa un prompt inverso. Esto es especialmente útil en modo interactivo.

Banderas principales de llama-cli que importan

En lugar de memorizar 200 banderas, enfócate en las que dominan la precisión, latencia y memoria.

Modelo y descarga

Contexto y throughput

Desplazamiento de GPU y selección de hardware

Muestreo y calidad de salida

Ejemplos de cargas de trabajo con llama-cli

Resumir un archivo, no solo un prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Resumes documentos técnicos. Máximo cinco viñetas." \
  --file ./docs/incident-report.txt \
  -n 300

Hacer los resultados más reproducibles

Cuando estás depurando prompts, fija la semilla y reduce la aleatoriedad:

llama-cli \
  -m models/my-model.gguf \
  -p "Extrae los principales riesgos de esta nota de diseño." \
  -n 200 \
  --seed 42 \
  --temp 0.2

Inicio rápido de llama-server con API compatible con OpenAI

llama-server es un servidor HTTP integrado que puede exponer:

• puntos finales compatibles con OpenAI para chat, completaciones, incrustaciones y respuestas,
• una interfaz web para pruebas interactivas,
• puntos finales de monitoreo opcionales para visibilidad en producción.

Iniciar un servidor con un modelo local

llama-server \
  -m models/my-model.gguf \
  -c 4096

Por defecto, escucha en 127.0.0.1:8080.

Para enlazar externamente (por ejemplo dentro de Docker o una LAN), especifique host y puerto:

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

Banderas del servidor importantes pero opcionales

Si ejecutas en contenedores, muchas configuraciones también pueden controlarse mediante variables de entorno LLAMA_ARG_*.

Ejemplos de llamadas API

Completaciones de chat con curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "Eres un asistente útil." },
      { "role": "user", "content": "Dame una rápida lista de verificación de llama.cpp." }
    ],
    "temperature": 0.7
  }'

Consejo para despliegues reales: si estableces --api-key, puedes enviarla mediante un encabezado x-api-key (o continuar usando encabezados de autorización según tu gateway).

Cliente Python de OpenAI apuntando a llama-server

Con un servidor compatible con OpenAI, muchos clientes pueden funcionar cambiando solo base_url.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "Eres un asistente conciso."},
        {"role": "user", "content": "Explica hilos vs tamaño de lote en llama.cpp."}
    ],
)

print(resp.choices[0].message.content)

Incrustaciones

Las incrustaciones compatibles con OpenAI se exponen en /v1/embeddings, pero el modelo debe soportar un modo de agrupación de incrustaciones que no sea none.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hola", "mundo"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

Si ejecutas un modelo dedicado de incrustaciones, considera iniciar el servidor en modo de incrustaciones solo:

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

Rendimiento, monitoreo y fortalecimiento para producción

La pregunta frecuente en FAQ “¿Cuáles opciones de línea de comandos de llama.cpp importan más para velocidad y memoria” se vuelve mucho más fácil cuando tratas la inferencia como un sistema:

• Límite de memoria suele ser la primera restricción (RAM en CPU, VRAM en GPU).
• Tamaño de contexto es un multiplicador importante de memoria.
• Desplazamiento de capas de GPU suele ser el camino más rápido hacia más tokens por segundo.
• Tamaños de lote y hilos pueden mejorar el throughput pero también pueden aumentar la presión de memoria.

Para una visión más profunda, centrada en ingeniería, consulta: Desempeño de LLM en 2026: Benchmarks, cuellos de botella y optimización.

Monitoreo de llama-server con Prometheus y Grafana

llama-server puede exponer métricas compatibles con Prometheus en /metrics cuando se habilita --metrics. Esto se combina naturalmente con Prometheus configuraciones de scrape y dashboards de Grafana.

Para dashboards y alertas específicas de llama.cpp (y vLLM, TGI): Monitoreo de inferencia de LLM en producción (2026): Prometheus y Grafana para vLLM, TGI, llama.cpp. Guías más amplias: Observabilidad: Guía de monitoreo, métricas, Prometheus y Grafana y Observabilidad para sistemas de LLM.

Lista de verificación básica de fortalecimiento

Cuando tu llama-server es accesible más allá de localhost:

• usa --api-key (o --api-key-file) para que las solicitudes estén autenticadas,
• evita enlazar a 0.0.0.0 a menos que lo necesites,
• considera TLS mediante las banderas SSL del servidor o termina TLS en un proxy inverso,
• restringe la concurrencia con --parallel para proteger la latencia bajo carga.

Soluciones rápidas para problemas de solución

El modelo carga pero las respuestas son extrañas en chat

Los endpoints de chat funcionan mejor cuando el modelo tiene una plantilla de chat compatible. Si las salidas parecen no estructuradas, intenta:

• usar llama-cli --conversation más un --system-prompt explícito,
• verificar que tu modelo sea una variante de instrucción o de chat ajustado,
• probar usando la interfaz web del servidor antes de conectarlo a una aplicación.

Te quedas sin memoria

Reduce el contexto o elige una cuantización más pequeña:

• reduce --ctx-size,
• reduce --n-gpu-layers si el problema es la VRAM,
• cambia a un modelo más pequeño o a una cuantización más comprimida.

Es lento en CPU

Empieza con:

• --threads igual a tus núcleos físicos,
• tamaños de lote moderados,
• validando que instalaste una compilación que coincide con tu máquina (características de CPU y backend).

Referencias

• Repositorio y documentación oficiales de llama.cpp
• Documentación oficial de banderas de CLI
• Documentación oficial de llama-server y detalles de API