backend/docs/setup.md

Setup — Backend

Pré-requisitos

• Node.js 18+ (ver engines.node no package.json)
• MySQL 8+ acessível na rede
• Qdrant rodando (padrão: http://localhost:6333)

• Ollama rodando com os modelos necessários:

  ollama pull nomic-embed-text
  ollama pull llama3.1
  

  Instalação

  cd backend
  npm install
  

Variáveis de ambiente

Crie o arquivo backend/.env com base nas variáveis abaixo:

Servidor

Variável	Descrição	Exemplo
PORT	Porta HTTP da API	3001
CORS_ORIGIN	Origem permitida pelo CORS	http://localhost:5173
API_KEY	Chave de API opcional	—
RATE_LIMIT_PER_MINUTE	Limite de requisições por minuto (0 desativa)	0

Banco de dados (MySQL)

Variável	Descrição	Exemplo
DB_HOST	Host do MySQL	localhost
DB_PORT	Porta do MySQL	3306
DB_USER	Usuário do banco	root
DB_PASS	Senha do banco	senha
DB_SCHEMA	Nome do schema/database	oracle

Qdrant (busca vetorial)

Variável	Descrição	Exemplo
QDRANT_URL	URL do Qdrant	http://localhost:6333
QDRANT_COLLECTION	Nome da collection (default no código: oraculo_docs)	empresa_docs
QDRANT_API_KEY	Chave de API do Qdrant (opcional)	—

Ollama (LLM local)

Variável	Descrição	Exemplo
OLLAMA_URL	URL do Ollama	http://localhost:11434
OLLAMA_EMBEDDINGS_MODEL	Modelo para embeddings	nomic-embed-text
OLLAMA_CHAT_MODEL	Modelo para chat	llama3.1
OLLAMA_VISION_MODEL	Modelo de visão (default llava:latest)	llava:latest

RAG

Variável	Descrição	Exemplo
RAG_QUERY_REWRITE	Reescrever query antes da busca, considerando o histórico da conversa (resolve follow-ups tipo "e o segundo caso?")	true
RAG_HISTORY_TOKEN_BUDGET	Tokens de histórico enviados ao LLM	1500
RAG_TOP_K	Número de chunks recuperados (default 8)	8
RAG_MIN_SCORE	Score mínimo de similaridade (default 0.40)	0.40
RAG_CHUNK_SIZE	Tamanho de cada chunk (caracteres)	900
RAG_CHUNK_OVERLAP	Sobreposição entre chunks	150
RAG_RERANK	Reordenar os chunks recuperados por relevância via LLM antes de montar o contexto	true
RAG_RERANK_TOP_N	Quantos chunks manter após o reranking (default = RAG_TOP_K)	8

LLM (parâmetros de geração)

Variável	Descrição	Exemplo
LLM_TEMPERATURE	Criatividade das respostas (0–1); baixo = mais fiel à fonte (default 0.2)	0.2
LLM_TOP_P	Nucleus sampling	0.9
LLM_NUM_PREDICT	Máximo de tokens gerados	2048
LLM_REPEAT_PENALTY	Penalidade de repetição	1.1

Autenticação (JWT)

Variável	Descrição	Exemplo
AUTH_MODE	Modo de auth (jwt ou none)	jwt
JWT_SECRET	Chave secreta para assinar tokens	trocar-em-producao
JWT_ISSUER	Issuer do token	oraculo-api
JWT_ACCESS_TTL_SECONDS	Duração do access token em segundos	900 (15 min)
JWT_REFRESH_TTL_SECONDS	Duração do refresh token em segundos	2592000 (30 dias)

Atenção: AUTH_MODE=none desativa a autenticação completamente. Nunca usar em produção.

Rodando localmente

# Criar as tabelas no banco (rodar uma vez ou após novas migrations)
npm run migrate:latest

# Modo desenvolvimento (hot reload)
npm run dev

# Modo produção
npm start

A API estará disponível em http://localhost:3001.

Para verificar o status dos serviços:

GET http://localhost:3001/health

Comandos disponíveis

Comando	Descrição
npm run dev	Inicia com hot reload (node --watch)
npm start	Inicia sem hot reload
npm run migrate:latest	Aplica todas as migrations pendentes
npm run migrate:rollback	Reverte a última migration
npm run seed:run	Executa os seeds do banco