Cómo ejecutar llama.cpp en un VPS con systemd
Compile llama.cpp desde la etiqueta b10488, sirva modelos GGUF con API compatible con OpenAI, use localhost y limite la memoria con systemd.
Qué va a configurar
Ejecutar el servidor de llama.cpp en un VPS significa usar un solo binario, llama-server, que carga un único archivo de modelo GGUF y responde a solicitudes HTTP mediante una API compatible con OpenAI. Configure un cliente compatible para que use http://127.0.0.1:8080/v1 y pruebe las funciones que utiliza su aplicación: la compatibilidad es parcial. La instalación es la parte sencilla.
El resto del trabajo corresponde a las operaciones: fijar una versión, mantener el puerto en localhost, crear una unidad de systemd y decidir qué ocurre cuando el servidor se queda sin memoria. Esto es lo que cubre esta guía. Si todavía no ha decidido entre las dos opciones más evidentes, lea primero las diferencias entre Ollama y llama.cpp, porque esta es la guía práctica que esa comparación omite deliberadamente.
Elija una etiqueta de release y anótela
llama.cpp usa etiquetas con números de compilación, como b10488, para las compilaciones nocturnas de desarrollo y etiquetas de versión semántica, vX.Y.Z, para los releases oficiales. b10488 es la compilación fijada que se usa aquí y se publicó el 18 August 2026. "Latest" cambia continuamente, y la versión que ha probado es la única que puede admitir. Elija una etiqueta, regístrela y use esa misma cadena en el clon, en el nombre del binario y en sus notas.
La etiqueta b10488 también incluye archivos precompilados. Para una VPS x86 que sólo use CPU, esa etiqueta es llama-b10488-bin-ubuntu-x64.tar.gz. Si usa una VPS ARM en lugar de x86, encontrará junto a ella un archivo para arm64.
curl -LO https://github.com/ggml-org/llama.cpp/releases/download/b10488/llama-b10488-bin-ubuntu-x64.tar.gz
tar tf llama-b10488-bin-ubuntu-x64.tar.gz | headEnumere el contenido del archivo antes de extraerlo para saber dónde se instalarán los archivos. Esos binarios están enlazados con la biblioteca C de la imagen que los compiló. Por eso, en una distribución antigua fallan al arrancar con un error que menciona una versión de GLIBC_ que no está instalada. Compilar desde el código fuente tarda unos minutos en una VPS pequeña y elimina toda esta clase de problemas. Por eso, ese es el procedimiento que se describe a continuación.
Compilar llama-server desde una etiqueta fijada
sudo apt update
sudo apt install -y build-essential cmake git libssl-dev
git clone --depth 1 --branch b10488 https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release -t llama-server -j 2--branch b10488 en un --depth 1 clonado extrae esa etiqueta y nada más, por lo que la compilación no puede desviarse mientras trabaja.
libssl-dev es importante porque la opción LLAMA_OPENSSL está activada de forma predeterminada. Esta opción permite que el binario descargue modelos mediante HTTPS más adelante. Sin los archivos de desarrollo de OpenSSL, esta compilación fijada muestra una advertencia de que la compatibilidad con HTTPS está desactivada, en lugar de fallar durante la configuración.
-DBUILD_SHARED_LIBS=OFF enlaza llama.cpp y GGML con el ejecutable; las dependencias de las bibliotecas del sistema se mantienen. La compilación predeterminada coloca las bibliotecas compartidas junto al ejecutable. Por tanto, copiar sólo el ejecutable en /usr/local/bin falla después con error while loading shared libraries: libllama.so.
-t llama-server compila sólo el destino del servidor. La compilación predeterminada también compila las demás herramientas y las pruebas. En una VPS con dos núcleos, esto añade varios minutos para archivos que nunca ejecutará.
-j 2 es deliberado. Cada trabajo de compilación en paralelo mantiene su propio conjunto de trabajo. Por eso -j $(nproc) en un plan pequeño termina con c++: fatal error: Killed signal terminated program cc1plus, cuando el asesino de procesos por falta de memoria del kernel detiene el compilador. Reduzca el número de trabajos o añada swap para la compilación.
Hay una opción que quizá quiera cambiar: GGML_NATIVE está activada de forma predeterminada, por lo que el compilador genera código para la CPU exacta que realiza la compilación. Eso es lo adecuado cuando compila en la máquina que ejecutará el binario. Si compila una vez y copia el binario a otro host, añada -DGGML_NATIVE=OFF, porque un binario que usa instrucciones que la otra CPU no tiene termina con Illegal instruction (core dumped) en la primera inferencia.
Instálelo con un nombre que incluya la etiqueta.
./build/bin/llama-server --version
sudo install -m 755 build/bin/llama-server /usr/local/bin/llama-server-b10488
sudo ln -sfn /usr/local/bin/llama-server-b10488 /usr/local/bin/llama-server--version muestra el número de compilación y el commit. Debe coincidir con la etiqueta que extrajo. Si no coincide, compiló otra cosa. Mantener el número en el nombre del archivo y apuntar un enlace simbólico hacia él permite hacer una actualización con un ln -sfn y un reinicio. La reversión usa el mismo comando con el número anterior.
Descargue un modelo GGUF y compruebe primero el espacio en disco
GGUF es el formato de archivo único que carga llama.cpp. Un archivo contiene los pesos, el tokenizador y los metadatos, por lo que no es necesario instalar nada más. El sufijo del nombre de archivo indica la cuantización, es decir, la precisión con la que se almacenan los pesos: Q4_K_M es una mezcla de 4 bits, Q8_0 es de 8 bits y f16 es el archivo sin cuantizar en precisión media.
Cree una cuenta de servicio y un directorio para el modelo antes de descargar cualquier archivo.
sudo useradd --system --home /srv/llama --create-home --shell /usr/sbin/nologin llama
sudo install -d -o llama -g llama /srv/models
df -h /srvEl servidor puede descargar el modelo por sí mismo con -hf. Es la forma más rápida de comprobar que la compilación funciona.
sudo -u llama env LLAMA_CACHE=/srv/models /usr/local/bin/llama-server \
-hf ggml-org/gemma-3-1b-it-GGUF:Q4_K_M --host 127.0.0.1 --port 8080LLAMA_CACHE establece el directorio de descarga. Sin esta opción o XDG_CACHE_HOME, el archivo se guarda en ~/.cache/llama.cpp con la cuenta que ejecutó el comando; la unidad siguiente hace que /srv/llama sea de solo lectura. Ejecute ls -lh /srv/models después, porque el nombre de archivo almacenado en caché se obtiene del nombre del repositorio y no del nombre de archivo simple.
Para un servicio, descargue el modelo en una ruta elegida por usted, de modo que el archivo de unidad tenga una ruta estable a la que apuntar.
sudo -u llama curl -L --output-dir /srv/models -O \
https://huggingface.co/ggml-org/gemma-3-1b-it-GGUF/resolve/main/gemma-3-1b-it-Q4_K_M.ggufEl espacio en disco es la primera limitación que encuentran muchos usuarios. Estos son los tamaños de archivo publicados para dos modelos, comprobados el 18 August 2026.
Los datos de este gráfico
[
{
"label": "gemma-3-1b-it Q4_K_M",
"size_gb": 0.81
},
{
"label": "gemma-3-1b-it Q8_0",
"size_gb": 1.07
},
{
"label": "gemma-3-1b-it f16",
"size_gb": 2.01
},
{
"label": "gpt-oss-20b MXFP4",
"size_gb": 12.11
}
]El archivo de 4 bits del modelo 1B ocupa 0.81 GB. El mismo modelo sin cuantización ocupa 2.01 GB, por lo que la elección del formato cambia la cifra en más del doble. Un modelo 20B en MXFP4 ocupa 12.11 GB y, además, después debe cargarse en memoria. Si está considerando una familia concreta, el mismo análisis de tamaños para GLM muestra con qué rapidez el modelo principal deja de ser viable en un VPS, mientras que una variante menor sí cabe.
Compruebe df -h antes de cada descarga. Si el sistema de archivos raíz se llena durante una transferencia de 12 GB, todo lo demás que necesite escribir dejará de funcionar, incluido el journal.
Ejecútelo una vez manualmente y compruébelo
sudo -u llama /usr/local/bin/llama-server \
--model /srv/models/gemma-3-1b-it-Q4_K_M.gguf \
--host 127.0.0.1 --port 8080 \
--ctx-size 4096 --parallel 1 --threads 2 --no-webuiEn una segunda sesión, pregunte al servidor si está listo.
curl -s http://127.0.0.1:8080/healthMientras se carga el archivo, recibirá HTTP 503 con este cuerpo:
{"error":{"code":503,"message":"Loading model","type":"unavailable_error"}}Cuando esté listo, el cuerpo será {"status": "ok" }. Después, envíe una solicitud real.
curl -s http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"local","messages":[{"role":"user","content":"Say hello in five words."}]}'Un objeto JSON con un arreglo choices indica que el servidor funciona. El campo model existe porque los clientes de OpenAI siempre lo envían. Este servidor tiene un solo modelo cargado, por lo que el valor no se usa para seleccionar ninguno.
La API compatible con OpenAI y qué más hay en el puerto
POST /v1/chat/completions, POST /v1/completions, POST /v1/responses y POST /v1/embeddings son rutas compatibles con OpenAI, y GET /v1/models informa del modelo cargado. Las inserciones requieren un modelo con una estrategia de pooling distinta de none. GET /health es la comprobación de disponibilidad anterior, GET /props devuelve la configuración actual del servidor y GET /metrics expone contadores de Prometheus cuando se inicia con --metrics.
Para realizar llamadas compatibles con los SDK de OpenAI, establezca la URL base en http://127.0.0.1:8080/v1 y proporcione una cadena de clave de API no vacía si el SDK la requiere. Esto no garantiza la compatibilidad con todas las funciones del SDK. La clave no se comprueba hasta que configure --api-key o --api-key-file manualmente.
No use la afirmación de rendimiento de otra persona como cifra para su propio plan. La velocidad de inferencia en CPU depende del número de núcleos, del ancho de banda de memoria y de los vecinos con los que comparte el host. Por tanto, mida los tokens por segundo en su propio equipo y considere ese resultado como la referencia real. El steal time de un vecino ruidoso aparece aquí como una velocidad de generación que cambia de una hora a otra.
Mantenlo en 127.0.0.1 y coloca un proxy delante
--host ya usa 127.0.0.1 de forma predeterminada, por lo que el servidor no es accesible desde el exterior hasta que lo cambies. No lo modifiques. Usa el proxy para las cuentas de usuario, los límites de tasa de las peticiones y el registro de auditoría. La autenticación integrada de la API usa claves estáticas: --api-key acepta una clave o una lista separada por comas, y --api-key-file lee una clave por línea. Un puerto de inferencia abierto ofrece capacidad de cómputo gratuita a cualquiera que lo encuentre. El mismo error con Ollama tiene la misma estructura: proteger una API de modelos autoalojada se aplica aquí punto por punto.
Termina TLS (seguridad de la capa de transporte) en nginx y usa un proxy hacia el puerto de loopback.
server {
listen 443 ssl;
server_name llm.example.com;
location /v1/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 600s;
}
}proxy_buffering off envía las respuestas en streaming al cliente a medida que nginx las recibe. Con el almacenamiento en búfer activado, nginx almacena los datos del upstream en lugar de reenviar cada evento de inmediato. proxy_read_timeout 600s da margen a las respuestas lentas. Es el tiempo máximo que nginx espera entre dos lecturas del servidor, no un límite para la respuesta completa. Por tanto, con el valor predeterminado de 60 segundos, una petición sin streaming que no envíe datos durante ese intervalo agota el tiempo de espera. En b10488, las respuestas en streaming envían pings de mantenimiento de SSE cada 30 segundos de forma predeterminada, incluso durante el procesamiento prolongado de un prompt. Obtén el certificado con Certbot y Let's Encrypt en nginx.
La unidad de systemd
Escriba /etc/systemd/system/llama-server.service.
[Unit]
Description=llama.cpp server
After=network-online.target
Wants=network-online.target
[Service]
User=llama
Group=llama
Environment=LLAMA_ARG_MODEL=/srv/models/gemma-3-1b-it-Q4_K_M.gguf
Environment=LLAMA_ARG_HOST=127.0.0.1
Environment=LLAMA_ARG_PORT=8080
Environment=LLAMA_ARG_CTX_SIZE=4096
Environment=LLAMA_ARG_N_PARALLEL=1
Environment=LLAMA_ARG_THREADS=2
ExecStart=/usr/local/bin/llama-server --no-webui
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
MemoryHigh=3G
MemoryMax=3500M
OOMPolicy=stop
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
[Install]
WantedBy=multi-user.targetLa configuración se encuentra en Environment= porque llama-server lee las variables LLAMA_ARG_* para la mayoría de las opciones, y un argumento de la línea de comandos reemplaza la variable correspondiente. Así tiene un único lugar donde cambiar el tamaño del contexto y ExecStart sigue siendo lo bastante corto para leerlo de un vistazo.
ProtectSystem=strict hace que el sistema de archivos sea de solo lectura para esta unidad, con excepciones que incluyen los directorios temporales privados. Esto es suficiente porque el servidor solo lee el modelo. Añada ReadWritePaths=/srv/models y Environment=LLAMA_CACHE=/srv/models si quiere que el propio servicio descargue modelos con -hf. ProtectHome=yes oculta /home, /root y /run/user; no oculta el directorio personal de esta cuenta de servicio en /srv/llama, pero ProtectSystem=strict hace que ese directorio sea de solo lectura.
sudo systemctl daemon-reload
sudo systemctl enable --now llama-server
systemctl status llama-server
curl -s http://127.0.0.1:8080/health
journalctl -u llama-server -n 50 --no-pagerenable --now es la mitad que muchas personas omiten. Sin enable, el servidor desaparecerá después del siguiente reinicio. Si quiere programar tareas relacionadas con el servicio, como comprobar cada noche si hay una nueva versión, un servicio systemd y un temporizador es el mecanismo adecuado.
Decida qué ocurre ante un OOM antes de que ocurra
El uso de memoria tiene dos componentes y se comportan de forma distinta bajo un límite. De forma predeterminada, el archivo del modelo se asigna en memoria, por lo que sus páginas están respaldadas por un archivo: el kernel puede descartarlas y volver a leerlas del disco. La caché KV, que es el estado por token que el servidor conserva para cada conversación activa, usa memoria anónima. No se puede descartar, por lo que es la memoria que provoca la terminación del proceso.
Por eso, los dos límites de la unidad tienen funciones distintas. MemoryHigh=3G es un límite blando: cuando se supera, el kernel aplica presión de recuperación al cgroup, por lo que las páginas asignadas del modelo se expulsan y se vuelven a leer del disco para el siguiente token. El servicio sigue funcionando, pero se vuelve más lento. MemoryMax=3500M es el límite estricto: el kernel recupera primero toda la memoria posible y, si aun así no puede mantener el uso por debajo del límite, el OOM killer se ejecuta dentro de la unidad y el journal lo indica claramente.
llama-server.service: A process of this unit has been killed by the OOM killer.Establezca --ctx-size manualmente. El valor predeterminado es 0, que corresponde al contexto con el que se entrenó el modelo y que, en un modelo moderno de contexto largo, asigna una caché KV muy grande durante el arranque. El servicio termina antes de atender una sola solicitud. --parallel no multiplica por sí solo ese consumo: --ctx-size establece el tamaño total de la caché KV, que comparten todos los slots, por lo que --ctx-size 4096 --parallel 4 proporciona a cada conversación unos 1,024 tokens en lugar de multiplicar por cuatro el consumo de memoria. Asignar a cada slot todo el contexto implica multiplicar --ctx-size por el número de slots, y la memoria aumenta en consecuencia, así que deje --parallel en 1 hasta que necesite concurrencia.
Con Restart=on-failure, un servicio terminado vuelve a iniciarse. Systemd deja de reiniciarlo con start request repeated too quickly sólo cuando el número de arranques supera el límite de tasa configurado; el retraso de cinco segundos entre reinicios de este ejemplo no alcanza el límite predeterminado de cinco arranques en diez segundos. Detenga un bucle persistente de reinicios con sudo systemctl stop llama-server, corrija el límite o el tamaño del contexto y, después, borre el estado fallido con sudo systemctl reset-failed llama-server y vuelva a iniciarlo.
Supervise el valor real con systemctl show llama-server -p MemoryCurrent mientras se ejecuta una solicitud. Limitar la memoria y la CPU de un proceso con systemd explica estas directivas con más detalle.
Evite la swap para esta carga de trabajo. Un modelo expulsado a la swap convierte cada token en lecturas del disco con desplazamientos aleatorios. La asignación en memoria del archivo del modelo produce el mismo efecto con menos impacto, porque el kernel lee directamente del archivo las páginas que necesita.
Dónde Ollama es la mejor opción
Este es un punto de decisión. Elija llama-server cuando quiera un único proceso con las opciones que haya configurado, una compilación fijada y un archivo elegido por usted. Nada cambiará por debajo porque no habrá ningún otro proceso en ejecución.
Elija Ollama cuando necesite gestión de modelos: descargar modelos por nombre, mantener varios en el disco, descargar de memoria uno inactivo y actualizar con un solo comando en lugar de volver a compilar. Es trabajo real que, de otro modo, tendría que automatizar con scripts. Ejecutar Ollama en un VPS aplica este mismo enfoque con la decisión contraria. Ambos ofrecen una API compatible con OpenAI, pero pruebe los endpoints y las funciones que usa su cliente antes de cambiar en cualquiera de las dos direcciones.
Actualizar una compilación fijada
Reemplace bNNNNN por la etiqueta de la compilación nightly a la que va a actualizarse; las etiquetas de las versiones oficiales usan vX.Y.Z.
cd llama.cpp
git fetch --tags
git checkout bNNNNN
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release -t llama-server -j 2
sudo install -m 755 build/bin/llama-server /usr/local/bin/llama-server-bNNNNN
sudo ln -sfn /usr/local/bin/llama-server-bNNNNN /usr/local/bin/llama-server
sudo systemctl restart llama-serverEl binario anterior permanece en el disco, por lo que una reversión consiste en ejecutar ln -sfn para volver a llama-server-b10488 y reiniciar una vez. Lea las notas de la versión antes de actualizar. Los archivos GGUF tienen versiones, pero la compatibilidad con versiones anteriores no es universal: el cargador actual rechaza GGUFv1. Las opciones también cambian de nombre: en b10488, --mlock y --no-mmap ya estaban obsoletas y habían sido sustituidas por --load-mode. Además, desde el 11 de octubre de 2026, la documentación actual del servidor ya no las incluye. Por tanto, un archivo de unidad que pase una opción eliminada falla al iniciar y muestra un mensaje de argumento no reconocido. Los valores predeterminados también cambian: las compilaciones actuales escuchan de forma predeterminada en el puerto 9931, mientras que b10488 usaba el puerto 8080. Por eso, todos los comandos y la unidad de este ejemplo establecen el puerto explícitamente.
Modos de fallo y mensajes que verá
error while loading shared libraries: libllama.so después de copiar el binario a otra ubicación. La compilación predeterminada genera bibliotecas compartidas junto al binario. Vuelva a compilar con -DBUILD_SHARED_LIBS=OFF o copie todo el directorio build/bin.
Illegal instruction (core dumped) durante el inicio o en la primera petición. El binario se compiló con GGML_NATIVE activado para una CPU diferente de la que lo ejecuta. Vuelva a compilarlo en esta máquina o configure con -DGGML_NATIVE=OFF.
c++: fatal error: Killed signal terminated program cc1plus durante la compilación. El compilador terminó porque consumió demasiada memoria. Reduzca -j o añada swap para la compilación y elimínelo después.
curl: (7) Failed to connect ... Connection refused desde su portátil. Es correcto: el servidor escucha en la dirección de loopback del VPS. Pruebe desde el propio VPS o abra un túnel con ssh -L 8080:127.0.0.1:8080 user@your-vps y use http://127.0.0.1:8080 localmente.
HTTP 503 con "message":"Loading model" durante los primeros segundos o minutos después de un reinicio. Leer un archivo de varios gigabytes lleva tiempo, y systemd informa de que la unidad está activa en cuanto se inicia el proceso, mucho antes de que el modelo esté en memoria.
Las peticiones se quedan bloqueadas y después devuelven 504 Gateway Time-out. El servidor no envió nada durante más tiempo que proxy_read_timeout, lo que puede ocurrir con peticiones que no usan streaming. Las peticiones de streaming en b10488 envían pings de keepalive cada 30 segundos de forma predeterminada durante el procesamiento prolongado del prompt. Aumente proxy_read_timeout y desactive proxy_buffering para que los tokens lleguen al cliente a medida que se generan.
La unidad se reinicia repetidamente y después se detiene con start request repeated too quickly. El número de inicios superó el límite de frecuencia configurado. Compruebe journalctl -u llama-server para localizar la línea del OOM killer. Después, reduzca --ctx-size o aumente MemoryMax.
FAQ
¿Debo ejecutar el servidor de llama.cpp o Ollama en mi VPS?
Ejecute llama-server cuando necesite fijar una compilación exacta, pasar flags exactos y mantener un modelo en un solo archivo que no se actualice sin su conocimiento. Use Ollama cuando necesite gestionar modelos y actualizarlos con un solo comando, porque descargar modelos por nombre, mantener varios en disco y descargar de memoria los que están inactivos son tareas que, de otro modo, tendría que automatizar mediante scripts. Ambos exponen una API compatible con OpenAI, pero el cambio requiere comprobar los endpoints y las funciones que usa el cliente.
¿Qué versión de llama.cpp debería fijar?
Cualquier tag que haya compilado y probado realmente. Las compilaciones de desarrollo nocturnas usan tags con el número de compilación, como b10488, publicada el 18 de agosto de 2026; las versiones oficiales usan tags de versiones semánticas, vX.Y.Z. Clone con --branch <tag>, instale el binario con un nombre que contenga ese tag y apunte un enlace simbólico a él, de modo que actualizar y revertir la versión requiera un solo comando en cada caso.
¿Cuánta RAM necesita llama-server?
Empiece por el tamaño del archivo GGUF y añada la caché KV, que crece con --ctx-size. Esa cifra es el presupuesto total de tokens compartido por todos los slots --parallel, por lo que más slots necesitan un --ctx-size mayor si cada uno debe conservar el mismo contexto. Las cifras publicadas no sustituyen a las mediciones de su propia configuración, porque el total depende del modelo, la cuantización y el contexto permitido. Ejecute systemctl show llama-server -p MemoryCurrent mientras haya una petición en curso y use el valor que muestra.
¿Por qué /health devuelve 503 con "Loading model"?
El proceso se ha iniciado, pero el archivo del modelo aún no está en la memoria, por lo que el servidor responde {"error":{"code":503,"message":"Loading model","type":"unavailable_error"}}. Esto es normal después de cada reinicio y dura lo que tarda en leerse el archivo. Sólo se convierte en un problema cuando un cliente o un proxy trata ese primer 503 como un fallo definitivo. Consulte /health periódicamente hasta que devuelva {"status": "ok" }.
¿Puedo exponer llama-server directamente a Internet?
No lo vincule a 0.0.0.0 ni abra el puerto. Use el proxy para gestionar cuentas, límites de tasa de las peticiones y registros de auditoría; la autenticación integrada de la API usa claves estáticas definidas con --api-key o --api-key-file. Mantenga el bind predeterminado 127.0.0.1, coloque nginx delante con TLS y establezca también --api-key, para que un error en la configuración del proxy no deje el modelo abierto a todo el mundo.