Pixel-Native RAG: como criar um pipeline de busca visual que entende documentos como imagens, não como texto

Pixel-Native RAG: como criar um pipeline de busca visual que entende documentos como imagens, não como texto

O Retrieval-Augmented Generation (RAG) tradicional tem um ponto cego: ele depende de parsing de HTML, extração de texto e chunking — processos que descartam tabelas, gráficos, fórmulas matemáticas, blocos de código e o layout visual que dá contexto ao conteúdo. Um tutorial publicado no MarkTechPost mostra como construir um sistema de RAG “pixel-nativo” que processa documentos inteiros como imagens, preservando 100% da informação visual original.

✅ O que você ganha

• Recuperação de documentos que preserva estrutura visual completa: tabelas, imagens, fórmulas e código
• Pipeline completo de ponta a ponta — da renderização de páginas web e PDFs à API de busca
• Combinação de busca densa (embeddings multimodais) com busca esparsa (OCR + BM25) via fusão recíproca de rankings
• Indexação eficiente com FAISS e treinamento de adaptador contrastivo para melhorar qualidade de recuperação
• Avaliação quantitativa com Recall@k e Mean Reciprocal Rank

⚠️ O que você NÃO ganha

• Velocidade de indexação comparável a pipelines puramente textuais (renderizar screenshots é mais lento)
• Compatibilidade imediata com bases de dados de produção em larga escala (milhões de documentos)
• Solução plug-and-play — requer GPUs locais ou acesso a APIs de embeddings multimodais

Tabela de requisitos

Passo a passo: construindo o pipeline

1. Configuração global e dependências

O ponto de partida é uma dataclass Config que centraliza todos os parâmetros do pipeline: URLs de documentos de exemplo, dimensões dos tiles (1024×1024 pixels), overlap entre tiles (128px), backend de embeddings (SigLIP, CLIP ou Qwen3-VL), e flags para servidor FastAPI, avaliação e treinamento de adaptador.

O sistema detecta automaticamente se está rodando no Google Colab e instala as dependências necessárias: Pillow, NumPy, FAISS, PyMuPDF, Transformers, FastAPI, Playwright e Tesseract OCR. Um helper assíncrono permite que coroutines do Playwright rodem em ambientes Jupyter sem conflitos de event loop.

2. Renderização de documentos em tiles

Esta é a camada central que diferencia o PixelRAG dos RAGs tradicionais. Documentos são convertidos em imagens e depois fatiados em tiles sobrepostos:

• Páginas web: O Playwright renderiza a página em Chromium headless, aplica autoscroll, remove elementos fixos e cookies banners, e captura screenshots em tiles de 1024×1024 pixels com 128px de overlap vertical
• PDFs: PyMuPDF converte cada página para imagem, que é então fatiada com o mesmo algoritmo de sliding window
• Fallback textual: Se o browser não estiver disponível, o sistema renderiza texto como imagem usando PIL
• Filtragem: Tiles em branco ou com baixo desvio padrão são descartados; tiles duplicados são detectados por perceptual hashing (Hamming distance ≤ 4)

3. Embeddings multimodais

Cada tile passa por OCR com Tesseract para extrair texto (usado na busca esparsa), e depois é codificado em um vetor de embedding por um dos três backends:

• SigLIP (padrão): modelo google/siglip-base-patch16-224, rápido e eficiente
• CLIP: alternativa com suporte mais amplo a idiomas
• Qwen3-VL: backend mais poderoso para documentos com layout complexo

Os embeddings são normalizados e processados em batches de 8 tiles para eficiência de GPU.

4. Indexação com FAISS e BM25

O índice PixelIndex combina duas estratégias de busca:

• Busca densa: embeddings armazenados em um índice FAISS (inner product). Para datasets com mais de 2.000 tiles, o índice muda automaticamente para IVF (Inverted File) com 16 probes
• Busca esparsa: texto extraído por OCR é indexado com BM25 (Okapi), capturando correspondências lexicais que embeddings visuais podem perder

5. Recuperação híbrida com RRF

A fusão de rankings é feita por Reciprocal Rank Fusion (RRF) com k=60. Os scores densos e esparsos são combinados com pesos configuráveis (padrão: 1.0 para ambos). Os tiles são então agregados por documento, produzindo um ranking final com os tiles de evidência mais fortes, scores de similaridade e snippets de OCR.

6. Servidor FastAPI

O sistema expõe dois endpoints REST:

