Adicionar README.md
This commit is contained in:
@@ -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.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user