Weaviate: Vektordatenbank mit GraphQL-API

Was dieser Artikel behandelt

• Was Weaviate ist und welche besonderen Features es von anderen Vektordatenbanken abheben
• Wie Du Weaviate mit Docker lokal installierst und betreibst
• Wie Du das Schema designst, Daten speicherst und Suchanfragen per GraphQL durchführst
• Wie Hybrid Search funktioniert und warum sie für RAG so wertvoll ist
• Wie sich Weaviate im Vergleich zu Chroma und Qdrant schlägt und wann es die richtige Wahl ist

Einleitung

Du beschäftigst Dich mit lokalem RAG und hast vielleicht schon Chroma oder Qdrant ausprobiert. Jetzt suchst Du nach einer Vektordatenbank, die mehr mitbringt als reine Vektorsuche. Eine Datenbank, die von Grund auf für semantische Anfragen gebaut wurde und Dir eine mächtige Abfragesprache an die Hand gibt.

Genau hier kommt Weaviate ins Spiel. Weaviate ist eine Open-Source-Vektordatenbank, die sich durch ihre GraphQL-API, ihr Modulsystem und die integrierte Hybrid Search auszeichnet. Statt nur Vektoren zu speichern und ähnliche zu finden, bietet Weaviate eine durchdachte Architektur, die Vektorisierung, Filterung und hybride Suche in einem System vereint.

Dieser Artikel führt Dich Schritt für Schritt durch die Installation, das Schema-Design, die Datenspeicherung und die Abfragen. Wenn Du die RAG Grundlagen noch nicht kennst, lies Dir diesen Artikel zuerst durch. Grundlagen zu Embedding-Modellen sind ebenfalls hilfreich.

Warum brauche ich Weaviate?

Stell Dir vor, Du betreibst eine Wissensbasis mit Tausenden von Dokumenten. Manche Fragen lassen sich gut über semantische Ähnlichkeit beantworten, also Vektorsuche. Andere Fragen enthalten spezifische Schlüsselwörter oder Eigennamen, die mit reiner Vektorsuche schlecht gefunden werden. Du bräuchtest also beides: Vektor- und Schlüsselwortsuche in einer Abfrage.

Mit den meisten Vektordatenbanken musst Du Dich für einen Ansatz entscheiden oder externe Tools wie BM25 hinzuschalten. Weaviate bringt Hybrid Search direkt mit. Du gewichtest Vektor- und Schlüsselwortsuche in einer einzigen Abfrage und bekommst Ergebnisse, die beide Welten kombinieren.

Hinzu kommt die GraphQL-API. Statt eine proprietäre REST-Schnittstelle zu lernen, nutzt Du eine standardisierte Abfragesprache, die viele Entwickler bereits kennen. Du kannst komplexe Filter, Sortierungen und Beziehungen zwischen Datenobjekten in einer einzigen Abfrage ausdrücken. Das ist besonders wertvoll, wenn Deine RAG-Anwendung strukturierte Metadaten und unstrukturierte Texte kombiniert.

Das Modulsystem ist ein weiteres Plus. Weaviate kann Embeddings direkt im Server berechnen, wenn Du ein Modul wie text2vec-transformers aktivierst. Du schickst also rohen Text an Weaviate, und die Datenbank kümmert sich um die Vektorisierung. Für lokale Setups kannst Du aber auch eigene Vektoren übergeben, was wir in diesem Artikel behandeln.

Weaviate kurz erklärt

Weaviate speichert Daten als Objekte mit Eigenschaften und Vektoren. Jedes Objekt gehört zu einer Klasse, die Du im Schema definierst. Das Schema ist vergleichbar mit dem Tabellenaufbau in einer relationalen Datenbank: Du legst fest, welche Felder eine Klasse hat, welchen Datentyp sie haben und ob sie vektorisiert werden sollen.

