---
title: "Busca híbrida"
description: "A busca léxica sempre funciona; a semântica e o graph boost são opcionais e se fundem via RRF — sem essas camadas, ela continua de texto completo."
---

# Busca híbrida

A busca no Notarium é montada a partir de canais independentes que se complementam. A busca de texto completo (léxica) está sempre disponível e não exige configuração. A busca semântica (por significado) e a consideração dos vínculos do grafo são camadas opcionais sobre ela. Os resultados dos canais se fundem em um ranking único e, se as camadas opcionais estiverem indisponíveis, a busca continua funcionando sobre o texto completo — sem erro.

## Três canais

| Canal | O que faz | Quando funciona |
|---|---|---|
| Léxico (FTS/BM25) | Encontra ocorrências exatas de palavras e frases, classifica por BM25 | Sempre, sem configuração |
| Semântico (vetores) | Encontra o que é próximo em significado, mesmo sem palavras em comum | Opcional (`VECTOR_SEARCH`) |
| Graph boost | Traz os vizinhos de um acerto via `[[wiki-links]]` | Opcional (`GRAPH_BOOST`), desligado por padrão |

O canal léxico é a base: ele funciona logo após a inicialização, sem nada para instalar. O canal semântico acrescenta a compreensão do significado (sinônimos, paráfrases), e o graph boost acrescenta o conhecimento sobre os vínculos entre as notas.

## Como os resultados se fundem

Os canais são combinados pelo algoritmo **RRF** (Reciprocal Rank Fusion, k=60): cada canal produz a própria lista classificada, e o RRF os funde em um ranking compartilhado por posição, e não por pontuações "brutas" incomparáveis. Assim, uma correspondência léxica e a proximidade semântica são ponderadas em conjunto. A fusão acontece no nível da nota — pelo seu identificador estável.

```mermaid
flowchart LR
  q([Consulta]) --> fts[Léxico · FTS/BM25]
  q --> vec[Semântico · vetores]
  q --> gr[Grafo · 1-hop]
  fts --> rrf{Fusão RRF}
  vec --> rrf
  gr --> rrf
  rrf --> res([Resultados])
```

## Se a semântica estiver indisponível

A camada semântica pode estar desligada ou indisponível: o `VECTOR_SEARCH` não foi habilitado, o stack vetorial não está instalado, o modelo não carregou ou o cálculo do vetor da consulta estourou o tempo limite. Em qualquer um desses casos, a consulta é atendida pelo canal léxico — a busca sempre responde e não gera erro apenas por faltar a semântica.

> [!note] A semântica é opt-in
> A busca vetorial puxa um stack nativo pesado (~660 MB em disco) e carrega o modelo de embeddings na memória (centenas de MB de RAM), por isso vem desligada por padrão na imagem pública. Como ativá-la e qual modelo escolher é o que aborda [Configuração da busca](/docs/self-hosting/search-setup/).

## Onde você busca

- **Spotlight / OmniSearch** — um salto rápido e classificado para uma nota. Aqui funciona a híbrida completa: importa a relevância, não apenas a ocorrência exata da palavra. Veja [Busca e Spotlight](/docs/guides/search-spotlight/).
- **Filtro do Feed** (`?q=` no [Feed](/docs/guides/feed/)) — um filtro léxico sobre o corpus: ele mantém as notas em que os termos realmente aparecem e se combina com os filtros de pasta, tag e data.

## O índice e sua reconstrução

O índice de busca é conhecimento derivado: é construído a partir dos arquivos e totalmente recuperável por uma nova varredura. Um índice por espaço. Trocar o modelo de embeddings não é uma migração, e sim uma reconstrução da parte vetorial a partir do zero. A construção inicial do índice vetorial em um corpus grande leva minutos, ou até horas; durante esse tempo, a interface exibe um indicador "Building search index…", enquanto a própria busca permanece disponível no modo léxico.

Tópicos relacionados: [Grafo de conhecimento](/docs/concepts/knowledge-graph/) — de onde vem o terceiro canal, [Configuração da busca](/docs/self-hosting/search-setup/) — ativar a semântica e escolher um nível, [File-first](/docs/concepts/file-first/) — por que o índice é recuperável.