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

llama.cpp es un motor de inferencia en C/C++ para modelos GGUF: llama-cli para chat interactivo, llama-completion para prompts guiados por guion, y llama-server para una API HTTP compatible con OpenAI.

Si aún estás decidiendo entre enfoques locales, autoalojados y en la nube, comienza con la guía principal Hosting 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 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 se busca privacidad y operación sin conexión, cuando se necesita control determinista sobre las banderas de tiempo de ejecución, o cuando se desea incorporar la inferencia en un sistema mayor sin ejecutar un stack pesado de Python.

También es útil comprender llama.cpp incluso si más adelante se elige un tiempo de ejecución de servidor con mayor rendimiento. Por ejemplo, si el objetivo es el máximo rendimiento de servicio en GPUs, podría ser necesario compararlo con vLLM usando: Inicio rápido de vLLM: Servicio de LLM de Alto Rendimiento y se pueden realizar pruebas de rendimiento de las herramientas en: Ollama vs vLLM vs LM Studio: ¿La Mejor Manera de Ejecutar LLM Localmente en 2026?.

Si Ollama es específicamente la alternativa que se está pesando frente a llama-server, llama.cpp vs Ollama en 2026 es la comparación pareada dedicada, con detonantes concretos de cuándo mantener Ollama y cuándo pasar a llama.cpp directamente.

Instalar llama.cpp en Windows, macOS y Linux

Los comandos a continuación corresponden a llama.cpp v0.6.0 (5 de octubre de 2026). Una entrada de catálogo para el mismo tiempo de ejecución — inferencia GGUF en CPU y backends de acelerador, versionada por commit de compilación — se encuentra en la referencia del tiempo de ejecución llama.cpp en LLM Systems. Hay cuatro rutas prácticas de instalación, dependiendo de si se desea comodidad, portabilidad o máximo rendimiento.

Instalación mediante administradores de paquetes

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

# Ubuntu (universe). Este paquete va muy por detrás de la versión principal:
# 8681+dfsg frente a la compilación actual b11433 / v0.6.0, por lo que faltarán banderas más nuevas.
sudo apt install llama.cpp-tools

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

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

Instalación mediante binarios precompilados

Si se desea una instalación limpia sin compiladores, use 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) Descargar el archivo correcto para tu sistema operativo y backend
# 2) Descomprimirlo
# 3) Ejecutar desde la carpeta descomprimida

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

Ejecutar el contenedor oficial

El proyecto publica imágenes de servidor en GitHub Container Registry. La imagen CPU es ghcr.io/ggml-org/llama.cpp:server; la imagen CUDA es :server-cuda. El contenedor debe escuchar en todas las interfaces, porque el vínculo predeterminado sigue siendo 127.0.0.1:

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

Compilar desde el código fuente para tu hardware exacto

Si le importa obtener el mejor rendimiento de su backend de CPU/GPU, compile 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

Habilite el backend que coincida con su 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: recorrido completo de compilación

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

