---
title: "Ativando a busca semântica"
description: "Busca vetorial opcional: pilha nativa pesada, o interruptor VECTOR_SEARCH, níveis de modelo e fallback para texto completo sem perda de serviço."
---

# 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](/docs/concepts/search/).

## Dois interruptores independentes

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

1. **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`.
2. **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

```bash
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](/docs/self-hosting/install/). 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. |

> [!warning] 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](/docs/reference/environment-variables/).

## 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.