O DeepSeek-V4-Flash-0731 chegou ao estado de produção a 31 de julho de 2026 e trouxe algo raro no mundo dos modelos de linguagem: pesos abertos, licença permissiva e desempenho de topo em tarefas de código, tudo isto num pacote Mixture-of-Experts com 284 mil milhões de parâmetros totais mas apenas 13 mil milhões ativos por token. Isso muda a equação para quem quer alojar o próprio modelo em vez de depender só da API da DeepSeek. Neste tutorial vamos montar um servidor de inferência com o vLLM dentro de contentores Docker, expondo uma API compatível com OpenAI que qualquer aplicação já preparada para o formato /v1/chat/completions consegue usar sem alterações.

Já existem guias no nosso site sobre Ollama e LM Studio para quem quer correr modelos pequenos num portátil. Este artigo é diferente: aqui o objetivo é montar uma infraestrutura de produção com vLLM, a mesma engine de serviço que a própria DeepSeek recomenda oficialmente no cartão do modelo no Hugging Face, e que a NVIDIA usa nos seus próprios “recipes” de implementação com Dynamo. Vamos cobrir hardware realista (a maioria dos leitores vai alugar GPU na nuvem, não comprar), erros comuns e uma checklist de resolução de problemas.

Vale a pena situar o momento: a linha V4 da DeepSeek passou de pré-visualização (24 de abril de 2026) para disponibilidade geral (20 de julho), com o build de produção do Flash a chegar a 31 de julho e o irmão maior, o V4-Pro, a sair de pré-visualização a 12-13 de agosto. Nesse processo, a DeepSeek reformou os aliases antigos “deepseek-chat” e “deepseek-reasoner”, que deixaram de responder depois de 24 de julho de 2026 – se o seu código ainda referencia esses nomes, é motivo extra para migrar já para os novos identificadores de modelo. Este tutorial assume que está a partir do zero, com uma instância cloud limpa, e termina com um serviço de produção a responder pedidos reais através de uma API compatível com OpenAI.

O que é o vLLM e porque é diferente do Ollama

O vLLM é um motor de inferência open source construído para servir modelos de linguagem em produção, com paged attention, batching contínuo de pedidos e suporte nativo a paralelismo tensorial em várias GPUs. Ao contrário do Ollama, desenhado para simplicidade num único computador, o vLLM assume que vai correr num servidor com uma ou mais GPUs de datacenter e que vai atender vários pedidos simultâneos com throughput elevado.

Essa diferença de propósito importa na escolha. Se quer testar um modelo pequeno no seu portátil, o Ollama continua a ser o caminho mais rápido (já explicámos isso no nosso guia de instalação do Ollama). Se está a construir um produto que precisa de servir muitos utilizadores em simultâneo com baixa latência, ou quer alojar o próprio DeepSeek-V4-Flash em vez de pagar por token à API oficial, o vLLM é a escolha documentada tanto pela DeepSeek como pela NVIDIA. O próprio repositório oficial do modelo no Hugging Face lista o comando vllm serve "deepseek-ai/DeepSeek-V4-Flash" como via de acesso suportada.

Duas técnicas explicam a maior parte do ganho de eficiência do vLLM face a um servidor de inferência ingénuo. A primeira é o paged attention, que gere a cache de atenção (KV cache) em blocos de memória, à semelhança da paginação de memória virtual num sistema operativo, evitando desperdício quando pedidos têm comprimentos diferentes. A segunda é o batching contínuo, que permite ao servidor juntar novos pedidos a um lote já em execução em vez de esperar que o lote anterior termine por completo. Para um modelo Mixture-of-Experts como o DeepSeek-V4-Flash, em que só 13 mil milhões dos 284 mil milhões de parâmetros são ativados por token, esta gestão eficiente de memória e de filas faz diferença real no número de pedidos simultâneos que uma mesma GPU consegue atender.

Pré-requisitos: hardware e versões de software

