Inicio›Guías›llama-server, el servidor de llama.cpp: flags, slots, API y errores (probado con la v1.0.0)

Instalar · Guía

llama-server, el servidor de llama.cpp: flags, slots, API y errores (probado con la v1.0.0)

llama-server es el servidor HTTP de llama.cpp: llama-server -m modelo.gguf sirve una API compatible con OpenAI y una página de chat en 127.0.0.1:9931 (8080 en la v0.6.0 y anteriores). Por defecto abre 4 slots que comparten el contexto que le des con -c. -np, --api-key y --host, solo cuando los necesites.

Medido y escrito por Local AI ScopePublicado el Cifras medidas por Local AI Scope

llama-server es el servidor HTTP de llama.cpp: llama-server -m modelo.gguf sirve una API compatible con OpenAI y una página de chat en 127.0.0.1:9931 (8080 en la v0.6.0 y anteriores). Por defecto abre 4 slots que comparten el contexto que le des con -c. -np, --api-key y --host, solo cuando los necesites.

Nos encanta llama-server porque no esconde nada: cada petición, cada slot y cada token están a la vista, si sabes dónde mirar. Así que el 11 de noviembre de 2026 cogimos la versión estable de llama.cpp, la v0.9.0 (compilación b12110, publicada el 4 de noviembre de 2026), arrancamos su llama-server para Linux en un contenedor sin red con un modelo diminuto de 135 millones de parámetros, SmolLM2 en Q4_K_M, y le preguntamos de todo: qué puerto usa, qué endpoints tiene, cómo reparten -c y -np el contexto y qué contesta cuando algo va mal. Cada mensaje que citamos aquí es el que nos devolvió, letra por letra. Donde solo leímos el código de la v0.9.0, lo decimos. El 15 de noviembre de 2026 repetimos todas las pruebas con la v1.0.0 (compilación b12359, publicada el 13 de noviembre de 2026): los mismos códigos de estado, mensajes y cifras de memoria, más una línea de seguridad al arrancar que explicamos más abajo.

llama.cppllama.cppFicha del programa

Arrancar llama-server: el comando, el puerto y la dirección

Lo mínimo es un fichero de modelo:

llama-server -m ./SmolLM2-135M-Instruct-Q4_K_M.gguf

o un modelo de Hugging Face con -hf y el nombre del repositorio. El nuevo programa único llama hace lo mismo con llama serve; aquí usamos llama-server, que sigue dentro de la compilación oficial para Linux que probamos. Con la v0.9.0 el 11 de noviembre de 2026, y otra vez con la v1.0.0 el 15 de noviembre, nuestro registro terminó en listening on http://127.0.0.1:9931 y el único socket abierto era 127.0.0.1 en el puerto 9931. El 8080 ni contestó. Si un tutorial antiguo te manda al 8080, es el puerto de la v0.6.0 y anteriores: --port 8080 te lo devuelve.

La excepción son las imágenes Docker del proyecto: en los Dockerfile de la v0.9.0 y de la v1.0.0 leímos que fijan LLAMA_ARG_HOST=0.0.0.0 y LLAMA_ARG_PORT=8080, así que dentro de un contenedor escucha en el 8080 y en todas las interfaces.

Página de GitHub de la versión v0.9.0 de llama.cpp, marcada como Latest, etiqueta v0.9.0 en el commit cd959ba
La versión estable que probamos primero (11 de noviembre de 2026). Su etiqueta apunta al mismo commit que la compilación diaria b12110; por eso llama-server --version imprime 0.9.0-dev (build 12110, commit cd959bae9) Captura: GitHub, ggml-org/llama.cpp, 11-11-2026

Los endpoints que vas a usar y qué contesta cada uno

llama-server habla el dialecto de OpenAI, así que a casi cualquier cliente le basta con la URL base http://127.0.0.1:9931/v1. Estos son los endpoints que llamamos, con el código que dio cada uno en un arranque por defecto:

Endpoint Para qué sirve Arranque por defecto (v0.9.0 y v1.0.0)
GET /health ¿está listo el servidor? 503 mientras carga, luego 200 {"status":"ok"}
GET /v1/models el modelo que sirve, al estilo OpenAI 200
POST /v1/chat/completions chat, al estilo OpenAI 200
GET /slots cada slot y su contexto 200
GET /props ajustes: slots, plantilla, qué está activado 200
GET /metrics contadores para Prometheus 501 hasta que añades --metrics
GET / la página de chat 200 en un navegador

Un detalle de /v1/models: el id del modelo es la ruta que pasaste a -m, en nuestro caso /models/SmolLM2-135M-Instruct-Q4_K_M.gguf. Arranca con --alias smollm2 y el id pasa a ser smollm2, mucho más cómodo para los clientes que te piden escribir el nombre del modelo. La respuesta trae además el contexto de entrenamiento (n_ctx_train, 8.192 aquí) y el tamaño, útiles para comprobar qué fichero está cargado de verdad. Y cada respuesta de chat lleva un bloque timings y un system_fingerprint con la compilación, b12110-cd959bae9 en la v0.9.0 y b12359-b1b770d90 en la v1.0.0.

