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_ide 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.jsoneindice_documentos.faissgerados 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:
- copie
dataset_chunks.jsoneindice_documentos.faisspara os caminhos configurados no backend; - mantenha os dois ficheiros sincronizados, pois a posição de cada vetor corresponde à respetiva linha do dataset;
- reinicie a API para carregar o novo índice e os novos excertos.
Author
José Garcia
Data Scientist
Process Digitalization & Automation