llama.cpp

Pi suporta o servidor roteador llama.cpp. O roteador descobre vários modelos GGUF e os carrega ou descarrega sob demanda.

Use uma versão llama.cpp atual com suporte para roteador. Siga o build instructions ou instale um prebuilt release para sua plataforma.

Comece llama-server sem --model ou -m. A passagem de um modelo inicia o modo de modelo único em vez do modo roteador.

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

Opções importantes:

• --models-dir ~/models descobre arquivos GGUF locais.
• --no-models-autoload continua carregando explícito até /llama.
• --jinja permite modelos de bate-papo compatíveis e chamadas de ferramentas.
• -ngl 999 descarrega tantas camadas quanto possível para a GPU.
• -c 32768 define a janela de contexto para cada modelo carregado. Omita-o para usar o contexto nativo do modelo, o que pode exigir substancialmente mais memória.

Um modelo de arquivo único pode ficar diretamente no diretório do modelo. Coloque modelos multimodais e multifragmentos em subdiretórios separados:

~/models/
├── llama-3.2-1b-Q4_K_M.gguf
├── gemma-3-4b-it-Q4_K_M/
│   ├── gemma-3-4b-it-Q4_K_M.gguf
│   └── mmproj-F16.gguf
└── large-model-Q4_K_M/
    ├── large-model-Q4_K_M-00001-of-00003.gguf
    ├── large-model-Q4_K_M-00002-of-00003.gguf
    └── large-model-Q4_K_M-00003-of-00003.gguf

Reinicie o roteador após adicionar arquivos manualmente. Para tamanhos de contexto por modelo e outras opções, use llama.cpp model presets.

Inicie Pi e configure o provedor:

/login llama.cpp

Insira o URL do roteador e opcional API key. O URL padrão é http://127.0.0.1:8080.

Variáveis ​​de ambiente podem configurar os mesmos valores sem /login:

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret
pi

Se o servidor usar API key, inicie llama-server com o valor --api-key correspondente. Mantenha --host 127.0.0.1 para acesso somente local.

Correr:

/llama

• Selecione um modelo descarregado para carregá-lo.
• Selecione um modelo carregado para descarregá-lo.
• Selecione Baixar modelo…, pesquise Hugging Face e escolha um repositório e quantização. Os valores owner/repository[:quant] exatos também funcionam.
• Pressione Escape durante um carregamento ou download para confirmar o cancelamento.

A pesquisa Hugging Face usa HF_TOKEN quando definida e verifica $HF_TOKEN_PATH, $HF_HOME/token, $XDG_CACHE_HOME/huggingface/token e ~/.cache/huggingface/token. A pesquisa também funciona sem autenticação, sujeita a limites de taxas mais baixos. Pi avisa antes de baixar repositórios bloqueados e links para sua página de acesso. O servidor llama.cpp realiza o download, portanto seu processo também deverá ter HF_TOKEN quando o repositório selecionado necessitar de acesso.

Se outros modelos estiverem carregados, Pi pergunta se deve descarregá-los primeiro ou mantê-los carregados. Pi não descarrega modelos silenciosamente e nunca exclui arquivos de modelo. O roteador pode ser compartilhado com outros clientes, portanto /llama sempre exibe o estado atual do roteador.

Apenas modelos carregados aparecem em /model. Após carregar um modelo, execute /model para selecioná-lo para a sessão Pi atual.

Se o roteador for desconectado, /llama mostrará Tentar novamente e Fechar. A nova tentativa reconecta e atualiza o estado do modelo sem repetir a operação interrompida.

Verifique se o roteador está acessível:

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/models

• Nenhum modelo em /llama: Verifique --models-dir, o layout do diretório, e reinicie o roteador.
• Modelo ausente em /model: Carregue-o com /llama primeiro.
• O carregamento falha ou usa muita memória: Reduza -c ou descarregue outro modelo.
• O servidor não está no modo roteador: Inicie-o sem --model, -m ou -hf.