Iniciación rápida de llama.cpp con CLI y servidor

Sigo volviendo a llama.cpp para la inferencia local, ya que te ofrece 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 Alojamiento de LLM en 2026: Infraestructura Local, Autoalojada y en la Nube Comparada.

Por qué llama.cpp en 2026

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

• portabilidad en CPUs y múltiples backends de GPU,
• latencia predecible en una sola máquina,
• flexibilidad de despliegue, desde portátiles hasta nodos en sitio (on-prem).

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

También es útil entender llama.cpp incluso si luego eliges un tiempo de ejecución de servidor con mayor rendimiento. Por ejemplo, si tu objetivo es el máximo rendimiento de servicio en GPUs, es posible que también quieras compararlo con vLLM usando: Puesta en marcha de vLLM: Servicio de LLM de alto rendimiento y puedes comparar herramientas mediante pruebas de rendimiento en: Ollama vs vLLM vs LM Studio: ¿La mejor forma de ejecutar LLM localmente en 2026?.

Si Ollama es específicamente la alternativa que estás sopesando frente a llama-server, llama.cpp vs Ollama en 2026 es la comparación dedicada par a par, con desencadenantes concretos para saber cuándo mantener Ollama y cuándo migrar a llama.cpp directo.

Instalar llama.cpp en Windows, macOS y Linux

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

Instalación mediante gestores de paquetes

Esta es la opción más rápida para “hacerlo funcionar”.

# 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 deseas una instalación limpia sin compiladores, usa los binarios precompilados oficiales publicados en las versiones de GitHub de llama.cpp. Generalmente cubren múltiples sistemas operativos y múltiples backends (variantes solo CPU y habilitadas para GPU).

Un flujo de trabajo común:

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

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

Compilar desde el código fuente para tu hardware exacto

Si te importa exprimir el mejor rendimiento de tu backend de CPU/GPU, compila desde el código 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 la compilación, los binarios suelen estar aquí:

ls -la ./build/bin/

Compilaciones para GPU en un solo comando

Habilita el backend que coincida con tu hardware (se muestran ejemplos 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: guía de compilación completa

En Ubuntu 24.04 con una GPU NVIDIA, necesitas el kit de herramientas CUDA y OpenSSL antes de compilar. Aquí tienes 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 (agrega al archivo ~/.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 una nueva terminal.

3. Instalar las cabeceras de desarrollo de OpenSSL (necesario 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 llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

Esto genera 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 compilació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 junto con metadatos estandarizados necesarios para 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 de Hugging Face

Las compilaciones modernas de llama.cpp pueden descargar de Hugging Face y mantener los archivos en una caché local. Esta suele ser la forma de trabajo más fácil para experimentos rápidos.

# Descarga un modelo de HF y ejecuta 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 sin conexión más adelante, --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ía elegir para la inferencia local?», ya que 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 con prioridad de CPU,
• pasa a una precisión más alta (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 un modelo mejor o una cuantización menos agresiva, no solo ajustes de muestreo.

Recuerda también que la ventana de contexto importa: los tamaños de contexto más grandes aumentan el uso de memoria (a veces dramáticamente), incluso cuando el archivo GGUF en sí cabe.

Puesta en marcha de llama-cli y parámetros clave

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

Ejecución mínima

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

Ejecución interactiva de chat

El modo de conversación está diseñado para plantillas de chat. Generalmente 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 imprima 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, centráate en las que dominan la corrección, la latencia y la memoria.

Modelo y descarga

Contexto y rendimiento

Desvío a GPU y selección de hardware

Muestreo y calidad de salida

Cargas de trabajo de ejemplo con llama-cli

Resumir un archivo, no solo un prompt

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

Hacer que los resultados sean 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 riesgos clave de esta nota de diseño." \
  -n 200 \
  --seed 42 \
  --temp 0.2

Puesta en marcha de llama-server con API compatible con OpenAI

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

• puntos finales compatibles con OpenAI para chat, completados, 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 vincular externamente (por ejemplo, dentro de Docker o una LAN), especifica el host y el puerto:

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

Banderas opcionales pero importantes del servidor

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

Llamadas de API de ejemplo

Completados 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 implementaciones reales: si configuras --api-key, puedes enviarlo mediante una cabecera x-api-key (o seguir usando cabeceras de Authorization dependiendo de tu pasarela).

Cliente de 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 threads vs batch size 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 incrustación 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 deseas ejecutar llama-cpp con un modelo de incrustación 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 /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "tu texto aquí" \
  --pooling last \
  --verbose-prompt

Servicio de múltiples modelos desde un solo proceso

Los ejemplos anteriores vinculan llama-server a un solo modelo al inicio. Si necesitas cambiar entre modelos en cada solicitud — sin reiniciar el proceso —, para eso es el modo de enrutador. Consulta Modo de enrutador de llama-server: conmutación dinámica de modelos sin reinicios. Para un flujo de descarga de todos los elementos que libera VRAM sin reiniciar el enrutador, consulta Descargar todos los modelos del enrutador de llama.cpp sin reiniciar.

Rendimiento, monitoreo y endurecimiento para producción

La pregunta frecuente «¿Qué opciones de línea de comandos de llama.cpp importan más para la velocidad y la memoria?» se vuelve mucho más fácil cuando tratas la inferencia como un sistema:

• El límite de memoria suele ser la primera restricción (RAM en CPU, VRAM en GPU).
• El tamaño del contexto es un multiplicador de memoria importante.
• El desvío de capas a GPU suele ser la ruta más rápida para obtener más tokens por segundo.
• Los tamaños de lote y los hilos pueden mejorar el rendimiento, pero también pueden aumentar la presión de memoria.

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

Si deseas resultados medidos estilo llama-cli en una GPU de clase 16 GB—tokens por segundo, VRAM y carga de GPU mientras varías el contexto (19K / 32K / 64K) en GGUF densos y MoE—consulta Benchmarks de LLM con llama.cpp para 16 GB de VRAM (velocidad y contexto).

Específicamente para Qwen 3.6, llama.cpp ahora soporta la decodificación especulativa de Predicción de Tokens Múltiplos (MTP) integrada que puede aumentar significativamente el rendimiento de la generación. Para una guía completa que cubra todos los métodos de decodificación especulativa en llama.cpp, consulta Decodificación Especulativa. Para benchmarks específicos de MTP de Qwen 3.6, consulta Qwen 3.6 MTP vs Estándar en GPU de 16GB.

Monitoreo de llama-server con Prometheus y Grafana

llama-server puede exponer métricas compatibles con Prometheus en /metrics cuando --metrics está habilitado. Esto combina naturalmente con configuraciones de scraping de Prometheus y 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: Guía de Monitoreo, Métricas, 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á del localhost:

• usa --api-key (o --api-key-file) para que las solicitudes estén 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 para la resolución de problemas

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

Los puntos finales de chat funcionan mejor cuando el modelo tiene una plantilla de chat compatible. Si las salidas parecen desestructuradas, prueba:

• usar llama-cli --conversation junto con un --system-prompt explícito,
• verificar que tu modelo sea una variante instruida o ajustada para chat,
• probar usando la interfaz web del servidor antes de integrarlo en una aplicación.

Has agotado la 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,
• validando que instalaste una compilación que coincide con tu máquina (características de CPU y backend).

Referencias

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