**OpenViking** 是专为 AI 智能体（Agent）打造的上下文数据库，主要适用于多 Agent 协同、长期记忆管理、复杂任务执行等场景。该数据库采用 `viking://`文件系统范式，将智能体的**记忆、资源与技能**进行统一组织管理，依托分层加载机制按需供给上下文，在减少 Token 消耗的同时提升运行效率，结合目录式检索优化信息召回效果。功能上，OpenViking 支持**多租户、多用户及多 Agent 隔离**，且能在会话结束后自动沉淀长期记忆，实现智能体能力的持续积累与自我优化，既有效降低开发者的上下文管理成本，也能显著提升 OpenClaw 等智能体的整体运行表现。方舟 Agent Plan 支持在 OpenViking 中使用，可参考本文进行配置及使用。 :::warning OpenViking 工具处于快速迭代阶段，本文使用的版本为 **0.2.13**，如果实际使用与以下步骤存在差异，可参见 [OpenViking：AI 智能体的上下文数据库](https://github.com/volcengine/OpenViking/blob/main/README_CN.md)。 ::: # 核心配置需要获取 Agent Plan 支持的专属 Base URL、专属 API Key及模型配置，才能正常使用并抵扣套餐额度。 ## 专属 Base URL 兼容 OpenAI 接口协议工具：`https://ark.cn-beijing.volces.com/api/plan/v3`（目前还不支持 Responses API，建议使用 Chat API。） :::warning 请勿使用 `https://ark.cn-beijing.volces.com/api/v3` ，接入会产生额外费用。 ::: ## 专属 API Key [获取专属 API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan) ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d11b0376e5f24d2f86e634aebcc91cb1~tplv-goo7wpa0wc-image.image =689x) :::warning Agent Plan 专属 API Key 与火山方舟平台的 API Key 不同，请勿混用。 ::: ## 模型配置 ### 语言模型 Agent Plan 支持的语言模型及配置方式如下： ```mixin-react return ( ); ``` ### 向量化模型支持的向量化模型：`doubao-embedding-vision`（对应模型 [doubao-embedding-vision-251215](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-embedding-vision)） :::warning * 向量化模型的 Base URL 请参见[配置向量化模型](/docs/82379/2375464)。 * 建议固定使用同一版本的向量化模型，请勿混用不同版本。 * 向量化模型只支持在配置文件中指定 Model Name，不支持通过 Auto 及控制台切换使用。 ::: # 前置操作进入 [Agent Plan 控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=agentPlan)，按需购买套餐。套餐介绍参见[套餐概览](/docs/82379/2366394)。 # 安装 OpenViking ## 前提条件 * 已安装 [Python 3.10 或更高版本](https://wiki.python.org/moin/BeginnersGuide/Download)。 * 已安装 [Go 1.22 或更高版本](https://golang.google.cn/dl/)。 * 已安装 C++ 编译器，且 GCC 9+ 或 Clang 11+。 :::tip 通过命令`clang++ --version`和`clang++ -std=c++17 -E -x c++ - < /dev/null`检查 C++编译器支持情况。 ::: ## 安装步骤执行以下命令安装 OpenViking。 ```Bash pip install openviking --upgrade --force-reinstall ``` 安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。 ```Bash openviking --version ``` # 配置 OpenViking 1. 创建配置文件`~/.openviking/ov.conf`，配置信息如下。需要修改的配置信息如下： * `storage.workspace`：替换为实际的工作空间路径。 * `embedding`：配置向量化模型，用于向量化和语义检索。 * `embedding.dense.model`：支持的 Embedding 模型 `doubao-embedding-vision`。 * `embedding.dense.api_key`：替换为您自己的[专属 API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan)。 * `vlm`：配置语言模型，用于图像和内容理解。 * `vlm.model`：支持的语言模型，具体参见[语言模型](/docs/82379/2373745#47a3a76a)。 * `vlm.api_key`：替换为您自己的[专属 API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan)。 ```JSON { "storage": { "workspace": "/home/your-name/openviking_workspace" }, "log": { "level": "INFO", "output": "stdout" }, "embedding": { "dense": { "backend": "volcengine", "api_key": "", "model": "doubao-embedding-vision", "api_base": "https://ark.cn-beijing.volces.com/api/plan/v3", "dimension": 1024, "input": "multimodal" } }, "vlm": { "backend": "volcengine", "api_key": "", "model": "doubao-seed-2.0-pro", "api_base": "https://ark.cn-beijing.volces.com/api/plan/v3", "temperature": 0.1, "max_retries": 3 } } ``` 2. 设置服务器配置环境变量。根据系统环境选择对应的方式设置环境变量。 :::tip 如果配置文件放在其他位置，需要在环境变量中指定对应的文件路径。 ::: ```mixin-react return ( ); ``` # 开始使用 OpenViking 1. 创建 Python 文件`example.py`，代码内容如下。 ```Python import openviking as ov # Initialize OpenViking client with data directory client = ov.OpenViking(path="./data") try: # Initialize the client client.initialize() # 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'] # Explore the resource tree structure ls_result = client.ls(root_uri) print(f"Directory structure:\n{ls_result}\n") # 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") # Wait for semantic processing to complete print("Wait for semantic processing...") client.wait_processed() # 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") # 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})") # Close the client client.close() except Exception as e: print(f"Error: {e}") ``` 2. 执行命令`python example.py`，输出如下内容则说明 OpenViking 已成功运行。 ```Plain Directory structure: ... Content preview: ... Wait for semantic processing... Abstract: ... Overview: ... Search results: viking://resources/... (score: 0.8523) ... ``` # CLI 服务端配置并使用 OpenViking 如果需要将 OpenViking 作为独立的 HTTP 服务运行，然后从任意客户端连接，请参考以下步骤进行配置。 ## 前提条件已安装并完成配置 OpenViking，具体参见[安装和配置 OpenViking](/docs/82379/2373745#4cc843e2)、[配置工具](/docs/82379/2373745#ceac2da4)。 ## 启动服务执行以下命令启动服务。 ```Bash openviking-server ``` 启动完成后，在新的命令行界面执行以下命令验证服务启动是否成功，若返回`"status":"ok"`则表示启动成功。 ```Bash curl http://localhost:1933/health ``` ## 使用 CLI 连接 1. 创建 CLI 连接配置文件 `~/.openviking/ovcli.conf`，配置信息如下。其中``需替换为您自己的 [API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan)。 ```JSON { "url": "http://localhost:1933", "api_key": "", "output": "table" } ``` 2. 在新的命令行界面执行以下 CLI 命令。 ```Bash # Check system health openviking observer system # Add a resource to memory openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md # List all synchronized resources openviking ls viking://resources # Query openviking find "what is openviking" ``` ## 使用 curl 连接启动服务后，也可以在命令行界面使用 curl 命令连接 OpenViking。 ```Bash # Add a resource curl -X POST http://localhost:1933/api/v1/resources \ -H "Content-Type: application/json" \ -d '{"path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"}' # List resources curl "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/" # Semantic search curl -X POST http://localhost:1933/api/v1/search/find \ -H "Content-Type: application/json" \ -d '{"query": "what is openviking"}' ``` # 在 OpenClaw 配置 OpenViking 记忆功能通过 OpenViking 为 OpenClaw 提供长效记忆能力，配置完成后，OpenClaw 将自动记住对话中的重要信息，并在回复前回忆相关内容。 ## 前提条件已完成 OpenClaw 的安装与配置，具体参见[安装和配置 OpenClaw](/docs/82379/2373742#b51c87f8)、[配置工具](/docs/82379/2373742#48c0b1ea)。 ## 安装及配置具体步骤参见[为 OpenClaw 安装 OpenViking 记忆功能](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-ZH.md)。安装完成后，编辑配置文件`~/.openviking/ov.conf`，使用 Agent Plan 支持的模型。配置信息可参见[配置工具](/docs/82379/2373745#ceac2da4)。