Weaviate: pesquisa híbrida e multi-location

#O que diferencia Weaviate das demais bases vetoriais

Weaviate é um banco de dados vetorial open source, cujo código está publicado no GitHub. Diferentemente de bibliotecas como FAISS, trata-se de um servidor: ele armazena os objetos (texto e propriedades), os vetores e o índice de busca, e responde a requisições via API. Três funções o distinguem de um simples repositório de vetores. A primeira é a codificação integrada: você insere objetos, um módulo configurado transforma o texto em vetores e as consultas são escritas em linguagem natural, em vez de arrays de números de ponto flutuante. Essa escolha elimina uma classe de bugs (dimensões incompatíveis, pergunta codificada com um modelo diferente daquele usado para o corpus), pois o mesmo módulo trata os dois lados.

A segunda é a busca híbrida, que combina palavras-chave e vetores em uma única consulta. A terceira é a multilocação: uma mesma implantação pode hospedar vários conjuntos de dados isolados, um por cliente, serviço ou usuário. O custo dessas funcionalidades é ter um componente em execução, com sua memória, seus backups e suas atualizações, enquanto o ChromaDB em modo de arquivo é apenas uma biblioteca Python.

#Manter tudo localmente: três configurações para verificar

Um módulo de codificação é uma dependência executada em algum lugar. Escolher um vetorizador hospedado por terceiros equivale a enviar cada um dos seus documentos e cada uma das suas perguntas para outro lugar; escolher o módulo Ollama mantém o cálculo no seu hardware. Dois outros ajustes são menos visíveis e merecem a mesma atenção.

O vetorizador

Use o text2vec-ollama, que chama a sua instância local do Ollama; a documentação indica que ele não exige nenhuma chave de API nesse caso. Atenção ao endereço: se o Weaviate estiver rodando em um contêiner e o Ollama na máquina hospedeira, a documentação recomenda host.docker.internal para que o contêiner consiga acessar a máquina hospedeira.

A telemetria

A documentação do Weaviate indica que ele coleta dados de telemetria por padrão: versão do servidor, sistema operacional, módulos utilizados, número de objetos e de coleções, enviados a cada 24 horas; ela esclarece que nenhum conteúdo dos seus dados é coletado. Para desativar a telemetria, defina a variável DISABLE_TELEMETRY como true. Em uma instalação que deve permanecer totalmente isolada, configure essa variável.

Acesso anônimo

O comando docker run de início rápido define AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED como true, e a documentação desaconselha fortemente o acesso anônimo fora de ambientes de desenvolvimento ou avaliação. Assim que a porta 8080 estiver acessível a partir de qualquer dispositivo além do seu computador, ative a autenticação por chave de API.

#Instalar Weaviate com Docker e Ollama

1. 01
   Ter Ollama e um modelo de embeddings

   Instale Ollama e baixe o modelo com ollama pull bge-m3.
2. 02
   Escrever o arquivo docker-compose.yml

   Ele declara o contêiner Weaviate, seu volume de dados, a ativação do módulo Ollama, a telemetria desativada e o acesso ao host.
3. 03
   Iniciar e verificar

   Execute docker compose up -d e, em seguida, teste o endereço http://localhost:8080/v1/meta: a resposta lista os módulos ativos.
4. 04
   Criar uma coleção vinculada ao módulo

   A coleção indica qual modelo do Ollama vetoriza quais propriedades.

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.7
    ports:
      - "8080:8080"
      - "50051:50051"
    volumes:
      - weaviate_data:/var/lib/weaviate
    restart: on-failure:0
    extra_hosts:
      - "host.docker.internal:host-gateway"   # utile sous Linux pour joindre Ollama sur l'hôte
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'   # à fermer si le port est exposé
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      ENABLE_MODULES: 'text2vec-ollama'
      DISABLE_TELEMETRY: 'true'
      CLUSTER_HOSTNAME: 'node1'
volumes:
  weaviate_data:

