Ativando a busca semântica

A busca de texto completo (FTS) no Notarium funciona sempre, sem nenhuma configuração. A busca semântica (vetorial) é um recurso opcional: ela acrescenta ranqueamento híbrido por significado, mas puxa uma pilha nativa pesada (onnxruntime + sqlite-vec, ~660 MB em disco) e um modelo de embeddings local que é baixado na primeira ativação (~600 MB em disco e centenas de MB de RAM). Por isso ela vem desligada por padrão e é ativada de forma deliberada. Para entender como a busca funciona por dentro, veja Conceitos: busca.

Dois interruptores independentes

Vale a pena separar dois níveis — instalação e execução:

Instalação — se a pilha vetorial nativa está presente em node_modules. A imagem Docker sempre a inclui, então ativá-la dentro do contêiner não exige nenhuma reconstrução. Ao rodar a partir do código-fonte, o make deps padrão não a instala (um node_modules local fica ~660 MB mais leve) — para trabalhar com vetores localmente é preciso usar make deps-vector.
Execução — a variável VECTOR_SEARCH. Na imagem publicada ela vem como off por padrão.

Para a busca semântica no Docker, basta acionar o interruptor de execução — a pilha já está no lugar.

Como ativar

docker run -d --name notarium \
  -p 3000:3000 \
  -v notarium-data:/data \
  -e VECTOR_SEARCH=on \
  docouno/notarium:latest

(Um único volume /data guarda todo o estado — o banco de metadados, os índices, suas notas, os artefatos de exportação; o mesmo de uma execução comum, veja Instalação. Aqui só se acrescenta VECTOR_SEARCH=on.)

Na primeira ativação, o modelo padrão (bge-m3) é baixado (~600 MB em disco) e usa centenas de MB de RAM. A indexação roda em segundo plano: a busca de texto completo fica disponível na hora, enquanto os vetores ainda estão sendo processados.

Níveis de modelo

O modelo é escolhido pelo par EMBED_MODEL + EMBED_DIMENSIONS (a dimensionalidade precisa coincidir com a do modelo) — é uma configuração de execução sobre uma única imagem, não uma build separada:

Nível	Variáveis	RAM	Quando
off	`VECTOR_SEARCH=off`	0	Uma máquina fraca, ou quando a busca por palavras-chave já basta. O padrão da imagem.
compact	`VECTOR_SEARCH=on`, `EMBED_MODEL=Xenova/multilingual-e5-small`, `EMBED_DIMENSIONS=384`	~120 MB	Homelab, um VPS pequeno.
full	`VECTOR_SEARCH=on` (padrões: bge-m3, 1024)	~600 MB	Uma máquina potente; mais de 100 idiomas, contexto longo.

Modelos e5 assimétricos

O nível compact (e5) exige os prefixos EMBED_QUERY_PREFIX="query: " e EMBED_PASSAGE_PREFIX="passage: " — esquecê-los degrada silenciosamente a qualidade da busca. Para o bge-m3 simétrico vale o contrário: você não deve definir os prefixos.

Recursos em uma máquina modesta

Em um host sem swap e com ~6 GB de RAM, a indexação inicial do bge-m3 pode esbarrar no teto de memória. Duas alavancas: use o nível compact (e5-small), ou defina EMBED_CPU_MEM_ARENA=off — isso mantém o consumo em torno de ~1,9 GB ao custo de uma pequena lentidão. Para a lista completa dos parâmetros de embedding, veja a Referência.

Recorrendo à busca de texto completo

Se VECTOR_SEARCH=off, ou se a pilha nativa deixar de carregar por qualquer motivo, a busca continua funcionando sobre o texto completo — sem erro, e os resultados têm a mesma aparência. A busca semântica é um canal de ranqueamento a mais, por cima da FTS que está sempre ativa, e não uma dependência obrigatória. Uma instância sem vetores é uma instância plenamente funcional.