diff --git a/README.md b/README.md index 862d23bf..1a40a85d 100644 --- a/README.md +++ b/README.md @@ -218,7 +218,7 @@ For complete model support, see [LiteLLM Providers Documentation](https://docs.l ### 3. Environment Configuration -#### Configuration Template +#### Server Configuration Template Create a configuration file `~/.openviking/ov.conf`, remove the comments before copy: @@ -253,7 +253,7 @@ Create a configuration file `~/.openviking/ov.conf`, remove the comments before > **Note**: For embedding models, currently `volcengine` (Doubao), `openai`, and `jina` providers are supported. For VLM models, we support three providers: `volcengine`, `openai`, and `litellm`. The `litellm` provider supports various models including Anthropic (Claude), DeepSeek, Gemini, Moonshot, Zhipu, DashScope, MiniMax, vLLM, Ollama, and more. -#### Configuration Examples +#### Server Configuration Examples 👇 Expand to see the configuration example for your model service: @@ -325,12 +325,12 @@ Create a configuration file `~/.openviking/ov.conf`, remove the comments before -#### Set Environment Variable +#### Set Server Configuration Environment Variable After creating the configuration file, set the environment variable to point to it (Linux/macOS): ```bash -export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf +export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # by default ``` On Windows, use one of the following: @@ -349,95 +349,75 @@ set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" > 💡 **Tip**: You can also place the configuration file in other locations, just specify the correct path in the environment variable. -### 4. Run Your First Example - -> 📝 **Prerequisite**: Ensure you have completed the environment configuration in the previous step. - -Now let's run a complete example to experience the core features of OpenViking. +#### CLI/Client Configuration Examples -#### Create Python Script +👇 Expand to see the configuration example for your CLI/Client: -Create `example.py`: +Example: ovcli.conf for visiting localhost server -```python -import openviking as ov +```json +{ + "url": "http://localhost:1933", + "timeout": 60.0, + "output": "table" +} +``` -# Initialize OpenViking client with data directory -client = ov.SyncOpenViking(path="./data") +After creating the configuration file, set the environment variable to point to it (Linux/macOS): -try: - # Initialize the client - client.initialize() +```bash +export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # by default +``` - # Add resource (supports URL, file, or directory) - add_result = client.add_resource( - path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md" - ) - root_uri = add_result['root_uri'] +On Windows, use one of the following: - # Explore the resource tree structure - ls_result = client.ls(root_uri) - print(f"Directory structure:\n{ls_result}\n") +PowerShell: - # Use glob to find markdown files - glob_result = client.glob(pattern="**/*.md", uri=root_uri) - if glob_result['matches']: - content = client.read(glob_result['matches'][0]) - print(f"Content preview: {content[:200]}...\n") +```powershell +$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf" +``` - # Wait for semantic processing to complete - print("Wait for semantic processing...") - client.wait_processed() +Command Prompt (cmd.exe): - # Get abstract and overview of the resource - abstract = client.abstract(root_uri) - overview = client.overview(root_uri) - print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n") +```bat +set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf" +``` - # Perform semantic search - results = client.find("what is openviking", target_uri=root_uri) - print("Search results:") - for r in results.resources: - print(f" {r.uri} (score: {r.score:.4f})") +### 4. Run Your First Example - # Close the client - client.close() +> 📝 **Prerequisite**: Ensure you have completed the configuration (ov.conf and ovcli.conf) in the previous step. -except Exception as e: - print(f"Error: {e}") -``` +Now let's run a complete example to experience the core features of OpenViking. -#### Run the Script +#### Launch Server ```bash -python example.py +openviking-server ``` -#### Expected Output +or you can run in background +```bash +nohup openviking-server > /data/log/openviking.log 2>&1 & ``` -Directory structure: -... - -Content preview: ... - -Wait for semantic processing... -Abstract: -... -Overview: -... +#### Run the CLI -Search results: - viking://resources/... (score: 0.8523) - ... +```bash +ov status +ov add-resource https://github.com/volcengine/OpenViking # --wait +ov ls viking://resources/ +ov tree viking://resources/volcengine -L 2 +# wait some time for semantic processing if not --wait +ov find "what is openviking" +ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh ``` Congratulations! You have successfully run OpenViking 🎉 --- -## Server Deployment +## Server Deployment Details For production environments, we recommend running OpenViking as a standalone HTTP service to provide persistent, high-performance context support for your AI Agents. @@ -446,7 +426,30 @@ To ensure optimal storage performance and data security, we recommend deploying 👉 **[View: Server Deployment & ECS Setup Guide](./docs/en/getting-started/03-quickstart-server.md)** ---- + +## OpenClaw Memory Plugin Details + +* Test Dataset: Effect testing based on LoCoMo10 (https://github.com/snap-research/locomo) long-range dialogues (1,540 cases in total after removing category5 without ground truth) +* Experimental Groups: Since users may not disable OpenClaw's native memory when using OpenViking, we added experimental groups with native memory enabled or disabled +* OpenViking Version: 0.1.18 +* Model: seed-2.0-code +* Evaluation Script: https://github.com/ZaynJarvis/openclaw-eval/tree/main + +| Experimental Group | Task Completion Rate | Cost: Input Tokens (Total) | +|----------|------------------|------------------| +| 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 | + +* Experimental Conclusions: +After integrating OpenViking: +- With native memory enabled: 43% improvement over original OpenClaw with 91% reduction in input token cost; 15% improvement over LanceDB with 92% reduction in input token cost. +- With native memory disabled: 49% improvement over original OpenClaw with 83% reduction in input token cost; 17% improvement over LanceDB with 96% reduction in input token cost. + +👉 **[View: OpenClaw Memory Plugin](examples/openclaw-memory-plugin/README.md)** + +-- ## Core Concepts @@ -535,77 +538,18 @@ OpenViking has a built-in memory self-iteration loop. At the end of each session This allows the Agent to get "smarter with use" through interactions with the world, achieving self-evolution. Learn more: [Session Management](./docs/en/concepts/08-session.md) ---- - -## Project Architecture - -The OpenViking project adopts a clear modular architecture design. The main directory structure is as follows: - -``` -OpenViking/ -├── openviking/ # Core source code directory -│ ├── core/ # Core modules: client, engine, filesystem, etc. -│ ├── models/ # Model integration: VLM and Embedding model encapsulation -│ ├── parse/ # Resource parsing: file parsing, detection, OVPack handling -│ ├── retrieve/ # Retrieval module: semantic retrieval, directory recursive retrieval -│ ├── storage/ # Storage layer: vector DB, filesystem queue, observers -│ ├── session/ # Session management: history, memory extraction -│ ├── message/ # Message processing: formatting, conversion -│ ├── prompts/ # Prompt templates: templates for various tasks -│ ├── utils/ # Utilities: config, helpers -│ └── bin/ # Command line tools -├── docs/ # Project documentation -│ ├── zh/ # Chinese documentation -│ ├── en/ # English documentation -│ └── images/ # Documentation images -├── examples/ # Usage examples -├── tests/ # Test cases -│ ├── client/ # Client tests -│ ├── engine/ # Engine tests -│ ├── integration/ # Integration tests -│ ├── session/ # Session tests -│ └── vectordb/ # Vector DB tests -├── src/ # C++ extensions (high-performance index and storage) -│ ├── common/ # Common components -│ ├── index/ # Index implementation -│ └── store/ # Storage implementation -├── third_party/ # Third-party dependencies -├── pyproject.toml # Python project configuration -├── setup.py # Setup script -├── LICENSE # Open source license -├── CONTRIBUTING.md # Contributing guide -├── AGENT.md # Agent development guide -└── README.md # Project readme -``` - - --- ## Advanced Reading -For more details, please visit our [Full Documentation](./docs/en/). - ---- - -## Community & Team +### Documentation -### About Us - -OpenViking is an open-source context database initiated and maintained by the **ByteDance Volcengine Viking Team**. - -The Viking team focuses on unstructured information processing and intelligent retrieval, accumulating rich commercial practical experience in context engineering technology: +For more details, please visit our [Full Documentation](./docs/en/). -- **2019**: VikingDB vector database supported large-scale use across all ByteDance businesses. -- **2023**: VikingDB sold on Volcengine public cloud. -- **2024**: Launched developer product matrix: VikingDB, Viking KnowledgeBase, Viking MemoryBase. -- **2025**: Created upper-layer application products like AI Search and Vaka Knowledge Assistant. -- **Oct 2025**: Open-sourced [MineContext](https://github.com/volcengine/MineContext), exploring proactive AI applications. -- **Jan 2026**: Open-sourced OpenViking, providing underlying context database support for AI Agents. +### Community & Team For more details, please see: **[About Us](./docs/en/about/01-about-us.md)** ---- - ### Join the Community OpenViking is still in its early stages, and there are many areas for improvement and exploration. We sincerely invite every developer passionate about AI Agent technology: @@ -621,14 +565,10 @@ OpenViking is still in its early stages, and there are many areas for improvemen Let's work together to define and build the future of AI Agent context management. The journey has begun, looking forward to your participation! ---- - ### Star Trend [![Star History Chart](https://api.star-history.com/svg?repos=volcengine/OpenViking&type=timeline&legend=top-left)](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left) ---- - ## License This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. diff --git a/README_CN.md b/README_CN.md index e53cfacf..44e367aa 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,10 +1,9 @@
- OpenViking -### OpenViking：为 AI Agent 而生的上下文数据库 +### OpenViking：AI 智能体的上下文数据库 [English](README.md) / 中文 @@ -17,73 +16,210 @@ [![][license-shield]][license-shield-link] [![][last-commit-shield]][last-commit-shield-link] -👋 加入我们的社区讨论 +👋 加入我们的社区 -📱 飞书群 · 微信群 · Discord · X +📱 飞书群 · 微信群 · Discord · X
--- -## 项目概览 +## 概述 + +### 智能体开发面临的挑战 -### Agent 开发面临的挑战 +在 AI 时代，数据丰富，但高质量的上下文却难以获得。在构建 AI 智能体时，开发者经常面临以下挑战： -在 AI 时代，数据易得，但高质量的上下文却难求。构建 AI Agent 时，开发者经常遇到这些挑战： -- **上下文碎片化**：记忆在代码里，资源在向量库，技能散落各处，难以统一管理 -- **所需上下文猛增**：Agent 的长程任务在每次执行时都会产出上下文，简单的截断或压缩会导致信息损失 -- **检索效果不佳**：传统 RAG 是平铺式存储，缺乏全局视野，难以理解信息的完整语境 -- **上下文不可观测**：传统 RAG 隐式的检索链路如同黑箱，出错时难以调试 -- **记忆迭代有限**：目前记忆只是用户记忆的记录，缺乏 Agent 相关的任务记忆 +- **上下文碎片化**：记忆存储在代码中，资源在向量数据库中，技能分散在各处，难以统一管理。 +- **上下文需求激增**：智能体的长运行任务在每次执行时都会产生上下文。简单的截断或压缩会导致信息丢失。 +- **检索效果不佳**：传统 RAG 使用扁平化存储，缺乏全局视图，难以理解信息的完整上下文。 +- **上下文不可观察**：传统 RAG 的隐式检索链像黑盒，出错时难以调试。 +- **记忆迭代有限**：当前记忆只是用户交互的记录，缺乏智能体相关的任务记忆。 ### OpenViking 解决方案 -OpenViking 是一个开源的、专为 AI Agent 设计的上下文数据库。 +**OpenViking** 是专为 AI 智能体设计的开源**上下文数据库**。 -我们旨在为 Agent 定义一套极简的上下文交互范式，让开发者彻底告别上下文管理的烦恼。 OpenViking 摒弃了传统 RAG 的碎片化向量存储模式，创新性地采用 **“文件系统范式”**，将 Agent 所需的记忆、资源和技能进行统一的结构化组织。 +我们的目标是为智能体定义一个极简的上下文交互范式，让开发者完全告别上下文管理的烦恼。OpenViking 抛弃了传统 RAG 的碎片化向量存储模型，创新性地采用**"文件系统范式"**来统一组织智能体所需的记忆、资源和技能。 -通过 OpenViking，开发者可以像管理本地文件一样构建 Agent 的大脑： +使用 OpenViking，开发者可以像管理本地文件一样构建智能体的大脑： -- **文件系统管理范式 → 解决碎片化问题**：基于文件系统范式，将记忆、资源、技能进行统一上下文管理 -- **分层上下文按需加载 → 降低 Token 消耗**：L0/L1/L2 三层结构，按需加载，大幅节省成本 -- **目录递归检索 → 提升检索效果**：支持原生文件系统检索方式，融合目录定位与语义搜索，实现递归式精准上下文获取 -- **可视化检索轨迹 → 上下文可观测**：支持可视化目录检索轨迹，让用户能够清晰观测问题根源并指导检索逻辑优化 -- **会话自动管理 → 上下文自迭代**：自动压缩对话中的内容、资源引用、工具调用等信息，提取长期记忆，让 Agent 越用越聪明 +- **文件系统管理范式** → **解决碎片化**：基于文件系统范式统一管理记忆、资源和技能。 +- **分层上下文加载** → **降低 Token 消耗**：L0/L1/L2 三层结构，按需加载，显著节省成本。 +- **目录递归检索** → **提升检索效果**：支持原生文件系统检索方式，结合目录定位和语义搜索，实现递归精准的上下文获取。 +- **可视化检索轨迹** → **可观察上下文**：支持目录检索轨迹可视化，让用户清晰观察问题根源，指导检索逻辑优化。 +- **自动会话管理** → **上下文自迭代**：自动压缩对话中的内容、资源引用、工具调用等，提取长期记忆，让智能体越用越聪明。 --- -## 快速上手 +## 快速开始 -### 前置要求 +### 前置条件 在开始使用 OpenViking 之前，请确保您的环境满足以下要求： - **Python 版本**：3.10 或更高版本 - **操作系统**：Linux、macOS、Windows -- **网络连接**：需要稳定的网络连接（用于下载依赖包和访问模型服务） +- **网络连接**：需要稳定的网络连接（用于下载依赖和访问模型服务） -### 1. 安装 OpenViking +### 1. 安装 + +#### Python 包 ```bash pip install openviking ``` +#### Rust CLI（可选） + +```bash +curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash +``` + +或从源码构建： + +```bash +cargo install --git https://github.com/volcengine/OpenViking ov_cli +``` + ### 2. 模型准备 OpenViking 需要以下模型能力： - **VLM 模型**：用于图像和内容理解 - **Embedding 模型**：用于向量化和语义检索 -OpenViking 支持多种模型服务： -- **OpenAI 模型**：支持 GPT-4V 等 VLM 模型和 OpenAI Embedding 模型 -- **火山引擎（豆包模型）**：推荐使用，成本低、性能好，新用户有免费额度。如需购买和开通，请参考：[火山引擎购买指南](./docs/zh/guides/02-volcengine-purchase-guide.md) -- **其他自定义模型服务**：支持兼容 OpenAI API 格式的模型服务 +#### 支持的 VLM 提供商 + +OpenViking 支持三种 VLM 提供商： + +| 提供商 | 描述 | 获取 API Key | +|----------|-------------|-------------| +| `volcengine` | 火山引擎豆包模型 | [Volcengine 控制台](https://console.volcengine.com/ark) | +| `openai` | OpenAI 官方 API | [OpenAI 平台](https://platform.openai.com) | +| `litellm` | 统一调用多种第三方模型 (Anthropic, DeepSeek, Gemini, vLLM, Ollama 等) | 参见 [LiteLLM 提供商](https://docs.litellm.ai/docs/providers) | + +> 💡 **提示**： +> - `litellm` 支持通过统一接口调用多种模型，model 字段需遵循 [LiteLLM 格式规范](https://docs.litellm.ai/docs/providers) +> - 系统自动检测常见模型（如 `claude-*`, `deepseek-*`, `gemini-*`, `hosted_vllm/*`, `ollama/*` 等），其他模型需按 LiteLLM 格式填写完整前缀 + +#### 提供商特定说明 + +
+Volcengine (豆包) + +Volcengine 支持模型名称和端点 ID。为简单起见，建议使用模型名称： + +```json +{ + "vlm": { + "provider": "volcengine", + "model": "doubao-seed-1-6-240615", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3" + } +} +``` + +您也可以使用端点 ID（可在 [Volcengine ARK 控制台](https://console.volcengine.com/ark) 中找到）： + +```json +{ + "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： + +```json +{ + "vlm": { + "provider": "openai", + "model": "gpt-4o", + "api_key": "your-api-key", + "api_base": "https://api.openai.com/v1" + } +} +``` + +您也可以使用自定义的 OpenAI 兼容端点： + +```json +{ + "vlm": { + "provider": "openai", + "model": "gpt-4o", + "api_key": "your-api-key", + "api_base": "https://your-custom-endpoint.com/v1" + } +} +``` + +
+ +
+LiteLLM (Anthropic, DeepSeek, Gemini, vLLM, Ollama 等) + +LiteLLM 提供对各种模型的统一访问。`model` 字段应遵循 LiteLLM 的命名约定： + +```json +{ + "vlm": { + "provider": "litellm", + "model": "claude-3-5-sonnet-20240620", + "api_key": "your-anthropic-api-key" + } +} +``` + +**常见模型格式：** + +| 提供商 | 模型示例 | 说明 | +|----------|---------------|-------| +| Anthropic | `claude-3-5-sonnet-20240620` | 自动检测，使用 `ANTHROPIC_API_KEY` | +| DeepSeek | `deepseek-chat` | 自动检测，使用 `DEEPSEEK_API_KEY` | +| Gemini | `gemini-pro` | 自动检测，使用 `GEMINI_API_KEY` | +| OpenRouter | `openrouter/openai/gpt-4o` | 需要完整前缀 | +| vLLM | `hosted_vllm/llama-3.1-8b` | 设置 `api_base` 为 vLLM 服务器 | +| Ollama | `ollama/llama3.1` | 设置 `api_base` 为 Ollama 服务器 | + +**本地模型 (vLLM / Ollama)：** + +```bash + +# 启动 Ollama +ollama serve +``` + +```json +// Ollama +{ + "vlm": { + "provider": "litellm", + "model": "ollama/llama3.1", + "api_base": "http://localhost:11434" + } +} +``` + +完整的模型支持，请参见 [LiteLLM 提供商文档](https://docs.litellm.ai/docs/providers)。 + +
-### 3. 配置环境 +### 3. 环境配置 -#### 配置文件模版 +#### 服务器配置模板 -创建配置文件 `~/.openviking/ov.conf`： +创建配置文件 `~/.openviking/ov.conf`，复制前请删除注释： ```json { @@ -92,34 +228,36 @@ OpenViking 支持多种模型服务： }, "log": { "level": "INFO", - "output": "stdout" // 可配置为 "stdout" or "file" + "output": "stdout" // 日志输出："stdout" 或 "file" }, "embedding": { "dense": { - "api_base" : "", // API 服务端点地址 - "api_key" : "", // 模型服务的 API 密钥 - "provider" : "", // 提供商类型（volcengine、openai 或 jina） + "api_base" : "", // API 端点地址 + "api_key" : "", // 模型服务 API Key + "provider" : "", // 提供商类型："volcengine" 或 "openai"（当前支持） "dimension": 1024, // 向量维度 "model" : "" // Embedding 模型名称（如 doubao-embedding-vision-250615 或 text-embedding-3-large） }, - "max_concurrent": 10 // Embedding 最大并发请求数（默认：10） + "max_concurrent": 10 // 最大并发 embedding 请求（默认：10） }, "vlm": { - "api_base" : "", // API 服务端点地址 - "api_key" : "", // 模型服务的 API 密钥 - "provider" : "", // 提供商类型（volcengine、openai 或 jina） + "api_base" : "", // API 端点地址 + "api_key" : "", // 模型服务 API Key + "provider" : "", // 提供商类型 (volcengine, openai, deepseek, anthropic 等) "model" : "", // VLM 模型名称（如 doubao-seed-1-8-251228 或 gpt-4-vision-preview） - "max_concurrent": 100 // 语义处理最大并发 LLM 调用数（默认：100） + "max_concurrent": 100 // 语义处理的最大并发 LLM 调用（默认：100） } } ``` -#### 配置示例 +> **注意**：对于 embedding 模型，目前支持 `volcengine`（豆包）、`openai` 和 `jina` 提供商。对于 VLM 模型，我们支持三种提供商：`volcengine`、`openai` 和 `litellm`。``litellm` 提供商支持各种模型，包括 Anthropic (Claude)、DeepSeek、Gemini、Moonshot、Zhipu、DashScope、MiniMax、vLLM、Ollama 等。 + +#### 服务器配置示例 -👇 根据你使用的模型服务，展开查看对应的配置示例： +👇 展开查看您的模型服务的配置示例：
-示例 1：使用火山引擎（豆包模型） +示例 1：使用 Volcengine（豆包模型） ```json { @@ -128,7 +266,7 @@ OpenViking 支持多种模型服务： }, "log": { "level": "INFO", - "output": "stdout" // 可配置为 "stdout" or "file" + "output": "stdout" // 日志输出："stdout" 或 "file" }, "embedding": { "dense": { @@ -162,7 +300,7 @@ OpenViking 支持多种模型服务： }, "log": { "level": "INFO", - "output": "stdout" // 可配置为 "stdout" or "file" + "output": "stdout" // 日志输出："stdout" 或 "file" }, "embedding": { "dense": { @@ -186,15 +324,15 @@ OpenViking 支持多种模型服务：
-#### 设置环境变量 +#### 设置服务器配置环境变量 -创建好配置文件后，设置环境变量指向配置文件（Linux/macOS）： +创建配置文件后，设置环境变量指向它（Linux/macOS）： ```bash -export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf +export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # 默认值 ``` -Windows 下可使用以下方式之一： +在 Windows 上，使用以下任一方式： PowerShell： @@ -202,120 +340,129 @@ PowerShell： $env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf" ``` -命令提示符（cmd.exe）： +命令提示符 (cmd.exe)： ```bat set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" ``` -> 💡 **提示**：你也可以将配置文件放在其他位置，只需在环境变量中指定正确的路径即可。 +> 💡 **提示**：您也可以将配置文件放在其他位置，只需在环境变量中指定正确路径。 -### 4. 运行你的第一个示例 +#### CLI/客户端配置示例 -> 📝 **前提**：请确保已完成上一步的环境配置 +👇 展开查看您的 CLI/客户端的配置示例： -现在让我们运行一个完整的示例，体验 OpenViking 的核心功能。 +示例：用于访问本地服务器的 ovcli.conf -#### 创建 Python 脚本 +```json +{ + "url": "http://localhost:1933", + "timeout": 60.0, + "output": "table" +} +``` -创建 `example.py`： +创建配置文件后，设置环境变量指向它（Linux/macOS）： -```python -import openviking as ov +```bash +export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # 默认值 +``` -# Initialize OpenViking client with data directory -client = ov.SyncOpenViking(path="./data") +在 Windows 上，使用以下任一方式： -try: - # Initialize the client - client.initialize() +PowerShell： - # Add resource (supports URL, file, or directory) - add_result = client.add_resource( - path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md" - ) - root_uri = add_result['root_uri'] +```powershell +$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf" +``` - # Explore the resource tree structure - ls_result = client.ls(root_uri) - print(f"Directory structure:\n{ls_result}\n") +命令提示符 (cmd.exe)： - # Use glob to find markdown files - glob_result = client.glob(pattern="**/*.md", uri=root_uri) - if glob_result['matches']: - content = client.read(glob_result['matches'][0]) - print(f"Content preview: {content[:200]}...\n") +```bat +set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf" +``` - # Wait for semantic processing to complete - print("Wait for semantic processing...") - client.wait_processed() +### 4. 运行您的第一个示例 - # Get abstract and overview of the resource - abstract = client.abstract(root_uri) - overview = client.overview(root_uri) - print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n") +> 📝 **前置条件**：确保您已完成上一步的配置（ov.conf 和 ovcli.conf）。 - # Perform semantic search - results = client.find("what is openviking", target_uri=root_uri) - print("Search results:") - for r in results.resources: - print(f" {r.uri} (score: {r.score:.4f})") +现在让我们运行一个完整的示例，体验 OpenViking 的核心功能。 - # Close the client - client.close() +#### 启动服务器 -except Exception as e: - print(f"Error: {e}") +```bash +openviking-server ``` -#### 运行脚本 +或者您可以在后台运行 ```bash -python example.py +nohup openviking-server > /data/log/openviking.log 2>&1 & ``` -#### 预期输出 +#### 运行 CLI +```bash +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 ``` -Directory structure: -... -Content preview: ... +恭喜！您已成功运行 OpenViking 🎉 + +--- -Wait for semantic processing... -Abstract: -... +## 服务器部署详情 -Overview: -... +对于生产环境，我们建议将 OpenViking 作为独立的 HTTP 服务运行，为您的 AI 智能体提供持久、高性能的上下文支持。 -Search results: - viking://resources/... (score: 0.8523) - ... -``` +🚀 **在云端部署 OpenViking**： +为确保最佳的存储性能和数据安全，我们建议在 **火山引擎弹性计算服务 (ECS)** 上使用 **veLinux** 操作系统进行部署。我们准备了详细的分步指南，帮助您快速上手。 -恭喜！你已成功运行 OpenViking 🎉 +👉 **[查看：服务器部署与 ECS 设置指南](./docs/en/getting-started/03-quickstart-server.md)** ---- -## 服务端部署 +## OpenClaw 记忆插件详情 + +* 测试集：基于 LoCoMo10(https://github.com/snap-research/locomo) 的长程对话进行效果测试（去除无真值的 category5 后，共 1540 条 case） +* 实验组：因用户在使用 OpenViking 时可能不关闭 OpenClaw 原生记忆，所以增加是否开关原生记忆的实验组 +* OpenViking 版本：0.1.18 +* 模型：seed-2.0-code +* 评测脚本：https://github.com/ZaynJarvis/openclaw-eval/tree/main -在生产环境中，我们推荐将 OpenViking 作为独立 HTTP 服务运行，以便为您的 AI Agent 提供持久化、高性能的上下文支持。 +| 实验组 | 任务完成率 | 成本：输入 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**： -为了确保存储性能与数据安全，我们推荐使用 **火山引擎云服务器 (ECS)** 结合 veLinux 系统进行部署。我们准备了详细的测试教程，点击下方链接即可快速上手。 +* 实验结论： +结合 OpenViking 后，若仍开启原生记忆，效果在原 OpenClaw 上提升 43%，输入 token 成本降低 91%；在 LanceDB 上效果提升 15%，输入 token 降低 92%。若关闭原生记忆，效果在原 OpenClaw 上提升 49%，输入 token 成本降低 83%；在 LanceDB 上效果提升 17%，输入 token 降低 96%。 -👉 **[点击查看：服务端部署与ECS测试文档](./docs/zh/getting-started/03-quickstart-server.md)** +👉 **[查看：OpenClaw 记忆插件](examples/openclaw-memory-plugin/README.md)** -## 核心理念 +## VikingBot 部署详情 -在成功运行第一个示例后，让我们深入了解 OpenViking 的设计理念。这五大核心理念与前面提到的解决方案一一对应，共同构建了一个完整的上下文管理体系： +OpenViking 有一个类似 nanobot 的机器人用于交互工作，现已可用。 -### 1. 文件系统管理范式 → 解决碎片化问题 +👉 **[查看：使用 VikingBot 部署服务器](bot/README.md)** -我们不再将上下文视为扁平的文本切片，而是将其统一抽象并组织于一个虚拟文件系统中。无论是记忆、资源还是能力，都会被映射到 `viking://` 协议下的虚拟目录，拥有唯一的 URI。 +-- -这种范式赋予了 Agent 前所未有的上下文操控能力，使其能像开发者一样，通过 `ls`、`find` 等标准指令来精确、确定性地定位、浏览和操作信息，让上下文的管理从模糊的语义匹配演变为直观、可追溯的"文件操作"。了解更多：[Viking URI](./docs/zh/concepts/04-viking-uri.md) | [上下文类型](./docs/zh/concepts/02-context-types.md) +## 核心概念 + +运行第一个示例后，让我们深入了解 OpenViking 的设计理念。这五个核心概念与前面提到的解决方案一一对应，共同构建了一个完整的上下文管理系统： + +### 1. 文件系统管理范式 → 解决碎片化 + +我们不再将上下文视为扁平的文本切片，而是将它们统一到一个抽象的虚拟文件系统中。无论是记忆、资源还是能力，都映射到 `viking://` 协议下的虚拟目录中，每个都有唯一的 URI。 + +这种范式赋予智能体前所未有的上下文操作能力，使它们能够像开发者一样，通过 `ls` 和 `find` 等标准命令精确、确定地定位、浏览和操作信息。这将上下文管理从模糊的语义匹配转变为直观、可追踪的"文件操作"。了解更多：[Viking URI](./docs/en/concepts/04-viking-uri.md) | [上下文类型](./docs/en/concepts/02-context-types.md) ``` viking:// @@ -329,10 +476,10 @@ viking:// ├── user/ # 用户：个人偏好、习惯等 │ └── memories/ │ ├── preferences/ -│ │ ├── 写作风格 -│ │ └── 编程习惯 +│ │ ├── writing_style +│ │ └── coding_habits │ └── ... -└── agent/ # Agent：技能、指令、任务记忆等 +└── agent/ # 智能体：技能、指令、任务记忆等 ├── skills/ │ ├── search_code │ ├── analyze_data @@ -341,19 +488,19 @@ viking:// └── instructions/ ``` -### 2. 分层上下文按需加载 → 降低 Token 消耗 +### 2. 分层上下文加载 → 降低 Token 消耗 -将海量上下文一次性塞入提示词，不仅成本高昂，更容易超出模型窗口并引入噪声。OpenViking 在上下文写入时便自动将其处理为三个层级： -- **L0 (摘要)**：一句话概括，用于快速检索和识别 -- **L1 (概述)**：包含核心信息和使用场景，供 Agent 在规划阶段进行决策 -- **L2 (详情)**：完整的原始数据，供 Agent 在确有必要时深入读取 +一次性将大量上下文塞入提示不仅昂贵，而且容易超出模型窗口并引入噪声。OpenViking 在写入时自动将上下文处理为三个级别： +- **L0 (摘要)**：一句话摘要，用于快速检索和识别。 +- **L1 (概览)**：包含核心信息和使用场景，用于智能体在规划阶段的决策。 +- **L2 (详情)**：完整的原始数据，供智能体在绝对必要时深度阅读。 -了解更多：[上下文分层](./docs/zh/concepts/03-context-layers.md) +了解更多：[上下文分层](./docs/en/concepts/03-context-layers.md) ``` viking://resources/my_project/ -├── .abstract # L0 层：摘要（~100 tokens）- 快速判断相关性 -├── .overview # L1 层：概览（~2k tokens）- 了解结构和要点 +├── .abstract # L0 层：摘要（~100 tokens）- 快速相关性检查 +├── .overview # L1 层：概览（~2k tokens）- 理解结构和关键点 ├── docs/ │ ├── .abstract # 每个目录都有对应的 L0/L1 层 │ ├── .overview @@ -369,138 +516,75 @@ viking://resources/my_project/ ### 3. 目录递归检索 → 提升检索效果 -单一的向量检索难以应对复杂的查询意图。OpenViking 设计了一套创新的**目录递归检索策略**，深度融合多种检索方式： +单一向量检索难以应对复杂的查询意图。OpenViking 设计了创新的**目录递归检索策略**，深度集成多种检索方法： -1. **意图分析**：通过意图分析生成多个检索条件 -2. **初始定位**：利用向量检索快速定位初始切片所在的高分目录 -3. **精细探索**：在该目录下进行二次检索，并将高分结果更新至候选集合 -4. **递归下探**：若目录下仍存在子目录，则逐层递归重复上述二次检索步骤 -5. **结果汇总**：最终拿到最相关上下文返回 +1. **意图分析**：通过意图分析生成多个检索条件。 +2. **初始定位**：使用向量检索快速定位初始切片所在的高分目录。 +3. **精细探索**：在该目录内进行二次检索，并将高分结果更新到候选集。 +4. **递归深入**：如果存在子目录，则逐层递归重复二次检索步骤。 +5. **结果聚合**：最终获取最相关的上下文返回。 -这种"先锁定高分目录、再精细探索内容"的策略，不仅能找到语义最匹配的片段，更能理解信息所在的完整语境，从而提升检索的全局性与准确性。了解更多：[检索机制](./docs/zh/concepts/07-retrieval.md) +这种"先锁定高分目录，再精细化内容探索"的策略不仅找到语义最佳匹配的片段，还能理解信息所在的完整上下文，从而提高检索的全局性和准确性。了解更多：[检索机制](./docs/en/concepts/07-retrieval.md) -### 4. 可视化检索轨迹 → 上下文可观测 +### 4. 可视化检索轨迹 → 可观察上下文 -OpenViking 的组织方式采用层次化虚拟文件系统结构，所有上下文均以统一格式整合且每个条目对应唯一 URI（如 `viking://` 路径），打破传统扁平黑箱式管理模式，层次分明易于理解。 +OpenViking 的组织采用分层虚拟文件系统结构。所有上下文以统一格式集成，每个条目对应一个唯一的 URI（如 `viking://` 路径），打破了传统的扁平黑盒管理模式，具有清晰易懂的层次结构。 -检索过程采用目录递归策略，每次检索的目录浏览、文件定位轨迹均被完整留存，能够清晰观测问题根源并指导检索逻辑优化。了解更多：[检索机制](./docs/zh/concepts/07-retrieval.md) +检索过程采用目录递归策略。每次检索的目录浏览和文件定位轨迹被完整保留，让用户能够清晰观察问题的根源，指导检索逻辑的优化。了解更多：[检索机制](./docs/en/concepts/07-retrieval.md) -### 5. 会话自动管理 → 上下文自迭代 +### 5. 自动会话管理 → 上下文自迭代 -OpenViking 内置了记忆自迭代闭环。在每次会话结束时，开发者可以主动触发记忆提取机制，系统会异步分析任务执行结果与用户反馈，并自动更新至 User 和 Agent 的记忆目录下。 +OpenViking 内置了记忆自迭代循环。在每个会话结束时，开发者可以主动触发记忆提取机制。系统将异步分析任务执行结果和用户反馈，并自动更新到用户和智能体记忆目录。 -- **用户记忆更新**：更新用户偏好相关记忆，使 Agent 回应更贴合用户需求 -- **Agent 经验积累**：从任务执行经验中提取操作技巧、工具使用经验等核心内容，助力后续任务高效决策 +- **用户记忆更新**：更新与用户偏好相关的记忆，使智能体响应更好地适应用户需求。 +- **智能体经验积累**：从任务执行经验中提取操作技巧和工具使用经验等核心内容，辅助后续任务的高效决策。 -让 Agent 在与世界的交互中"越用越聪明"，实现自我进化。了解更多：[会话管理](./docs/zh/concepts/08-session.md) +这使得智能体能够通过与世界的交互"越用越聪明"，实现自我进化。了解更多：[会话管理](./docs/en/concepts/08-session.md) --- -## 项目架构 +## 深入阅读 -OpenViking 项目采用清晰的模块化架构设计，主要目录结构如下： +### 文档 -``` -OpenViking/ -├── openviking/ # 核心源代码目录 -│ ├── core/ # 核心模块：客户端、引擎、文件系统等核心功能 -│ ├── models/ # 模型集成：VLM 和 Embedding 模型的封装 -│ ├── parse/ # 资源解析：文件解析、资源检测、OVPack 格式处理 -│ ├── retrieve/ # 检索模块：语义检索、目录递归检索等 -│ ├── storage/ # 存储层：向量数据库、文件系统队列、观察者模式 -│ ├── session/ # 会话管理：对话历史、记忆提取等 -│ ├── message/ # 消息处理：消息格式化、转换等 -│ ├── prompts/ # 提示词模板：各类任务的提示词模板 -│ ├── utils/ # 工具函数：配置管理、辅助工具等 -│ └── bin/ # 命令行工具 -├── docs/ # 项目文档 -│ ├── zh/ # 中文文档 -│ ├── en/ # 英文文档 -│ └── images/ # 文档图片资源 -├── examples/ # 使用示例 -├── tests/ # 测试用例 -│ ├── client/ # 客户端测试 -│ ├── engine/ # 引擎测试 -│ ├── integration/ # 集成测试 -│ ├── session/ # 会话测试 -│ └── vectordb/ # 向量数据库测试 -├── src/ # C++ 扩展模块（高性能索引和存储） -│ ├── common/ # 公共组件 -│ ├── index/ # 索引实现 -│ └── store/ # 存储实现 -├── third_party/ # 第三方依赖 -├── pyproject.toml # Python 项目配置文件 -├── setup.py # 安装脚本 -├── LICENSE # 开源协议 -├── CONTRIBUTING.md # 贡献指南 -├── AGENT.md # Agent 开发指南 -└── README.md # 项目说明文档 -``` +更多详情，请访问我们的[完整文档](./docs/en/)。 +### 社区与团队 ---- - -## 进阶阅读 - -如需了解更多详细信息，请访问我们的[完整文档](./docs/zh/)。 - ---- - -## 社区与团队 - -### 关于我们 - -OpenViking 是由**字节跳动火山引擎 Viking 团队**发起并维护的开源项目。 - -Viking 团队专注于非结构化信息处理和智能检索领域，在上下文工程技术方面积累了丰富的商业化实践经验： - -- **2019 年**：VikingDB 向量数据库支撑字节内部全业务大规模使用 -- **2023 年**：VikingDB 在火山引擎公有云售卖 -- **2024 年**：推出面向开发者的产品矩阵：VikingDB 向量数据库、Viking 知识库、Viking 记忆库 -- **2025 年**：打造 AI 搜索、vaka 知识助手等上层应用产品 -- **2025 年 10 月**：开源 [MineContext](https://github.com/volcengine/MineContext)，主动式 AI 应用探索 -- **2026 年 1 月**：开源 OpenViking，为 AI Agent 提供底层上下文数据库支撑 - -更多详细信息请查看：**[关于我们](./docs/zh/about/01-about-us.md)** - ---- +更多详情，请参见：**[关于我们](./docs/en/about/01-about-us.md)** ### 加入社区 -OpenViking 目前还处于早期阶段，有许多需要完善和探索的地方。在此，我们诚挚地邀请每一位对 AI Agent 技术充满热情的开发者： +OpenViking 仍处于早期阶段，有许多改进和探索的空间。我们真诚邀请每一位对 AI 智能体技术充满热情的开发者： -- 为我们点亮一颗宝贵的 **Star**，给予我们前行的动力 -- 访问我们的 [**网站**](https://www.openviking.ai)，了解我们传递的理念，并通过[**文档**](https://www.openviking.ai/docs)使用它，在您的项目中感受它带来的改变，并向我们反馈最真实的体验 -- 加入我们的社区，分享您的洞见，帮助解答他人的疑问，共同营造一个开放、互助的技术氛围： - - 📱 **飞书群**：扫描二维码加入 → [查看二维码](./docs/zh/about/01-about-us.md#飞书群) - - 💬 **微信群**：添加小助手微信，备注「OpenViking」→ [查看二维码](./docs/zh/about/01-about-us.md#微信群) +- 为我们点亮一颗珍贵的 **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) -- 成为我们的**贡献者**，无论是提交一个 Bug 修复，还是贡献一个新功能，您的每一行代码都将是 OpenViking 成长的重要基石 + - 🐦 **X (Twitter)**：[关注我们](https://x.com/openvikingai) +- 成为**贡献者**，无论是提交错误修复还是贡献新功能，您的每一行代码都将是 OpenViking 成长的重要基石。 -让我们一起，共同定义和构建 AI Agent 上下文管理的未来。旅程已经开始，期待您的加入！ - ---- +让我们共同努力，定义和构建 AI 智能体上下文管理的未来。旅程已经开始，期待您的参与！ ### Star 趋势 [![Star History Chart](https://api.star-history.com/svg?repos=volcengine/OpenViking&type=timeline&legend=top-left)](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left) ---- - ## 许可证 -本项目采用 Apache License 2.0 开源协议 - 详见 [LICENSE](./LICENSE) +本项目采用 Apache License 2.0 许可证 - 详情请参见 [LICENSE](./LICENSE) 文件。 - + [release-shield]: https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff&labelColor=black&logo=github&style=flat-square [release-link]: https://github.com/volcengine/OpenViking/releases [license-shield]: https://img.shields.io/badge/license-apache%202.0-white?labelColor=black&style=flat-square [license-shield-link]: https://github.com/volcengine/OpenViking/blob/main/LICENSE [last-commit-shield]: https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square -[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commits/main +[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commcommits/main [github-stars-shield]: https://img.shields.io/github/stars/volcengine/OpenViking?labelColor&style=flat-square&color=ffcb47 [github-stars-link]: https://github.com/volcengine/OpenViking [github-issues-shield]: https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black&style=flat-square&color=ff80eb