Modo Roteador do Llama-Server - Comutação Dinâmica de Modelos Sem Reinicializações

Sirva e troque LLMs sem reinicializações.

Conteúdo da página

Por muito tempo, o llama.cpp teve uma limitação flagrante: você só podia servir um modelo por processo, e alternar significava reiniciar.

Essa era chegou ao fim.

Atualizações recentes introduziram o modo roteador no llama-server, trazendo algo muito mais próximo do que as pessoas esperam dos runtimes locais modernos de LLM:

  • carregamento dinâmico de modelos
  • descarregamento sob demanda
  • alternância por requisição
  • sem reinício do processo

llm router on the table

Em outras palavras: comportamento semelhante ao Ollama, mas sem as rodinhas de apoio.

Se você ainda está decidindo entre runtimes locais, APIs de nuvem e infraestrutura auto-hospedada, o visão geral de hospedagem de LLM é um bom ponto de partida.

Pré-requisitos

O modo roteador requer um build recente do llama-server — aproximadamente posterior à meados de 2024. Builds mais antigos não possuem as flags --models-preset ou --models-dir.

Para opções de instalação (gerenciador de pacotes, binários pré-compilados ou build completo do source com CUDA), consulte o quickstart do llama.cpp.

Uma vez que você tenha o llama-server, confirme se seu build suporta o modo roteador:

llama-server --help | grep -i models

Se --models-preset ou --models-dir aparecerem, está tudo certo. Se estiverem ausentes, atualize para um build mais novo.

Minha saída atual da ajuda relacionada a modelos:

-cl,   --cache-list                     show list of models in cache
                                        Prefix/Suffix/Middle) as some models prefer this. (default: disabled)
                                        models with dynamic resolution (default: read from model)
                                        models with dynamic resolution (default: read from model)
                                        embedding models (default: disabled)
--models-dir PATH                       directory containing models for the router server (default: disabled)
                                        (env: LLAMA_ARG_MODELS_DIR)
--models-preset PATH                    path to INI file containing model presets for the router server
                                        (env: LLAMA_ARG_MODELS_PRESET)
--models-max N                          for router server, maximum number of models to load simultaneously
                                        (env: LLAMA_ARG_MODELS_MAX)
--models-autoload, --no-models-autoload
                                        for router server, whether to automatically load models (default:
                                        (env: LLAMA_ARG_MODELS_AUTOLOAD)

O que o modo roteador realmente faz

O modo roteador transforma o llama-server em um dispatcher de modelos.

Em vez de se vincular a um único modelo via -m, o servidor:

  • inicia sem nenhum modelo carregado
  • recebe uma requisição que especifica um modelo
  • carrega esse modelo se ele não estiver já em memória
  • executa a inferência
  • opcionalmente descarrega o modelo após a resposta, ou mantém-o quente para a próxima requisição

A ideia chave

Você não está mais executando:

./llama-server -m model.gguf

Você está executando:

./llama-server --models-preset models.ini --port 8080

E deixando o servidor decidir o que carregar e quando, com base no que o cliente realmente solicita.

Isso importa porque significa que um processo persistente pode servir uma frota inteira de modelos, com os clientes selecionando o certo para cada tarefa — um modelo de código, um modelo de chat, um modelo de resumo — sem qualquer sobrecarga de coordenação do seu lado.

Configuração: definindo seus modelos

É aqui que as coisas ainda são um pouco cruas.

Ainda não há um formato oficial totalmente estável, mas os builds atuais suportam definições de modelos no estilo INI via arquivo de configuração.

Exemplo de models.ini

[llama3]
model = /opt/models/llama-3-8b-instruct.Q5_K_M.gguf
ctx-size = 8192
ngl = 35
threads = 8

[mistral]
model = /opt/models/mistral-7b-instruct-v0.3.Q4_K_M.gguf
ctx-size = 4096
ngl = 20
threads = 8

[qwen]
model = /opt/models/qwen2.5-coder-7b-instruct.Q5_K_M.gguf
ctx-size = 16384
ngl = 35
threads = 8

Cada nome de seção se torna o identificador do modelo que os clientes usam no campo "model" de suas requisições de API.

Parâmetros de configuração principais

Parâmetro O que controla
model Caminho absoluto para o arquivo GGUF
ctx-size Tamanho da janela de contexto em tokens. Valores maiores usam mais VRAM.
ngl Número de camadas de GPU descarregadas. Defina 0 para apenas CPU; aumente até atingir os limites de VRAM.
threads Threads de CPU para as camadas que permanecem na CPU.

Escolher o valor correto de ngl depende da VRAM disponível da sua GPU — para seleção de GPU e economia de hardware, o guia de hardware de computação é uma referência útil. Para monitorar o consumo de VRAM ao vivo enquanto ajusta, consulte as ferramentas de monitoramento de GPU para Linux.

Iniciando o servidor com configuração

./llama-server --models-preset /opt/llama.cpp/models.ini --port 8080

Confirme se o servidor foi iniciado corretamente:

curl http://localhost:8080/v1/models | jq '.data[].id'

Você deve ver cada nome de seção do seu models.ini listado como um ID de modelo.

Uma nota sobre estabilidade

A interface de configuração INI ainda está evoluindo:

  • as flags podem mudar entre commits
  • alguns parâmetros são reconhecidos apenas por configurações de build específicas
  • a documentação fica para trás em relação à implementação

Fixe-se em um commit específico do llama.cpp se precisar de reprodutibilidade entre reinícios.

Uso da API: alternando modelos por requisição

Uma vez que o servidor esteja em execução, a alternância de modelos acontece através da API padrão compatível com OpenAI. Você simplesmente define o campo "model".

Listar modelos registrados

curl http://localhost:8080/v1/models

Requisição de conclusão — primeiro modelo

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [
      {"role": "user", "content": "Explain router mode in one paragraph"}
    ]
  }'

