OpenViking 存储架构解析VikingFS URI 抽象层、AGFS 内容存储与向量库索引的双层设计【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文基于 OpenViking 概念文档「存储架构」展开完整解析其双层存储模型VikingFSURI 抽象层如何屏蔽底层差异、AGFS 如何作为唯一内容数据源、向量库如何只存引用不存内容以及 VikingFS 如何在删除/移动时自动同步向量索引。读完本文你将理解 OpenViking 上下文数据的落盘结构、上下文集合的完整 Schema、向量库多后端接入机制以及多写模式的配置要点足以支撑你针对自己的部署场景选择合适的存储后端并保持索引与内容的一致性。概览双层存储架构OpenViking 采用双层存储架构分离内容存储和索引存储。整体结构如下┌─────────────────────────────────────────┐ │ VikingFS (URI 抽象层) │ │ URI 映射 · 层级访问 │ └────────────────┬────────────────────────┘ ┌────────┴────────┐ │ │ ┌───────▼────────┐ ┌─────▼───────────┐ │ 向量库索引 │ │ AGFS │ │ (语义搜索) │ │ (内容存储) │ └────────────────┘ └─────────────────┘上层是 VikingFS 提供的统一 URI 抽象层负责 URI 映射与层级访问下层则分为两个独立角色存储层职责存储内容AGFS内容存储L0/L1/L2 完整内容、多媒体文件向量库索引存储URI、向量、元数据不存文件内容设计优势职责清晰向量库只负责检索AGFS 负责存储内存优化向量库不存储文件内容节省内存单一数据源所有内容从 AGFS 读取向量库只存引用独立扩展向量库和 AGFS 可分别扩展注AGFS 已经重写为 Rust 实现RAGFS对应仓库中的crates/ragfscrate 及其 Python 绑定crates/ragfs-python。这一「内容与索引分离」的取舍在源码中体现得非常直接向量记录中的content字段只写入截断后的文本受VIKINGDB_CONTENT_MAX_SIZE约束见 collection_schemas.py 中TextEmbeddingHandler._materialize_content用于 VikingDB 系后端的服务端全文检索而文件的完整内容始终留在 AGFS 一侧检索命中后通过 URI 回到 AGFS 读取原文。VikingFS 虚拟文件系统VikingFS 是统一的 URI 抽象层屏蔽底层存储细节。它的实现位于 openviking/storage/viking_fs 目录按职责拆分为多个模块_base.py基础操作、_access.py访问控制、_vector.py向量同步、_semantic.py语义检索、_sync.py目录同步原语等对上层 SDK、HTTP API 和 CLI 暴露一致的文件系统接口。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可以看到 URI 映射隐含了租户隔离resources挂在账号account_id维度~/开头的个人空间则进一步按user_id隔离。完整的 URI 规范见 Viking URI。核心 API方法说明read(uri)读取文件内容write(uri, data)写入文件mkdir(uri)创建目录rm(uri)删除文件/目录同步删除向量mv(old, new)移动/重命名同步更新向量 URIabstract(uri)读取 L0 摘要overview(uri)读取 L1 概览find(query, uri)语义搜索其中abstract和overview对应上下文层级的 L0/L1 两层详见 上下文层级find则是走向量库的语义搜索入口。AGFS 底层存储AGFS 提供 POSIX 风格的文件操作支持多种后端。Python 侧的客户端接口封装在 openviking/pyagfs包含async_client.py、protocols.py等模块。单后端与多写模式默认情况下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本地文件系统paths3fsS3 兼容存储bucket,endpointmemory内存存储测试用-目录结构每个上下文目录遵循统一结构viking://resources/docs/auth/ ├── .abstract.md # L0 摘要 ├── .overview.md # L1 概览 └── *.md # L2 详细内容L0/L1/L2 的命名规则与向量集合中的level字段一一对应level0对应{目录}/.abstract.mdlevel1对应{目录}/.overview.mdlevel2默认对应实际文件路径。这一约定直接写在集合 Schema 的字段注释中见 collection_schemas.py 的CollectionSchemas.context_collection。向量库索引向量库存储语义索引支持向量搜索和标量过滤。Context 集合 Schema概念文档给出的核心字段如下字段类型说明idstring主键uristring资源 URIparent_uristring父目录 URIcontext_typestringresource/memory/skillis_leafbool是否叶子节点vectorvector密集向量sparse_vectorsparse_vector稀疏向量abstractstringL0 摘要文本namestring名称descriptionstring描述created_atstring创建时间active_countint64使用次数对照当前仓库的实现collection_schemas.py 中context_collection的 Schema 在上述基础上还有几处值得注意的细节字段类型uri的FieldType是path而非普通 stringvector字段声明了Dim由config.embedding.dimension决定context_type的推导规则源码注释URI 位于 user skills 目录下 →skillURI 包含memories→memory其他情况 →resource额外的标量字段levelL0/L1/L2 层级、tags、search_tagsliststring、contenttext 类型、account_id、owner_user_id以及一组 ACL 相关字段acl_mode及 grant 字段ScalarIndexuri、type、context_type、created_at、updated_at、active_count、level、name、tags、search_tags、account_id、owner_user_id及 ACL 字段均建有标量索引保证「向量召回 标量过滤」的复合查询可以下推到向量库执行FullTextcontent字段配置了全文索引standard分词器过滤 symbol 停用词。collection_schemas.py 中init_context_collection还有一段兼容逻辑若既有集合缺少content/FullText 配置只会在grep engineauto时回退到文件系统 grep而不是阻止服务启动。此外集合创建时还会把当前嵌入模型的元数据provider/model/dimension/model_identity编码进集合描述中。后续启动时若发现元数据与当前配置不一致会抛出EmbeddingRebuildRequiredError要求重建若仅 provider/model 变化而维度不变可通过embedding.allow_metadata_overridetrue显式保留既有向量。索引策略index_meta { IndexType: flat_hybrid, # 混合索引 Distance: cosine, # 余弦距离 Quant: int8, # 量化方式 }从源码看IndexType 的实际取值只有两种见 validation.pyflat仅密集向量的 flat 索引flat_hybrid密集 稀疏混合索引。在 vectordb_adapters/base.py 中可以看到默认策略index_type flat_hybrid if use_sparse else flat即是否启用混合索引取决于稀疏向量sparse embedding是否开启。后端支持后端说明local本地持久化httpHTTP 远程服务volcengine火山引擎 VikingDB当前仓库的适配层位于 openviking/storage/vectordb_adaptersfactory.py 中的注册表实际包含五个内置后端_ADAPTER_REGISTRY: dict[str, type[CollectionAdapter]] { local: LocalCollectionAdapter, cuvs: CuVSCollectionAdapter, http: HttpCollectionAdapter, volcengine: VolcengineCollectionAdapter, vikingdb: VikingDBPrivateCollectionAdapter, }即除了文档列出的三个还支持cuvs本地 GPU 索引与vikingdb私有化部署。create_collection_adapter(config)按config.backend路由若 backend 值包含.则按完整类路径动态加载第三方 Adapter并可通过custom_params传递自定义参数。完整的接入步骤新增 Adapter 类、实现from_config/_load_existing_collection_if_needed/_create_backend_collection、注册到 factory、补充配置见 vectordb_adapters/README.md。两点实现细节懒加载集合各 Adapter 通过_load_existing_collection_if_needed懒加载已存在的 collection handle不存在时保持为空后续按需创建content 字段策略Adapter 基类的USE_CONTENT_FIELD类属性默认为False仅 VikingDB 系后端开启写入时其他后端会自动跳过content字段避免无谓的全文存储开销。向量同步VikingFS 自动维护向量库与 AGFS 的一致性相关逻辑收敛在openviking/storage/viking_fs/_vector.py向量读写同步与_sync.py目录级 diff 与 mv/rm 合并原语中。删除同步viking_fs.rm(viking://resources/docs/auth, recursiveTrue) # 自动递归删除向量库中所有 uri 以此开头的记录即删除 AGFS 侧目录时向量库中所有uri以该路径为前缀的记录会被一并清理不会出现「幽灵向量」指向已删除内容的问题。移动同步viking_fs.mv( viking://resources/docs/auth, viking://resources/docs/authentication ) # 自动更新向量库中的 uri 和 parent_uri 字段mv在重命名目录后会自动把受影响向量记录的uri与parent_uri字段更新为新路径保证向量库中的引用链与 AGFS 目录树始终对应。从_sync.py的实现可以看到目录级同步sync_tree采用「自上而下的递归 diff 移动合并」策略对可见子节点做增/删/改对比.开头的隐藏文件被跳过parser 副产物如.image_mappings.json由调用方显式携带并通过SyncDiff结构返回目标侧的变更清单供增量重建索引的管线消费。总结与延伸阅读回到双层架构的四个核心收益向量库只管检索、内容统一从 AGFS 读取、引用与原文一一对应、两层可独立扩展。理解这套架构后再结合以下几个文档可以补全全貌架构概述 - 系统整体架构上下文层级 - L0/L1/L2 模型Viking URI - URI 规范多写存储 - primary/backup、多写路由与一致性检索机制 - 检索流程详解【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考