Qwen3-VL localmente: o modelo de visão de referência com Ollama

#Por que usar o Qwen3-VL localmente

Um modelo de visão e linguagem (VLM) aceita tanto texto quanto imagens como entrada. Você mostra a ele uma foto, uma captura de tela ou uma imagem digitalizada e faz uma pergunta sobre ela em linguagem natural. O Qwen3-VL, desenvolvido pela equipe Qwen da Alibaba, se consolidou como a referência entre os modelos de pesos abertos para esse uso: combina uma boa compreensão visual, um OCR multilíngue robusto (incluindo o francês) e um raciocínio sólido sobre o que vê.

A vantagem de rodá-lo localmente é a mesma de qualquer LLM auto-hospedado, mas aqui ela tem ainda mais peso: as imagens que você analisa são frequentemente sensíveis — capturas de tela de trabalho, documentos administrativos, fotos de faturas, documentos de identidade. Com Qwen3-VL na sua máquina, nada sai do seu disco. Sem upload para a nuvem, sem cota de uso, sem assinatura.

Privacidade

As imagens permanecem na sua máquina. Ideal para documentos de RH, médicos, jurídicos ou qualquer digitalização pessoal.

Sem custo de uso

Nenhum custo por imagem nem por token. Você processa 10 ou 10 000 capturas sem uma conta que aumenta.

Offline

Depois que o modelo for baixado, tudo funciona sem conexão com a internet.

Automatizável

A API do Ollama compatível com a da OpenAI permite automatizar o processamento de imagens em massa com scripts em Python ou shell.

#Requisitos e VRAM necessária

Um VLM consome mais recursos do que um modelo de texto de tamanho equivalente: além dos pesos do modelo de linguagem, ele carrega um codificador visual e precisa processar os “tokens de imagem” gerados por cada foto. Uma imagem de alta resolução pode representar vários milhares de tokens, o que consome contexto e memória durante a inferência. Reserve, portanto, uma margem de VRAM além do tamanho dos pesos.

Com quantização Q4_K_M (o melhor equilíbrio entre qualidade e memória para a maioria dos usos), veja as referências de consumo de memória conforme o tamanho do modelo de linguagem subjacente. Adicione ~1 a 2 GB para o codificador visual e o processamento de imagens.

Variante de ~3-4B

≈ 2–3 GB de VRAM. Cabe em uma RTX 3060 de 12 GB sem esforço, ou em um Mac com chip da série M e 16 GB. O ponto de entrada para visão local.

Variante de ~7–8B

≈ 5-6 GB de VRAM. Confortável em uma RTX 3060/4070 de 12 GB ou RTX 4080 de 16 GB. A melhor relação entre qualidade e recursos para uso diário.

Variante ~30-32B

≈ 19-20 GB de VRAM. Indicada para uma RTX 4090 de 24 GB, uma placa profissional ou um Mac com bastante memória unificada (M4 Pro/Max com 32 GB ou mais).