O número de versão 1.39.7 é o da documentação oficial do Weaviate na data de redação; use a versão atual indicada na página de instalação. As portas 8080 (HTTP) e 50051 (gRPC) são as usadas no início rápido da documentação.

#Esquema: coleções, propriedades, vetorizador, tenants

import weaviate
from weaviate.classes.config import Configure, Property, DataType

client = weaviate.connect_to_local()

client.collections.create(
    "Document",
    vector_config=[
        Configure.Vectors.text2vec_ollama(
            name="contenu_vecteur",
            source_properties=["contenu"],
            api_endpoint="http://host.docker.internal:11434",
            model="bge-m3",
        )
    ],
    properties=[
        Property(name="contenu", data_type=DataType.TEXT),
        Property(name="source", data_type=DataType.TEXT),
    ],
)

coll = client.collections.use("Document")
coll.data.insert_many([
    {"contenu": "Le délai de préavis est de trois mois.", "source": "contrat.pdf"},
    {"contenu": "Le loyer est révisé chaque année au 1er janvier.", "source": "bail.pdf"},
])
client.close()

A estrutura segue a documentação oficial: vector_config, um vetorizador nomeado, propriedades de origem e um ponto de acesso ao Ollama. O Weaviate vetoriza por padrão as propriedades do tipo texto, ordenadas alfabeticamente e depois concatenadas; source_properties permite restringir o cálculo à propriedade útil e deixar o nome do arquivo fora do vetor.

#A pesquisa híbrida no Weaviate

A busca semântica localiza trechos com significado próximo, mas falha em cadeias exatas: um número de fatura, uma referência de peça, um código de erro ou um nome próprio. A busca híbrida do Weaviate combina os resultados de uma busca vetorial e de uma busca por palavras-chave BM25F, fundindo os dois conjuntos de resultados, com pesos e um método de fusão configuráveis. O parâmetro alpha regula o equilíbrio: de acordo com a documentação, 1 corresponde a uma busca vetorial pura e 0 a uma busca por palavras-chave pura. Sem alpha, o peso efetivo depende do seu cliente: defina-o sempre explicitamente.

coll = client.collections.use("Document")
res = coll.query.hybrid(query="préavis contrat CDI", alpha=0.5, limit=5)
for o in res.objects:
    print(o.properties["source"], o.properties["contenu"][:80])

Desde a versão 1.24, o método de fusão padrão é a fusão por pontuações relativas; a alternativa é a fusão por posições no ranking. O princípio e a escolha entre as duas são explicados no guia sobre busca híbrida. Em um corpus técnico, isso muitas vezes faz a diferença entre um sistema em que se confia e um sistema que se abandona: as falhas da busca puramente vetorial ocorrem justamente nas buscas que os usuários consideram triviais.

#Multitenancy: um tenant por grupo de usuários

A multitenência divide uma coleção em fragmentos, um por tenant. A documentação a descreve assim: cada tenant é armazenado em um fragmento separado, e os dados de um tenant não são visíveis para outro. Ela está desativada por padrão e é ativada na definição da coleção com multi_tenancy_config. Se vários grupos consultam o mesmo sistema (clientes de uma PME, departamentos de uma empresa, membros de uma família), isso oferece uma resposta estrutural à pergunta «essa pessoa pode recuperar esse documento?», muito mais segura do que um filtro aplicado posteriormente e infinitamente mais segura do que uma instrução no prompt.

from weaviate.classes.config import Configure
from weaviate.classes.tenants import Tenant

client.collections.create(
    "DocumentClient",
    multi_tenancy_config=Configure.multi_tenancy(enabled=True),
)
coll = client.collections.use("DocumentClient")
coll.tenants.create([Tenant(name="client_a"), Tenant(name="client_b")])

# Toute requête passe par un tenant : les autres restent invisibles
res = coll.with_tenant("client_a").query.hybrid(query="préavis", limit=3)

Os tenants são leves: a documentação indica que é possível ter 50.000 fragmentos ativos ou mais por nó. Eles têm um estado (ACTIVE, INACTIVE, OFFLOADED): um tenant inativo está no disco e não ocupa memória, o que permite hospedar muitos pequenos conjuntos de dados, mantendo ativos apenas os que estão em uso. O nome de um tenant aceita apenas caracteres alfanuméricos, underline e hífen.

#Quanto custa rodar o Weaviate

Weaviate é um verdadeiro serviço: um contêiner, armazenamento persistente, memória proporcional aos seus vetores. A documentação de dimensionamento é clara sobre a restrição: o índice HNSW deve ser armazenado em memória, a memória determina o tamanho máximo do conjunto de dados e não influencia diretamente a velocidade das consultas. A regra empírica da documentação é prever o dobro da memória ocupada por todos os vetores.

empreinte d'un vecteur = dimensions × 4 octets (float32)
mémoire estimée   = 2 × nombre de vecteurs × empreinte d'un vecteur

Exemple, bge-m3 (1 024 dimensions) :
  1 024 × 4 = 4 096 octets par vecteur
  100 000 passages → 2 × 100 000 × 4 096 ≈ 0,8 Go
  1 000 000 passages → 2 × 1 000 000 × 4 096 ≈ 8,2 Go

As 1.024 dimensões do bge-m3 são, aqui, uma hipótese a ser verificada na ficha do seu modelo. Para um corpus pessoal ou de uma PME (algumas dezenas de milhares de passagens), o consumo de memória do índice é baixo; ele passa a ser uma preocupação a partir de vários milhões de passagens. O Weaviate oferece compressão de vetores: a documentação recomenda a quantização rotacional (RQ) e também menciona a quantização por produto (PQ), binária (BQ) e escalar (SQ), ao custo de uma pequena perda de informação. Adicione o módulo de codificação local: o Ollama executa um modelo de embeddings na mesma máquina que seu modelo de linguagem. Em uma única máquina, decida qual dos dois ocupa a placa de vídeo ou aceite que a indexação e a inferência interfiram uma na outra.

#Fornecer seus próprios vetores, ou migrar do ChromaDB

O módulo de codificação não é obrigatório. A documentação do Weaviate descreve a abordagem “bring your own vectors”: em vez de deixar a base calcular os embeddings, você fornece os que já possui, sejam eles personalizados ou pré-gerados. No cliente Python, você declara então um vetor nomeado com Configure.Vectors.self_provided. É a forma mais econômica de migrar do ChromaDB: você relê os documentos e os vetores já calculados (o Chroma pode retorná-los com a opção include) e depois os envia ao Weaviate, sem chamar novamente o modelo de embeddings. Duas verificações evitam surpresas desagradáveis: a dimensão dos vetores deve ser a mesma em toda a coleção, e as perguntas devem ser codificadas com o modelo original, pois o Weaviate não fará isso por você.

Quando é melhor usar a codificação integrada? Se você quer que as consultas sejam escritas diretamente em texto, que a adição de documentos não exija código para realizar os cálculos e que a consistência do modelo seja garantida pela configuração. Quando preferir seus próprios vetores? Se você já tem um pipeline de embeddings, se precisa usar um modelo que nenhum módulo oferece ou se quer poder mudar de base vetorial sem recalcular tudo.

#Weaviate ou outra base vetorial

Se você tiver dúvidas, comece com a solução mais simples: ChromaDB para um protótipo, depois migre para um serviço quando surgir uma necessidade específica (isolamento, busca híbrida nativa, volume de dados). A escolha é reversível desde que você mantenha os documentos de origem e o script de indexação.

#Perguntas frequentes sobre Weaviate

• Busca híbrida: BM25 + vetorial
• Qdrant: o banco vetorial de um RAG local
• pgvector: a busca vetorial no PostgreSQL
• FAISS: a biblioteca por trás da busca vetorial
• RAG local com ChromaDB e Ollama

• Fonte: Weaviate, pesquisa híbrida
• Fonte: Weaviate, módulo Ollama
• Fonte: Weaviate, telemetria
• Fonte: Weaviate, recursos e memória