Bei einer Suchanfrage wandelt Weaviate die Anfrage in einen Vektor um, vergleicht ihn mit den gespeicherten Vektoren und liefert die ähnlichsten Objekte zurück. Das ist die klassische Vektorsuche. Mit Hybrid Search kombiniert Weaviate diese Vektorsuche mit einer Schlüsselwortsuche und gewichtet beide nach einem Parameter, den Du steuern kannst.

Die GraphQL-API ist die Hauptschnittstelle für alle Abfragen. Du schreibst GraphQL-Queries, um Objekte abzufragen, zu filtern und zu durchsuchen. Für das Schreiben und Aktualisieren von Objekten nutzt Du die REST-API oder den Python-Client, der beides für Dich abstrahiert.

Für wen ist dieser Artikel gedacht?

Dieser Artikel richtet sich an Entwickler, die bereits grundlegend mit RAG und Vektordatenbanken vertraut sind. Du solltest verstehen, was lokale KI ist und wie RAG funktioniert. Wenn Du bereits Chroma oder Qdrant ausprobiert hast, ist dieser Artikel der logische nächste Schritt. Du brauchst grundlegende Python-Kenntnisse und solltest wissen, wie man Docker bedient, da wir Weaviate in einem Docker-Container betreiben.

Wichtige Begriffe

Begriff	Erklärung
Class	Eine Kategorie von Datenobjekten, vergleichbar mit einer Tabelle. Jede Klasse hat definierte Eigenschaften.
Schema	Die Definition aller Klassen, Eigenschaften und Vektorisierer. Wird vor dem Speichern von Daten angelegt.
Object	Ein einzelner Datensatz innerhalb einer Klasse, bestehend aus Eigenschaften und einem Vektor.
Vector	Ein numerischer Array, der den semantischen Inhalt eines Objekts repräsentiert.
Module	Ein Plugin, das Vektorisierung oder andere Funktionen übernimmt, etwa text2vec-transformers.
Hybrid Search	Eine Suchmethode, die Vektorsuche und Schlüsselwortsuche kombiniert und gewichtet.
GraphQL	Eine Abfragesprache, mit der Du strukturierte Abfragen an Weaviate stellst.
BM25	Ein Algorithmus für die Schlüsselwortsuche, der auf Termfrequenz und Dokumentlänge basiert.
Vectorizer	Ein Modul, das Text automatisch in Vektoren umwandelt, ohne dass Du externe Embeddings berechnen musst.

Installation: Weaviate mit Docker starten

Weaviate läuft am besten in einem Docker-Container. Wenn Du Docker noch nicht installiert hast, schau Dir die Docker Grundlagen an.

Die einfachste Variante ist ein einzelner Docker-Container ohne externe Module. Diese Konfiguration ist ideal für den Einstieg, weil Du eigene Vektoren mitbringst und Weaviate nur als Speicher und Suchmaschine nutzt.

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:latest

Nach dem Start erreichst Du Weaviate unter http://localhost:8080. Du kannst prüfen, ob der Server läuft, indem Du die Status-Abfrage aufrufst:

curl http://localhost:8080/v1/.well-known/ready

Wenn die Antwort READY lautet, ist Weaviate einsatzbereit. Das Docker-Volume weaviate_data sorgt dafür, dass Deine Daten auch nach einem Neustart des Containers erhalten bleiben.

Für komplexere Setups mit integrierten Vektorisierungs-Modulen empfiehlt sich Docker Compose. Weaviate stellt fertige docker-compose.yml-Dateien bereit, die zusätzliche Container für Transformer-Modelle starten. Für diesen Artikel reicht der einfache Container aus, da wir eigene Vektoren verwenden.

Python-Client installieren

Weaviate bietet einen offiziellen Python-Client, der die REST- und GraphQL-API abstrahiert. Installiere ihn mit pip:

pip install weaviate-client

Danach verbindest Du Dich in Python mit Deiner lokalen Weaviate-Instanz:

import weaviate

client = weaviate.connect_to_local(
    host="localhost",
    port=8080
)