Alternar para um modelo diferente — mesmo endpoint, mesma porta

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "messages": [
      {"role": "user", "content": "Write a Python function that reads a CSV file"}
    ]
  }'

O servidor lida com o ciclo de descarregamento/carregamento de forma transparente. Seu código cliente não muda — apenas o campo model.

Exemplo em Python

Se você está usando o cliente Python openai:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

# Use o modelo de código
response = client.chat.completions.create(
    model="qwen",
    messages=[{"role": "user", "content": "Write a Go HTTP handler"}],
)
print(response.choices[0].message.content)

# Alterne para o modelo de chat — mesmo cliente, diferente nome de modelo
response = client.chat.completions.create(
    model="llama3",
    messages=[{"role": "user", "content": "What is the capital of Australia?"}],
)
print(response.choices[0].message.content)

O que acontece internamente

Quando uma requisição chega para qwen e llama3 está atualmente carregado:

  1. llama3 é descarregado da VRAM
  2. Os pesos de qwen são lidos do disco e carregados para a VRAM
  3. A inferência é executada
  4. A próxima requisição determina se manter qwen carregado ou alternar novamente

Isso responde diretamente à pergunta comum:

Como um servidor local de LLM pode alternar modelos sem reiniciar

Carregando modelos dinamicamente por requisição, em vez de se vincular na inicialização.

Serviço Systemd: configuração pronta para produção

Criar um usuário dedicado e diretórios

sudo useradd --system --shell /usr/sbin/nologin --home-dir /opt/llama.cpp llm
sudo mkdir -p /opt/llama.cpp/models
sudo chown -R llm:llm /opt/llama.cpp

Copie seu binário e configuração de modelo para o lugar:

sudo cp build/bin/llama-server /opt/llama.cpp/
sudo cp models.ini /opt/llama.cpp/

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

[Unit]
Description=Llama.cpp Router Server
After=network.target

[Service]
Type=simple
User=llm
WorkingDirectory=/opt/llama.cpp
ExecStart=/opt/llama.cpp/llama-server --models-preset /opt/llama.cpp/models.ini --port 8080
Restart=always
RestartSec=5

Environment=LLAMA_LOG_LEVEL=info

[Install]
WantedBy=multi-user.target

Habilitar e iniciar

sudo systemctl daemon-reload
sudo systemctl enable llama-server
sudo systemctl start llama-server

Verificar e inspecionar logs

sudo systemctl status llama-server

journalctl -u llama-server -f

Em um início bem-sucedido, você verá linhas indicando que o servidor está ouvindo e que o registro de modelos foi carregado. Uma verificação rápida de sanidade:

curl -s http://localhost:8080/v1/models | jq '.data[].id'

Agora você tem um serviço persistente com reinício automático e alternância centralizada de modelos — sem necessidade de gerenciamento manual de processos. Se você quiser aplicar o mesmo padrão a outros binários, hospedar qualquer executável como um serviço Linux percorre a abordagem geral.

A flag --metrics do llama-server expõe um endpoint compatível com Prometheus. Para dashboards específicos do llama.cpp, consultas PromQL e regras de alerta, consulte o guia de monitoramento de inferência de LLM. Para a configuração mais ampla de observabilidade, o guia de observabilidade cobre a pilha completa.

Limitações que você precisa entender

O modo roteador é genuinamente útil, mas vem com compensações das quais você deve estar ciente antes de depender dele em produção.

Apenas um modelo em memória por vez

Embora vários modelos sejam definidos no models.ini, apenas um é residente na VRAM por worker em qualquer momento dado. Alternar significa um ciclo completo de descarregamento e recarregamento.

  • alternar significa recarregar
  • o pico de latência é inevitável
  • em um modelo 7B típico em Q5, um recarregamento pode levar de 3 a 10 segundos, dependendo da velocidade do disco e da largura de banda da VRAM

Isso responde a outra pergunta chave:

O llama.cpp suporta servir múltiplos modelos ao mesmo tempo

Não realmente. Ele suporta múltiplas definições, não residência simultânea. Se você precisar de dois modelos genuinamente carregados em paralelo, precisa de dois processos em duas GPUs separadas.

Para consumo de VRAM medido e tokens por segundo através de tamanhos de modelo, os benchmarks de desempenho de LLM cobrem o quadro completo. Para números específicos do llama.cpp em uma GPU de 16 GB — modelos densos e MoE em múltiplos tamanhos de contexto — consulte os benchmarks do llama.cpp em 16 GB de VRAM.

