Weaviate: Base de datos vectorial con API GraphQL
Qué cubre este artículo
- Qué es Weaviate y cuáles son las características que la diferencian de otras bases de datos vectoriales
- Cómo instalar y ejecutar Weaviate localmente con Docker
- Cómo diseñar el esquema, almacenar datos y realizar consultas de búsqueda mediante GraphQL
- Cómo funciona la búsqueda híbrida y por qué es tan valiosa para RAG
- Cómo se compara Weaviate con Chroma y Qdrant, y cuándo es la opción adecuada
Introducción
Trabajas con RAG local y probablemente ya has experimentado con Chroma o Qdrant. Ahora buscas una base de datos vectorial que ofrezca más allá de la búsqueda vectorial pura. Una base de datos construida desde cero para consultas semánticas y que te proporcione un lenguaje de consulta potente.
Aquí es donde entra Weaviate. Es una base de datos vectorial de código abierto que destaca por su API GraphQL, su sistema de módulos y su búsqueda híbrida integrada. En lugar de solo almacenar vectores y encontrar similares, Weaviate ofrece una arquitectura bien pensada que integra vectorización, filtrado y búsqueda híbrida en un único sistema.
Este artículo te guía paso a paso a través de la instalación, el diseño del esquema, el almacenamiento de datos y las consultas. Si aún no conoces los fundamentos de RAG, te recomiendo leerlos primero. También es útil familiarizarse con los modelos de embedding.
¿Por qué necesito Weaviate?
Imagina que administras una base de conocimientos con miles de documentos. Algunas preguntas se responden bien mediante similitud semántica, es decir, búsqueda vectorial. Otras contienen palabras clave específicas o nombres propios que la búsqueda vectorial pura no encuentra bien. Necesitarías ambas: búsqueda vectorial y por palabras clave en una única consulta.
Con la mayoría de las bases de datos vectoriales tienes que elegir un enfoque o agregar herramientas externas como BM25. Weaviate trae consigo la búsqueda híbrida. Pesas la búsqueda vectorial y la búsqueda por palabras clave en una sola consulta y obtienes resultados que combinan ambos mundos.
Además está la API GraphQL. En lugar de aprender una interfaz REST propietaria, usas un lenguaje de consulta estandarizado que muchos desarrolladores ya conocen. Puedes expresar filtros complejos, ordenamientos y relaciones entre objetos de datos en una sola consulta. Esto es particularmente valioso cuando tu aplicación RAG combina metadatos estructurados y textos no estructurados.
El sistema de módulos es otro punto a favor. Weaviate puede calcular embeddings directamente en el servidor si activas un módulo como text2vec-transformers. Envías texto sin procesar a Weaviate y la base de datos se encarga de la vectorización. Para configuraciones locales, puedes pasar tus propios vectores, lo que cubriremos en este artículo.
Weaviate explicado brevemente
Weaviate almacena datos como objetos con propiedades y vectores. Cada objeto pertenece a una clase que defines en el esquema. El esquema es comparable a la estructura de tabla en una base de datos relacional: defines qué campos tiene una clase, qué tipo de datos tienen y si deben vectorizarse.
En una consulta de búsqueda, Weaviate convierte la consulta en un vector, lo compara con los vectores almacenados y devuelve los objetos más similares. Esta es la búsqueda vectorial clásica. Con la búsqueda híbrida, Weaviate combina esta búsqueda vectorial con una búsqueda por palabras clave y pondera ambas según un parámetro que controlas.
La API GraphQL es la interfaz principal para todas las consultas. Escribes consultas GraphQL para buscar, filtrar y explorar objetos. Para escribir y actualizar objetos, usas la API REST o el cliente Python, que abstrae ambas operaciones por ti.
A quién va dirigido este artículo
Este artículo está dirigido a desarrolladores que ya están familiarizados con RAG y bases de datos vectoriales. Debes comprender qué es la IA local y cómo funciona RAG. Si ya has experimentado con Chroma o Qdrant, este artículo es el siguiente paso lógico. Necesitas conocimientos básicos de Python y debes saber cómo usar Docker, ya que ejecutaremos Weaviate en un contenedor Docker.
Términos importantes
| Término | Explicación |
|---|---|
| Class | Una categoría de objetos de datos, similar a una tabla. Cada clase tiene propiedades definidas. |
| Schema | La definición de todas las clases, propiedades y vectorizadores. Se crea antes de almacenar datos. |
| Object | Un único registro dentro de una clase, que consta de propiedades y un vector. |
| Vector | Un array numérico que representa el contenido semántico de un objeto. |
| Module | Un plugin que realiza vectorización u otras funciones, como text2vec-transformers. |
| Hybrid Search | Un método de búsqueda que combina y pondera búsqueda vectorial y búsqueda por palabras clave. |
| GraphQL | Un lenguaje de consulta con el que realizas consultas estructuradas a Weaviate. |
| BM25 | Un algoritmo para búsqueda por palabras clave que se basa en frecuencia de términos y longitud de documento. |
| Vectorizer | Un módulo que convierte texto automáticamente en vectores sin necesidad de calcular embeddings externos. |
Instalación: Inicia Weaviate con Docker
Weaviate funciona mejor en un contenedor Docker. Si aún no has instalado Docker, revisa los fundamentos de Docker.
La variante más sencilla es un único contenedor Docker sin módulos externos. Esta configuración es ideal para empezar, porque proporcionas tus propios vectores y usas Weaviate solo como almacenamiento y motor de búsqueda.
docker run -d \
--name weaviate \
-p 8080:8080 \
-e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
-e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
-v weaviate_data:/var/lib/weaviate \
semitechnologies/weaviate:latestDespués del inicio, accedes a Weaviate en http://localhost:8080. Puedes verificar que el servidor está funcionando llamando a la consulta de estado:
curl http://localhost:8080/v1/.well-known/readySi la respuesta es READY, Weaviate está listo para usar. El volumen Docker weaviate_data asegura que tus datos se conserven después de reiniciar el contenedor.
Para configuraciones más complejas con módulos de vectorización integrados, Docker Compose es la opción recomendada. Weaviate proporciona archivos docker-compose.yml listos para usar que inician contenedores adicionales para modelos Transformer. Para este artículo, el contenedor simple es suficiente, ya que usaremos nuestros propios vectores.
Instalar el cliente Python
Weaviate ofrece un cliente Python oficial que abstrae las APIs REST y GraphQL. Instálalo con pip:
pip install weaviate-clientDespués, te conectas a tu instancia local de Weaviate en Python:
import weaviate
client = weaviate.connect_to_local(
host="localhost",
port=8080
)
print(client.is_ready()) # True si la conexión está establecidaEl cliente Python utiliza la nueva API v4, que proporciona una interfaz tipado e intuitivo. Si encuentras tutoriales antiguos que usan la API v3, ten en cuenta que la sintaxis es diferente.
Diseñar el esquema
Antes de almacenar datos, defines un esquema. Este define qué clases existen y qué propiedades tienen. Aquí también estableces si Weaviate debe vectorizar automáticamente o si proporcionas vectores externos.
En nuestro ejemplo, creamos una clase Article con las propiedades title, content y source. No configuramos un vectorizador interno, sino que traemos nuestros propios vectores.
from weaviate.classes.config import Configure
client.collections.create(
name="Article",
vectorizer_config=Configure.Vectorizer.none(),
properties=[
Configure.property(name="title", data_type=Configure.DataType.TEXT),
Configure.property(name="content", data_type=Configure.DataType.TEXT),
Configure.property(name="source", data_type=Configure.DataType.TEXT),
]
)La configuración Configure.Vectorizer.none() indica que Weaviate no realiza vectorización automática. Tú proporcionas los vectores, que calculas con un modelo de embedding externo.
Si prefieres usar un módulo como text2vec-transformers, configuras el vectorizador en ese módulo. Sin embargo, Weaviate necesitará un contenedor adicional con el modelo Transformer, lo que aumenta los requisitos de recursos.
Almacenar datos
Ahora añadimos objetos a la clase Article. Como no configuramos un vectorizador interno, debemos proporcionar el vector manualmente.
articles = client.collections.get("Article")
articles.data.insert_many([
{
"properties": {
"title": "Was ist lokale KI?",
"content": "Lokale KI läuft auf dem eigenen Rechner ohne Cloud-Dienste.",
"source": "blog"
},
"vector": [0.12, 0.34, 0.56, 0.78] # Dein Embedding-Vektor
},
{
"properties": {
"title": "RAG erklärt",
"content": "RAG verbindet Dokumentensuche mit Sprachmodellen für bessere Antworten.",
"source": "blog"
},
"vector": [0.23, 0.45, 0.67, 0.89] # Dein Embedding-Vektor
}
])En la práctica, generas los vectores con un modelo de embedding como intfloat/multilingual-e5-large o BAAI/bge-m3. La dimensión del vector debe ser idéntica para todos los objetos de una clase. Si cambias el modelo de embedding, debes vectorizar nuevamente los datos.
Realizar consultas de búsqueda
Weaviate soporta tres tipos de búsqueda: búsqueda por vector, búsqueda por palabras clave (BM25) y Hybrid Search. Veamos las tres.
Búsqueda por vector
En la búsqueda por vector, proporcionas un vector de búsqueda y obtienes los objetos más similares:
articles = client.collections.get("Article")
results = articles.query.near_vector(
near_vector=[0.15, 0.40, 0.60, 0.80], # Dein Suchvektor
limit=3
)
for obj in results.objects:
print(obj.properties["title"], obj.properties["content"])Búsqueda por palabras clave con BM25
La búsqueda BM25 encuentra objetos basándose en palabras clave. Funciona bien para nombres propios y términos específicos:
results = articles.query.bm25(
query="lokale KI",
limit=3
)
for obj in results.objects:
print(obj.properties["title"], obj.properties["content"])Hybrid Search
Hybrid Search combina búsqueda por vector y BM25. El parámetro alpha controla la ponderación: alpha=0 significa búsqueda BM25 pura, alpha=1 significa búsqueda por vector pura. Un valor de 0.5 pondera ambas por igual.
results = articles.query.hybrid(
query="lokale KI",
vector=[0.15, 0.40, 0.60, 0.80], # Optional, kann auch automatisch erzeugt werden
alpha=0.5,
limit=3
)
for obj in results.objects:
print(obj.properties["title"], obj.properties["content"])Hybrid Search es especialmente valioso para RAG, porque muchas preguntas tienen componentes tanto semánticos como basados en palabras clave. Más información en el artículo sobre Hybrid Search.
Filtrado
Weaviate permite filtrar resultados de búsqueda por propiedades. Esto es importante cuando solo quieres buscar en fuentes o períodos específicos.
from weaviate.classes.query import Filter
results = articles.query.near_vector(
near_vector=[0.15, 0.40, 0.60, 0.80],
limit=3,
filters=Filter.by_property("source").equal("blog")
)
for obj in results.objects:
print(obj.properties["title"], obj.properties["source"])Los filtros se pueden combinar con and_ y or_ para formular condiciones complejas. Esto es más potente que los simples filtros de metadatos en otras bases de datos.
Comparación: Weaviate vs. Chroma vs. Qdrant
| Propiedad | Weaviate | Chroma | Qdrant |
|---|---|---|---|
| Lenguaje de consulta | GraphQL | Python-API | REST y gRPC |
| Hybrid Search | Integrado | Limitado | Con Sparse Vectors |
| Vectorización automática | Sí, vía módulos | Sí, vía funciones de embedding | Sí, vía FastEmbed |
| Esquema | Explícito, basado en clases | Implícito, basado en colecciones | Basado en colecciones |
| Escalabilidad | Buena, también distribuida | Pequeña a mediana | Buena, lista para producción |
| Barrera de entrada | Media | Muy baja | Baja a media |
| GraphQL | Sí | No | No |
| Filtros | Muy potentes, combinables | Simples | Muy potentes |
| Requisitos de recursos | Media | Baja | Baja a media |
Weaviate destaca cuando necesitas Hybrid Search sin herramientas externas y aprecias GraphQL como lenguaje de consulta. Chroma es más simple para empezar rápidamente, Qdrant es más robusto para búsqueda por vector puro con grandes volúmenes de datos. Weaviate ofrece más características listas para usar, pero requiere más tiempo de aprendizaje.
Errores comunes
- Crear el esquema antes que los datos: Weaviate requiere un esquema antes de almacenar datos. Si intentas insertar objetos en una clase inexistente, obtendrás un error. Siempre crea el esquema primero.
- La dimensión del vector debe ser consistente: Todos los vectores en una clase deben tener la misma dimensión. Si cambias el modelo de embedding, debes recrear la clase y recargar los datos.
- Vectorizador configurado incorrectamente: Si configuras
Configure.Vectorizer.none()pero no proporcionas vectores, Weaviate almacena objetos sin vector. Las búsquedas fallarán. Verifica que el vectorizador coincida con cómo proporcionas los datos. - No dominar la sintaxis de GraphQL: GraphQL es potente, pero propenso a errores. Un campo incorrecto o un error tipográfico en la consulta generan errores crípticos. Usa el cliente Python, que genera la sintaxis por ti.
- Olvidar el volumen de persistencia: Sin un volumen Docker, todos los datos se pierden después de un reinicio. Siempre configura
PERSISTENCE_DATA_PATHcon un volumen. - Requisitos de recursos con módulos: Si activas módulos de vectorización como
text2vec-transformers, Weaviate necesita significativamente más RAM y CPU. Para configuraciones locales sin GPU, suele ser mejor calcular vectores externamente. - Dejar la autenticación deshabilitada: En nuestro ejemplo, habilitamos acceso anónimo. Está bien para pruebas locales, pero nunca debe usarse en instancias accesibles públicamente.
- No entender los índices: Weaviate usa HNSW por defecto para la indexación de vectores. Si tienes grandes volúmenes de datos, deberías familiarizarte con los parámetros de índice para optimizar la velocidad de búsqueda.
Hardware, costos y seguridad
Weaviate sin módulos de vectorización consume pocos recursos. Para algunos miles de documentos, una máquina con 4 GB de RAM y CPU convencional es suficiente. Si activas módulos como text2vec-transformers, el consumo de RAM sube a 8 GB o más, y una GPU acelera significativamente la vectorización.
Weaviate es Open Source y gratuito. La edición Community incluye todas las funciones que necesitas para proyectos locales de RAG. Existe una versión comercial en la nube, pero no es relevante para configuraciones locales.
En cuanto a seguridad, aplican las mismas reglas que para otras bases de datos locales: mientras Weaviate sea accesible solo en tu red interna, tus datos están protegidos. Si expones Weaviate a través de la red, activa autenticación y utiliza un proxy inverso con TLS. Dado que todos los datos permanecen locales, esto representa una ventaja importante frente a bases de datos vectoriales basadas en la nube, tal como se explica en el artículo sobre IA local vs. IA en la nube.
Enlaces útiles
- Resumen de bases de datos vectoriales - Todos los artículos sobre bases de datos vectoriales
- RAG local - Resumen de todos los artículos sobre RAG
- Fundamentos de RAG - Cómo funciona RAG
- Modelos de embedding - Generar vectores a partir de texto
- Búsqueda híbrida - Combinar búsqueda vectorial y por palabras clave
- Chroma - Base de datos vectorial simple
- Qdrant - Base de datos vectorial escalable
- Fundamentos de Docker - Entender la tecnología de contenedores
Preguntas frecuentes
¿Necesito aprender GraphQL para usar Weaviate?
No obligatoriamente. El cliente Python abstrae las consultas GraphQL por ti. Sin embargo, si necesitas consultas complejas con filtros y relaciones, es útil comprender los fundamentos de GraphQL.
¿Puede Weaviate calcular vectores propios?
Sí, con módulos como text2vec-transformers o text2vec-cohere. Para configuraciones locales sin GPU, a menudo es más eficiente calcular vectores externamente y pasarlos a Weaviate.
¿Es Weaviate gratuito?
Sí, la versión Open Source es gratuita e incluye todas las funciones para proyectos locales. Existe una versión en la nube de pago, pero no es necesaria para configuraciones locales.
¿Cuántos documentos soporta Weaviate localmente?
Depende de la RAM y el espacio en disco. Weaviate es apropiado para cientos de miles hasta millones de objetos. Con volúmenes de datos muy grandes, deberías optimizar los parámetros del índice.
¿Puedo conectar Weaviate con Ollama?
Sí. Ollama proporciona el modelo de lenguaje, Weaviate la base de datos vectorial. Tu script Python conecta ambos: Weaviate encuentra los documentos relevantes, Ollama genera la respuesta.
¿Cuál es la diferencia entre Weaviate y Chroma?
Chroma es más simple y rápido de configurar, ideal para prototipos. Weaviate ofrece más características como GraphQL, búsqueda híbrida y un sistema de módulos, pero es más complejo de instalar.
¿Necesito Docker para Weaviate?
Docker es el método recomendado, aunque también existen binarios. Para pruebas locales y sistemas en producción, Docker es el más simple y mejor documentado.
¿Soporta Weaviate búsqueda híbrida?
Sí, la búsqueda híbrida es una de las fortalezas de Weaviate. Ajustas la búsqueda vectorial y por palabras clave con el parámetro alpha y obtienes resultados combinados.
¿Puedo ejecutar Weaviate en un NAS?
Sí, con Docker. Asegúrate de tener suficiente RAM y almacenamiento rápido. Weaviate se beneficia del almacenamiento SSD, especialmente con grandes volúmenes de datos.
¿Cómo aseguro Weaviate?
Las instancias locales sin exposición de red suelen ser suficientemente seguras en redes protegidas. Para acceso a través de la red, activa autenticación y utiliza un proxy inverso con cifrado TLS.
¿Cuál es la diferencia entre Weaviate y Qdrant?
Qdrant es más ligero y se enfoca en búsqueda vectorial pura. Weaviate ofrece más funciones como GraphQL, un sistema de módulos y búsqueda híbrida integrada, pero consume más recursos.
Fuentes
- Sitio web oficial de Weaviate: weaviate.io
- Documentación de Weaviate: weaviate.io/developers/weaviate
- Cliente Python de Weaviate: github.com/weaviate/weaviate-python-client
- Repositorio GitHub de Weaviate: github.com/weaviate/weaviate
- Artículo sobre bases de datos vectoriales en esta serie
- Artículo sobre búsqueda híbrida en esta serie