Ollama: como funcionam NUM_PARALLEL e MAX_QUEUE
Entenda quando a segunda solicitação espera ou recebe HTTP 503, como OLLAMA_NUM_PARALLEL e OLLAMA_MAX_QUEUE agem e por que cada slot consome memória.
O que acontece com o segundo pedido ao Ollama enquanto o primeiro está a ser gerado
A concorrência do Ollama é definida por três variáveis de ambiente e, por predefinição, um modelo carregado atende um pedido de cada vez. O segundo pedido não é recusado nem recebe uma resposta parcial. Fica numa fila até haver um slot livre e depois é executado à velocidade normal.
Um pedido recebido tem três destinos possíveis. Pode começar imediatamente num slot livre. Pode ficar à espera na fila. Ou a fila pode já estar cheia e o servidor recusá-lo com HTTP 503. O resultado depende de OLLAMA_NUM_PARALLEL, OLLAMA_MAX_QUEUE e OLLAMA_MAX_LOADED_MODELS. Existe uma particularidade nas versões atuais, em outubro de 2026. A FAQ descreve a fila em termos gerais, mas o código-fonte do agendador é mais específico. O erro 503 só se aplica a pedidos recebidos enquanto o respetivo modelo ainda tem de ser carregado ou recarregado com definições diferentes. O Ollama não recusa um pedido que possa ser atendido pelo modelo já carregado, tal como está. Esse pedido espera por um slot durante o tempo necessário.
A predefinição é segura. É também por isso que um segundo utilizador pode dizer que o servidor "bloqueou", mesmo quando não existe nenhuma falha. Adicionar slots requer apenas duas linhas de alteração. O ponto crítico é a memória. Cada slot paralelo precisa da sua própria cache de chaves/valores (cache KV), o bloco de memória onde o modelo mantém os tokens que já processou. Se adicionar slots sem aumentar a VRAM (memória de vídeo da GPU), transforma uma resposta lenta numa falha de carregamento. Num servidor que usa apenas CPU, a mesma cache é alocada na RAM do sistema.
O que controlam OLLAMA_NUM_PARALLEL, OLLAMA_MAX_QUEUE e OLLAMA_MAX_LOADED_MODELS
Estes são os valores predefinidos nas versões atuais do Ollama em outubro de 2026. Confirme os seus em vez de confiar no número apresentado aqui, usando a linha do log mostrada mais abaixo.
OLLAMA_NUM_PARALLELindica quantos pedidos um modelo carregado processa em simultâneo. O valor predefinido é 1, por isso os pedidos são processados um após o outro.OLLAMA_MAX_LOADED_MODELSindica quantos modelos diferentes permanecem residentes em simultâneo. O valor predefinido é 0, o que significa que o Ollama escolhe: três modelos por GPU e três numa máquina sem GPU.OLLAMA_MAX_QUEUEé, nas palavras da FAQ, o número máximo de pedidos que o Ollama coloca em fila quando está ocupado antes de rejeitar pedidos adicionais. O valor predefinido é 512. O pedido que chega quando a fila está cheia é rejeitado imediatamente. No código atual do scheduler, porém, apenas os pedidos cujo modelo tem de ser carregado ou recarregado primeiro entram nesta fila. Os pedidos para um modelo que já está carregado ignoram esta fila e aguardam uma slot livre; esta espera não tem limite. Um maintainer descreveu isto como um efeito secundário da implementação do scheduler, e os maintainers do Ollama acompanham uma correção como pedido de funcionalidade (issue #7758), que continuava em aberto em outubro de 2026.
No pior caso, a memória é o produto dos dois primeiros valores. Dois modelos carregados com quatro slots cada correspondem a oito alocações de slots de cache KV, todas residentes em simultâneo, e o Ollama tentará satisfazer essa configuração. Numa máquina com uma única GPU, normalmente é melhor manter um modelo e atribuir-lhe slots, porque os cálculos continuam a ser fáceis de fazer mentalmente.
Por que cada slot paralelo consome VRAM
Quando o Ollama carrega um modelo, inicia um processo runner separado. Dois dos argumentos que passa são importantes aqui: -c é o contexto total para o qual o runner aloca uma cache KV, e -np é o número de sequências paralelas. O Ollama define -c como o comprimento do contexto por pedido multiplicado pelo número de slots. Depois, o runner divide esse total igualmente entre os slots, para que cada pedido continue a receber o comprimento de contexto solicitado.
Essa é toda a restrição e explica por que o paralelismo não é gratuito. Passar de um slot para quatro exige quatro vezes mais cache KV com o mesmo contexto por pedido. Nada é partilhado entre os slots, e a parte de um slot inativo não é cedida a um slot ocupado, porque a divisão é fixa quando o runner arranca. Numa GPU, essa memória é VRAM. Num servidor apenas com CPU, é RAM do sistema, e aplica-se a mesma multiplicação.
Pode consultar os valores reais, em vez dos valores que pretendia definir:
journalctl -u ollama --no-pager -n 500 | grep "starting llama-server"Essa linha contém a linha de comandos completa do runner, incluindo -c e -np. Se -np for 1 depois de definir a variável, verifique primeiro o tipo de modelo. O Ollama v0.40.15 adicionou pedidos paralelos para modelos GGUF recorrentes e de visão, pelo que a restrição anterior de um único slot já não se aplica a esses modelos. Os modelos de embeddings continuam a receber um slot no scheduler. Num modelo GGUF de completions, confirme se a definição está a chegar ao servidor, como explica a secção seguinte.
Se os pesos do modelo mais essa cache KV não couberem na VRAM, o Ollama move algumas camadas para a RAM do sistema e essas camadas são executadas na CPU. As camadas da CPU são muito mais lentas do que as camadas da GPU, pelo que cada pedido fica mais lento, incluindo o único pedido que iniciou. Aumentar o paralelismo pode, portanto, reduzir o throughput em vez de o aumentar. Num modelo suficientemente grande, os pesos por si só determinam a resposta antes de qualquer cálculo de slots, razão pela qual alojar localmente algo do tamanho do Kimi K3 é uma questão de quantas placas tem, e não de quantos slots definiu.
ollama psA coluna PROCESSOR apresenta 100% GPU quando tudo cabe. Uma divisão como 35%/65% CPU/GPU significa que parte do modelo está a ser executada na CPU. A coluna SIZE inclui a cache KV, pelo que cresce quando aumenta o número de slots e recarrega o modelo. Aumente OLLAMA_NUM_PARALLEL, reinicie, envie um pedido e execute ollama ps novamente: esse é o custo de memória da alteração, medido em vez de estimado. Se essa medição indicar que o modelo já não cabe, lembre-se de que os pesos são a outra metade do mesmo orçamento, e passar de uma compilação fp16 para q8 ou q4 normalmente liberta mais VRAM do que custa o slot que estava a tentar adicionar.
O comprimento do contexto e o número de slots multiplicam-se, por isso têm de ser escolhidos em conjunto. Um contexto grande com quatro slots corresponde a quatro contextos grandes. Se também estiver a ajustar a janela de contexto num_ctx do seu modelo, altere apenas um dos dois de cada vez. Caso contrário, não saberá qual deles encheu a placa.
Como definir estas variáveis para que persistam após um reboot
No Linux, o Ollama é executado como um serviço systemd. Executar export OLLAMA_NUM_PARALLEL=4 na sua shell não altera nada, porque o systemd inicia o serviço com o seu próprio ambiente e nunca vê a sua shell. Use um ficheiro drop-in.
sudo systemctl edit ollama.serviceAdicione isto no editor que abrir:
[Service]
Environment="OLLAMA_NUM_PARALLEL=4"
Environment="OLLAMA_MAX_LOADED_MODELS=1"
Environment="OLLAMA_MAX_QUEUE=32"Depois, recarregue e reinicie:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property=Environmentsystemctl show mostra o que o systemd entregará ao processo. Se a sua variável não aparecer ali, o drop-in não foi guardado ou daemon-reload foi omitido. Confirme também a partir do próprio servidor:
journalctl -u ollama --no-pager | grep "server config" | tail -1O Ollama regista a configuração do servidor no arranque, numa linha cuja mensagem é server config. Esse mapa mostra os valores das variáveis de ambiente configuradas que o Ollama comunica e é a forma mais rápida de resolver uma dúvida sobre a aplicação de uma variável. Ele mostra o valor que definiu, não o número de slots que um determinado modelo recebeu. Para isso, leia o valor -np na linha do runner acima.
Um modelo que já esteja carregado mantém o número de slots com que foi iniciado, porque o valor fica definido no processo do runner no arranque. O reinício acima descarrega tudo, para que o pedido seguinte carregue novamente o modelo com a nova configuração e suporte o tempo de carregamento uma vez. Durante quanto tempo um modelo permanece residente depois disso é um controlo separado, abordado em manter um modelo Ollama carregado entre pedidos.
Como as respostas servidas, colocadas em fila e recusadas aparecem no cliente
Envie vários pedidos ao mesmo tempo e meça o tempo de resposta. Isto executa oito pedidos de streaming em paralelo e mostra o estado e os tempos de cada um:
for i in $(seq 1 8); do
curl -s -o /dev/null \
-w "req$i http=%{http_code} ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
http://127.0.0.1:11434/api/generate \
-d '{"model":"llama3.2:3b","prompt":"Explain what a KV cache is.","stream":true}' &
done
waitttfb é o tempo até ao primeiro byte do stream. Este valor é próximo do tempo até ao primeiro token (TTFT), porque o primeiro bloco enviado contém o primeiro token.
Servidos em paralelo. Todos os pedidos apresentam um ttfb semelhante, e o total aumenta em conjunto para todos. A GPU é partilhada entre os slots em execução. Por isso, cada resposta é mais lenta do que seria isoladamente, mas há mais respostas concluídas por minuto. Este é o regime que está a obter ao aumentar OLLAMA_NUM_PARALLEL.
Em fila. Os primeiros pedidos respondem rapidamente. Os seguintes apresentam um ttfb elevado, seguido de uma geração normal. A espera está na fila, não no modelo. Numa janela de chat, o utilizador vê uma pausa longa sem conteúdo e depois texto à velocidade normal. Este padrão, lento no início e rápido depois, indica uma fila e não uma GPU sobrecarregada.
Recusados. O cliente recebe http=503 quase imediatamente, e o corpo é:
{"error":"server busy, please try again. maximum pending requests exceeded"}Esta mensagem significa que a fila de agendamento estava cheia quando o pedido chegou. Não fornece qualquer informação sobre a VRAM nem sobre o modelo. Nas versões atuais, essa fila contém apenas pedidos cujo modelo ainda não foi carregado ou tem de ser carregado novamente com configurações diferentes. Se o modelo já estiver residente quando executar o ciclo acima, espere que todos os pedidos devolvam 200, independentemente do valor baixo definido para OLLAMA_MAX_QUEUE. O excesso aparece, em vez disso, como um ttfb mais elevado.
Há uma limitação importante: o Ollama não publica a profundidade da fila. ollama ps e o endpoint /api/ps mostram os modelos carregados, não os pedidos em espera. Por isso, a fila tem de ser medida do lado do cliente, observando o tempo até ao primeiro byte, ou contando as respostas 503 no componente que estiver à frente.
Por que um MAX_QUEUE menor costuma ser uma configuração melhor
Uma fila de 512 parece generosa, mas, com apenas um slot, é quase inútil. A solicitação 300 fica atrás de 299 gerações concluídas. Isso demora vários minutos, na melhor das hipóteses. Qualquer cliente HTTP desiste muito antes disso. O chamador recebe um timeout do lado do cliente, que não informa a causa e não permite que o seu sistema de monitorização gere um alerta útil.
Uma fila menor transforma esse excesso numa resposta 503 imediata, mas apenas para solicitações que aguardam o carregamento ou recarregamento de um modelo, como o pico que chega depois de um reinício ou durante a troca de modelos. Em outubro de 2026, as solicitações para um modelo que já está carregado ignoram OLLAMA_MAX_QUEUE e aguardam por um slot livre sem limite. Por isso, reduzir a fila não encurta a espera num servidor ocupado com um modelo residente. Para obter uma recusa rápida nesse caso, limite a concorrência à frente do Ollama, conforme descrito na secção seguinte. Uma resposta 503 é útil: um reverse proxy pode tentar novamente, um cliente pode aplicar backoff, um dashboard pode contabilizá-la e uma pessoa pode interpretá-la. Calcule o limite com base nas suas próprias medições. Se uma geração demora cerca de dez segundos e o seu cliente aguarda sessenta, cerca de seis solicitações por slot podem terminar dentro desse intervalo. Permitir que mais solicitações aguardem apenas produz timeouts.
Quando colocar uma fila à frente do Ollama
A fila incorporada funciona no modelo first in, first out (FIFO) e não sabe quem está a fazer o pedido. Para uma aplicação a comunicar com um único servidor, isso é suficiente. Adicionar infraestrutura apenas introduziria mais modos de falha. Use uma solução à frente do Ollama quando uma destas condições se aplicar.
- Precisa de prioridade. Um chat interativo não deve esperar atrás de um trabalho de sumarização em lote. A fila do Ollama não tem prioridades. Por isso, o trabalho em lote tem de ser mantido externamente e enviado lentamente.
- Precisa de equidade. Um cliente pode ocupar todos os slots e acumular pedidos em espera. Os restantes clientes ficam atrás desse cliente ou recebem 503 se o pedido precisar de um modelo carregado.
- Precisa de um tempo de espera limitado. O Ollama mantém indefinidamente os pedidos de um modelo que já está carregado. Por isso, o único limite fiável é um limite definido à frente do Ollama.
- Precisa que o trabalho sobreviva a um reinício. A fila existe na memória do servidor. Se reiniciar o Ollama, todos os pedidos em espera são perdidos.
- Precisa de novas tentativas reais com backoff, registadas num local que possa consultar posteriormente.
A opção mais simples é um reverse proxy. No nginx, limit_conn limita o número de ligações simultâneas e limit_req limita a taxa de chegada por cliente. Assim, o excesso é recusado no proxy e nunca chega ao Ollama. A opção mais robusta é uma fila de trabalhos com uma base de dados à frente de um worker que chama o Ollama. É essa a opção adequada quando os pedidos têm de sobreviver ao reinício de um processo. Dimensionar essa solução para tráfego real é um exercício separado: planear um LLM self-hosted para utilizadores simultâneos explica os cálculos, e executar o Ollama numa VPS aborda a instalação base que estas variáveis pressupõem.
Quando a resposta correta é outro servidor
Há um limite que não pode ser ultrapassado com ajustes. O Ollama divide a cache KV em slots iguais e fixos quando o modelo é carregado. A memória de um slot inativo não pode ser usada por um slot ocupado, e o número de slots não pode mudar sem descarregar o modelo. Esse desenho é adequado para uma pessoa, uma equipa pequena ou um agente de programação.
Servidores concebidos para muitos utilizadores em simultâneo funcionam de forma diferente. Alocam a cache KV em páginas pequenas, conforme necessário, e adicionam os pedidos recebidos a um batch que já está em execução. Assim, a memória acompanha a utilização real, em vez de seguir uma divisão fixa. Se o objetivo for suportar muitos utilizadores concorrentes numa única GPU, essa diferença arquitetural é mais importante do que qualquer valor de OLLAMA_NUM_PARALLEL. A comparação entre Ollama e vLLM é o local certo para tomar essa decisão. No entanto, não mude apenas por princípio. Operar um servidor diferente exige mais trabalho. Se o tráfego vier de poucas pessoas, o comportamento integrado é a opção correta. Se a questão real for saber se deve executar um servidor de modelos por conta própria, a comparação entre um servidor de IA privado com orçamento sob consulta e a criação da mesma stack numa GPU alugada explica essa decisão, incluindo os casos em que uma API é uma opção de compra melhor.
Meça o seu próprio throughput e o tempo até ao primeiro token
Os valores publicados de tokens por segundo vêm da GPU, do modelo, da quantização, do tamanho do contexto e do prompt de outra pessoa. Nenhum desses parâmetros corresponde aos seus, por isso trate qualquer valor lido como uma indicação aproximada e meça a máquina que tem à sua frente.
Ollama devolve os tempos no objeto JSON final de cada resposta. eval_count é o número de tokens gerados e eval_duration é o tempo gasto a gerá-los, em nanossegundos.
sudo apt install -y jq
curl -s http://127.0.0.1:11434/api/generate \
-d '{"model":"llama3.2:3b","prompt":"Explain what a KV cache is.","stream":false}' \
| jq '{prompt_eval_count, eval_count, eval_duration, tokens_per_second: (.eval_count / (.eval_duration / 1000000000))}'Execute isso com um slot e depois novamente com a simultaneidade que espera realmente utilizar. Compare os dois valores que determinam a satisfação dos utilizadores: o tempo até ao primeiro token e os tokens por segundo por pedido. O throughput por pedido diminui sempre que são adicionados slots. A questão é saber se diminui mais do que os seus utilizadores aceitam. Medir tokens por segundo num LLM local explica o método com mais detalhe, incluindo como manter o prompt constante entre as execuções.
Um endpoint público com uma fila generosa é um alvo de negação de serviço
Definir OLLAMA_HOST=0.0.0.0:11434 coloca a API em todas as interfaces, e a API local não exige autenticação. O Ollama tem início de sessão integrado para modelos na cloud, publicação e transferências privadas. A inferência direta na cloud em https://ollama.com/api e https://ollama.com/v1 exige uma chave de API. Com a fila predefinida, um endpoint aberto aceita até 512 pedidos à espera que um modelo seja carregado, de qualquer pessoa que o encontre. Quando um modelo já está carregado, mantém todos os pedidos que estabelecem ligação, sem limite, enquanto cada cliente permanecer ligado. Manter o servidor ocupado desta forma custa quase nada a um atacante: prompts longos, sem início de sessão, sem limite de pedidos e sem custos. Os seus próprios utilizadores recebem respostas 503 ou ficam à espera durante muito tempo, e a máquina permanece ocupada durante todo esse período.
Mantenha o listener na interface de loopback e aceda-lhe através de um túnel SSH ou de uma rede privada, ou coloque autenticação e limitação de pedidos à sua frente. Proteger um endpoint da API do Ollama aborda ambas as opções. Ajuste a fila só depois de concluir essa configuração, porque o comprimento da fila é uma definição de capacidade e não protege nada.
FAQ
Por que a minha segunda solicitação ao Ollama espera que a primeira termine?
Porque OLLAMA_NUM_PARALLEL tem o valor padrão 1. Assim, um modelo carregado processa uma solicitação de cada vez e as restantes esperam pela sua vez. A solicitação em espera mantém a ligação HTTP aberta e não envia bytes até libertar-se um slot. Do lado do cliente, isto parece um modelo lento. O padrão dos tempos permite distinguir os casos: uma pausa longa seguida de texto à velocidade máxima indica uma fila, enquanto um fluxo lento desde o primeiro token indica um modelo lento. Aumente o número de slots com um drop-in do systemd e reinicie o serviço. Depois, verifique o valor de -np na linha do runner, porque os modelos de embeddings continuam a ter um único slot no agendador.
O que significa "server busy, please try again. maximum pending requests exceeded"?
Esse é o erro de transbordo da fila do Ollama, devolvido com o estado HTTP 503. O número de solicitações à espera de agendamento, ou seja, à espera de o modelo ser carregado ou recarregado, atingiu OLLAMA_MAX_QUEUE, que tem o valor padrão 512. Por isso, a solicitação mais recente foi rejeitada em vez de ser adicionada. As solicitações a um modelo que já está carregado não contam para esse limite. Este erro ocorre sobretudo durante picos no arranque ou enquanto os modelos estão a ser trocados. Não é um erro de memória nem um erro do modelo. Aumentar o tamanho da fila apenas faz com que os clientes esperem mais tempo antes da mesma rejeição. As correções reais são aumentar o número de slots, se houver VRAM disponível, reduzir a carga recebida ou usar uma fila à frente do serviço que possa repetir e definir prioridades.
Aumentar OLLAMA_NUM_PARALLEL torna o Ollama mais rápido?
Não. Permite executar mais solicitações em simultâneo, mas cada solicitação fica mais lenta do que ficaria se fosse executada sozinha, porque todas partilham uma GPU. Também multiplica a cache KV, porque o Ollama inicia o runner com um contexto total igual ao comprimento do contexto multiplicado pelo número de slots. Se o resultado já não couber na VRAM, o Ollama coloca camadas na CPU e todas as solicitações ficam mais lentas, incluindo uma única solicitação sem concorrência. Verifique ollama ps depois da alteração e confirme que a coluna PROCESSOR continua a mostrar 100% GPU.
Preciso de reiniciar o Ollama depois de alterar estas variáveis?
Sim. O servidor lê estas variáveis no arranque, e um modelo em execução mantém o número de slots definido no processo runner quando este foi iniciado. Edite o drop-in com sudo systemctl edit ollama.service e execute sudo systemctl daemon-reload e sudo systemctl restart ollama. Confirme com systemctl show ollama --property=Environment e, depois, verifique a linha server config em journalctl -u ollama, que lista os valores de ambiente configurados reportados pelo Ollama.
Quantos slots paralelos devo configurar?
Comece com 1 e aumente um passo de cada vez. Depois de cada passo, reinicie o Ollama, envie uma solicitação para carregar o modelo e execute ollama ps. Pare no último valor em que PROCESSOR ainda mostre 100% GPU e a coluna SIZE mantenha margem para o contexto mais longo que disponibiliza. Depois, meça o tempo até ao primeiro token e os tokens por segundo com essa configuração, sob a concorrência real, e recue um passo se a velocidade por solicitação tiver descido abaixo do que os utilizadores toleram.