No lado do software, você precisa ter o Ollama instalado (o daemon escuta por padrão em http://localhost:11434) e de uma versão recente compatível com entrada multimodal. Uma interface como Open WebUI ou LM Studio torna o envio de imagens mais confortável do que pela linha de comando, mas não é obrigatória.

#Escolher a variante certa de acordo com a VRAM

O Qwen3-VL está disponível em vários tamanhos. O bom hábito não é escolher a maior variante que sua máquina consegue tecnicamente carregar, mas aquela que deixa margem para o contexto e o processamento de imagens. Veja como decidir.

1. 01
   Você tem 8-12 GB de VRAM

   Comece com uma variante de 3-4B em Q4_K_M. Ela descreve corretamente uma imagem, realiza OCR em texto nítido e responde rapidamente. Suficiente para a maioria dos usos simples (descrição, extração de texto).
2. 02
   Você tem de 12 a 16 GB de VRAM

   Opte por uma variante 7-8B em Q4_K_M ou Q5_K_M. É o ponto ideal: muito melhor em documentos complexos, tabelas e raciocínio visual, mantendo a fluidez.
3. 03
   Você tem 24 GB de VRAM ou um Mac com bastante memória

   Uma variante de 30–32B em Q4_K_M permite alcançar a melhor qualidade disponível localmente: leitura confiável de documentos densos, tabelas com várias colunas e raciocínio refinado sobre diagramas. É aí que a diferença em relação à nuvem mais diminui.
4. 04
   Na dúvida

   Comece com a variante 7-8B. Se a qualidade for suficiente, você terá economizado VRAM; se ela atingir seu limite ao lidar com seus documentos, passe para uma variante maior.

#Instalar o Qwen3-VL com Ollama

A instalação é feita com apenas um comando. Ollama baixa o modelo da sua biblioteca, incluindo o codificador visual, e o torna disponível para inferência. Substitua a tag pela variante escolhida na etapa anterior.

# Télécharger la variante (exemple ~8B ; adaptez le tag à votre VRAM)
ollama pull qwen3-vl:8b

# Lancer une session interactive
ollama run qwen3-vl:8b

# Vérifier ce qui est chargé et sur quel matériel (GPU/CPU)
ollama ps

Uma vez na sessão interativa, enviar uma imagem é feito informando seu caminho no prompt. Ollama detecta o caminho do arquivo, codifica a imagem e a adiciona ao contexto. Depois, você pode fazer quantas perguntas quiser sobre ela.

>>> Décris cette image en détail : /home/moi/captures/dashboard.png

>>> Quel est le chiffre affiché en haut à droite ?

>>> Y a-t-il une alerte visible ? Résume-la.

#Descrever imagens e capturas de tela

Este é o caso de uso mais imediato. O Qwen3-VL descreve o conteúdo de uma foto, identifica objetos, lê textos presentes na imagem e raciocina sobre o que observa. Para capturas de tela — interfaces, dashboards, mensagens de erro — ele é particularmente útil: lê a UI, identifica os elementos e pode explicar o que está sendo exibido.

Descrição geral

« O que mostra essa imagem? » — inventário de elementos, atmosfera, contexto. Útil para adicionar tags às fotos ou classificá-las.

Leitura de captura de tela

Interpretar um dashboard, transcrever uma mensagem de erro, explicar uma interface desconhecida a partir de uma captura de tela.

Extração direcionada

“Qual é o valor total?”, “Liste os nomes visíveis” — o modelo isola a informação solicitada em vez de descrever tudo.

Perguntas de acompanhamento

Depois que a imagem estiver no contexto, continue fazendo perguntas sem reenviá-la. O modelo mantém a referência visual.

#Ler documentos digitalizados e tabelas

O OCR e a compreensão de documentos são onde o Qwen3-VL realmente se destaca e justificam a migração para uma variante 7-8B ou superior. Ele não se limita a transcrever o texto: entende a estrutura (títulos, colunas, caixas), o que permite extrair dados de uma tabela ou formulário em um formato organizado.

Fatura ou recibo digitalizado

Extrair fornecedor, data, valor sem/com impostos, linhas de itens — e solicitar uma saída em JSON diretamente utilizável.

Tabela em imagem

Reconstruir uma tabela capturada em foto no formato Markdown ou CSV, preservando as linhas e colunas.

Documento manuscrito

O OCR lida com texto impresso sem dificuldade; os resultados com texto manuscrito são mais incertos, mas ele funciona quando a letra é clara.

Formulário administrativo

Identificar os campos preenchidos e seus valores, incluindo as caixas marcadas.

>>> Voici un tableau scanné : /home/moi/docs/tableau-ventes.png
... Reproduis-le exactement au format Markdown, sans rien ajouter
... ni interpréter. Conserve toutes les colonnes et l'ordre des lignes.

#Automatizar via a API

Para processar imagens em massa — organizar uma pasta de capturas de tela, extrair dados de dezenas de faturas — a API do Ollama permite automatizar tudo isso com scripts. O Ollama expõe uma API compatível com a OpenAI na porta 11434, com a imagem enviada codificada em base64. Aqui está um exemplo mínimo em Python.

import base64
import requests

with open("facture.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post("http://localhost:11434/api/generate", json={
    "model": "qwen3-vl:8b",
    "prompt": "Extrais fournisseur, date et montant TTC au format JSON.",
    "images": [img_b64],
    "stream": False,
})

