Moondream: o modelo de visão que cabe partout

#Uma família, não um modelo

Moondream é publicado pela M87 Labs. Seu criador original, Vikhyat Korrapati, o descreve no repositório GitHub como “a tiny vision language model that kicks ass and runs anywhere”. O nome Moondream designa hoje quatro variantes com características muito diferentes, e guias mais antigos frequentemente as confundem.

A diferença de escala muda a natureza dos usos. Um modelo com 2 bilhões de parâmetros pode rodar em um notebook sem placa dedicada ou em uma máquina embarcada. Um modelo com 9 bilhões de parâmetros, mesmo ativo apenas 2 por token, deve manter todos os pesos na memória: é por isso que a geração 3 exige dezenas de gigabytes, com um arquivo FP8 de 10,51 GB para a Preview. A documentação do Moondream especifica que um Mac mini M4 de base com 16 GB acolhe o Moondream 2, mas que os pesos do Moondream 3 ultrapassam sua memória unificada.

#O que ele sabe fazer

Os modelos Moondream oferecem habilidades nativas, com saídas estruturadas em vez de texto livre a interpretar. Segundo a ficha da versão 3.1, cada habilidade tem um contrato de saída fixo.

Query (responder a uma pergunta)

Pergunta em linguagem natural sobre a imagem, resposta livre. É a opção de uso geral. A ficha do modelo esclarece que não há uma medida de confiança calibrada: formule perguntas verificáveis.

Caption (descrever)

Legendas em três comprimentos: short, normal ou long. A ficha do modelo alerta que uma legenda longa troca recall por um maior risco de alucinação e que ela não deve ser analisada para extrair contagens nem coordenadas.

Detect (detectar)

Caixas delimitadoras para qualquer expressão, com coordenadas normalizadas entre 0 e 1 a partir do canto superior esquerdo. Até 200 caixas por chamada, limiar padrão de 0,30.

Point (apontar)

O centro de cada instância, até 64 pontos: mais econômico que uma caixa e adequado à contagem.

Segment (segmentar)

Uma máscara por objeto correspondente, até 50 instâncias; as pontuações de confiança não são fornecidas para as máscaras.

O Moondream 2 adquiriu essas capacidades em etapas. Seu registro de alterações, publicado pelo autor, menciona em março de 2025 a geração de legendas longas, a rotulagem com vocabulário aberto e uma contagem aprimorada (CountBenchQA de 80 para 86,4). Em abril de 2025, a leitura de documentos e gráficos avança (ChartQA de 74,8 para 77,5). Em junho de 2025, chega um modo de raciocínio ancorado, ativado por reasoning=True na habilidade query, que troca velocidade por precisão, além de uma geração de texto 20 a 40% mais rápida, segundo o autor. Esses números são do próprio autor, com base em suas próprias avaliações: use-os para situar a evolução, não para comparar com outro modelo.

Um detalhe de uso: o Moondream não trabalha com a imagem inteira, ele a divide em blocos. De acordo com sua FAQ, ele redimensiona a imagem para que uma grade de blocos de aproximadamente 378 × 378 pixels a cubra, com no máximo 12 blocos locais mais uma visão global, totalizando cerca de 1,7 milhão de pixels para os blocos locais. A ficha da versão 3.1 confirma uma divisão adaptativa em no máximo 12 blocos, para imagens PNG, JPEG ou WebP com até 4.096 pixels no lado maior. Uma foto de 12 megapixels é, portanto, bastante reduzida antes da análise: para ler um detalhe, recorte primeiro a área.

#O que consome

Esses números são os da página dos modelos do Moondream: o contexto importa, pois se trata de uma placa RTX 3090, com int4 e compile(), e da velocidade de geração de texto, não do tempo por imagem. O tempo por imagem depende do tamanho da saída e do número de tiles. A mesma página afirma que a quantização int4 reduz o uso de memória em 42% com perda de precisão de 0,6%, sem especificar a avaliação; considere isso uma declaração do desenvolvedor.

Para a geração 3.1, o hardware compatível com o motor Photon é uma placa NVIDIA Ampere ou mais recente com Linux ou Windows, ou um Mac Apple Silicon com macOS 13 ou posterior, com Python 3.10 a 3.14. A ficha do modelo também indica NVIDIA SM75 ou superior, com pelo menos 10 GB de VRAM, uma versão GGUF para processadores x86 ou ARM e MLX para Apple Silicon. Por fim, a documentação lista placas Jetson, incluindo a Jetson Orin Nano de 8 GB, entre as plataformas compatíveis.

• VRAM: o que é e quanta é necessária para a IA

#Três formas de iniciá-lo

1. 01
   Com a biblioteca moondream e Photon

   Instale o pacote, depois carregue o modelo: os pesos são baixados do Hugging Face na primeira chamada, e nenhuma chave de API é necessária para os modelos de base, de acordo com a documentação. O Photon funciona apenas em GPU NVIDIA Ampere ou mais recente, ou em Mac com Apple Silicon.
2. 02
   Com Transformers

   O repositório vikhyatk/moondream2 é carregado com AutoModelForCausalLM. Especifique a revisão: o autor alerta que o modelo é atualizado frequentemente e recomenda fixar a versão em produção. A opção trust_remote_code=True executa código fornecido pelo repositório: ative-a apenas se você confiar na fonte.
