Llama Cpp Python: instalação, compilação com suporte a GPU e parâmetros

llama-cpp-python é a ligação em Python para o llama.cpp. Ele carrega modelos no formato GGUF diretamente na memória, expõe um wrapper de baixo nível baseado em ctypes, além de uma interface de alto nível com a classe Llama e inclui um servidor HTTP compatível com OpenAI. A instalação padrão via pip compila uma versão exclusiva para CPU. Para usar a GPU, você deve instalar uma versão pré-compilada com suporte a GPU ou reconstruir a partir do código-fonte com CMAKE_ARGS, e então passar n_gpu_layers.

Por que a instalação padrão é exclusiva para CPU

O pacote é uma interface leve em torno de uma biblioteca em C++ que precisa ser compilada com o suporte ao backend embutido no momento da compilação. Não há nenhuma flag de tempo de execução que ative a CUDA após a compilação. Quando o pip compila o sdist sem CMAKE_ARGS definir essa variável, o CMake configura o backend genérico para CPU, e é isso que você obtém, permanentemente, até que você recompile. No macOS arm64, esse problema é menos frequente porque versões recentes ativam o backend Metal por padrão, mas no Linux e no Windows uma instalação básica será executada inteiramente na sua CPU.

Duas consequências dignas de atenção: primeiro, n_gpu_layers=-1 em uma compilação exclusiva para CPU não faz nada útil de forma silenciosa, levando muitos usuários a concluir erroneamente que sua GPU é "muito lenta", quando ela sequer foi utilizada. Segundo, o pip armazena em cache as wheels compiladas. Executar novamente a instalação com diferentes CMAKE_ARGS configurações pode entregar-lhe novamente a wheel em cache para CPU, razão pela qual todos os comandos de reconstrução abaixo incluem --no-cache-dir --force-reinstall.

Instalando o llama-cpp-python com suporte a GPU

Opção 1: wheels pré-compiladas (sem necessidade de compilador)

O projeto publica índices de wheels, incluindo um índice para CPU em https://abetlen.github.io/llama-cpp-python/whl/cpu e variantes CUDA cujo segmento de caminho codifica a versão da CUDA, por exemplo .../whl/cu124. Instale com:

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

Quais tags CUDA e versões do Python são publicadas varia conforme a versão lançada, e os índices às vezes ficam defasados em relação à versão mais recente no PyPI. Verifique o README do projeto para identificar quais tags estão disponíveis atualmente — assumir uma tag incorreta resultará em um erro 404 e o pip recorrerá silenciosamente à compilação a partir do código-fonte.

Opção 2: compilação a partir do código-fonte (Linux, CUDA)

Você precisa de uma cadeia de ferramentas C++, do CMake e do toolkit CUDA com nvcc disponível no seu PATH.

nvcc --version   # deve exibir uma versão, não "comando não encontrado"

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

O nome dessa flag mudou ao longo da vida do projeto: guias muito antigos usam -DLLAMA_CUBLAS=on, guias de meados de 2024 usam -DLLAMA_CUDA=on, e a versão atual upstream usa o prefixo GGML_ . Se uma compilação falhar devido a uma opção desconhecida do CMake, esse descompasso geralmente é a causa. Outros backends seguem o mesmo padrão — Vulkan usa -DGGML_VULKAN=on, SYCL usa -DGGML_SYCL=on, e a opção AMD/ROCm foi renomeada mais de uma vez; portanto, consulte o README da versão instalada em vez de copiar uma flag de um post em fórum.

Você pode reduzir substancialmente o tempo de compilação ao direcioná-la apenas para a capacidade de computação da sua GPU, por exemplo -DCMAKE_CUDA_ARCHITECTURES=89 para uma placa Ada, como a RTX 4090, ou 86 para uma RTX 3090. Consulte a lista oficial da NVIDIA para identificar a capacidade de computação da sua placa; se ainda estiver escolhendo hardware, nosso guia sobre as melhores GPUs para executar LLMs localmente aborda as compensações entre VRAM e custo.

Opção 3: macOS com Metal

xcode-select --install

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

