架构概述

OpenViking 是为 AI Agent 设计的上下文数据库，将所有上下文（Memory、Resource、Skill）统一抽象为目录结构，支持语义检索和渐进式内容加载。

系统概览

文本版本

text

CLI / SDK / HTTP client
          |
      HTTP Server
          |
      Service Layer
          |
   +------+------+----------------+
   |             |                |
Retrieval     Sessions       Resource / Skill import
   |             |                |
   |       Memory extraction  Parse / Semantic queues
   |             |                |
   +-------------+----------------+
                 |
             VikingFS
           /          \
      RAGFS         Vector index

核心模块

模块	职责	关键能力
Client	统一入口	通过 HTTP API 提交 SDK/CLI 支持的操作
Service	业务逻辑	FSService、SearchService、SessionService、ResourceService、PackService、DebugService
Retrieve	上下文检索	意图分析（IntentAnalyzer）、全局检索（HierarchicalRetriever）、Rerank 精排
Session	会话管理	消息记录、使用追踪、会话归档、触发记忆提交
Parse	上下文提取	文档解析（PDF/MD/HTML）、树构建（TreeBuilder）、异步语义生成
Memory	记忆提取	按 MemoryType Schema 提取记忆（ExtractLoop），由 LLM 合并去重后以 patch 写回（MemoryUpdater）；由 `SessionCompressorV3` 编排
Storage	存储层	VikingFS 虚拟文件系统、向量索引、RAGFS 集成

Service 层

Service 层将业务逻辑与传输层解耦，CLI 和 SDK 通过 HTTP Server 访问业务能力：

Service	职责	主要方法
FSService	文件系统操作	ls, mkdir, rm, mv, tree, stat, read, abstract, overview, grep, glob
SearchService	语义搜索	search, find
SessionService	会话管理	session, sessions, commit, delete
ResourceService	资源导入	add_resource, add_skill, wait_processed
PackService	导入导出、备份恢复	export_ovpack, import_ovpack, backup_ovpack, restore_ovpack
DebugService	调试服务	observer (ObserverService)

双层存储

OpenViking 采用双层存储架构，实现内容与索引分离（详见存储架构）：

存储层	职责	内容
RAGFS	内容存储	L0/L1/L2 完整内容、多媒体文件、关联关系
向量库	索引存储	URI、向量、元数据和检索需要的文本（包括摘要）

数据流概览

添加上下文

输入 → Parser → TreeBuilder → ResourceProcessor → RAGFS → SemanticQueue → 向量库

Parser：将源文档解析为文件与目录；是否调用模型取决于所选 Parser
TreeBuilder：确定目标 URI，保留临时产物引用
ResourceProcessor：将内容写入 RAGFS，入队语义处理
SemanticQueue：异步自底向上生成 L0/L1
向量库：建立索引用于语义搜索

检索上下文

查询 → 意图分析 → 全局检索 → Rerank → 结果

意图分析：分析查询意图，生成 0-5 个类型化查询
全局检索：每条查询在权限范围内执行一次向量搜索
Rerank：可选，对召回候选统一精排一次
结果：返回按相关性排序的上下文

会话提交

消息 → 归档边界 → 归档 → 记忆提取 → 存储

消息：累积对话消息和使用记录
归档边界：按提交参数划分归档消息和保留消息；默认归档全部当前消息
归档：生成历史片段的 L0/L1
记忆提取：根据记忆策略和 MemoryType Schema 从消息中提取记忆
存储：写入 RAGFS + 向量库

部署模式

HTTP 模式

用于团队共享、生产环境和跨语言集成：

python

# Python SDK 连接 OpenViking Server
from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")

bash

# 或使用 curl / 任意 HTTP 客户端
curl http://localhost:1933/api/v1/search/find \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "how to use openviking"}'

Server 作为独立进程运行（openviking-server）
客户端通过 HTTP API 连接
支持任何能发起 HTTP 请求的语言
参见服务部署了解配置方法

设计原则

原则	说明
存储层纯粹	存储层只做 RAGFS 操作和基础向量搜索，Rerank 在检索层完成
三层信息	L0/L1/L2 实现渐进式详情加载，节省 Token 消耗
两阶段检索	向量搜索召回候选 + Rerank 精排提高准确性
单一数据源	RAGFS 保存源文件，向量记录保留检索需要的文本与元数据

架构概述 ​

系统概览 ​

核心模块 ​

Service 层 ​

双层存储 ​

数据流概览 ​

添加上下文 ​

检索上下文 ​

会话提交 ​

部署模式 ​

HTTP 模式 ​

设计原则 ​

相关文档 ​