3. 03
   Com Ollama

   A página do moondream no Ollama indica 1,7 GB, um contexto de 2 000 tokens e uma última atualização há dois anos, portanto anterior às versões de 2025 do Moondream 2. Ela não abrange as gerações 3. Verifique se oferece os recursos de que você precisa antes de adotá-la.

# pip install --upgrade moondream
import moondream as md
from PIL import Image

model = md.photon("moondream2")   # ou "moondream3.1-9B-A2B" avec une carte de 10 Go ou plus
image = Image.open("photo.jpg")

print(model.caption(image, length="short")["caption"])
print(model.query(image, "Combien de personnes sont visibles ?")["answer"])
for obj in model.detect(image, "casque")["objects"]:
    print(obj)

Lembre-se de que a habilidade detect retorna coordenadas normalizadas: multiplique-as pela largura e pela altura da imagem original para obter coordenadas em pixels.

• Panorama dos modelos multimodais executados localmente
• Fonte: a documentação oficial para execução local
• Fonte: a ficha do Moondream 2 no Hugging Face

#Os casos em que ele se destaca

1. 01
   Indexar uma biblioteca de fotos

   Gerar uma legenda por imagem para tornar um acervo de fotos pesquisável por texto. O custo por imagem determina a viabilidade, e é nesse ponto que um modelo pequeno leva vantagem. Use legendas curtas: as longas podem inventar detalhes.
2. 02
   Filtrar antes de enviar a um modelo grande

   Fazer uma triagem inicial para enviar ao modelo caro apenas as imagens que valem a pena. A capacidade point serve para contar, e a capacidade detect, para recortar automaticamente a área a ser analisada em seguida.
3. 03
   Descrever imagens para acessibilidade

   Produzir textos alternativos em lote em um site existente, localmente e sem enviar as imagens a um serviço de terceiros. Revise uma amostra: uma legenda continua sendo uma hipótese.
4. 04
   Monitorar um fluxo

   Fazer uma pergunta fechada sobre imagens sucessivas, em uma máquina modesta que funciona continuamente. O modelo de 0,5B foi projetado para receber ajuste fino para uma tarefa específica, o que melhora significativamente sua precisão segundo a M87 Labs.

Uma boa prática emerge da ficha da versão 3.1: faça perguntas fechadas e precisas. Um modelo pequeno responde bem a "há um capacete na cabeça da pessoa?" e se dispersa em "analise esta cena".

#O que não se deve pedir a ele

A ficha da versão 3.1 dedica uma seção inteira às suas limitações, o que é raro e precioso. Ela descreve os erros mais comuns na avaliação e os limiares que ela fornece servem de referência para os modelos da mesma família.

textos pequenos

Textos com tamanho inferior a cerca de 10 pixels na resolução do bloco de imagem costumam ser lidos incorretamente ou ignorados: primeiro recorte e amplie a área.

Pequenos objetos

Objetos com menos de 12 pixels no lado maior não são detectados por detect: use point em uma região recortada da imagem.

Cenas com muitos elementos

Acima de aproximadamente 50 instâncias, o recall cai e objetos adjacentes idênticos se fundem. Contagens acima de 50 são pouco confiáveis.

Leitura de texto desfocado

Em texto desfocado, estilizado ou parcialmente oculto, o modelo pode gerar uma sequência plausível, mas incorreta, sem sinal de baixa confiança. Para um documento completo, um motor de OCR é mais seguro.

Usos de alto impacto

Interpretação médica e decisões jurídicas ou financeiras com base em documentos, sem revisão humana, são declaradas fora do escopo. A saída de um modelo pequeno deve ser verificada.

• Para ler um documento escaneado, é necessário o OCR
• Qwen VL: visão local de alto nível

#Licenças: o que você pode fazer

Para indexar sua própria coleção de fotos ou descrever as imagens do seu site, nenhuma dessas licenças apresenta problema: o uso interno ou como componente de um produto é autorizado. A limitação se aplica apenas a quem quiser vender acesso ao próprio Moondream, por exemplo, por meio de uma API de visão de uso geral hospedada. Em caso de dúvida sobre uso comercial, o que prevalece é a licença, não este resumo.

#Moondream ou um grande modelo de visão

A pergunta a se fazer não é «qual é o melhor», mas «quantas imagens e para qual decisão». Poucas imagens por dia e perguntas abertas: use o maior modelo que sua placa suporta. Milhares de imagens e uma pergunta fechada repetida: um modelo pequeno torna o projeto possível.

Uma arquitetura em cascata combina os dois: o modelo pequeno processa tudo e sinaliza os casos interessantes, e o modelo grande intervém apenas nesses casos. Em um acervo grande, esse esquema oferece a melhor relação entre qualidade e tempo de processamento. A capacidade de detecção do Moondream atua então como filtro: ela recorta o objeto, e o modelo grande analisa a área recortada.

• Modelos multimodais locais com Ollama
• Qwen3-VL local
• PaddleOCR: o OCR que entende a página
• Fonte: o repositório GitHub do Moondream
• Fonte: a página dos modelos do Moondream

#FAQ