Pular para o conteúdo principal

Relatório de Análise: Python Services (estudos/)

Data: 06-07 de Janeiro de 2026
Última Atualização: 07/01/2026 23:30 UTC
Versão Python: 3.12.3
Tipo: Análise Estrutural + Performance Tuning

🚀 Atualização 07/01/2026 — motor-rag Performance​

Mudanças Aplicadas​

ComponenteAntesDepois
Servidoruvicorn diretoGunicorn + 4 UvicornWorkers
Pool DB/tenant3 conexões (hardcoded)8 conexões (configurável via env)
Timeout poolFalha imediataRetry 2s antes de 503
Erro pool exhaustedHTTP 500HTTP 503 (backpressure)

Arquivos Modificados​

  • motorRag/services/tenant_manager.py — Pool size via FREGERAG_TENANT_POOL_SIZE
  • motorRag/services/tenant_search_engine.py — Retry com FREGERAG_POOL_WAIT_SECONDS
  • motorRag/server/routes/search.py — 503 para PoolError

Benchmark Real (POST /api/fregerag/search)​

Concorrênciap50p90p99RPS
122.9s29.1s29.1s0.04
227.5s38.4s38.4s0.06

Gargalo identificado: Disk I/O (400-600 MiB/s) → Resolvido com MariaDB buffer pool 18GB

Ver: RELATORIO_INFRAESTRUTURA_2026-01-07.md

Nota (07 de Janeiro de 2026): O Motor RAG está em 127.0.0.1:8768, gerenciado por PM2 via pm2-root, com pm2 save/pm2 resurrect.

📌 Resumo Executivo​

A pasta /home/arboreolab/estudos/ contém os serviços Python críticos do sistema ArboreoLab, incluindo o motor RAG (Retrieval Augmented Generation), processamento OCR, gerenciamento de Google Drive, e geração de entidades. Estes scripts são chamados diretamente pelo backend Node.js.

Métricas Principais​

MétricaValor
Tamanho Total9.4 GB
Scripts Python (usuário)59 arquivos
Virtual EnvironmentPython 3.12.3
Subpastas __pycache__0 ✅ (removidas)
Arquivos .DS_Store0 ✅ (removidos)
Arquivos vazios2 (placeholders)
Pastas vazias3

🔗 Dependências com Outros Projetos​

Chamadas do Backend Node.js​

O backend Node.js depende diretamente dos scripts Python desta pasta:

