Cómo fijar versiones de llama.cpp en un servidor

Qué cambió en el versionado de llama.cpp

Fijar las versiones de llama.cpp significa compilar un tag con nombre y registrar ese nombre junto al archivo del modelo. El tag no cambia por sí solo, por lo que el servidor sigue produciendo mañana lo mismo que produce hoy. Durante años sólo hubo un tipo de tag entre los que elegir: un número de compilación como b10502, creado automáticamente a partir de master. Desde 2026 existe un segundo tipo, un tag de versión como v0.1.2, y ambas líneas se crean al mismo tiempo a partir del mismo historial.

Los tags de versión todavía no significan lo que suele significar un número de versión. Las notas de la versión en v0.1.2 lo indican en una línea:

El versionado semántico todavía está en proceso. Hay más información en https://github.com/ggml-org/ggml/discussions/1579

Interprételo literalmente. La discusión de ggml asociada a ese enlace es donde todavía se está definiendo el esquema, incluida la frecuencia de publicación de versiones y lo que cuenta como un parche. Un tag v0. indica que el proyecto decidió marcar un punto del historial. No garantiza que el siguiente sea un reemplazo directo seguro sólo porque el último dígito haya aumentado en uno.

El número de un tag de compilación tampoco tiene significado de versión. Proviene del número de commits, por lo que aumenta por sí solo, aunque no haya cambiado nada relevante para su configuración. Al 19 de agosto de 2026, la página principal de la lista de versiones contenía nueve tags de compilación, desde b10455 hasta b10502, con v0.1.2 entre ellos.

Nunca compile desde master en un equipo que atienda tráfico

git pull seguido de una recompilación instala todo lo que se haya incorporado durante las últimas horas. Esto está bien en un portátil. En un servidor, impide responder a la pregunta importante cuando cambia el comportamiento: qué se está ejecutando ahora y qué se ejecutaba la semana pasada. El texto que produce un modelo y la velocidad con la que lo produce también cambian con la compilación. Si alguien informa de que las respuestas empeoraron el martes pasado, no habrá respuesta si el commit del martes no se registró.

Fije una etiqueta en su lugar. El proyecto las crea y cada archivo de versión precompilado lleva el nombre de una de ellas.

¿A qué etiqueta debe fijar las versiones de llama.cpp?

Fije una etiqueta de compilación cuando necesite un estado específico y conocido. Esta es la línea con el historial más extenso, la que se usa para nombrar los archivos de las versiones y la que aparece en la mayoría de los informes de errores. Por eso, un número de compilación es la forma más sencilla de comparar el estado con el de otro sistema.

Fije una etiqueta de versión si prefiere seguir una lista más corta de puntos definidos deliberadamente. Lea las notas antes de cambiar de versión y tenga en cuenta la advertencia anterior, porque la numeración todavía no constituye un contrato de compatibilidad.

En ambos casos, la regla operativa es la misma. La cadena de la etiqueta se guarda en un archivo, el sistema sólo se vuelve a compilar cuando esa cadena cambia y el cambio debe ser una decisión deliberada.

Compilar la etiqueta fijada

sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tags

git describe --tags debe mostrar b10502. Un clon superficial de una etiqueta contiene ese commit y ningún commit posterior, por lo que nadie puede moverla después mediante un git pull ejecutado por error. Si el paso de configuración se detiene porque falta una dependencia, instale la que indique y vuelva a ejecutarlo.

Compile con las opciones que necesite su hardware. Sólo CPU:

cmake -B build
cmake --build build --config Release -j $(nproc)

GPU NVIDIA, que requiere instalar primero el kit de herramientas CUDA:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

OpenBLAS en un equipo que sólo usa CPU:

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)

Los binarios se generan en build/bin, junto a las bibliotecas compartidas que cargan (libllama.so y los archivos libggml). Confirme que la compilación funciona antes de instalarla:

./build/bin/llama-server --version

Instale todo el directorio en una ruta cuyo nombre corresponda a la etiqueta y, después, apunte un único enlace simbólico a él:

sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current

Copie el directorio, no sólo el archivo. Un llama-server aislado falla en su primera ejecución con error while loading shared libraries: libllama.so: cannot open shared object file, porque las bibliotecas que necesita están junto a él en ese directorio.

Configure el servicio para usar el enlace simbólico, nunca un directorio de etiquetas:

