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

Sigo volviendo a llama.cpp para la inferencia local: te ofrece un control que Ollama y otras herramientas 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 principal: LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

Por qué llama.cpp en 2026

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

• portabilidad entre CPUs y múltiples backends de GPU,
• latencia predecible en una sola máquina,
• flexibilidad de despliegue, desde portátiles hasta nodos en las instalaciones (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 infraestructura pesada basada en Python.

También es útil comprender llama.cpp incluso si luego eliges un servidor de tiempo de ejecución con mayor rendimiento. Por ejemplo, si tu objetivo es el máximo rendimiento de servicio en GPUs, también podrías compararlo con vLLM utilizando: vLLM Quickstart: High-Performance LLM Serving y puedes realizar pruebas de rendimiento de las herramientas en: Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Instalar llama.cpp en Windows, macOS y Linux

Existen tres vías prácticas de instalación, dependiendo de si buscas conveniencia, portabilidad o rendimiento máximo.

Instalación mediante gestores de paquetes

Esta es la opción más rápida para “tenerlo funcionando”.

# 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, utiliza los binarios precompilados oficiales publicados en los lanzamientos de llama.cpp en GitHub. Generalmente 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) Descarga el archivo correcto para tu sistema operativo y backend
# 2) Extraelo
# 3) Ejecuta desde la carpeta extraída

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

Compilar desde el código fuente para tu hardware exacto

Si te preocupa 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 (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: guía completa de compilación

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. Agregar CUDA a tu entorno (añadir al archivo ~/.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 una nueva terminal.

3. Instalar los 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 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 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 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 compilaciones modernas de llama.cpp pueden descargar desde Hugging Face y mantener los archivos en una caché local. Este 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 "Había 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 tarde, --offline fuerza el uso de la 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 “¿Qué cuantización GGUF deberías elegir para la 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 centradas en CPU,
• pasa a mayor precisión (o 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 mejor modelo o una cuantización menos agresiva, no solo ajustes de muestreo.

También recuerda 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.

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

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

Ejecución mínima

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

Ejecución de chat interactivo

El modo 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 imprime una secuencia específica, usa un prompt inverso (reverse prompt). Esto es especialmente útil en modo interactivo.

Principales banderas de llama-cli que importan

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

Modelo y descarga

Contexto y rendimiento

Descarga 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. Máximo cinco puntos." \
  --file ./docs/incident-report.txt \
  -n 300

Hacer los resultados más reproducibles

Cuando depures 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 (embeddings) y respuestas,
• una interfaz web (Web UI) 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 en 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, muchas configuraciones también pueden controlarse mediante variables de entorno LLAMA_ARG_*.

Ejemplos de llamadas a 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 estableces --api-key, puedes enviarla mediante un encabezado x-api-key (o seguir usando encabezados Authorization dependiendo de tu puerta de enlace).

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 agrupamiento (pooling) 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 un 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

prueba así:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/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 en una base por solicitud —sin reiniciar el proceso—, eso es para lo que está el modo enrutador (router mode). Ver llama-server router mode: dynamic model switching without restarts. Para un flujo de descarga de todos los modelos que libere VRAM sin reiniciar el enrutador, ver Unload All llama.cpp Router Models Without Restarting.

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 la velocidad y la memoria” se vuelve mucho más fácil cuando tratas la inferencia como un sistema:

• El techo de memoria suele ser la primera restricción (RAM en CPU, VRAM en GPU).
• El tamaño de contexto es un multiplicador de memoria importante.
• La descarga de capas a GPU suele ser el camino más rápido hacia 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 sobre la memoria.

Para una visión más profunda, centrada en la ingeniería, ver: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Si deseas resultados de llama-cli medidos en una GPU de clase 16 GB—tokens por segundo, VRAM y carga de GPU mientras varías el contexto (19K / 32K / 64K) en GGUFs densos y MoE—ver 16 GB VRAM LLM benchmarks with llama.cpp (speed and context).

Específicamente para Qwen 3.6, llama.cpp ahora soporta decodificación especulativa de predicción de múltiples tokens (MTP) integrada que puede aumentar significativamente el rendimiento de generación. Ver Qwen 3.6 27B and 35B MTP vs Standard on 16GB GPU para velocidades de generación medidas, sobrecarga de VRAM y valores recomendados de --spec-draft-n-max.

Monitoreo de llama-server con Prometheus y Grafana

llama-server puede exponer métricas compatibles con Prometheus en /metrics cuando --metrics está habilitado. Esto se combina naturalmente con configuraciones de extracción (scrape) de Prometheus y paneles de Grafana.

Para paneles y alertas específicas para llama.cpp (y vLLM, TGI): Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp. Guías más amplias: Observability: Monitoring, Metrics, Prometheus & Grafana Guide y Observability for LLM Systems.

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 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.

Solución rápida de problemas

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

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

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

Te quedas sin memoria (out of memory)

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

• baja --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

Comienza con:

• --threads igual a tus núcleos físicos,
• tamaños de lote moderados,
• validar que instalaste una compilació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