SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como executar o llama.cpp numa VPS com systemd

Compile o llama.cpp a partir da tag b10488, sirva modelos GGUF em /v1, limite o acesso a 127.0.0.1 e controle a memória com systemd.

O que está a construir

Executar o servidor llama.cpp numa VPS significa usar um único binário, llama-server, que carrega um único ficheiro de modelo GGUF e responde a pedidos HTTP através de uma API compatível com OpenAI. Aponte um cliente compatível para http://127.0.0.1:8080/v1 e teste as funcionalidades utilizadas pela sua aplicação: a compatibilidade é parcial. A instalação é a parte simples.

O restante trabalho é operacional: fixar uma versão, manter a porta em localhost, criar uma unidade systemd e decidir o que acontece quando o servidor fica sem memória. É disso que este guia trata. Se ainda não decidiu entre as duas opções óbvias, leia primeiro as diferenças entre Ollama e llama.cpp, porque este é o guia prático que essa comparação omite deliberadamente.

Escolha uma tag de release e registe-a

O llama.cpp usa tags com números de build, como b10488, para builds de desenvolvimento nightly e tags de versão semântica, vX.Y.Z, para releases oficiais. b10488 é a build fixada usada aqui, lançada em 18 August 2026. "Latest" muda ao longo do tempo, e a versão testada é a única que pode suportar. Escolha uma tag, registe-a e use a mesma string no clone, no nome do binário e nas suas notas.

A tag b10488 também disponibiliza arquivos pré-compilados. Para uma VPS x86 apenas com CPU, essa tag é llama-b10488-bin-ubuntu-x64.tar.gz. Existe um arquivo arm64 ao lado desse se estiver a usar uma VPS ARM em vez de x86.

curl -LO https://github.com/ggml-org/llama.cpp/releases/download/b10488/llama-b10488-bin-ubuntu-x64.tar.gz
tar tf llama-b10488-bin-ubuntu-x64.tar.gz | head

Liste o arquivo antes de o extrair, para saber onde os ficheiros serão colocados. Esses binários estão ligados à biblioteca C da imagem que os compilou. Por isso, numa distribuição mais antiga, falham no arranque com um erro que indica uma versão GLIBC_ não instalada. Compilar a partir do código-fonte demora alguns minutos numa VPS pequena e elimina toda essa classe de problemas. É esse o caminho apresentado abaixo.

Compilar llama-server a partir de uma tag fixada

sudo apt update
sudo apt install -y build-essential cmake git libssl-dev
git clone --depth 1 --branch b10488 https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release -t llama-server -j 2

--branch b10488 num --depth 1 faz checkout dessa tag e de mais nada. Assim, a compilação não muda enquanto trabalha.

libssl-dev é importante porque a opção LLAMA_OPENSSL fica ativada por predefinição. É ela que permite ao binário descarregar modelos por HTTPS mais tarde. Sem os ficheiros de desenvolvimento do OpenSSL, esta compilação fixada avisa que o suporte a HTTPS está desativado, em vez de falhar durante a configuração.

-DBUILD_SHARED_LIBS=OFF liga llama.cpp e GGML ao executável. As dependências de bibliotecas do sistema continuam a existir. A compilação predefinida coloca as bibliotecas partilhadas junto do executável. Por isso, copiar apenas o executável para /usr/local/bin falha depois com error while loading shared libraries: libllama.so.

-t llama-server compila apenas o destino do servidor. A compilação predefinida também compila as restantes ferramentas e os testes. Num VPS com dois cores, isso acrescenta vários minutos a compilar ficheiros que nunca vai executar.

-j 2 é intencional. Cada tarefa de compilação paralela mantém o seu próprio conjunto de trabalho. Por isso, -j $(nproc) num plano pequeno termina com c++: fatal error: Killed signal terminated program cc1plus, quando o kernel termina o compilador por falta de memória. Reduza o número de tarefas ou adicione swap para a compilação.

