Quantos workers do FastAPI cabem em uma VPS com pouca RAM?

Fala aí, beleza? Se tu tá procurando o número mágico de workers do FastAPI pra uma VPS com pouca RAM, já te adianto: ele não existe 😛

Cada worker do FastAPI é um processo próprio, com seu próprio PID. E qualquer coisa carregada na inicialização: um modelo de IA, um cache pesado, qualquer objeto grande guardado em memória: é carregada separadamente em cada worker: com --workers 1 existe uma cópia, com --workers 4 existem quatro (fonte secundária)

Ou seja, o número certo depende da SUA aplicação, não de uma tabela pronta da internet

Este post é pra quem já publicou uma API FastAPI numa VPS pequena e quer usar o --workers sem estourar a RAM

A ideia é simples: medir quanto um worker consome, fazer a conta com a RAM e os núcleos da máquina e só então subir o valor

Bora ver na prática?

O que você precisa antes de ajustar os workers:

Antes de mexer em qualquer número, confere se tu tem estas três coisas na mão:

• Uma aplicação FastAPI rodando com fastapi ou uvicorn: os dois comandos aceitam a opção --workers, que inicia vários processos em paralelo pra aproveitar CPUs com mais de um núcleo (documentação de server workers)
• Acesso ao servidor: você vai precisar iniciar a aplicação e observar os processos dela
• Os números da sua VPS: quantos vCPUs e quanta RAM ela tem, porque são exatamente esses dois limites que entram na conta dos workers

E aí vem a pergunta: qual VPS usar pra isso?

Aqui na Hora de Codar a recomendação principal pra esse tipo de projeto é a VPS da Hostinger (aviso rápido: este artigo contém links de afiliado da Hostinger)

O motivo é bem prático pro nosso problema: os planos deixam claro o par vCPU e RAM, que é justamente o que tu vai usar no cálculo (página oficial dos planos)

Além disso, a VPS tem acesso root completo, o que te deixa rodar e inspecionar os processos da aplicação sem pedir permissão pra ninguém 🙂

Os planos usam virtualização KVM, vêm com IP dedicado, processadores AMD EPYC, armazenamento SSD NVMe e backups semanais gratuitos

Se liga num detalhe: a VPS da Hostinger é autogerenciada (self-managed). Isso significa acesso root completo e controle total sobre o sistema, incluindo o dimensionamento dos workers do FastAPI, o monitoramento e a manutenção do ambiente: é exatamente isso que o resto do post ensina a fazer

Passo a passo para dimensionar os workers do FastAPI:

A lógica é sempre a mesma: um worker de referência, uma medição honesta e uma conta simples

1. Rode com um único worker pra criar a linha de base

Sobe a aplicação sem passar --workers, que é o mesmo que rodar com um único worker:

fastapi run app/main.py

Por que começar com um só?

Porque tu quer saber quanto UM processo consome, e não o total de vários somados

Erro comum deste passo: medir com vários workers já ativos e achar que aquele total é o consumo por processo. Aí a conta inteira sai errada

2. Observe a memória desse processo pelo PID

Com --workers, cada worker ganha um PID próprio no log de inicialização, junto com um PID do processo pai que gerencia todos eles (documentação de server workers). Então dá pra acompanhar cada processo separadamente

Use a ferramenta de monitoramento que você já usa no servidor e olha a memória daquele PID

Faz isso com a aplicação recebendo requisições, não parada, porque o consumo de um processo recém-iniciado nem sempre reflete o consumo em operação normal

Deixa a aplicação rodar um tempo sob tráfego real (ou simulado) até o consumo de memória parar de subir, e só então anota esse valor como a memória de um worker

3. Faça a conta com RAM e vCPU

Agora é matemática de padaria:

workers_pela_ram = RAM livre para a aplicação / RAM medida de um worker
workers = menor valor entre workers_pela_ram e a quantidade de vCPUs

Que RAM livre é essa?

É a memória que sobra depois do sistema operacional e dos outros serviços que rodam na mesma VPS (banco, proxy e por aí vai)

E por que o vCPU entra como teto?

