diff --git a/README.md b/README.md new file mode 100644 index 00000000..15ccf5c0 --- /dev/null +++ b/README.md @@ -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 . A resposta esperada é: + +```json +{"status": "ok"} +``` + +A documentação interativa fica disponível em . + +### 3. Iniciar o frontend + +Noutro terminal: + +```powershell +Set-Location .\Frontend\angular-internal-chat +npm start +``` + +Abra 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. + + +