Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
快速开始
当你希望 AI Agent 根据项目资料回答问题时,需要先让它找到相关内容,再读取原文。OpenViking 是面向 Agent 的上下文数据库,负责保存和检索这些资料,让 Agent 能够根据来源生成回答。
接下来,你会导入一份虚构的“灯塔项目”说明,让 Agent 回答反馈收集的问题,并打开它引用的原文核对结果。你可以使用火山引擎云服务,也可以在本机运行 OpenViking:两条路径都会完成 导入资料 → 检索与读取 → 生成回答 → 核对来源。
准备工作
先选择运行方式,再安装对应的工具:
| 运行方式 | 适合的情况 | 需要准备 |
|---|---|---|
| 火山引擎云服务 | 希望使用托管服务,并在已有 Agent 中提问 | Node.js/npm、火山引擎账号,以及能在本机执行终端命令的 Agent |
| 本地服务 | 希望在自己的电脑上运行,并直接使用内置 Agent VikingBot | Node.js/npm、uv、Python,以及模型访问凭据 |
安装 Node.js
两条路径都通过 ov CLI 操作资料。打开 Node.js 下载页,选择与你的系统匹配的 LTS 版本,按页面提供的安装程序或命令完成安装;npm 会随 Node.js 一同安装。
安装后重新打开终端,确认两个命令都能输出版本号:
node --version
npm --version
使用云服务时,可以直接进入开通或启动服务。
准备本地运行环境
本地服务使用 uv 安装 OpenViking,并使用 Python 运行。下面以 macOS / Linux 终端为例;其他系统的安装方式可查看 uv 安装指南和服务端部署。
先安装 uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
重新打开终端,确认 uv 可用:
uv --version
再用 uv 安装 Python 3.13,供后续服务使用:
uv python install 3.13
已有 Python 3.13 时可直接使用。其他安装方式见 Python 下载页和 uv 的 Python 管理指南。
最后,准备两个模型的调用信息:Embedding 模型用于资料向量化和检索,支持工具调用的 VLM用于内容理解和 VikingBot 回答。每个模型需要模型名、调用端点及 API Key;可按火山引擎模型开通指南取得这些信息。使用 Agent Plan 时,选择套餐支持的模型与端点。导入资料和生成回答会产生模型调用,按所选服务计费。
开通或启动服务
选择下面的一条路径,完成后继续连接 CLI。
火山引擎云服务
云服务负责运行 OpenViking 和处理资料,你的电脑只需安装客户端。
- 打开 OpenViking 控制台,登录火山引擎账号,并按控制台提示开通服务。套餐与额度可在服务说明中查看。
- 在控制台取得用于访问 OpenViking 的 API Key,供下一步配置 CLI 使用。
- 准备一个能在本机执行终端命令的 Agent。在“提问并核对”中,通过它调用
ov检索云端资料并生成回答;接入方式可查看 CLI 入门。
取得 API Key 后,继续连接 CLI。
本地服务
先安装 OpenViking 和 VikingBot,让本机同时具备资料管理和问答能力:
uv tool install --python 3.13 "openviking[bot]" --upgrade
接着运行初始化向导。选择本机访问,并填写准备好的 Embedding 和 VLM 模型信息;VikingBot 默认使用这里配置的 VLM。
openviking-server init
配置完成后,检查模型和服务配置。若检查报告错误,按提示修正对应项目后再次检查:
openviking-server doctor
检查通过后,启动服务和 VikingBot。保持这个终端运行,后续操作在另一个终端中进行。
openviking-server --with-bot
在新终端中确认资料服务和 Agent 都已就绪:
curl -f http://127.0.0.1:1933/health
curl -f http://127.0.0.1:1933/bot/v1/health
分别看到 healthy: true 和 Bot 的 status: healthy 后,继续连接 CLI。
连接 CLI
安装 CLI,以便在终端中导入、检索和读取资料。已有 ov 时可以跳过安装命令。
npm install -g @openviking/cli
将界面语言设为中文,再打开连接向导:
ov language zh-CN
ov config
在向导中添加连接,按所选路径填写,然后保存并设为当前配置:
| 运行方式 | 连接类型 | 填写内容 |
|---|---|---|
| 火山引擎云服务 | OpenViking Service | 按向导使用服务地址,输入控制台取得的 API Key |
| 本地服务 | 自定义(Custom) | URL 填写 http://127.0.0.1:1933;默认本机模式的密钥留空 |
如果本地服务已有认证配置,使用对应的 User/Admin Key;配置方式见身份认证。
检查当前连接,成功后即可开始导入:
ov health
导入样例
下载灯塔项目资料,保存为 lighthouse.zh.md,然后在终端中进入该文件所在目录。资料包含试点的网络条件、反馈收集方式和未确定事项。
将它导入独立的演示目录,并通过 --wait 等待处理完成。再次体验时,可将 lighthouse-demo 换成一个新的目录名,并在后续命令中使用相同名称。
ov add-resource ./lighthouse.zh.md --to viking://resources/lighthouse-demo --wait
处理成功后,查看导入的文件:
ov tree viking://resources/lighthouse-demo
如果等待超时,使用返回的任务 ID 执行 ov task status <task_id> 查看进度。任务完成后继续;任务失败时,先根据错误信息修正模型或连接配置,再重试。任务状态说明见任务管理。
提问并核对
检索并读取资料
先查找与反馈收集相关的内容:
ov find "灯塔项目第一版怎样收集用户反馈?" --uri viking://resources/lighthouse-demo
结果中会包含匹配内容的 URI。复制其中的来源文件 URI,替换下面的占位值,打开原文:
ov read "<来源文件 URI>"
能读到“试点环境”和“反馈收集”等内容后,就可以让 Agent 使用这些资料回答问题。
让 Agent 生成回答
使用云服务: 在能够执行本机终端命令的 Agent 中发送下面的任务。让它使用刚才配置好的 CLI 连接;如果 Agent 运行在另一台机器或独立容器中,先在那里完成CLI 连接配置。
请使用本机已配置的 ov CLI,根据 OpenViking 中的项目资料回答问题。
先执行 ov health 确认连接,再执行:
ov find "灯塔项目第一版怎样收集用户反馈?" --uri viking://resources/lighthouse-demo
用 ov read 读取检索结果中的相关原文,然后回答:
灯塔项目第一版应怎样收集用户反馈,需要提前准备什么?
请只依据该目录中的资料,为关键结论列出来源文件的完整 viking:// URI,
并明确指出资料未说明的内容。
使用本地服务: 通过 ov chat 把同一个问题交给已启动的 VikingBot,它会调用检索和读取工具:
ov chat -m "请只使用 viking://resources/lighthouse-demo 中的资料,先按问题进行语义检索,再读取相关原文并回答:灯塔项目第一版应怎样收集用户反馈,需要提前准备什么?为关键结论列出来源文件的完整 viking:// URI;资料没有说明的部分请明确指出。"
核对回答的依据
打开回答引用的来源文件,逐项比较下面的事实。回答可以采用不同措辞,关键是结论与原文一致。
| 应包含的结论 | 原文依据 |
|---|---|
| 反馈保存在本地,由试点管理员每周导出并交给项目负责人 | “反馈收集” |
| 提前准备离线安装包和本地存储目录 | “试点环境” |
| 第一版没有云端同步,后续是否支持尚未决定 | “反馈收集” |
如果某项结论缺少来源,可以请 Agent 补充引用并重新核对。再问一次“试点何时结束?”,查看它是否根据资料说明该日期尚未确定。
至此,你已经完成了资料导入、检索、原文读取和带来源的问答。接下来可以换成自己的资料,重复这个流程。
常见问题
| 现象 | 下一步 |
|---|---|
安装后找不到 uv、node 或 ov |
重新打开终端;仍不可用时,按对应安装指南检查命令路径 |
ov health 连接失败 |
在 ov config 中检查当前连接、服务地址和 API Key;本地服务同时检查运行终端 |
Bot 健康检查返回 503 |
确认已使用 --with-bot 启动,查看服务终端及 VikingBot 日志 |
| 导入失败或检索无结果 | 查看返回的任务状态,确认模型可用、处理完成且查询 URI 与导入目标一致 |
模型返回 UnsupportedModel |
核对模型名、端点和套餐是否匹配,参见模型开通指南 |
Agent 无法调用 ov |
在 Agent 使用的终端中检查 ov --version 和 ov health,完成安装及连接配置 |