Rota Node.jsScript PythonFunção
fregeRAGRoute.js1_busca/fregeV2+busca_entidades.pyBusca semântica
inserirEntidadesRoute.jsenviar_db/entidadesV2.pyInserção de entidades
clusteringRoute.jsgerar_documento/ocr_cluster_segmentadov1v2v3.pyClustering OCR
correcaoEntidadesRoute.jscorrecao_entidades/*Correção de entidades
gerenciadorDriveGoogle.jsgerenciador_drive/GerenciadorDriveGoogle.pyOperações Google Drive
mapeadorDriveGoogle.jsgerenciador_drive/MapeadorDriveGoogle.pyMapeamento de arquivos
driveWebhook.jsgerenciador_drive/*Webhooks do Drive
pdfTreatmentRoute.jsgerenciador_drive/GerenciadorDriveGoogle.pyTratamento de PDFs

Variáveis de Ambiente Utilizadas​

// Definidas no Node.js (hardcoded ou .env)
PYTHON_EXECUTABLE = '/home/arboreolab/estudos/.venv/bin/python3'
PYTHON_SCRIPTS_DIR = '/home/arboreolab/estudos/1_funcionais/fregeRAG_v1/gerenciador_drive'

PM2 (ecosystem.config.js)​

{
   name: 'motor-rag',
   script: '/home/arboreolab/estudos/.venv/bin/uvicorn',
   args: 'motorRag.server.main:app --host 127.0.0.1 --port 8768',
  cwd: '/home/arboreolab/estudos/1_funcionais/fregeRAG_v1',
   interpreter: 'none',
  env: {
    PYTHONPATH: '/home/arboreolab/estudos/1_funcionais/fregeRAG_v1'
  }
}

📁 Estrutura Atual​

estudos/
├── .venv/                              # Virtual Environment Python 3.12.3
├── config_produzir_nomes.json          # Configuração global
├── estudos.code-workspace              # Workspace VS Code
├── rag_server.log                      # Log do servidor RAG (47KB)
│
├── 1_funcionais/
│   └── fregeRAG_v1/                    # Sistema RAG principal
│       ├── config/                     # Configurações (config.ini, prompt.ini)
│       ├── 1_busca/                    # Motor de busca semântica
│       ├── motorRag/                   # Servidor FastAPI (organizado)
│       ├── gerenciador_drive/          # Integração Google Drive
│       ├── gerar_documento/            # Processamento OCR/clustering
│       ├── gerar_entidades/            # Extração de entidades NER
│       ├── correcao_entidades/         # Correção e clustering de entidades
│       ├── enviar_db/                  # Persistência no banco de dados
│       ├── converter_md_pdf_html/      # Conversão de formatos
│       ├── migracoesdedb/              # Scripts de migração
│       ├── backup/                     # Backups SQL
│       ├── pareceres/                  # Documentos gerados
│       └── output_md/                  # Saídas em Markdown
│
└── macos_worker/                       # Worker OCR para macOS
    ├── worker_server.py                # Servidor HTTP do worker
    ├── ocr_refiner.py                  # Refinamento OCR
    ├── requirements.txt                # Dependências
    └── [scripts de instalação]

🔍 Análise por Módulo​

1. motorRag/ (Motor RAG - FastAPI)​

Status: ✅ BEM ORGANIZADO

Estrutura modular seguindo padrões de indústria:

  • server/ → Servidor FastAPI com rotas separadas
  • services/ → Lógica de negócio (embeddings, search, TF-IDF)
  • models/ → Pydantic models (requests/responses)
  • config/ → Carregamento de config.ini
  • utils/ → Logging

Endpoints:

  • GET /health → Health check
  • POST /api/fregerag/search → Busca híbrida
  • POST /api/fregerag/reindex → Re-indexação

2. gerenciador_drive/ (Google Drive)​

Status: ⚠️ REQUER ORGANIZAÇÃO

  • GerenciadorDriveGoogle.py (42KB) → Download/upload de arquivos
  • MapeadorDriveGoogle.py (35KB) → Mapeamento de estrutura
  • GoogleDrive/ → Tokens e cache de estruturas por conta
  • temp_uploads/, temp_pdf/ → Arquivos temporários

Observações:

  • Arquivos de configuração .config.cfg e .config.cfg.migrated na raiz
  • Diretório credentials.json é executável (possível problema de permissão)
  • Cache de estruturas JSON pode crescer muito

3. gerar_documento/ (Processamento OCR)​

Status: ⚠️ REQUER ORGANIZAÇÃO

Múltiplas versões de scripts:

  • ocr_cluster_segmentadov1v2v3.py (versão atual)
  • FUNCIONANDO_ocr_cluster_segmentadov1v2v3.py (backup funcional)
  • reserva_ocr_cluster_segmentadov1v2v3.py (backup)
  • Versões docling_* (experimentos com Docling)

Observação: Arquivo import pytest.py com nome incorreto.

4. correcao_entidades/ (Correção de Entidades)​

Status: ⚠️ REQUER ORGANIZAÇÃO

Scripts de clustering e correção de entidades NER:

  • 1_correcao_entidades_um_todos.py
  • cluster_entities.py
  • entity_linker.py
  • backfill_vectors.py, backfill_segment_vectors.py
  • Scripts duplicados: log_de_desvio.py e log_deviation.py

5. macos_worker/ (Worker OCR macOS)​

Status: ✅ BEM ORGANIZADO

Worker para processamento OCR usando Apple Vision Framework:

  • worker_server.py (57KB) → Servidor HTTP
  • ocr_refiner.py (34KB) → Refinamento OCR
  • Scripts de instalação como serviço launchd

⚠️ Problemas Identificados​

Alta Prioridade​

  1. Arquivos de Dados na Raiz do fregeRAG_v1

    • *.npy (embeddings) → 550+ MB
    • *.json (dados) → 140+ MB
    • backup.sql → 125 MB
    • Recomendação: Mover para pasta data/ ou embeddings/

  2. Pastas Vazias/Placeholder

    • validar_fact_check/ (vazia)
    • gerenciador_metadados/ (vazia)
    • gerenciadorarboreolabadm/ (arquivo vazio)
    • Recomendação: Remover ou documentar propósito futuro

  3. Arquivos Vazios

    • enviar_texto/enviar_texto_parecer.py (0 bytes)
    • gerenciadorarboreolabadm/migrardb_arboreolabadm.py (0 bytes)
    • gerar_entidades/5, gerar_entidades/Daria (lixo)

Média Prioridade​

  1. pycache (12 pastas)

    • Adicionar ao .gitignore se não estiver
    • Podem ser removidas com: find . -type d -name __pycache__ -exec rm -rf {} +

  2. Arquivos .DS_Store (8 arquivos)

    • Lixo do macOS
    • Remover com: find . -name .DS_Store -delete

  3. Nomenclatura Inconsistente

    • fregeV2+busca_entidades.py (caractere + em nome de arquivo)
    • FUNCIONANDO_ocr_cluster... (prefixo não-padrão)
    • import pytest.py (nome incorreto)

Baixa Prioridade​

  1. Arquivos Temporários Grandes

    • temp_uploads/ com imagens JPG de teste
    • pareceres/Arquivado/ com documentos antigos

  2. PDF de Teste

    • exposicoesiap_smithsonian b_img1080.pdf na raiz

📋 Propostas de Organização​

Estrutura Ideal (SEM IMPLEMENTAR AGORA)​

estudos/
├── .venv/
├── README.md                           # CRIAR: Documentação principal
├── ESTRUTURA_DIRETORIOS.md             # CRIAR: Este documento
├── pyproject.toml                      # CRIAR: Configuração moderna Python
│
├── services/                           # Renomear 1_funcionais/
│   └── fregerag/                       # Renomear fregeRAG_v1/
│       ├── README.md
│       ├── config/
│       │   ├── config.ini
│       │   ├── prompt.ini
│       │   └── settings.py
│       │
│       ├── server/                     # motorRag atual (já organizado)
│       │   ├── main.py
│       │   ├── routes/
│       │   ├── middleware/
│       │   ├── services/
│       │   ├── models/
│       │   └── utils/
│       │
│       ├── integrations/               # Integrações externas
│       │   └── google_drive/
│       │       ├── manager.py
│       │       ├── mapper.py
│       │       └── cache/
│       │
│       ├── processing/                 # Processamento de documentos
│       │   ├── ocr/
│       │   ├── clustering/
│       │   └── conversion/
│       │
│       ├── nlp/                        # Processamento de linguagem
│       │   ├── entities/
│       │   ├── search/
│       │   └── embeddings/
│       │
│       ├── data/                       # Dados e embeddings
│       │   ├── embeddings/
│       │   └── cache/
│       │
│       ├── migrations/                 # Migrações de banco
│       │
│       └── _archived/                  # Scripts obsoletos
│
└── workers/                            # Workers remotos
    └── macos_ocr/

✅ Próximos Passos Recomendados​

Fase 1: Limpeza (Baixo Risco)​

  • Remover __pycache__ (12 pastas)
  • Remover .DS_Store (8 arquivos)
  • Remover arquivos vazios óbvios (5, Daria)
  • Criar .gitignore adequado

Fase 2: Organização de Dados (Médio Risco)​

  • Mover *.npy e *_data.json para pasta data/
  • Mover backup.sql para pasta backup/sql/
  • Documentar propósito de pastas vazias ou removê-las

Fase 3: Reorganização de Código (Alto Risco - Requer Testes)​

  • Padronizar nomes de arquivos (remover +, prefixos)
  • Consolidar scripts duplicados
  • Atualizar paths hardcoded no Node.js
  • Testar todas as rotas após mudanças

⚠️ Pendente de Integração (08/01/2026)​

ComponenteStatusDescrição
Multi-Signal v2✅ Backendsearch_documents_v2() implementado
Endpoint /search_v2✅ DisponívelFastAPI em 8768
Frontend v2🔄 Em progressoIntegrar useFregeRAG.ts
Consolidação Entidades✅ CompletoUPSERT automático + script limpeza

🎯 Próximos Passos Priorizados (Motor RAG)​

Fase 1: Integração Frontend v2 (08/01/2026)​

#TarefaStatus
1Modificar useFregeRAG.ts → /search_v2🔄 Em progresso
2Adicionar interface SearchResponseV2⏳ Pendente
3Feature flag USE_SEARCH_V2⏳ Pendente
4Testar em produção⏳ Pendente

Fase 2: Feedback Loop (Janeiro 2026)​

#TarefaStatus
5Criar tabela search_feedback⏳ Pendente
6Endpoint POST /api/fregerag/feedback⏳ Pendente
7UI thumbs up/down⏳ Pendente

Fase 3: Layout-Aware Segments (Janeiro 2026)​

#TarefaStatus
8Integrar Docling para layout⏳ Pendente
9Adicionar segment_type na tabela⏳ Pendente
10Boost de score para headings⏳ Pendente

🚨 Ação Recomendada Agora​

Multi-Signal Scoring v2 já está no backend:

  • motorRag/services/tenant_search_engine.py → search_documents_v2()
  • motorRag/server/routes/search.py → /api/fregerag/search_v2

Próximo passo: Integrar frontend para usar endpoint v2.

Impacto Esperado:

Métricav1 (Atual)v2 (Multi-Signal)
Precision@10~40%≥70%
Queries sem resultado útil~25%≤10%

🔧 Manutenção de Entidades (Periódica)​

Script de consolidação para entidades DESCRICAO:

cd /home/arboreolab/estudos/1_funcionais/fregeRAG_v1/enviar_db/
python consolidar_entidades_descricao.py --dry-run   # Simular
python consolidar_entidades_descricao.py             # Executar

Frequência: Mensalmente ou após reprocessamentos em massa.

📝 Observações Finais​

Esta análise foi realizada SEM ALTERAÇÕES no código ou estrutura. Todas as recomendações devem ser implementadas em fases, com testes adequados, pois os scripts Python são dependências críticas do sistema.

ATENÇÃO: Alterações nos paths requerem atualização sincronizada em:

  1. Backend Node.js (PYTHON_SCRIPTS_DIR, PYTHON_EXECUTABLE)
  2. PM2 (ecosystem.config.js)
  3. Scripts Python internos (imports relativos)

Autor: Engenheiro Sênior ArboreoLab
Próxima Revisão: Após aprovação do Diretor para implementação