print(resp.json()["response"])

A partir daí, um simples laço que percorre uma pasta permite processar um lote inteiro de imagens e agregar os resultados. Como a inferência é local, não se aplica nenhum limite de taxa de requisições: a única restrição é a velocidade da sua GPU.

#O que a visão local ainda não consegue fazer

Vamos ser honestos: o Qwen3-VL executado localmente é excelente, mas ainda há diferenças em relação aos melhores modelos de visão na nuvem, e há tarefas nas quais é preciso reduzir as expectativas. Conhecer essas limitações evita surpresas desagradáveis.

Pequenos detalhes e baixa resolução

Em uma imagem borrada, muito densa ou de baixa resolução, o OCR falha. Uma digitalização nítida e bem enquadrada muda tudo. O modelo não "adivinha" o que não vê claramente.

Contagem precisa

Contar exatamente muitos objetos idênticos (“quantas pessoas há nesta foto?”) continua pouco confiável além de alguns elementos. Essa é uma limitação conhecida dos VLMs.

Raciocínio espacial preciso

Posições relativas exatas, medidas, geometria precisa: o modelo fornece uma ideia, não uma resposta metrológica.

Vídeo e tempo real

Ollama processa imagens estáticas. A análise de vídeo exige que você faça a divisão em frames, sem compreensão temporal nativa.

Alucinações visuais

Como qualquer LLM, ele pode afirmar ver um elemento ausente, especialmente se sua pergunta sugerir sua presença. Faça perguntas neutras, sem induzir a resposta.

#Solução de problemas

«Arquivo não encontrado» em uma imagem existente

Caminho relativo resolvido incorretamente. Forneça o caminho absoluto completo. No Windows, use barras (C:/...).

Resposta lenta ou aos solavancos

O modelo excede a capacidade da VRAM e parte dele roda no CPU. Verifique com ollama ps; se for o caso, escolha uma variante menor ou uma quantização de menor precisão.

OCR medíocre

Imagem de resolução muito baixa ou quantização excessivamente agressiva. Forneça uma digitalização mais nítida e use no mínimo Q4_K_M.

O modelo ignora a imagem

Você pode ter carregado por engano uma variante de texto do Qwen. Certifique-se de que a tag contenha -vl e de que sua versão do Ollama tenha suporte à multimodalidade.

Out of memory ao carregar

A variante excede sua VRAM. Passe para um tamanho menor — lembre-se de adicionar uma margem para o encoder visual e os tokens de imagem.

# Le modèle est-il bien chargé et sur GPU ?
ollama ps

# Lister les modèles vision installés
ollama list

# Tester l'API en local
curl http://localhost:11434/api/tags

#Para se aprofundar

O Qwen3-VL usa o mesmo stack Ollama que o restante dos seus modelos locais. Estes guias dão continuidade natural à sua configuração de visão:

LLM multimodal com visão em execução local: analisar imagens com Ollama

O panorama dos VLM que podem ser auto-hospedados (Qwen-VL, Llama-Vision, Llama 4 Scout) para comparar e escolher de acordo com suas necessidades.

Instalar o Ollama: Windows, macOS e Linux

Se Ollama ainda não estiver instalado, o guia de instalação completo com os pré-requisitos de GPU.

Escolher sua quantização (Q4, Q5, Q8, FP16)

Para ajustar o consumo de memória da sua variante Qwen3-VL à VRAM disponível.