Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

5.4 KB
Raw Blame

存储架构

OpenViking 采用双层存储架构,分离内容存储和索引存储。

概览

双层存储

存储层 职责 存储内容
AGFS 内容存储 L0/L1/L2 完整内容、多媒体文件
向量库 索引存储 URI、向量、元数据和摘要等检索文本

设计优势

AGFS 保存源文件,向量库存储检索需要的 URI 引用、向量、元数据和摘要。记忆记录会把正文保存在向量记录的 abstract 字段(上限 50,000 字节),因此向量库中也可能包含可读文本。

两类后端可以分别配置。文件 API 从 AGFS 读取内容,检索则可直接返回索引中的文本,无需逐个回读源文件。备份和访问控制需要覆盖两类存储。

注:AGFS 已经重写为 Rust 实现(RAGFS)

VikingFS 虚拟文件系统

VikingFS 是统一的 URI 抽象层,屏蔽底层存储细节。

URI 映射

viking://resources/docs/auth  →  /local/{account_id}/resources/docs/auth
viking://~/memories        →  /local/{account_id}/user/{user_id}/memories
viking://~/skills          →  /local/{account_id}/user/{user_id}/skills

核心 API

方法 说明
read(uri) 读取文件内容
write(uri, data) 写入文件
mkdir(uri) 创建目录
rm(uri) 删除文件/目录(同步删除向量)
mv(old, new) 移动/重命名(同步更新向量 URI)
abstract(uri) 读取 L0 摘要
overview(uri) 读取 L1 概览
find(query, uri) 语义搜索

AGFS 底层存储

AGFS 提供 POSIX 风格的文件操作,支持多种后端。

单后端与主备模式

默认情况下,AGFS 使用一个后端作为内容存储。配置 storage.agfs.backups 后,OpenViking 会启用主备模式:

  • 顶层 storage.agfs.backend 是 primary,也是唯一直接读取来源。
  • storage.agfs.backups.items[] 是后台异步更新的 backup。
  • Python SDK、HTTP API 和 CLI 的文件系统接口保持不变。
  • V2 metadata 分区存储,并且只存储在 primary。

更多概念说明见 主备存储,配置示例见 主备存储指南。

后端类型

后端 说明 配置
localfs 本地文件系统 path
s3fs S3 兼容存储 bucket, endpoint
memory 内存存储(测试用) -

目录结构

完成语义处理的目录通常有以下结构。处理前或仅创建 L0 时,部分摘要文件可能尚不存在:

viking://resources/docs/auth/
├── .abstract.md          # L0 摘要
├── .overview.md          # L1 概览
└── *.md                  # L2 详细内容

向量库索引

向量库存储语义索引,支持向量搜索和标量过滤。

本地记录格式兼容

本地后端将非向量字段打包成 JSON。新写入的当前记录和 Delta 日志使用带 32 位字节长度的 text 保存这份 JSON,解除原先整个 JSON 合计 65,535 字节的限制,不截断内容。

新记录带有格式版本。已有的无版本记录继续可读,更新时写入新格式;本次格式升级不需要 全库重写、重建索引或重新计算 embedding。Delta 恢复也支持新旧格式混存。

兼容方向为新版读取旧数据:旧版程序无法读取新格式。需要降级时,应恢复首次写入新格式 之前的备份,不能只替换回旧版程序。

Context 集合 Schema

字段 类型 说明
id string 主键
uri string 资源 URI
parent_uri string 父目录 URI
context_type string resource/memory/skill
is_leaf bool 是否叶子节点
vector vector 密集向量
sparse_vector sparse_vector 稀疏向量
abstract string L0 摘要文本
name string 名称
description string 描述
created_at string 创建时间
active_count int64 使用次数

索引策略

以下为索引元数据示例;可用选项取决于向量后端:

index_meta = {
    "IndexType": "flat_hybrid",  # 混合索引
    "Distance": "cosine",        # 余弦距离
    "Quant": "int8",             # 量化方式
}

后端支持

后端 说明
local 本地持久化
http HTTP 远程服务
volcengine 火山引擎 VikingDB

向量同步

文件系统操作协调文件与向量记录的变更。目录摘要可能继续异步刷新,失败也可能留下部分变更;各操作的具体行为见文件系统 API。下面的示例使用已初始化的同步 Python SDK 客户端。

删除同步

client.rm("viking://resources/docs/auth", recursive=True)
# 自动递归删除向量库中所有 uri 以此开头的记录

移动同步

client.mv(
    "viking://resources/docs/auth",
    "viking://resources/docs/authentication"
)
# 自动更新向量库中的 uri 和 parent_uri 字段

相关文档