Sem cache inteligente

Diferente do Ollama, que mantém um pool quente e evicta modelos com base na recência:

  • não há estratégia automática de evicção de modelos
  • sem pré-aquecimento em segundo plano
  • sem fila de prioridade para modelos frequentemente usados

Se você enviar requisições alternadas para llama3 e mistral, cada única requisição dispara um recarregamento. Este é o custo fundamental de estar mais próximo do metal.

A latência é imprevisível para workloads mistos

Um workload bem-comportado que usa um modelo consistentemente será rápido. Um workload que intercala múltiplos modelos será lento. Planeje sua lógica de roteamento de cliente de acordo — agrupe requisições por modelo onde possível.

A configuração não é estável

O suporte a INI existe e funciona na maioria dos builds recentes, mas não é totalmente padronizado. As flags e nomes de parâmetros mudaram entre versões. Se você atualizar o llama-server, teste seu models.ini contra o novo build antes de implantar.

Llama.cpp vs Ollama

O modo roteador reduz a antiga lacuna de ciclo de vida com o Ollama — carregamento dinâmico e alternância por requisição agora existem nativamente no llama-server — mas não a fecha. O gerenciamento de memória permanece básico (sem política de evicção, sem pool quente), a estabilidade da configuração ainda é experimental, e alternar entre dois modelos diferentes sempre paga um descarregamento e recarregamento completo em vez do keep-alive baseado em TTL do Ollama. Em resumo: o modo roteador lhe dá controle máximo e uma base hackeável; o Ollama lhe dá uma experiência mais polida e opinativa com menos para configurar.

Para o detalhamento completo par a par — instalação, gerenciamento de modelos, posicionamento de GPU, controle de cache KV, APIs, desempenho, modos de falha e gatilhos concretos para escolher um ou migrar entre eles — consulte llama.cpp vs Ollama em 2026, que é a comparação canônica entre os dois runtimes neste site.

Se você for com o Ollama, a folha de dicas da CLI do Ollama cobre os comandos do dia a dia. Para uma comparação mais ampla que também inclui vLLM, LM Studio e LocalAI, consulte como diferentes runtimes locais se comparam em 2026.

Llama.cpp vs llama-swap

O llama-swap é um orquestrador externo que se posiciona na frente de uma ou mais instâncias do llama-server:

  • ele intercepta requisições e inspeciona o campo model
  • ele inicia o processo llama-server apropriado para aquele modelo
  • ele desliga instâncias ociosas após um timeout configurável
  • ele proxy a requisição uma vez que o modelo esteja pronto

Para uma configuração hands-on, consulte o quickstart do llama-swap.

Diferença chave

Aspecto modo roteador llama-swap
Integrado Sim Não (binário separado)
Maturidade Experimental Mais estável
Flexibilidade Limitada Alta
Camada de controle Interno Proxy externo
Config por modelo Arquivo INI Arquivo YAML
Modelo de processo Processo único Um processo por modelo

Quando usar llama-swap

O llama-swap lhe dá isolamento em nível de processo por modelo, o que significa que uma falha em uma instância de modelo não afeta as outras. Ele também permite que cada modelo execute com flags do llama-server completamente independentes.

Use-o se você precisar de:

  • melhor controle de ciclo de vida e isolamento
  • lógica de alternância mais inteligente com timeouts de ociosidade configuráveis
  • latência mais previsível (cada modelo tem um processo quente após o primeiro carregamento)
  • estabilidade de produção hoje, não eventualmente

Quando o modo roteador nativo é suficiente

Use o roteador integrado se você quiser:

  • zero dependências externas
  • um único processo para gerenciar
  • implantação mais simples (um binário, um arquivo de configuração)
  • pilha mínima para desenvolvimento ou setups de usuário único

Pensamentos finais

O modo roteador é um passo significativo para frente para o llama-server.

Ele responde à demanda de longa data:

O que é o modo roteador no servidor llama.cpp

É a camada em falta que transforma um binário estático em um serviço dinâmico de inferência — um processo que pode atender requisições para um catálogo inteiro de modelos.

Mas não está terminado.

Hoje ele é:

  • poderoso o suficiente para workloads reais
  • promissor como fundação para roteamento mais sofisticado
  • ligeiramente áspero nas bordas de configuração e estabilidade

Se seu workload é previsível e você pode agrupar requisições por modelo, o modo roteador funciona bem hoje. Se você precisa de confiabilidade de nível de produção e isolamento por modelo, procure o llama-swap enquanto a implementação nativa amadurece.

Quando você precisa de liberar VRAM sem reiniciar — para uma execução de benchmark, uma janela de manutenção ou um reset limpo de desenvolvimento — a abordagem scriptável é listar os modelos carregados e chamar o endpoint de descarregamento para cada um. O padrão completo de curl-e-jq é coberto em Descarregar Todos os Modelos do Roteador llama.cpp Sem Reiniciar.

De qualquer forma, você obtém comportamento semelhante ao Ollama, sem esconder a maquinaria.

Subscrever

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.