print(client.is_ready())  # True, wenn die Verbindung steht

Der Python-Client nutzt die neue v4-API, die ein typisiertes und intuitiveres Interface bietet. Falls Du ältere Tutorials findest, die die v3-API verwenden, beachte dass sich die Syntax unterscheidet.

Schema designen

Bevor Du Daten speicherst, legst Du ein Schema an. Das Schema definiert, welche Klassen es gibt und welche Eigenschaften sie haben. Hier legst Du auch fest, ob Weaviate selbst vektorisieren soll oder ob Du externe Vektoren übergibst.

In unserem Beispiel erstellen wir eine Klasse Article mit den Eigenschaften title, content und source. Wir setzen keinen internen Vektorisierer, sondern bringen eigene Vektoren mit.

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),
    ]
)

Die Einstellung Configure.Vectorizer.none() bedeutet, dass Weaviate keine automatische Vektorisierung durchführt. Du übergibst die Vektoren selbst, die Du mit einem externen Embedding-Modell berechnest.

Wenn Du stattdessen ein Modul wie text2vec-transformers nutzen willst, setzt Du den Vektorisierer auf das entsprechende Modul. Dann benötigt Weaviate aber einen zusätzlichen Container mit dem Transformer-Modell, was den Ressourcenbedarf erhöht.

Daten speichern

Jetzt fügen wir Objekte zur Klasse Article hinzu. Da wir keinen internen Vektorisierer konfiguriert haben, müssen wir den Vektor selbst übergeben.

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
    }
])

In der Praxis erzeugst Du die Vektoren mit einem Embedding-Modell wie intfloat/multilingual-e5-large oder BAAI/bge-m3. Die Dimension des Vektors muss für alle Objekte in einer Klasse gleich sein. Wenn sich das Embedding-Modell ändert, musst Du die Daten neu vektorisieren.

Suchanfragen durchführen

Weaviate unterstützt drei Arten von Suchen: reine Vektorsuche, Schlüsselwortsuche (BM25) und Hybrid Search. Schauen wir uns alle drei an.

Vektorsuche

Bei der Vektorsuche übergibst Du einen Suchvektor und bekommst die ähnlichsten Objekte zurück:

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"])

Schlüsselwortsuche mit BM25

Die BM25-Suche findet Objekte anhand von Schlüsselwörtern. Sie ist gut für Eigennamen und spezifische Begriffe:

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 kombiniert Vektorsuche und BM25. Der Parameter alpha steuert die Gewichtung: alpha=0 bedeutet reine BM25-Suche, alpha=1 bedeutet reine Vektorsuche. Ein Wert von 0.5 gewichtet beide gleich.

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 ist besonders für RAG wertvoll, weil viele Fragen sowohl semantische als auch schlüsselwortbasierte Anteile haben. Mehr dazu im Artikel zu Hybrid Search.

Filterung

Weaviate erlaubt es, Suchergebnisse nach Eigenschaften zu filtern. Das ist wichtig, wenn Du nur bestimmte Quellen oder Zeiträume durchsuchen willst.

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"])

Filter lassen sich mit and_ und or_ kombinieren, um komplexe Bedingungen zu formulieren. Das ist mächtiger als einfache Metadaten-Filter in anderen Datenbanken.

Vergleich: Weaviate vs. Chroma vs. Qdrant

Eigenschaft	Weaviate	Chroma	Qdrant
Abfragesprache	GraphQL	Python-API	REST und gRPC
Hybrid Search	Integriert	Begrenzt	Mit Sparse Vectors
Automatische Vektorisierung	Ja, über Module	Ja, über Embedding-Funktionen	Ja, über FastEmbed
Schema	Explizit, Klassen-basiert	Implizit, Collection-basiert	Collection-basiert
Skalierung	Gut, auch verteilt möglich	Eher klein bis mittel	Gut, produktionsreif
Einstiegshürde	Mittel	Sehr niedrig	Niedrig bis mittel
GraphQL	Ja	Nein	Nein
Filter	Sehr mächtig, kombinierbar	Einfach	Sehr mächtig
Ressourcenbedarf	Mittel	Niedrig	Niedrig bis mittel

