Como executar o Qwen2.5-VL e o Qwen3-VL localmente em 2026: guia de OCR de documentos e visão

Qual modelo de visão do Qwen você deve executar?

Tags do Ollama, tamanhos e licenças do Qwen3-VL e do Qwen2.5-VL

Requisitos de hardware para os modelos de visão do Qwen

• Os tamanhos de download são apenas os pesos: o Qwen3-VL 8B tem 6.2 GB e o Qwen2.5-VL 7B tem 6.0 GB. O cache de contexto e o codificador de imagens precisam de memória extra, que cresce com o tamanho do contexto e da imagem, então deixe folga acima do tamanho do download.
• Opções menores: Qwen3-VL 2B (1.9 GB) e 4B (3.3 GB) ou Qwen2.5-VL 3B (3.2 GB) servem para GPUs pequenas e notebooks; espere menos precisão do que nos modelos de 7B–8B.
• Opções maiores: Qwen3-VL 30B-A3B (20 GB), Qwen3-VL 32B e Qwen2.5-VL 32B (21 GB) e Qwen2.5-VL 72B (49 GB) exigem uma GPU grande, várias GPUs ou Apple Silicon com muita memória unificada.
• Offload parcial: quando um modelo não cabe na VRAM, o Ollama pode colocar parte dele na RAM do sistema; funciona, mas é bem mais lento.
• Software: Ollama 0.12.7+ para o Qwen3-VL e 0.7.0+ para o Qwen2.5-VL, conforme as páginas da biblioteca do Ollama.

Configurando o Qwen2.5-VL e o Qwen3-VL com o Ollama

1. 1
   Instalar ou atualizar o Ollama
   Why it matters: O Qwen2.5-VL exige Ollama 0.7.0 ou mais recente e o Qwen3-VL exige 0.12.7 ou mais recente. Verifique com `ollama --version` e atualize se necessário. O Ollama está disponível para macOS, Linux e Windows.
2. 2
   Baixar um modelo com uma tag explícita
   Why it matters: Use `qwen3-vl:8b` ou `qwen2.5vl:7b`. Não use `qwen2-vl:7b` — ele não está na biblioteca oficial do Ollama, então o download falha.
3. 3
   Executar o modelo e anexar uma imagem
   Why it matters: No modo interativo, digite o caminho do arquivo de imagem dentro do prompt. O Ollama detecta o caminho e carrega a imagem.
4. 4
   Enviar imagens pela API
   Why it matters: O endpoint /api/generate aceita um array `images` em base64 sem o prefixo data:. É assim que aplicações — e o PromptQuorum — enviam imagens de forma programática.
5. 5
   Verificar o OCR multilíngue
   Why it matters: Envie a digitalização de um documento em chinês ou japonês e compare o texto extraído com o original antes de construir em cima disso.

# Step 1 — Install or update Ollama (Qwen3-VL needs 0.12.7+, Qwen2.5-VL needs 0.7.0+)
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows — download from https://ollama.com/download
ollama --version

# Step 2 — Pull a Qwen vision model (explicit tag)
ollama pull qwen3-vl:8b          # 6.2 GB
# or: ollama pull qwen2.5vl:7b   # 6.0 GB

# Step 3 — Run and attach an image (interactive)
ollama run qwen3-vl:8b
>>> Extract every line of text from ./invoice-jp.png

# Step 4 — Send an image through the API
# Encode the image first:  base64 -i scan.png   (macOS)
curl http://localhost:11434/api/generate -d '{
  "model": "qwen3-vl:8b",
  "prompt": "Extract every line of text from this document. Preserve line breaks.",
  "images": ["<base64-encoded-image>"],
  "stream": false
}'

# Step 5 — Verify multilingual OCR
ollama run qwen3-vl:8b
>>> Extract all text from this image: ./contract-zh.png

Configurando os modelos de visão do Qwen com o LM Studio

1. 1
   Baixar e instalar o LM Studio
   Why it matters: Uma interface gráfica multiplataforma para inferência local de modelos. Não precisa de terminal.
2. 2
   Procurar os modelos de visão do Qwen
   Why it matters: Pesquise "Qwen3-VL" ou "Qwen2.5-VL" no navegador de modelos e escolha uma versão cuja ficha informe suporte a visão. Ajuste a quantização à sua memória.
3. 3
   Carregar o modelo e anexar uma imagem
   Why it matters: Use o botão de imagem na caixa de chat para enviar uma foto ou digitalização. O LM Studio a repassa ao codificador de visão.
4. 4
   Iniciar o servidor local
   Why it matters: A opção "Start Server" expõe uma API compatível com a OpenAI em localhost:1234. As requisições de visão usam o formato de conteúdo padrão image_url.

