Llama Cpp Python: instalación, compilación con GPU y parámetros

llama-cpp-python es el enlace en Python para llama.cpp. Carga modelos GGUF directamente en memoria, expone un contenedor de bajo nivel basado en ctypes, además de una interfaz de alto nivel mediante una clase Llama y también incluye un servidor HTTP compatible con OpenAI. La instalación predeterminada mediante pip compila una versión exclusiva para CPU. Para usar la GPU, debe instalar una versión precompilada con soporte para GPU o volver a compilar desde el código fuente con CMAKE_ARGS, y luego pasar n_gpu_layers.

Por qué la instalación predeterminada es exclusiva para CPU

El paquete es un enlace ligero alrededor de una biblioteca en C++ que debe compilarse con el soporte para el backend integrado en tiempo de compilación. No existe ninguna bandera en tiempo de ejecución que active CUDA después de la compilación. Cuando pip compila el paquete fuente (sdist) sin CMAKE_ARGS establecer ninguna variable, CMake configura automáticamente el backend genérico para CPU, y eso es exactamente lo que obtienes, de forma permanente, hasta que vuelvas a compilarlo. En macOS arm64 este problema es menos acusado porque las versiones recientes activan el backend Metal de forma predeterminada, pero en Linux y Windows una instalación básica se ejecutará íntegramente en la CPU.

Dos consecuencias dignas de considerar: primero, n_gpu_layers=-1 en una compilación exclusiva para CPU no hace nada útil de forma silenciosa, por lo que muchas personas concluyen erróneamente que su GPU es «demasiado lenta», cuando en realidad nunca fue utilizada. Segundo, pip almacena en caché las ruedas (wheels) ya compiladas. Volver a ejecutar la instalación con distintos CMAKE_ARGS parámetros puede devolverte nuevamente la rueda previamente almacenada en caché para CPU, razón por la cual cada comando de reconstrucción que aparece a continuación incluye --no-cache-dir --force-reinstall.

Instalación de llama-cpp-python con soporte para GPU

Opción 1: ruedas precompiladas (no se requiere compilador)

El proyecto publica índices de ruedas (wheel indexes), incluido un índice para CPU en https://abetlen.github.io/llama-cpp-python/whl/cpu y variantes CUDA cuyo segmento de ruta codifica la versión de CUDA; por ejemplo, .../whl/cu124. Instálalo mediante:

pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

Qué etiquetas CUDA y qué versiones de Python están disponibles varía según la versión publicada, y los índices a veces se retrasan respecto a la versión más reciente en PyPI. Consulta el archivo README del proyecto para conocer las etiquetas actualmente disponibles, en lugar de asumir una arbitrariamente: una etiqueta incorrecta devuelve un error 404 y pip pasa silenciosamente a compilar desde el código fuente.

Opción 2: compilar desde el código fuente (Linux, CUDA)

Necesitas una cadena de herramientas C++, CMake y el kit de herramientas CUDA con nvcc en tu variable PATH.

nvcc --version   # debe mostrar una versión, no el mensaje «command not found»

CMAKE_ARGS="-DGGML_CUDA=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

El nombre de la bandera ha cambiado a lo largo de la historia del proyecto: las guías muy antiguas usan -DLLAMA_CUBLAS=on, las guías de mediados de 2024 usan -DLLAMA_CUDA=on, y la versión actual oficial emplea el prefijo GGML_ . Si una compilación falla debido a una opción desconocida de CMake, normalmente esa incoherencia es la causa. Otros backends siguen el mismo patrón: Vulkan usa -DGGML_VULKAN=on, SYCL usa -DGGML_SYCL=on, y la opción para AMD/ROCm ha sido renombrada varias veces; por tanto, consulta el README de tu versión instalada en lugar de copiar una bandera de un foro.

Puedes reducir sustancialmente el tiempo de compilación limitando la construcción únicamente a la capacidad de cómputo (compute capability) de tu GPU; por ejemplo, -DCMAKE_CUDA_ARCHITECTURES=89 para una tarjeta Ada como la RTX 4090, o 86 para una RTX 3090. Busca la capacidad de cómputo de tu tarjeta en la lista oficial de NVIDIA; si aún estás eligiendo hardware, nuestra guía sobre las mejores GPUs para ejecutar LLMs localmente analiza los compromisos entre VRAM y precio.

Opción 3: macOS con Metal

xcode-select --install

CMAKE_ARGS="-DGGML_METAL=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall

En Apple Silicon, verifica que no estés ejecutando una versión de Python para x86 bajo Rosetta: python -c "import platform; print(platform.machine())" debe mostrar arm64. Un intérprete x86_64 generará una compilación sin soporte para Metal, independientemente de los valores que pases en CMAKE_ARGS. Dado que la GPU y la CPU comparten memoria en Apple Silicon, n_gpu_layers=-1 n_gpu_layers=-1

Opción 4: Windows con CUDA

Instala las «Herramientas de compilación de Visual Studio 2022» con la carga de trabajo «Desarrollo de escritorio con C++» primero, seguida del kit de herramientas CUDA, para que CUDA instale su integración con MSBuild dentro de una instalación existente de Visual Studio. Luego, en PowerShell:

$env:CMAKE_ARGS = "-DGGML_CUDA=on"
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

En cmd.exe la equivalencia es set CMAKE_ARGS=-DGGML_CUDA=on en una línea independiente. Las compilaciones desde el código fuente en Windows son la vía más propensa a errores de las tres plataformas; si solo necesitas inferencia y no una compilación personalizada, las ruedas precompiladas para CUDA o WSL2 son opciones menos problemáticas.

Cómo identificar qué versión tiene

La verificación más fiable es la salida detallada del cargador, que es independiente de la versión:

from llama_cpp import Llama
llm = Llama(model_path="./models/model.gguf", n_gpu_layers=-1, verbose=True)

En una compilación con CUDA verás líneas de inicialización del backend que mencionan CUDA y un nombre de dispositivo, además de una línea de carga de tensores que indica cuántas capas del modelo se han descargado (offloaded) a la GPU. En Metal verás líneas relacionadas con el dispositivo Metal. Una compilación exclusiva para CPU no muestra ninguno de estos mensajes y reporta cero capas descargadas. Contrasta esto con nvidia-smi durante la generación: si su proceso de Python no está ocupando la VRAM, nada se está ejecutando en la GPU.

Las versiones recientes también exponen una comprobación directa de capacidades:

from llama_cpp import llama_cpp, __version__
print(__version__)
print(llama_cpp.llama_supports_gpu_offload())

Si ese atributo lanza AttributeError, su compilación es anterior a su inclusión; vuelva al método de registro detallado.

Cargar un archivo GGUF y ejecutar una primera finalización

Punto model_path cualquier archivo GGUF. Si prefiere descargarlo desde Hugging Face, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) realiza la descarga automáticamente cuando huggingface-hub está instalado.

from llama_cpp import Llama

llm = Llama(
    model_path="./models/qwen2.5-7b-instruct-q4_k_m.gguf",
    n_gpu_layers=-1,
    n_ctx=4096,
    n_batch=512,
    verbose=False,
)

out = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Explica una caché KV en dos frases."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Para la continuación directa de texto sin formato, invoque el objeto directamente: llm("P: ¿Qué es un archivo GGUF? R:", max_tokens=128, stop=["P:"]) y leer out["choices"][0]["text"].

Transmisión de tokens

Pase stream=True e itere. La estructura de la respuesta sigue el formato de transmisión de OpenAI, por lo que el primer fragmento normalmente contiene únicamente el rol y los fragmentos posteriores contienen deltas de content (contenido):

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Escribe un haiku sobre los archivos GGUF."}],
    stream=True,
)
for chunk in stream:
    delta = chunk["choices"][0]["delta"]
    if "content" in delta:
        print(delta["content"], end="", flush=True)

La mayoría de los archivos GGUF incluyen incrustada una plantilla de chat que llama-cpp-python aplica automáticamente. Cuando la salida parece distorsionada o el modelo nunca finaliza, la plantilla es el primer sospechoso; sobrescríbala con el argumento chat_format Explore las opciones cuantizadas y sus tamaños en nuestra Base de datos de modelos de IA.

Los parámetros que importan

Tenga en cuenta que la atención flash y la cuantización de la caché KV (type_k / type_v) han cambiado entre versiones: el interruptor de flash-attention ha sido un valor booleano en algunas versiones y una opción de tres valores (auto/on/off) en otras. Ejecuta help(Llama) con tu versión instalada, en lugar de confiar en un nombre de bandera tomado de una entrada de blog.

Ajuste práctico

Las dos opciones que interactúan son n_gpu_layers y n_ctx. Los pesos y la caché KV compiten por la misma VRAM, y la caché KV escala aproximadamente de forma lineal con la longitud del contexto. Reducir a la mitad n_ctx de 8192 a 4096 suele liberar suficiente memoria para descargar varias capas adicionales a la GPU, lo cual normalmente constituye una mejor compensación. Calcula previamente tu presupuesto de memoria antes de comenzar a probar valores al azar con nuestra Calculadora de VRAM, o consulta las cifras específicas por modelo en la referencia de requisitos de VRAM.