«Loading model»: el 503 de /health

Nada más arrancar, /health responde 503 con {"error":{"message":"Loading model","type":"unavailable_error","code":503}}. No es un fallo: el modelo todavía está cargando. El nuestro tardó 0,28 segundos y aun así lo pillamos 5 veces seguidas antes del primer 200; con un modelo de muchos gigas estarás ahí bastante más. Si tienes un script, que espere al 200 antes de mandar trabajo.

«This server does not support metrics endpoint. Start it with `--metrics`»

Es el 501 que devuelve /metrics en un arranque por defecto. Con --metrics devuelve contadores de Prometheus como llamacpp:prompt_tokens_total, llamacpp:tokens_predicted_total y llamacpp:n_tokens_max.

«Error: gzip is not supported by this browser»

Probamos la página de chat con un curl http://127.0.0.1:9931/ a pelo y nos llevamos un 415 con ese texto. La página va guardada comprimida y curl, sin más, no dice que acepte gzip. Un navegador sí lo dice, y curl --compressed recibe un 200 normal. No hay nada roto.

-c y -np: cómo reparte llama-server el contexto entre los slots

Aquí nacen casi todas las sorpresas. Un slot es un asiento para una conversación; -np (o --parallel) dice cuántos hay y -c (o --ctx-size) dice cuántos tokens de memoria reserva el servidor en total. Esto dijo el registro, línea n_slots / n_ctx_slot / kv_unified, en cada arranque con nuestro modelo de 8.192 tokens:

Arrancas con Slots Contexto por slot ¿Bolsa compartida? Caché KV reservada (RAM, compilación CPU)
nada (por defecto) 4 8.192 sí, 8.192 para los 4 180 MiB
-np 4 4 8.192 no: 4 × 8.192 720 MiB
-c 4096 -np 4 4 1.024 no 90 MiB
-c 4096 -np 4 -kvu 4 4.096 sí, 4.096 para los 4 no consta
-c 16384 -np 4 4 4.096 no 360 MiB
-np 1 1 8.192 no 180 MiB

Medido con llama.cpp v0.9.0 el 11 de noviembre de 2026 y con la v1.0.0 el 15 de noviembre de 2026 (mismas cifras), SmolLM2-135M en Q4_K_M; memoria según la línea KV buffer size del registro. Un modelo más grande necesita muchísima más memoria por token.

De ahí salen tres reglas. Sin flags, llama-server elige 4 slots y una caché unificada (lo leímos en tools/server/server.cpp, líneas 126-130 en la v0.9.0 y 129-133 en la v1.0.0): una sola bolsa de tokens de la que beben todas las conversaciones, así que un chat largo puede usarla entera. Si escribes tú -np 4, la bolsa deja de ser compartida: cada slot recibe el contexto completo y la caché ocupó 4 veces más, 720 MiB en vez de 180. Y con -c más -np, -c se divide: 4.096 entre 4 slots deja 1.024 tokens a cada uno, y el registro avisa, muy educado, n_ctx_seq (1024) < n_ctx_train (8192) -- the full capacity of the model will not be utilized. -kvu (--kv-unified) recupera la bolsa compartida.

Respuesta JSON del endpoint /slots de llama-server: 4 slots, cada uno con n_ctx 4096
/slots tras arrancar con -c 4096 y sin -np: 4 slots, cada uno capaz de usar los 4.096 tokens de la bolsa compartida Captura: llama-server v0.9.0 (localaiscope.com), 11-11-2026

Más slots sirven para trabajo en paralelo de verdad. Con -np 1 mandamos 2 peticiones a la vez: una acabó en 1,18 s y la otra esperó su turno y tardó 2,18 s. Con -np 2, las dos acabaron en 1,33 s. Si el único usuario eres tú, 1 slot con todo el contexto es lo sensato; con -np escrito a mano, cada slot de más reserva su propia caché (en nuestra prueba, en RAM; una tarjeta gráfica no la medimos). Cuánta memoria ocupan el modelo y su contexto en tu tarjeta lo calcula nuestro buscador de modelos, a 8.192 tokens.

PC con una NVIDIA GeForce RTX 3060
En una tarjeta de 12 GB como la RTX 3060, la caché del contexto sale de los mismos 12 GB que el modelo Foto: NVIDIA

«request (931 tokens) exceeds the available context size (256 tokens), try increasing it»

Ese es el error literal que nos dio un prompt que no cabía en su slot. Arrancamos con -c 512 -np 2 (256 tokens por slot) y mandamos 931 tokens. La respuesta fue un 400:

{"error":{"code":400,"message":"request (931 tokens) exceeds the available context size (256 tokens), try increasing it","type":"exceed_context_size_error","n_prompt_tokens":931,"n_ctx":256}}

