187 lines
5.6 KiB
Markdown
187 lines
5.6 KiB
Markdown
# 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.
|
|
|
|
|