ByteNoteByteNote
字

字节笔记本

2026年2月20日

OpenViking：专为 AI Agent 设计的开源上下文数据库

#AI 前沿

本文介绍 OpenViking，字节跳动火山引擎开源的专为 AI Agent 设计的上下文数据库，通过文件系统范式统一管理 Agent 所需的记忆、资源和技能。

项目简介

OpenViking 是一个开源的上下文数据库（Context Database），专门为 AI Agent 设计。它由字节跳动火山引擎 Viking 团队开发和维护，旨在解决 AI Agent 开发中上下文管理的痛点。

该项目在 GitHub 上已获得广泛关注，采用 Apache 2.0 开源协议。

核心解决的问题

在 AI 时代，数据丰富但高质量上下文稀缺。开发 AI Agent 时，开发者常面临以下挑战：

挑战说明
上下文碎片化记忆在代码中，资源在向量数据库，技能散落各处，难以统一管理
上下文需求激增Agent 长时运行任务产生大量上下文，简单截断或压缩导致信息丢失
检索效果差传统 RAG 使用扁平存储，缺乏全局视图，难以理解信息全貌
上下文不可观测传统 RAG 的隐式检索链像黑盒，出错时难以调试
记忆迭代受限当前记忆只是用户交互记录，缺乏 Agent 相关任务记忆

OpenViking 的解决方案

OpenViking 创新性地采用**"文件系统范式"**来统一组织 Agent 所需的记忆、资源和技能：

1. 文件系统管理范式 → 解决碎片化

基于文件系统范式统一上下文管理，将记忆、资源、技能映射到 viking:// 协议下的虚拟目录：

text
viking://
├── resources/              # 资源：项目文档、代码仓库、网页等
│   ├── my_project/
│   │   ├── docs/
│   │   └── src/
│   └── ...
├── user/                   # 用户：个人偏好、习惯等
│   └── memories/
│       ├── preferences/
│       └── ...
└── agent/                  # Agent：技能、指令、任务记忆等
    ├── skills/
    ├── memories/
    └── instructions/

2. 分层上下文加载 → 降低 Token 消耗

自动将上下文处理为三层结构：

  • L0 (摘要)：一句话总结，用于快速检索识别
  • L1 (概览)：包含核心信息和使用场景，Agent 规划阶段决策使用
  • L2 (详情)：完整原始数据，Agent 深度阅读时按需加载

3. 目录递归检索 → 提升检索效果

采用创新的目录递归检索策略：

  1. 意图分析：生成多个检索条件
  2. 初定位：使用向量检索快速定位高分目录
  3. 精细探索：在该目录内进行二次检索
  4. 递归深入：如存在子目录，逐层递归重复检索
  5. 结果聚合：获取最相关的上下文返回

4. 可视化检索轨迹 → 可观测上下文

所有上下文以统一格式集成，每个条目对应唯一 URI，检索过程的目录浏览和文件定位轨迹完整保留，便于问题定位。

5. 自动会话管理 → 上下文自我迭代

内置记忆自迭代循环，会话结束时触发记忆提取机制：

  • 用户记忆更新：更新用户偏好相关记忆
  • Agent 经验积累：提取操作技巧、工具使用经验等核心内容

技术栈

  • Python - 核心开发语言（3.10+）
  • Rust - CLI 工具和高性能索引存储
  • C++ - 扩展模块（高性能索引和存储）

安装指南

Python 包安装

bash
pip install openviking

Rust CLI 安装（可选）

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

或从源码构建：

bash
cargo install --git https://github.com/volcengine/OpenViking ov_cli

快速开始

1. 模型准备

OpenViking 需要以下模型能力：

  • VLM 模型：用于图像和内容理解
  • Embedding 模型：用于向量化和语义检索

支持的 VLM 提供商

提供商模型获取 API Key
volcenginedoubao火山引擎控制台
openaigptOpenAI Platform
anthropicclaudeAnthropic Console
deepseekdeepseekDeepSeek Platform
geminigeminiGoogle AI Studio
moonshotkimiMoonshot Platform
zhipuglm智谱开放平台
dashscopeqwenDashScope 控制台
minimaxminimaxMiniMax Platform
openrouter(任意模型)OpenRouter
vllm(本地模型)—