Pode querer alterar uma opção: GGML_NATIVE fica ativada por predefinição, por isso o compilador cria um binário para a CPU exata onde a compilação é feita. É isso que pretende quando compila na máquina que vai executar o binário. Se compilar uma vez e copiar o binário para outro host, adicione -DGGML_NATIVE=OFF. Caso contrário, um binário que use instruções inexistentes na outra CPU termina com Illegal instruction (core dumped) na primeira inferência.

Instale-o com um nome que inclua a tag.

./build/bin/llama-server --version
sudo install -m 755 build/bin/llama-server /usr/local/bin/llama-server-b10488
sudo ln -sfn /usr/local/bin/llama-server-b10488 /usr/local/bin/llama-server

--version mostra o número da compilação e o commit. Estes valores têm de corresponder à tag que foi selecionada. Se não corresponderem, compilou outra coisa. Manter o número no nome do ficheiro e apontar um symlink para esse ficheiro faz com que uma atualização consista num ln -sfn e num reinício. Para reverter, use o mesmo comando com o número antigo.

Obtenha um modelo GGUF e verifique o disco primeiro

GGUF é o formato de ficheiro único carregado pelo llama.cpp. Um ficheiro contém os pesos, o tokenizador e os metadados, por isso não há mais nada para instalar. O sufixo do nome do ficheiro indica a quantização, ou seja, a precisão usada para armazenar os pesos: Q4_K_M é uma mistura de 4 bits, Q8_0 usa 8 bits e f16 é o ficheiro de meia precisão sem quantização.

Crie uma conta de serviço e um diretório para o modelo antes de iniciar qualquer transferência.

sudo useradd --system --home /srv/llama --create-home --shell /usr/sbin/nologin llama
sudo install -d -o llama -g llama /srv/models
df -h /srv

O servidor pode obter o modelo diretamente com -hf. Esta é a forma mais rápida de confirmar que a compilação funciona.

sudo -u llama env LLAMA_CACHE=/srv/models /usr/local/bin/llama-server \
  -hf ggml-org/gemma-3-1b-it-GGUF:Q4_K_M --host 127.0.0.1 --port 8080

LLAMA_CACHE define o diretório de transferência. Sem LLAMA_CACHE ou XDG_CACHE_HOME, o ficheiro é guardado em ~/.cache/llama.cpp, na conta que executou o comando; a unidade abaixo torna /srv/llama somente de leitura. Execute ls -lh /srv/models depois, porque o nome do ficheiro em cache é derivado do nome do repositório, e não do nome simples do ficheiro.

Para um serviço, transfira o modelo para um caminho escolhido por si, para que o ficheiro da unidade tenha um destino estável.

sudo -u llama curl -L --output-dir /srv/models -O \
  https://huggingface.co/ggml-org/gemma-3-1b-it-GGUF/resolve/main/gemma-3-1b-it-Q4_K_M.gguf

O espaço em disco é a primeira limitação encontrada pela maioria das pessoas. Estes são os tamanhos publicados dos ficheiros de dois modelos, verificados em 18 August 2026.

GráficoGGUF file size on disk, published figures, 18 August 2026
Os dados por trás deste gráfico
[
  {
    "label": "gemma-3-1b-it Q4_K_M",
    "size_gb": 0.81
  },
  {
    "label": "gemma-3-1b-it Q8_0",
    "size_gb": 1.07
  },
  {
    "label": "gemma-3-1b-it f16",
    "size_gb": 2.01
  },
  {
    "label": "gpt-oss-20b MXFP4",
    "size_gb": 12.11
  }
]

O ficheiro de 4 bits do modelo 1B tem 0.81 GB. O mesmo modelo sem quantização tem 2.01 GB, por isso a escolha do formato altera o valor por um fator superior a dois. Um modelo 20B em MXFP4 tem 12.11 GB e, depois disso, ainda tem de ser carregado para a memória. Se estiver a considerar uma família específica, o mesmo cálculo de dimensionamento para GLM mostra a rapidez com que o tamanho do modelo deixa de ser viável num VPS, enquanto um modelo mais pequeno da mesma família cabe.

