Pular para o conteúdo
Alberto Mateus

OpenLake RAG

Protótipo

Lakehouse documental local com recuperação baseada em citações verificáveis

  • DOMÍNIO: RESEARCH
  • ATUALIZADO EM: 2026-07-07
[AVISO] Protótipo de pesquisa.

Leitura Rápida (30s)

[problema_chave]

Desenvolver um pipeline local-first de recuperação de informação que faça parsing de documentos brutos, gere embeddings, realize busca vetorial e híbrida de alta precisão e entregue respostas fundamentadas onde o usuário possa checar a origem exata do texto.

[papel_alberto]

Desenvolvedor backend e engenheiro de dados. Alberto estruturou o pipeline em Python/FastAPI, organizou a persistência híbrida no Docker e configurou os stubs de teste de embeddings.

[resultado_principal]

Endpoints funcionais validados localmente: healthcheck, upload, busca e analytics.

[diagrama_arquitetura]

Arquitetura de Dados e Pipeline do OpenLake RAGDiagrama lógico demonstrando o fluxo de ingestão de documentos para o MinIO, o processamento de metadados no PostgreSQL, a geração de chunks e embeddings salvos no Qdrant, e a análise de consultas através do DuckDB e dbt.PDF/TXT/URLsFontes de dadosFastAPI GatewayIngestion & Query APIMinIO (S3)Object Storage (Originals)PostgreSQLMetadados & TrackChunker & EmbedSentenceTransformersQdrant DBVector Index & ChunksRAG EngineExtractive + CitesDuckDB + dbtLakehouse AnalíticoCaminho de Recuperação / IACaminho de Ingestão de DocumentosMétricas e Analytics (DuckDB)
contexto & objetivo

O Contexto Operacional

Cenário de Entrada

Documentações técnicas internas, registros operacionais e corpora acadêmicos exigem um sistema de consulta semântica capaz de responder perguntas técnicas sem alucinações generativas, mantendo a proveniência dos fatos.

Objetivo Técnico

Construir um protótipo de busca semântica e RAG extrativo que rode inteiramente local, sem dependência obrigatória de APIs proprietárias ou tráfego externo de dados privados.

restrições

Restrições de Projeto

  • Licenciamento Aberto

    Uso exclusivo de tecnologias open-source (MinIO, PostgreSQL, Qdrant, DuckDB, FastAPI).

  • Tolerância a Falhas

    Mecanismo de fallback para SQLite e stubs quando a infraestrutura de banco vetorial externa estiver offline.

  • Exclusividade de Citação

    O modelo de IA só deve gerar afirmações que possuam link explícito e numérico para um bloco de texto recuperado.

camadas

Estrutura de Sistemas em Camadas

LAYER 01 //

Ingestion Layer

Processamento de Documentos

Controlador FastAPI que aceita uploads ou URLs, segmenta os textos em chunks otimizados de acordo com tokens e gera metadados.

LAYER 02 //

Object Storage (MinIO)

Blob storage

Bucket local S3-compatible que armazena os arquivos binários originais (PDFs, TXT) para auditoria visual de proveniência.

LAYER 03 //

Metadata Store (PostgreSQL)

Persistência Operacional

Banco de dados relacional que mantém o log transacional de uploads, status de processamento e tabelas de auditoria de uso.

LAYER 04 //

Vector Database (Qdrant)

Busca Vetorial

Qdrant Vector DB indexando os vetores de embeddings locais com metadados e payloads associados contendo o ID exato da citação.

LAYER 05 //

Retrieval & RAG Engine

Recuperação Híbrida e Resposta

Controlador que executa busca híbrida (semântica + metadados), formata o prompt delimitado por fontes e extrai a resposta citando blocos numéricos.

LAYER 06 //

Analytics Lakehouse (DuckDB)

Analítica Local

DuckDB processa os logs de chamadas e volume de tokens consumidos, preparando tabelas analíticas organizadas com dbt.

decisões

Matriz de Decisão Arquitetural (ADRs)

ADR-OLK-01accepted

Fallback local-first automático no bootstrap

Contexto
Subir o cluster Docker completo com PostgreSQL, Qdrant, MinIO e DuckDB consome RAM significativa em ambientes locais de desenvolvimento ou CI.
Decisão
Adicionar uma verificação de conectividade na inicialização da API. Se os serviços remotos falharem, o pipeline chaveia de forma silenciosa para SQLite e stubs de embeddings locais.
Consequências
Garantia de que a API sempre inicializa (/health retorna verde) e os testes integrados passam em ambientes de build isolados.
ADR-OLK-02accepted

Filtro RAG Extrativo com Citações Numéricas no Prompt

Contexto
Modelos generativos de linguagem tendem a associar fontes incorretas ou inventar links de referência se não forem restringidos.
Decisão
Estruturar o prompt de forma a fornecer os blocos de dados indexados por chaves curtas e ordenar explicitamente o modelo a recusar responder se a informação não estiver naquelas fontes.
Consequências
Redução de alucinações a níveis mínimos e rastreabilidade total das afirmações.
execução

Detalhamento da Implementação

O OpenLake RAG foi programado em Python usando FastAPI para expor endpoints REST documentados. A persistência utiliza conexões assíncronas para PostgreSQL e o cliente Qdrant para busca por similaridade de cosseno. Os testes automatizados em pytest cobrem todo o fluxo: do upload à geração analítica local usando dados simulados. A suite de teste pode rodar sem Docker ativo devido à arquitetura de stubs.

evidências

Evidências Técnicas Registradas

Bucket local MinIO (S3) e PostgreSQL

REPOSITORY · projects/04-openlake-rag-intelligence-platform/app/storage/ e app/database/

Estrutura de persistência de blobs originais no MinIO e controle transacional no Postgres.

Verificar evidência [externo] (abre em nova aba)

Fallback de Embeddings e SQLite

REPOSITORY · projects/04-openlake-rag-intelligence-platform/app/embeddings/fallback.py

Lógica de resiliência local que substitui Qdrant/Ollama por stubs locais quando offline.

Verificar evidência [externo] (abre em nova aba)
resultados

Resultados Obtidos

  • RESULTADO 01

    Endpoints funcionais validados localmente: healthcheck, upload, busca e analytics.

  • RESULTADO 02

    Suite de testes com 100% de aprovação validando embeddings, chunking e fallback de banco.

  • RESULTADO 03

    Estrutura dbt-duckdb preparada para organizar telemetria de uso nas camadas bronze, silver e gold.

Nota de Segurança e Privacidade
  • [public] O código-fonte e as configurações no repositório ocultam quaisquer chaves S3, senhas de banco ou paths locais do sistema de arquivos Windows.
evolução

Próximos Passos e Direções Futuras

Validação Docker de ponta a ponta

planned

Subir a stack completa localmente com conexões reais sem fallback e rodar testes de carga.

Modelagem dbt real

planned

Transformar as tabelas sintéticas em dbt para usar os logs reais de produção do banco PostgreSQL.