Análise e guia de instalação do SurrealDB: um único banco de dados para apps de IA e de agentes

Um app de IA que se lembra das coisas costuma acabar com três bancos de dados: um para usuários e sessões, um para documentos e um armazenamento vetorial separado para busca. O SurrealDB é um banco de dados multimodelo de código aberto que reúne dados de documentos, grafos, relacionais, vetoriais, geoespaciais e de séries temporais em um só lugar. Ele serve a desenvolvedores que criam apps local-first, fluxos de agentes ou backends para modelos de linguagem.

Este guia mostra o que ele tem de diferente, como instalá-lo e rodá-lo localmente e como usá-lo com modelos servidos pelo Ollama. Ele foi escrito a partir de uma configuração de desenvolvimento local com LLMs de código aberto, que, segundo esse relato, foi rápida de pôr para funcionar e simples de usar.

Por que ele serve para aplicações de IA

O SurrealDB cobre vários tipos de dados em um único banco:

• Tabelas relacionais para metadados estruturados, como usuários e sessões
• Documentos e grafos para relações e conteúdo aninhado
• Vetores para busca por similaridade em geração aumentada por recuperação (RAG), em que o modelo consulta textos relevantes antes de responder
• Implantação embarcada ou distribuída

Isso o torna adequado para memória de chatbots, pipelines de RAG com modelos de embeddings de código aberto, acompanhamento do estado de um agente e implantações privadas que nunca saem da sua máquina.

Como funciona

Todos esses modelos de dados são consultados por uma única linguagem, a SurrealQL, que se parece com SQL e lida com consultas entre tipos de dados e relações. Apesar da amplitude, é leve: roda com folga em um notebook, pode ser embarcado em um app e também escala para um cluster.

O design separa computação de armazenamento:

• A camada de consulta analisa e executa consultas e gerencia transações.
• A camada de armazenamento pode usar engines diferentes:
  • RocksDB para uso embarcado, em memória,
  • TiKV para configurações distribuídas,
  • IndexedDB para apps que rodam no navegador.

Por causa dessa divisão, as mesmas consultas e a mesma lógica funcionam em uma única máquina e em um sistema distribuído. Você pode rodar o SurrealDB como o banco de dados por trás do seu app, como um backend-as-a-service completo com autenticação e permissões, ou embarcado em um agente de IA de desktop ou de navegador.

Passo 1: instale o SurrealDB

No Ubuntu ou em outra distribuição Linux:

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

Mova o binário para o seu path:

sudo mv surreal /usr/local/bin/

Confira se foi instalado:

surreal version

Você deve ver algo como:

surreal 1.0.0-beta.9 (linux-x86_64)

Passo 2: inicie-o localmente

Em memória, para desenvolvimento e testes:

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

Com os dados salvos em disco:

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

Por padrão, ele escuta por HTTP na porta 8000.

Passo 3: conecte-se pelo Python

Instale o cliente:

pip install surrealdb

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

Passo 4: armazene vetores

Você pode armazenar embeddings de qualquer modelo, por exemplo um servido pelo Ollama ou vindo do Hugging Face. Este exemplo usa embeddings da 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})

A filtragem por similaridade de cosseno pode então ser feita em SurrealQL, se a sua versão aceitar.

Exemplo: um chatbot local com memória

Sirva um modelo local com o Ollama:

ollama run llama3

O chatbot então funciona assim:

1. O Ollama processa a mensagem do usuário, e o modelo escreve uma resposta e um resumo.
2. O resumo é transformado em um embedding e salvo no SurrealDB.
3. Quando o chatbot reinicia, ele encontra conversas anteriores por similaridade vetorial e as acrescenta ao prompt.

Segundo o relato, a recuperação a partir do banco foi rápida e precisa mesmo nessa forma básica, o que torna o SurrealDB uma escolha razoável para agentes e assistentes que precisam se lembrar de coisas sem chamar uma API externa.

Como é trabalhar com ele

• Configuração rápida: instale, rode e conecte em menos de 5 minutos.
• Um sistema de schema capaz: defina tipos de documento, índices, restrições e relações no próprio banco.
• Vetores embutidos: você não precisa do Pinecone, do Qdrant nem de outro banco vetorial separado.
• Bom para protótipos: o modo em memória permite testar ideias sem montar infraestrutura na nuvem.
• SDKs em várias linguagens: aqui se usa Python, e há clientes para Node.js, Rust, Go e outras.
• Totalmente offline: roda localmente sem depender da nuvem, o que ajuda em trabalhos sensíveis à privacidade, na borda ou regulados.

O porém: este guia foi escrito com base em uma versão beta (1.0.0-beta.9), e a busca por similaridade vetorial em SurrealQL dependia da versão que você tinha, então confira o que a sua build aceita antes de planejar um sistema de RAG em torno dela.

Nossa opinião: se o seu projeto de IA precisaria de um banco relacional e de um armazenamento vetorial lado a lado, o SurrealDB permite que um único processo local faça os dois trabalhos, e é rápido o bastante de configurar para que prototipar com ele custe muito pouco.

O código está no GitHub. Para orquestrar os agentes que ficam sobre um banco de dados como este, veja nossa análise do Kiro.