Verifique df -h antes de cada transferência. Um sistema de ficheiros raiz que fique cheio durante uma transferência de 12 GB impede tudo o que precise de escrever, incluindo o journal.

Execute-o uma vez manualmente e verifique o resultado

sudo -u llama /usr/local/bin/llama-server \
  --model /srv/models/gemma-3-1b-it-Q4_K_M.gguf \
  --host 127.0.0.1 --port 8080 \
  --ctx-size 4096 --parallel 1 --threads 2 --no-webui

Numa segunda sessão, pergunte ao servidor se está pronto.

curl -s http://127.0.0.1:8080/health

Enquanto o ficheiro é carregado, recebe HTTP 503 e este corpo:

{"error":{"code":503,"message":"Loading model","type":"unavailable_error"}}

Quando estiver pronto, o corpo será {"status": "ok" }. Em seguida, envie um pedido real.

curl -s http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"local","messages":[{"role":"user","content":"Say hello in five words."}]}'

Um objeto JSON com um array choices indica que o servidor está a funcionar. O campo model existe porque os clientes OpenAI o enviam sempre. Este servidor tem um único modelo carregado, pelo que o valor não é usado para selecionar nada.

A API compatível com OpenAI e os restantes recursos disponíveis na porta

POST /v1/chat/completions, POST /v1/completions, POST /v1/responses e POST /v1/embeddings são rotas compatíveis com OpenAI, e GET /v1/models devolve o modelo carregado. Para gerar embeddings, é necessário um modelo com pooling diferente de none. GET /health é a verificação de prontidão apresentada acima, GET /props devolve as definições atuais do servidor e GET /metrics disponibiliza contadores Prometheus quando o servidor é iniciado com --metrics.

Para chamadas compatíveis com os SDKs da OpenAI, defina a URL base como http://127.0.0.1:8080/v1 e forneça uma string de chave API não vazia se o SDK exigir uma. Isto não garante compatibilidade com todas as funcionalidades do SDK. A chave não é validada até definir --api-key ou --api-key-file manualmente.

Não use a estimativa de throughput de outra pessoa como valor para o seu próprio planeamento. A velocidade de inferência no CPU depende do número de cores, da largura de banda da memória e dos vizinhos com quem partilha o host. Por isso, meça os tokens por segundo na sua própria máquina e trate esse resultado como referência. O steal time causado por um vizinho ruidoso aparece aqui como uma velocidade de geração que varia de hora para hora.

Mantenha-o em 127.0.0.1 e coloque um proxy à frente

--host já usa 127.0.0.1 por predefinição. Por isso, o servidor fica inacessível a partir do exterior até alterar essa configuração. Não a altere. Use o proxy para gerir contas de utilizador, limites de taxa dos pedidos e registos de auditoria. A autenticação integrada da API usa chaves estáticas: --api-key aceita uma chave ou uma lista separada por vírgulas, e --api-key-file lê uma chave por linha. Uma porta de inferência exposta fornece capacidade de computação gratuita a qualquer pessoa que a encontre. O mesmo erro no Ollama tem a mesma configuração: proteger uma API de modelos alojada localmente aplica-se aqui sem alterações.

Termine o TLS (transport layer security) no nginx e encaminhe os pedidos para a porta de loopback.

server {
    listen 443 ssl;
    server_name llm.example.com;

    location /v1/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 600s;
    }
}

proxy_buffering off transmite as respostas em fluxo para o cliente à medida que o nginx as recebe. Com o buffering ativo, o nginx armazena os dados do upstream em vez de encaminhar cada evento imediatamente. proxy_read_timeout 600s dá margem para respostas lentas. Este é o tempo máximo que o nginx espera entre duas leituras do servidor, não um limite para a resposta completa. Assim, com o valor predefinido de 60 segundos, um pedido sem streaming que não envie dados durante esse intervalo excede o tempo limite. Em b10488, as respostas em fluxo enviam pings de keepalive SSE a cada 30 segundos por predefinição, inclusive durante o processamento prolongado do prompt. Obtenha o certificado com Certbot e Let's Encrypt no nginx.

