ghcr.io/volcengine/openviking:v0.3.12.dev33

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

英文 / 中文 / 日本語

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

👋 加入我们的社区

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

---

概述

智能体开发中的挑战

在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

3. 环境配置

本地模型快速设置（Ollama）

如果您希望通过 Ollama 使用本地模型运行 OpenViking，交互式设置向导会自动处理所有事项：

openviking-server init

向导将：

• 检测并在需要时安装 Ollama
• 根据您的硬件推荐并拉取合适的嵌入模型和 VLM 模型
• 生成可直接使用的 ov.conf 配置文件

随时验证您的设置：

openviking-server doctor

doctor 会检查本地先决条件（配置文件、Python 版本、嵌入/VLM 提供商连接性、磁盘空间），无需运行服务器。

对于云 API 提供商（Volcengine、OpenAI、Gemini 等），请继续以下手动配置。

服务器配置模板

推荐的首次使用流程为：

openviking-server init
openviking-server doctor

如果在 openviking-server init 中选择 OpenAI Codex，向导可以导入现有的 Codex 身份验证或为您启动 Codex 登录流程。

如果您倾向于手动配置，请创建 ~/.openviking/ov.conf，复制前移除注释：

{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
},
"log": {
"level": "INFO",
"output": "stdout" // 日志输出："stdout" 或 "file"
},
"embedding": {
"dense": {
"api_base" : " ", // API 端点地址
"api_key" : " ", // 模型服务 API Key
"provider" : " ", // 提供商类型："volcengine" 或 "openai"（当前支持）
"dimension": 1024, // 向量维度
"model" : " " // 嵌入模型名称（例如 doubao-embedding-vision-251215 或 text-embedding-3-large）
},
"max_concurrent": 10, // 最大并发嵌入请求数（默认：10）
"text_source": "content_only", // 文本文件向量化来源：content_only|summary_first|summary_only
"max_input_tokens": 4096 // 发送至嵌入模型的最大预估原始文本 tokens
},
"vlm": {
"api_base" : " ", // API 端点地址
"api_key" : " ", // 模型服务 API Key（openai-codex 可选）
"provider" : " ", // 提供商类型（volcengine、openai、openai-codex、kimi、glm 等）
"model" : " ", // VLM 模型名称（例如 doubao-seed-2-0-pro-260215 或 gpt-4-vision-preview）
"max_concurrent": 100 // 语义处理的最大并发 LLM 调用数（默认：100）
}
}

[!NOTE] 对于嵌入模型，支持的提供商包括 volcengine（豆包）、openai、azure、jina、ollama、voyage、dashscope、minimax、cohere、vikingdb、gemini（需 pip install "google-genai>=1.0.0"）、litellm 和 local。对于 VLM 模型，常见提供商包括 volcengine、openai、openai-codex、kimi 和 glm。

服务器配置示例

👇 展开查看您的模型服务的配置示例：

示例 1：使用 Volcengine（豆包模型）

{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
},
"log": {
"level": "INFO",
"output": "stdout" // 日志输出："stdout" 或 "file"
},
"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
}
}

示例 2：使用 OpenAI 模型

{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
},
"log": {
"level": "INFO",
"output": "stdout" // 日志输出："stdout" 或 "file"
},
"embedding": {
"dense": {
"api_base" : "https://api.openai.com/v1",
"api_key" : "your-openai-api-key",
"provider" : "openai",
"dimension": 3072,
"model" : "text-embedding-3-large"
},
"max_concurrent": 10
},
"vlm": {
"api_base" : "https://api.openai.com/v1",
"api_key" : "your-openai-api-key",
"provider" : "openai",
"model" : "gpt-4-vision-preview",
"max_concurrent": 100
}
}

示例 3：使用 Google Gemini 嵌入

首先安装所需包：

pip install "google-genai>=1.0.0"

{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
},
"embedding": {
"dense": {
"provider": "gemini",
"api_key": "your-google-api-key",
"model": "gemini-embedding-2-preview",
"dimension": 3072
},
"max_concurrent": 10
},
"vlm": {
"api_base" : "https://api.openai.com/v1",
"api_key" : "your-openai-api-key",
"provider" : "openai",
"model" : "gpt-4o",
"max_concurrent": 100
}
}

获取 Google API 密钥的地址：

示例 4：使用 Volcengine 嵌入 + Codex VLM

使用 openviking-server init 并选择 OpenAI Codex，然后运行 openviking-server doctor。

{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
},
"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"
}
},
"vlm": {
"api_base" : "https://chatgpt.com/backend-api/codex",
"provider" : "openai-codex",
"model" : "gpt-5.3-codex",
"max_concurrent": 100
}
}

设置服务器配置环境变量

创建配置文件后，设置环境变量以指向它（Linux/macOS）：

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # 默认路径

在 Windows 上，使用以下方法之一：

PowerShell：

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

命令提示符（cmd.exe）：

set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"

[!NOTE] 您也可以将配置文件放在其他位置，只需在环境变量中指定正确路径即可。

CLI/客户端配置示例

服务器部署详情

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

🚀 云部署 OpenViking： 为确保最佳存储性能和数据安全性，我们建议在 火山引擎弹性计算服务（ECS） 上使用 veLinux 操作系统进行部署。我们已准备了详细的分步指南，帮助您快速上手。

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

OpenClaw 上下文插件详情

• 测试数据集：基于 LoCoMo10（ ）长程对话的效果测试（移除无真实标签的 category5 后共 1,540 个案例）
• 实验组：由于用户在使用 OpenViking 时可能不会禁用 OpenClaw 的原生内存，我们添加了启用或禁用原生内存的实验组
• OpenViking 版本：0.1.18
• 模型：seed-2.0-code
• 评估脚本：

• 实验结论： 集成 OpenViking 后：

• 启用原生内存时：相比原始 OpenClaw，任务完成率提升 43%，输入 token 成本降低 91%；相比 LanceDB，任务完成率提升 15%，输入 token 成本降低 96%。
• 禁用原生内存时：相比原始 OpenClaw，任务完成率提升 49%，输入 token 成本降低 83%；相比 LanceDB，任务完成率提升 17%，输入 token 成本降低 92%。

👉 查看：OpenClaw上下文插件

👉 查看：OpenCode内存插件示例

👉 查看：Claude代码内存插件示例

👉 查看：LangChain / LangGraph集成

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

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

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