Antes de avançar, vale a pena ser honesto sobre o hardware. O DeepSeek-V4-Flash-0731 ocupa cerca de 160 GB em disco na sua precisão mista nativa FP4+FP8, e isso é só o peso do modelo, sem contar com a cache de contexto (KV cache). Os “recipes” de implementação publicados pela NVIDIA para este modelo específico apontam para clusters com 4 GPUs H200 (141 GB de VRAM cada, cerca de 564 GB agregados) ou 4 GPUs B200 (192 GB cada, cerca de 768 GB agregados) em configuração agregada, com opções ainda maiores em topologia desagregada para cargas agênticas mais pesadas.

Isto significa que a esmagadora maioria dos leitores vai alugar GPU na nuvem em vez de comprar hardware. É um caminho perfeitamente normal: fornecedores como RunPod, Lambda Labs ou Vast.ai disponibilizam instâncias com H200 por hora, e vamos falar de custos mais à frente. A lista de pré-requisitos de software é a seguinte:

  • Sistema operativo: Ubuntu 22.04 LTS ou 24.04 LTS (a maioria das imagens de cloud GPU já vem pronta)
  • Driver NVIDIA: versão 545 ou superior (recomenda-se 560+ para GPUs H200/B200)
  • CUDA: 12.2 ou superior, verificável com nvidia-smi
  • Docker Engine: versão 27 ou superior
  • NVIDIA Container Toolkit: última versão estável, necessária para o Docker conseguir ver as GPUs
  • Conta na Hugging Face com token de acesso e aceitação da licença do modelo
  • Pelo menos 200 GB de espaço em disco livre para a cache de pesos do modelo

Não precisa de instalar Python nem vLLM diretamente na máquina anfitriã. Tudo corre dentro do contentor oficial vllm/vllm-openai, o que poupa uma boa parte da dor de cabeça habitual com dependências CUDA. Isto também facilita a reprodutibilidade entre ambientes: a mesma imagem que testou no seu portátil com uma GPU alugada por uma hora é exatamente a mesma que vai correr no servidor de produção semanas depois, sem surpresas de versões de bibliotecas Python desalinhadas entre máquinas diferentes.

Passo 1: Escolher a infraestrutura de GPU

Antes de tocar em Docker, decida onde vai correr isto. Há três caminhos práticos:

  1. Cloud GPU por hora (RunPod, Lambda Labs, Vast.ai): a opção mais acessível para testar sem compromisso, com instâncias H200 a rondar os $4,3/hora em modelos “on-demand”, segundo dados de mercado da RunPod, com preços “spot” a partir de cerca de $1,3/hora consoante disponibilidade.
  2. Servidor dedicado com GPUs próprias: só faz sentido para quem já tem hardware H100/H200/B200 disponível, tipicamente em contexto empresarial.
  3. Modelo menor via llama.cpp para desenvolvimento local: se só quer validar o fluxo de trabalho num portátil com uma GPU de consumo, use uma variante GGUF quantizada (falamos disso na secção de dicas avançadas), sabendo que não vai obter o desempenho nem as capacidades completas do V4-Flash.

Para este tutorial, vamos assumir uma instância cloud com pelo menos 4 GPUs H200 e Ubuntu já instalado, o cenário documentado oficialmente para este modelo.

Passo 2: Instalar o Docker Engine e o NVIDIA Container Toolkit

Ligue-se por SSH à instância e instale o Docker Engine seguindo o pacote oficial da distribuição. Depois, instale o NVIDIA Container Toolkit, o componente que permite ao Docker expor GPUs físicas dentro dos contentores:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Depois de reiniciar o Docker, confirme que o driver está a funcionar corretamente correndo nvidia-smi diretamente na máquina anfitriã. Deve ver a listagem das GPUs, a versão do driver e a versão de CUDA suportada no canto superior direito da tabela.

Passo 3: Validar que o Docker consegue ver as GPUs

Este passo poupa horas de frustração mais à frente. Corra o seguinte comando para confirmar que um contentor consegue aceder às GPUs através do runtime NVIDIA:

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Se a saída mostrar a mesma tabela de GPUs que viu na máquina anfitriã, está tudo pronto. Se receber um erro do tipo could not select device driver "" with capabilities: [[gpu]], o NVIDIA Container Toolkit não ficou corretamente configurado como runtime padrão do Docker – volte ao passo anterior e confirme o resultado de nvidia-ctk runtime configure.

