SurrealDB 리뷰와 설치 가이드: AI와 에이전트 앱을 위한 단일 데이터베이스

작성자 Andrew Miller · 2025년 8월 8일

보관된 글입니다. 2025년 8월에 작성된 글이며, 이후 가격, 모델, 기능이 바뀌었을 수 있습니다. 최신 내용은 최고의 벡터 데이터베이스에서 확인하세요.

무언가를 기억하는 AI 앱은 보통 데이터베이스를 세 개 갖게 됩니다. 사용자와 세션용 하나, 문서용 하나, 그리고 검색용 별도 벡터 저장소입니다. SurrealDB는 문서, 그래프, 관계형, 벡터, 지리 공간, 시계열 데이터를 한곳에 두는 오픈소스 멀티모델 데이터베이스입니다. 로컬 우선 앱, 에이전트 워크플로, 언어 모델용 백엔드를 만드는 개발자에게 맞습니다.

이 가이드는 무엇이 다른지, 로컬에서 설치하고 실행하는 방법, 그리고 Ollama로 제공되는 모델과 함께 쓰는 방법을 다룹니다. 오픈소스 LLM을 쓰는 로컬 개발 환경을 바탕으로 작성되었으며, 그 기록에 따르면 금방 실행할 수 있었고 다루기도 간단했습니다.

AI 애플리케이션에 맞는 이유

SurrealDB는 데이터베이스 하나로 여러 종류의 데이터를 다룹니다.

사용자와 세션 같은 구조화된 메타데이터를 위한 관계형 테이블
관계와 중첩된 콘텐츠를 위한 문서와 그래프
모델이 답하기 전에 관련 텍스트를 찾아보는 검색 증강 생성(RAG)의 유사도 검색을 위한 벡터
임베디드 또는 분산 배포

그래서 챗봇 메모리, 오픈소스 임베딩 모델을 쓰는 RAG 파이프라인, 에이전트의 상태 추적, 그리고 내 컴퓨터를 떠나지 않는 비공개 배포에 맞습니다.

작동 방식

이 모든 데이터 모델은 SQL처럼 생긴 하나의 언어 SurrealQL로 쿼리하며, 데이터 유형과 관계를 넘나드는 쿼리를 처리합니다. 폭이 넓은데도 가볍습니다. 노트북에서 무리 없이 돌아가고, 앱에 내장할 수 있으며, 클러스터로 확장할 수도 있습니다.

설계는 연산과 저장을 분리합니다.

쿼리 계층은 쿼리를 파싱하고 실행하며 트랜잭션을 관리합니다.
저장 계층은 여러 엔진을 쓸 수 있습니다.
- 임베디드 및 인메모리용 RocksDB,
- 분산 구성용 TiKV,
- 브라우저에서 돌아가는 앱용 IndexedDB.

이렇게 나뉘어 있어서 같은 쿼리와 로직이 단일 머신에서도 분산 시스템에서도 작동합니다. SurrealDB를 앱 뒤의 데이터베이스로, 인증과 권한을 갖춘 완전한 서비스형 백엔드로, 또는 데스크톱이나 브라우저 기반 AI 에이전트에 내장해서 쓸 수 있습니다.

1단계: SurrealDB 설치

Ubuntu나 다른 Linux 배포판에서:

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

바이너리를 경로로 옮깁니다.

sudo mv surreal /usr/local/bin/

설치를 확인합니다.

surreal version

다음과 비슷한 결과가 보여야 합니다.

surreal 1.0.0-beta.9 (linux-x86_64)

2단계: 로컬에서 시작

개발과 테스트용으로 메모리에서:

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

데이터를 디스크에 저장하면서:

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

기본적으로 8000 포트에서 HTTP로 수신합니다.

3단계: Python에서 연결

클라이언트를 설치합니다.

pip install surrealdb

최소 예제:

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

4단계: 벡터 저장

어떤 모델의 임베딩이든 저장할 수 있습니다. 예를 들어 Ollama로 제공되는 모델이나 Hugging Face의 모델입니다. 이 예제는 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})

그런 다음 사용하는 버전이 지원한다면 SurrealQL에서 코사인 유사도 필터링을 할 수 있습니다.

예제: 메모리가 있는 로컬 챗봇

Ollama로 로컬 모델을 제공합니다.

ollama run llama3

챗봇은 다음과 같이 작동합니다.

Ollama가 사용자의 메시지를 처리하고 모델이 답과 요약을 씁니다.
요약을 임베딩으로 바꿔 SurrealDB에 저장합니다.
챗봇이 다시 시작되면 벡터 유사도로 지난 대화를 찾아 프롬프트에 더합니다.

그 기록에 따르면 이 기본적인 형태에서도 데이터베이스에서의 회상이 빠르고 정확했으며, 그래서 SurrealDB는 외부 API를 호출하지 않고 무언가를 기억해야 하는 에이전트와 어시스턴트에 합리적인 선택입니다.

써 보면 어떤가

빠른 설정: 5분 안에 설치, 실행, 연결까지 끝납니다.
쓸 만한 스키마 시스템: 문서 유형, 인덱스, 제약 조건, 관계를 데이터베이스 안에서 정의합니다.
내장 벡터: Pinecone, Qdrant 같은 별도의 벡터 데이터베이스가 필요 없습니다.
프로토타입에 좋음: 인메모리 모드로 클라우드 인프라를 설정하지 않고 아이디어를 시험할 수 있습니다.
여러 언어의 SDK: 여기서는 Python을 썼고, Node.js, Rust, Go 등용 클라이언트가 있습니다.
완전한 오프라인: 클라우드 의존 없이 로컬에서 돌아가므로, 개인정보에 민감한 작업, 엣지 작업, 규제 대상 작업에 도움이 됩니다.

주의할 점: 이 가이드는 베타 릴리스(1.0.0-beta.9)를 기준으로 작성되었고, SurrealQL의 벡터 유사도 검색은 쓰는 버전에 따라 달랐으니, RAG 시스템을 그 위에 설계하기 전에 빌드가 무엇을 지원하는지 확인하십시오.

결론: AI 프로젝트에 관계형 데이터베이스와 벡터 저장소를 나란히 두어야 한다면, SurrealDB는 로컬 프로세스 하나로 두 일을 다 하게 해 주며, 설정이 빨라서 그 위에서 프로토타입을 만드는 비용이 아주 적습니다.

코드는 GitHub에 있습니다. 이런 데이터베이스 위에서 에이전트를 조율하는 방법은 Kiro 리뷰를 참고하십시오.