1. Instalar el kit de herramientas CUDA 13.1. Este recorrido fija el instalador local 13.1.1. Un kit de herramientas más nuevo del repositorio de Ubuntu 24.04 de NVIDIA sigue los mismos pasos de archivo de fijación y deb local con nombres de archivo actualizados.

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 su entorno (añadir a ~/.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 ejecute source ~/.bashrc o abra 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 su 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 es posible compilar múltiples backends y elegir dispositivos en tiempo de ejecución. Esto es útil si se despliega la misma compilación en máquinas heterogéneas.

Elegir un modelo GGUF y una cuantización

Para ejecutar la inferencia, se necesita 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 maneras de obtener un modelo

Opción A: Usar un archivo GGUF local

Descargue o copie un GGUF a ./models/:

mkdir -p models
# Coloque su GGUF en models/my-model.gguf

Luego ejecútelo por ruta:

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

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. A menudo, este es 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 \
  -st

También se puede especificar la cuantización en el selector de repositorio y dejar que la herramienta seleccione 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 \
  -st

Si más adelante necesita un flujo de trabajo totalmente sin conexión, --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 debe elegir para inferencia local?” porque intercambia directamente calidad, tamaño del modelo y velocidad.

Un punto de partida pragmático:

• comience con una variante Q4 o Q5 para máquinas centradas en CPU,
• pase a una precisión mayor (o una cuantización menos agresiva) cuando pueda permitirse la RAM o la VRAM,
• cuando el modelo “se siente tonto” para su tarea, la solución a menudo es un mejor modelo o una cuantización menos agresiva, no solo ajustes de muestreo.

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

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

llama-cli es la manera más rápida de validar que su modelo se carga, que su backend funciona y que sus prompts se comportan correctamente.

llama-cli ha sido un cliente de chat interactivo desde la reescritura de diciembre de 2025. Cuando el modelo incorpora una plantilla de chat, el modo de conversación está activado por defecto, y --no-conversation se rechaza con un puntero hacia llama-completion. Ese segundo binario es el antiguo llama-cli: un prompt de entrada, una completación de salida, apto para guiones y tuberías. Desde el nuevo cliente, --single-turn (-st) genera una respuesta y finaliza.

Una respuesta, y luego salir

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

El mismo prompt a través del binario no interactivo:

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

Ejecución de chat interactivo

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

--conversation ya no es necesario. Para terminar la generación cuando el modelo imprime una secuencia específica, use un prompt inverso.

Banderas principales de llama-cli que importan

En lugar de memorizar 200 banderas, cúmpase 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 "Tú resumas documentos técnicos. Salida de un máximo de cinco puntos." \
  --file ./docs/incident-report.txt \
  -n 300 \
  -st

Hacer los resultados más reproducibles

Cuando esté depurando prompts, fije la semilla y reduzca el azar:

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

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 vincular externamente (por ejemplo, dentro de Docker o una LAN), especifique el host y el puerto:

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

Banderas de servidor opcionales pero importantes

Si ejecuta en contenedores, muchas configuraciones también se pueden controlar a través de variables de entorno LLAMA_ARG_*.

Llamadas de API de ejemplo

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 establece --api-key, puede enviarlo a través de una cabecera x-api-key (o seguir usando cabeceras de autorización dependiendo de su gateway).

Cliente de Python de OpenAI apuntando a llama-server

Con un servidor compatible con OpenAI, muchos clientes pueden funcionar cambiando solo base_url — esta es también la manera en que agentes de investigación como lukeswade/deep-research se comunican directamente con llama-server, sin una capa de adaptador separada. Sistemas de Investigación Profunda Autoalojados: 12 Herramientas Comparadas cubre ese proyecto y otros apuntados a puntos finales locales compatibles con OpenAI.

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 admitir un modo de agregació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 ejecuta un modelo de incrustaciones dedicado, considere 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 desea 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

pruébelo así:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "su 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 necesita cambiar entre modelos en una base de solicitud individual — sin reiniciar el proceso —, ese es el propósito del modo enrutador. Consulte Modo enrutador de llama-server: cambio dinámico de modelos sin reinicios. Para un flujo descargable de liberar todo que libera VRAM sin reiniciar el enrutador, consulte Descargar todos los modelos del enrutador de llama.cpp sin reiniciar.

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 se trata 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 mayor de la memoria.
• La descarga de capas a GPU a menudo es el camino más rápido hacia más tokens por segundo.
• Los tamaños de lote y las 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, consulte: Rendimiento de LLM en 2026: Benchmarks, Cuellos de Botella y Optimización.

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

Para Qwen 3.6, llama.cpp admite decodificación especulativa de Predicción de Múltiples Tokens (MTP) integrada. Actívelo con --spec-type draft-mtp; --spec-draft-n-max establece cuántos tokens propone la cabeza de borrador (predeterminado 3). La v0.6.0 extiende esa misma ruta MTP a Qwen4Exp. Para la comparación de métodos, consulte Decodificación Especulativa. Para números medidos de Qwen 3.6 en 16 GB, consulte Qwen 3.6 MTP vs Estándar en GPU de 16GB.

Monitorear llama-server con Prometheus y Grafana

llama-server expone métricas compatibles con Prometheus en /metrics solo cuando --metrics está habilitado. Apunte un trabajo de scraping de Prometheus a esa ruta. Los paneles de control y los umbrales de alerta para llama.cpp, vLLM y TGI están en Monitorear Inferencia de LLM en Producción (2026): Prometheus y Grafana para vLLM, TGI, llama.cpp.

Lista de verificación básica de endurecimiento

Cuando su llama-server es alcanzable más allá del localhost:

• use --api-key (o --api-key-file) para que las solicitudes estén autenticadas,
• evite vincular a 0.0.0.0 a menos que lo necesite,
• considere TLS a través de las banderas SSL del servidor o termine TLS en un proxy inverso,
• restrinja la concurrencia con --parallel para proteger la latencia bajo carga,
• deje --tools y --agent desactivados. Ambos son experimentales y exponen operaciones de archivo y shell a través de la API; habilitar cualquiera de ellos también restringe CORS al localhost.

Soluciones rápidas de solución de problemas

El modelo se carga pero las respuestas son raras en chat

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

• pasando un --system-prompt explícito (el modo de conversación ya es el predeterminado en llama-cli),
• verificando que su modelo sea una variante ajustada para instrucciones o chat,
• probando usando la interfaz web del servidor antes de integrarlo en una aplicación. La v0.6.0 reconstruyó esa interfaz con un navegador de Hugging Face Hub, por lo que un modelo puede descargarse desde la página y no solo desde la CLI.

Los modelos de razonamiento envuelven la respuesta en trazas de razonamiento. --reasoning off suprime eso, y --reasoning-format deepseek mueve la traza a reasoning_content en lugar de content.

Se agota la memoria

Reduzca el contexto o elija una cuantización más pequeña:

• reduzca --ctx-size,
• reduzca --n-gpu-layers si VRAM es el problema, o establezca --cpu-moe para que los pesos de los expertos de un modelo MoE permanezcan en RAM,
• cambie a un modelo más pequeño o a una cuantización más comprimida,
• cuantice la caché KV con --cache-type-k q8_0 --cache-type-v q8_0.

El contexto o la división de GPU no es lo que pidió

--fit está activado por defecto y reescribe las configuraciones de memoria que dejó sin definir, buscando dejar 1024 MiB libres en cada dispositivo (--fit-target). Reducirá el contexto, pero nunca por debajo de --fit-ctx (4096), y solo cuando no pasó -c. No tocará la colocación de capas una vez que pase cualquier -ngl. --fit off deshabilita el mecanismo. Si los registros dicen n_gpu_layers already set by user, su -ngl explícito es lo que se cargó, y fit no rescata un agotamiento de memoria de él.

Es lento en CPU

Comience con:

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

Referencias

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