A unidade systemd

Escreva /etc/systemd/system/llama-server.service.

[Unit]
Description=llama.cpp server
After=network-online.target
Wants=network-online.target

[Service]
User=llama
Group=llama
Environment=LLAMA_ARG_MODEL=/srv/models/gemma-3-1b-it-Q4_K_M.gguf
Environment=LLAMA_ARG_HOST=127.0.0.1
Environment=LLAMA_ARG_PORT=8080
Environment=LLAMA_ARG_CTX_SIZE=4096
Environment=LLAMA_ARG_N_PARALLEL=1
Environment=LLAMA_ARG_THREADS=2
ExecStart=/usr/local/bin/llama-server --no-webui
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
MemoryHigh=3G
MemoryMax=3500M
OOMPolicy=stop
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes

[Install]
WantedBy=multi-user.target

As definições estão em linhas Environment= porque llama-server lê variáveis LLAMA_ARG_* para a maioria dos flags, e um argumento da linha de comandos substitui a variável correspondente. Assim, existe um único local para alterar o tamanho do contexto, e ExecStart mantém-se suficientemente curto para ser lido rapidamente.

ProtectSystem=strict torna o sistema de ficheiros apenas de leitura para esta unidade, com exceções que incluem os diretórios temporários privados. Isto é adequado porque o servidor apenas lê o modelo. Adicione ReadWritePaths=/srv/models e Environment=LLAMA_CACHE=/srv/models se quiser que o próprio serviço descarregue modelos com -hf. ProtectHome=yes oculta /home, /root e /run/user. Não oculta o diretório pessoal desta conta de serviço em /srv/llama, mas ProtectSystem=strict torna esse diretório apenas de leitura.

sudo systemctl daemon-reload
sudo systemctl enable --now llama-server
systemctl status llama-server
curl -s http://127.0.0.1:8080/health
journalctl -u llama-server -n 50 --no-pager

enable --now é a metade que muitas pessoas ignoram. Sem enable, o servidor deixa de estar disponível depois do próximo reboot. Se quiser agendar tarefas relacionadas com o serviço, como verificar todas as noites se existe uma nova release, um serviço systemd com um temporizador é o mecanismo adequado.

Defina o comportamento em caso de OOM antes que aconteça

O uso de memória tem duas partes, e elas comportam-se de forma diferente sob um limite. Por predefinição, o ficheiro do modelo é mapeado em memória, por isso as respetivas páginas são suportadas por ficheiro: o kernel pode libertá-las e voltar a lê-las do disco. A cache KV, que é o estado por token mantido pelo servidor para cada conversa ativa, é memória anónima. Não pode ser libertada, por isso é ela que faz com que o processo seja terminado.

É por isso que os dois limites na unidade têm funções diferentes. MemoryHigh=3G é um limite flexível: acima dele, o kernel coloca o cgroup sob pressão de reclaim, por isso as páginas mapeadas do modelo são expulsas e lidas novamente do disco no token seguinte. O serviço continua a funcionar, mas fica mais lento. MemoryMax=3500M é o limite rígido: o kernel tenta primeiro recuperar o que conseguir e, se o uso continuar sem poder ser mantido abaixo do limite, o OOM killer é executado dentro da unidade, e o journal regista isso claramente.

llama-server.service: A process of this unit has been killed by the OOM killer.

Defina --ctx-size manualmente. O valor predefinido é 0, que corresponde ao contexto com que o modelo foi treinado e, num modelo moderno com contexto longo, aloca uma cache KV muito grande durante o arranque. O serviço morre antes de atender um único pedido. --parallel não multiplica esse custo por si só: --ctx-size define o tamanho total da cache KV, partilhada por todos os slots, por isso --ctx-size 4096 --parallel 4 dá a cada conversa cerca de 1,024 tokens, em vez de quadruplicar o uso de memória. Dar a cada slot o contexto completo significa multiplicar --ctx-size pelo número de slots, e a memória cresce com isso, por isso mantenha --parallel em 1 até saber que precisa de concorrência.

