volcengine/OpenViking

## 概述 ### Agent 开发中的挑战 在 AI 时代，数据随处可见，但高质量的上下文却难以获取。在构建 AI Agent 时，开发者通常面临以下挑战： - **上下文碎片化**：记忆散落在代码中，资源存储在向量数据库中，技能更是四处分散，难以进行统一管理。 - **上下文需求激增**：Agent 的长周期任务在每次执行时都会产生上下文。简单的截断或压缩会导致信息丢失。 - **检索效果不佳**：传统 RAG 采用扁平化存储，缺乏全局视角，难以理解信息的完整上下文。 - **上下文不可观测**：传统 RAG 的隐式检索链如同黑盒，发生错误时难以调试。 - **记忆迭代受限**：当前的所谓记忆仅仅是用户交互记录的堆砌，缺乏与 Agent 相关的任务记忆。 ### OpenViking 解决方案 **OpenViking** 是一个专为 AI Agent 设计的开源**上下文数据库**。 我们致力于为 Agent 定义一种极简的上下文交互范式，让开发者彻底告别上下文管理的繁琐。OpenViking 摒弃了传统 RAG 碎片化的向量存储模式，创新性地采用**“文件系统范式”**，统一了 Agent 所需的记忆、资源和技能的结构化组织。 借助 OpenViking，开发者可以像管理本地文件一样构建 Agent 的大脑： - **文件系统管理范式** → **解决碎片化问题**：基于文件系统范式对记忆、资源和技能进行统一的上下文管理。 - **分层上下文加载** → **降低 Token 消耗**：L0/L1/L2 三层结构，按需加载，显著节省成本。 - **目录递归检索** → **提升检索效果**：支持原生文件系统检索方式，将目录定位与语义搜索相结合，实现递归且精准的上下文获取。 - **可视化检索轨迹** → **上下文可观测**：支持目录检索轨迹的可视化，让用户清晰观察问题的根本原因，引导检索逻辑优化。 - **自动会话管理** → **上下文自我迭代**：自动压缩对话中的内容、资源引用、工具调用等，并提取长期记忆，让 Agent 越用越聪明。 ## 快速开始 ### 前置条件 在开始使用 OpenViking 之前，请确保您的环境满足以下要求： - **Python 版本**：3.10 或更高版本 - **Go 版本**：1.22 或更高版本（构建 AGFS 组件所需） - **C++ 编译器**：GCC 9+ 或 Clang 11+（构建核心扩展所需） - **操作系统**：Linux、macOS、Windows - **网络连接**：需要稳定的网络连接（用于下载依赖和访问模型服务） ### 1. 安装 #### Python 包 ``` pip install openviking --upgrade --force-reinstall ``` #### Rust 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 ``` ### 2. 模型准备 OpenViking 需要以下模型能力： - **VLM 模型**：用于图像和内容理解 - **Embedding 模型**：用于向量化和语义检索 #### 支持的 VLM 提供商 OpenViking 支持三种 VLM 提供商： | 提供商 | 描述 | 获取 API Key | |----------|-------------|-------------| | `volcengine` | 火山引擎豆包模型 | [火山引擎控制台](https://console.volcengine.com/ark) | | `openai` | OpenAI 官方 API | [OpenAI 平台](https://platform.openai.com) | | `litellm` | 统一调用多种第三方模型 (Anthropic, DeepSeek, Gemini, vLLM, Ollama 等) | 参见 [LiteLLM Providers](https://docs.litellm.ai/docs/providers) | #### 提供商特定说明

Volcengine (Doubao)

火山引擎同时支持模型名称和 endpoint 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" } } ``` 您也可以使用 endpoint ID（可在 [火山引擎 ARK 控制台](https://console.volcengine.com/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 兼容 endpoint： ``` { "vlm": { "provider": "openai", "model": "gpt-4o", "api_key": "your-api-key", "api_base": "https://your-custom-endpoint.com/v1" } } ```

LiteLLM (Anthropic, DeepSeek, Gemini, Qwen, vLLM, Ollama 等)

