You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
279 lines
11 KiB
Markdown
279 lines
11 KiB
Markdown
# 🤖 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 (Tools)** | PostgreSQL | Banco relacional para metadados de ferramentas |
|
|
| **Banco Fictício (Mock)** | MySQL | Dados de negócio simulados usados pelos handlers |
|
|
| **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
|
|
│ │ └── handlers.py # Handlers consultando MySQL fictício
|
|
│ │
|
|
│ ├── 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 MySQL fictício │
|
|
└──────┬───────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────┐
|
|
│ 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.
|
|
|
|
---
|
|
|
|
## Telegram Satellite Service
|
|
|
|
Foi adicionado um servico satelite dedicado ao Telegram.
|
|
|
|
Arquivos principais:
|
|
|
|
- `app/integrations/telegram_satellite_service.py`: interface Telegram via long polling, chamando o `OrquestradorService`
|
|
|
|
Como executar:
|
|
|
|
```bash
|
|
python -m app.integrations.telegram_satellite_service
|
|
```
|
|
|
|
Variaveis necessarias:
|
|
|
|
- `TELEGRAM_BOT_TOKEN`
|
|
- `TELEGRAM_POLLING_TIMEOUT` (opcional, padrao `30`)
|
|
- `TELEGRAM_REQUEST_TIMEOUT` (opcional, padrao `45`)
|