El número entre paréntesis es el contexto de un slot, no el -c que escribiste. Si ves una cifra más pequeña de la que esperabas, divide tu -c entre tus slots y ahí tienes al culpable. Los arreglos, por orden: quita -np (o pon -np 1), añade -kvu para que los slots compartan la bolsa, o sube -c.

El otro borde es más discreto. Con el mismo servidor, un prompt corto, max_tokens 400 e ignore_eos (para que el modelo no pudiera parar por su cuenta), la generación se paró en 256 tokens en total (35 de prompt y 221 de respuesta) con finish_reason: "length" y un 200, y el registro dijo truncated = 1. Ningún error: la respuesta se corta donde acaba el slot, porque el desplazamiento de contexto viene apagado por defecto en la v0.9.0 y en la v1.0.0 (lo leímos en common/common.h, línea 580 en la v0.9.0, 592 en la v1.0.0). Si las respuestas se quedan a medias, mira finish_reason antes de echarle la culpa al modelo.

--host, --port y --api-key: «Invalid API Key»

--host 0.0.0.0 --port 8080 hizo lo que promete: el registro mostró listening on http://0.0.0.0:8080 y el socket quedó abierto en todas las interfaces. Antes de hacerlo en un portátil que sale de casa, ponle una clave. Con --api-key (o la variable LLAMA_API_KEY, para no escribirla en la línea de comandos), una petición sin clave, o con otra, se llevó un 401:

{"error":{"message":"Invalid API Key","type":"authentication_error","code":401}}

Mándala como Authorization: Bearer tu-clave, que es lo que hacen los clientes de OpenAI; el código de la v0.9.0 también la acepta en una cabecera X-Api-Key. Dos cosas que la clave no cubre, medidas: /health siguió contestando 200 sin ella, y la página de chat también es pública (sin clave siguió contestando, con el 415 del gzip de curl a pelo); sus propias llamadas a la API sí necesitan la clave, según leímos en el código. Y si el puerto está ocupado, el servidor no arranca: couldn't bind HTTP server socket, hostname: 127.0.0.1, port: 9931, y se cierra. Ese error y 13 más están en nuestra guía de errores de llama.cpp.

La interfaz web: un chat en el mismo puerto

Abre http://127.0.0.1:9931 en el navegador y tienes un chat completo: conversaciones, nombre del modelo, número de parámetros y cuantización, y tokens por segundo debajo de cada respuesta. Viene activada; --no-webui la apaga si solo quieres la API.

Interfaz web de llama-server en el navegador: una pregunta sobre los ficheros GGUF y la respuesta de SmolLM2 135M Q4_K_M
Nuestro chat de prueba. La interfaz, impecable; el modelo de 135M, preguntado por qué es un fichero GGUF, se inventó muy seguro de sí mismo un «Generated Guarantee File» Captura: llama-server v0.9.0 (localaiscope.com), 11-11-2026

Sí, la respuesta está mal, y con mucho arte: 135 millones de parámetros dan para probar un servidor, no para explicarlo. Para preguntas de verdad, un modelo de verdad. En este curso en español se arranca llama-server y se usan la interfaz de chat y el endpoint local:

Se abre en YouTube (sin cookies) solo si pulsas.

Varios modelos detrás de un solo servidor: el modo router

Arranca llama-server sin modelo y con una carpeta, y se convierte en un router:

llama-server --models-dir ~/modelos

Nuestro registro dijo starting server in router mode. models will be automatically loaded on-demand y, a modo de aviso, router mode enabled - do not expose to untrusted environments. /v1/models listó nuestros 2 ficheros GGUF (el mismo modelo, copiado con 2 nombres), cada uno con el nombre de su fichero sin .gguf y marcado unloaded. Una petición de chat sin nombre de modelo se llevó un 400: model name is missing from the request. Con "model": "SmolLM2-135M-Instruct-Q4_K_M" en el cuerpo, el router lanzó un llama-server aparte para ese modelo en su propio puerto, contestó, y la lista lo mostró loaded mientras el otro seguía unloaded. En el código leímos que mantiene hasta 4 modelos cargados por defecto (--models-max).

Se abre en YouTube (sin cookies) solo si pulsas.

El arranque que copiaríamos

Para una persona en una máquina:

export LLAMA_API_KEY="una-cadena-larga-y-aleatoria"
llama-server -m ./tu-modelo.gguf -c 8192 -np 1 --alias local

Eso te da un slot con los 8.192 tokens, una clave y un nombre corto de modelo, en 127.0.0.1:9931. Compruébalo con curl http://127.0.0.1:9931/health y curl -H "Authorization: Bearer $LLAMA_API_KEY" http://127.0.0.1:9931/v1/models. Instalar llama.cpp, elegir la compilación para tu tarjeta y el resto de la seguridad, CORS incluido, está en nuestra guía para instalar llama.cpp; lo que envía por su cuenta, en la ficha de llama.cpp; y si lo comparas con un servidor pensado para muchos usuarios, mira vLLM vs llama.cpp.