Passo 4: Criar o token de acesso na Hugging Face

Os pesos oficiais do DeepSeek-V4-Flash estão publicados no repositório deepseek-ai/DeepSeek-V4-Flash no Hugging Face. Crie uma conta, gere um token de acesso com permissão de leitura em Settings → Access Tokens, e aceite os termos de licença na página do modelo (a DeepSeek publica os pesos sob licença permissiva, mas o Hugging Face ainda exige o clique de aceitação por conta).

Guarde o token como variável de ambiente na sua instância:

export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
mkdir -p ~/.cache/huggingface

A pasta de cache vai ser montada dentro do contentor para que o download dos ~160 GB de pesos não se perca sempre que o contentor reinicia.

Passo 5: Fazer pull da imagem oficial do vLLM

A documentação oficial do vLLM publica três imagens Docker consoante o fabricante da GPU: vllm/vllm-openai para NVIDIA/CUDA, vllm/vllm-openai-rocm para AMD e vllm/vllm-openai-xpu para Intel. Como estamos a usar GPUs NVIDIA, vamos com a primeira:

docker pull vllm/vllm-openai:latest

Esta imagem já traz o vLLM, os kernels de atenção otimizados e as dependências CUDA necessárias. Não precisa de instalar mais nada na máquina anfitriã além do driver e do Container Toolkit dos passos 2 e 3. Pode confirmar que a imagem existe consultando a página oficial da organização vLLM no Docker Hub.

Passo 6: Lançar o servidor vLLM com o DeepSeek-V4-Flash

Com a imagem já em cache, é hora de subir o servidor. Este comando lança o servidor OpenAI-compatible do vLLM com paralelismo tensorial em 4 GPUs, um comprimento de contexto reduzido para 128 mil tokens (bem abaixo do limite teórico de 1 milhão, para poupar memória) e 90% da VRAM disponível reservada para pesos e cache:

docker run --gpus all --rm -d \
  --name deepseek-v4-flash \
  -p 8000:8000 \
  --shm-size 16g \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HF_TOKEN=$HF_TOKEN \
  vllm/vllm-openai:latest \
  --model deepseek-ai/DeepSeek-V4-Flash \
  --port 8000 \
  --tensor-parallel-size 4 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.9

O download inicial dos pesos demora bastante (estamos a falar de ~160 GB), por isso acompanhe os logs com docker logs -f deepseek-v4-flash antes de assumir que algo está mal. Só quando os logs mostrarem a linha Uvicorn running on http://0.0.0.0:8000 é que o servidor está pronto a atender pedidos.

Passo 7: Testar a API compatível com OpenAI

Com o contentor a correr, teste o endpoint diretamente com curl:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash",
    "messages": [{"role": "user", "content": "Explica o que é Mixture-of-Experts em duas frases."}]
  }'

Uma resposta com sucesso devolve um JSON no formato padrão da OpenAI, com o texto gerado dentro de choices[0].message.content. Um exemplo de saída (truncado):

{
  "id": "chatcmpl-8f3a2b1c",
  "object": "chat.completion",
  "model": "deepseek-ai/DeepSeek-V4-Flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Mixture-of-Experts é uma arquitetura onde só uma fração dos parâmetros do modelo é ativada por token..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 14, "completion_tokens": 62, "total_tokens": 76}
}

Para testar a partir de Python, use a própria biblioteca openai, apenas apontando o base_url para o seu servidor local:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="não-necessária")

resposta = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash",
    messages=[{"role": "user", "content": "Resume em português o que muda no V4-Flash-0731."}],
)
print(resposta.choices[0].message.content)

Passo 8: Empacotar tudo num docker-compose.yml

