SurrealDB는 AI 시스템을 위해 특별히 설계된 통합 멀티모델 데이터베이스입니다. 구조화된 데이터와 비구조화된 데이터(vector search, graph traversal, relational query, full-text search, document storage, time-series data 포함)를 단일 ACID 호환 엔진으로 결합하여, 3MB 엣지 바이너리부터 클라우드의 페타바이트 규모 클러스터까지 확장할 수 있습니다. 여러 전문 스토어의 필요성을 제거함으로써 SurrealDB는 아키텍처를 단순화하고, 지연 시간을 줄이며, AI 워크로드의 일관성을 보장합니다. GenAI 시스템에서 SurrealDB가 중요한 이유
  • 스토리지와 메모리를 위한 하나의 엔진: 영구 스토리지와 빠른 에이전트 친화적 메모리를 단일 시스템으로 결합하여, 에이전트가 필요로 하는 모든 데이터를 제공하고 여러 시스템을 동기화할 필요를 제거합니다.
  • 에이전트를 위한 원홉 메모리: vector search, graph traversal, semantic join, transactional write를 단일 쿼리로 실행하여, relational, graph, vector 데이터베이스를 연결하지 않고도 LLM 에이전트에게 빠르고 일관된 메모리 액세스를 제공합니다.
  • 인플레이스 추론 및 실시간 업데이트: SurrealDB는 에이전트가 데이터 옆에서 추론을 실행하고 밀리초 단위의 최신 업데이트를 받을 수 있게 하여, 실시간 추론과 협업에 중요합니다.
  • 버전 관리되는 영구 컨텍스트: SurrealDB는 time-travel 쿼리와 버전 관리된 레코드를 지원하여, 에이전트가 일관되고 설명 가능한 추론을 위해 과거 상태를 감사하거나 “재생”할 수 있게 합니다.
  • 플러그 앤 플레이 에이전트 메모리: AI 메모리를 네이티브 개념으로 노출하여, SurrealDB를 AI 프레임워크의 드롭인 백엔드로 쉽게 사용할 수 있게 합니다.
이 노트북은 SurrealDB vector store를 시작하는 방법을 다룹니다.

​
Setup

SurrealDB를 로컬에서 실행하거나 무료 SurrealDB 클라우드 계정으로 시작할 수 있습니다. 로컬의 경우 두 가지 옵션이 있습니다:
  1. SurrealDB 설치 및 SurrealDB 실행. 인메모리로 실행: 
    surreal start -u root -p root
  2. Docker로 실행. 
    docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start

​
Install dependencies

langchain-surrealdb와 surrealdb python 패키지를 설치합니다. 
# -- Using pip
pip install -U langchain-surrealdb surrealdb
# -- Using poetry
poetry add langchain-surrealdb surrealdb
# -- Using uv
uv add langchain-surrealdb surrealdb
이 노트북을 실행하려면 이 예제에 필요한 추가 종속성을 설치하기만 하면 됩니다: 
!poetry add --quiet --group docs langchain-ollama langchain-surrealdb

​
Initialization

from langchain_ollama import OllamaEmbeddings
from langchain_surrealdb.vectorstores import SurrealDBVectorStore
from surrealdb import Surreal

conn = Surreal("ws://localhost:8000/rpc")
conn.signin({"username": "root", "password": "root"})
conn.use("langchain", "demo")
vector_store = SurrealDBVectorStore(OllamaEmbeddings(model="llama3.2"), conn)

​
Manage vector store

​
Add items to vector store

from langchain_core.documents import Document

_url = "https://surrealdb.com"
d1 = Document(page_content="foo", metadata={"source": _url})
d2 = Document(page_content="SurrealDB", metadata={"source": _url})
d3 = Document(page_content="bar", metadata={"source": _url})
d4 = Document(page_content="this is surreal", metadata={"source": _url})

vector_store.add_documents(documents=[d1, d2, d3, d4], ids=["1", "2", "3", "4"])

['1', '2', '3', '4']

​
Update items in vector store

updated_document = Document(
    page_content="zar", metadata={"source": "https://example.com"}
)

vector_store.add_documents(documents=[updated_document], ids=["3"])

['3']

​
Delete items from vector store

vector_store.delete(ids=["3"])

​
Query vector store

vector store가 생성되고 관련 문서가 추가되면, chain이나 agent를 실행하는 동안 쿼리하고 싶을 것입니다.

​
Query directly

간단한 유사도 검색은 다음과 같이 수행할 수 있습니다: 
results = vector_store.similarity_search(
    query="surreal", k=1, custom_filter={"source": "https://surrealdb.com"}
)
for doc in results:
    print(f"{doc.page_content} [{doc.metadata}]")

this is surreal [{'source': 'https://surrealdb.com'}]
유사도 검색을 실행하고 해당 점수를 받으려면 다음을 실행할 수 있습니다: 
results = vector_store.similarity_search_with_score(
    query="thud", k=1, custom_filter={"source": "https://surrealdb.com"}
)
for doc, score in results:
    print(f"[similarity={score:.0%}] {doc.page_content}")

[similarity=57%] this is surreal

​
Query by turning into retriever

vector store를 retriever로 변환하여 chain에서 더 쉽게 사용할 수도 있습니다. 
retriever = vector_store.as_retriever(
    search_type="mmr", search_kwargs={"k": 1, "lambda_mult": 0.5}
)
retriever.invoke("surreal")

[Document(id='4', metadata={'source': 'https://surrealdb.com'}, page_content='this is surreal')]

​
Usage for retrieval-augmented generation

retrieval-augmented generation (RAG)을 위해 이 vector store를 사용하는 방법에 대한 가이드는 다음 섹션을 참조하세요:

​
API reference

모든 SurrealDBVectorStore 기능 및 구성에 대한 자세한 문서는 API reference를 참조하세요: python.langchain.com/api_reference/surrealdb/index.html

​
Next steps

Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I