Weaviate: búsqueda híbrida y multi-location

#Lo que distingue a Weaviate de otras bases vectoriales

Weaviate es una base de datos vectorial de código abierto, cuyo código está publicado en GitHub. A diferencia de bibliotecas como FAISS, es un servidor: almacena los objetos (texto y propiedades), los vectores y el índice de búsqueda, y responde a consultas mediante una API. Tres funciones lo distinguen de un simple almacén de vectores. La primera es la codificación integrada: introduces objetos, un módulo configurado transforma el texto en vectores y las consultas se escriben en lenguaje natural en lugar de como arrays de números de coma flotante. Esta opción elimina una clase de errores (dimensiones incompatibles, una pregunta codificada con un modelo distinto del utilizado para el corpus), ya que el mismo módulo procesa ambos lados.

La segunda es la búsqueda híbrida, que combina palabras clave y vectores en una sola consulta. La tercera es la arquitectura multiinquilino: un mismo despliegue puede alojar varios conjuntos de datos aislados, uno por cliente, servicio o usuario. El coste de estas funciones es tener que ejecutar un componente, con su memoria, sus copias de seguridad y sus actualizaciones, mientras que ChromaDB en modo de archivo es solo una biblioteca Python.

#Mantener todo localmente: tres ajustes por verificar

Un módulo de codificación es una dependencia que se ejecuta en un lugar concreto. Elegir un vectorizador alojado por un tercero equivale a enviar cada uno de tus documentos y cada una de tus preguntas a otro lugar; elegir el módulo Ollama mantiene el cálculo en tu hardware. Otros dos ajustes son menos visibles y merecen la misma atención.

El vectorizador

Utiliza text2vec-ollama, que llama a tu instancia local de Ollama; la documentación indica que no requiere ninguna clave de API en este caso. Cuidado con la dirección: si Weaviate se ejecuta en un contenedor y Ollama en la máquina anfitriona, la documentación recomienda host.docker.internal para que el contenedor acceda a ella.

La telemetría

La documentación de Weaviate indica que recopila datos de telemetría por defecto: versión del servidor, sistema operativo, módulos utilizados y número de objetos y colecciones, enviados cada 24 horas; especifica que no se recopila ningún contenido de tus datos. Para desactivar la telemetría, establece la variable DISABLE_TELEMETRY en true. En una instalación que deba permanecer hermética, configúrala así.

Acceso anónimo

El comando docker run de inicio rápido establece AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED en true, y la documentación desaconseja encarecidamente el acceso anónimo fuera de los entornos de desarrollo o evaluación. En cuanto el puerto 8080 sea accesible desde cualquier dispositivo distinto de tu ordenador, activa la autenticación mediante una clave de API.

#Instalar Weaviate con Docker y Ollama

1. 01
   Tener Ollama y un modelo de embeddings

   Instala Ollama y descarga el modelo con ollama pull bge-m3.
2. 02
   Escribir el archivo docker-compose.yml

   Indica el contenedor Weaviate, su volumen de datos, la activación del módulo Ollama, la telemetría desactivada y el acceso al host.
3. 03
   Iniciar y verificar

   Ejecuta docker compose up -d, luego prueba la dirección http://localhost:8080/v1/meta: la respuesta lista los módulos activos.
4. 04
   Crear una colección vinculada al módulo

   La colección indica qué modelo de Ollama vectoriza qué propiedades.

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:

La versión 1.39.7 es la de la documentación oficial de Weaviate en la fecha de redacción; toma la versión actual indicada en la página de instalación. Los puertos 8080 (HTTP) y 50051 (gRPC) son los del inicio rápido de la documentación.

#Esquema: colecciones, propiedades, vectorizador, 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()

La estructura sigue la documentación oficial: vector_config, un vectorizador con nombre, propiedades de origen y un punto de acceso a Ollama. Weaviate vectoriza por defecto las propiedades de tipo texto, ordenadas alfabéticamente y luego concatenadas; source_properties permite restringir el cálculo a la propiedad útil y dejar el nombre del archivo fuera del vector.

#La búsqueda híbrida en Weaviate

La búsqueda semántica encuentra pasajes de significado similar y falla con cadenas exactas: un número de factura, una referencia de pieza, un código de error, un nombre propio. La búsqueda híbrida de Weaviate combina los resultados de una búsqueda vectorial y una búsqueda por palabras clave BM25F fusionando ambos conjuntos de resultados, con pesos y un método de fusión configurables. El parámetro alpha regula el equilibrio: según la documentación, 1 corresponde a una búsqueda vectorial pura y 0 a una búsqueda por palabras clave pura. Si no especificas alpha, el peso efectivo depende de tu cliente: fíjalo siempre explícitamente.

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 la versión 1.24, el método de fusión por defecto es la fusión por puntuaciones relativas; la alternativa es la fusión por rangos. El principio y la elección entre ambos se explican en la guía sobre búsqueda híbrida. En un corpus técnico, a menudo se trata de la diferencia entre un sistema en el que se confía y otro que se abandona: los fallos de la búsqueda puramente vectorial se producen precisamente en las búsquedas que los usuarios consideran triviales.