Com Restart=on-failure, um serviço terminado volta a arrancar. O Systemd só deixa de o reiniciar com start request repeated too quickly quando o número de arranques excede o limite de frequência configurado; o atraso de cinco segundos entre reinícios usado aqui não atinge o limite predefinido de cinco arranques em dez segundos. Interrompa um ciclo persistente de reinícios com sudo systemctl stop llama-server, corrija o limite ou o tamanho do contexto, depois limpe o estado de falha com sudo systemctl reset-failed llama-server e volte a iniciar o serviço.

Observe o valor real com systemctl show llama-server -p MemoryCurrent enquanto um pedido está a ser processado. Limitar a memória e a CPU dos processos com systemd explica estas diretivas com mais detalhe.

Evite usar swap para esta carga de trabalho. Um modelo colocado em swap transforma cada token em leituras do disco com deslocamentos aleatórios. O mapeamento do ficheiro do modelo em memória produz o mesmo efeito com menos impacto, porque o kernel lê diretamente do ficheiro as páginas de que precisa.

Onde o Ollama é a melhor opção

Este é um ponto de decisão. Escolha llama-server quando quiser um único processo com as opções que definiu, uma compilação fixada e um ficheiro escolhido por si. Nada muda por baixo porque não há outro componente em execução.

Escolha o Ollama quando quiser gestão de modelos: descarregar modelos pelo nome, manter vários modelos no disco, descarregar um modelo inativo e fazer atualizações com um único comando, sem uma nova compilação. Esse é trabalho real que, de outro modo, teria de automatizar com scripts. Executar o Ollama numa VPS é o mesmo trabalho com a decisão tomada no sentido oposto. Ambos disponibilizam uma API compatível com OpenAI, mas teste os endpoints e as funcionalidades usadas pelo seu cliente antes de mudar numa ou noutra direção.

Atualizar uma build fixada

Substitua bNNNNN pela tag da build nightly para a qual pretende atualizar; as tags de versões oficiais usam vX.Y.Z.

cd llama.cpp
git fetch --tags
git checkout bNNNNN
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release -t llama-server -j 2
sudo install -m 755 build/bin/llama-server /usr/local/bin/llama-server-bNNNNN
sudo ln -sfn /usr/local/bin/llama-server-bNNNNN /usr/local/bin/llama-server
sudo systemctl restart llama-server

O binário antigo permanece no disco. Para fazer rollback, basta executar um ln -sfn para llama-server-b10488 e reiniciar o serviço. Leia as notas da versão antes de atualizar. Os ficheiros GGUF têm versões, mas a compatibilidade retroativa não é universal: o loader atual rejeita GGUFv1. As flags também são renomeadas: em b10488, --mlock e --no-mmap já estavam obsoletas e foram substituídas por --load-mode. Desde 11 October 2026, a documentação atual do servidor já não as lista. Por isso, um unit file que passe uma flag removida falha no arranque com uma mensagem de argumento não reconhecido. Os valores predefinidos também mudam: as builds atuais escutam por predefinição na porta 9931, enquanto b10488 usava a porta 8080. Por esse motivo, todos os comandos e a unit apresentada definem explicitamente a porta.

Modos de falha e mensagens apresentadas

error while loading shared libraries: libllama.so depois de copiar o binário para outro local. A compilação predefinida produz bibliotecas partilhadas juntamente com o binário. Recompile com -DBUILD_SHARED_LIBS=OFF ou copie o diretório build/bin completo.

Illegal instruction (core dumped) no arranque ou no primeiro pedido. O binário foi compilado com GGML_NATIVE ativado, para uma CPU diferente da que o está a executar. Recompile nesta máquina ou configure com -DGGML_NATIVE=OFF.

c++: fatal error: Killed signal terminated program cc1plus durante a compilação. O compilador foi terminado por utilizar demasiada memória. Reduza -j ou adicione swap para a compilação e remova-a depois.

