ghcr.io/volcengine/openviking:v0.4.5.dev1

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

英文 / 中文 / 日本語

官网 · 在线演示 · GitHub · 问题反馈 · 文档

👋 加入我们的社区

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

---

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

概述

智能体开发中的挑战

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

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

OpenViking解决方案

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

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

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

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

快速开始

[!NOTE] 想先体验一下？ 试试OpenViking Studio——一个托管的在线实例，包含上下文 playground、语义搜索和多智能体中心。无需安装。

OpenViking Helper for macOS 和 Windows（测试版）

OpenViking Helper是面向OpenViking用户的桌面应用。它将本地智能体设置、会话轨迹、记忆和技能整合到可视化控制台中，便于验证设置并将本地上下文同步到OpenViking。

主要功能：

• 可视化本地智能体设置：检测OpenViking CLI、Claude Code、Codex、Cursor、Trae和OpenCode，然后配置支持的插件、MCP、Hook和CLI集成。
• 会话轨迹检查：解析Claude Code、Codex和Trae会话，显示OpenViking召回、提示注入、MCP调用、捕获和提交事件。
• 本地记忆和技能管理：查看本地记忆/规则文件和SKILL.md技能，然后将它们同步到OpenViking。

[!NOTE] OpenViking Helper目前处于测试阶段，支持macOS和Windows x64。

下载：

• macOS Apple Silicon (arm64)
• macOS Intel (x64)
• Windows (x64)

本地部署

前提条件

开始使用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-lite-260428",
"api_key": "your-api-key",
"api_base": "https://ark.cn-beijing.volces.com/api/v3"
}
}

您也可以使用端点ID（可在https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0%5C&briefType=introduce%5C&type=new%5C&utm_content=OpenViking%5C&utm_medium=devrel%5C&utm_source=OWO%5C&utm_term=OpenViking%E4%B8%AD%E6%89%BE%E5%88%B0%EF%BC%89%EF%BC%9A

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 Coding (订阅版)

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

openviking-server init
# 出现提示时选择Kimi Coding
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
}
}

[!NOTE]

• kimi会自动应用推荐的Kimi Coding默认值，包括默认的Kimi Coding用户代理
• kimi-code和kimi-coding是提供商名称的可接受别名
• kimi-code会自动规范化为Kimi的上游编码模型

GLM Coding Plan (订阅版)

当您希望OpenViking直接调用智谱AI（Z.AI）的OpenAI兼容Coding Plan端点时，使用此提供商：

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

[!NOTE]

• glm、zhipu、zai、z-ai和z.ai均解析为同一个一级GLM提供商
• 默认端点是Coding Plan端点，而非通用的Z.AI端点
• 对于多模态解析，请使用具备视觉能力的模型，例如glm-4.6v或glm-5v-turbo

3. 环境配置

本地模型快速设置（Ollama）

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

openviking-server init

该向导将：

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

随时验证您的设置：

openviking-server doctor

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

对于云API提供商（火山引擎、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密钥
"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 // 发送至嵌入模型的最大预估原始文本标记数
},
"vlm": {
"api_base" : " ", // API端点地址
"api_key" : " ", // 模型服务API密钥（openai-codex可选）
"provider" : " ", // 提供商类型（volcengine、openai、openai-codex、kimi、glm等）
"model" : " ", // VLM模型名称（例如：doubao-seed-2-0-lite-260428 或 gpt-4-vision-preview）
"max_concurrent": 64 // 语义处理的最大并发LLM调用数（默认：64）
}
}

[!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。

[!NOTE] 内存配置：OpenViking始终使用v3内存提取管道。旧版memory.version设置已弃用并被忽略；设置了该值的现有配置仍可加载，但不会改变行为。

[!NOTE] 内存模式作用域：内存模式YAML默认值为stage: "user"和peer_enabled: true。对于执行派生的模式（如轨迹/经验），使用stage: "agent"；当模式必须保留在当前用户的内存目录而非对等目录时，设置peer_enabled: false。

服务器配置示例

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

示例1：使用火山引擎（豆包模型）

{
"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-lite-260428",
"max_concurrent": 64
}
}

示例2：使用OpenAI模型

设置服务器配置环境变量

创建配置文件后，设置环境变量以指向该文件（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/客户端配置示例

你可以通过 ov config 命令以交互方式初始化 CLI/客户端配置。如果有多个 OpenViking 服务器，你还可以使用 ov config switch 命令切换到其他配置。

👇 展开查看 CLI/客户端的配置示例：

示例：访问本地服务器的 ovcli.conf

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

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

export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # 默认路径

在 Windows 上，使用以下命令之一：

PowerShell：

$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"

命令提示符（cmd.exe）：

set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"

4. 运行你的第一个示例

[!IMPORTANT] 前提条件：确保已完成上一步中的配置（ov.conf 和 ovcli.conf）。

现在让我们运行一个完整示例，体验 OpenViking 的核心功能。

启动服务器

openviking-server doctor
openviking-server

如果你配置了 provider=openai-codex，openviking-server doctor 已验证 Codex 身份认证。

或者你可以在后台运行：

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

运行 CLI

ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# 如果未使用 --wait，需等待一段时间进行语义处理
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh

要重建现有索引，ov reindex --mode vectors_only 仅刷新向量。当必须在生成向量前重新生成语义工件（.abstract.md 和 .overview.md）时，使用 --mode semantic_and_vectors；没有 semantic 或 full 模式别名。

恭喜！你已成功运行 OpenViking 🎉

4. Visualized Retrieval Trajectory → Observable Context

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

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

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

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