• GET /health — verificação de disponibilidade
• GET /search?q=...&n=5 — busca com limite configurável de documentos retornados

O servidor Uvicorn roda em uma thread separada, permitindo que o pipeline continue funcionando como biblioteca enquanto atende requisições HTTP.

7. Avaliação e adaptador contrastivo

O pipeline inclui um benchmark com 7 consultas de avaliação usando Recall@1, Recall@3, Recall@5 e Mean Reciprocal Rank (MRR). Pares de pseudo-consulta e tile são extraídos do texto OCR para treinar um adaptador residual contrastivo — uma pequena rede neural que aprende a projetar queries para o espaço de embeddings visuais com maior precisão.

Opcionalmente, os tiles de evidência mais fortes podem ser enviados para um modelo de visão-linguagem (Qwen2.5-VL-3B) para gerar respostas fundamentadas.

Tabela comparativa: RAG textual vs Pixel-Native RAG

Casos de uso reais

1. Documentação técnica com diagramas: manuais de engenharia, especificações de API com fluxogramas e esquemas de arquitetura que seriam perdidos em extração textual
2. Artigos científicos com fórmulas: papers com notação LaTeX, tabelas de resultados e gráficos que precisam ser recuperados no contexto visual original
3. Sites com layout complexo: landing pages de produtos, dashboards e relatórios onde a disposição espacial carrega significado
4. Documentos escaneados: contratos, formulários e documentos históricos onde OCR isolado perde a estrutura do documento
5. Catálogos de produtos: e-commerce com imagens, tabelas de especificações e selos de qualidade que só fazem sentido no contexto visual completo

Troubleshooting: erros comuns

1. ❌ Playwright não instala o Chromium: Execute playwright install --with-deps chromium manualmente. Se falhar, o pipeline usa fallback de renderização textual com PIL.
2. ❌ Tesseract não encontrado: Instale com apt-get install tesseract-ocr. Se indisponível, a busca híbrida opera em modo apenas-denso (sem BM25).
3. ❌ Memória insuficiente na GPU: Reduza embed_batch_size para 2 ou 4. Para CPU, espere tempos de embedding 5-10× maiores.
4. ❌ Índice FAISS muito grande: Acima de 2.000 tiles, o sistema migra automaticamente para IVF. Ajuste ivf_nprobe (padrão: 16) para controlar precisão vs velocidade.
5. ❌ Tiles em branco dominando o índice: Aumente blank_std_threshold (padrão: 6.0) para filtrar tiles com mais agressividade.
6. ❌ Timeout ao navegar em páginas web: Aumente nav_timeout_ms (padrão: 60.000ms). Para páginas muito pesadas, considere pré-renderizar offline.

FAQ

1. Preciso de GPU para rodar? Não obrigatoriamente — o pipeline funciona em CPU, mas embeddings serão 5-10× mais lentos. Para datasets pequenos (até 50 documentos), CPU é aceitável.
2. Posso usar meus próprios documentos? Sim. Altere a lista Config.urls para apontar para suas URLs ou caminhos de PDF. O pipeline aceita páginas web, PDFs e arquivos de imagem.
3. Qual backend de embedding devo escolher? SigLIP é o padrão e oferece o melhor equilíbrio velocidade/qualidade. Use Qwen3-VL se seus documentos tiverem muito texto em layouts complexos.
4. Quanto storage o índice ocupa? Cada tile de 1024×1024 salvo como PNG otimizado ocupa ~50-200 KB. Um documento típico gera 5-12 tiles, totalizando ~1-2 MB por documento mais o índice FAISS.
5. Funciona com documentos em português? Sim, desde que o backend de embedding escolhido (SigLIP/CLIP) tenha sido treinado com diversidade linguística. O OCR Tesseract suporta português com -l por.
6. É melhor que RAG textual tradicional? Depende do seu domínio. Se seus documentos são principalmente texto linear, RAG textual é mais rápido e eficiente. Se você precisa preservar tabelas, gráficos, fórmulas ou layout, o PixelRAG é superior.

Para onde isso vai

O Pixel-Native RAG representa uma mudança de paradigma na recuperação de documentos. À medida que modelos de visão-linguagem como Qwen2.5-VL e Gemini 2.5 Flash se tornam mais rápidos e baratos, a abordagem de “indexar pixels, não parágrafos” deve ganhar tração — especialmente em domínios como documentação técnica, pesquisa científica e compliance regulatório, onde o contexto visual é informação, não decoração.

O código completo está disponível no GitHub sob licença Apache 2.0.