[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080

systemd resuelve el enlace simbólico cuando inicia el proceso, por lo que cambiar de compilación sólo requiere establecer un nuevo destino para el enlace y ejecutar sudo systemctl restart llama-server. El resto del archivo de unidad y el reverse proxy situado delante se explican en la guía completa para un servidor llama.cpp en un VPS.

Registre la etiqueta junto al archivo GGUF y la cuantización

La compilación determina parte del resultado. El archivo del modelo determina la otra parte. GGUF (GGML universal file format) es el contenedor en el que se distribuyen los pesos. El mismo modelo se publica con muchos niveles de cuantización. Por eso, dos servidores con la misma etiqueta aún pueden producir resultados distintos si uno contiene un archivo Q4_K_M y el otro un archivo Q8_0. Mantenga un archivo pequeño junto al modelo con toda la información necesaria para reconstruir exactamente la configuración:

tag: b10502
commit: 7c1f2a9
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>

Obtenga el commit con git rev-parse --short HEAD dentro del checkout fijado. Obtenga la suma de comprobación con sha256sum model-q4_k_m.gguf y compárela también con el valor del editor al descargar el archivo. Comprobar una descarga con su suma de comprobación publicada permite detectar un archivo truncado antes de que cause un problema difícil de diagnosticar. El efecto del nivel de cuantización sobre las respuestas es otra cuestión. Qué coste tiene cada nivel de cuantización la explica.

¿Cómo se actualiza sin romper el servidor?

Ejecute la actualización como una prueba. Compile el nuevo tag junto al anterior, mida ambos y conserve el anterior hasta que el nuevo haya demostrado que funciona.

1. Clone el nuevo tag en su propio directorio. No reutilice el checkout anterior.
2. Compile con los mismos argumentos de cmake registrados en el manifiesto.
3. Ejecute llama-bench en ambas compilaciones con el mismo archivo de modelo, la misma longitud del prompt y el mismo número de repeticiones.
4. Envíe a ambos servidores un prompt cuya respuesta conozca bien y lea las dos respuestas.
5. Mueva el enlace simbólico, reinicie el servicio y deje el directorio anterior en el disco.

/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5

llama-bench imprime una fila por prueba, con una columna backend, una columna ngl y una columna de tokens por segundo que incluye su desviación estándar. Compare la misma fila entre las dos compilaciones. No compare la fila del prompt de una compilación con la fila de generación de la otra. Una cifra obtenida con una longitud de prompt diferente es una medición distinta. Por eso medir los tokens por segundo siempre de la misma forma es más importante que el valor en sí.

La reversión requiere dos comandos y sólo funciona porque el directorio anterior todavía existe:

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

Conserve como mínimo la compilación anterior. Ocupa una fracción del espacio de disco que ya utiliza el archivo de modelo situado junto a ella.

Qué se rompe al actualizar llama.cpp

Un archivo de modelo deja de cargarse. Esta suele ser la razón principal para actualizar: un modelo publicado recientemente usa una arquitectura que la compilación fijada no conoce, por lo que nunca se carga. llama-server termina durante el arranque y el registro contiene una línea failed to load model from /srv/models/model-q4_k_m.gguf. Lea las líneas que aparecen justo antes. Muestran hasta dónde llegó el cargador. GGUF también incluye una versión de formato en su encabezado (el valor actual de la especificación es 3, y la versión 2 amplió los campos de longitud de 32 a 64 bits), aunque en la práctica un nombre de arquitectura desconocido detiene el proceso mucho antes de que intervenga la versión de formato. La solución es usar una etiqueta más reciente y dejar constancia de ella.

Se cambia el nombre de una opción del servidor o queda obsoleta. Una opción no reconocida detiene llama-server durante el arranque en lugar de ignorarla. Con systemd, esto parece un servicio que arranca y termina en un bucle. journalctl -u llama-server -n 50 muestra el mensaje real. A fecha de 19 August 2026, la documentación del servidor marca --mlock y --mmap como obsoletas y recomienda -lm, --load-mode, que acepta valores como auto, mmap, mlock y dio. La opción de descarga de trabajo a la GPU está documentada como -ngl, --gpu-layers, mientras que las guías antiguas escriben --n-gpu-layers. Antes de mover el enlace simbólico, ejecute /opt/llama.cpp/<new tag>/bin/llama-server --help y compruebe todas las opciones del archivo de unidad.

Se cambia el nombre de una opción de compilación. Las opciones de CMake pasaron de usar el prefijo LLAMA_ al prefijo GGML_, y el archivo raíz CMakeLists.txt sigue conteniendo la correspondencia. LLAMA_CUBLAS ahora genera un error fatal que indica GGML_CUDA como reemplazo, mientras que LLAMA_CUDA y LLAMA_METAL generan una advertencia y se traducen automáticamente. Que un script de compilación se detenga en el paso de configuración es un resultado correcto. El fallo silencioso es peor: si omite -DGGML_CUDA=ON por accidente, la compilación termina correctamente, el servidor arranca y todo se ejecuta en la CPU. llama-bench lo muestra de inmediato, porque la columna backend contiene CPU.

La compilación para el acelerador no es portable. A fecha de 19 August 2026, los recursos de Linux asociados a una etiqueta de compilación son las variantes CPU, Vulkan, SYCL y OpenVINO, para x64, arm64 y s390x. No hay un archivo CUDA para Linux en esa lista. Por tanto, un servidor NVIDIA requiere compilar desde el código fuente o ejecutar una imagen de contenedor. Los archivos CUDA para Windows se publican por versión del toolkit. Esto da una pista útil: la versión del toolkit forma parte de la identificación del binario, por lo que debe registrarla junto con los argumentos de cmake.

Fijar la imagen del contenedor

La misma regla se aplica a otro nombre. Las imágenes publicadas (ghcr.io/ggml-org/llama.cpp:server y sus variantes con acelerador) usan nombres que cambian, por lo que descargar :server el próximo mes proporciona un programa diferente bajo la misma etiqueta. Descárguela una vez y lea el resumen criptográfico:

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

docker pull muestra una línea Digest: sha256:.... Ponga ese resumen en el archivo compose en lugar de la etiqueta. Así, la imagen no puede cambiar sin que lo advierta la próxima vez que alguien ejecute docker compose pull. Mantenga el resumen anterior en un comentario para que una reversión requiera editar una sola línea, igual que la rutina de actualización y reversión para una pila de Compose trata cualquier otro servicio.

La función de fijar versiones

Una versión fijada permite saber exactamente qué se está ejecutando y restaurar la compilación anterior en menos de un minuto cuando un cambio empeora la situación. llama.cpp exige controlar dos elementos para ello: la etiqueta de compilación y el archivo del modelo, porque los proporciona por separado. Los entornos de ejecución que los incluyen en un único paquete funcionan de otra forma. La comparación entre Ollama y llama.cpp como servidores explica esa diferencia: un solo número de versión para todo requiere registrar y controlar menos elementos.

FAQ

¿Debo fijar la etiqueta de compilación bNNNN o la etiqueta v0.x?

Cualquiera de las dos sirve, siempre que fije una. Las etiquetas de compilación como b10502 corresponden al canal de mantenimiento prolongado: cada archivo de lanzamiento precompilado usa una de ellas en su nombre y la mayoría de los informes de errores mencionan una. Por eso, el número de compilación es la forma más sencilla de comparar con otro operador. Las etiquetas de versión como v0.1.2 forman una lista más corta de puntos seleccionados deliberadamente. Esto resulta adecuado para un servidor que se modifica unas pocas veces al año. Lo más importante no es la elección, sino registrar la cadena de la etiqueta junto al archivo del modelo y hacer que la actualización sea una decisión, no un efecto secundario de git pull.

¿llama.cpp sigue ahora el versionado semántico?

Todavía no, según la propia declaración del proyecto. Las notas de la versión v0.1.2 indican que el versionado semántico todavía está en desarrollo y remiten a un debate de ggml donde se está definiendo el esquema, incluida la frecuencia de publicación y lo que se considera un parche. Interprete una etiqueta de versión como un punto que los mantenedores han decidido marcar. No suponga que un cambio en el último dígito garantiza una actualización directa y pruebe la nueva etiqueta con su propio archivo de modelo antes de cambiar a ella.

¿Cómo puedo saber qué compilación de llama.cpp ejecuta mi servidor?

llama-server --version muestra la versión y la información de compilación. El registro de inicio también comienza con una línea build que contiene el número de compilación, el hash del commit y el compilador utilizado. Por tanto, journalctl -u llama-server permite encontrarla en un servicio en ejecución. En una instalación desde el código fuente, git describe --tags dentro del checkout fijado muestra la etiqueta, y readlink /opt/llama.cpp/current indica a qué directorio apunta realmente el servicio.

¿Por qué mi modelo dejó de cargarse después de actualizar llama.cpp?

Un fallo de carga inmediatamente después de una actualización indica una incompatibilidad entre la compilación y el archivo GGUF. El registro termina con una línea failed to load model from que indica la ruta, y las líneas anteriores muestran hasta dónde llegó el cargador. Si se avanza, un archivo de modelo muy nuevo necesita una compilación que conozca su arquitectura. Si se retrocede, una reversión a una etiqueta anterior a aquella con la que se creó el archivo puede romper un archivo que funcionaba el día anterior. Apunte el enlace simbólico a la compilación anterior, reinicie y confirme qué compilación y archivo funcionan juntos correctamente antes de decidir cuál de los dos debe cambiar.

¿Hay binarios de Linux precompilados que pueda fijar en lugar de compilar?

Sí, para algunas configuraciones. Cada etiqueta de compilación incluye archivos de lanzamiento cuyo nombre contiene dicha etiqueta, como llama-b10502-bin-ubuntu-x64.tar.gz, junto con variantes arm64, s390x, Vulkan, SYCL y OpenVINO disponibles al 19 August 2026. Esta nomenclatura facilita fijar una versión porque la etiqueta aparece en el nombre del archivo. En esa lista no había ningún archivo CUDA para Linux. Por tanto, un servidor NVIDIA todavía requiere compilar desde el código fuente con -DGGML_CUDA=ON o ejecutar una de las imágenes de contenedor de CUDA.