308 lines
9.8 KiB
Markdown
308 lines
9.8 KiB
Markdown
# MAIA — Meeting AI Assistant
|
|
|
|
<p align="center">
|
|
<img src="frontend/public/maia-logo.png" alt="MAIA Logo" width="120"/>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<strong>Grave, transcreva e analise suas reuniões com Inteligência Artificial</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="#-instalação">Instalação</a> •
|
|
<a href="#-arquitetura">Arquitetura</a> •
|
|
<a href="#-configuração">Configuração</a> •
|
|
<a href="#-deploy">Deploy</a> •
|
|
<a href="#-endpoints-da-api">API</a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## 📖 Sobre o Projeto
|
|
|
|
O **MAIA** (Meeting AI Assistant) é uma plataforma desenvolvida pela **ASAP Telecom** para gravar, transcrever e analisar reuniões automaticamente usando Inteligência Artificial.
|
|
|
|
### ✨ Funcionalidades Principais
|
|
|
|
- 🎙️ **Gravação contínua** de reuniões via navegador (sem gaps, usando MediaRecorder API com timeslice)
|
|
- 📝 **Transcrição automática** com Whisper.cpp na GPU (modelo large-v3, alta precisão)
|
|
- 👥 **Diarização de speakers** — identifica quem falou o quê (SpeechBrain ECAPA-TDNN, ~85% precisão)
|
|
- 🤖 **Análise com IA** — resumo, pontos de ação e insights com LLM (deepseek-v3.1)
|
|
- 🔐 **Autenticação SSO** via Keycloak
|
|
- 📱 **PWA instalável** em Android e iOS
|
|
- 🔎 **Histórico** com busca de reuniões passadas
|
|
- 👤 **Identificação de speakers** por enrollment de voz
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitetura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CLIENTE │
|
|
│ Browser / PWA (React 18 + Vite + TypeScript) │
|
|
│ MediaRecorder API → chunks de áudio → upload automático │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│ HTTPS
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ APP SERVER (5.0.0.181) │
|
|
│ ┌─────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ Nginx :80 │ │ Backend API :8090 │ │ Diarization :5060│ │
|
|
│ │ (Frontend) │ │ FastAPI + Celery │ │ FastAPI+SpeechBr.│ │
|
|
│ └─────────────┘ └────────┬─────────┘ └────────┬─────────┘ │
|
|
│ │ │ │
|
|
│ ┌─────────────┐ ┌────────▼─────────┐ │ │
|
|
│ │ PostgreSQL │ │ Redis (Celery) │ │ │
|
|
│ └─────────────┘ └──────────────────┘ │ │
|
|
└────────────────────────────┬──────────────────────┼────────────┘
|
|
│ │
|
|
┌──────────────▼──────┐ ┌──────────▼───────────┐
|
|
│ GPU SERVER │ │ LLM Server │
|
|
│ 10.100.16.13 :5003 │ │ asapai.asaptelecom. │
|
|
│ Whisper.cpp GPU │ │ com.br/ollama │
|
|
│ AMD GPU, large-v3 │ │ deepseek-v3.1:671b │
|
|
└─────────────────────┘ └──────────────────────┘
|
|
|
|
┌─────────────────────┐
|
|
│ Keycloak SSO │
|
|
│ Autenticação/Authz │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
### 📁 Estrutura do Monorepo
|
|
|
|
```
|
|
Maia/
|
|
├── frontend/ # PWA React 18 + Vite + TypeScript
|
|
├── backend/ # API FastAPI + Celery + PostgreSQL
|
|
├── diarization/ # API de Diarização com SpeechBrain
|
|
├── README.md
|
|
└── CHANGELOG.md
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Requisitos
|
|
|
|
| Componente | Requisito |
|
|
|------------|-----------|
|
|
| Node.js | 18+ |
|
|
| Python | 3.11+ |
|
|
| PostgreSQL | 14+ |
|
|
| Redis | 7+ |
|
|
| GPU | AMD/NVIDIA (para Whisper GPU) |
|
|
| RAM | 16 GB mínimo (32 GB recomendado) |
|
|
| VRAM | 8 GB mínimo para Whisper large-v3 |
|
|
|
|
---
|
|
|
|
## 🚀 Instalação
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
cp .env.example .env
|
|
# Edite o .env com as variáveis necessárias
|
|
npm run dev # desenvolvimento
|
|
npm run build # produção
|
|
```
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd backend
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/Mac
|
|
venv\Scripts\activate # Windows
|
|
pip install -r requirements.txt
|
|
cp .env.example .env
|
|
# Edite o .env com as variáveis necessárias
|
|
alembic upgrade head # aplicar migrações
|
|
uvicorn app.main:app --host 0.0.0.0 --port 8090
|
|
```
|
|
|
|
### Diarization API
|
|
|
|
```bash
|
|
cd diarization
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env
|
|
uvicorn main:app --host 0.0.0.0 --port 5060
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Configuração
|
|
|
|
### Variáveis de Ambiente — Backend (`backend/.env`)
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://user:password@localhost:5432/maia
|
|
REDIS_URL=redis://localhost:6379/0
|
|
KEYCLOAK_URL=https://seu-keycloak.exemplo.com
|
|
KEYCLOAK_REALM=seu-realm
|
|
KEYCLOAK_CLIENT_ID=maia-backend
|
|
OLLAMA_URL=https://llm.exemplo.com/ollama
|
|
OLLAMA_MODEL=deepseek-v3.1:671b-cloud
|
|
WHISPER_URL=http://gpu-server:5003
|
|
```
|
|
|
|
### Variáveis de Ambiente — Diarization API (`diarization/.env`)
|
|
|
|
```env
|
|
WHISPER_ORIGIN=http://gpu-server:5003
|
|
VOICE_DB_PATH=/data/voice_db
|
|
SPEAKER_CONFIDENCE_THRESHOLD=0.75
|
|
HF_TOKEN=seu_token_huggingface
|
|
SPEECHBRAIN_CACHE=/data/speechbrain_cache
|
|
```
|
|
|
|
### Variáveis de Ambiente — Frontend (`frontend/.env`)
|
|
|
|
```env
|
|
VITE_API_URL=http://seu-backend:8090
|
|
VITE_KEYCLOAK_URL=https://seu-keycloak.exemplo.com
|
|
VITE_KEYCLOAK_REALM=seu-realm
|
|
VITE_KEYCLOAK_CLIENT_ID=maia-frontend
|
|
```
|
|
|
|
---
|
|
|
|
## 🐳 Deploy
|
|
|
|
### Com Podman/Docker Compose
|
|
|
|
```bash
|
|
# Na raiz do projeto
|
|
podman-compose up -d
|
|
```
|
|
|
|
### Deploy Manual
|
|
|
|
#### Backend (systemd)
|
|
```bash
|
|
# /etc/systemd/system/maia-backend.service
|
|
[Unit]
|
|
Description=MAIA Backend API
|
|
After=network.target postgresql.service redis.service
|
|
|
|
[Service]
|
|
User=maia
|
|
WorkingDirectory=/opt/Backend/meeting-assistant-api
|
|
ExecStart=/opt/Backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8090
|
|
Restart=always
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
#### Celery Worker
|
|
```bash
|
|
celery -A app.celery_app worker --loglevel=info -Q transcription,analysis
|
|
```
|
|
|
|
#### Frontend (Nginx)
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
root /var/www/maia;
|
|
index index.html;
|
|
|
|
location / {
|
|
try_files $uri $uri/ /index.html;
|
|
}
|
|
|
|
location /api/ {
|
|
proxy_pass http://localhost:8090/;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 Endpoints Principais da API
|
|
|
|
### Backend API (`http://server:8090`)
|
|
|
|
| Método | Endpoint | Descrição |
|
|
|--------|----------|-----------|
|
|
| `POST` | `/meetings/` | Criar nova reunião |
|
|
| `GET` | `/meetings/` | Listar reuniões |
|
|
| `GET` | `/meetings/{id}` | Detalhes da reunião |
|
|
| `DELETE` | `/meetings/{id}` | Deletar reunião |
|
|
| `POST` | `/meetings/{id}/upload-chunk` | Upload de chunk de áudio |
|
|
| `POST` | `/meetings/{id}/finalize` | Finalizar e processar reunião |
|
|
| `GET` | `/meetings/{id}/transcript` | Transcrição completa |
|
|
| `GET` | `/meetings/{id}/analysis` | Análise da IA |
|
|
| `POST` | `/speakers/enroll` | Enrollar speaker com voz |
|
|
| `GET` | `/speakers/` | Listar speakers |
|
|
| `GET` | `/admin/users` | (Admin) Listar usuários |
|
|
|
|
### Diarization API (`http://server:5060`)
|
|
|
|
| Método | Endpoint | Descrição |
|
|
|--------|----------|-----------|
|
|
| `POST` | `/transcribe` | Transcrever + diarizar áudio |
|
|
| `POST` | `/enroll` | Enrollar voz de speaker |
|
|
| `GET` | `/speakers` | Listar speakers cadastrados |
|
|
| `DELETE` | `/speakers/{name}` | Remover speaker |
|
|
| `GET` | `/health` | Health check |
|
|
|
|
---
|
|
|
|
## 🛠️ Tecnologias
|
|
|
|
### Frontend
|
|
| Tecnologia | Versão | Uso |
|
|
|------------|--------|-----|
|
|
| React | 18 | Framework UI |
|
|
| Vite | 5 | Build tool |
|
|
| TypeScript | 5 | Tipagem estática |
|
|
| Zustand | 4 | Gerenciamento de estado |
|
|
| Axios | 1.x | Cliente HTTP |
|
|
| Workbox | 7 | PWA / Service Worker |
|
|
| MediaRecorder API | — | Gravação de áudio |
|
|
|
|
### Backend
|
|
| Tecnologia | Versão | Uso |
|
|
|------------|--------|-----|
|
|
| FastAPI | 0.110+ | Framework API |
|
|
| SQLAlchemy | 2.x | ORM |
|
|
| Alembic | 1.x | Migrações de banco |
|
|
| PostgreSQL | 14+ | Banco de dados |
|
|
| Celery | 5.x | Processamento assíncrono |
|
|
| Redis | 7+ | Broker/Cache |
|
|
| httpx | 0.27+ | Cliente HTTP assíncrono |
|
|
|
|
### Diarização & IA
|
|
| Tecnologia | Uso |
|
|
|------------|-----|
|
|
| Whisper.cpp | Transcrição de áudio (GPU) |
|
|
| SpeechBrain ECAPA-TDNN | Diarização de speakers |
|
|
| pyannote.audio | Diarização (fallback) |
|
|
| librosa | Processamento de áudio |
|
|
| deepseek-v3.1 | Análise e resumo de reuniões |
|
|
|
|
### Infraestrutura
|
|
| Tecnologia | Uso |
|
|
|------------|-----|
|
|
| Podman | Containerização |
|
|
| Nginx | Reverse proxy / Servir frontend |
|
|
| systemd | Gerenciamento de serviços |
|
|
| Keycloak | SSO / Autenticação |
|
|
|
|
---
|
|
|
|
## 📄 Licença
|
|
|
|
Proprietário — ASAP Telecom. Todos os direitos reservados.
|
|
|
|
---
|
|
|
|
<p align="center">Desenvolvido com ❤️ pela equipe ASAP Telecom</p>
|