Weaviate glänzt, wenn Du Hybrid Search ohne externe Tools brauchst und GraphQL als Abfragesprache schätzt. Chroma ist einfacher für den schnellen Start, Qdrant ist robuster für reine Vektorsuche bei großen Datenmengen. Weaviate bietet die meisten Features out of the box, verlangt aber etwas mehr Einarbeitung.

Typische Stolpersteine

1. Schema vor Daten anlegen: Weaviate verlangt ein Schema, bevor Du Daten speichern kannst. Wenn Du versuchst, Objekte in eine nicht existierende Klasse einzufügen, bekommst Du einen Fehler. Lege das Schema immer zuerst an.
2. Vektor-Dimension muss konsistent sein: Alle Vektoren in einer Klasse müssen dieselbe Dimension haben. Wenn Du das Embedding-Modell wechselst, musst Du die Klasse neu anlegen und die Daten neu laden.
3. Vektorisierer falsch konfiguriert: Wenn Du Configure.Vectorizer.none() setzt, aber keine Vektoren übergibst, speichert Weaviate Objekte ohne Vektor. Suchen schlagen dann fehl. Prüfe, ob der Vektorisierer zur Deiner Datenübergabe passt.
4. GraphQL-Syntax unterschätzen: GraphQL ist mächtig, aber fehleranfällig. Ein falsches Feld oder ein Tippfehler im Query führt zu kryptischen Fehlern. Nutze den Python-Client, der die Syntax für Dich generiert.
5. Persistenz-Volume vergessen: Ohne ein Docker-Volume sind alle Daten nach einem Neustart weg. Konfiguriere immer PERSISTENCE_DATA_PATH mit einem Volume.
6. Ressourcenbedarf bei Modulen: Wenn Du Vektorisierungs-Module wie text2vec-transformers aktivierst, braucht Weaviate deutlich mehr RAM und CPU. Für lokale Setups ohne GPU ist es oft besser, Vektoren extern zu berechnen.
7. Authentifizierung deaktiviert lassen: In unserem Beispiel haben wir anonymen Zugriff aktiviert. Das ist für lokale Tests in Ordnung, sollte aber nie für öffentlich erreichbare Instanzen genutzt werden.
8. Indizes nicht verstehen: Weaviate nutzt standardmäßig HNSW für die Vektorindizierung. Wenn Du sehr große Datenmengen hast, solltest Du Dich mit den Index-Parametern vertraut machen, um die Suchgeschwindigkeit zu optimieren.

Hardware, Kosten und Sicherheit

Weaviate ohne Vektorisierungs-Module ist ressourcenschonend. Für ein paar Tausend Dokumente reicht ein Rechner mit 4 GB RAM und einer normalen CPU. Wenn Du Module wie text2vec-transformers aktivierst, steigt der RAM-Bedarf auf 8 GB oder mehr, und eine GPU beschleunigt die Vektorisierung erheblich.

Weaviate ist Open Source und kostenlos. Die Community Edition deckt alle Funktionen ab, die Du für lokale RAG-Projekte brauchst. Es gibt auch eine kommerzielle Cloud-Version, die für lokale Setups nicht relevant ist.

Sicherheitstechnisch gilt dasselbe wie für andere lokale Datenbanken: Solange Weaviate nur im eigenen Netzwerk erreichbar ist, sind Deine Daten geschützt. Wenn Du Weaviate über das Netzwerk zugänglich machst, aktiviere Authentifizierung und nutze einen Reverse Proxy mit TLS. Da alle Daten lokal bleiben, ist das ein großer Vorteil gegenüber Cloud-basierten Vektordatenbanken, wie im Artikel zu lokaler KI vs. Cloud-KI erläutert.