No Apple Silicon, verifique se você não está executando um interpretador Python x86 via Rosetta: python -c "import platform; print(platform.machine())" deve exibir arm64. Um interpretador x86_64 produzirá uma compilação sem suporte ao backend Metal, independentemente dos valores passados em CMAKE_ARGS. Como GPU e CPU compartilham memória no Apple Silicon, n_gpu_layers=-1 é quase sempre a configuração correta nesse caso.

Opção 4: Windows com CUDA

Instale as Ferramentas de Build do Visual Studio 2022 com a carga de trabalho "Desenvolvimento para desktop com C++" primeiro, seguida pelo toolkit CUDA, para que a instalação do CUDA integre-se ao MSBuild do Visual Studio já instalado. Em seguida, no PowerShell:

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

Em cmd.exe a equivalência é set CMAKE_ARGS=-DGGML_CUDA=on em uma linha separada. As compilações a partir do código-fonte no Windows são o caminho com maior probabilidade de falha entre as três plataformas; se você deseja apenas inferência e não uma compilação personalizada, as wheels CUDA pré-compiladas ou o WSL2 são alternativas menos problemáticas.

Como identificar qual versão você possui

A verificação mais confiável é a saída detalhada do carregador, que é independente da versão:

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

Em uma compilação CUDA, você verá linhas de inicialização do backend mencionando CUDA e um nome de dispositivo, além de uma linha de carregamento de tensores indicando quantas camadas do modelo foram descarregadas para a GPU. No Metal, você verá linhas relacionadas ao dispositivo Metal. Uma compilação exclusiva para CPU não exibe nenhuma dessas mensagens e relata zero camadas descarregadas. Confirme cruzadamente com nvidia-smi durante a geração: se seu processo Python não estiver ocupando VRAM, nada está sendo executado na GPU.

Versões recentes também expõem uma verificação direta de capacidade:

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

Se esse atributo gerar uma exceção AttributeError, sua compilação é anterior a essa funcionalidade — recorra ao método de verificação por meio dos logs detalhados.

Carregando um GGUF e executando uma primeira conclusão

Ponto model_path para qualquer arquivo GGUF. Se preferir baixar diretamente do Hugging Face, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) realiza o download automaticamente quando 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": "Explique o que é um cache KV em duas frases."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Para continuação direta de texto sem formatação, chame o objeto diretamente: llm("Q: O que é um arquivo GGUF? A:", max_tokens=128, stop=["Q:"]) e leia out["choices"][0]["text"].

Transmissão contínua de tokens (streaming)

Passe stream=True e itere sobre os resultados. A estrutura da resposta segue o formato de streaming da OpenAI, portanto o primeiro fragmento normalmente contém apenas a função (role) e os fragmentos subsequentes trazem as diferenças incrementais (deltas) no campo content (conteúdo):

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Escreva um haicai sobre arquivos GGUF."}],
    stream=True,
)
for chunk in stream:
    delta = chunk["choices"][0]["delta"]
    if "content" in delta:
        print(delta["content"], end="", flush=True)

A maioria dos arquivos GGUF incorpora um modelo de conversação (chat template) que o llama-cpp-python aplica automaticamente. Quando a saída parece corrompida ou o modelo nunca para de gerar, o modelo de conversação é o primeiro suspeito — substitua-o usando o argumento chat_format . Explore opções quantizadas e seus respectivos tamanhos em nosso Banco de dados de modelos de IA.

Os parâmetros que importam

