OpenViking 快速开始：从安装到 add-resource 的完整新手教程

OpenViking 快速开始从安装到 add-resource 的完整新手教程【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 是一款面向 AI Agent 的开源上下文数据库Context Database它将 Agent 的记忆、知识 RAG 与技能统一管理在一个虚拟文件系统里。本教程面向新手带你 5 分钟完成 OpenViking 的安装、服务器初始化、doctor 健康检查并学会用ov add-resource把网页、文件或目录变成可语义检索的知识库。OpenViking 是什么AI Agent 的上下文数据库传统做法是给 Agent 配一个黑盒向量库查询结果难以追踪。OpenViking 换了一种思路所有记忆、资源和技能都存放在viking://协议下的虚拟文件系统里Agent 可以用熟悉的ls、tree、find命令浏览自己的上下文就像开发者操作文件一样直观。它的另一个核心设计是三层分级加载在写入时就完成处理按需加载、节省 token层级内容典型大小用途L0Abstract一句话摘要~100 tokens快速判断相关性L1Overview结构与关键点~2k tokens规划检索路径L2Details完整原文按需真正需要时才读取每次检索还会保留完整的浏览轨迹结果不对时你可以精确看到是哪条路径产生的。完整介绍可参考 docs/en/getting-started/01-introduction.md。安装 OpenViking一条 pip 命令搞定环境要求Python3.10 及以上操作系统Linux / macOS / Windows稳定的网络连接用于下载依赖与访问模型服务安装命令如下任选其一# pip 安装最常用 pip install openviking --upgrade # 或使用 uv 安装 uv tool install openviking --upgrade安装完成后你会得到两个命令openviking-server服务端命令ov客户端 CLI 命令openviking是它的别名模型准备VLM 与 Embedding 两件套OpenViking 需要两类模型能力VLM 模型负责图片与内容理解Embedding 模型负责向量化和语义检索它支持火山引擎豆包系列新用户有免费额度推荐、OpenAI、Codex OAuth 以及本地 Ollama 等多种服务。以火山引擎为例进入方舟控制台的 API Key 管理页面即可创建密钥各供应商的完整配置示例见 docs/en/guides/01-configuration.md本地 Ollama 方案还可以让 init 向导自动检测硬件并拉取适配的模型。初始化服务器init 向导 doctor 体检推荐新手走交互式初始化路径而不是手写配置# 第一步交互式向导选择供应商、填入 API Key自动生成配置 openviking-server init # 第二步体检验证配置文件、Python 版本、模型连通性、磁盘空间 openviking-server doctorinit会引导你完成供应商选择并把可运行的配置写入~/.openviking/ov.confdoctor不需要服务器运行就能完成全部检查。所有检查通过时你会看到这样的输出如果有检查项失败例如缺少 API Keydoctor 会直接给出修复建议照着改即可不想用向导的话也可以参考 examples/ov.conf.example 手动创建配置文件核心结构如下{ embedding: { dense: { api_base: 端点, api_key: 密钥, provider: 供应商, model: 模型 } }, vlm: { api_base: 端点, api_key: 密钥, provider: 供应商, model: 模型 } }启动服务并添加第一个资源add-resource保持服务器在终端中运行openviking-server # 前台启动 # 或后台启动nohup openviking-server openviking.log 21 默认本地模式不需要 API Key。另开一个终端开始体验核心工作流ov status # 确认服务在线 ov add-resource https://example.com/docs # 添加资源URL / 文件 / 目录均可 ov ls viking://resources/ # 浏览虚拟文件系统 ov tree viking://resources/my_project -L 2 # 查看目录树限制 2 层 ov find what is openviking # 语义检索 ov grep openviking --uri viking://resources/my_project/docs # 内容精确搜索关于add-resource的三个实用提示它支持URL、本地文件、本地目录三种输入本地目录扫描默认遵循.gitignore。语义处理是异步的建议加--wait参数等待处理完成后再检索。添加成功后会返回一个root_uri如viking://resources/xxx后续检索都围绕它展开。不想敲命令试试官方 Python 示例项目内置了开箱即用的示例脚本直接运行即可体验添加资源 → 浏览目录树 → 语义搜索的完整链路python examples/quick_start.py示例内部的关键调用是 SDK 的add_resource方法来自 examples/quick_start.pyfrom openviking_sdk import SyncHTTPClient client SyncHTTPClient(urlhttp://localhost:1933) client.initialize() # 添加资源并等待语义处理完成 result client.add_resource(pathhttps://example.com/docs/README.md, waitTrue) root_uri result[root_uri] # 语义检索 results client.find(querywhat is openviking, target_uriroot_uri)如果想看更完整的演示含 L0/L1/L2 分层读取、grep 内容搜索、会话记忆管理可以运行 examples/basic-usage/basic_usage.py。遇到问题怎么排查doctor 有红叉每条 FAIL 后面都附带 Fix 建议例如设置 vlm.api_key或重新强制安装 pip 包照做后重跑 doctor 即可。配置不在默认路径设置环境变量指向你的配置文件——export OPENVIKING_CONFIG_FILE/path/to/ov.conf。Docker 部署的 Mac 网络问题官方文档 docs/en/getting-started/02-quickstart.md 提供了 socat 端口转发的解决方案。命令行高级用法独立 CLI 安装、索引重建等参考 docs/en/getting-started/05-cli-setup.md。下一步把 OpenViking 接进你的 Agent跑通 add-resource 只是开始真正的价值在于让 Agent 用上这些上下文Agent 集成docs/en/agent-integrations/ 目录提供 Claude Code、Codex、Cursor、TRAE 等十余种接入指南Python SDKsdk/python/ 目录用于在自己的应用中调用Docker 生产部署docs/en/guides/03-deployment.md基准测试想看看效果提升多少benchmark/ 目录包含 LoCoMo 长对话记忆与 tau2 多轮任务评测脚本恭喜你已经完成了 OpenViking 从安装到 add-resource 的全部流程。现在给你的 Agent 加上记得住、找得到、可追溯的上下文数据库吧。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考