SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

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

llama.cpp añade tags vX.Y.Z junto a bNNNN. Fija uno, registra el GGUF y la cuantización, y prueba cada actualización para poder revertirla.

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 seguirá produciendo mañana lo mismo que produjo hoy. Durante años sólo hubo un tipo de tag disponible: 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.6.0, y ambas líneas no avanzan al mismo ritmo. Los tags de compilación se crean en casi cada commit de master. Un maintainer crea manualmente los tags de versión con menor frecuencia, y cada versión indica el tag de compilación que le corresponde.

Al principio, los tags de versión eran provisionales. Las notas de la versión v0.1.2, publicadas el 18 de agosto de 2026, lo indicaban en una línea:

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

Tres días después, v0.2.0 lo estableció. Sus notas de la versión indican que la versión «marca el inicio de un versionado semántico coherente para llama.cpp». Describen los tags vX.Y.Z como versiones estables con un ciclo de publicación más lento, recomendadas para la distribución posterior y los usuarios ocasionales, y los tags b[NUM] como compilaciones nocturnas o de desarrollo con la funcionalidad más reciente, recomendadas para desarrolladores y usuarios técnicos. A fecha de 14 de noviembre de 2026, el tag de versión más reciente es v1.0.0, publicado el 13 de noviembre, y sus notas indican que b12359 es el tag de compilación correspondiente.

La discusión de ggml que está detrás de ese enlace todavía conserva el razonamiento de este esquema y, a fecha de 21 de octubre de 2026, sigue abierta a comentarios. El versionado ya ha llegado a 1.x, por lo que debe leer las notas antes de cada cambio, en lugar de valorar una actualización según el dígito que haya cambiado.

El número de un tag de compilación no tiene significado de versión. Procede del recuento de commits, por lo que aumenta por sí solo, independientemente de que haya cambiado algo relevante para su configuración.

No compile desde master en un equipo que preste servicios

git pull seguido de una nueva compilación le proporciona todo lo que se haya incorporado durante las últimas horas. Esto está bien en un portátil. En un servidor, elimina la posibilidad de responder a la pregunta importante cuando cambia el comportamiento: qué se está ejecutando ahora y qué se estaba ejecutando la semana pasada. El texto que produce un modelo y la velocidad a la que lo produce también cambian con la compilación. Una queja sobre que las respuestas empeoraron el martes pasado no puede resolverse si el commit del martes nunca se registró.

Fije una etiqueta en su lugar. El proyecto las crea por usted y los archivos de versión precompilados incluyen una etiqueta de compilación en sus nombres, excepto los paquetes del entorno de ejecución CUDA para Windows (cudart-llama-bin-win-...).

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

Fije una etiqueta de compilación cuando necesite un estado concreto y conocido. Esta es la línea con el historial más largo, la que da nombre a los archivos de las versiones y la que aparece en la mayoría de los informes de errores. Por eso, el número de compilación es el dato más sencillo para comparar con otra persona.

Fije una etiqueta de versión si prefiere seguir una lista más corta de puntos definidos de forma deliberada. Esta es la línea que el proyecto recomienda actualmente para la distribución posterior. Cada versión indica la etiqueta de compilación correspondiente, y los binarios precompilados se encuentran en esa etiqueta de compilación. Por tanto, registre el número de compilación junto a la versión. Lea las notas antes de actualizar, aunque la numeración ya haya alcanzado 1.x.

En ambos casos, la regla operativa es la misma. La cadena de la etiqueta se guarda en un archivo, el servidor sólo se vuelve a compilar cuando cambia esa cadena 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 es una de las dos cosas que determinan la salida. El archivo del modelo es la otra. 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 pueden producir resultados distintos si uno tiene un archivo Q4_K_M y el otro un Q8_0. Mantenga junto al modelo un archivo pequeño con todo lo necesario para reconstruir exactamente la configuración:

tag: b10502
commit: 0adcc3b
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 durante la descarga. Comprobar una descarga con la suma de comprobación publicada permite detectar un archivo truncado antes de que provoque un error difícil de diagnosticar. El efecto del nivel de cuantización en las respuestas es una cuestión distinta. El coste de cada nivel de cuantización lo 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é cambia entre las actualizaciones de llama.cpp

Un archivo de modelo deja de cargarse. Esto suele ser lo que motiva la actualización: un modelo publicado recientemente usa una arquitectura que la compilación fijada no conoce y, por tanto, no se carga. llama-server termina durante el arranque. A fecha del 21 October 2026, el código fuente del servidor registra failed to load model, '/srv/models/model-q4_k_m.gguf' en este caso, con una coma y la ruta entre comillas simples, y la última línea que muestra es exiting due to model loading error, que no incluye ninguna ruta. Busque failed to load model en el journal en lugar de buscar la línea completa. Lea las líneas mostradas justo antes, incluida la línea error loading model: del propio cargador, porque indican hasta dónde llegó el cargador y por qué se detuvo. 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 la carga mucho antes de que intervenga la versión de formato. La solución es usar un tag más reciente y dejar constancia de cuál se eligió.

