SurrealDB im Test mit Installationsanleitung: eine Datenbank für KI- und Agent-Apps

Eine KI-App, die sich Dinge merkt, landet meist bei drei Datenbanken: einer für Nutzer und Sitzungen, einer für Dokumente und einem separaten Vektorspeicher für die Suche. SurrealDB ist eine Open-Source-Multi-Model-Datenbank, die Dokument-, Graph-, relationale, Vektor-, Geo- und Zeitreihendaten an einem Ort zusammenführt. Sie passt zu Entwicklern, die Local-first-Apps, Agent-Workflows oder Backends für Sprachmodelle bauen.

Diese Anleitung behandelt, was an ihr anders ist, wie du sie lokal installierst und betreibst und wie du sie mit Modellen nutzt, die über Ollama bereitgestellt werden. Sie entstand anhand einer lokalen Entwicklungsumgebung mit Open-Source-LLMs, die laut diesem Bericht schnell lief und einfach zu handhaben war.

Warum sie zu KI-Anwendungen passt

SurrealDB deckt mehrere Datenarten in einer Datenbank ab:

• Relationale Tabellen für strukturierte Metadaten wie Nutzer und Sitzungen
• Dokumente und Graphen für Beziehungen und verschachtelte Inhalte
• Vektoren für Ähnlichkeitssuche bei Retrieval-Augmented Generation (RAG), bei der das Modell vor dem Antworten relevanten Text nachschlägt
• Eingebettete oder verteilte Bereitstellung

Damit passt sie für Chatbot-Gedächtnis, RAG-Pipelines mit Open-Source-Embedding-Modellen, das Festhalten des Zustands eines Agenten und private Installationen, die deinen Rechner nie verlassen.

Wie sie funktioniert

All diese Datenmodelle werden über eine einzige Sprache abgefragt, SurrealQL, die wie SQL aussieht und Abfragen über Datentypen und Beziehungen hinweg beherrscht. Trotz der Breite ist sie schlank: Sie läuft problemlos auf einem Laptop, lässt sich in eine App einbetten und skaliert auch zu einem Cluster.

Das Design trennt Rechnen von Speichern:

• Die Abfrageschicht parst und führt Abfragen aus und verwaltet Transaktionen.
• Die Speicherschicht kann verschiedene Engines nutzen:
  • RocksDB für eingebettete Nutzung im Arbeitsspeicher,
  • TiKV für verteilte Setups,
  • IndexedDB für Apps, die im Browser laufen.

Wegen dieser Trennung funktionieren dieselben Abfragen und dieselbe Logik auf einer einzelnen Maschine und auf einem verteilten System. Du kannst SurrealDB als Datenbank hinter deiner App betreiben, als vollständiges Backend-as-a-Service mit Authentifizierung und Berechtigungen oder eingebettet in einen KI-Agenten auf dem Desktop oder im Browser.

Schritt 1: SurrealDB installieren

Unter Ubuntu oder einer anderen Linux-Distribution:

curl -sSf https://install.surrealdb.com | sh

Verschiebe die Binärdatei in deinen Pfad:

sudo mv surreal /usr/local/bin/

Prüfe die Installation:

surreal version

Du solltest etwa Folgendes sehen:

surreal 1.0.0-beta.9 (linux-x86_64)

Schritt 2: lokal starten

Im Arbeitsspeicher, für Entwicklung und Tests:

surreal start --log debug --user root --pass root memory

Mit Daten, die auf die Festplatte gespeichert werden:

surreal start --log debug --user root --pass root file:/path/to/data

Standardmäßig lauscht sie über HTTP auf Port 8000.

Schritt 3: aus Python verbinden

Installiere den Client:

pip install surrealdb

Ein minimales Beispiel:

from surrealdb import Surreal
import asyncio

async def run():
    db = Surreal()
    await db.connect("http://localhost:8000/rpc")

    # Sign in
    await db.signin({"user": "root", "pass": "root"})
    await db.use("test", "test")

    # Create a document
    await db.query("CREATE message CONTENT { text: 'Hello from SurrealDB!' }")

    # Query it back
    results = await db.query("SELECT * FROM message")
    print(results)

asyncio.run(run())

Schritt 4: Vektoren speichern

Du kannst Embeddings aus jedem Modell speichern, zum Beispiel aus einem über Ollama bereitgestellten oder von Hugging Face. Dieses Beispiel nutzt Embeddings von OpenAI:

from openai import OpenAI
import numpy as np

# Assume you have your API key and text
response = openai.Embedding.create(
    input="This is a sample text",
    model="text-embedding-ada-002"
)
embedding = response['data'][0]['embedding']

await db.query("CREATE vector_doc CONTENT { id: 'doc1', text: 'This is a sample text', embedding: $embedding }", {"embedding": embedding})

Filtern nach Kosinus-Ähnlichkeit lässt sich dann in SurrealQL erledigen, sofern deine Version es unterstützt.

Beispiel: ein lokaler Chatbot mit Gedächtnis

Stelle mit Ollama ein lokales Modell bereit:

ollama run llama3

Der Chatbot funktioniert dann so:

1. Ollama verarbeitet die Nachricht des Nutzers, und das Modell schreibt eine Antwort und eine Zusammenfassung.
2. Die Zusammenfassung wird in ein Embedding umgewandelt und in SurrealDB gespeichert.
3. Wenn der Chatbot neu startet, findet er frühere Gespräche über Vektorähnlichkeit und fügt sie dem Prompt hinzu.

Laut dem Bericht war der Abruf aus der Datenbank selbst in dieser einfachen Form schnell und genau, was SurrealDB zu einer vernünftigen Wahl für Agenten und Assistenten macht, die sich Dinge merken müssen, ohne eine externe API aufzurufen.

Wie sich die Arbeit damit anfühlt

• Schnelle Einrichtung: installieren, starten und verbinden in unter 5 Minuten.
• Ein leistungsfähiges Schemasystem: Dokumenttypen, Indizes, Constraints und Beziehungen in der Datenbank selbst definieren.
• Eingebaute Vektoren: Du brauchst kein Pinecone, Qdrant oder eine andere separate Vektordatenbank.
• Gut für Prototypen: Der In-Memory-Modus lässt dich Ideen ausprobieren, ohne Cloud-Infrastruktur einzurichten.
• SDKs in mehreren Sprachen: Hier wird Python genutzt, und es gibt Clients für Node.js, Rust, Go und mehr.
• Komplett offline: Sie läuft lokal ohne Cloud-Abhängigkeit, was bei datenschutzsensibler, Edge- oder regulierter Arbeit hilft.

Der Haken: Diese Anleitung wurde für eine Beta-Version (1.0.0-beta.9) geschrieben, und die Vektor-Ähnlichkeitssuche in SurrealQL hing von deiner Version ab, prüfe also, was dein Build unterstützt, bevor du ein RAG-System darauf planst.

Unser Fazit: Wenn dein KI-Projekt sonst eine relationale Datenbank und einen Vektorspeicher nebeneinander bräuchte, lässt SurrealDB einen einzigen lokalen Prozess beide Aufgaben erledigen, und die Einrichtung geht so schnell, dass dich Prototyping darauf sehr wenig kostet.

Der Code liegt auf GitHub. Zur Orchestrierung der Agenten, die auf einer solchen Datenbank aufsetzen, siehe unseren Testbericht zu Kiro.