205 lines
5.5 KiB
Markdown
Executable File
205 lines
5.5 KiB
Markdown
Executable File
# OpenViking - Agent 上下文数据库
|
||
|
||
> 字节跳动开源的 AI Agent 记忆管理系统
|
||
>
|
||
> 归档：2026-04-22
|
||
|
||
---
|
||
|
||
## 基本信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| GitHub | https://github.com/volcengine/OpenViking |
|
||
| 官网 | https://www.openviking.ai |
|
||
| Stars | ⭐ 22,714 |
|
||
| Forks | 1,651 |
|
||
| 许可证 | AGPL-3.0 |
|
||
| 语言 | Python |
|
||
| 更新 | 2026-04-21 |
|
||
|
||
---
|
||
|
||
## 核心定位
|
||
|
||
**专为 AI Agent 设计的上下文数据库**
|
||
|
||
解决传统 RAG 的问题：
|
||
- 碎片化上下文：记忆在代码里，资源在向量数据库，技能分散
|
||
- 上下文需求暴涨：Agent 长任务产生大量上下文，简单截断会丢失信息
|
||
- 检索效果差：传统 RAG 平面存储，缺乏全局视图
|
||
- 检索链不可观测：传统 RAG 是黑盒，难以调试
|
||
- 记忆迭代有限：当前记忆只是用户交互记录
|
||
|
||
---
|
||
|
||
## 核心架构
|
||
|
||
### 文件系统范式
|
||
|
||
```
|
||
viking://
|
||
├── resources/ # 外部资源（文档、代码、URL）
|
||
├── user/ # 用户上下文
|
||
└── agent/ # Agent 记忆和技能
|
||
```
|
||
|
||
### L0 / L1 / L2 三层加载
|
||
|
||
| 层级 | 内容 | Token 消耗 | 用途 |
|
||
|------|------|-----------|------|
|
||
| **L0** | 摘要 | ~100 tokens | 快速扫描，判断相关性 |
|
||
| **L1** | 概览 | ~2k tokens | 理解架构，制定计划 |
|
||
| **L2** | 全文 | 按需加载 | 深读具体文件 |
|
||
|
||
### Token 节省效果
|
||
|
||
| 方案 | Token 消耗 |
|
||
|------|-----------|
|
||
| 全量加载（传统 RAG） | ~50,000 |
|
||
| L0 扫描 + L1 概览 | ~3,000 |
|
||
| L0 + L1 + L2 按需 | ~8,000 |
|
||
| **节省比例** | **83%~96%** |
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 文件系统协议 `viking://` | 统一管理 resources/user/agent 三类上下文 |
|
||
| 分层摘要 | L0/L1/L2 按需加载 |
|
||
| 目录递归检索 | 语义检索 + 目录定位 |
|
||
| 会话记忆 | 自动提取长期记忆，跨会话保持 |
|
||
| Token 追踪 | 可视化检索轨迹，追踪每个操作的 token 消耗 |
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
### OpenClaw Skill 安装
|
||
|
||
```bash
|
||
# 使用 clawhub 安装 openviking-context skill
|
||
clawhub install openviking-context
|
||
|
||
# 在 OpenClaw 中说 "refresh skills" 即可发现
|
||
```
|
||
|
||
### OpenViking 本体安装
|
||
|
||
```bash
|
||
# 自动检测 Python >= 3.10，安装 openviking 包
|
||
bash scripts/install.sh
|
||
|
||
# 可选：安装 Rust CLI (ov)
|
||
```
|
||
|
||
### 配置支持的模型
|
||
|
||
| 提供商 | VLM 模型 | Embedding 模型 |
|
||
|--------|---------|---------------|
|
||
| OpenAI | gpt-4o | text-embedding-3-large (dim=3072) |
|
||
| Volcengine | doubao-seed-2-0-pro-260215 | doubao-embedding-vision-250615 (dim=1024) |
|
||
| LiteLLM | claude-3-5-sonnet / deepseek-chat | - |
|
||
| NVIDIA NIM | meta/llama-3.3-70b-instruct | nvidia/nv-embed-v1 (dim=4096) |
|
||
|
||
**注意**：避免使用推理模型（kimi-k2.5, deepseek-r1），它们的 reasoning 字段与 OpenViking 不兼容。
|
||
|
||
---
|
||
|
||
## 核心操作
|
||
|
||
```bash
|
||
# 启动服务器
|
||
openviking-server
|
||
|
||
# 添加资源
|
||
python3 scripts/viking.py add ./docs/
|
||
python3 scripts/viking.py add https://github.com/volcengine/OpenViking
|
||
|
||
# 语义搜索
|
||
python3 scripts/viking.py search "用户认证 鉴权"
|
||
|
||
# 浏览目录
|
||
python3 scripts/viking.py ls viking://resources/
|
||
python3 scripts/viking.py tree viking://resources/ -L 2
|
||
|
||
# 分层读取
|
||
python3 scripts/viking.py abstract viking://resources/proj # L0 ~100 tokens
|
||
python3 scripts/viking.py overview viking://resources/proj # L1 ~2k tokens
|
||
python3 scripts/viking.py read viking://resources/proj/api.md # L2 全文
|
||
|
||
# 状态和统计
|
||
python3 scripts/viking.py info # 检查服务状态
|
||
python3 scripts/viking.py stats # 查看 token 消耗统计
|
||
python3 scripts/viking.py commit # 提取当前会话记忆
|
||
```
|
||
|
||
---
|
||
|
||
## 工作流示例
|
||
|
||
收到开发需求时：
|
||
|
||
1. **L0 快速扫描**（~300 tokens）
|
||
```bash
|
||
python3 scripts/viking.py search "用户认证 鉴权 登录"
|
||
```
|
||
用 L0 摘要判断哪些资源相关，过滤无关内容。
|
||
|
||
2. **L1 概览决策**（~2k tokens/资源）
|
||
```bash
|
||
python3 scripts/viking.py overview viking://resources/auth-docs
|
||
```
|
||
理解架构和技术选型，制定实现计划。
|
||
|
||
3. **L2 按需深读**（仅必要文件）
|
||
```bash
|
||
python3 scripts/viking.py read viking://resources/auth-docs/jwt-config.md
|
||
```
|
||
只加载写代码需要的具体文件。
|
||
|
||
---
|
||
|
||
## Token 节省演示
|
||
|
||
```bash
|
||
python3 scripts/demo-token-compare.py ./your-project-docs/
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
方案 Token 消耗 说明
|
||
─────────────────────────────────────────────────────
|
||
全量加载 (传统 RAG) ~50,000 所有文档塞进 prompt
|
||
L0 扫描 + L1 概览 ~3,000 分层按需，仅摘要和概览
|
||
L0 + L1 + L2 按需 ~8,000 最终只深读 2-3 个必要文件
|
||
─────────────────────────────────────────────────────
|
||
节省比例 84%~94% 相比全量加载
|
||
```
|
||
|
||
---
|
||
|
||
## 相关资源
|
||
|
||
| 资源 | 链接 |
|
||
|------|------|
|
||
| OpenViking GitHub | https://github.com/volcengine/OpenViking |
|
||
| OpenViking 官网 | https://www.openviking.ai |
|
||
| ClawHub Skill | openviking-context |
|
||
|
||
---
|
||
|
||
## 替代方案对比
|
||
|
||
| 方案 | 说明 |
|
||
|------|------|
|
||
| **OpenViking** | 字节跳动开源，上下文数据库，AGPL 许可 |
|
||
| Elite Longterm Memory | 高级长期记忆，ClawHub Skill |
|
||
| Memory Tiering | 记忆分层，ClawHub Skill |
|
||
| Fluid Memory | 流动记忆，ClawHub Skill |
|
||
|
||
---
|
||
|
||
*整理：知识库管理员 | 来源：GitHub / OpenViking 官网 | 归档：2026-04-22* |