Inicio rápido de llama.cpp con CLI y servidor

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

Si aún estás decidiendo entre enfoques locales, autoalojados y en la nube, comienza con la guía fundamental Hosting de LLM en 2026: Comparativa de Infraestructura Local, Autoalojada 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 portátiles hasta nodos on-premise.

Brilla cuando deseas privacidad y operación offline, cuando necesitas un control determinista sobre las banderas de tiempo de ejecución, o cuando quieres integrar la inferencia en un sistema más grande sin ejecutar un stack pesado de Python.

También es útil entender llama.cpp incluso si luego eliges un runtime de servidor de mayor rendimiento. Por ejemplo, si tu objetivo es el máximo rendimiento de servicio en GPUs, podrías querer compararlo con vLLM usando: vLLM Quickstart: Servicio de LLM de alto rendimiento y puedes realizar pruebas de rendimiento de las herramientas en: Ollama vs vLLM vs LM Studio: ¿La mejor forma de ejecutar LLMs localmente en 2026?.

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

Hay tres rutas de instalación prácticas, dependiendo de si buscas comodidad, portabilidad o rendimiento máximo.

Instalación mediante gestores de paquetes

Esta es la opción más rápida de “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

Instalación mediante binarios precompilados

Si quieres una instalación limpia sin compiladores, usa los binarios precompilados oficiales publicados en los releases de GitHub de llama.cpp. Típicamente cubren múltiples objetivos de sistema operativo y múltiples backends (variantes solo CPU y habilitadas para GPU).

Un flujo de trabajo común:

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

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

Construcción desde el código fuente para tu hardware exacto

Si te importa exprimir el mejor rendimiento de tu backend de CPU/GPU, construye desde el código fuente con CMake.

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

# Construcción CPU
cmake -B build
cmake --build build --config Release

Después de la construcción, los binarios suelen estar aquí:

ls -la ./build/bin/

Construcciones de GPU en un solo comando

Habilita el backend que coincide 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 + GPU NVIDIA: recorrido completo de construcción

En Ubuntu 24.04 con una GPU NVIDIA, necesitas el toolkit de CUDA y OpenSSL antes de construir. Aquí tienes una secuencia probada:

1. Instalar toolkit 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ñadir a ~/.bashrc):

# cuda toolkit
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 cabeceras de desarrollo de OpenSSL (necesario para una construcción limpia):

sudo apt update
sudo apt install libssl-dev

4. Construir 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 llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

Esto produce llama-cli, llama-mtmd-cli, llama-server, llama-embedding 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 la misma construcción en máquinas heterogéneas.

Elige un modelo GGUF y una cuantización

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

Dos formas de obtener un modelo

Opción A: Usar 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: Dejar que llama.cpp descargue desde Hugging Face

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

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

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

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

Si necesitas un flujo de trabajo totalmente offline más tarde, --offline fuerza el uso de la caché y previene el acceso a la red.

Elección de cuantización para inferencia local

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

Un punto de partida pragmático:

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

Recuerda también que la ventana de contexto importa: tamaños de contexto más grandes aumentan el uso de memoria (a veces drásticamente), incluso cuando el archivo GGUF encaja.

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 de TCP vs UDP." \
  -n 200

Ejecución de chat interactivo

El modo de conversación está diseñado para plantillas de chat. Típicamente habilita el 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.

Principales banderas de llama-cli que importan

En lugar de memorizar 200 banderas, céntrate en las que dominan la corrección, la latencia y la memoria.

Modelo y descarga

Contexto y rendimiento

Descarga de GPU y selección de hardware

Muestreo y calidad de salida

Cargas de trabajo de ejemplo con llama-cli

Resumen de 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 resultados más reproducibles

Cuando depuras prompts, fija la semilla y reduce la aleatoriedad:

llama-cli \
  -m models/my-model.gguf \
  -p "Extrae los riesgos clave 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:

• endpoints compatibles con OpenAI para chat, completaciones, incrustaciones y respuestas,
• una interfaz web para pruebas interactivas,
• endpoints 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 vincular externamente (por ejemplo, dentro de Docker o una LAN), especifica host y puerto:

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

Banderas del servidor opcionales pero importantes

Si ejecutas en contenedores, muchos ajustes también se pueden controlar a través de variables de entorno LLAMA_ARG_*.

Ejemplos de llamadas a la 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 lista de verificación rápida de llama.cpp." }
    ],
    "temperature": 0.7
  }'

Consejo para despliegues reales: si configuras --api-key, puedes enviarlo mediante un encabezado x-api-key (o seguir usando encabezados Authorization 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 (Embeddings)

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 de incrustaciones dedicado, considera iniciar el servidor en modo solo incrustaciones:

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

o si quieres ejecutar llama-cpp con modelo de incrustaciones en CPU:

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

pruébalo así:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /ruta/a/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "tu texto aquí" \
  --pooling last \
  --verbose-prompt

Servir múltiples modelos desde un solo proceso

Los ejemplos anteriores vinculan llama-server a un solo modelo al inicio. Si necesitas cambiar entre modelos por solicitud — sin reiniciar el proceso — eso es para lo que sirve el modo enrutador. Consulta Modo enrutador de llama-server: cambio dinámico de modelos sin reinicios.

Rendimiento, monitoreo y endurecimiento para producción

La pregunta de la FAQ “¿Qué 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:

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

Para una visión más profunda, orientada a ingeniería, consulta: Rendimiento de LLM en 2026: Benchmarks, Cuellos de Botella y Optimización.

Si quieres resultados de estilo llama-cli medidos en una GPU de clase 16 GB —tokens por segundo, VRAM y carga de GPU al barrer contexto (19K / 32K / 64K) a través de GGUF densos y MoE— consulta Benchmarks de LLM con 16 GB VRAM con llama.cpp (velocidad y contexto).

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 empareja naturalmente con las configuraciones de raspado de Prometheus y los paneles de Grafana.

Para paneles y alertas específicos de llama.cpp (y vLLM, TGI): Monitorear Inferencia de LLM en Producción (2026): Prometheus y Grafana para vLLM, TGI, llama.cpp. Guías más amplias: Observabilidad: Monitoreo, Métricas, Guía de Prometheus y Grafana y Observabilidad para Sistemas de LLM.

Lista de verificación básica de endurecimiento

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

• usa --api-key (o --api-key-file) para que las solicitudes sean autenticadas,
• evita vincular 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 de problemas

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

Los endpoints de chat son mejores cuando el modelo tiene una plantilla de chat soportada. Si las salidas parecen sin estructura, prueba:

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

Llegas al límite de memoria

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

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

Es lento en CPU

Comienza con:

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

Referencias

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