ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

OpenViking 架构深度解析:面向 AI Agent 的统一上下文数据库设计与实现

OpenViking 架构深度解析:面向 AI Agent 的统一上下文数据库设计与实现 OpenViking 架构深度解析面向 AI Agent 的统一上下文数据库设计与实现【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 将 AI Agent 的全部上下文Memory、Resource、Skill统一抽象为目录结构构建起一个支持语义检索与渐进式内容加载的上下文数据库。本文以 docs/zh/concepts/01-architecture.md 为骨架结合仓库源码剖析其分层架构、双层存储、三大数据流与部署模式帮助读者理解从「上下文写入」到「上下文检索」的完整链路并掌握 Client / Service / Retrieve / Session / Parse / Storage 各层的真实实现与调用关系。系统概览目录即上下文OpenViking 的核心设计理念是将 Agent 的所有上下文Memory、Resource、Skill统一抽象为目录结构。目录既是组织单元也是检索单元——每个目录都可以承载语义信息从而实现「以文件系统的方式管理上下文以语义检索的方式读取上下文」。整体架构自顶向下分为五层┌────────────────────────────────────────────────────────────────────────────┐ │ OpenViking 系统架构 │ ├────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ │ │ │ Client │ │ │ │ (OpenViking)│ │ │ └──────┬──────┘ │ │ │ 委托 │ │ ┌──────▼──────┐ │ │ │ Service │ │ │ │ Layer │ │ │ └──────┬──────┘ │ │ │ │ │ ┌─────────────────────────┼─────────────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Retrieve │ │ Session │ │ Parse │ │ │ │ (上下文检索) │ │ (会话管理) │ │ (上下文提取) │ │ │ │ │ │ │ │ │ │ │ │ search/find │ │ add/used │ │ 文档解析 │ │ │ │ 意图分析 │ │ commit │ │ L0/L1/L2 │ │ │ │ Rerank │ │ commit │ │ 树构建 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ │ │ 记忆提取 │ │ │ │ ▼ │ │ │ │ ┌─────────────┐ │ │ │ │ │ Compressor │ │ │ │ │ │ 压缩/去重 │ │ │ │ │ └──────┬──────┘ │ │ │ │ │ │ │ │ └────────────────────────┼────────────────────────┘ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Storage 层 │ │ │ │ AGFS (文件内容) 向量库 (索引) │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────────────────────┘其中各核心模块的职责与关键能力如下模块职责关键能力Client统一入口提供所有操作接口委托给 Service 层Service业务逻辑FSService、SearchService、SessionService、ResourceService、PackService、DebugServiceRetrieve上下文检索意图分析IntentAnalyzer、层级检索HierarchicalRetriever、Rerank 精排Session会话管理消息记录、使用追踪、会话压缩、记忆提交Parse上下文提取文档解析PDF/MD/HTML、树构建TreeBuilder、异步语义生成Compressor记忆压缩Schema 驱动的记忆提取、LLM 去重决策Storage存储层VikingFS 虚拟文件系统、向量索引、AGFS 集成Service 层业务逻辑与传输层的解耦Service 层将业务逻辑与传输层解耦使得 HTTP Server 与 CLI 可以复用同一套服务实现。仓库中每个 Service 都是一个独立的模块位于 openviking/service/ 目录下Service职责主要方法FSService文件系统操作ls, mkdir, rm, mv, tree, stat, read, abstract, overview, grep, globSearchService语义搜索search, findSessionService会话管理session, sessions, commit, deleteResourceService资源导入add_resource, add_skill, wait_processedPackService导入导出、备份恢复export_ovpack, import_ovpack, backup_ovpack, restore_ovpackDebugService调试服务observer (ObserverService)从源码看这六个核心 Service 由OpenVikingService统一组合装配。openviking/service/core.py 中OpenVikingService的构造函数会创建FSService、PackService、SearchService、ResourceMemoryLinkService、ResourceService、SessionService、DebugService并额外装配了AgentEvolutionService、ExternalTaskService与CompileService后者通过_external_task_service.register()注册为外部任务处理器。所有子服务通过属性对外暴露fs、pack、search、resources、sessions、debug、compile、agent_evolution等见 core.py。在initialize()阶段各服务通过set_dependencies(...)注入VikingFS、VikingDBManager、压缩器、资源处理器等依赖完成装配见 core.py。以外部知识库集成为例openviking/connector/delegate.py 中的ConnectorDelegate会在ResourceService收到 add_resource 请求时接管整个委托生命周期路由判定delegate / 降级到标准流水线 / 报错、payload 构造与提交、后台任务监控最终根据远端任务的终态关闭 OpenViking 侧的 TaskRecord。ConnectorClientopenviking/connector/client.py则负责调用外部 Connector 的 doc/add 与 task/info 接口并在日志中只打印参数键名而非敏感凭据。双层存储内容与索引分离OpenViking 采用双层存储架构实现内容与索引分离详见 存储架构存储层职责内容AGFS内容存储L0/L1/L2 完整内容、多媒体文件、关联关系向量库索引存储URI、向量、元数据不存储文件内容这一架构在 core.py 的_init_storage()中完整落地RAGFS 客户端通过create_agfs_client()创建承载文件内容存储QueueManager绑定 AGFS 挂载点初始化 5 类异步队列——EXTERNAL_PARSE外部解析、ADD_RESOURCE资源入库、SESSION_COMMIT会话提交、EXTERNAL_TASK外部任务、USER_DELETION用户删除每类队列都有独立的并发上限配置VikingDBManager初始化向量库管理器并绑定AclManager做租户与权限过滤VikingFS在initialize()阶段通过init_viking_fs()组装core.py将 AGFS、embedder、rerank 配置、向量存储、ACL 管理器、检索配置、grep 配置统一成一个虚拟文件系统入口。存储层纯粹是这里的关键设计原则存储层只做 AGFS 操作和基础向量搜索Rerank 在检索层完成。所有内容从 AGFS 读取向量库仅存储引用和索引保证单一数据源。数据流一添加上下文Resource 入库添加上下文的核心流水线为输入 → Parser → TreeBuilder → AGFS → SemanticQueue → 向量库四个步骤的含义Parser解析文档创建文件和目录结构无 LLM 调用。这是纯规则解析阶段负责 PDF/MD/HTML 等格式的拆解TreeBuilder将临时目录移动到 AGFS并把语义处理任务入队SemanticQueue异步自底向上生成 L0/L1 语义信息先处理叶子文件再聚合到父目录向量库建立索引用于语义搜索。结合源码这套流水线由AddResourceProcessoropenviking/storage/queuefs/add_resource_processor.py消费ADD_RESOURCE队列驱动OpenVikingService.initialize()为EXTERNAL_PARSE与ADD_RESOURCE两个队列注册AddResourceProcessor为SESSION_COMMIT队列注册SessionCommitProcessor见 core.py。任务入队后由队列工作线程异步执行与请求线程解耦因此add_resource可以立即返回调用方通过wait_processed等待处理完成。解析与语义生成的结果遵循L0/L1/L2 三层信息模型详见 上下文层级层级名称存储形式默认正文上限用途L0摘要目录内的.abstract.md256 字符向量检索、快速过滤L1概览目录内的.overview.md4000 字符Rerank、内容导航L2详情原始文件和子目录无统一上限完整内容、按需加载L0/L1 是目录级语义 sidecar——它们描述一个目录而非每个普通文件L0 从 L1 正文的 Brief Description 段落提取L2 则保留源格式按需加载。这套渐进式加载机制的核心收益是节省 Token 消耗检索阶段先看 256 字符的摘要需要时再看 4000 字符的概览只有确认需要时才读取完整内容。数据流二检索上下文语义搜索检索上下文的流水线为查询 → 意图分析 → 层级检索 → Rerank → 结果四个步骤逐一展开意图分析分析查询意图生成0-5 个类型化查询。这一步的实现位于 openviking/retrieve/intent_analyzer.pyIntentAnalyzer.analyze()将「会话压缩摘要 最近消息 当前消息」整合成 prompt最近消息默认 5 条压缩摘要上限 30000 字符调用查询规划 LLM解析出QueryPlan其中每个TypedQuery携带query、context_typeresource / memory / skill、intent、priority字段。默认使用retrieval.intent_analysis提示词模板且对特定微调模型如ollama/guoxuter/ov_intent_analysis_sft:v7_q8有专属提示词映射见 intent_analyzer.py层级检索目录级递归搜索使用优先队列heapq按目录相关性做收敛排序。实现在 openviking/retrieve/hierarchical_retriever.pyHierarchicalRetriever内置MAX_CONVERGENCE_ROUNDS 3topk 连续多轮不变即停止、DIRECTORY_DOMINANCE_RATIO 1.2目录得分需超过子节点最大得分才继续下钻、GLOBAL_SEARCH_TOPK 10全局召回更多候选以提升精排精度、MAX_PARALLEL_CHILD_SEARCHES 4限制远程向量库的扇出并发Rerank标量过滤 模型重排。RerankClient.from_config()统一分派各 provider未配置 rerank 时自动退化为纯向量搜索hierarchical_retriever.py结果返回按相关性排序的上下文并受score_threshold、level0/1/2 层级过滤、scope_dsl租户与权限过滤约束。两阶段检索是这里的核心设计原则向量搜索召回候选 Rerank 精排提高准确性配合 L0/L1 的渐进式加载兼顾召回率、精度与 Token 成本。数据流三会话提交记忆沉淀会话提交的流水线为消息 → 压缩 → 归档 → 记忆提取 → 存储五个步骤的含义消息累积对话消息和使用记录压缩保留最近 N 轮旧消息归档归档生成历史片段的 L0/L1记忆提取根据记忆策略和MemoryType Schema从消息中提取记忆存储写入 AGFS 向量库。会话侧由SessionService与SessionCompressorV3通过create_session_compressor()创建见 core.py协作完成。压缩器组合了SkillProcessor用于 Skill 的自动提取与隐私过滤。会话提交通过SESSION_COMMIT队列异步执行此外SessionAutoCommitScheduler支持空闲自动提交由memory.session_auto_commit配置控制见 core.py。关于会话与记忆管理的更完整说明可参阅 会话管理 与 事务模型。部署模式HTTP 服务与任意语言集成HTTP 模式HTTP 模式面向团队共享、生产环境和跨语言集成场景。Server 作为独立进程运行openviking-server客户端通过 HTTP API 连接任何能发起 HTTP 请求的语言都可以集成。Python SDK 连接示例# Python SDK 连接 OpenViking Server client SyncHTTPClient(urlhttp://localhost:1933, api_keyxxx)或使用 curl / 任意 HTTP 客户端# 或使用 curl / 任意 HTTP 客户端 curl http://localhost:1933/api/v1/search/find \ -H X-API-Key: xxx \ -d {query: how to use openviking}HTTP 模式下的配置方法参见 服务部署。除 HTTP 外仓库还提供SyncHTTPClient、AsyncClient等 Python 客户端openviking/pyagfs/async_client.py并在 sdk/ 下提供 Go、Python、TypeScript 三种语言的官方 SDK。设计原则总结原则说明存储层纯粹存储层只做 AGFS 操作和基础向量搜索Rerank 在检索层完成三层信息L0/L1/L2 实现渐进式详情加载节省 Token 消耗两阶段检索向量搜索召回候选 Rerank 精排提高准确性单一数据源所有内容从 AGFS 读取向量库仅存储引用和索引这四个原则在源码中均能找到落点VikingFS只封装存储与基础搜索、Rerank 由HierarchicalRetriever持有L0/L1 sidecar 是目录的语义描述向量库只存 URI、向量与元数据所有内容读取统一经过 AGFS。相关文档导航架构是理解 OpenViking 的入口以下概念文档构成完整的知识体系上下文类型 - Resource/Memory/Skill 三种类型上下文层级 - L0/L1/L2 模型Viking URI - 统一资源标识符存储架构 - 双层存储详解上下文提取 - 解析和提取流程检索机制 - 检索流程详解会话管理 - 会话和记忆管理事务模型 - 写入与一致性模型数据加密 - 静态数据加密与密钥架构多租户 - account / user / agent 隔离模型指标 -/metrics使用方式与关键指标说明用户隐私配置 - 隐私版本管理、自动提取 Skill 隐私配置【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表