Para produção, é mais prático gerir o serviço com Docker Compose em vez de comandos manuais. Crie um ficheiro docker-compose.yml:

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: deepseek-v4-flash
    restart: unless-stopped
    shm_size: "16gb"
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    environment:
      - HF_TOKEN=${HF_TOKEN}
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model deepseek-ai/DeepSeek-V4-Flash
      --port 8000
      --tensor-parallel-size 4
      --max-model-len 131072
      --gpu-memory-utilization 0.9

Suba o serviço com docker compose up -d. A opção restart: unless-stopped garante que, se a instância reiniciar, o servidor volta a subir sozinho sem precisar de reintroduzir os comandos manualmente.

Passo 9: Ajustar os parâmetros de desempenho

Três flags controlam a maior parte do comportamento de memória e desempenho do vLLM. Vale a pena perceber cada uma antes de as alterar às cegas:

FlagO que controlaEfeito de subir o valor
--tensor-parallel-sizeNúmero de GPUs entre as quais o modelo é divididoMais GPUs ativas, mais VRAM total disponível, mas exige que o valor corresponda ao número de GPUs visíveis
--max-model-lenComprimento máximo de contexto (tokens) que o servidor aceitaMais contexto disponível, mas cresce o consumo de VRAM da KV cache de forma proporcional
--gpu-memory-utilizationFração da VRAM de cada GPU reservada para o vLLMMais margem para pesos e cache, mas menos folga para outros processos na mesma GPU

Se receber erros de memória insuficiente, a primeira coisa a tentar é baixar --max-model-len antes de assumir que precisa de mais GPUs. O contexto de 1 milhão de tokens documentado pela DeepSeek é o limite teórico do modelo, não uma obrigação de configuração – a maioria das aplicações reais funciona bem com 32 mil a 128 mil tokens de contexto.

Passo 10: Colocar um proxy reverso à frente da API

O servidor vLLM, por padrão, não tem autenticação nem TLS. Nunca exponha a porta 8000 diretamente à internet. Coloque um proxy reverso como Caddy ou Nginx à frente, com um certificado TLS e uma verificação simples de cabeçalho de autenticação. Um exemplo mínimo com Caddy:

seu-dominio.exemplo.pt {
  reverse_proxy localhost:8000 {
    header_up Authorization {header.Authorization}
  }
}

Depois, valide os pedidos recebidos com um middleware simples (numa aplicação intermédia em Node.js, Python ou no próprio Caddy com um plugin) antes de os reencaminhar para o vLLM. Isto evita que qualquer pessoa com o endereço IP do seu servidor consiga consumir a sua GPU alugada de graça.

Passo 11: Ativar autenticação nativa com –api-key

Além do proxy reverso, o próprio vLLM aceita uma flag --api-key que obriga todos os pedidos a incluírem um cabeçalho Authorization: Bearer <chave> correto, rejeitando com erro 401 quem não o enviar. É a forma mais simples de acrescentar uma primeira camada de proteção sem montar infraestrutura extra:

docker run --gpus all --rm -d \
  --name deepseek-v4-flash \
  -p 8000:8000 \
  --shm-size 16g \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HF_TOKEN=$HF_TOKEN \
  vllm/vllm-openai:latest \
  --model deepseek-ai/DeepSeek-V4-Flash \
  --port 8000 \
  --tensor-parallel-size 4 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.9 \
  --api-key "$(openssl rand -hex 24)"

Guarde a chave gerada num gestor de segredos (Vault, AWS Secrets Manager, ou mesmo um ficheiro .env fora do controlo de versões) e distribua-a apenas às aplicações que precisam de consumir a API. Combine sempre esta flag com o proxy reverso e TLS do passo anterior: o --api-key protege contra acesso não autorizado, mas não cifra o tráfego por si só.

Streaming de respostas token a token

Para aplicações de chat, esperar pela resposta completa antes de mostrar qualquer texto ao utilizador dá uma sensação de lentidão, mesmo quando o servidor está rápido. O endpoint do vLLM suporta streaming via Server-Sent Events, exatamente como a API da OpenAI, bastando definir "stream": true no pedido:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="a-sua-chave")

stream = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash",
    messages=[{"role": "user", "content": "Escreve um haiku sobre Lisboa."}],
    stream=True,
)

