AI 2026年4月22日 3 分钟阅读

给 AI Agent 装个”文件系统”：OpenViking 上手指南

tinyash 0 条评论
openviking

前两天我在 GitHub 上刷到一个项目，叫 OpenViking。字节开源的，给 AI Agent 用的上下文数据库。

我一开始没太在意，心想上下文管理嘛，不就是 RAG 那一套，向量数据库存一存，检索的时候查一查，能有什么花样。

结果点开 README 看了一眼，给我整愣住了。

这玩意不用向量数据库的扁平存储，它用文件系统范式来管理 AI 的上下文。

什么意思呢？就是你像管理本地文件一样管理 AI 的记忆、资源和技能。ls、find、grep，这些你天天用的命令，直接拿来操作 AI 的上下文。

我当时就想，这思路有点意思啊。

为什么需要这玩意

先聊聊痛点。

你现在要搞一个 AI Agent，比如开个 OpenClaw 或者 Codex 让它帮你干活，上下文管理是个绕不开的问题。

记忆存在代码里，资源存在向量数据库里，技能又散落在各个地方。碎片化不说，检索效果还玄学。

更麻烦的是，Agent 跑长任务的时候，上下文是源源不断产生的。简单截断吧，信息丢了。全塞进 prompt 吧，token 烧不起，模型窗口也撑不住。

还有就是那个黑盒检索。传统 RAG 怎么检索的，你根本看不到。出问题了也不知道从哪 debug。

OpenViking 想解决的就是这些事。

它是怎么想的

OpenViking 的核心思路，是把上下文抽象成一个虚拟文件系统。

所有的记忆、资源、技能，都映射到 viking:// 协议下的虚拟目录里，每个条目都有唯一的 URI。

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

这样一来，Agent 操作上下文就像开发者操作文件一样，可以精确定位、浏览、 манипулировать。

不再是模糊的语义匹配，而是可追溯的”文件操作”。

光有结构还不够，OpenViking 还搞了个三层上下文加载。

L0（摘要层）：一句话总结，用于快速检索和识别，大概 100 token。

L1（概览层）：包含核心信息和使用场景，Agent 做规划决策时用，大概 2k token。

L2（详情层）：完整原始数据，Agent 真需要深入阅读时才加载。

这设计挺聪明的。大部分时候 Agent 只需要 L0 或 L1 就能判断相关性，真需要细节再往下钻。token 省了，噪音也少了。

检索策略也有讲究。

它不是单一向量检索，而是目录递归检索。先用向量检索定位到高评分目录，然后在那个目录里做二次检索，如果有子目录就继续递归。

“先锁目录，再探内容”。这比漫无目的地在扁平空间里捞片段要准得多。

安装

好了，理念聊完了，该动手了。

先看看环境要求。

  • Python 3.10 或更高
  • Go 1.22 或更高（构建 AGFS 组件需要）
  • C++ 编译器：GCC 9+ 或 Clang 11+
  • 操作系统：Linux、macOS、Windows 都行

第一步，装 Python 包。

pip install openviking --upgrade --force-reinstall

第二步，装 CLI 工具。

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

或者从源码构建。

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

配置模型

OpenViking 需要两类模型。

VLM 模型：用于图像和内容理解。

Embedding 模型：用于向量化和语义检索。

VLM 支持好几个提供商。

Volcengine（豆包）：字节的，用 model name 就行，比较简单。

{
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-pro-260215",
    "api_key": "your-api-key",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  }
}

OpenAI：官方 API。

{
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key": "your-api-key",
    "api_base": "https://api.openai.com/v1"
  }
}

OpenAI Codex：用 OAuth 会话调用，不需要 API key。

{
  "vlm": {
    "provider": "openai-codex",
    "model": "gpt-5.3-codex",
    "api_base": "https://chatgpt.com/backend-api/codex",
    "temperature": 0.0,
    "max_retries": 2
  }
}

Kimi Coding：月之暗面的订阅服务。

{
  "vlm": {
    "provider": "kimi",
    "model": "kimi-code",
    "api_key": "your-kimi-subscription-api-key",
    "api_base": "https://api.kimi.com/coding",
    "temperature": 0.0,
    "max_retries": 2
  }
}

GLM Coding Plan：智谱的。

{
  "vlm": {
    "provider": "glm",
    "model": "glm-4.6v",
    "api_key": "your-zai-api-key",
    "api_base": "https://api.z.ai/api/coding/paas/v4",
    "temperature": 0.0,
    "max_retries": 2
  }
}

Embedding 模型支持的提供商有 Volcengine、OpenAI、Jina、Voyage、Minimax、VikingDB、Gemini。

配置文件

配置好了模型，接下来创建配置文件。

