Projeto de RAG com Arquitetura MCP
Aplicação de Busca Aumentada por Geração (RAG) para consulta de documentos, reestruturada com a arquitetura Memory, Controller, Policy (MCP) para maior clareza, manutenibilidade e escalabilidade.
Relatório de Melhorias: Da Arquitetura Inicial para MCP
1. Estado Inicial do Projeto
O projeto inicial já era funcional e implementava um fluxo RAG básico. No entanto, a arquitetura apresentava os seguintes desafios:
- Alto Acoplamento: A lógica de negócio, as chamadas à API do Pinecone e a formatação de prompts para o LLM estavam misturadas nos mesmos arquivos de rota da API (ex:
llm_router.py). - Dificuldade de Manutenção: Qualquer alteração, como a troca do modelo de embedding ou a adição de uma nova regra de negócio, exigiria modificar múltiplos arquivos e funções interligadas.
- Baixa Escalabilidade: Adicionar novos fluxos, como um histórico de conversas ou regras de acesso mais complexas, seria complicado e tornaria o código progressivamente mais confuso.
2. Solução Implementada (Arquitetura MCP)
Para resolver esses desafios, o projeto foi refatorado para adotar o padrão de arquitetura Memory, Controller, Policy (MCP), que separa claramente as responsabilidades do sistema.
Componentes da Arquitetura MCP:
-
Memory(Memória):- Responsabilidade: Gerenciar o estado e o conhecimento de longo prazo do sistema.
- Implementação: A pasta
memory/e o arquivopinecone_memory.pyagora centralizam toda a interação com o banco de dados vetorial (Pinecone). Qualquer operação de busca ou salvamento de documentos passa por esta camada.
-
Policy(Política):- Responsabilidade: Aplicar regras de negócio, validações e restrições.
- Implementação: A pasta
policy/e o arquivopolicy.pycontêm a lógica para validar perguntas, filtrar resultados com base em score de relevância, ou aplicar quaisquer outras regras de negócio (ex: anonimização de dados, controle de acesso).
-
Controller(Controlador):- Responsabilidade: Orquestrar todo o fluxo de uma requisição. Ele atua como o "cérebro" da operação.
- Implementação: A pasta
controller/e o arquivocontroller.pyrecebem a requisição, utilizam aMemorypara buscar o contexto, aplicam as regras daPolicye, finalmente, montam o prompt e chamam o LLM (Gemini) para gerar a resposta.
3. Principais Vantagens da Nova Arquitetura
- Separação de Responsabilidades: Cada componente tem um único trabalho, tornando o código mais limpo e fácil de entender.
- Facilidade de Manutenção: Precisa trocar o Pinecone por outro banco vetorial? Modifique apenas a camada de
Memory. Quer adicionar novas regras de negócio? Trabalhe apenas na camada dePolicy. - Escalabilidade: É simples adicionar novas funcionalidades. Por exemplo, para implementar um histórico de conversas, basta expandir a camada de
Memorye ajustar oControllerpara usá-lo. - Testabilidade: Cada camada (Memory, Controller, Policy) pode ser testada de forma isolada, garantindo maior qualidade e confiabilidade do código.
Diagrama da Nova Arquitetura
graph TD
subgraph "API Layer"
A[FastAPI: /mcp/ask]
end
subgraph "Application Core (MCP)"
B[Controller]
C[Policy]
D[Memory]
end
subgraph "External Services"
E[Pinecone DB]
F[Gemini LLM]
end
A -- Requisição --> B
B -- Aplica Regras --> C
B -- Busca Contexto --> D
D <--> E
B -- Gera Resposta --> F
F -- Resposta --> B
B -- Resposta Final --> A
Como Configurar e Rodar o Projeto
Pré-requisitos
- Python 3.9+
- Conta no Pinecone
- Chave de API da Google (Gemini)
1. Crie o Ambiente Virtual
python -m venv venv
2. Ative o Ambiente Virtual
- Windows (PowerShell):
.\venv\Scripts\activate - Linux/macOS:
source venv/bin/activate
3. Instale as Dependências
pip install -r requirements.txt
4. Configure as Variáveis de Ambiente
- Renomeie o arquivo
.env.examplepara.env. - Abra o arquivo
.enve preencha com suas chaves de API:PINECONE_API_KEY="SUA_CHAVE_PINECONE" PINECONE_HOST="SEU_HOST_PINECONE" PINECONE_INDEX_NAME="brito-ai" GEMINI_API_KEY="SUA_CHAVE_GEMINI"
5. Rodar o Back-End
uvicorn api_mcp:app --reload --host 0.0.0.0 --port 8000
6. Rodar o Front-End
cd frontend
npm run dev
7. Rode o Servidor da API
uvicorn api_mcp:app --reload
O servidor estará disponível em http://127.0.0.1:8000/docs.
Como Usar a API
- Acesse a documentação interativa no seu navegador: http://127.0.0.1:8000/docs.
- Encontre o endpoint
POST /mcp/ask. - Clique em "Try it out".
- Preencha o corpo da requisição com sua pergunta. Exemplo:
{ "pergunta": "Quais são as principais cláusulas do contrato de aluguel?", "max_results": 3 } - Clique em "Execute" para ver a resposta gerada pelo sistema.