LiteLLM 提供了对各种模型的统一访问。`model` 字段应遵循 LiteLLM 的命名约定。这里我们以 Claude 和 Qwen 为例： **Anthropic:** ``` { "vlm": { "provider": "litellm", "model": "claude-3-5-sonnet-20240620", "api_key": "your-anthropic-api-key" } } ``` **Qwen (DashScope):** ``` { "vlm": { "provider": "litellm", "model": "dashscope/qwen-turbo", // see https://docs.litellm.ai/docs/providers/dashscope for more details "api_key": "your-dashscope-api-key", "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1" } } ``` **常见模型格式：** | 提供商 | 模型示例 | 备注 | |----------|---------------|-------| | Anthropic | `claude-3-5-sonnet-20240620` | 自动检测，使用 `ANTHROPIC_API_KEY` | | DeepSeek | `deepseek-chat` | 自动检测，使用 `DEEPSEEK_API_KEY` | | Gemini | `gemini-pro` | 自动检测，使用 `GEMINI_API_KEY` | | Qwen | `dashscope/qwen-turbo` | 根据地区设置 `api_base`（见上文） | | OpenRouter | `openrouter/openai/gpt-4o` | 需要完整前缀 | | vLLM | `hosted_vllm/llama-3.1-8b` | 将 `api_base` 设置为 vLLM 服务器 | | Ollama | `ollama/llama3.1` | 将 `api_base` 设置为 Ollama 服务器 | **本地模型 (vLLM / Ollama):** ``` # 启动 Ollama ollama serve ``` ``` // Ollama { "vlm": { "provider": "litellm", "model": "ollama/llama3.1", "api_base": "http://localhost:11434" } } ``` 完整的模型支持列表，请参见 [LiteLLM Providers 文档](https://docs.litellm.ai/docs/providers)。

### 3. 环境配置 #### 服务端配置模板 创建配置文件 `~/.openviking/ov.conf`，复制前请去除注释： ``` { "storage": { "workspace": "/home/your-name/openviking_workspace" }, "log": { "level": "INFO", "output": "stdout" // Log output: "stdout" or "file" }, "embedding": { "dense": { "api_base" : "", // API endpoint address "api_key" : "", // Model service API Key "provider" : "", // Provider type: "volcengine" or "openai" (currently supported) "dimension": 1024, // Vector dimension "model" : "" // Embedding model name (e.g., doubao-embedding-vision-250615 or text-embedding-3-large) }, "max_concurrent": 10 // Max concurrent embedding requests (default: 10) }, "vlm": { "api_base" : "", // API endpoint address "api_key" : "", // Model service API Key "provider" : "", // Provider type (volcengine, openai, deepseek, anthropic, etc.) "model" : "", // VLM model name (e.g., doubao-seed-2-0-pro-260215 or gpt-4-vision-preview) "max_concurrent": 100 // Max concurrent LLM calls for semantic processing (default: 100) } } ``` #### 服务端配置示例 👇 展开查看适用于您的模型服务的配置示例：

示例 1：使用火山引擎 (Doubao 模型)

``` { "storage": { "workspace": "/home/your-name/openviking_workspace" }, "log": { "level": "INFO", "output": "stdout" // Log output: "stdout" or "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-250615" }, "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" // Log output: "stdout" or "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 } } ```

#### 设置服务端配置环境变量 创建配置文件后，设置环境变量指向该文件 (Linux/macOS)： ``` export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # by default ``` 在 Windows 上，使用以下方式之一： PowerShell: ``` $env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf" ``` 命令提示符 (cmd.exe): ``` set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" ``` #### CLI/客户端配置示例 👇 展开查看适用于您的 CLI/客户端的配置示例： 示例：用于访问本地服务器的 ovcli.conf ``` { "url": "http://localhost:1933", "timeout": 60.0, "output": "table" } ``` 创建配置文件后，设置环境变量指向该文件 (Linux/macOS)： ``` export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # by default ``` 在 Windows 上，使用以下方式之一： PowerShell: ``` $env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf" ``` 命令提示符 (cmd.exe): ``` set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf" ``` ### 4. 运行第一个示例 现在让我们运行一个完整的示例，体验 OpenViking 的核心功能。 #### 启动服务器 ``` openviking-server ``` 或者您可以在后台运行 ``` 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 ``` 恭喜！您已成功运行 OpenViking 🎉 ## 服务端部署详情 对于生产环境，我们建议将 OpenViking 作为独立的 HTTP 服务运行，为您的 AI Agent 提供持久化、高性能的上下文支持。 🚀 **在云端部署 OpenViking**： 为了确保最佳的存储性能和数据安全，我们推荐在**火山引擎云服务器 (ECS)** 上使用 **veLinux** 操作系统进行部署。我们准备了详细的分步指南助您快速上手。 👉 **[查看：服务端部署与 ECS 配置指南](./docs/en/getting-started/03-quickstart-server.md)** ## OpenClaw 记忆插件详情 * 测试数据集：基于 LoCoMo10 (https://github.com/snap-research/locomo) 长程对话的效果测试（去除没有 ground truth 的 category5 后共计 1,540 个用例） * 实验分组：由于用户在使用 OpenViking 时可能不会禁用 OpenClaw 的原生记忆，我们增加了启用或禁用原生记忆的实验组 * OpenViking 版本：0.1.18 * 模型：seed-2.0-code * 评估脚本：https://github.com/ZaynJarvis/openclaw-eval/tree/main | 实验组 | 任务完成率 | 成本：输入 Token (总计) | |----------|------------------|------------------| | OpenClaw(memory-core) | 35.65% | 24,611,530 | | OpenClaw + LanceDB (-memory-core) | 44.55% | 51,574,530 | | OpenClaw + OpenViking Plugin (-memory-core) | 52.08% | 4,264,396 | | OpenClaw + OpenViking Plugin (+memory-core) | 51.23% | 2,099,622 | * 实验结论： 集成 OpenViking 后： - 开启原生记忆：相比原始 OpenClaw 提升 43%，输入 token 成本降低 91%；相比 LanceDB 提升 15%，输入 token 成本降低 96%。 - 关闭原生记忆：相比原始 OpenClaw 提升 49%，输入 token 成本降低 83%；相比 LanceDB 提升 17%，输入 token 成本降低 92%。 👉 **[查看：OpenClaw 记忆插件](examples/openclaw-memory-plugin/README.md)** -- ## 核心概念 运行完第一个示例后，让我们深入了解 OpenViking 的设计哲学。这五个核心概念与前文提到的解决方案一一对应，共同构建了一个完整的上下文管理系统： ### 1. 文件系统管理范式 → 解决碎片化 我们不再将上下文视为扁平的文本切片，而是将其统一到一个抽象的虚拟文件系统中。无论是记忆、资源还是能力，都被映射到 `viking://` 协议下的虚拟目录中，每个对象都有唯一的 URI。 这种范式赋予了 Agent 前所未有的上下文操控能力，使其能够像开发者一样通过 `ls`、`find` 等标准命令进行精准、确定性的定位、浏览和操作信息。这将上下文管理从模糊的语义匹配转变为直观、可追溯的“文件操作”。了解更多：[Viking URI](./docs/en/concepts/04-viking-uri.md) | [上下文类型](./docs/en/concepts/02-context-types.md) ``` viking:// ├── resources/ # Resources: project docs, repos, web pages, etc. │ ├── my_project/ │ │ ├── docs/ │ │ │ ├── api/ │ │ │ └── tutorials/ │ │ └── src/ │ └── ... ├── user/ # User: personal preferences, habits, etc. │ └── memories/ │ ├── preferences/ │ │ ├── writing_style │ │ └── coding_habits │ └── ... └── agent/ # Agent: skills, instructions, task memories, etc. ├── skills/ │ ├── search_code │ ├── analyze_data │ └── ... ├── memories/ └── instructions/ ``` ### 2. 分层上下文加载 → 降低 Token 消耗 将海量上下文一次性塞入 prompt 不仅昂贵，还容易超出模型窗口并引入噪声。OpenViking 在写入时自动将上下文处理为三个层级： - **L0 (摘要)**：一句话总结，用于快速检索和识别。 - **L1 (概览)**：包含核心信息和使用场景，供 Agent 在规划阶段进行决策。 - **L2 (详情)**：完整的原始数据，供 Agent 在绝对必要时进行深度阅读。 了解更多：[上下文层级](./docs/en/concepts/03-context-layers.md) ``` viking://resources/my_project/ ├── .abstract # L0 Layer: Abstract (~100 tokens) - Quick relevance check ├── .overview # L1 Layer: Overview (~2k tokens) - Understand structure and key points ├── docs/ │ ├── .abstract # Each directory has corresponding L0/L1 layers │ ├── .overview │ ├── api/ │ │ ├── .abstract │ │ ├── .overview │ │ ├── auth.md # L2 Layer: Full content - Load on demand │ │ └── endpoints.md │ └── ... └── src/ └── ... ``` ### 3. 目录递归检索 → 提升检索效果 单一向量检索难以应对复杂的查询意图。OpenViking 设计了创新的**目录递归检索策略**，深度融合了多种检索方式： 1. **意图分析**：通过意图分析生成多个检索条件。 2. **初步定位**：利用向量检索快速定位初始切片所在的高分目录。 3. **精细探索**：在该目录内进行二次检索，并更新高分结果至候选集。 4. **递归下钻**：若存在子目录，则逐层递归重复二次检索步骤。 5. **结果聚合**：最终获取最相关的上下文并返回。 这种“先锁定高分目录，再精细化内容探索”的策略不仅找到了语义最匹配的片段，还能信息所在的全貌，从而提升了检索的全局性和准确性。了解更多：[检索机制](./docs/en/concepts/07-retrieval.md) ### 4. 可视化检索轨迹 → 上下文可观测 OpenViking 的组织采用层级化的虚拟文件系统结构。所有上下文以统一格式集成，每个条目对应一个唯一的 URI（如 `viking://` 路径），打破了传统扁平化的黑盒管理模式，层级清晰，易于理解。 检索过程采用目录递归策略。每次检索的目录浏览和文件定位轨迹都被完整保留，用户可以清晰观察问题的根源，引导检索逻辑的优化。了解更多：[检索机制](./docs/en/concepts/07-retrieval.md) ### 5. 自动会话管理 → 上下文自我迭代 OpenViking 内置了记忆自我迭代循环。在每次会话结束时，开发者可以主动触发记忆提取机制。系统将异步分析任务执行结果和用户反馈，并自动更新至用户（User）和 Agent 的记忆目录中。 - **用户记忆更新**：更新与用户偏好相关的记忆，使 Agent 的回复更符合用户需求。 - **Agent 经验积累**：从任务执行经验中提取操作技巧、工具使用经验等核心内容，辅助后续任务的高效决策。 这使得 Agent 能够通过与世界的交互“越用越聪明”，实现自我进化。了解更多：[会话管理](./docs/en/concepts/08-session.md) ## 进阶阅读 ### 文档 欲了解更多详情，请访问我们的[完整文档](./docs/en/)。 ### 社区与团队 更多详情，请参见：**[关于我们](./docs/en/about/01-about-us.md)** ### 加入社区 OpenViking 仍处于早期阶段，有许多待改进和探索的地方。我们诚邀每一位对 AI Agent 技术充满热情的开发者： - 为我们点亮一颗宝贵的 **Star**，给予我们前行的动力。 - 访问我们的[**官网**](https://www.openviking.ai)了解我们传达的理念，并通过[**文档**](https://www.openviking.ai/docs)将其应用到您的项目中。感受它带来的变化，并向我们反馈您最真实的体验。 - 加入我们的社区，分享您的见解，帮助解答他人的疑问，共同营造开放互助的技术氛围： - 📱 **飞书群**：扫码加入 → [查看二维码](./docs/en/about/01-about-us.md#lark-group) - 💬 **微信群**：扫码添加助手 → [查看二维码](./docs/en/about/01-about-us.md#wechat-group) - 🎮 **Discord**：[加入 Discord 服务器](https://discord.com/invite/eHvx8E9XF3) - 🐦 **X (Twitter)**：[关注我们](https://x.com/openvikingai) - 成为一名 **Contributor**，无论是提交 Bug 修复还是贡献新功能，您的每一行代码都将成为 OpenViking 成长的重要基石。 让我们携手定义并构建 AI Agent 上下文管理的未来。旅程已经开启，期待您的参与！ ### Star 趋势 [](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left) ## 许可证 本项目基于 Apache License 2.0 授权 - 详情请参见 [LICENSE](./LICENSE) 文件。

标签：Agent内存, AI基础设施, DLL 劫持, DNS解析, LLM应用开发, OpenViking, RAG, 上下文感知, 上下文数据库, 中间件, 人工智能, 可视化界面, 向量数据库, 大语言模型, 层级上下文, 开源, 开源项目, 技能管理, 数据库, 文件系统范式, 日志审计, 智能体开发框架, 检索增强生成, 火山引擎, 用户模式Hook绕过, 知识管理, 自进化, 记忆系统, 资源管理, 逆向工具