简介

OpenViking 是由字节跳动火山引擎团队开源的一款专为 AI Agent 设计的上下文数据库。它旨在解决传统 RAG 系统在 Agent 长周期任务中面临的上下文碎片化、Token 消耗激增、检索效果差及调试困难等痛点。OpenViking 创新性地采用 “文件系统范式”，将 Agent 所需的记忆、资源、技能统一抽象为虚拟文件系统中的目录和文件，通过 viking://协议进行结构化组织，实现了上下文的分层按需加载、目录递归检索与记忆自迭代，让 Agent 拥有一个可观测、可治理且越用越聪明的“大脑”。

主要功能

• 文件系统管理范式：摒弃扁平化向量存储，将所有上下文（记忆、资源、技能）映射为 viking://协议下的虚拟目录（如 viking://resources/my_project/），支持 ls、find、tree等标准文件操作，实现确定性的上下文寻址。

• 分层上下文加载（L0/L1/L2）：数据摄入时自动生成三层结构。L0（Abstract，约100 tokens）用于快速筛选；L1（Overview，约2k tokens）用于决策规划；L2（Detail）为完整数据，按需加载。此机制可大幅降低 Token 消耗（实测可节省 70%-90%）。

• 目录递归检索：结合语义搜索与文件系统路径定位。先通过向量检索定位高分目录，再在该目录下进行递归精细搜索，提升检索的精准度与全局性。

• 可视化检索轨迹：检索过程完全可观测，开发者可以清晰看到 Agent 是如何从根目录一步步定位到目标文件的，便于调试和优化检索逻辑。

• 自动会话管理与记忆迭代：会话结束时自动压缩对话内容，提取长期记忆并归档，更新用户偏好与 Agent 经验，实现记忆的自我进化。

安装与配置

1. 安装

OpenViking 提供 Python SDK 和 Rust CLI 两种安装方式。

Python SDK（推荐）：

pip install openviking --upgrade --force-reinstall

Rust CLI（可选，用于命令行操作）：

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

2. 配置

创建配置文件 ~/.openviking/ov.conf，配置模型服务与存储路径。

示例配置（使用 OpenAI 模型）：

{
  "storage": { "workspace": "/path/to/your/workspace" },
  "embedding": {
    "dense": {
      "provider": "openai",
      "model": "text-embedding-3-large",
      "api_key": "your-openai-key",
      "api_base": "https://api.openai.com/v1"
    }
  },
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key": "your-openai-key",
    "api_base": "https://api.openai.com/v1"
  }
}

设置环境变量：

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

如何使用

1. 启动服务

openviking-server
# 或使用 nohup 后台运行
nohup openviking-server > /data/log/openviking.log 2>&1 &

2. 基础操作流程（以 CLI 为例）

• 添加资源：ov add-resource https://github.com/volcengine/OpenViking --wait

• 浏览结构：ov ls viking://resources/或 ov tree viking://resources/ -L 2

• 语义搜索：ov find "what is openviking"

• 内容检索：ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/

3. Python SDK 集成

在 Agent 代码中导入 SDK，通过 URI 直接读取上下文或进行搜索，利用分层加载机制仅获取必要的 L0/L1 信息用于规划，仅在执行阶段加载 L2 详情。

应用场景实例

实例 1：OpenClaw 长周期任务增强

场景：OpenClaw 原生 Memory 模块在长对话中易出现记忆碎片化，导致复杂任务完成率仅 35.65%，且 Token 成本极高。

OpenViking 方案：集成 OpenViking 作为外挂记忆体。Agent 执行任务时，通过目录递归检索精准定位项目配置文件（如 viking://resources/project-alpha/config/db.yaml），而非在碎片中盲猜。实测结果显示，任务完成率提升至 52.08%，输入 Token 总量从 2461 万降至 426 万，成本降低 83%。

实例 2：企业级智能客服知识库

场景：企业拥有海量产品文档（PDF、网页、API 文档），传统 RAG 检索常返回无关片段，且无法理解文档间的层级关系。

OpenViking 方案：将文档按产品线、版本、模块组织为 viking://resources/products/v2.1/api/结构。当用户询问“V2.1 版本支付接口的变更”时，Agent 先定位到 V2.1 目录，再递归搜索支付相关文件，确保返回的上下文具有完整的版本上下文，避免混淆不同版本的信息。

实例 3：多模态研发助手

场景：研发 Agent 需要结合代码仓库、设计稿（图像）和 PR 评论进行代码审查。

OpenViking 方案：将代码仓库、UI 截图、PR 链接作为资源添加。利用 VLM 能力生成图像摘要存储在 L0 层。当 Agent 审查代码时，通过 find命令关联到对应的设计稿资源，确保代码实现与视觉设计的一致性。

GitHub 地址

项目仓库：https://github.com/volcengine/OpenViking