#Multitenencia: un tenant por grupo de usuarios

La arquitectura multiinquilino particiona una colección en fragmentos, uno por inquilino (tenant). La documentación la describe así: cada inquilino se almacena en un fragmento separado y los datos de un inquilino no son visibles para otro. Está desactivada por defecto y se activa en la definición de la colección con multi_tenancy_config. Si varios grupos consultan el mismo sistema (clientes de una pyme, departamentos de una empresa, miembros de una familia), ofrece una respuesta estructural a la pregunta «¿puede esta persona recuperar este documento?», mucho más segura que un filtro aplicado a posteriori e infinitamente más segura que una instrucción en el 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)

Los tenants son ligeros: la documentación indica que se pueden tener 50.000 fragmentos activos o más por nodo. Tienen un estado (ACTIVE, INACTIVE, OFFLOADED): un tenant inactivo está en disco y no ocupa memoria, lo que permite alojar muchos conjuntos de datos pequeños manteniendo activos solo los que se usan. El nombre de un tenant solo admite caracteres alfanuméricos, guion bajo y guion.

#Lo que cuesta ejecutar Weaviate

Weaviate es un servicio real: un contenedor, almacenamiento persistente y memoria proporcional a tus vectores. La documentación de dimensionado es clara sobre la restricción: el índice HNSW debe almacenarse en memoria, la memoria determina el tamaño máximo del conjunto de datos y no influye directamente en la velocidad de las consultas. La regla empírica de la documentación es prever el doble de la memoria que ocupan todos los vectores.

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

Las 1.024 dimensiones de bge-m3 son aquí una hipótesis que debes verificar en la ficha de tu modelo. Para un corpus personal o de una pyme (unas pocas decenas de miles de pasajes), el índice ocupa poca memoria; esta empieza a ser un factor importante a partir de varios millones de pasajes. Weaviate ofrece compresión de vectores: la documentación recomienda la cuantización rotacional (RQ) y menciona también la cuantización por producto (PQ), binaria (BQ) y escalar (SQ), a costa de una ligera pérdida de información. Añade el módulo de codificación local: Ollama ejecuta un modelo de embeddings en la misma máquina que tu modelo de lenguaje. Si usas una sola máquina, decide cuál de los dos ocupa la tarjeta gráfica, o acepta que la indexación y la inferencia interfieran entre sí.

#Proporcionar tus propios vectores o migrar desde ChromaDB

El módulo de codificación no es obligatorio. La documentación de Weaviate describe el enfoque «bring your own vectors»: en lugar de dejar que la base calcule los embeddings, proporcionas los que ya tienes, ya sean personalizados o pregenerados. En el cliente Python, se declara entonces un vector con nombre mediante Configure.Vectors.self_provided. Esta es la vía de migración más económica desde ChromaDB: vuelves a leer los documentos y los vectores ya calculados (Chroma puede devolverlos con la opción include) y luego los envías a Weaviate, sin volver a llamar al modelo de embeddings. Dos comprobaciones evitan sorpresas desagradables: la dimensión de los vectores debe ser la misma en toda la colección y las preguntas deben codificarse con el modelo original, ya que Weaviate no lo hará por ti.

¿Cuándo conviene optar por la codificación integrada? Si quieres escribir las consultas directamente como texto, añadir documentos sin escribir código para realizar cálculos y garantizar la coherencia del modelo mediante la configuración. ¿Cuándo conviene usar tus propios vectores? Si ya tienes un pipeline de embeddings, si necesitas usar un modelo que ningún módulo ofrece o si quieres poder cambiar de base vectorial sin recalcularlo todo.

#Weaviate o otra base vectorial

Si dudas, comienza con la solución más sencilla: ChromaDB para un prototipo, luego migra a un servicio cuando surja una necesidad específica (aislamiento, búsqueda híbrida nativa, volumen de datos). La elección es reversible siempre que conserves los documentos originales y el script de indexación.

#Preguntas frecuentes sobre Weaviate

• Búsqueda híbrida: BM25 + vectorial
• Qdrant: la base vectorial de un RAG local
• pgvector: la búsqueda vectorial en PostgreSQL
• FAISS: la biblioteca detrás de la búsqueda vectorial
• RAG local con ChromaDB y Ollama

• Fuente: Weaviate, búsqueda híbrida
• Fuente: Weaviate, módulo Ollama
• Fuente: Weaviate, telemetría
• Fuente: Weaviate, recursos y memoria