// LM Studio — OpenAI-compatible vision request (localhost:1234)
{
  "model": "<model-id-shown-in-LM-Studio>",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Extract all text from this document." },
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,<base64-encoded-image>" }
        }
      ]
    }
  ]
}

OCR de documentos em chinês, japonês e idiomas mistos

• Extração de texto simples: "Extraia cada linha de texto desta imagem. Preserve as quebras de linha e a ordem de leitura."
• Campos estruturados: "Esta é uma nota fiscal japonesa. Devolva fornecedor, data, subtotal, imposto e total como pares chave: valor."
• Extração de tabelas: "Extraia esta tabela como CSV. Trate a primeira linha como cabeçalho."
• Extrair e traduzir de uma vez: "Extraia o texto em chinês desta imagem e traduza para o inglês. Mostre os dois."

# Japanese invoice -> structured fields
ollama run qwen3-vl:8b
>>> This is a Japanese invoice. Extract vendor name, invoice date,
    subtotal, consumption tax, and total. Return as key: value pairs.
    ./invoice-jp.png

# Illustrative output format (not a measured result):
# vendor: <vendor name>
# date: <invoice date>
# subtotal: <amount> JPY
# tax: <amount> JPY
# total: <amount> JPY

Perguntas sobre imagens, análise de capturas de tela e leitura de gráficos

• Perguntas sobre imagens: faça perguntas abertas sobre uma foto — "O que há nesta imagem?" — e confira as respostas com a imagem.
• Análise de capturas de tela e de interfaces: comece lendo capturas de interface, caixas de erro e estados de aplicativos. As fichas dos dois modelos também descrevem habilidades de agente para interfaces gráficas, que este guia não cobre.
• Leitura de gráficos: descrever a estrutura e as tendências de um gráfico funciona melhor do que extrair números exatos; confirme os valores exatos nos dados de origem.
• Comparação de várias imagens: envie várias imagens em uma única requisição para comparar versões ou descrever um conjunto; quantas cabem depende da sua memória e do tamanho do contexto.

Comparação entre Qwen2-VL, Qwen2.5-VL e Qwen3-VL

Conectando um modelo de visão local do Qwen ao PromptQuorum

Solução de problemas dos modelos de visão do Qwen

• "pull model manifest: file does not exist" ou modelo desconhecido: a tag não está na biblioteca oficial. `qwen2-vl:7b` não está disponível — use `ollama pull qwen3-vl:8b` ou `ollama pull qwen2.5vl:7b`.
• O download termina, mas o modelo não carrega: atualize o Ollama. O Qwen2.5-VL exige 0.7.0+ e o Qwen3-VL exige 0.12.7+.
• A imagem é ignorada e o modelo responde como se nenhuma imagem tivesse sido enviada: confirme que o caminho do arquivo está correto e legível. Na API do Ollama, o array `images` deve conter base64 puro *sem* o prefixo `data:`; o prefixo `data:` é só do formato do LM Studio e da OpenAI.
• Caracteres CJK ilegíveis ou ausentes: a digitalização provavelmente tem resolução baixa demais. Digitalize de novo a 150–300 DPI e compare o resultado.
• Falta de memória: escolha uma tag menor (por exemplo `qwen3-vl:4b` ou `qwen2.5vl:3b`), reduza o tamanho do contexto ou a resolução da imagem, ou use Apple Silicon, que compartilha memória unificada entre CPU e GPU.
• Números errados extraídos de uma nota fiscal ou gráfico: modelos de visão locais podem ler dígitos errados em entradas com ruído. Melhore a qualidade da digitalização e sempre confira a saída numérica com o original.
• Um PDF não carrega: a API do Ollama aceita imagens, não arquivos PDF. Converta primeiro as páginas em PNG ou JPEG (com pdf2image ou pypdfium2) e envie cada página como uma imagem separada.
• O LM Studio mostra "failed to load model": ou a memória é insuficiente, ou você baixou uma versão sem visão. Confirme que a ficha do modelo informa suporte a visão e tente uma quantização menor.

Leitura relacionada

• Como executar o Qwen 3 localmente — o complemento de modelos de texto: configuração do Ollama e do LM Studio para os modelos de linguagem do Qwen.
• Modelos de visão locais comparados: LLaVA, Llama 3.2 Vision, MiniCPM-V — o panorama completo de outros modelos de visão locais.
• LLMs locais multimodais: visão, áudio e texto — visão geral mais ampla sobre executar modelos multimodais localmente.
• Qwen vs Llama vs Mistral — como os modelos de texto do Qwen se comparam às alternativas.
• Guia de hardware para LLMs locais — requisitos de VRAM e GPU para inferência local.
• Ver todos os guias de LLMs locais

Perguntas frequentes