存储架构

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

概览

┌─────────────────────────────────────────┐
│            VikingFS (URI 抽象层)         │
│            URI 映射 · 层级访问           │
└────────────────┬────────────────────────┘
        ┌────────┴────────┐
        │                 │
┌───────▼────────┐  ┌─────▼───────────┐
│   向量库索引    │  │      AGFS       │
│   (语义搜索)    │  │   (内容存储)    │
└────────────────┘  └─────────────────┘

双层存储

存储层	职责	存储内容
AGFS	内容存储	L0/L1/L2 完整内容、多媒体文件
向量库	索引存储	URI、向量、元数据（不存文件内容）

设计优势

职责清晰：向量库只负责检索，AGFS 负责存储
内存优化：向量库不存储文件内容，节省内存
单一数据源：所有内容从 AGFS 读取，向量库只存引用
独立扩展：向量库和 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 的文件系统接口保持不变。
多写内部使用 .redirect.json 和 .sync_log.json 维护 redirect 映射与同步进度，这些文件对用户不可见。

更多概念说明见多写存储，配置示例见多写存储指南。

后端类型

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

目录结构

每个上下文目录遵循统一结构：

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

向量库索引

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

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

向量同步

VikingFS 自动维护向量库与 AGFS 的一致性。

删除同步

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

移动同步

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