Skip to main content
SurrealDB 是一个专为 AI 系统构建的统一多模型数据库。它将结构化和非结构化数据（包括向量搜索、图遍历、关系查询、全文搜索、文档存储和时间序列数据）整合到单一符合 ACID 的引擎中，可从 3 MB 的边缘二进制文件扩展至云端 PB 级集群。通过消除对多个专用存储的需求，SurrealDB 简化了架构，降低了延迟，并确保 AI 工作负载的一致性。 SurrealDB 对 GenAI 系统的价值
  • 存储与记忆合二为一： 在单一系统中结合持久存储和快速的 Agent 友好型内存，为 Agent 提供所需的所有数据，无需同步多个系统。
  • Agent 的单跳记忆： 在单个查询中执行向量搜索、图遍历、语义连接和事务写入，为 LLM Agent 提供快速、一致的内存访问，无需拼接关系型、图形和向量数据库。
  • 就地推理与实时更新： SurrealDB 使 Agent 能够在数据旁边运行推理并接收毫秒级的实时更新，这对于实时推理和协作至关重要。
  • 版本化的持久上下文： SurrealDB 支持时间旅行查询和版本化记录，让 Agent 能够审计或“回放”过去的状态，实现一致且可解释的推理。
  • 即插即用的 Agent 记忆： 将 AI 记忆作为原生概念暴露，使 SurrealDB 可轻松作为 AI 框架的后端替代品。
本笔记本介绍如何开始使用 SurrealDB 向量存储。

​
设置

你可以在本地运行 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

​
安装依赖

安装 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

​
初始化

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)

​
管理向量存储

​
向向量存储添加项目

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']

​
更新向量存储中的项目

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

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

['3']

​
从向量存储删除项目

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

​
查询向量存储

向量存储创建完成并添加相关文档后，你通常会在运行链或 Agent 时对其进行查询。

​
直接查询

执行简单的相似度搜索方法如下： 
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

​
转换为检索器进行查询

你也可以将向量存储转换为检索器，以便在链中更方便地使用。 
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')]

​
用于检索增强生成

有关如何将此向量存储用于检索增强生成（RAG）的指南，请参阅以下章节：

​
API 参考

有关 SurrealDBVectorStore 所有功能和配置的详细文档，请参阅 API 参考：python.langchain.com/api_reference/surrealdb/index.html

​
后续步骤

Edit this page on GitHub or file an issue.
通过 MCP 将这些文档连接到 Claude、VSCode 等工具，获取实时解答。