推荐用交互式向导，省心。

openviking-server init

这个向导会帮你检测安装 Ollama（如果用本地模型），推荐合适的 embedding 和 VLM 模型，然后生成 ov.conf 配置文件。

想手动配置也行。在 ~/.openviking/ 目录下创建 ov.conf 文件。

{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "your-volcengine-api-key",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-251215"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "your-volcengine-api-key",
    "provider": "volcengine",
    "model": "doubao-seed-2-0-pro-260215",
    "max_concurrent": 100
  }
}

配置完设置环境变量。

Linux/macOS：

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

Windows PowerShell：

$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"

CLI 工具也需要配置文件 ovcli.conf。

{
  "url": "http://localhost:1933",
  "timeout": 60.0,
  "output": "table"
}

export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf

启动和验证

配置好了，先验证一下。

openviking-server doctor

这个命令会检查本地前置条件，配置文件、Python 版本、embedding/VLM 提供商连通性、磁盘空间，不需要服务器运行就能测。

没问题了就启动服务器。

openviking-server

或者后台运行。

nohup openviking-server > /data/log/openviking.log 2>&1 &

跑个完整例子

服务器起来了，咱们体验一下核心功能。

先看看状态。

ov status

添加一个资源，比如 OpenViking 自己的 GitHub 仓库。

ov add-resource https://github.com/volcengine/OpenViking

加个 --wait 参数可以等待语义处理完成，不然得等一会儿。

查看资源列表。

ov ls viking://resources/

看看目录树。

ov tree viking://resources/volcengine -L 2

搜索一下。

ov find "what is openviking"

或者用 grep。

ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh

恭喜，你已经成功跑通 OpenViking 了。

VikingBot

OpenViking 上面还套了个 Agent 框架叫 VikingBot。

安装。

# 从 PyPI 安装（推荐）
pip install "openviking[bot]"

# 从源码安装（开发用）
uv pip install -e ".[bot]"

启动带 Bot 的服务器。

openviking-server --with-bot

另一个终端启动交互式聊天。

ov chat

官方 Docker 镜像里已经 bundled VikingBot，默认和服务器一起启动。想禁用可以用 --without-bot 或者设置环境变量 OPENVIKING_WITH_BOT=0。

性能怎么样

光说不练假把式，看看数据。

测试用的是 LoCoMo10 长程对话数据集，1540 个用例。模型是 seed-2.0-code。

对比了三组。

实验组任务完成率输入 Token 总量
OpenClaw（原生记忆）35.65%24,611,530
OpenClaw + LanceDB（禁用原生记忆）44.55%51,574,530
OpenClaw + OpenViking（禁用原生记忆）52.08%4,264,396
OpenClaw + OpenViking（启用原生记忆）51.23%2,099,622

结论挺明显的。

集成 OpenViking 之后，相比原生 OpenClaw，任务完成率提升 43-49%，输入 token 成本降低 83-91%。

相比 LanceDB，任务完成率提升 15-17%，token 成本降低 92-96%。

这省 token 的效果，有点离谱了。

一些想法

我琢磨了一下 OpenViking 这个设计。

它最妙的地方是把”上下文管理”这个模糊的问题，转化成了”文件系统操作”这个具体的问题。

开发者天天跟文件系统打交道，ls、cd、find、grep，这些命令早就刻进 DNA 里了。用这套范式来管理 AI 的上下文，学习成本几乎为零。

而且文件系统天然有层次结构，这比扁平的向量空间更适合组织复杂的上下文信息。

三层加载的设计也很实用。大部分时候 Agent 根本不需要读全文，L0 或 L1 就够判断相关性了。真需要细节再往下钻，token 自然就省下来了。

还有就是可观测性。传统 RAG 检索是个黑盒，出问题了不知道从哪查。OpenViking 把检索轨迹都记下来，目录浏览、文件定位，每一步都看得见。这就好 debug 多了。

当然，这项目还早期，肯定有不少要完善的地方。但思路是对的。

AI Agent 发展到今天，基础设施这块确实需要一些新东西。

怎么开始

感兴趣的话可以试试。

GitHub：https://github.com/volcengine/OpenViking

官网：https://www.openviking.ai

文档：https://www.openviking.ai/docs

社区有飞书群、微信群、Discord、X，扫码或者点链接都能进。

项目是 AGPLv3 许可，CLI 工具和 examples 是 Apache 2.0。

最后说一句。

AI 时代，数据不缺，缺的是高质量的上下文。

谁能把上下文管理这件事做好，谁就能让 Agent 真正变聪明。

OpenViking 走了一条有意思的路。文件系统范式，听起来简单，但说不定就是那个对的方向。

大时代啊，朋友们。

AI AI 工具

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。