🤖 ML Service - Nutri A.I (XGBoost + Python)

Descrição

Serviço Python que fornece análise tabular baseada em machine learning (XGBoost) para a aplicação Nutri A.I. Processa dados biométricos e retorna predições sobre o estado nutricional de crianças.

📁 Estrutura

ml-service/
├── src/
│   ├── data_generator.py        # Gera dados sintéticos de treino
│   ├── model_trainer.py         # Treina o modelo XGBoost
│   ├── predict_service.py       # API Flask para predições
│   └── __pycache__/             # Cache Python (ignorar)
├── models/
│   ├── synthetic_nutrition_data.csv     # Dataset de treino
│   └── xgboost_nutrition_model.json     # Modelo treinado
├── requirements.txt             # Dependências Python
└── README.md                    # Este arquivo

🚀 Como Executar

Pré-requisitos

• Python 3.8+ instalado
• pip (gerenciador de pacotes Python)

1. Instalar Dependências

cd ml-service
pip install -r requirements.txt

2. Treinar o Modelo (Primeira vez)

python src/model_trainer.py

Isso irá:

• Gerar dados sintéticos em models/synthetic_nutrition_data.csv
• Treinar o modelo XGBoost
• Salvar o modelo em models/xgboost_nutrition_model.json

3. Executar o Serviço

python src/predict_service.py

O serviço estará disponível em: http://localhost:8000

🔌 Endpoints da API

Predição Tabular

Método	Endpoint	Descrição
POST	/api/v1/diagnose/tabular	Análise tabular com XGBoost

Parâmetros (JSON):

{
  "weight_kg": 15.5,
  "height_cm": 110.0,
  "age_months": 48,
  "gender": "M",  // ou "F"
  "edema": false
}

Resposta:

{
  "prediction": "Normal",
  "confidence": 0.92,
  "status_code": 200
}

Exemplo de requisição:

curl -X POST http://localhost:8000/api/v1/diagnose/tabular \
  -H "Content-Type: application/json" \
  -d '{
    "weight_kg": 15.5,
    "height_cm": 110.0,
    "age_months": 48,
    "gender": "M",
    "edema": false
  }'

📊 Dados de Entrada

O modelo XGBoost espera os seguintes parâmetros:

Parâmetro	Tipo	Intervalo	Descrição
weight_kg	float	5.0 - 50.0	Peso da criança em quilogramas
height_cm	float	50 - 150	Altura da criança em centímetros
age_months	int	6 - 60	Idade em meses (6 a 5 anos)
gender	string	"M" ou "F"	Gênero (M=Masculino, F=Feminino)
edema	boolean	true/false	Presença de edema

🎯 Saídas Possíveis

O modelo classifica em uma das seguintes categorias:

• Normal - Estado nutricional adequado
• Desnutrição Leve - MAZ entre -1 e -1.99
• Desnutrição Moderada - MAZ entre -2 e -2.99
• Desnutrição Severa - MAZ < -3
• Sobrepeso - IMC acima do esperado
• Obesidade - IMC significativamente acima

🔄 Fluxo de Dados

┌─────────────────────────────────────────┐
│ Frontend (form.html)                    │
│ Coleta dados biométricos + imagem       │
└──────────────┬──────────────────────────┘
               │
               │ POST /api/v1/diagnose/run-analysis
               ▼
┌─────────────────────────────────────────┐
│ Backend (NutriAIController)             │
│ Recebe multipart/form-data              │
└──────────────┬──────────────────────────┘
               │
               ├─ Envia dados para XGBoost
               │  POST /api/v1/diagnose/tabular
               │
               ├─ Envia imagem para Gemini API
               │  POST generativelanguage.googleapis.com
               │
               └─ Combina respostas
                  ▼
┌─────────────────────────────────────────┐
│ XGBoost Service (Python)                │
│ Análise tabular: weight, height, age... │
└──────────────┬──────────────────────────┘
               │
               │ Retorna classificação
               ▼
┌─────────────────────────────────────────┐
│ Backend (DiagnosisRecord)               │
│ Consolidação de resultados              │
└──────────────┬──────────────────────────┘
               │
               │ Retorna JSON
               ▼
┌─────────────────────────────────────────┐
│ Frontend (result.html)                  │
│ Exibe diagnóstico completo              │
└─────────────────────────────────────────┘

🧠 Modelo XGBoost

Características

• Algoritmo: XGBoost (Extreme Gradient Boosting)
• Formato: JSON (modelo serializado)
• Variáveis de Entrada: 5
• Classes de Saída: 6

Como o Modelo Funciona

1. Dados de Entrada: weight, height, age, gender, edema
2. Processamento: Normalização e encoding
3. Predição: Floresta de árvores de decisão
4. Saída: Classificação + confiança

🔧 Configuração

requirements.txt

xgboost==2.0.0
flask==3.0.0
pandas==2.0.0
numpy==1.24.0
scikit-learn==1.3.0

Para atualizar dependências:

pip install --upgrade -r requirements.txt

📈 Treinar Novo Modelo

Se quiser retreinar o modelo com novos dados:

1. Preparar dados

Coloque seu CSV em models/ com as colunas:

weight_kg, height_cm, age_months, gender, edema, diagnosis

2. Executar treinamento

python src/model_trainer.py --data seu_arquivo.csv

3. Reiniciar o serviço

# Parar a aplicação anterior (Ctrl+C)
python src/predict_service.py

🧪 Testar Localmente

import requests

response = requests.post('http://localhost:8000/api/v1/diagnose/tabular', json={
    'weight_kg': 15.5,
    'height_cm': 110.0,
    'age_months': 48,
    'gender': 'M',
    'edema': False
})

print(response.json())

🐛 Troubleshooting

Erro: "ModuleNotFoundError: No module named 'xgboost'"

pip install xgboost

Erro: "Modelo não encontrado"

Retreine o modelo:

python src/model_trainer.py

Erro: "Porta 8000 já está em uso"

Use outra porta:

python -c "import predict_service; predict_service.app.run(port=8001)"

Depois atualize em backend/src/main/resources/application.properties:

app.services.xgboost.url=http://localhost:8001/api/v1/diagnose/tabular

🚢 Deploy

Docker

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY src/ src/
COPY models/ models/
EXPOSE 8000
CMD ["python", "src/predict_service.py"]

Build:

docker build -t nutri-ai-ml .
docker run -p 8000:8000 nutri-ai-ml

Railway/Heroku

Configure Procfile:

web: python src/predict_service.py

📚 Referências

• XGBoost Documentation
• Flask Documentation
• OMS Z-Score Reference