Observe que a atenção flash e a quantização do cache KV (type_k / type_vmudaram entre versões — o parâmetro flash-attention já foi um booleano em algumas versões e uma configuração de três opções (auto/on/off) em outras. Execute help(Llama) com a versão instalada em vez de confiar em um nome de parâmetro obtido de um post de blog.

Ajuste na prática

As duas configurações que interagem são n_gpu_layers e n_ctx. Os pesos e o cache KV competem pelo mesmo VRAM, e o cache KV escala aproximadamente de forma linear com o comprimento do contexto. Reduzir pela metade o valor de n_ctx de 8192 para 4096 frequentemente libera memória suficiente para descarregar mais algumas camadas, o que normalmente representa uma melhor compensação. Calcule seu orçamento de memória antes de começar a fazer tentativas aleatórias com nossa Calculadora de VRAM, ou consulte os valores específicos por modelo na referência de requisitos de VRAM.

O descarregamento parcial funciona — é a principal característica do llama.cpp —, mas espere uma queda acentuada de desempenho assim que qualquer camada permanecer na CPU, pois cada token precisa atravessar o barramento PCIe. Se for possível carregar todas as camadas na GPU, faça-o.

Modo de servidor compatível com 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

Os parâmetros do servidor espelham os argumentos do construtor, incluindo os sublinhados. Você obtém /v1/chat/completions, /v1/completions, /v1/models, além de documentação interativa em /docs. Qualquer cliente OpenAI funciona, e o streaming é suportado via SSE:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
for event in client.chat.completions.create(
    model="gpt-3.5-turbo",  # ignorado, a menos que você defina apelidos de modelo
    messages=[{"role": "user", "content": "Olá"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

Para mais de um modelo, passe --config_file config.json com um modelos array, atribuindo a cada entrada um modelo path, um model_alias que os clientes podem solicitar pelo nome, e seus próprios n_gpu_layers / n_ctx. Adicione --api_key se a porta for acessível além do localhost. Quer comparar isso com um endpoint hospedado? O calculadora de ponto de equilíbrio entre hospedagem local e uso de API apresenta dados quantitativos sobre o assunto.

Falhas comuns de compilação e soluções

Perguntas frequentes

O llama-cpp-python é o mesmo que o llama.cpp?

Não. O llama.cpp é o mecanismo de inferência em C/C++; o llama-cpp-python incorpora (venda) um commit específico desse projeto e o envolve para uso em Python. Como a versão incorporada é fixada por lançamento, as interfaces de ligação podem ficar atrás da versão principal por dias ou semanas — o que é relevante quando uma nova arquitetura de modelo acaba de ser adicionada ao llama.cpp, mas ainda não foi incluída em uma versão publicada das interfaces.

Como confirmo se a GPU está realmente sendo utilizada?

Carregue com verbose=True e procure linhas de inicialização do backend e um relatório indicando quais camadas foram descarregadas para a GPU. Em seguida, observe o uso da GPU com nvidia-smi (ou com o Monitor de Atividade — e seu histórico de uso da GPU no macOS) durante uma geração. Se o uso de VRAM não aumentar e a taxa de tokens por segundo for semelhante à obtida em CPU, você está usando uma compilação exclusiva para CPU.

Posso evitar totalmente a compilação?

Frequentemente, sim — use os índices pré-construídos de pacotes wheel do projeto com --extra-index-url, correspondendo à tag CUDA à sua ferramenta de desenvolvimento. Quando nenhum wheel compatível estiver disponível para sua versão do Python e plataforma, o pip reverterá para uma compilação a partir do código-fonte, processo que normalmente leva vários minutos com suporte CUDA ativado.

Devo usar o llama-cpp-python, o Ollama ou o LM Studio?

Use o llama-cpp-python quando desejar executar o modelo diretamente dentro do seu próprio processo Python, com controle direto sobre amostragem, logits e gramáticas. Prefira o Ollama para um daemon gerenciado com suporte nativo a downloads de modelos e gerenciamento automático de memória, ou o LM Studio para uma interface gráfica (GUI). Os três projetos são baseados no llama.cpp, portanto a qualidade dos resultados é comparável; a diferença reside na facilidade de uso e na experiência de desenvolvimento.

Posso executar um modelo maior do que minha VRAM?

Sim. Defina n_gpu_layers para um valor inferior ao número total de camadas do modelo, e as camadas restantes serão executadas na CPU, utilizando a memória RAM do sistema. Esse recurso funciona de forma confiável, mas a penalidade de desempenho é severa assim que uma parcela significativa das camadas permanecer na CPU; portanto, geralmente é melhor usar um modelo menor com uma quantização mais alta do que um modelo grande parcialmente descarregado para a CPU.

O suporte à GPU funciona no Windows sem WSL?

Funciona. Você pode instalar um wheel pré-construído com suporte CUDA ou compilar a partir do código-fonte usando as Ferramentas de Build do Visual Studio 2022 (desenvolvimento para desktop com C++), instaladas antes do CUDA Toolkit, e definindo $env:CMAKE_ARGS no PowerShell. O WSL2 continua sendo o caminho mais fluido, caso você esteja confortável com ele, já que as instruções de compilação para Linux são mais consolidadas.