curl: (7) Failed to connect ... Connection refused a partir do seu computador portátil. Isto está correto: o servidor escuta no endereço de loopback da VPS. Teste na própria VPS ou abra um túnel com ssh -L 8080:127.0.0.1:8080 user@your-vps e utilize http://127.0.0.1:8080 localmente.

HTTP 503 com "message":"Loading model" durante os primeiros segundos ou minutos depois de um reinício. A leitura de um ficheiro com vários gigabytes demora tempo, e o systemd comunica que a unidade está ativa assim que o processo arranca, muito antes de o modelo estar carregado na memória.

Os pedidos ficam bloqueados e depois devolvem 504 Gateway Time-out. O servidor não enviou nada durante mais tempo do que proxy_read_timeout, o que pode acontecer com pedidos sem streaming. Os pedidos de streaming em b10488 enviam, por predefinição, pings de keepalive a cada 30 segundos durante o processamento de prompts longos. Aumente proxy_read_timeout e desative proxy_buffering para que os tokens cheguem ao cliente à medida que são produzidos.

A unidade reinicia repetidamente e depois para com start request repeated too quickly. O número de arranques excedeu o limite de taxa configurado. Verifique journalctl -u llama-server à procura da linha do OOM killer e, em seguida, reduza --ctx-size ou aumente MemoryMax.

FAQ

Devo executar o servidor do llama.cpp ou o Ollama na minha VPS?

Execute llama-server quando quiser fixar uma compilação exata, passar flags exatas e manter um modelo num único ficheiro que nada atualiza sem o seu conhecimento. Use o Ollama quando quiser gestão de modelos e atualizações com um comando, porque obter modelos pelo nome, manter vários modelos no disco e descarregar os que estão inativos são tarefas que, de outro modo, teria de automatizar com scripts. Ambos disponibilizam uma API compatível com OpenAI, mas a mudança exige verificar os endpoints e as funcionalidades usadas pelo seu cliente.

Que versão do llama.cpp devo fixar?

Qualquer tag que tenha efetivamente compilado e testado. As compilações de desenvolvimento nightly usam tags com o número da compilação, como b10488, publicada em 18 August 2026; as versões oficiais usam tags de versão semântica, vX.Y.Z. Faça o clone com --branch <tag>, instale o binário num nome de ficheiro que contenha essa tag e aponte um symlink para ele, para que a atualização e o rollback possam ser feitos com um comando cada.

De quanta RAM precisa o llama-server?

Comece pelo tamanho do ficheiro GGUF e adicione a cache KV, que cresce com --ctx-size. Esse valor é o orçamento total de tokens partilhado por todos os slots --parallel, pelo que mais slots exigem um --ctx-size maior se cada um tiver de manter o mesmo contexto. Os valores publicados não substituem a medição da sua própria configuração, porque o total depende do modelo, da quantização e do contexto permitido. Execute systemctl show llama-server -p MemoryCurrent enquanto houver um pedido em curso e use o número apresentado.

Por que motivo /health devolve 503 com "Loading model"?

O processo iniciou, mas o ficheiro do modelo ainda não está na memória, pelo que o servidor responde com {"error":{"code":503,"message":"Loading model","type":"unavailable_error"}}. Isto é normal depois de cada reinício e dura enquanto a leitura do ficheiro estiver a decorrer. Só se torna um problema quando um cliente ou proxy trata esse primeiro 503 como uma falha definitiva. Consulte /health repetidamente até devolver {"status": "ok" }.

Posso expor o llama-server diretamente à Internet?

Não o associe a 0.0.0.0 nem abra a porta. Use o proxy para contas, limites de taxa dos pedidos e registo de auditoria; a autenticação integrada da API usa chaves estáticas definidas com --api-key ou --api-key-file. Mantenha a associação predefinida 127.0.0.1, coloque o nginx à frente com TLS e defina também --api-key, para que um erro na configuração do proxy não deixe o modelo acessível a qualquer pessoa.

Este artigo foi útil?