Hands-on Lab

llama.cpp server en Docker con una API compatible con OpenAI

21 de octubre de 2026 4 min 1

0 / 5

Chuleta

¿Te ha servido? No te pierdas el próximo lab

El vídeo tiene subtítulos y transcripción. Todo lo que se ve está escrito, paso a paso, más abajo. Chuleta con todos los comandos

0:00 / 0:00

Descargamos la imagen server de llama.cpp desde el registro de GitHub con la etiqueta fijada server-v0.5.0. Solo contiene el binario llama-server y tiene variantes para amd64 y arm64; la etiqueta server sin versión apunta a la compilación nocturna y cambia sola.

docker pull ghcr.io/ggml-org/llama.cpp:server-v0.5.0

Lo hice yo

Comprobamos que Docker eligió la variante linux/arm64 de la imagen y le pedimos la versión al binario: 0.5.0, compilación 11146, compilado para Linux aarch64. El sufijo -dev aparece porque la imagen se compila con LLAMA_BUILD_IS_DEV activado.

docker image inspect --format '{{.Os}}/{{.Architecture}}' ghcr.io/ggml-org/llama.cpp:server-v0.5.0 && docker run --rm ghcr.io/ggml-org/llama.cpp:server-v0.5.0 --version 2>&1 | grep -E '^(version|built)'

Qué demuestra

