Test et guide d'installation de SurrealDB : une seule base de données pour les applications d'IA et d'agents

Une application d'IA qui se souvient des choses finit généralement avec trois bases de données : une pour les utilisateurs et les sessions, une pour les documents et un magasin vectoriel distinct pour la recherche. SurrealDB est une base de données open source multimodèle qui réunit au même endroit des données de type document, graphe, relationnel, vectoriel, géospatial et séries temporelles. Elle convient aux développeurs qui créent des applications local-first, des workflows d'agents ou des back-ends pour des modèles de langage.

Ce guide explique ce qui la distingue, comment l'installer et la faire tourner en local, et comment l'utiliser avec des modèles servis par Ollama. Il a été rédigé à partir d'un environnement de développement local avec des LLM open source, qui, selon ce compte rendu, a été rapide à mettre en route et simple à utiliser.

Pourquoi elle convient aux applications d'IA

SurrealDB couvre plusieurs types de données dans une seule base :

• des tables relationnelles pour les métadonnées structurées comme les utilisateurs et les sessions
• des documents et des graphes pour les relations et les contenus imbriqués
• des vecteurs pour la recherche par similarité dans la génération augmentée par récupération (RAG), où le modèle cherche un texte pertinent avant de répondre
• un déploiement embarqué ou distribué

Cela la rend adaptée à la mémoire de chatbots, aux pipelines RAG avec des modèles d'embedding open source, au suivi de l'état d'un agent et aux déploiements privés qui ne quittent jamais votre machine.

Comment elle fonctionne

Tous ces modèles de données s'interrogent avec un seul langage, SurrealQL, qui ressemble à SQL et gère les requêtes portant sur plusieurs types de données et leurs relations. Malgré cette étendue, elle est légère : elle tourne confortablement sur un ordinateur portable, peut être intégrée à une application et passe aussi à l'échelle sur un cluster.

Sa conception sépare le calcul du stockage :

• La couche de requêtes analyse et exécute les requêtes et gère les transactions.
• La couche de stockage peut utiliser différents moteurs :
  • RocksDB pour un usage embarqué, en mémoire,
  • TiKV pour les configurations distribuées,
  • IndexedDB pour les applications qui tournent dans le navigateur.

Grâce à cette séparation, les mêmes requêtes et la même logique fonctionnent sur une seule machine comme sur un système distribué. Vous pouvez utiliser SurrealDB comme base de données derrière votre application, comme backend-as-a-service complet avec authentification et autorisations, ou intégrée dans un agent IA de bureau ou dans le navigateur.

Étape 1 : installer SurrealDB

Sur Ubuntu ou une autre distribution Linux :

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

Placez le binaire dans votre PATH :

sudo mv surreal /usr/local/bin/

Vérifiez l'installation :

surreal version

Vous devriez voir quelque chose comme :

surreal 1.0.0-beta.9 (linux-x86_64)

Étape 2 : la lancer en local

En mémoire, pour le développement et les tests :

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

Avec les données enregistrées sur disque :

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

Par défaut, elle écoute en HTTP sur le port 8000.

Étape 3 : se connecter depuis Python

Installez le client :

pip install surrealdb

Un exemple minimal :

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())

Étape 4 : stocker des vecteurs

Vous pouvez stocker des embeddings issus de n'importe quel modèle, par exemple un modèle servi par Ollama ou provenant de Hugging Face. Cet exemple utilise des embeddings 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})

Le filtrage par similarité cosinus peut ensuite se faire en SurrealQL, si votre version le prend en charge.

Exemple : un chatbot local avec mémoire

Servez un modèle local avec Ollama :

ollama run llama3

Le chatbot fonctionne ensuite ainsi :

1. Ollama traite le message de l'utilisateur et le modèle rédige une réponse et un résumé.
2. Le résumé est transformé en embedding et enregistré dans SurrealDB.
3. Quand le chatbot redémarre, il retrouve les conversations passées par similarité vectorielle et les ajoute à la consigne.

Selon le compte rendu, la récupération depuis la base était rapide et précise, même sous cette forme basique, ce qui fait de SurrealDB un choix raisonnable pour les agents et les assistants qui doivent se souvenir de choses sans appeler d'API externe.

À l'usage

• Installation rapide : installer, lancer et se connecter en moins de 5 minutes.
• Un système de schéma performant : définissez les types de documents, les index, les contraintes et les relations dans la base elle-même.
• Vecteurs intégrés : vous n'avez pas besoin de Pinecone, de Qdrant ni d'une autre base vectorielle distincte.
• Idéal pour les prototypes : le mode en mémoire permet d'essayer des idées sans mettre en place d'infrastructure cloud.
• Des SDK dans plusieurs langages : Python est utilisé ici, et il existe des clients pour Node.js, Rust, Go et d'autres.
• Entièrement hors ligne : elle tourne en local sans dépendance au cloud, ce qui aide pour les travaux sensibles en matière de confidentialité, en périphérie ou réglementés.

Le hic : ce guide a été rédigé pour une version bêta (1.0.0-beta.9), et la recherche par similarité vectorielle en SurrealQL dépendait de la version utilisée : vérifiez ce que votre build prend en charge avant de bâtir un système RAG autour.

Notre avis : si votre projet d'IA nécessiterait sinon une base relationnelle et un magasin vectoriel côte à côte, SurrealDB permet à un seul processus local de faire les deux, et elle est assez rapide à mettre en place pour que prototyper dessus ne vous coûte presque rien.

Le code est sur GitHub. Pour orchestrer les agents qui reposent sur une base de données comme celle-ci, consultez notre test de Kiro.