Análisis y guía de instalación de SurrealDB: una sola base de datos para aplicaciones de IA y de agentes

Una aplicación de IA que recuerda cosas suele acabar con tres bases de datos: una para usuarios y sesiones, otra para documentos y un almacén vectorial aparte para la búsqueda. SurrealDB es una base de datos multimodelo de código abierto que reúne datos de documentos, grafos, relacionales, vectoriales, geoespaciales y de series temporales en un solo sitio. Conviene a desarrolladores que construyen aplicaciones local-first, flujos de trabajo de agentes o backends para modelos de lenguaje.

Esta guía cubre qué tiene de distinto, cómo instalarla y ejecutarla en local, y cómo usarla con modelos servidos a través de Ollama. Se redactó a partir de una configuración de desarrollo local con LLM de código abierto que, según ese informe, fue rápida de poner en marcha y sencilla de manejar.

Por qué encaja en aplicaciones de IA

SurrealDB cubre varios tipos de datos en una sola base de datos:

• Tablas relacionales para metadatos estructurados como usuarios y sesiones
• Documentos y grafos para relaciones y contenido anidado
• Vectores para la búsqueda por similitud en la generación aumentada por recuperación (RAG), en la que el modelo busca texto relevante antes de responder
• Despliegue embebido o distribuido

Eso la hace adecuada para la memoria de chatbots, pipelines RAG con modelos de embeddings de código abierto, el seguimiento del estado de un agente y despliegues privados que nunca salen de tu máquina.

Cómo funciona

Todos esos modelos de datos se consultan con un solo lenguaje, SurrealQL, que se parece a SQL y maneja consultas entre tipos de datos y relaciones. A pesar de su amplitud, es ligera: funciona con soltura en un portátil, se puede embeber en una aplicación y también escala a un clúster.

El diseño separa el cómputo del almacenamiento:

• La capa de consultas analiza y ejecuta las consultas y gestiona las transacciones.
• La capa de almacenamiento puede usar distintos motores:
  • RocksDB para uso embebido y en memoria,
  • TiKV para configuraciones distribuidas,
  • IndexedDB para aplicaciones que se ejecutan en el navegador.

Gracias a esa separación, las mismas consultas y la misma lógica funcionan en una sola máquina y en un sistema distribuido. Puedes ejecutar SurrealDB como la base de datos que hay detrás de tu aplicación, como un backend como servicio completo con autenticación y permisos, o embebida en un agente de IA de escritorio o de navegador.

Paso 1: instala SurrealDB

En Ubuntu u otra distribución de Linux:

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

Mueve el binario a tu path:

sudo mv surreal /usr/local/bin/

Comprueba que se ha instalado:

surreal version

Deberías ver algo así:

surreal 1.0.0-beta.9 (linux-x86_64)

Paso 2: arráncala en local

En memoria, para desarrollo y pruebas:

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

Con los datos guardados en disco:

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

Por defecto escucha por HTTP en el puerto 8000.

Paso 3: conéctate desde Python

Instala el cliente:

pip install surrealdb

Un ejemplo mínimo:

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

Paso 4: guarda vectores

Puedes guardar embeddings de cualquier modelo, por ejemplo uno servido por Ollama o de Hugging Face. Este ejemplo usa embeddings de 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})

Después se puede filtrar por similitud del coseno en SurrealQL, si tu versión lo admite.

Ejemplo: un chatbot local con memoria

Sirve un modelo local con Ollama:

ollama run llama3

El chatbot funciona entonces así:

1. Ollama procesa el mensaje del usuario y el modelo escribe una respuesta y un resumen.
2. El resumen se convierte en un embedding y se guarda en SurrealDB.
3. Cuando el chatbot se reinicia, encuentra conversaciones anteriores por similitud vectorial y las añade al prompt.

Según el informe, la recuperación desde la base de datos fue rápida y precisa incluso en esta forma básica, lo que convierte a SurrealDB en una opción razonable para agentes y asistentes que necesitan recordar cosas sin llamar a una API externa.

Cómo es trabajar con ella

• Configuración rápida: instalar, ejecutar y conectar en menos de 5 minutos.
• Un sistema de esquemas capaz: define tipos de documentos, índices, restricciones y relaciones en la propia base de datos.
• Vectores integrados: no necesitas Pinecone, Qdrant ni otra base de datos vectorial aparte.
• Buena para prototipos: el modo en memoria te permite probar ideas sin montar infraestructura en la nube.
• SDK en varios lenguajes: aquí se usa Python, y hay clientes para Node.js, Rust, Go y más.
• Totalmente sin conexión: funciona en local sin depender de la nube, lo que ayuda en trabajos sensibles a la privacidad, en edge o regulados.

La pega: esta guía se escribió con una versión beta (1.0.0-beta.9), y la búsqueda por similitud vectorial en SurrealQL dependía de la versión que tuvieras, así que comprueba qué admite tu compilación antes de planificar un sistema RAG en torno a ella.

Nuestra opinión: si tu proyecto de IA necesitaría de otro modo una base de datos relacional y un almacén vectorial en paralelo, SurrealDB permite que un solo proceso local haga ambos trabajos, y es lo bastante rápida de configurar como para que prototipar con ella te cueste muy poco.

El código está en GitHub. Para orquestar los agentes que funcionan sobre una base de datos como esta, consulta nuestro análisis de Kiro.