feat: add Docker Compose, environment template and README
This commit is contained in:
omp committed
1 parent
7f4d4bde66
commit
b25bf8ff7d
4 files changed
+412
No files matched your search
@@ -0,0 +1,237 @@
|
||||
# Pastor Online
|
||||
|
||||
Sistema web RAG para consulta bíblica. Lê PDFs da Bíblia, indexa o conteúdo em um
|
||||
banco vetorial e responde em chat com um agente pastoral **ancorado exclusivamente nos
|
||||
versículos recuperados** — com as referências sempre à vista.
|
||||
|
||||
Containerizado com Docker Compose: frontend React, backend FastAPI, ChromaDB e
|
||||
(opcionalmente) Ollama local.
|
||||
|
||||
---
|
||||
|
||||
## Como funciona
|
||||
|
||||
```
|
||||
./PDF/*.pdf ──▶ PyMuPDF + OCR (Tesseract) ──▶ parser bíblico ──▶ embeddings
|
||||
│
|
||||
navegador ◀── SSE ── FastAPI ◀── busca + validação
|
||||
│
|
||||
ChromaDB
|
||||
```
|
||||
|
||||
**Fidelidade ao texto.** A resposta só é gerada quando há evidência recuperada do
|
||||
corpus. As citações são conferidas no servidor contra as fontes consultadas: uma
|
||||
referência que o modelo inventou é removida **antes** de chegar à tela. Sem evidência,
|
||||
o sistema responde com uma mensagem fixa e não chama o LLM.
|
||||
|
||||
**Extração.** Se a camada textual do PDF é utilizável, ela é usada (rápido). Se o PDF
|
||||
usa fontes sem mapeamento Unicode — caso comum em PDFs de Bíblia digitalizados — o
|
||||
sistema detecta a corrupção e aplica OCR na página. O resultado do OCR é cacheado por
|
||||
página: reindexações não repetem o trabalho.
|
||||
|
||||
---
|
||||
|
||||
## Requisitos
|
||||
|
||||
- Docker com Compose v2 (ou Podman com `podman-compose`)
|
||||
- ~2 GB de RAM livres para o backend
|
||||
- ~1,5 GB de disco para o modelo de embeddings e o banco vetorial
|
||||
|
||||
---
|
||||
|
||||
## Início rápido
|
||||
|
||||
### 1. Coloque os PDFs
|
||||
|
||||
Copie seus PDFs da Bíblia para a pasta **`./PDF`**. O diretório já contém o
|
||||
`biblia.pdf` desta edição da Almeida Revista e Corrigida.
|
||||
|
||||
> A pasta `./pdfs` (minúscula) também funciona: basta apontar `PDF_DIR` para ela no
|
||||
> `docker-compose.yml`. O Compose monta `./PDF` como somente-leitura em `/data/pdfs`.
|
||||
|
||||
### 2. Configure o provedor de LLM
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edite o `.env`. Três caminhos possíveis:
|
||||
|
||||
| Provedor | Configuração | Observação |
|
||||
|---|---|---|
|
||||
| **Ollama** (local) | `LLM_PROVIDER=ollama` | Subir com `--profile local`; o modelo é baixado na primeira execução |
|
||||
| **OpenAI** | `LLM_PROVIDER=openai` + `OPENAI_API_KEY` | |
|
||||
| **Groq** | `LLM_PROVIDER=groq` + `GROQ_API_KEY` | |
|
||||
| **Anthropic** | `LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY` | |
|
||||
|
||||
### 3. Suba o sistema
|
||||
|
||||
```bash
|
||||
# Com Ollama local:
|
||||
docker compose --profile local up --build -d
|
||||
|
||||
# Sem Ollama (usando OpenAI, Groq ou Anthropic):
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
Acesse **http://localhost:8080**.
|
||||
|
||||
### 4. Acompanhe a indexação
|
||||
|
||||
A primeira indexação faz OCR de todas as páginas do PDF — são ~3.400 páginas, e o
|
||||
tempo típico fica entre 15 e 30 minutos em CPU. O painel lateral mostra o progresso
|
||||
(PDFs lidos e vetores indexados) e o chat já responde durante a indexação.
|
||||
|
||||
Para acompanhar os logs:
|
||||
|
||||
```bash
|
||||
docker compose logs -f backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comandos úteis
|
||||
|
||||
```bash
|
||||
# Reiniciar só o frontend (após mudanças no React)
|
||||
docker compose up -d --build frontend
|
||||
|
||||
# Forçar a reindexação dos PDFs
|
||||
curl -X POST http://localhost:8080/api/reindex
|
||||
|
||||
# Ver o estado da indexação
|
||||
curl http://localhost:8080/api/status
|
||||
|
||||
# Rodar os testes do backend
|
||||
docker compose exec backend pytest tests/ -v
|
||||
|
||||
# Rodar os testes do frontend
|
||||
docker compose exec frontend npm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
| Rota | Método | Descrição |
|
||||
|---|---|---|
|
||||
| `/api/health` | GET | Saúde do serviço |
|
||||
| `/api/status` | GET | PDFs lidos, vetores indexados, erros |
|
||||
| `/api/reindex` | POST | Força a reindexação (202). 409 se já em andamento |
|
||||
| `/api/chat` | POST | Chat em streaming (SSE) |
|
||||
| `/api/sources` | GET | Trechos consultados na última resposta |
|
||||
|
||||
O chat responde em Server-Sent Events:
|
||||
|
||||
```
|
||||
event: sources
|
||||
data: {"sources":[{"reference":"Gênesis 1:1","text":"...","page":6}]}
|
||||
|
||||
event: token
|
||||
data: {"text":"No princípio criou Deus os céus e a terra..."}
|
||||
|
||||
event: done
|
||||
data: {"citations":["Gênesis 1:1"]}
|
||||
```
|
||||
|
||||
O frontend consome o stream com `fetch` + `ReadableStream`, porque `EventSource` não
|
||||
aceita `POST`.
|
||||
|
||||
---
|
||||
|
||||
## Configuração
|
||||
|
||||
Todas as variáveis ficam no `.env`. As principais:
|
||||
|
||||
| Variável | Padrão | Efeito |
|
||||
|---|---|---|
|
||||
| `LLM_PROVIDER` | `ollama` | `ollama`, `openai`, `groq` ou `anthropic` |
|
||||
| `EMBEDDING_MODEL` | `paraphrase-multilingual-MiniLM-L12-v2` | `all-MiniLM-L6-v2` é menor e mais rápido |
|
||||
| `TOP_K` | `6` | Quantos trechos são recuperados por pergunta |
|
||||
| `MIN_SIMILARITY` | `0.35` | Corte de relevância; acima disso, o sistema responde que o texto não aborda o assunto |
|
||||
| `OCR_DPI` | `200` | Resolução do OCR |
|
||||
| `OCR_LANGUAGE` | `por+eng` | Idiomas do Tesseract |
|
||||
| `REINDEX_TOKEN` | vazio | Se preenchido, `/api/reindex` exige o header `X-Reindex-Token` |
|
||||
| `CORS_ORIGINS` | `http://localhost:8080` | Origens permitidas |
|
||||
| `AUTO_INDEX` | `true` | Indexa automaticamente na inicialização |
|
||||
|
||||
---
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
**A indexação não termina / fica em "Indexando".**
|
||||
O OCR é o gargalo. Verifique `docker compose logs backend`. Se o OCR estiver lento,
|
||||
aumente `OCR_DPI` não ajuda — reduza para 150 para acelerar, com perda de acurácia.
|
||||
Para retomar após uma interrupção, basta reiniciar o container: o cache de OCR é
|
||||
preservado no volume e só as páginas faltantes são reprocessadas.
|
||||
|
||||
**O chat responde que o texto "não aborda diretamente o assunto".**
|
||||
O índice pode estar vazio (`/api/status`) ou a pergunta pode estar longe do corpus.
|
||||
Reduza `MIN_SIMILARITY` para 0.25, ou increase `TOP_K` para 10. Verifique também se a
|
||||
pergunta cita uma referência explícita — nesse caso a busca é determinística e não
|
||||
depende do limiar.
|
||||
|
||||
**"Nenhum versículo pôde ser extraído".**
|
||||
O PDF pode não ser de uma Bíblia com capítulos e versículos numerados, ou o OCR
|
||||
pode ter falhado. Inspecione o cache de OCR em `/data/vector_db/ocr_cache/` para ver
|
||||
o texto que foi extraído de cada página.
|
||||
|
||||
**Ollama não sobe.**
|
||||
`docker compose --profile local up -d`. O serviço `ollama-pull` baixa o modelo
|
||||
indicado em `OLLAMA_MODEL` na primeira execução. Para outro modelo:
|
||||
`OLLAMA_MODEL=llama3.2:3b docker compose --profile local up -d`.
|
||||
|
||||
**Porta 8080 já em uso.**
|
||||
`FRONTEND_PORT=8090 docker compose up -d`. Atualize também `CORS_ORIGINS`.
|
||||
|
||||
---
|
||||
|
||||
## Estrutura do projeto
|
||||
|
||||
```
|
||||
.
|
||||
├── docker-compose.yml
|
||||
├── .env.example
|
||||
├── PDF/ # PDFs da Bíblia (entrada, somente-leitura)
|
||||
├── backend/
|
||||
│ ├── Dockerfile
|
||||
│ ├── requirements.txt
|
||||
│ ├── app/
|
||||
│ │ ├── config.py # settings via pydantic-settings
|
||||
│ │ ├── models.py # schemas da API
|
||||
│ │ ├── extraction.py # PDF → texto (PyMuPDF + OCR + cache)
|
||||
│ │ ├── bible_parser.py # livro / capítulo / versículo
|
||||
│ │ ├── embedding.py # sentence-transformers
|
||||
│ │ ├── vector_store.py # ChromaDB
|
||||
│ │ ├── indexer.py # manifesto incremental
|
||||
│ │ ├── llm.py # adaptadores Ollama/OpenAI/Groq/Anthropic
|
||||
│ │ ├── chat.py # contexto, validação de citações
|
||||
│ │ └── main.py # rotas FastAPI
|
||||
│ └── tests/
|
||||
├── frontend/
|
||||
│ ├── Dockerfile
|
||||
│ ├── nginx.conf
|
||||
│ └── src/
|
||||
│ ├── App.tsx
|
||||
│ ├── api.ts
|
||||
│ ├── lib/sse.ts
|
||||
│ └── components/
|
||||
└── docs/superpowers/ # design e plano de implementação
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Segurança
|
||||
|
||||
- As chaves de API vivem **apenas** no backend, via variáveis de ambiente. Nunca
|
||||
chegam ao bundle do navegador.
|
||||
- Os PDFs são montados somente-leitura; a escrita fica restrita ao volume `/data`.
|
||||
- O conteúdo indexado é entregue ao modelo como **dado delimitado**, nunca como
|
||||
instrução — o que neutraliza tentativas de prompt injection via corpus.
|
||||
- Mensagens acima de 4.000 caracteres são recusadas; o histórico é limitado às
|
||||
últimas 10 trocas.
|
||||
- O endpoint de reindexação rejeita chamadas concorrentes (409) e aceita um token
|
||||
opcional (`REINDEX_TOKEN`).
|
||||
|
||||
A aplicação é local, sem autenticação. Não a exponha à internet sem colocar um proxy
|
||||
com autenticação à frente.
|
||||
Reference in new issue
Block a user