81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
# Agente de Classificação Bancária (RAG + Llama 3.2)
|
|
|
|
> **Branch:** `iris-classificacao-bancaria`
|
|
|
|
Este projeto implementa um **Agente de IA especializado na classificação de transações bancárias** via API. Ele utiliza uma arquitetura **RAG (Retrieval-Augmented Generation)** com modelos locais otimizados para execução em **CPU**.
|
|
|
|
## 🎯 Objetivo
|
|
Classificar transações financeiras (ex: Pix, TED, Boletos) em categorias contábeis padronizadas, utilizando descrições históricas e aprendizado por similaridade.
|
|
|
|
## 🏗 Arquitetura
|
|
|
|
O sistema é construído sobre três pilares principais:
|
|
1. **FastAPI (Python 3.12):** Exposição da API REST de alta performance.
|
|
2. **Qdrant (Vector DB):** Busca de transações similares ("few-shot learning" dinâmico).
|
|
3. **Llama 3.2 1B (GGUF):** LLM Local quantizado (Q4_K_M) para inferência final.
|
|
|
|
### Stack Tecnológica
|
|
- **Runtime:** Python 3.12
|
|
- **IA Framework:** PydanticAI (Validação e Orquestração)
|
|
- **Database:** Qdrant (Vetorial)
|
|
- **Monitoramento:** Logs Estruturados (Zabbix Ready)
|
|
|
|
## 🚀 Como Rodar
|
|
|
|
### Pré-requisitos
|
|
- Docker & Docker Compose
|
|
- Python 3.12+ (Opcional, para rodar sem Docker)
|
|
|
|
### 1. Configuração
|
|
Copie o arquivo de exemplo e ajuste as variáveis (se necessário):
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### 2. Executando com Docker (Recomendado)
|
|
O comando abaixo sobe a API e o Banco Vetorial:
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
A API estará disponível em: `http://localhost:8000/docs`
|
|
|
|
### 3. Executando Localmente (Dev)
|
|
Se preferir rodar o Python diretamente:
|
|
|
|
1. **Suba apenas as dependências (Qdrant):**
|
|
```bash
|
|
docker-compose up qdrant -d
|
|
```
|
|
|
|
2. **Instale as libs:**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Rode a API:**
|
|
```bash
|
|
uvicorn src.main:app --reload
|
|
```
|
|
|
|
## 📁 Estrutura do Projeto
|
|
|
|
```
|
|
.
|
|
├── src/
|
|
│ ├── main.py # Entrypoint da API
|
|
│ ├── config.py # Configurações centralizadas
|
|
│ ├── core/ # Lógica do LLM e Vector Store
|
|
│ ├── models/ # Schemas Pydantic (Input/Output)
|
|
│ └── services/ # Regras de Negócio
|
|
├── docker-compose.yml # Orquestração de Containers
|
|
├── requirements.txt # Dependências Python
|
|
└── scripts/ # Utilitários de MLOps
|
|
```
|
|
|
|
## 🧠 pipeline RAG (Resumo)
|
|
1. **Input:** Recebe JSON da transação (`descricao`, `valor` ignorado, `tipo`).
|
|
2. **Retrieval:** Busca 5 exemplos similares no Qdrant.
|
|
3. **Inference:** Llama 3.2 analisa a transação atual + exemplos.
|
|
4. **Validation:** PydanticAI garante que a categoria retornada existe.
|
|
5. **Feedback:** Transações validadas alimentam o treino futuro.
|