Aqui vale um aviso importante: isso não vem escrito na documentação do FastAPI, é uma regra prática que a gente adota aqui no Hora de Codar. A documentação confirma que a replicação de processos serve pra aproveitar vários núcleos e atender mais requisições (documentação de server workers), mas não define um número ideal de workers nem fala em vCPU como limite. Na prática, como cada worker é um processo concorrendo por CPU, usar a quantidade de vCPUs como teto evita criar mais processos do que a máquina consegue executar em paralelo de verdade. É heurística nossa, não recomendação oficial do projeto

Erro comum deste passo: esquecer que um modelo ou objeto pesado carregado na inicialização é carregado uma vez POR worker. Com --workers 1 existe uma cópia, com --workers 4 existem quatro (explicação sobre carregar modelo uma vez, fonte secundária)

Tome cuidado com isso, é o tipo de coisa que derruba a VPS do nada quando tu sobe o número de workers

Se a conta der apertada, antes de qualquer coisa revisa o que a aplicação carrega na memória ao iniciar. A mesma mentalidade vale pra outras ferramentas, tipo quando a gente fala de otimizar o n8n com pouca RAM

4. Aplique o valor calculado

Com o número em mãos, sobe a aplicação assim:

fastapi run --workers N app/main.py

No uvicorn a opção é a mesma: --workers N

Se você roda em Docker sem orquestrador, o Dockerfile de exemplo da documentação de Docker do FastAPI usa este CMD, sem --workers:

CMD ["fastapi", "run", "app/main.py", "--port", "80"]

Pra rodar vários workers dentro desse mesmo container, acrescenta a opção --workers com o N que saiu da sua conta:

CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "N"]

E se o container fica atrás de um proxy fazendo terminação TLS, como Nginx ou Traefik, a documentação manda acrescentar --proxy-headers:

CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"]

5. Valide e mantenha

Depois de subir, confere se existe um PID por worker, ou seja, se a quantidade de processos bate com o N que você definiu

Aí observa a memória total com a aplicação sob carga, pra ver se o resultado ficou perto do que a conta previu

E o mais importante: refaz a medição sempre que a aplicação passar a carregar algo novo na memória (um modelo, um cache, uma biblioteca pesada e etc)

O número de workers não é "configura e esquece", ele acompanha a aplicação

Workers no container ou um processo por container?

Depende de quem faz a replicação: o orquestrador ou você

Com Kubernetes ou um orquestrador parecido, a documentação do FastAPI recomenda rodar um único processo Uvicorn por container, sem --workers:

CMD ["fastapi", "run", "app/main.py", "--port", "80"]

Nesse cenário quem cria as réplicas é o orquestrador, e cada container roda exatamente um processo. É razoável esperar que o consumo de memória de cada container fique na mesma faixa do que você mediu por worker no passo 2, mas vale confirmar isso com uma nova medição depois do deploy: a documentação do FastAPI não detalha o comportamento de memória especificamente nesse cenário com orquestrador, então não dá pra tratar os dois números como idênticos sem checar

Já numa VPS simples, sem orquestrador, o caminho é o outro: vários workers dentro de um único container (ou direto no sistema, sem container nenhum), com --workers no comando de inicialização

Só que aí o trabalho de dimensionar sai do orquestrador e cai no seu colo 😀

Ou seja, a medição por worker e a conta que vimos no passo a passo ficam por conta de quem administra a VPS

Se um dia o projeto crescer pra várias instâncias, vale entender os trade-offs de arquitetura com múltiplos workers, que a gente discute no post sobre n8n em queue mode

Mais conteúdo do Hora de Codar:

Aproveita e confere mais um conteúdo do canal 😀

Próximo passo: medir antes de escalar

A ação de hoje é uma só: sobe a aplicação com um worker, mede a memória desse PID com tráfego chegando e faz a conta

Só depois disso mexe no --workers

Se mesmo depois de revisar o que é carregado na inicialização a conta mostrar que nem o mínimo de workers cabe na RAM, aí sim faz sentido comparar os planos KVM pelo par vCPU e RAM

Repara que a ordem importa: um modelo duplicado em cada worker é problema de configuração, e upgrade de máquina só esconde ele por um tempo

Quando o upgrade for de fato necessário, dá pra conferir a VPS para este projeto escolhendo o plano em que a sua conta fecha com folga

E aí, quantos workers coube na sua VPS? Bora trocar uma ideia nos comentários

até o próximo post! 🙂

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.