Sistema RAG (Retrieval-Augmented Generation) local para consulta inteligente de documentos com suporte a múltiplos formatos, histórico de conversas, busca híbrida e ingestão via API.
| Componente | Tecnologia | Descrição |
|---|---|---|
| Banco de Dados | PostgreSQL + pgvector | Armazenamento e busca vetorial |
| Embeddings | Nomic Embed v1.5 | Modelo de embeddings via LM Studio |
| LLM | Phi-3.5 Mini | Geração de respostas via LM Studio |
| API | Flask | Backend REST API |
| NLP | spaCy | Chunking semântico por sentenças |
| Ingestão | pypdf, python-docx, beautifulsoup4 | Extração de múltiplos formatos |
| Testes | pytest | Testes automatizados |
- 📄 Múltiplos formatos: PDF, DOCX, TXT, Markdown, HTML
- 🔍 Busca Híbrida: Combina busca vetorial (semântica) + Full-Text Search (palavras-chave)
- 🗜️ Compressão de Contexto: Reduz contexto grande automaticamente antes de enviar ao LLM
- 🔎 Filtro de similaridade: Descarta resultados irrelevantes automaticamente
- 💬 Histórico de conversas: Perguntas de follow-up com contexto mantido
- 📤 Upload via API: Ingestão de documentos com processamento assíncrono
- ✂️ Chunking semântico: Divisão inteligente por sentenças (spaCy)
- 🔄 Streaming: Respostas em tempo real
- 📊 Logging detalhado: Sistema de logs para API, RAG e ingestão
- 🧪 Testes automatizados: Suíte de testes para validação de funcionalidades
rag/
├── db/
│ ├── docker-compose.yml # PostgreSQL + pgvector + Adminer
│ ├── init.sql # Script de inicialização do banco
│ └── connections.md # Documentação de conexões
├── scripts/
│ └── ingest.py # CLI para ingestão de documentos
├── src/
│ ├── api/
│ │ └── routes.py # Endpoints da API
│ ├── core/
│ │ ├── embeddings.py # Geração de embeddings (Nomic)
│ │ ├── llm.py # Integração com LLM (Phi-3.5)
│ │ ├── rag.py # Pipeline RAG completo
│ │ ├── conversation.py # Gerenciador de histórico de conversas
│ │ ├── context_compression.py # Compressão inteligente de contexto
│ │ └── logger.py # Sistema de logging
│ ├── data/
│ │ ├── database.py # Conexão PostgreSQL + pgvector
│ │ ├── hybrid_search.py # Busca híbrida (vetorial + FTS)
│ │ ├── ingestion.py # Leitura de documentos + chunking
│ │ └── chunking.py # Chunking semântico com spaCy
│ ├── app.py # Aplicação Flask principal
│ └── config.py # Configurações centralizadas
├── tests/
│ └── test_chunking_comparison.py # Testes de chunking
├── docs/
│ ├── MELHORIAS.md # Roadmap de melhorias
│ ├── PLANO_CHUNKING_SEMANTICO.md # Plano de implementação do chunking
│ └── EVOLUCAO_LANGCHAIN_SGLANG.md # Evolução futura com LangChain
├── requirements.txt
└── README.md
- Python 3.11+ e Node.js 18+
- Docker (para PostgreSQL)
- LM Studio com modelos
bge-m3ephi-3.5-minicarregados
# Backend
python -m venv .venv
.\.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/Mac
# Instalar dependências pinadas (produção/estável)
pip install -r requirements.txt
# Para desenvolvimento (incluindo pip-tools e ferramentas de dev)
pip install -r requirements-dev.txt
python -m spacy download pt_core_news_sm
# Frontend
cd frontend
npm install
cd ..Tip
O projeto utiliza pip-tools para gerenciar dependências. Se desejar adicionar novos pacotes, edite os arquivos .in em requirements/ e rode pip-compile.
python -m venv .venv && . .venv/bin/activate
pip install spacy==3.8.11
python -m spacy download pt_core_news_sm --target ./models/spacy
python -m spacy download en_core_web_sm --target ./models/spacyMonte ./models/spacy no container (já configurado em docker-compose) para evitar downloads na imagem.
cd db
docker-compose up -d
cd ..
alembic upgrade headO sistema utiliza pydantic-settings para configuração:
# Copiar template
cp .env.example .env
# Editar .env com suas configurações
# Ou usar ambientes específicos:
# export APP_ENV=sit # Usa .env.sit
# export APP_ENV=uat # Usa .env.uatVariáveis principais:
LM_STUDIO_BASE_URL: URL do LM Studio (default:http://127.0.0.1:1234/v1)DOCUMENTS_DIR: Diretório de documentosDATABASE_*: Configurações PostgreSQLENABLE_*: Ativar/desativar funcionalidades (HyDE, MMR, etc.)ENABLE_ADAPTIVE_RETRIEVAL: Habilitar Adaptive Retrieval (default: true)RATE_LIMIT_*: Configurações de limite de requisições por endpoint
O sistema oferece proteção de dados sensíveis em duas camadas:
Criptografia de dados sensíveis armazenados no banco de dados usando AES-128 + HMAC-SHA256.
Campos Criptografados:
content(conteúdo de documentos)metadata(metadados de documentos e feedback)comment(comentários de feedback)
Configuração:
# Habilitar criptografia
ENABLE_ENCRYPTION=true
ENCRYPTION_KEY=your-generated-key-here
ENCRYPT_DOCUMENT_CONTENT=true
ENCRYPT_METADATA=true
ENCRYPT_FEEDBACK_COMMENTS=trueGerar chave de criptografia:
python scripts/generate_encryption_key.py- Faça backup da chave em local seguro
- Nunca commite a chave no Git
- Habilitar criptografia NÃO criptografa dados existentes automaticamente
- Para criptografar dados existentes: backup → limpar documentos → re-ingerir
Comunicação segura via TLS1.3 com headers de segurança (HSTS, CSP, etc.).
Configuração:
ENABLE_HTTPS=true
SSL_CERT_PATH=./certs/cert.pem
SSL_KEY_PATH=./certs/key.pem
SSL_PROTOCOL=TLSv1.3
SSL_CIPHERS=HIGH:!aNULL:!MD5Gerar certificado SSL (desenvolvimento):
mkdir -p certs
openssl req -x509 -newkey rsa:4096 \
-keyout certs/key.pem \
-out certs/cert.pem \
-days 365 \
-nodesProdução (Let's Encrypt):
sudo certbot certonly --standalone -d seu-dominio.com
# Certificados em: /etc/letsencrypt/live/seu-dominio.com/| Operação | Sem Criptografia | Com Criptografia |
|---|---|---|
| Inserção de documento | 100ms | 110ms (+10%) |
| Busca similar | 50ms | 55ms (+10%) |
| Recuperação de documento | 10ms | 15ms (+50%) |
Erro: "Encryption key not provided"
python scripts/generate_encryption_key.py
# Adicionar chave ao .envErro: "SSL context creation failed"
# Verificar arquivos
ls -la certs/
# Regenerar certificado
openssl req -x509 -newkey rsa:4096 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes- LGPD (Art. 46): Criptografia de dados pessoais
- ISO 27001 (A.10.1.1): Controles de criptografia
- SOC 2: Proteção de informações em repouso e em trânsito
python run_app.pyEste script inicia:
- Backend Flask (porta 5000)
- Frontend Vite (porta 5173)
- Limpeza automática de sessões expiradas
# Testar qualidade do chunking
python tests/test_chunking_comparison.pypython -m scripts.ingest --stats
### Build de todas as imagens Docker
O repositório contém múltiplos `Dockerfile` (ex.: raiz/backend e `frontend/`). Para facilitar, há dois scripts que encontram todos os `Dockerfile` recursivamente e fazem o build automaticamente.
- PowerShell (Windows):
```powershell
.\scripts\build_all.ps1 # build com cache
.\scripts\build_all.ps1 -NoCache # build sem cache
# Exemplos PowerShell com tag
```powershell
# build e usa tag 'v1.2.3'
.\scripts\build_all.ps1 -ImageTag v1.2.3
# sem cache e usa tag 'v1.2.3'
.\scripts\build_all.ps1 -ImageTag v1.2.3 -NoCache
- Bash (Linux / macOS / WSL / Git Bash):
```bash
chmod +x scripts/build_all.sh
./scripts/build_all.sh # build com cache, tag default 'latest'
./scripts/build_all.sh --no-cache # build sem cache, tag default 'latest'
./scripts/build_all.sh mytag # build com cache e usa tag 'mytag'
./scripts/build_all.sh --no-cache mytag # sem cache e usa tag 'mytag'
Comportamento:
- Cada
Dockerfileserá tagueado automaticamente com o caminho relativo (ex.:frontendvirafrontend:latest). - Os scripts rodam builds sequenciais; para builds paralelos podemos adaptar os scripts se desejar.
Argumento de tag
- Ambos os scripts aceitam um argumento para definir a tag usada nas imagens. Se nenhum argumento for passado, a tag padrão é
latest. - PowerShell: parâmetro
-ImageTag(ex.:.build_all.ps1 -ImageTag v1.2.3). - Bash: passe a tag como primeiro argumento, ou use
--no-cacheseguido da tag (ex.:./build_all.sh v1.2.3ou./build_all.sh --no-cache v1.2.3). - A tag final aplicada às imagens terá o formato
<path-based-name>:<tag>(ex.:frontend:v1.2.3).
Alternativa com docker-compose:
Se os serviços estiverem declarados em docker-compose.yml com build:, você pode usar:
docker-compose build --no-cacheVia API:
# Upload de arquivo
curl -X POST http://localhost:5000/api/ingest \
-F "file=@documento.pdf"
# Verificar status
curl http://localhost:5000/api/ingest/status/{job_id}
# Ingerir todos
curl -X POST http://localhost:5000/api/documents/ingest-all \
-H "Content-Type: application/json" \
-d '{"force": false}'| Endpoint | Método | Descrição |
|---|---|---|
/api/query |
POST | Query RAG principal |
/api/query/stream |
POST | Query com streaming |
/api/chat |
POST | Chat com histórico |
/api/search |
POST | Apenas busca (sem LLM) |
Exemplo /api/query:
{
"question": "O que é GWPRP?",
"top_k": 5,
"temperature": 0.7,
"include_sources": true,
"collection": "default",
"enable_adaptive": true,
"debug": false
}Nota: O parâmetro enable_adaptive permite habilitar/desabilitar o Adaptive Retrieval por query. Quando habilitado, o sistema ajusta automaticamente top_k e min_similarity baseado na complexidade da pergunta.
Exemplo /api/chat:
{
"question": "Como funciona o GWPRP?",
"session_id": "uuid-da-sessão",
"top_k": 5,
"temperature": 0.7,
"include_explanation": true,
"enable_adaptive": true
}Nota: O parâmetro include_explanation (default: true) adiciona uma explicação detalhada do processo RAG na resposta, incluindo timeline de etapas, métricas de similaridade e detalhes técnicos.
Nota: O parâmetro search_mode (default: "automatic") define a estratégia de recuperação:
"automatic": Sistema decide automaticamente (hierárquico ou sentence window)"hierarchical": Usa chunks grandes para contexto amplo (Explicação)"sentence": Usa sentenças individuais expandidas para precisão (Precisão)
| Endpoint | Método | Descrição |
|---|---|---|
/api/chat/sessions |
GET | Listar sessões |
/api/chat/sessions/<id> |
GET | Histórico de sessão |
/api/chat/sessions/<id> |
DELETE | Deletar sessão |
/api/chat/new |
POST | Criar nova sessão |
| Endpoint | Método | Descrição |
|---|---|---|
/api/ingest |
POST | Upload de documento |
/api/ingest/status/<job_id> |
GET | Status do job |
/api/ingest/jobs |
GET | Listar todos jobs |
/api/ingest/formats |
GET | Formatos suportados |
/api/documents/stats |
GET | Estatísticas do diretório |
/api/documents/scan |
GET | Documentos pendentes |
/api/documents/ingest-all |
POST | Ingerir todos |
/api/documents/ingest-status |
GET | Status da ingestão em massa |
/api/documents/reprocess |
POST | Re-processar tudo |
/api/documents/ingested |
GET | Lista documentos ingeridos |
/api/documents/delete |
POST | Deletar documento |
| Endpoint | Método | Descrição |
|---|---|---|
/api/prompts |
GET | Listar todos prompts |
/api/prompts/<id> |
GET | Detalhes do prompt |
/api/prompts |
POST | Criar novo prompt |
/api/prompts/<id> |
PUT | Atualizar prompt |
/api/prompts/<id> |
DELETE | Deletar prompt |
/api/prompts/categories |
GET | Categorias disponíveis |
| Endpoint | Método | Descrição |
|---|---|---|
/api/embeddings/advanced-stats |
GET | Estatísticas do processador avançado |
/api/embeddings/advanced-stats/reset |
POST | Resetar estatísticas |
| Endpoint | Método | Descrição |
|---|---|---|
/api/metrics |
GET | Métricas Prometheus |
/api/metrics/status |
GET | Status do módulo |
/api/metrics/adaptive-retrieval/stats |
GET | Estatísticas agregadas do Adaptive Retrieval |
/api/metrics/adaptive-retrieval/recent |
GET | Queries recentes com ajustes aplicados |
/api/metrics/adaptive-retrieval/performance |
GET | Métricas de performance do Adaptive |
/api/cache/stats |
GET | Estatísticas do cache |
/api/cache/clear |
POST | Limpar cache |
/api/classify |
POST | Classificar pergunta |
/api/evaluate |
POST | Avaliar resposta RAG |
/api/hyde/test |
POST | Testar HyDE |
| Endpoint | Método | Descrição |
|---|---|---|
/api/health |
GET | Health check |
/api/stats |
GET | Estatísticas gerais |
/api/collections |
GET | Listar coleções |
- Chat Interface: Chat moderno com streaming de respostas
- Adaptive Retrieval Toggle: Botão no header para habilitar/desabilitar automaticamente
- Admin Dashboard:
- Documentos: Upload, listagem, gerenciamento
- Prompts: Criar, editar, deletar prompts
- Sessões: Ver e gerenciar sessões ativas
- Overview: Estatísticas do sistema
- Adaptive Retrieval Metrics: Dashboard de métricas de adaptive retrieval
- Debug Panel: Visualização detalhada do pipeline RAG
- Modo Dark/Light: Alternância de temas
- Responsivo: Funciona em desktop e mobile
ChatArea: Área principal de conversaçãoMessageList: Lista de mensagens com markdown e botão de explicaçãoMessageInput: Input com suporte a multi-linhaUploadModal: Modal de upload de documentosExplanationModal: Modal de explicação detalhada do pipeline RAGAdminDashboard: Dashboard administrativoPromptsManagement: Gerenciador de promptsDocumentsPanel: Painel de documentosSessionsPanel: Painel de sessõesDebugPanel: Painel de debugTemperatureSelector: Seletor de temperaturaThemeContext: Contexto de temaAdaptiveRetrievalMetrics: Dashboard de métricas de adaptive
Combina similaridade semântica (embeddings) com busca textual (FTS):
- Alpha: 0.7 (70% vetorial, 30% FTS)
- Ajustável via
HYBRID_SEARCH_ALPHA
Refina resultados usando Cross-Encoder:
- Modelo:
text-embedding-bge-reranker-v2-m3 - Top-K inicial: 15 → Top-K final: 5
- Melhora significativamente a precisão
Gera documento hipotético para busca:
- Usa LLM para criar resposta "ideal"
- Busca embeddings do documento hipotético
- Melhora buscas por conceito abstratos
Gera variações da pergunta usando LLM para busca mais abrangente:
- Número de variações: 3 (configurável via
QUERY_EXPANSION_COUNT) - Fusão com RRF: Combina resultados de múltiplas buscas usando Reciprocal Rank Fusion
- Melhoria de recall: +20-40% na recuperação de documentos relevantes
- Prompt customizável: Gerenciado via banco de dados (tabela
prompts) - Útil para: Perguntas curtas, ambíguas, ou com terminologia técnica variada
- Documentação detalhada:
docs/melhorias_feitas/IMPLEMENTACAO_2_QUERY_EXPANSION.md
Diversifica resultados:
- Lambda: 0.7 (equilíbrio relevância/diversidade)
- Evita chunks muito similares
- Melhor cobertura de tópicos
Ajusta parâmetros dinamicamente baseado na complexidade da query:
- Análise de Complexidade: Detecta nível (0-10) considerando:
- Número de palavras
- Presença de palavras interrogativas (como, por que, etc.)
- Múltiplas frases
- Terminologia técnica
- Ajuste Automático:
- Queries Simples (0-3): Aumenta
top_ke diminuimin_similaritypara buscar mais contexto - Queries Médias (4-6): Usa valores padrão (equilíbrio)
- Queries Complexas (7-10): Diminui
top_ke aumentamin_similaritypara focar nos mais relevantes
- Queries Simples (0-3): Aumenta
- Configurável: Limites ajustáveis via
MAX_TOP_K_ADAPTIVE,MIN_TOP_K_ADAPTIVE, etc. - Toggle de Usuário: Botão no header para habilitar/desabilitar
- Métricas Completas:
- Estatísticas agregadas (total, complexidade média, etc.)
- Distribuição de complexidade (Simple/Medium/Complex)
- Tabela de queries recentes com ajustes aplicados
- Monitoramento via Admin Dashboard
- Documentação Detalhada:
docs/melhorias_feitas/IMPLEMENTACAO_ADAPTIVE_RETRIEVAL.md
Exemplo de Uso:
POST /api/query
{
"question": "Como funciona o sistema?",
"enable_adaptive": true
}Resposta com Análise:
{
"adaptive_params_used": {
"applied": true,
"complexity_score": 3,
"top_k": 12,
"min_similarity": 0.55,
"adjustment_reason": "Simple query - expanding search scope"
}
}Reduz tamanho do contexto:
- Threshold: 3000 tokens
- Método: LLM-based
- Preserva informações relevantes
Avalia e refina automaticamente respostas incompletas:
- Avaliação de qualidade (score 0-100)
- Refinamento automático com Query Expansion
- Métricas detalhadas (iterations, initial_score, final_score, was_refined)
- Configurável via
ENABLE_SELF_RAG,SELF_RAG_MIN_SCORE,SELF_RAG_MAX_ITERATIONS - Integração transparente em
/api/querye/api/chat
Cache LRU para embeddings:
- Max size: 1000
- Hit rate esperado: 30-50%
- Reduz latência drasticamente
Identifica tipo de pergunta:
- Types: definition, comparison, procedure, troubleshooting, etc.
- Permite prompts específicos por tipo
- Melhora precisão
Processamento paralelo de múltiplos batches simultâneos:
- Workers paralelos: 4 workers por padrão (configurável)
- Speedup: 2.5x mais rápido que processamento sequencial
- Throughput: ~50 embeddings/segundo
- Utilização de GPU: Maximiza capacidade de processamento
- Configurável: Desativável via
ENABLE_ADVANCED_BATCH_PROCESSING - Estatísticas: API para monitorar throughput e error rate
Suíte completa de testes para Adaptive Retrieval:
- 48 testes unitários: Cobertura completa de funcionalidades
- Categorias: Cálculo de complexidade, ajuste de parâmetros, validação de limites, integração, casos de borda
- Execução:
pytest tests/test_adaptive_retrieval.py -v - Documentação: Testes com docstrings explicativas
Busca precisa usando sentenças individuais com expansão dinâmica:
- 3 Modos de Recuperação:
- Automático: Sistema analisa a pergunta e escolhe a melhor estratégia (hierárquico ou sentence window)
- Explicação (Hierarchical): Contexto amplo com chunks grandes, ideal para tutoriais e documentação
- Precisão (Sentence Window): Chunks pequenos (1 sentença) com janela expandida, ideal para perguntas específicas de fatos
- Ingestão Seletiva: Tipo de chunking selecionável por documento (Hierarchical vs Sentence Window)
- Expansão Dinâmica: 3 sentenças vizinhas (antes e depois) para contexto suficiente
- Heurísticas de Decisão: Sistema analisa pergunta para escolher estratégia automaticamente:
- Perguntas curtas (≤5 palavras) → Precisão
- Perguntas "qual é", "quanto custa", "onde fica" → Precisão
- Perguntas "como funciona", "por que", "explique" → Explicação
- Benefícios:
- Melhor recall para perguntas específicas
- Respostas mais diretas e precisas
- Menos ruído nos embeddings
- Contexto mais adequado ao tipo de pergunta
- Configurável:
SENTENCE_WINDOW_SIZE(default: 3) - Dependências: spaCy + modelo
pt_core_news_sm - Documentação Detalhada:
docs/melhorias_feitas/IMPLEMENTACAO_SENTENCE_WINDOW.md
Exemplo de Uso:
POST /api/query
{
"question": "Qual o preço do produto?",
"search_mode": "automatic" // "hierarchical", "sentence", ou "automatic"
}Resposta com Modo Usado:
{
"answer": "...",
"search_mode_used": "sentence",
"retrieval_strategy": "Precisão (Sentence Window) - 7 chunks expandidos"
}rag_query_duration_seconds: Tempo total de queryrag_embedding_duration_seconds: Tempo de embeddingrag_search_duration_seconds: Tempo de buscarag_llm_duration_seconds: Tempo do LLMrag_chunks_retrieved: Número de chunks retornadosrag_similarity_score: Similaridade médiarag_cache_hits_total: Hits do cacherag_cache_misses_total: Misses do cacherag_errors_total: Erros totais
# Scraping (formato Prometheus)
curl http://localhost:5000/api/metrics
# Verificar status
curl http://localhost:5000/api/metrics/status
# Métricas de Adaptive Retrieval
curl http://localhost:5000/api/metrics/adaptive-retrieval/stats?days=7
curl http://localhost:5000/api/metrics/adaptive-retrieval/recent?limit=50
curl http://localhost:5000/api/metrics/adaptive-retrieval/performance?days=7- Query Latency: P95, P99, média
- Cache Hit Rate: Hits vs Misses
- Error Rate: Taxa de erros
- Chunks per Query: Distribuição
- Similarity Distribution: Histograma de similaridade
documentos:
- Chunks indexados com embeddings
- Metadados (source, page, collection_id)
- Vetor pgvector (1024 dimensões)
prompts:
- Templates de prompts
- Categorias e prioridades
- Versionamento
user_feedback:
- Feedback do usuário
- Rating (1-5)
- Comentários
ingestion_control:
- Controle de ingestão
- Hash SHA-256
- Status e timestamps
conversation_history:
- Histórico de conversas
- Sessões com expiração
adaptive_retrieval_metrics:
- Métricas de adaptive retrieval
- Complexidade de queries
- Ajustes de parâmetros aplicados
- Performance e timing
question_type_instructions:
- Instruções especializadas para cada tipo de pergunta
- Exemplos few-shot para guiar o modelo
- 7 tipos suportados: definition, comparison, listing, procedure, factual, reason, general
- Cache em memória (TTL 5 minutos) para otimizar performance
- Fallback para instruções hardcoded se BD indisponível
- Gerenciamento via SQL (sem frontend por enquanto)
# Ver status
alembic current
# Criar nova migração
alembic revision --autogenerate -m "Descrição"
# Aplicar migrações
alembic upgrade head
# Reverter
alembic downgrade -1# Executar todos os testes
pytest
# Com cobertura
pytest --cov=src --cov-report=html
# Testes específicos
pytest tests/test_embeddings.py
pytest tests/test_adaptive_retrieval.py -v# Type checking
mypy src/
# Linting
flake8 src/
# Formatação (Black)
black src/
# Ordenação de imports
isort src/O sistema utiliza o módulo padrão de logging do Python configurado via dictConfig.
Formato de Log:
2026-01-03 12:30:45 INFO flask.app Iniciando processamento do pedido 9988
2026-01-03 12:30:45 ERROR rag.llm Erro fatal ao processar requisição LLM
Traceback (most recent call last):
File "src/core/llm.py", line 80, in generate_response
response.raise_for_status()
requests.exceptions.HTTPError: 502 Server Error
Níveis de Log:
- DEBUG: Detalhes de execução (queries SQL, embedding vectors)
- INFO: Eventos importantes (API requests, LLM calls, document ingestion)
- WARNING: Situações anormais não-críticas
- ERROR: Erros que requerem atenção
Arquivos de Log:
logs/flask_app.log: Log principal com rotação automática (10MB, 3 backups)
Configuração:
# src/config.py
LOG_LEVEL: str = "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FILE: str = "logs/flask_app.log"
LOG_MAX_BYTES: int = 10485760 # 10MB
LOG_BACKUP_COUNT: int = 3| Variável | Padrão | Descrição |
|---|---|---|
CHUNK_SIZE |
800 |
Tamanho máximo do chunk |
MIN_CHUNK_SIZE |
200 |
Tamanho mínimo do chunk |
USE_SEMANTIC_CHUNKING |
True |
Usar chunking por sentenças |
CHUNK_OVERLAP_SENTENCES |
1 |
Sentenças de overlap |
logger = logging.getLogger(name)
logger.info("Mensagem informativa")
order_id = 9988 logger.info("Iniciando processamento do pedido %s", order_id)
try: resultado = 1 / 0 except Exception: logger.exception("Erro fatal ao processar pagamento do pedido %s", order_id)
---
## 🚀 Performance
### Benchmarks
| Operação | Tempo Alvo | Tempo Atual |
|----------|------------|-------------|
| Embedding (cache hit) | < 50ms | ~10ms |
| Embedding (cache miss) | < 500ms | ~200ms |
| Busca vetorial | < 100ms | ~50ms |
| Re-ranking | < 200ms | ~100ms |
| LLM generation | < 2s | ~1.5s |
| Query total | < 3s | ~1.8s |
---
## 📝 Melhorias Futuras
Ver documento completo em `docs/MELHORIAS_COMPLETAS.md`
### Próximas Prioridades
- [ ] **Sistema de autenticação**: API Key ou JWT
- [ ] **Distributed tracing**: OpenTelemetry/Jaeger
- [ ] **Sistema de filas**: Celery ou RQ
- [ ] **Exportação de conversas**: JSON, Markdown, TXT
- [ ] **Sugestões de perguntas**: Baseadas em documentos
- [ ] **Multi-query**: Busca com múltiplas variações
- [ ] **Temporal re-ranking**: Priorizar documentos recentes
---
## 🤝 Contribuindo
# Iniciar API
python -m src.app
# Testar qualidade do chunking
python tests/test_chunking_comparison.py
- ✅ Filtro de similaridade mínima
- ✅ Chunking semântico com spaCy
- ✅ Suporte a múltiplos formatos (PDF, DOCX, TXT, MD, HTML)
- ✅ Histórico de conversas
- ✅ Endpoint de ingestão via API
- ✅ Busca Híbrida - Combina busca vetorial (pgvector) com Full-Text Search (BM25)
- ✅ Compressão de Contexto - Reduz contexto grande antes de enviar ao LLM
- ✅ Sistema de Logging - Logs detalhados para API, RAG e ingestão
- ✅ Testes Automatizados - Validação de funcionalidades do chunking
-
Re-ranking com cross-encoder
-
Cache de embeddings
-
Métricas e monitoramento
-
Interface de chat (frontend)
-
Autenticação na API
-
Expansão da suíte de testes
-
Issues: GitHub Issues
-
Documentação: Ver pasta
docs/ -
Exemplos:
docs/MELHORIAS.md -
Sistema de Avaliação RAG: Documentação completa em
docs/SISTEMA_AVALIACAO_QUALIDADE.md- Métricas de qualidade (fidelidade, relevância, precisão do contexto)
- Avaliação manual e automática
- Dashboard administrativo
- Exemplos de uso da API
- Implementação de Adaptive Retrieval:
docs/melhorias_feitas/IMPLEMENTACAO_ADAPTIVE_RETRIEVAL.md
-
Implementação de Sentence Window Retrieval:
docs/melhorias_feitas/IMPLEMENTACAO_SENTENCE_WINDOW.md
- BAAI: Modelo BGE-M3
- Microsoft: Modelo Phi-3.5 Mini
- LangChain: Inspiração e conceitos
- Sentence Transformers: Modelos de re-ranking
- spaCy: Processamento de NLP
O projeto possui documentação para evolução futura com tecnologias avançadas:
- Blocos prontos para loaders, splitters, embeddings e retrievers
- Observabilidade com callbacks/tracing
- Composição de chains/runnables para flexibilidade
- Servidor de inferência otimizado com batching e speculative decoding
- Redução de latência e custo
- Cache KV para melhor performance
Para mais detalhes sobre o plano de migração, consulte docs/EVOLUCAO_LANGCHAIN_SGLANG.md.
Projeto pessoal para estudo e uso local.