for pedaco in stream:
    delta = pedaco.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Cada pedaço chega assim que é gerado, em vez de esperar pela resposta inteira. Para uma interface web, isto traduz-se em texto a aparecer palavra a palavra, tal como acontece no ChatGPT ou no Claude, e é normalmente o comportamento esperado por qualquer utilizador habituado a assistentes de IA modernos.

Passo 12: Monitorizar o servidor com as métricas do vLLM

O vLLM expõe um endpoint /metrics no formato Prometheus, com dados como número de pedidos em fila, tempo de geração por token e utilização da cache. Aponte um Prometheus já existente para http://localhost:8000/metrics e construa um dashboard no Grafana para acompanhar latência e throughput ao longo do tempo. Isto é especialmente útil quando está a pagar por hora numa GPU alugada: uma GPU subutilizada durante a noite é dinheiro parado.

Passo 13: Parar, atualizar e remover o contentor em segurança

Para parar o serviço sem perder a cache de pesos já descarregada:

docker compose down
# a pasta ~/.cache/huggingface mantém os pesos para o próximo arranque

Quando a DeepSeek publicar uma nova revisão do modelo, basta fazer docker pull vllm/vllm-openai:latest para atualizar a engine e apagar a pasta de cache específica do modelo antigo se quiser forçar um novo download dos pesos mais recentes.

Hardware e custos: quanto isto realmente custa

Esta é provavelmente a pergunta mais prática de todas. Os “recipes” oficiais de implementação da NVIDIA para o DeepSeek-V4-Flash com vLLM definem várias topologias consoante a carga esperada:

ConfiguraçãoGPUsVRAM agregada aproximadaCenário indicado
Agregada, H2004× H200 (141 GB cada)~564 GBServiço padrão, cargas agênticas moderadas
Agregada, B2004× B200 (192 GB cada)~768 GBMaior margem de contexto e concorrência
Desagregada, H200 (4P3D)28× H200~3.948 GBCargas agênticas pesadas em escala, prefill/decode separados
Desagregada, B200 (2P1D)12× B200~2.304 GBAlto throughput com menos nós que a topologia H200

Para a maioria dos projetos pequenos e médios, a configuração agregada com 4 GPUs é o ponto de partida realista. Ao preço praticado pela RunPod para instâncias H200 sob procura (cerca de $4,3 por GPU/hora), quatro GPUs H200 durante um mês inteiro em funcionamento contínuo custam uma fatura considerável – o que reforça a importância de desligar o contentor fora de horas de utilização ou de usar instâncias “spot”, que segundo dados de mercado chegam a ficar por cerca de $1,3 por GPU/hora consoante disponibilidade e fornecedor.

Antes de comprometer o orçamento com uma configuração de 4 GPUs, vale a pena testar durante algumas horas com uma instância “on-demand” mais pequena para validar o fluxo completo (download dos pesos, arranque do contentor, testes de carga) antes de mudar para reserva mais longa ou capacidade “spot”. Muitos fornecedores de cloud GPU cobram por minuto ou por segundo, o que torna esta fase de validação relativamente barata mesmo em GPUs de topo. Só depois de confirmar que a configuração funciona de ponta a ponta é que faz sentido negociar preços de reserva mensal ou de longo prazo, tipicamente mais baratos do que o preço “on-demand” à hora.

vLLM vs Ollama vs LM Studio: qual escolher

Já cobrimos o Ollama e o LM Studio em tutoriais anteriores, por isso aqui fica um resumo direto de quando cada ferramenta faz sentido:

FerramentaPúblico-alvoHardware típicoPonto forte
vLLMEquipas que alojam um serviço com múltiplos utilizadores em simultâneo1 a dezenas de GPUs de datacenterThroughput elevado, paralelismo tensorial, API compatível com OpenAI pronta para produção
OllamaUtilizador individual, prototipagem rápidaUm portátil ou desktop com GPU de consumoInstalação em minutos, gestão de modelos por linha de comandos simples
LM StudioUtilizador não-técnico que quer uma interface gráficaUm portátil ou desktop com GPU de consumoInterface visual, sem necessidade de terminal

Na prática, muitas equipas usam as duas coisas: Ollama ou LM Studio no portátil do programador durante o desenvolvimento, e vLLM no servidor quando a aplicação vai para produção com utilizadores reais a bater na API.

Há ainda uma diferença relevante na forma como cada ferramenta lida com formatos de modelo. O Ollama e o LM Studio trabalham sobretudo com pesos convertidos para o formato GGUF, otimizado para correr eficientemente em CPU e em GPUs de consumo com menos VRAM, muitas vezes através do llama.cpp por baixo do capô. O vLLM, pelo contrário, foi construído à volta dos formatos nativos publicados pelos próprios laboratórios de IA (safetensors em precisão mista, como o FP4+FP8 do DeepSeek-V4-Flash), o que evita uma camada extra de conversão mas exige mais VRAM disponível. Se já tem um pipeline a correr com pesos GGUF e só precisa de mais throughput, vale a pena confirmar primeiro se a sua carga de trabalho justifica mesmo a migração para vLLM antes de refazer toda a infraestrutura.

Erros comuns ao autoalojar o DeepSeek-V4-Flash

A maioria dos problemas ao autoalojar um modelo deste tamanho não vem de bugs no vLLM em si, mas de configurações que assumem hardware ou memória que a instância não tem. Estes são os erros que mais frequentemente fazem as pessoas desistirem antes de terem o servidor a funcionar:

  • Definir --tensor-parallel-size diferente do número de GPUs visíveis no contentor. Se o contentor só vê 2 GPUs mas o flag pede 4, o vLLM falha logo no arranque com um erro de inicialização de comunicação entre processos.
  • Usar --max-model-len perto do limite teórico de 1 milhão de tokens numa configuração pequena. A cache de contexto em FP8 cresce proporcionalmente e esgota a VRAM disponível mesmo antes de processar o primeiro pedido real.
  • Esquecer o token da Hugging Face ou não aceitar a licença do modelo na página do repositório. O download falha silenciosamente com um erro de autorização 401, não com uma mensagem óbvia sobre a licença.
  • Expor a porta 8000 diretamente à internet sem proxy nem autenticação. Qualquer pessoa que descubra o IP consegue consumir a GPU alugada sem limites.
  • Não montar a pasta de cache do Hugging Face como volume persistente. Cada reinício do contentor obriga a repetir o download de ~160 GB de pesos, o que desperdiça tempo e largura de banda.
  • Ignorar o parâmetro --shm-size ao correr em Docker. O valor por padrão do Docker (64 MB) é demasiado pequeno para comunicação entre processos em cargas multi-GPU, e o sintoma costuma ser um crash silencioso ou uma mensagem confusa sobre memória partilhada, não um erro óbvio sobre o tamanho da shared memory.

Dicas avançadas

Se o orçamento não permite alugar 4 GPUs H200 mas quer mesmo assim experimentar o fluxo de trabalho do V4-Flash num único GPU de consumo, existem variantes GGUF quantizadas publicadas pela comunidade no Hugging Face para uso com o llama.cpp em vez do vLLM. Note que estas variantes não são o caminho de serviço oficial recomendado pela DeepSeek para produção e vão ter throughput e capacidade de contexto muito inferiores às configurações completas descritas neste tutorial – servem sobretudo para aprender o fluxo antes de escalar para um servidor real.

Outra dica prática: use docker stats em paralelo com nvidia-smi -l 2 enquanto testa a carga do servidor, para perceber em tempo real se o gargalo está na CPU, na VRAM ou na largura de banda entre GPUs. E se estiver a pensar em multi-nó (várias máquinas físicas, não só várias GPUs na mesma máquina), tenha em atenção o mapeamento de rede entre GPU e placa de rede – a NVIDIA documenta explicitamente a variável VLLM_GPU_NIC_PCIE_MAPPING nos seus recipes para topologias desagregadas, e configurá-la mal não dá erro, só degrada o throughput silenciosamente.

