Bot SIBS — Vitória AI

Assistente virtual interno para consulta de documentação através de uma interface de chat. O projeto utiliza uma arquitetura RAG (Retrieval-Augmented Generation): pesquisa os excertos mais relevantes dos documentos e envia esse contexto para um modelo de linguagem local, que produz uma resposta curta em português e identifica as fontes consultadas.

Funcionalidades

  • Interface de chat desenvolvida em Angular 18;
  • API REST desenvolvida com FastAPI;
  • pesquisa semântica multilingue com Sentence Transformers;
  • indexação e pesquisa vetorial com FAISS;
  • respostas geradas por um servidor compatível com a API do llama.cpp;
  • apresentação do documento, categoria, chunk_id e distância de cada fonte;
  • suporte a documentos digitalizados através do processo auxiliar de OCR.

Arquitetura

Utilizador
    │
    ▼
Frontend Angular (:4200)
    │  POST /perguntar
    ▼
API FastAPI (:8000)
    ├── Sentence Transformer ──► índice FAISS
    │                              │
    │                              ▼
    │                       excertos relevantes
    │
    └── contexto + pergunta ──► servidor llama.cpp ──► resposta

Estrutura do projeto

Bot SIBS/
├── app.py                         # API FastAPI e fluxo RAG
├── dataset_chunks.json            # Conteúdo e metadados dos excertos
├── embeddings.npy                 # Embeddings gerados durante a indexação
├── indice_documentos.faiss        # Índice vetorial usado pela API
├── pdfs/                           # Documentos de origem
├── Scripts/
│   ├── Classificador.ipynb        # Extração, divisão e indexação documental
│   └── OCR.ipynb                  # Tratamento OCR de PDFs digitalizados
└── Frontend/angular-internal-chat/ # Aplicação Angular

Pré-requisitos

  • Python 3.10 ou superior;
  • Node.js 18.19 ou superior e npm;
  • servidor llama.cpp, ou outro servidor com endpoint compatível com OpenAI Chat Completions;
  • ficheiros dataset_chunks.json e indice_documentos.faiss gerados e compatíveis entre si.

Para voltar a processar documentos digitalizados são também necessários Tesseract OCR, o idioma português do Tesseract e Ghostscript. Estes componentes não são necessários para executar o chat com um índice já criado.

Instalação

1. Backend

Na raiz do projeto, crie e ative um ambiente virtual:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Instale as dependências:

python -m pip install fastapi "uvicorn[standard]" requests pandas numpy faiss-cpu sentence-transformers

Na primeira execução, o Sentence Transformers poderá descarregar o modelo sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2.

2. Frontend

Set-Location .\Frontend\angular-internal-chat
npm install

Configuração

Antes de iniciar a aplicação, reveja as constantes no início de app.py:

INDEX_PATH = r"D:\Trabalhos\Bot SIBS\indice_documentos.faiss"
CHUNKS_PATH = r"D:\Trabalhos\Bot SIBS\dataset_chunks.json"
LLAMA_URL = "http://192.168.1.39:8089/v1/chat/completions"
MODEL_NAME = "Qwen3-1.7B-Q4_K_M.gguf"
  • INDEX_PATH: caminho para o índice FAISS;
  • CHUNKS_PATH: caminho para o dataset de excertos;
  • LLAMA_URL: endpoint de Chat Completions do servidor do modelo;
  • MODEL_NAME: nome do modelo disponibilizado pelo servidor.

O endereço da API utilizado pelo frontend encontra-se em:

Frontend/angular-internal-chat/src/environments/environment.ts

Por defeito, o frontend comunica com http://127.0.0.1:8000/perguntar e aguarda até 240 segundos por uma resposta.

Execução

1. Iniciar o servidor do modelo

Inicie o llama.cpp com o modelo configurado e confirme que o endpoint definido em LLAMA_URL está acessível.

2. Iniciar o backend

Execute na raiz do projeto:

python -m uvicorn app:app --reload --host 127.0.0.1 --port 8000

Verifique o estado da API em http://127.0.0.1:8000/. A resposta esperada é:

{"status": "ok"}

A documentação interativa fica disponível em http://127.0.0.1:8000/docs.

3. Iniciar o frontend

Noutro terminal:

Set-Location .\Frontend\angular-internal-chat
npm start

Abra http://localhost:4200 no browser.

API

POST /perguntar

Pedido:

{
  "pergunta": "Como validar a receção dos webservices?"
}

Resposta:

{
  "pergunta": "Como validar a receção dos webservices?",
  "resposta": "Resposta produzida com base nos documentos...",
  "fontes": [
    {
      "nome_pdf": "Manual_Outs_EDP_VF.pdf",
      "categoria": "Outros",
      "chunk_id": 3,
      "score_distancia": 12.34
    }
  ]
}

Exemplo em PowerShell:

$body = @{ pergunta = "Como validar a receção dos webservices?" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/perguntar" -ContentType "application/json" -Body $body

Atualização da base documental

O notebook Scripts/Classificador.ipynb contém o processo de extração de texto, divisão em excertos, criação de embeddings e geração do índice FAISS. O notebook Scripts/OCR.ipynb trata previamente PDFs sem texto pesquisável.

Depois de processar novos documentos:

  1. copie dataset_chunks.json e indice_documentos.faiss para os caminhos configurados no backend;
  2. mantenha os dois ficheiros sincronizados, pois a posição de cada vetor corresponde à respetiva linha do dataset;
  3. reinicie a API para carregar o novo índice e os novos excertos.

Author

José Garcia
Data Scientist
Process Digitalization & Automation

S
Description
No description provided
Readme 7.9 GiB
Languages
Jupyter Notebook 100%