2. 环境配置

创建配置文件 ~/.openviking/ov.conf：

json
{
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "your-api-key",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-250615"
    }
  },
  "vlm": {
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "your-api-key",
    "provider": "volcengine",
    "model": "doubao-seed-1-8-251228"
  }
}

设置环境变量：

bash
export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

3. 运行示例

python
import openviking as ov

# 初始化 OpenViking 客户端
client = ov.SyncOpenViking(path="./data")

try:
    # 初始化客户端
    client.initialize()

    # 添加资源（支持 URL、文件或目录）
    add_result = client.add_resource(
        path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
    )
    root_uri = add_result['root_uri']

    # 浏览资源树结构
    ls_result = client.ls(root_uri)
    print(f"目录结构:\n{ls_result}\n")

    # 使用 glob 查找 markdown 文件
    glob_result = client.glob(pattern="**/*.md", uri=root_uri)
    if glob_result['matches']:
        content = client.read(glob_result['matches'][0])
        print(f"内容预览: {content[:200]}...\n")

    # 等待语义处理完成
    print("等待语义处理...")
    client.wait_processed()

    # 获取资源摘要和概览
    abstract = client.abstract(root_uri)
    overview = client.overview(root_uri)
    print(f"摘要:\n{abstract}\n\n概览:\n{overview}\n")

    # 执行语义搜索
    results = client.find("what is openviking", target_uri=root_uri)
    print("搜索结果:")
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

    # 关闭客户端
    client.close()

except Exception as e:
    print(f"错误: {e}")

项目架构

text
OpenViking/
├── openviking/              # 核心源代码目录
│   ├── core/               # 核心模块：客户端、引擎、文件系统等
│   ├── models/             # 模型集成：VLM 和 Embedding 模型封装
│   ├── parse/              # 资源解析：文件解析、检测、OVPack 处理
│   ├── retrieve/           # 检索模块：语义检索、目录递归检索
│   ├── storage/            # 存储层：向量数据库、文件系统队列、观察者
│   ├── session/            # 会话管理：历史、记忆提取
│   ├── message/            # 消息处理：格式化、转换
│   ├── prompts/            # Prompt 模板
│   ├── utils/              # 工具函数
│   └── bin/                # 命令行工具
├── docs/                    # 项目文档
├── examples/                # 使用示例
├── tests/                   # 测试用例
├── src/                     # C++ 扩展（高性能索引和存储）
└── third_party/             # 第三方依赖

服务器部署

生产环境建议将 OpenViking 作为独立的 HTTP 服务运行，为 AI Agent 提供持久、高性能的上下文支持。

推荐使用**火山引擎弹性计算服务（ECS）**配合 veLinux 操作系统部署，以获得最佳存储性能和数据安全。

与 VikingDB 的关系

OpenViking 由字节跳动火山引擎 Viking 团队开发和维护：

  • 2019：VikingDB 向量数据库支持字节跳动全业务大规模使用
  • 2023：VikingDB 在火山引擎公有云上线
  • 2024：推出开发者产品矩阵：VikingDB、Viking KnowledgeBase、Viking MemoryBase
  • 2025：打造 AI Search、Vaka 知识助手等上层应用产品
  • 2025年10月：开源 MineContext，探索主动式 AI 应用
  • 2026年1月：开源 OpenViking，为 AI Agent 提供底层上下文数据库支持

社区与支持

总结

OpenViking 是一个创新的 AI Agent 上下文数据库，通过文件系统范式解决了传统 RAG 的碎片化、检索效果差、不可观测等问题。它让开发者能够像管理本地文件一样构建 Agent 的大脑，实现分层上下文加载、目录递归检索和自动记忆迭代。

对于正在构建 AI Agent 的开发者来说，OpenViking 提供了一个强大而优雅的上下文管理解决方案，值得深入探索和使用。

AI 前沿
上一篇

Cloudflare Tunnel 反向代理配置完全指南

下一篇

OpenViking：专为 AI Agent 设计的开源上下文数据库

分享: