ghcr.io/volcengine/openviking:v0.3.22.dev2

OpenViking：AI智能体的上下文数据库

英文 / 中文 / 日本語

网站 · GitHub · 问题反馈 · 文档

👋 加入我们的社区

📱 飞书群 · 微信 · *** · X

---

✨ 2026年5月更新：更新了OpenViking在用户记忆、智能体记忆和知识库问答场景下的基准测试结果。→ 参见评估亮点。

概述

智能体开发中的挑战

在AI时代，数据虽丰富，但高质量的上下文却难以获取。构建AI智能体时，开发者常面临以下挑战：

• 上下文碎片化：记忆存储在代码中，资源位于向量数据库，技能分散各处，难以统一管理。
• 上下文需求激增：智能体的长期运行任务在每次执行时都会产生上下文。简单的截断或压缩会导致信息丢失。
• 检索效果不佳：传统RAG采用扁平存储，缺乏全局视角，难以理解信息的完整上下文。
• 上下文不可观测：传统RAG的隐式检索链如同黑盒，出现错误时难以调试。
• 记忆迭代受限：当前记忆仅记录用户交互，缺乏智能体相关的任务记忆。

OpenViking解决方案

OpenViking 是专为AI智能体设计的开源上下文数据库。

我们旨在为智能体定义极简的上下文交互范式，让开发者彻底告别上下文管理的烦恼。OpenViking摒弃了传统RAG的碎片化向量存储模型，创新性地采用**“文件系统范式”**，统一智能体所需的记忆、资源和技能的结构化组织。

借助OpenViking，开发者可以像管理本地文件一样构建智能体的“大脑”：

• 文件系统管理范式 → 解决碎片化问题：基于文件系统范式统一管理记忆、资源和技能的上下文。
• 分层上下文加载 → 降低Token消耗：L0/L1/L2三层结构，按需加载，大幅节省成本。
• 目录递归检索 → 提升检索效果：支持原生文件系统检索方式，结合目录定位与语义搜索，实现递归精准的上下文获取。
• 可视化检索轨迹 → 上下文可观测：支持目录检索轨迹可视化，用户可清晰观察问题根源，指导检索逻辑优化。
• 自动会话管理 → 上下文自迭代：自动压缩对话中的内容、资源引用、工具调用等，提取长期记忆，让智能体越用越聪明。

快速开始

前提条件

开始使用OpenViking前，请确保您的环境满足以下要求：

• Python版本：3.10或更高
• Rust工具链：Cargo（从源码构建RAGFS和CLI组件时必需）
• C++编译器：GCC 9+ 或 Clang 11+（构建核心扩展时必需）
• 操作系统：Linux、macOS、Windows
• 网络连接：需要稳定的网络连接（用于下载依赖和访问模型服务）

1. 安装

Python包

pip install openviking --upgrade --force-reinstall

Rust CLI（可选）

npm i -g @openviking/cli

或从源码构建：

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

2. 模型准备

OpenViking需要以下模型能力：

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

支持的VLM提供商

OpenViking支持多种VLM提供商：

特定提供商说明

火山引擎（豆包）

火山引擎支持模型名称和端点ID。为简单起见，建议使用模型名称：

{
"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"
}
}

您也可以使用端点ID（可在火山引擎ARK控制台中找到）：

{
"vlm": {
"provider": "volcengine",
"model": "ep-20241220174930-xxxxx",
"api_key": "your-api-key",
"api_base": "https://ark.cn-beijing.volces.com/api/v3"
}
}

OpenAI

使用OpenAI官方API：

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

您也可以使用自定义的OpenAI兼容端点：

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

OpenAI Codex（OAuth）

当您希望OpenViking通过您的***/Codex OAuth会话而非标准OpenAI API密钥调用Codex VLM时，使用此提供商：

openviking-server init
# 出现提示时选择OpenAI Codex
openviking-server doctor

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

[!NOTE]

• 当Codex OAuth可用时，openai-codex 不需要 vlm.api_key
• OpenViking将自己的Codex认证状态存储在 ~/.openviking/codex_auth.json
• openviking-server doctor 验证当前Codex认证是否可用

Kimi代码（订阅）

当您希望OpenViking直接调用专用的Kimi代码订阅端点时，使用此提供商：

openviking-server init
# 出现提示时选择Kimi代码
openviking-server doctor

{
"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 编码计划（订阅版）

当您希望 OpenViking 直接调用 Z.AI 的 OpenAI 兼容编码计划端点时，请使用此提供商：

openviking-server init
# 出现提示时选择 GLM Coding Plan
openviking-server doctor

{
"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
}
}

💡 提示：

• glm、zhipu、zai、z-ai 和 z.ai 均指向同一个一流的 GLM 提供商
• 默认端点是编码计划端点，而非通用 Z.AI 端点
• 对于多模态解析，请使用支持视觉的模型，例如 glm-4.6v 或 glm-5v-turbo

服务器部署详情

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

🚀 云部署OpenViking：
为确保最佳存储性能和数据安全，我们建议在Volcengine Elastic Compute Service (ECS) 上使用veLinux操作系统进行部署。我们已准备了详细的分步指南，帮助您快速上手。

👉 查看：服务器部署与ECS设置指南

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

OpenViking 采用层级化虚拟文件系统结构进行组织。所有上下文均以统一格式整合，每个条目对应唯一 URI（如 viking:// 路径），打破了传统的扁平化黑盒管理模式，层级清晰且易于理解。

检索过程采用目录递归策略。每次检索的目录浏览和文件定位轨迹均被完整保留，用户可清晰观察问题根源并指导检索逻辑的优化。了解更多：检索机制

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

OpenViking 内置记忆自迭代循环。在每个会话结束时，开发者可主动触发记忆提取机制。系统会异步分析任务执行结果和用户反馈，并自动更新至 User 和 Agent 记忆目录。

• 用户记忆更新：更新与用户偏好相关的记忆，使 Agent 响应更贴合用户需求。
• Agent 经验积累：从任务执行经验中提取操作技巧、工具使用经验等核心内容，辅助后续任务的高效决策。

这使得 Agent 通过与世界的交互实现越用越“聪明”，达成自我进化。了解更多：会话管理

• 主项目：AGPLv3 - 详情参见 LICENSE 文件
• crates/ov_cli：Apache 2.0 - 详情参见 LICENSE 文件
• examples：Apache 2.0 - 详情参见 LICENSE 文件
• third_party：第三方项目各自的原始许可证