Se cambia el nombre o se declara obsoleta una opción del servidor. Una opción no reconocida hace que llama-server termine durante el arranque en lugar de ignorarse. 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 del 19 August 2026, la documentación del servidor marcaba --mlock y --mmap como obsoletas y recomendaba -lm, --load-mode. A fecha del 21 October 2026, ninguna de las dos opciones aparece ya en la documentación del servidor ni en la lista de argumentos de master. Traslade el comportamiento a --load-mode, que acepta auto (el valor predeterminado), none, mmap, mlock, mmap+mlock y dio. La opción de descarga en la GPU está documentada como -ngl, --gpu-layers, --n-gpu-layers, por lo que la forma larga de las guías antiguas todavía se acepta. Los valores predeterminados también cambian: desde v0.7.0, llama-server escucha de forma predeterminada en el puerto 9931 en lugar del 8080 (las imágenes de Docker mantienen el 8080 dentro del contenedor). Por tanto, una unidad que omita --port deja de responder donde la espera el reverse proxy. La versión v1.0.0 también elimina la opción obsoleta --defrag-thold. Antes de cambiar el symlink, ejecute /opt/llama.cpp/<new tag>/bin/llama-server --help y compruebe todas las opciones de la unidad.

Se cambia el nombre de una opción de compilación. Las opciones de CMake pasaron de usar el prefijo LLAMA_ a usar el prefijo GGML_, y el archivo raíz CMakeLists.txt todavía contiene la correspondencia. LLAMA_CUBLAS es ahora un error fatal que indica GGML_CUDA como sustitución, mientras que LLAMA_CUDA y LLAMA_METAL muestran una advertencia y realizan la traducción automáticamente. Que un script de compilación se detenga durante 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 indica CPU.

La compilación para el acelerador no es portable. A fecha del 19 August 2026, los assets de Linux asociados a un tag de compilación eran las variantes CPU, Vulkan, SYCL y OpenVINO, para x64, arm64 y s390x, sin ningún archivo CUDA para Linux. Esto ha cambiado desde entonces. A fecha del 21 October 2026, b11669, el tag de compilación asociado a v0.7.0, también incluye archivos CUDA de Ubuntu para CUDA 12.8 y 13.4 en x64 y para CUDA 13.4 en arm64. Cada uno incluye un archivo de runtime cudart- correspondiente, además de una compilación ROCm. En Linux y Windows, los archivos CUDA se publican por versión del toolkit. Esto da una pista importante: la versión del toolkit forma parte de lo que identifica el binario. Anótela 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 a la línea de desarrollo continuo: los archivos precompilados de la versión incluyen una en sus nombres (excepto los paquetes de runtime CUDA para Windows) y la mayoría de los informes de errores indican 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.6.0 forman una lista más corta de puntos seleccionados que el proyecto recomienda para la distribución posterior, lo que resulta adecuado para un servidor que se modifica varias veces al año. Cada una indica su etiqueta de compilación correspondiente, así que registre ambas. Lo importante es que la cadena de la etiqueta quede registrada junto al archivo del modelo y que la actualización sea una decisión, no un efecto secundario de git pull.

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

Sí, desde v0.2.0, el 21 de agosto de 2026. Las notas de la versión indican que ese cambio marca el inicio de un versionado semántico coherente para llama.cpp y sustituye la advertencia de trabajo en curso que incluía v0.1.2. Al 14 de noviembre de 2026, la numeración de versiones ya ha alcanzado 1.x; la más reciente es v1.0.0, publicada el 13 de noviembre. Lea las notas de la versión antes de actualizar y pruebe la nueva etiqueta con su propio archivo de modelo antes de cambiar a ella, independientemente del dígito que haya cambiado.

¿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. Ejecútelo contra el binario que utiliza el servicio: /opt/llama.cpp/current/bin/llama-server --version. Al 21 de octubre de 2026, la línea de inicio que contiene el número de compilación, el hash del commit y el compilador se registra en el nivel trace. Por tanto, no cuente con encontrarla en journalctl -u llama-server con el nivel de registro predeterminado. 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 justo después de una actualización indica una incompatibilidad entre la compilación y el archivo GGUF. El registro contiene una línea failed to load model, '<path>' con el nombre del archivo y termina con exiting due to model loading error. Las líneas anteriores muestran hasta dónde leyó el cargador. Al avanzar a una compilación más reciente, un archivo de modelo muy nuevo necesita una compilación que conozca su arquitectura. Al retroceder, una reversión a una etiqueta anterior a la etiqueta 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 correctamente juntos antes de decidir cuál de los dos debe cambiar.

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

Sí. Cada etiqueta de compilación incluye archivos de versión con nombres basados en ella, como llama-b10502-bin-ubuntu-x64.tar.gz. Por tanto, la etiqueta aparece en el nombre del archivo y es fácil fijarla. El 19 de agosto de 2026, el conjunto para Linux incluía CPU, arm64, s390x, Vulkan, SYCL y OpenVINO, sin ningún archivo CUDA. Al 21 de octubre de 2026, la versión más reciente b11669 también incluye archivos para Ubuntu con CUDA 12.8 y 13.4, junto con paquetes de runtime cudart- compatibles. Por tanto, un servidor NVIDIA con una etiqueta reciente ya no tiene que compilar desde el código fuente con -DGGML_CUDA=ON ni ejecutar una imagen de contenedor CUDA. Si fija una etiqueta de versión, descargue los archivos de la etiqueta de compilación que indiquen sus notas de la versión.

¿Te resultó útil este artículo?