Weiterführende Links

• Vektordatenbanken Übersicht - Alle Vektordatenbank-Artikel
• Lokales RAG - Übersicht aller RAG-Artikel
• RAG Grundlagen - Wie RAG funktioniert
• Embedding-Modelle - Vektoren aus Text erzeugen
• Hybrid Search - Vektor- und Schlüsselwortsuche kombinieren
• Chroma - Einfache Vektordatenbank
• Qdrant - Skalierbare Vektordatenbank
• Docker Grundlagen - Container-Technologie verstehen

FAQ

Muss ich GraphQL lernen, um Weaviate zu nutzen?

Nein, nicht zwingend. Der Python-Client abstrahiert die GraphQL-Abfragen für Dich. Wenn Du aber komplexe Abfragen mit Filtern und Beziehungen brauchst, ist es hilfreich, die GraphQL-Grundlagen zu verstehen.

Kann Weaviate eigene Vektoren berechnen?

Ja, mit Modulen wie text2vec-transformers oder text2vec-cohere. Für lokale Setups ohne GPU ist es oft effizienter, Vektoren extern zu berechnen und an Weaviate zu übergeben.

Ist Weaviate kostenlos?

Ja, die Open-Source-Version ist kostenlos und deckt alle Funktionen für lokale Projekte ab. Es gibt eine kostenpflichtige Cloud-Version, die für lokale Setups nicht nötig ist.

Wie viele Dokumente verträgt Weaviate lokal?

Das hängt von RAM und Speicherplatz ab. Für Hunderttausende bis Millionen von Objekten ist Weaviate geeignet. Bei sehr großen Datenmengen solltest Du die Index-Parameter optimieren.

Kann ich Weaviate mit Ollama verbinden?

Ja. Ollama liefert das Sprachmodell, Weaviate die Vektordatenbank. Dein Python-Skript verbindet beide: Weaviate findet die relevanten Dokumente, Ollama generiert die Antwort.

Was ist der Unterschied zwischen Weaviate und Chroma?

Chroma ist einfacher und schneller einzurichten, ideal für Prototypen. Weaviate bietet mehr Features wie GraphQL, Hybrid Search und ein Modulsystem, ist aber komplexer in der Einrichtung.

Brauche ich Docker für Weaviate?

Docker ist der empfohlene Weg, aber es gibt auch Binärdateien. Für lokale Tests und Produktionssysteme ist Docker am einfachsten und am besten dokumentiert.

Unterstützt Weaviate hybride Suche?

Ja, Hybrid Search ist eine der Stärken von Weaviate. Du gewichtest Vektor- und Schlüsselwortsuche mit dem Parameter alpha und bekommst kombinierte Ergebnisse.

Kann ich Weaviate auf einem NAS betreiben?

Ja, mit Docker. Achte auf ausreichend RAM und schnellen Speicher. Weaviate profitiert von SSD-Speicher, besonders bei großen Datenmengen.

Wie sichere ich Weaviate ab?

Lokale Instanzen ohne Netzwerkexposition sind in sicheren Netzwerken meist ausreichend. Für den Zugriff über das Netz aktiviere Authentifizierung und nutze einen Reverse Proxy mit TLS-Verschlüsselung.

Was ist der Unterschied zwischen Weaviate und Qdrant?

Qdrant ist schlanker und fokussierter auf reine Vektorsuche. Weaviate bietet mehr Funktionen wie GraphQL, ein Modulsystem und integrierte Hybrid Search, verbraucht aber etwas mehr Ressourcen.

Quellen

• Weaviate offizielle Webseite: weaviate.io
• Weaviate Dokumentation: weaviate.io/developers/weaviate
• Weaviate Python Client: github.com/weaviate/weaviate-python-client
• Weaviate GitHub Repository: github.com/weaviate/weaviate
• Artikel zu Vektordatenbanken in dieser Reihe
• Artikel zu Hybrid Search in dieser Reihe