O projeto RagPub visa o desenvolvimento de um sistema de agentes assistentes inteligentes para o repositório de conhecimento do Ipea. A proposta central é criar uma solução robusta, baseada em IA, capaz de processar e interpretar todos os documentos do repositório, permitindo aos usuários interagir com o conteúdo por meio de um agente conversacional. Os principais recursos incluem:
- Recomendação personalizada de leituras;
- Respostas a perguntas com base no contexto específico dos documentos (RAG);
- Interação conversacional com fontes de dados (gráficos, imagens e tabelas) presentes nos documentos.
Para atingir esses objetivos, o projeto utilizará uma arquitetura de sistema multi-agentes, bibliotecas Python especializadas e técnicas avançadas de Recuperação Aumentada por Geração (RAG). O detalhamento do funcionamento interno será apresentado nas próximas seções.
Pipeline completo de ingestão, processamento e indexação vetorial híbrida (Dense + Sparse + ColBERT) para publicações institucionais do IPEA.
- 📚 Sistema de Indexação e Recuperação Semântica
- 1. Contexto
- 2. Tecnologias
- 3. Funcionamento
- 🏗️ Arquitetura Geral
- 📂 Estrutura do Projeto
- 🗃️ Banco de Controle (SQLite)
- 🌐 Scraper do Repositório
- 🧠 Pipeline de Ingestão
- 📥 Download e Cache de PDFs
- ✂️ Chunking
- 🔎 Indexação Vetorial (Qdrant)
- 📦 Estrutura do Payload
- 🖼️ Extração de Imagens
- 🔐 Robustez Operacional
- 🚀 Execução
- 🔌 API
O projeto RagPub visa o desenvolvimento de um sistema de agentes assistentes inteligentes para o repositório de conhecimento do Ipea. A proposta central é criar uma solução robusta, baseada em IA, capaz de processar e interpretar todos os documentos do repositório, permitindo aos usuários interagir com o conteúdo por meio de um agente conversacional. Os principais recursos incluem:
- Recomendação personalizada de leituras;
- Respostas a perguntas com base no contexto específico dos documentos (RAG);
- Interação conversacional com fontes de dados (gráficos, imagens e tabelas) presentes nos documentos.
Para atingir esses objetivos, o projeto utilizará uma arquitetura de sistema multi-agentes, bibliotecas Python especializadas e técnicas avançadas de Recuperação Aumentada por Geração (RAG). O detalhamento do funcionamento interno será apresentado nas próximas seções.
O projeto está sendo desenvolvido em Python, com código fonte disponível em IpeaPub no GitHub do Ipea. Os principais frameworks e bibliotecas utilizadas no projeto são:
- Docling (para parsing de documentos)
- Qdrant (para banco vetorial)
- PyTorch/transformers (para rodar modelos de IA localmente)
- BeautifulSoup (para o crawler do site do Ipea)
- FastAPI (para receber e responder requisições)
- Docker (Conteinerização do projeto)
Existem 2 etapas para o funcionamento integral do sistema: ingestão e recuperação. Abaixo, será explicado cada uma delas. Os arquivos Python envolvidos em cada sub etapa do projeto estará explicitado entre parênteses para ajudar o entendimento.
Essa etapa serve para inserir as informações dos documentos do repositório na base de dados do projeto. As informações são a base para o funcionamento do sistema multiagente, por isso pode ser considerada a etapa mais importante do projeto. São utilizados bancos de dados vetoriais para realizar a busca semântica de informações.
- (scraper.py e banco_metadados.py) Todos os metadados de todos os documentos são adicionados em um banco de dados relacional âncora, com um estado de processamento pendente.
- (docling_pipeline.py e banco_vetorial.py) A pipeline busca por documentos pendentes no banco relacional e processa as informações dele para inserir nas coleções de pontos vetoriais: chunks, tabelas, imagens e recomendação, utilizando o Docling como ferramenta principal.
O arquivo utils.py possui funções auxiliares, como o crawler do site para buscar os arquivos PDFs a serem processados. Na pipeline do Docling, encontra-se também acesso a modelos de LLM e visão computacional para resumir e legendar tabelas e imagens, para que possam ser buscadas na query semântica do banco vetorial. Os arquivos de processamento se encontram na pasta ingestor, relacionado justamente com a etapa de ingestão.
Scraper → SQLite (Banco 1) → Ingestão → Chunking → Embeddings
→ Qdrant (Banco Vetorial) → API de Consulta
O sistema é dividido em dois bancos:
| Camada | Tecnologia | Finalidade |
|---|---|---|
| Banco 1 | SQLite | Controle operacional da ingestão |
| Banco 2 | Qdrant | Armazenamento vetorial híbrido |
.
├── create_collection.py
├── create_indexes.py
├── create_ingestion.py
├── teste_ingestion.py
├── run.py
├── scraper.py
│
├── ingestao/
│ ├── db/
│ │ └── banco_metadados.py
│ └── utils/
│ ├── clean_itens.py
│ ├── semantic_chunker.py
│ └── simple_chunker.py
│
├── cache/pdfs/
├── logs/
├── img/
└── data/banco1.db
Arquivo:
Tabela principal:
documentos (
id TEXT PRIMARY KEY,
titulo TEXT,
autores TEXT,
ano INTEGER,
tipo_conteudo TEXT,
resumo TEXT,
palavras_chave TEXT,
link_pdf TEXT,
link_download TEXT,
status_ingestao TEXT,
data_ingestao TEXT
)pendenteem processamentosem_pdfprocessadoerro
A ingestão é incremental e resiliente a falhas.
Arquivo:
Funções:
- Consome API do repositório IPEA
- Extrai metadados estruturados
- Normaliza campos
- Persiste no SQLite
- Remove duplicatas posteriormente
Controle de duplicidade baseado em:
titulo + ano + resumo
Arquivo:
Fluxo completo:
- Busca documento pendente no SQLite
- Download real do PDF (com retry + cache SHA256)
- Extração via Docling (OCR + imagens)
- Limpeza textual avançada
- Chunking semântico
- Geração de embeddings híbridos
- Upload batch para Qdrant
- Atualização de status
Arquivo:
Características:
- Retry automático
- Verificação de assinatura
%PDF - Cache por hash SHA256
- Armazenamento em
cache/pdfs/
Arquivo:
Características:
- Embeddings SentenceTransformers
- Clusterização HDBSCAN
- Agrupamento por similaridade semântica
- Controle rígido de tokens (max_tokens=290)
Arquivo:
- Split por sentenças
- Controle direto de tokens
- Sem clusterização
Arquivo:
Configuração híbrida:
vectors_config = {
"dense": 768 (cosine),
"colbert": 128 (multi-vector MAX_SIM)
}
sparse_vectors_config = {
"sparse": BM25
}| Tipo | Modelo |
|---|---|
| Dense | sentence-transformers/paraphrase-multilingual-mpnet-base-v2 |
| Sparse | Qdrant/bm25 |
| ColBERT | colbert-ir/colbertv2.0 |
Arquivo:
Cria índices KEYWORD para:
- metadata.ticker
- metadata.form_type
- metadata.source
Arquivo:
Valida:
- Conexão com Qdrant
- Estrutura vetorial híbrida
- Upsert de ponto sintético
Cada chunk gera:
{
"text": "...",
"metadata": {
"document_id": "...",
"titulo": "...",
"autores": "...",
"ano": 2023,
"tipo_conteudo": "...",
"palavras_chave": "...",
"pagina": 12,
"imagens_pagina": [...]
}
}- Extraídas por página via Docling
- Salvas em
img/{pdf_hash}/ - Caminhos armazenados no payload
- Controle transacional de status
- Batch upload resiliente
- Log individual por documento em
logs/ - Retry HTTP automático
- Proteção contra overflow de tokens no ColBERT
- Flush final garantido de buffer
.env:
QDRANT_URL=http://localhost:6333
python create_collection.pypython create_indexes.pyArquivo:
python run.pypython create_ingestion.pyA camada de API já está implementada separadamente e consome:
- Coleção
publicacoes_ipea - Recuperação híbrida
- Payload estruturado
A API não depende do pipeline de ingestão em tempo real, apenas da coleção indexada.