linux/arm64 Docker descargó la variante arm64 de la imagen multiarquitectura Objetivo · sabes que la misma etiqueta funciona en tu máquina arm64 sin compilar nada
version: 0.5.0-dev (build 11146 el binario de la imagen es la versión 0.5.0, compilación 11146 Objetivo · confirmas que ejecutas la versión estable que fija la guía y no una nocturna

Creamos /srv/llama/llama_keys con una línea de comentario y la clave de prueba tu_clave_de_api, y le damos permisos 600 para que solo root la lea. El contenedor montará este fichero en solo lectura; en un servidor real, usa una clave larga y aleatoria.

mkdir -p /srv/llama && printf '# clave de prueba del lab\ntu_clave_de_api\n' > /srv/llama/llama_keys && chmod 600 /srv/llama/llama_keys

Lo hice yo

Comprobamos que el fichero pertenece a root con permisos 600 y que, sin contar los comentarios, contiene exactamente una clave.

stat -c '%a %U %n' /srv/llama/llama_keys && echo "keys: $(grep -vc '^#' /srv/llama/llama_keys)"

Qué demuestra

600 root /srv/llama/llama_keys el fichero de claves solo lo puede leer root Objetivo · la clave no queda al alcance de otros usuarios de la máquina
keys: 1 hay una única línea de clave, sin contar el comentario Objetivo · sabes exactamente qué clave aceptará el servidor

Arrancamos llama-server en segundo plano. Con -hf descarga de Hugging Face la cuantización Q4_0 de Qwen3.5 0.8B al volumen llama-cache, al que apunta LLAMA_CACHE. Con --alias fijamos el nombre que verán los clientes, y con -t 4 usa 4 de los 18 núcleos. La opción -c 4096 limita el contexto, --api-key-file exige la clave y el puerto solo se publica en 127.0.0.1.

docker run -d --name llama-server -p 127.0.0.1:8080:8080 -v llama-cache:/cache -e LLAMA_CACHE=/cache -v /srv/llama/llama_keys:/run/secrets/llama_keys:ro ghcr.io/ggml-org/llama.cpp:server-v0.5.0 -hf ggml-org/Qwen3.5-0.8B-GGUF:Q4_0 --alias qwen3.5-0.8b -t 4 -c 4096 --port 8080 --api-key-file /run/secrets/llama_keys

Lo hice yo

Consultamos /health cada 2 s, con un máximo de 200 intentos, en lugar de esperar a ciegas con sleep. La descarga del GGUF ocupa casi toda la espera. Al final, /health devuelve {"status":"ok"} con un 200 sin enviar la clave: llama-server lo deja abierto para los healthchecks.

s=$(date +%s); for i in $(seq 1 200); do curl -sf -o /dev/null http://127.0.0.1:8080/health && break; sleep 2; done; echo "ready after $(( $(date +%s) - s )) s"; curl -sf -w '\nhealth without key: HTTP %{http_code}\n' http://127.0.0.1:8080/health

Qué demuestra

{"status":"ok"} el servidor terminó de cargar el modelo y acepta peticiones Objetivo · sabes cuándo puedes empezar a enviar peticiones, sin adivinar un tiempo de espera
health without key: HTTP 200 /health responde 200 aunque la petición no lleva clave Objetivo · puedes usar /health como healthcheck de Docker o del proxy sin repartir la clave

Leemos el registro de arranque: el modelo que cargó, los 4 hilos, las 4 ranuras que comparten los 4096 tokens de contexto y la dirección en la que escucha. Después, dentro del contenedor, medimos el fichero Qwen3.5-0.8B-Q4_0.gguf que quedó en la caché del volumen.

docker logs llama-server 2>&1 | grep -oE 'loading model .*|n_threads = [0-9]+|n_slots = .*|listening on .*'; docker exec llama-server sh -c 'du -shL /cache/models--*/snapshots/*/*.gguf'

Qué demuestra

n_threads = 4 llama-server usa los 4 hilos que pedimos con -t 4 Objetivo · controlas cuánta CPU ocupa el servidor y dejas núcleos libres para lo demás
Qwen3.5-0.8B-Q4_0.gguf el GGUF descargado está en la caché, dentro del volumen llama-cache Objetivo · sabes dónde vive el modelo y que no forma parte de la capa del contenedor

Pedimos la lista de modelos sin la cabecera Authorization. El servidor la rechaza con un 401 y un cuerpo de error con la misma forma que usa OpenAI: message, type authentication_error y code.

curl -s -w '\nHTTP %{http_code}\n' http://127.0.0.1:8080/v1/models

Qué demuestra

Invalid API Key llama-server rechaza la petición porque no lleva una clave válida Objetivo · compruebas que nadie usa tu modelo sin la clave, aunque llegue al puerto
HTTP 401 el código de estado es 401 Unauthorized Objetivo · un cliente de OpenAI recibirá el mismo error de autenticación que con la API original

Repetimos la petición con la cabecera Authorization: Bearer y la clave del fichero. Ahora responde 200, y jq filtra la lista con el formato de OpenAI: el identificador es el alias qwen3.5-0.8b, en Q4_0 y con 4096 tokens de contexto.

curl -s -o /dev/null -w 'with key: HTTP %{http_code}\n' -H 'Authorization: Bearer tu_clave_de_api' http://127.0.0.1:8080/v1/models; curl -s -H 'Authorization: Bearer tu_clave_de_api' http://127.0.0.1:8080/v1/models | jq '{object, data: [.data[] | {id, owned_by, ftype: .meta.ftype, n_ctx: .meta.n_ctx}]}'

Qué demuestra

with key: HTTP 200 con la clave del fichero la petición se acepta Objetivo · confirmas que --api-key-file leyó la clave y saltó la línea de comentario
"id": "qwen3.5-0.8b" el modelo aparece con el nombre que fijamos con --alias Objetivo · sabes qué valor poner en el campo model de tus clientes
"ftype": "Q4_0" el servidor cargó la cuantización Q4_0 que pedimos con -hf Objetivo · compruebas que la etiqueta :Q4_0 eligió el fichero pequeño y no el Q8_0

Enviamos la misma petición que haríamos a la API de OpenAI, con temperatura 0, un máximo de 64 tokens y reasoning_effort none para que Qwen3.5 conteste sin razonar antes. jq extrae la respuesta, el motivo de parada y el bloque usage con los tokens del prompt y de la respuesta.

curl -s http://127.0.0.1:8080/v1/chat/completions -H 'Content-Type: application/json' -H 'Authorization: Bearer tu_clave_de_api' -d '{"model": "qwen3.5-0.8b", "messages": [{"role": "user", "content": "Explica qué es un contenedor Docker en una frase."}], "max_tokens": 64, "temperature": 0, "reasoning_effort": "none"}' | jq '{model, content: .choices[0].message.content, finish_reason: .choices[0].finish_reason, usage: {prompt_tokens: .usage.prompt_tokens, completion_tokens: .usage.completion_tokens, total_tokens: .usage.total_tokens}}'

Qué demuestra

"finish_reason": "stop" el modelo terminó la respuesta por sí mismo, antes del límite de 64 tokens Objetivo · sabes que la respuesta está completa y no cortada por max_tokens
"completion_tokens": la respuesta trae el bloque usage de OpenAI con los tokens consumidos Objetivo · puedes medir el consumo de cada petición igual que con la API de OpenAI
toda la respuesta la generó el modelo local en CPU, sin salir de la máquina Objetivo · tienes una API compatible con OpenAI que no depende de un servicio externo

Borramos el contenedor con docker rm -f y lo creamos de nuevo con exactamente las mismas opciones y el mismo volumen llama-cache. Es lo que harías al cambiar la etiqueta de la imagen para actualizar.

docker rm -f llama-server && docker run -d --name llama-server -p 127.0.0.1:8080:8080 -v llama-cache:/cache -e LLAMA_CACHE=/cache -v /srv/llama/llama_keys:/run/secrets/llama_keys:ro ghcr.io/ggml-org/llama.cpp:server-v0.5.0 -hf ggml-org/Qwen3.5-0.8B-GGUF:Q4_0 --alias qwen3.5-0.8b -t 4 -c 4096 --port 8080 --api-key-file /run/secrets/llama_keys

Lo hice yo

Repetimos la espera sobre /health, ahora cada segundo. Compara la cifra de ready after con la del primer arranque: el servidor solo carga el GGUF que ya estaba en el volumen llama-cache, sin pedirlo otra vez a Hugging Face.

s=$(date +%s); for i in $(seq 1 60); do curl -sf -o /dev/null http://127.0.0.1:8080/health && break; sleep 1; done; echo "ready after $(( $(date +%s) - s )) s"; curl -sf http://127.0.0.1:8080/health; echo; docker volume ls --filter name=llama-cache --format 'volume: {{.Name}}'

Qué demuestra

{"status":"ok"} el contenedor nuevo está listo para atender peticiones Objetivo · puedes recrear o actualizar el contenedor sin perder el modelo
volume: llama-cache el volumen llama-cache sobrevivió al docker rm Objetivo · sabes que la descarga del modelo se hace una sola vez por máquina

Borramos el contenedor llama-server, el volumen llama-cache con el GGUF descargado y el directorio /srv/llama con la clave de prueba.

docker rm -f llama-server && docker volume rm llama-cache && rm -rf /srv/llama

Lo hice yo

Comprobamos que no queda ningún contenedor llamado llama-server, ningún volumen llama-cache y que el directorio /srv/llama ya no existe.

docker ps -a --filter name=llama-server --format '{{.Names}}' | grep . || echo 'no llama-server container'; docker volume ls --filter name=llama-cache --format '{{.Name}}' | grep . || echo 'no llama-cache volume'; ls /srv/llama 2>/dev/null || echo 'no /srv/llama'

Qué demuestra

no llama-cache volume el volumen con el modelo ya no existe Objetivo · recuperas el espacio en disco que ocupaba el GGUF
no llama-server container no queda ningún contenedor del laboratorio Objetivo · dejas la máquina como estaba antes del laboratorio

1 vista

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

Transcripción del vídeo

0:00 Un modelo local que responde como la API de OpenAI, dentro de Docker.
0:07 Descargamos la imagen server de llama.cpp con la etiqueta fijada
0:13 server-v0.5.0, la misma que usa la guía.
0:18 Servimos un modelo GGUF con llama.cpp en Docker y le hablamos como a la API de
0:24 OpenAI.
0:26 llama-server es el binario de llama.cpp que carga un
0:32 GGUF y lo sirve por HTTP con la forma de la API de OpenAI.
0:38 El recorrido:
0:39 Hugging Face, la caché en un volumen, llama-server y la respuesta en formato
0:45 OpenAI.
0:47 Lo comprobamos:
0:48 la imagen es linux/arm64 y el binario dice versión 0.5.0, compilación
0:54 11146.
0:57 Con --api-key-file, cada petición necesita la cabecera Authorization con una de las
1:02 claves del fichero.
1:05 Guardamos la clave de API en un fichero con permisos 600, con una línea de
1:10 comentario y una clave de prueba.
1:13 Lo comprobamos:
1:14 el fichero es de root, tiene permisos 600 y contiene una sola clave.
1:23 Con -hf, el propio contenedor descarga el GGUF a la caché, lo carga y abre el
1:29 puerto.
1:30 Arrancamos llama-server:
1:32 descarga Qwen3.5 0.8B en Q4_0 a un volumen, usa 4
1:38 hilos y exige la clave del fichero.
1:42 Esperamos a que /health responda ok, con un límite de intentos.
1:47 Mientras descarga y carga el modelo, el servidor aún no contesta.
1:51 En el registro vemos 4 hilos y el puerto 8080, y en el volumen está el
1:57 fichero GGUF que bajó de Hugging Face.
2:02 Sin clave, /v1/models responde 401 con un error en el formato de OpenAI:
2:08 Invalid API Key.
2:11 Con la clave, la respuesta es 200 y /v1/models lista
2:15 qwen3.5-0.8b, en Q4_0 y con 4096 tokens de contexto.
2:23 La prueba de verdad:
2:24 una petición a /v1/chat/completions.
2:29 El modelo contesta en una frase y el bloque usage cuenta los tokens.
2:35 El volumen vive fuera del contenedor, así que el GGUF sigue ahí después de docker
2:40 rm.
2:42 Borramos el contenedor y creamos otro con el mismo volumen, para ver qué pasa con el
2:47 modelo descargado.
2:50 Esta vez /health responde ok mucho antes:
2:53 el modelo ya estaba en el volumen y no se descarga otra vez.
2:58 Limpiamos:
2:59 borramos el contenedor, el volumen con el modelo y el fichero de claves.
3:05 Lo comprobamos:
3:06 no queda ni el contenedor, ni el volumen, ni la clave.

Este laboratorio ejecuta llama.cpp server en Docker y lo pone a prueba como si fuera la API de OpenAI. Es la parte de Docker de nuestra guía cómo instalar llama.cpp en Linux, macOS y Docker, llevada hasta la API que detallamos en llama-server como API compatible con OpenAI en Docker. Todo lo que ves en la terminal se ejecutó de verdad, en una máquina arm64 sin GPU.

Qué hace este laboratorio

Arrancas la imagen ghcr.io/ggml-org/llama.cpp:server-v0.5.0, la misma etiqueta que fija la guía de la API. Con -hf ggml-org/Qwen3.5-0.8B-GGUF:Q4_0 el contenedor descarga el modelo de Hugging Face a un volumen montado en /cache. Esperas a que /health devuelva {"status":"ok"} en un bucle con límite, y luego compruebas tres cosas: sin clave, /v1/models responde 401; con clave, lista el modelo; y /v1/chat/completions devuelve una respuesta con su bloque usage.

Por qué este modelo y no el de la guía de la API

La guía de la API usa Qwen3 1.7B en Q8_0, un GGUF de 1,8 GB. Para que el laboratorio se pueda repetir con poca descarga elegimos el modelo de la guía de instalación, Qwen3.5 0.8B, del repositorio ggml-org/Qwen3.5-0.8B-GGUF, en su cuantización Q4_0. Ese repositorio no tiene Q4_K_M, así que sin la etiqueta :Q4_0 el servidor bajaría el Q8_0, más pesado. Qwen3.5 razona antes de responder, y por eso la petición lleva "reasoning_effort": "none" y un max_tokens de 64. Si te interesa elegir otra cuantización, la tienes explicada en cuantización de modelos y llama.cpp en tu portátil.

La clave de API y el volumen de caché

La clave vive en un fichero con permisos 600 que el contenedor monta en solo lectura y lee con --api-key-file, una línea por clave y comentarios con #, según la referencia de opciones de llama-server. Es el mismo principio que en nuestro laboratorio de gestión de secretos en Docker: la clave no queda en la imagen ni en la línea de órdenes. El valor tu_clave_de_api es de prueba; en tu servidor usa una clave larga y aleatoria.

El modelo se guarda en un volumen con nombre, como describe la documentación de volúmenes de Docker. Por eso, al borrar el contenedor y crear otro con el mismo volumen, el servidor arranca sin volver a descargar el GGUF. Si quieres ver ese mecanismo con más detalle, mira el laboratorio sobre cómo persisten los datos en Docker con volúmenes y bind mounts.

Cómo usar esta API desde tu código

El cuerpo de la petición sigue el formato de la API de chat de OpenAI, así que el SDK oficial funciona apuntando base_url a http://127.0.0.1:8080/v1 con tu clave. El puerto se publica solo en 127.0.0.1; para exponerlo fuera, ponlo detrás de un proxy inverso con TLS. Las variantes de la imagen para GPU, como server-cuda y server-vulkan, están en la documentación de Docker de llama.cpp; aquí no las probamos porque la máquina no tiene GPU.

Preguntas frecuentes

¿Qué etiqueta de la imagen de llama.cpp uso en Docker?

Una etiqueta fijada como ghcr.io/ggml-org/llama.cpp:server-v0.5.0. La etiqueta server sin versión apunta a la compilación nocturna y cambia sola; con la versión fijada actualizas cuando tú decides, cambiando la etiqueta. En este laboratorio el binario de esa imagen informa de la compilación 11146 para Linux aarch64.

¿Hace falta una GPU para ejecutar llama-server en Docker?

No. La imagen server funciona solo con CPU, y este laboratorio se grabó en una máquina arm64 sin GPU con 4 hilos (-t 4). Un modelo de 0,8 B en Q4_0 responde a una pregunta corta en menos de un segundo. Para GPU existen las variantes server-cuda y server-vulkan de la misma imagen.

¿Por qué /health responde sin clave si arranqué llama-server con –api-key-file?

Porque llama-server deja /health abierto a propósito, para que un healthcheck de Docker o de un proxy inverso pueda comprobar el servicio sin conocer la clave. Todo lo demás, incluido /v1/models, devuelve un 401 con el mensaje Invalid API Key si falta la cabecera Authorization.

¿Dónde guarda el contenedor el modelo que descarga con -hf?

En la ruta que indica la variable LLAMA_CACHE, con la estructura de la caché de Hugging Face (models–usuario–repositorio). Si esa ruta es un volumen de Docker, el GGUF sobrevive a docker rm y el siguiente contenedor arranca sin volver a descargarlo.

Chuleta

docker pull ghcr.io/ggml-org/llama.cpp:server-v0.5.0

mkdir -p /srv/llama && printf '# clave de prueba del lab\ntu_clave_de_api\n' > /srv/llama/llama_keys && chmod 600 /srv/llama/llama_keys

docker run -d --name llama-server -p 127.0.0.1:8080:8080 -v llama-cache:/cache -e LLAMA_CACHE=/cache -v /srv/llama/llama_keys:/run/secrets/llama_keys:ro ghcr.io/ggml-org/llama.cpp:server-v0.5.0 -hf ggml-org/Qwen3.5-0.8B-GGUF:Q4_0 --alias qwen3.5-0.8b -t 4 -c 4096 --port 8080 --api-key-file /run/secrets/llama_keys

docker rm -f llama-server && docker run -d --name llama-server -p 127.0.0.1:8080:8080 -v llama-cache:/cache -e LLAMA_CACHE=/cache -v /srv/llama/llama_keys:/run/secrets/llama_keys:ro ghcr.io/ggml-org/llama.cpp:server-v0.5.0 -hf ggml-org/Qwen3.5-0.8B-GGUF:Q4_0 --alias qwen3.5-0.8b -t 4 -c 4096 --port 8080 --api-key-file /run/secrets/llama_keys

docker rm -f llama-server && docker volume rm llama-cache && rm -rf /srv/llama

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

Qué hace este laboratorio

Por qué este modelo y no el de la guía de la API

La clave de API y el volumen de caché

Cómo usar esta API desde tu código

Preguntas frecuentes

¿Qué etiqueta de la imagen de llama.cpp uso en Docker?

¿Hace falta una GPU para ejecutar llama-server en Docker?

¿Por qué /health responde sin clave si arranqué llama-server con –api-key-file?

¿Dónde guarda el contenedor el modelo que descarga con -hf?

Chuleta