Por fim, mantenha um registo de qual revisão exata do modelo está a servir. Como a DeepSeek publica atualizações rotuladas por data (a exemplo de “0731” para a revisão de 31 de julho), é boa prática fixar o hash de commit do repositório Hugging Face em vez de confiar apenas no nome curto do modelo, sobretudo em produção. Isto evita que uma atualização silenciosa dos pesos no repositório altere o comportamento do seu serviço sem aviso, algo particularmente importante se a sua aplicação depende de respostas consistentes ao longo do tempo para testes automatizados ou auditorias internas.

Resolução de problemas

Uma checklist rápida para os problemas mais comuns, do arranque ao dia a dia em produção:

  • “CUDA out of memory” no arranque: reduza --max-model-len e/ou --gpu-memory-utilization, ou confirme que tem VRAM agregada suficiente para as 4 GPUs configuradas.
  • “could not select device driver” ao correr o contentor: o NVIDIA Container Toolkit não está configurado como runtime padrão – repita sudo nvidia-ctk runtime configure --runtime=docker e reinicie o Docker.
  • Erro 401 durante o download dos pesos: o token da Hugging Face está incorreto, expirado, ou a licença do modelo ainda não foi aceite na página do repositório.
  • O contentor arranca mas fica preso sem avançar nos logs: normalmente é o download dos ~160 GB de pesos em curso – confirme com docker exec deepseek-v4-flash du -sh /root/.cache/huggingface se o tamanho está a crescer.
  • “no kernel image is available for execution on the device”: normalmente indica incompatibilidade entre o driver NVIDIA da máquina anfitriã e a versão de CUDA esperada pela imagem do vLLM – atualize o driver para 560+ e tente novamente.
  • Erros de comunicação entre processos (rank mismatch) no arranque com múltiplas GPUs: confirme que --tensor-parallel-size corresponde exatamente ao número de GPUs que o --gpus all está a expor ao contentor.
  • Respostas muito lentas mesmo com GPUs de sobra: verifique se --gpu-memory-utilization está demasiado baixo, o que limita o espaço para batching contínuo de pedidos.
  • API a responder mas a devolver erro 400 “model not found”: o campo model no pedido JSON tem de corresponder exatamente ao valor passado em --model no arranque do servidor.

Reduzir custos: desligar a GPU quando não está em uso

Como o custo de GPU cloud é cobrado por hora (ou por minuto, consoante o fornecedor), deixar quatro GPUs H200 ligadas 24 horas por dia sem tráfego real é a forma mais rápida de esvaziar o orçamento. Um script simples de cron que verifica se houve pedidos recentes ao endpoint /metrics e desliga a instância automaticamente fora de horas resolve boa parte do problema para cargas previsíveis, como um chatbot interno de equipa que só é usado durante o horário de expediente:

#!/bin/bash
# verifica se houve pedidos nos ultimos 30 minutos, senao para o servico
PEDIDOS=$(curl -s http://localhost:8000/metrics | grep -oP 'vllm:num_requests_running \K[0-9.]+')
if [ "${PEDIDOS:-0}" = "0" ]; then
  echo "Sem pedidos ativos, a parar o vLLM..."
  docker compose down
fi

Combine isto com um pequeno serviço de “wake-up” que arranca o contentor novamente assim que chega o primeiro pedido, aceitando alguns minutos de latência extra nesse arranque inicial em troca de poupança real na fatura. Para equipas com tráfego mais constante, esta otimização perde relevância e o foco deve estar antes em ajustar --gpu-memory-utilization e --max-model-len para maximizar o throughput por GPU já ligada.

Um projeto completo: chatbot interno com DeepSeek-V4-Flash

Para fechar o tutorial com algo funcional de ponta a ponta, aqui está um pequeno cliente Python que liga a um servidor vLLM já a correr e mantém histórico de conversa, útil como base para um chatbot interno de equipa:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="não-necessária")
historico = [{"role": "system", "content": "És um assistente técnico conciso, em português europeu."}]

