vitor
/
orquestrador
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(readme): Reescrever README com visão, stack e arquitetura

Browse Source 
- Documento reorganizado para apresentação profissional do projeto
- Adiciona explicação de arquitetura, stack e fluxos
main
Vitor Hugo Belorio Simão 2 months ago
parent 88a49571da
commit 6486dc1ff6
1 changed files with 256 additions and 0 deletions
Show Stats Download Patch File Download Diff File

256
README.md
Unescape Escape View File

@ -0,0 +1,256 @@
# 🤖 AI Orquestrador
Um sistema inteligente de orquestração de ferramentas que utiliza inteligência artificial para processar pedidos de clientes e executar ações automaticamente. Utilizando o poder do Google Vertex AI e Gemini, o sistema compreende intenções naturais e chama as ferramentas apropriadas para resolver cada solicitação.
---
## 📖 Visão Geral
AI Orquestrador é um MVP (Produto Mínimo Viável) que demonstra como integrar um modelo de linguagem avançado com um conjunto de ferramentas específicas do domínio para criar uma experiência conversacional inteligente.
**Fluxo de funcionamento:**
1. Cliente envia uma mensagem descrevendo uma ação desejada
2. O sistema envia a mensagem e lista de ferramentas disponíveis ao modelo de IA
3. A IA analisa a solicitação e decide qual ferramenta chamar (se necessário)
4. O sistema extrai parâmetros da mensagem e executa a ferramenta
5. Resultado é formatado e retornado ao cliente de forma natural
**Exemplo prático:**
```
Cliente: "Gostaria de comprar um carro de até 50000 reais que seja sedan"
↓
IA decide: chamar ferramenta "consultar_estoque"
↓
Sistema busca no banco de dados
↓
Retorna: "Encontrei 5 veículos sedans disponíveis até R$ 50.000..."
```
---
## 🛠️ Stack Tecnológico
| Componente | Tecnologia | Descrição |
| ------------------- | ------------------ | ------------------------------------------------ |
| **Backend** | FastAPI | Framework web moderno e rápido para APIs Python |
| **IA/LLM** | Google Vertex AI | Plataforma de IA empresarial com Gemini 1.5 Pro |
| **Banco de Dados** | PostgreSQL | Banco relacional robusto para dados estruturados |
| **Dados de Teste** | Mockaroo | Geração de dados fictícios para simulação |
| **Containerização** | Docker | Isolamento e deploy consistente |
| **Orquestração** | Google Cloud Build | Pipeline automatizado de build e deploy |
| **Computação** | Google Cloud Run | Plataforma serverless escalável |
| **Runtime** | Python 3.11+ | Linguagem principal da aplicação |
---
## 🏗️ Arquitetura do Projeto
```
Orquestrador/
├── app/
│ ├── main.py # Ponto de entrada da aplicação FastAPI
│ │
│ ├── api/
│ │ ├── routes.py # Endpoints principais (Chat, Health)
│ │ ├── tool_routes.py # Endpoints de gerenciamento de ferramentas
│ │ └── schemas.py # Modelos Pydantic para validação
│ │
│ ├── core/
│ │ └── settings.py # Configurações e variáveis de ambiente
│ │
│ ├── db/
│ │ ├── database.py # Conexão e declaração SQLAlchemy
│ │ ├── models.py # Modelos ORM do banco de dados
│ │ ├── init_db.py # Inicialização de banco
│ │ └── tool_seed.py # Dados iniciais de ferramentas
│ │
│ ├── services/
│ │ ├── orquestrador_service.py # Lógica principal de orquestração
│ │ ├── llm_service.py # Integração com Vertex AI / Gemini
│ │ ├── tool_registry.py # Registro e descoberta de ferramentas
│ │ ├── handlers.py # Handlers de execução de tools
│ │ └── mockaroo_client.py # Cliente para gerar dados fictícios
│ │
│ ├── repositories/
│ │ └── tool_repository.py # Acesso a dados de ferramentas
│ │
│ └── integrations/ # Integrações externas
│
├── Dockerfile # Imagem Docker da aplicação
├── cloudbuild.yaml # Configuração CI/CD (Cloud Build)
├── docker-compose.yml # Stack local com PostgreSQL
├── deploy.sh # Script de deploy no Cloud Run
├── requirements.txt # Dependências Python
├── .env.example # Exemplo de configuração
└── README.md # Esta documentação
```
---
## 🛠️ Ferramentas Disponíveis
O sistema possui as seguintes ferramentas pré-configuradas:
| Ferramenta | Descrição |
| ------------------------- | ------------------------------------------------- |
| **consultar_estoque** | Busca veículos por critérios de preço e categoria |
| **validar_cliente_venda** | Verifica aprovação de crédito do cliente |
| **avaliar_veiculo_troca** | Calcula valor estimado de troca de veículo |
| **agendar_revisao** | Agenda manutenção e revisão de veículo |
| **cancelar_pedido** | Cancela pedido existente do cliente |
---
## 🚀 Tecnologias em Detalhes
### FastAPI
Framework web de alto desempenho construído sobre Starlette. Oferece validação automática de dados com Pydantic, documentação interativa (Swagger/OpenAPI) e tipagem forte em Python.
### Google Vertex AI + Gemini
Plataforma de IA gerenciada do Google Cloud que permite usar modelos de linguagem avançados como o Gemini 1.5 Pro. Oferece segurança, escalabilidade e integração nativa com o ecossistema Google Cloud.
### PostgreSQL
Banco de dados relacional de código aberto com suporte a JSON, transações ACID e extensibilidade. Ideal para estruturar dados de ferramentas e histórico de interações.
### Docker
Containerização da aplicação garantindo consistência entre ambientes de desenvolvimento, teste e produção.
### Google Cloud Build + Cloud Run
Pipeline CI/CD totalmente gerenciado que faz build da imagem, realiza testes e faz deploy automático no Cloud Run (plataforma serverless que escala automaticamente conforme a demanda).
---
## 📊 Fluxograma de Funcionamento
```
┌─────────────┐
│ Cliente │ "Comprar carro por até 50mil"
└──────┬──────┘
│
▼
┌──────────────────────────┐
│ Endpoint /chat (POST) │
└──────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ OrquestradorService │
│ - Processa mensagem │
│ - Busca ferramentas disponíveis │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ LLMService (Vertex AI) │
│ - Envia ao Gemini 1.5 Pro │
│ - Recebe decisão de tool │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Tool Handlers │
│ - Executa: consultar_estoque │
│ - Busca no PostgreSQL │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Formata Resposta │
│ - Estrutura resultado │
│ - Retorna ao cliente │
└──────┬───────────────────────────┘
│
▼
┌──────────────────┐
│ Cliente │ Resultado formatado
└──────────────────┘
```
---
## 🔐 Segurança
O sistema foi construído com foco em boas práticas de segurança:
- **Variáveis sensíveis**: Armazenadas em `.env` e variáveis de ambiente, nunca commitadas
- **Autenticação Google Cloud**: Utiliza credenciais de serviço (service account) com roles específicas
- **Isolamento de banco de dados**: Credenciais separadas por ambiente
- **Validação de dados**: Pydantic garante tipagem e validação em todos os endpoints
- **CORS**: Configurável para ambientes específicos
- **Cloud Run**: Ambiente gerenciado com certificados SSL automáticos
---
## 📝 Como Usar
Para mais detalhes sobre instalação, configuração e uso, consulte os documentos:
- [GUIA_COMPLETO_CONFIGURE_E_DEPLOY.md](GUIA_COMPLETO_CONFIGURE_E_DEPLOY.md) - Setup completo do Google Cloud
- [CLOUD_SQL_PROXY.md](CLOUD_SQL_PROXY.md) - Configuração de Cloud SQL Proxy
- [TEST_CASES.md](TEST_CASES.md) - Casos de teste e exemplos
---
## 📚 Estrutura de Dados
### Tabela: tools
Armazena metadados das ferramentas disponíveis:
- Nome e descrição
- Parâmetros obrigatórios e opcionais
- Endpoint correspondente
- Estado (ativa/inativa)
### Histórico de Interações
Logs de todas as chamadas para fins de auditoria e análise.
---
## 🌐 APIs Disponíveis
| Método | Endpoint | Descrição |
| ------ | --------- | ---------------------------------- |
| POST | `/chat` | Enviar mensagem e processar com IA |
| GET | `/docs` | Documentação interativa (Swagger) |
| GET | `/health` | Status da aplicação |
| GET | `/tools` | Listar ferramentas disponíveis |
| POST | `/tools` | Registrar nova ferramenta |
---
## 📈 Monitoramento na Produção
Quando implantado no Google Cloud Run, o sistema aproveita:
- **Cloud Logging**: Logs centralizados e estruturados
- **Cloud Monitoring**: Métricas de CPU, memória, latência e requisições
- **Cloud Trace**: Rastreamento distribuído para análise de performance
---
## 🔄 Próximas Melhorias
O projeto está em evolução contínua com planos para:
- Autenticação e autorização de usuários
- Rate limiting e proteção contra abuso
- Persistência de histórico de conversa
- Analytics de uso de ferramentas
- Testes end-to-end automatizados
- Suporte a múltiplos modelos de IA
- Dashboard de administração
---
## 📧 Contato
Para dúvidas, sugestões ou contribuições, entre em contato com o time de desenvolvimento.
Write Preview
Loading…
Cancel
Save