La descarga parcial funciona —es la característica distintiva de llama.cpp—, pero espera una caída brusca del rendimiento tan pronto como alguna capa permanezca en la CPU, ya que cada token debe atravesar el bus PCIe. Si puedes cargar todas las capas en la GPU, hazlo.

Modo servidor compatible con OpenAI

pip install "llama-cpp-python[server]"

python -m llama_cpp.server 
  --model ./models/qwen2.5-7b-instruct-q4_k_m.gguf 
  --n_gpu_layers -1 
  --n_ctx 4096 
  --host 0.0.0.0 --port 8000

Las banderas del servidor reflejan los argumentos del constructor, incluidos los guiones bajos. Obtendrás /v1/chat/completions, /v1/completions, /v1/models, y documentación interactiva en /docs. Cualquier cliente OpenAI es compatible, y se admite transmisión mediante SSE (Server-Sent Events):

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="no-es-necesario")
for event in client.chat.completions.create(
    model="gpt-3.5-turbo",  # se ignora a menos que definas alias de modelos
    messages=[{"role": "user", "content": "Hola"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

Para más de un modelo, pasa --config_file config.json con un modelos array, asignando a cada entrada una modelo ruta model_alias que los clientes podrán usar para solicitar el modelo por nombre, así como su propia configuración n_gpu_layers / n_ctx. Añade --api_key si el puerto es accesible desde fuera de localhost. ¿Estás comparando esto con un punto final alojado? El calculadora de punto de equilibrio entre autohospedaje y API proporciona cifras concretas.

Errores comunes durante la compilación y sus soluciones

Preguntas frecuentes

¿Es llama-cpp-python lo mismo que llama.cpp?

No. llama.cpp es el motor de inferencia en C/C++; llama-cpp-python incluye una versión específica (commit) de dicho motor y lo encapsula para su uso en Python. Dado que la versión integrada está fijada por cada lanzamiento, los bindings pueden retrasarse varios días o semanas respecto al desarrollo principal —lo cual resulta relevante cuando una nueva arquitectura de modelo acaba de incorporarse a llama.cpp, pero aún no se ha publicado en una versión de los bindings.

¿Cómo puedo confirmar que realmente se está utilizando la GPU?

Cargue con verbose=True y busque las líneas de inicialización del backend y un informe sobre las capas descargadas a la GPU. A continuación, observe nvidia-smi (o el historial de uso de GPU en el Monitor de Actividad en macOS) durante la generación. Si el uso de VRAM no aumenta y la velocidad de generación (tokens por segundo) se parece a la obtenida en CPU, entonces está utilizando una compilación exclusiva para CPU.

¿Puedo evitar completamente la compilación?

A menudo, sí: utilice los índices de paquetes precompilados (wheels) del proyecto con la opción --extra-index-url, asegurándose de que la etiqueta CUDA coincida con su kit de herramientas. Cuando no exista un wheel compatible con su versión de Python y plataforma, pip recurrirá automáticamente a una compilación desde el código fuente, lo que normalmente tarda varios minutos si CUDA está habilitado.

¿Debería usar llama-cpp-python, Ollama o LM Studio?

Use llama-cpp-python cuando desee ejecutar el modelo dentro de su propio proceso Python, con control directo sobre el muestreo, los logits y las gramáticas. Prefiera Ollama para un daemon gestionado con descarga automática de modelos y manejo automático de memoria, o LM Studio para una interfaz gráfica (GUI). Los tres se basan en llama.cpp, por lo que la calidad es comparable; la diferencia radica en la facilidad de uso.

¿Puedo ejecutar un modelo más grande que mi VRAM?

Sí. Establezca n_gpu_layers en un valor inferior al número total de capas del modelo, y el resto se ejecutará en la CPU utilizando la memoria RAM del sistema. Esta técnica funciona de forma fiable, pero la penalización de rendimiento es severa una vez que una proporción significativa de capas permanece en la CPU; por tanto, normalmente es preferible usar un modelo más pequeño con una cuantización más alta, en lugar de uno grande parcialmente descargado a la CPU.

¿Funciona el soporte para GPU en Windows sin WSL?

Sí. Puede instalar un wheel precompilado de CUDA o compilar desde el código fuente tras haber instalado previamente las «Herramientas de compilación para Visual Studio 2022» (con la carga de trabajo «Desarrollo de escritorio con C++») antes de instalar el Kit de herramientas CUDA, y configurando $env:CMAKE_ARGS en PowerShell. No obstante, WSL2 sigue siendo la opción más fluida si se siente cómodo con ella, ya que las instrucciones de compilación para Linux están mejor documentadas y probadas.