def perguntar(mensagem):
    historico.append({"role": "user", "content": mensagem})
    resposta = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V4-Flash",
        messages=historico,
        temperature=0.3,
        max_tokens=512,
    )
    texto = resposta.choices[0].message.content
    historico.append({"role": "assistant", "content": texto})
    return texto

if __name__ == "__main__":
    while True:
        pergunta = input("Tu: ")
        if pergunta.lower() in ("sair", "exit"):
            break
        print("DeepSeek:", perguntar(pergunta))

Este script já cobre o essencial: histórico de conversa, ligação ao endpoint local e um ponto de partida para adicionar autenticação, streaming de resposta token a token, ou uma interface web por cima com Streamlit ou um frontend em React. A partir daqui, o passo seguinte natural é adicionar o proxy reverso do passo 10 e distribuir o acesso pela equipa em vez de o correr só em localhost.

Perguntas frequentes

Preciso mesmo de 4 GPUs para correr o DeepSeek-V4-Flash?
Para a configuração oficial documentada pela NVIDIA com vLLM, sim – os recipes de implementação assumem 4 GPUs H200 ou B200 na topologia agregada. Para experimentação num único GPU de consumo, tem de recorrer a variantes GGUF quantizadas via llama.cpp, com desempenho e contexto reduzidos.

Posso usar o vLLM com GPUs AMD?
Sim, a documentação oficial do vLLM publica a imagem vllm/vllm-openai-rocm especificamente para GPUs AMD com ROCm.

Qual é a diferença entre o DeepSeek-V4-Flash e o DeepSeek-V4-Pro?
O V4-Flash tem 284 mil milhões de parâmetros totais e 13 mil milhões ativos, otimizado para custo e velocidade. O V4-Pro é o modelo “flagship” com cerca de 1,6 biliões de parâmetros totais, lançado oficialmente a 13 de agosto de 2026, com preço significativamente mais elevado via API.

A API do vLLM é mesmo compatível com o SDK da OpenAI?
Sim, o servidor expõe os endpoints /v1/chat/completions e equivalentes no formato exato usado pela OpenAI, por isso qualquer código já escrito com o SDK oficial da OpenAI funciona apenas trocando o base_url.

O que acontece se eu não definir --gpu-memory-utilization?
O vLLM assume um valor padrão conservador, mas em modelos deste tamanho é boa prática defini-lo explicitamente para controlar quanta margem fica livre para outros processos na mesma GPU.

Consigo correr isto sem Docker, diretamente com pip?
Sim, o comando pip install vllm seguido de vllm serve "deepseek-ai/DeepSeek-V4-Flash" funciona sem contentores, mas perde-se o isolamento de dependências CUDA que o Docker garante, o que costuma gerar mais problemas de compatibilidade em servidores partilhados.

Quanto tempo demora o download inicial dos pesos?
Depende inteiramente da largura de banda da instância, mas com ~160 GB para transferir, mesmo em ligações rápidas de datacenter é normal demorar entre 20 a 60 minutos na primeira vez.

Vale a pena autoalojar em vez de usar a API oficial da DeepSeek?
Depende do volume. Para uso esporádico, a API paga por token costuma sair mais barata do que alugar GPUs por hora, através da própria documentação da API DeepSeek. Para tráfego elevado e constante, ou para requisitos de privacidade de dados que impedem enviar prompts para uma API externa, autoalojar com vLLM tende a compensar a médio prazo.

O que é o parâmetro --shm-size e porque preciso dele?
É a quantidade de memória partilhada que o Docker atribui ao contentor, usada pela comunicação interna entre processos durante o paralelismo tensorial. O valor por padrão do Docker (64 MB) é demasiado baixo para modelos deste tamanho; 16 GB é um ponto de partida seguro para uma configuração de 4 GPUs.

Consigo migrar este setup para Kubernetes mais tarde?
Sim. A mesma imagem vllm/vllm-openai corre dentro de um pod Kubernetes sem alterações, bastando adaptar os equivalentes de --gpus all e dos volumes para os recursos nativos do Kubernetes (device plugin da NVIDIA e PersistentVolumeClaims). É o caminho natural quando a equipa cresce e precisa de escalar automaticamente consoante a carga.