OpenViking 存储架构详解VikingFS 抽象层、AGFS/RAGFS 内容存储与向量索引双层设计【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 的存储子系统采用“内容存储与索引存储分离”的双层架构上层 VikingFS 提供统一的 URI 虚拟文件系统抽象下层由 AGFSRust 重写后的 RAGFS负责 L0/L1/L2 全量内容与多媒体的持久化向量索引则只保存 URI、向量与元数据。读懂这套架构你就能理解 OpenViking 中一次rm/mv文件操作如何自动同步向量库记录、多写模式下主备后端如何通过隐藏文件跟踪同步进度以及上下文目录为何统一呈现.abstract.md/.overview.md/ 明细文件 的三层结构。双层存储总体架构OpenViking 的存储架构可以用下图概括┌─────────────────────────────────────────┐ │ VikingFS (URI Abstraction) │ │ URI Mapping · Hierarchical Access │ └────────────────┬────────────────────────┘ ┌────────┴────────┐ │ │ ┌───────▼────────┐ ┌─────▼───────────┐ │ Vector Index │ │ AGFS │ │ (Semantic │ │ (Content │ │ Search) │ │ Storage) │ └────────────────┘ └─────────────────┘两层存储的职责划分如下层职责存放内容AGFS内容存储L0/L1/L2 全量内容、多媒体文件Vector Index索引存储URI、向量、元数据不存文件内容这一分离设计带来四个直接收益职责清晰向量索引负责检索RetrievalAGFS 负责存储Storage内存优化向量索引不保存文件内容显著降低内存占用单一数据源所有内容从 AGFS 读取向量索引只保存引用避免内容双写导致的不一致独立扩展向量索引与 AGFS 可以分别水平扩展。一个重要的演进事实是AGFS 已经重写为 Rust 实现即 RAGFS。仓库中crates/ragfs/目录含 Cargo.toml 与 ORIGIN.md承载这一实现Python 侧配置模型 AGFSConfig 的 docstring 也直接标注为 “Configuration for RAGFS (Rust-based AGFS)”。VikingFS 虚拟文件系统VikingFS 是统一 URI 抽象层它屏蔽底层存储细节让上层Python SDK、HTTP API、CLI 文件系统接口始终面对同一套viking://寻址语义。URI 的完整规范scope、~家目录别名、路径变量等见 Viking URI。URI 映射VikingFS 将逻辑 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其中{account_id}与{user_id}由服务端根据请求认证身份填充viking://~展开为当前调用者的用户根目录因此同一字符串对不同调用者指向不同物理目录。核心 APIVikingFS 对外暴露的最小操作集合方法说明read(uri)读取文件内容write(uri, data)写入文件mkdir(uri)创建目录rm(uri)删除文件/目录同步删除向量记录mv(old, new)移动/重命名同步更新向量记录中的 URIabstract(uri)读取 L0 摘要overview(uri)读取 L1 概览find(query, uri)语义搜索源码中的 VikingFS 组织从源码结构看VikingFS 实现位于 openviking/storage/viking_fs/按关注点拆分为多个私有模块_ops.py文件操作、_semantic.py语义搜索、_sync.py向量同步、_vector.py向量记录、_access.py访问控制、_grep.py文本检索、_snapshot.py快照等。VikingFS 以单例方式初始化入口函数init_viking_fs的签名openviking/storage/viking_fs/_base.py清晰展示了它与下层两个子系统的依赖关系def init_viking_fs( agfs: Any, # 预初始化的 AGFS/RAGFS 客户端 query_embedder: Optional[Any] None, # 查询向量化器 rerank_config: Optional[RerankConfig] None, vector_store: Optional[VikingVectorIndexBackend] None, # 向量索引后端 acl_manager: Optional[AclManager] None, retrieval_config: Optional[RetrievalConfig] None, grep_config: Optional[GrepConfig] None, timeout: int 10, enable_recorder: bool False, encryptor: Optional[Any] None, ): ...可以看到 VikingFS 的构造直接注入agfs内容侧与vector_store索引侧两个依赖这正是“双层存储”在代码层面最直接的体现。AGFS 后端存储AGFS 提供 POSIX 风格的文件操作并支持多种后端。当前配置模型见 openviking_cli/utils/config/agfs_config.py。单后端与多写模式默认情况下 AGFS 使用单一后端存储内容。一旦配置了storage.agfs.backupsOpenViking 即进入多写模式顶层storage.agfs.backend是主后端始终是权威的写入目标storage.agfs.backups.items[]定义备份后端用于副本、迁移或读加速Python SDK、HTTP API、CLI 文件系统接口在多写模式下保持不变多写内部通过.redirect.json与.sync_log.json两个隐藏文件跟踪重定向映射和同步进度这些文件对用户不可见。配置模型中与此相关的字段openviking_cli/utils/config/agfs_config.pybackups: Optional[dict[str, Any]] Field( defaultNone, descriptionMulti-write backups configuration. None single backend mode. ) redirects: Optional[List[dict[str, Any]]] Field( defaultNone, descriptionPrimary redirect policies. )并带有一条一致性校验redirects只有在配置了backups时才允许存在——单后端模式不支持重定向策略源码中的校验信息为 “redirects requires backups; single-backend mode does not support redirects”。多写的完整概念模型主/备角色、路由、一致性见 Multi-Write Storage实操示例见 Multi-Write Storage Guide。后端类型文档层面给出的后端一览后端说明关键配置localfs本地文件系统paths3fsS3 兼容存储bucket、endpointmemory内存存储测试用-从当前源码看RAGFS 迁移后AGFSConfig.backend的取值被校验为local | s3 | memoryopenviking_cli/utils/config/agfs_config.py即文档表格中的localfs/s3fs命名在配置项层面演化为local/s3。选择s3后端时配置会被展开到S3Config子模型openviking_cli/utils/config/agfs_config.py其核心字段包括字段默认值说明bucket-S3 桶名必填region-区域如us-east-1、cn-beijing必填access_key/secret_key-访问密钥未提供时 RAGFS 可尝试环境变量或 IAM 角色必填校验endpoint-自定义 S3 端点MinIO/LocalStack 等 S3 兼容服务必填标准 AWS S3 留空必填校验prefix键前缀用于命名空间隔离use_sslTrue是否启用 HTTPSuse_path_styleTrueMinIO 等用 path-styleTOS 等部分服务用 virtual-host-styledirectory_marker_modeemptyS3 目录标记持久化方式none/empty零字节标记/nonemptydisable_batch_deleteFalse禁用 DeleteObjects 批量删除某些 S3 兼容服务要求 DeleteObjects 携带 Content-MD5需要置为Truenormalize_encoding_chars?#%对象键中需转义为!HH十六进制的字符置空可关闭键归一化auto_detect_content_typeFalse上传时按扩展名推断 Content-Type默认关闭以保持向后兼容此外AGFSConfig还内嵌了三组与文件系统运行相关的子配置queuefs任务队列默认sqlite后端、cachefs读缓存默认 local、单文件缓存上限 1MB、pathlock原生路径锁锁过期时间默认 30 秒分别对应内容写入队列、读加速与并发路径互斥。AGFSConfig采用extraforbid严格模式port、url、mode、impl、lib_path等旧版 AGFS 字段被标记为废弃并直接忽略仅打警告这体现了向 RAGFS 迁移过程中的兼容性策略。上下文目录的统一结构每个上下文目录遵循统一的三层文件结构viking://resources/docs/auth/ ├── .abstract.md # L0 abstract ├── .overview.md # L1 overview └── *.md # L2 detailed content.abstract.md是 L0 摘要约 100 token对应 VikingFS API 中的abstract(uri).overview.md是 L1 概览约 2k token对应overview(uri)明细文件L2才是完整内容。这一约定让 L0/L1/L2 上下文分层见 Context Layers在物理存储层面有了确定性的落盘位置而不只是检索时的逻辑概念。向量索引向量索引存放语义索引支持向量搜索与标量过滤本身不保存文件内容。上下文集合 Schema字段类型说明idstring主键uristring资源 URIparent_uristring父目录 URIcontext_typestringresource/memory/skillis_leafbool是否叶子节点vectorvector稠密向量sparse_vectorsparse_vector稀疏向量abstractstringL0 摘要文本namestring名称descriptionstring描述created_atstring创建时间active_countint64使用次数其中id是确定性主键对 L2普通文件记录id md5(f{account_id}:{uri})由stat()等元数据接口返回调用方无需额外查找即可在向量记录与文件之间交叉引用文件移动 URI 后向量记录会随 URI 迁移重新定键。索引策略index_meta { IndexType: flat_hybrid, # Hybrid index稠密稀疏混合 Distance: cosine, # 余弦距离 Quant: int8, # 向量量化 }flat_hybrid意味着同时维护稠密向量与稀疏向量索引配合 int8 量化在精度与内存之间取平衡。后端支持后端说明local本地持久化httpHTTP 远程服务volcengine火山引擎 VikingDB从源码结构看三类后端分别对应 openviking/storage/vectordb/collection/ 下的 local_collection.py、http_collection.py、volcengine_collection.py另有vikingdb_collection.py封装 VikingDB 客户端索引层位于 openviking/storage/vectordb/index/除通用index.py外还包含local_index.py与cuvs_index.pycuVS GPU 索引实验。集合 Schema 与一致性工具集中在 collection_schemas.py 和 index_consistency.py向量索引后端的顶层抽象是 viking_vector_index_backend.py 与 vikingdb_manager.py。向量同步机制VikingFS 自动维护向量索引与 AGFS 之间的一致性使“文件系统操作”与“索引状态”永远同进退。删除同步viking_fs.rm(viking://resources/docs/auth, recursiveTrue) # 自动从向量索引中删除所有该 URI 前缀的记录删除文件/目录时VikingFS 会按 URI 前缀批量清除向量索引中对应的全部记录避免检索结果中出现指向已删内容的“幽灵引用”。移动同步viking_fs.mv( viking://resources/docs/auth, viking://resources/docs/authentication ) # 自动更新向量索引中的 uri 与 parent_uri 字段重命名/移动目录时向量记录不会“删除后重建”而是原子地更新uri与parent_uri两个字段保证层级关系父目录指针在移动后依然正确。实现上这一同步逻辑从源码结构看落在 openviking/storage/viking_fs/_sync.py 模块中与_ops.py的文件操作、_vector.py的向量记录读写配合完成。小结与延伸阅读OpenViking 的存储架构核心在于三点VikingFS 作为唯一入口统一了 URI 语义与文件操作AGFS/RAGFS 以纯内容层的身份承担 L0/L1/L2 与多媒体落盘并可通过backups进入多写模式向量索引只保存 URI、向量与元数据靠rm/mv的同步钩子与内容层保持一致。围绕这套架构可继续深入以下文档Architecture Overview — 系统整体架构Context Layers — L0/L1/L2 上下文模型Viking URI — URI 规范、scope 与路径变量Multi-Write Storage — 主/备角色、路由与一致性Retrieval Mechanism — 检索流程细节【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking 存储架构详解：VikingFS 抽象层、AGFS/RAGFS 内容存储与向量索引双层设计
OpenViking 存储架构详解VikingFS 抽象层、AGFS/RAGFS 内容存储与向量索引双层设计【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 的存储子系统采用“内容存储与索引存储分离”的双层架构上层 VikingFS 提供统一的 URI 虚拟文件系统抽象下层由 AGFSRust 重写后的 RAGFS负责 L0/L1/L2 全量内容与多媒体的持久化向量索引则只保存 URI、向量与元数据。读懂这套架构你就能理解 OpenViking 中一次rm/mv文件操作如何自动同步向量库记录、多写模式下主备后端如何通过隐藏文件跟踪同步进度以及上下文目录为何统一呈现.abstract.md/.overview.md/ 明细文件 的三层结构。双层存储总体架构OpenViking 的存储架构可以用下图概括┌─────────────────────────────────────────┐ │ VikingFS (URI Abstraction) │ │ URI Mapping · Hierarchical Access │ └────────────────┬────────────────────────┘ ┌────────┴────────┐ │ │ ┌───────▼────────┐ ┌─────▼───────────┐ │ Vector Index │ │ AGFS │ │ (Semantic │ │ (Content │ │ Search) │ │ Storage) │ └────────────────┘ └─────────────────┘两层存储的职责划分如下层职责存放内容AGFS内容存储L0/L1/L2 全量内容、多媒体文件Vector Index索引存储URI、向量、元数据不存文件内容这一分离设计带来四个直接收益职责清晰向量索引负责检索RetrievalAGFS 负责存储Storage内存优化向量索引不保存文件内容显著降低内存占用单一数据源所有内容从 AGFS 读取向量索引只保存引用避免内容双写导致的不一致独立扩展向量索引与 AGFS 可以分别水平扩展。一个重要的演进事实是AGFS 已经重写为 Rust 实现即 RAGFS。仓库中crates/ragfs/目录含 Cargo.toml 与 ORIGIN.md承载这一实现Python 侧配置模型 AGFSConfig 的 docstring 也直接标注为 “Configuration for RAGFS (Rust-based AGFS)”。VikingFS 虚拟文件系统VikingFS 是统一 URI 抽象层它屏蔽底层存储细节让上层Python SDK、HTTP API、CLI 文件系统接口始终面对同一套viking://寻址语义。URI 的完整规范scope、~家目录别名、路径变量等见 Viking URI。URI 映射VikingFS 将逻辑 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其中{account_id}与{user_id}由服务端根据请求认证身份填充viking://~展开为当前调用者的用户根目录因此同一字符串对不同调用者指向不同物理目录。核心 APIVikingFS 对外暴露的最小操作集合方法说明read(uri)读取文件内容write(uri, data)写入文件mkdir(uri)创建目录rm(uri)删除文件/目录同步删除向量记录mv(old, new)移动/重命名同步更新向量记录中的 URIabstract(uri)读取 L0 摘要overview(uri)读取 L1 概览find(query, uri)语义搜索源码中的 VikingFS 组织从源码结构看VikingFS 实现位于 openviking/storage/viking_fs/按关注点拆分为多个私有模块_ops.py文件操作、_semantic.py语义搜索、_sync.py向量同步、_vector.py向量记录、_access.py访问控制、_grep.py文本检索、_snapshot.py快照等。VikingFS 以单例方式初始化入口函数init_viking_fs的签名openviking/storage/viking_fs/_base.py清晰展示了它与下层两个子系统的依赖关系def init_viking_fs( agfs: Any, # 预初始化的 AGFS/RAGFS 客户端 query_embedder: Optional[Any] None, # 查询向量化器 rerank_config: Optional[RerankConfig] None, vector_store: Optional[VikingVectorIndexBackend] None, # 向量索引后端 acl_manager: Optional[AclManager] None, retrieval_config: Optional[RetrievalConfig] None, grep_config: Optional[GrepConfig] None, timeout: int 10, enable_recorder: bool False, encryptor: Optional[Any] None, ): ...可以看到 VikingFS 的构造直接注入agfs内容侧与vector_store索引侧两个依赖这正是“双层存储”在代码层面最直接的体现。AGFS 后端存储AGFS 提供 POSIX 风格的文件操作并支持多种后端。当前配置模型见 openviking_cli/utils/config/agfs_config.py。单后端与多写模式默认情况下 AGFS 使用单一后端存储内容。一旦配置了storage.agfs.backupsOpenViking 即进入多写模式顶层storage.agfs.backend是主后端始终是权威的写入目标storage.agfs.backups.items[]定义备份后端用于副本、迁移或读加速Python SDK、HTTP API、CLI 文件系统接口在多写模式下保持不变多写内部通过.redirect.json与.sync_log.json两个隐藏文件跟踪重定向映射和同步进度这些文件对用户不可见。配置模型中与此相关的字段openviking_cli/utils/config/agfs_config.pybackups: Optional[dict[str, Any]] Field( defaultNone, descriptionMulti-write backups configuration. None single backend mode. ) redirects: Optional[List[dict[str, Any]]] Field( defaultNone, descriptionPrimary redirect policies. )并带有一条一致性校验redirects只有在配置了backups时才允许存在——单后端模式不支持重定向策略源码中的校验信息为 “redirects requires backups; single-backend mode does not support redirects”。多写的完整概念模型主/备角色、路由、一致性见 Multi-Write Storage实操示例见 Multi-Write Storage Guide。后端类型文档层面给出的后端一览后端说明关键配置localfs本地文件系统paths3fsS3 兼容存储bucket、endpointmemory内存存储测试用-从当前源码看RAGFS 迁移后AGFSConfig.backend的取值被校验为local | s3 | memoryopenviking_cli/utils/config/agfs_config.py即文档表格中的localfs/s3fs命名在配置项层面演化为local/s3。选择s3后端时配置会被展开到S3Config子模型openviking_cli/utils/config/agfs_config.py其核心字段包括字段默认值说明bucket-S3 桶名必填region-区域如us-east-1、cn-beijing必填access_key/secret_key-访问密钥未提供时 RAGFS 可尝试环境变量或 IAM 角色必填校验endpoint-自定义 S3 端点MinIO/LocalStack 等 S3 兼容服务必填标准 AWS S3 留空必填校验prefix键前缀用于命名空间隔离use_sslTrue是否启用 HTTPSuse_path_styleTrueMinIO 等用 path-styleTOS 等部分服务用 virtual-host-styledirectory_marker_modeemptyS3 目录标记持久化方式none/empty零字节标记/nonemptydisable_batch_deleteFalse禁用 DeleteObjects 批量删除某些 S3 兼容服务要求 DeleteObjects 携带 Content-MD5需要置为Truenormalize_encoding_chars?#%对象键中需转义为!HH十六进制的字符置空可关闭键归一化auto_detect_content_typeFalse上传时按扩展名推断 Content-Type默认关闭以保持向后兼容此外AGFSConfig还内嵌了三组与文件系统运行相关的子配置queuefs任务队列默认sqlite后端、cachefs读缓存默认 local、单文件缓存上限 1MB、pathlock原生路径锁锁过期时间默认 30 秒分别对应内容写入队列、读加速与并发路径互斥。AGFSConfig采用extraforbid严格模式port、url、mode、impl、lib_path等旧版 AGFS 字段被标记为废弃并直接忽略仅打警告这体现了向 RAGFS 迁移过程中的兼容性策略。上下文目录的统一结构每个上下文目录遵循统一的三层文件结构viking://resources/docs/auth/ ├── .abstract.md # L0 abstract ├── .overview.md # L1 overview └── *.md # L2 detailed content.abstract.md是 L0 摘要约 100 token对应 VikingFS API 中的abstract(uri).overview.md是 L1 概览约 2k token对应overview(uri)明细文件L2才是完整内容。这一约定让 L0/L1/L2 上下文分层见 Context Layers在物理存储层面有了确定性的落盘位置而不只是检索时的逻辑概念。向量索引向量索引存放语义索引支持向量搜索与标量过滤本身不保存文件内容。上下文集合 Schema字段类型说明idstring主键uristring资源 URIparent_uristring父目录 URIcontext_typestringresource/memory/skillis_leafbool是否叶子节点vectorvector稠密向量sparse_vectorsparse_vector稀疏向量abstractstringL0 摘要文本namestring名称descriptionstring描述created_atstring创建时间active_countint64使用次数其中id是确定性主键对 L2普通文件记录id md5(f{account_id}:{uri})由stat()等元数据接口返回调用方无需额外查找即可在向量记录与文件之间交叉引用文件移动 URI 后向量记录会随 URI 迁移重新定键。索引策略index_meta { IndexType: flat_hybrid, # Hybrid index稠密稀疏混合 Distance: cosine, # 余弦距离 Quant: int8, # 向量量化 }flat_hybrid意味着同时维护稠密向量与稀疏向量索引配合 int8 量化在精度与内存之间取平衡。后端支持后端说明local本地持久化httpHTTP 远程服务volcengine火山引擎 VikingDB从源码结构看三类后端分别对应 openviking/storage/vectordb/collection/ 下的 local_collection.py、http_collection.py、volcengine_collection.py另有vikingdb_collection.py封装 VikingDB 客户端索引层位于 openviking/storage/vectordb/index/除通用index.py外还包含local_index.py与cuvs_index.pycuVS GPU 索引实验。集合 Schema 与一致性工具集中在 collection_schemas.py 和 index_consistency.py向量索引后端的顶层抽象是 viking_vector_index_backend.py 与 vikingdb_manager.py。向量同步机制VikingFS 自动维护向量索引与 AGFS 之间的一致性使“文件系统操作”与“索引状态”永远同进退。删除同步viking_fs.rm(viking://resources/docs/auth, recursiveTrue) # 自动从向量索引中删除所有该 URI 前缀的记录删除文件/目录时VikingFS 会按 URI 前缀批量清除向量索引中对应的全部记录避免检索结果中出现指向已删内容的“幽灵引用”。移动同步viking_fs.mv( viking://resources/docs/auth, viking://resources/docs/authentication ) # 自动更新向量索引中的 uri 与 parent_uri 字段重命名/移动目录时向量记录不会“删除后重建”而是原子地更新uri与parent_uri两个字段保证层级关系父目录指针在移动后依然正确。实现上这一同步逻辑从源码结构看落在 openviking/storage/viking_fs/_sync.py 模块中与_ops.py的文件操作、_vector.py的向量记录读写配合完成。小结与延伸阅读OpenViking 的存储架构核心在于三点VikingFS 作为唯一入口统一了 URI 语义与文件操作AGFS/RAGFS 以纯内容层的身份承担 L0/L1/L2 与多媒体落盘并可通过backups进入多写模式向量索引只保存 URI、向量与元数据靠rm/mv的同步钩子与内容层保持一致。围绕这套架构可继续深入以下文档Architecture Overview — 系统整体架构Context Layers — L0/L1/L2 上下文模型Viking URI — URI 规范、scope 与路径变量Multi-Write Storage — 主/备角色、路由与一致性Retrieval Mechanism — 检索流程细节【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考