Adicionar README.md

This commit is contained in:
2026-08-28 12:09:59 +00:00
parent 9fcd4ed179
commit 40e93f56c4
+209
View File
@@ -0,0 +1,209 @@
# 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
```text
Utilizador
│
▼
Frontend Angular (:4200)
│ POST /perguntar
▼
API FastAPI (:8000)
├── Sentence Transformer ──► índice FAISS
│ │
│ ▼
│ excertos relevantes
│
└── contexto + pergunta ──► servidor llama.cpp ──► resposta
```
## Estrutura do projeto
```text
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:
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```
Instale as dependências:
```powershell
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
```powershell
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`:
```python
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:
```text
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:
```powershell
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 é:
```json
{"status": "ok"}
```
A documentação interativa fica disponível em <http://127.0.0.1:8000/docs>.
### 3. Iniciar o frontend
Noutro terminal:
```powershell
Set-Location .\Frontend\angular-internal-chat
npm start
```
Abra <http://localhost:4200> no browser.
## API
### `POST /perguntar`
Pedido:
```json
{
"pergunta": "Como validar a receção dos webservices?"
}
```
Resposta:
```json
{
"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:
```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.
## Notas de segurança e produção
- O CORS está atualmente aberto a todas as origens (`allow_origins=["*"]`); restrinja-o antes de disponibilizar a aplicação numa rede não controlada.
- Os caminhos e o endereço do modelo estão fixos em `app.py`; para implantação, recomenda-se movê-los para variáveis de ambiente.
- A API não possui autenticação nem limitação de pedidos.
- O histórico enviado pela interface ainda não é utilizado pelo backend na geração da resposta.
- Os documentos e índices podem conter informação interna; não os publique num repositório público.
## Resolução de problemas
**O frontend indica que não consegue ligar ao backend**
Confirme que o Uvicorn está ativo na porta `8000` e que `apiUrl` está correto no ficheiro de ambiente do Angular.
**A API devolve `Erro llama.cpp`**
Confirme o endereço em `LLAMA_URL`, o nome em `MODEL_NAME` e se o servidor do modelo aceita pedidos em `/v1/chat/completions`.
**O backend falha ao arrancar**
Confirme os caminhos de `INDEX_PATH` e `CHUNKS_PATH`, bem como a instalação de `faiss-cpu` e `sentence-transformers`.
**As respostas não correspondem aos documentos**
Volte a gerar o dataset e o índice em conjunto e confirme que foi usado o mesmo modelo de embeddings configurado no backend.