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 arquivo pinecone_memory.py agora 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 arquivo policy.py contê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 arquivo controller.py recebem a requisição, utilizam a Memory para buscar o contexto, aplicam as regras da Policy e, finalmente, montam o prompt e chamam o LLM (Gemini) para gerar a resposta.

3. Principais Vantagens da Nova Arquitetura

1. Separação de Responsabilidades: Cada componente tem um único trabalho, tornando o código mais limpo e fácil de entender.

2. 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 de Policy.

3. Escalabilidade: É simples adicionar novas funcionalidades. Por exemplo, para implementar um histórico de conversas, basta expandir a camada de Memory e ajustar o Controller para usá-lo.

4. Testabilidade: Cada camada (Memory, Controller, Policy) pode ser testada de forma isolada, garantindo maior qualidade e confiabilidade do código.

Related MCP server: MCP-RAG Server

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.example para .env.

• Abra o arquivo .env e 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

1. Acesse a documentação interativa no seu navegador: http://127.0.0.1:8000/docs.

2. Encontre o endpoint POST /mcp/ask.

3. Clique em "Try it out".

4. 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
   }

5. Clique em "Execute" para ver a resposta gerada pelo sistema.