OpenViking 上下文数据库

技能来自 ara.so — Daily 2026 Skills 系列。

OpenViking 是一个开源的 上下文数据库，用于 AI 智能体，它用统一的 文件系统范式 取代了碎片化的向量存储。它在分层 L0/L1/L2 结构中管理智能体记忆、资源和技能，实现分层上下文交付、可观察的检索轨迹以及自进化的会话记忆。

安装

Python 包

pip install openviking --upgrade --force-reinstall

可选的 Rust CLI

# 通过脚本安装
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

# 或从源码构建（需要 Rust 工具链）
cargo install --git https://github.com/volcengine/OpenViking ov_cli

先决条件

• Python 3.10+
• Go 1.22+（用于 AGFS 组件）
• GCC 9+ 或 Clang 11+（用于核心扩展）

配置

创建 ~/.openviking/ov.conf：

{
  "storage": {
    "workspace": "/home/user/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "$OPENAI_API_KEY",
      "provider": "openai",
      "dimension": 1536,
      "model": "text-embedding-3-large"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "$OPENAI_API_KEY",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}

注意： OpenViking 将 api_key 值作为字符串读取；请在启动时使用环境变量注入，而不是直接写入明文密钥。

提供商选项

LiteLLM VLM 示例

{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20240620",
    "api_key": "$ANTHROPIC_API_KEY"
  }
}

{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}

{
  "vlm": {
    "provider": "litellm",
    "model": "deepseek-chat",
    "api_key": "$DEEPSEEK_API_KEY"
  }
}

核心概念

文件系统范式

OpenViking 像文件系统一样组织智能体上下文：

workspace/
├── memories/          # 长期智能体记忆（L0 始终加载）
│   ├── user_prefs/
│   └── task_history/
├── resources/         # 外部知识、文档（L1 按需加载）
│   ├── codebase/
│   └── docs/
└── skills/            # 可复用的智能体能力（L2 检索获取）
    ├── coding/
    └── analysis/

分层上下文加载（L0/L1/L2）

• L0：始终加载 — 核心身份、持久偏好
• L1：按需加载 — 每个任务获取的相关资源
• L2：语义检索 — 通过相似性搜索拉取的技能

这种分层方法在最大化上下文相关性的同时，最大限度地减少了 token 消耗。

Python API 使用

基本设置

import os
from openviking import OpenViking

# 使用配置文件初始化
ov = OpenViking(config_path="~/.openviking/ov.conf")

# 或以编程方式初始化
ov = OpenViking(
    workspace="/home/user/openviking_workspace",
    vlm_provider="openai",
    vlm_model="gpt-4o",
    vlm_api_key=os.environ["OPENAI_API_KEY"],
    embedding_provider="openai",
    embedding_model="text-embedding-3-large",
    embedding_api_key=os.environ["OPENAI_API_KEY"],
    embedding_dimension=1536,
)

管理上下文命名空间（智能体大脑）

# 创建或打开一个命名空间（类似于一个智能体的文件系统根目录）
brain = ov.namespace("my_agent")

# 添加一个记忆文件
brain.write("memories/user_prefs.md", """
# 用户偏好
- 语言: Python
- 代码风格: PEP8
- 首选框架: FastAPI
""")

# 添加一个资源文档
brain.write("resources/api_docs/stripe.md", open("stripe_docs.md").read())

# 添加一个技能
brain.write("skills/coding/write_tests.md", """
# 技能：编写单元测试
当被要求编写测试时，使用 pytest 和 fixtures。
始终模拟外部 API 调用。目标是 80%+ 的覆盖率。
""")

查询上下文

# 在整个命名空间中进行语义搜索
results = brain.search("用户偏好如何格式化代码？")
for result in results:
    print(result.path, result.score, result.content[:200])

# 限定目录范围的检索（递归）
skill_results = brain.search(
    query="为 FastAPI 端点编写单元测试",
    directory="skills/",
    top_k=3,
)

# 直接路径读取（L0 始终可用）
prefs = brain.read("memories/user_prefs.md")
print(prefs.content)

会话记忆与自动压缩

# 开始一个会话 — OpenViking 跟踪对话轮次并自动压缩
session = brain.session("task_build_api")

# 添加对话轮次
session.add_turn(role="user", content="为我构建一个待办事项的 REST API")
session.add_turn(role="assistant", content="我将创建一个具有 CRUD 操作的 FastAPI 应用...")

# 多次轮次后，触发压缩以提取长期记忆
summary = session.compress()
# 压缩后的洞察会自动写入 memories/ 目录

# 结束会话 — 持久化提取的记忆
session.close()

检索轨迹（可观测的 RAG）

# 启用轨迹跟踪以观察检索决策
with brain.observe() as tracker:
    results = brain.search("身份验证最佳实践")
    
trajectory = tracker.trajectory()
for step in trajectory.steps:
    print(f"[{step.level}] {step.path} → score={step.score:.3f}")
    # 输出示例：
    # [L0] memories/user_prefs.md → score=0.82
    # [L1] resources/security/auth.md → score=0.91
    # [L2] skills/coding/jwt_auth.md → score=0.88

常见模式

模式 1：具有持久记忆的智能体

import os
from openviking import OpenViking

ov = OpenViking(config_path="~/.openviking/ov.conf")
brain = ov.namespace("coding_agent")

def agent_respond(user_message: str, conversation_history: list) -> str:
    # 检索相关上下文
    context_results = brain.search(user_message, top_k=5)
    context_text = "\n\n".join(r.content for r in context_results)
    
    # 使用检索到的上下文构建提示词
    system_prompt = f"""你是一个编码助手。

## 相关上下文
{context_text}
"""
    # ... 在这里调用你的 LLM，传入 system_prompt 和 conversation_history
    response = call_llm(system_prompt, conversation_history, user_message)
    
    # 存储交互以供未来记忆使用
    brain.session("current").add_turn("user", user_message)
    brain.session("current").add_turn("assistant", response)
    
    return response

模式 2：分层技能加载

# 从目录结构注册技能
import pathlib

skills_dir = pathlib.Path("./agent_skills")
for skill_file in skills_dir.rglob("*.md"):
    relative = skill_file.relative_to(skills_dir)
    brain.write(f"skills/{relative}", skill_file.read_text())

# 在运行时，仅检索相关技能
def get_relevant_skills(task: str) -> list[str]:
    results = brain.search(task, directory="skills/", top_k=3)
    return [r.content for r in results]

task = "重构此类以使用依赖注入"
skills = get_relevant_skills(task)
# 只返回与 DI 相关的技能，而不是所有已注册的技能

模式 3：代码库的 RAG

import subprocess
import pathlib

brain = ov.namespace("codebase_agent")

# 索引代码库
def index_codebase(repo_path: str):
    for f in pathlib.Path(repo_path).rglob("*.py"):
        content = f.read_text(errors="ignore")
        # 使用相对路径作为键存储
        rel = f.relative_to(repo_path)
        brain.write(f"resources/codebase/{rel}", content)

index_codebase("/home/user/myproject")

# 使用目录范围查询
def find_relevant_code(query: str) -> list:
    return brain.search(
        query=query,
        directory="resources/codebase/",
        top_k=5,
    )

hits = find_relevant_code("数据库连接池")
for h in hits:
    print(h.path, "\n", h.content[:300])

模式 4：多智能体共享上下文

# 智能体 1 写入发现
agent1_brain = ov.namespace("researcher_agent")
agent1_brain.write("memories/findings/api_rate_limits.md", """
# 发现的 API 速率限制
- Stripe: 100 req/s in live mode
- SendGrid: 600 req/min
""")

# 智能体 2 读取共享工作区发现
agent2_brain = ov.namespace("coder_agent")
# 跨命名空间读取（如果允许）
shared = ov.namespace("shared_knowledge")
rate_limits = shared.read("memories/findings/api_rate_limits.md")

CLI 命令（ov_cli）

# 检查版本
ov --version

# 列出命名空间
ov namespace list

# 创建命名空间
ov namespace create my_agent

# 写入上下文文件
ov write my_agent/memories/prefs.md --file ./prefs.md

# 读取文件
ov read my_agent/memories/prefs.md

# 搜索上下文
ov search my_agent "如何处理身份验证" --top-k 5

# 显示查询的检索轨迹
ov search my_agent "数据库迁移" --trace

# 压缩会话
ov session compress my_agent/task_build_api

# 列出命名空间中的文件
ov ls my_agent/skills/

# 删除上下文文件
ov rm my_agent/resources/outdated_docs.md

# 导出命名空间到本地目录
ov export my_agent ./exported_brain/

# 从本地目录导入
ov import ./exported_brain/ my_agent_restored

故障排除

未找到配置文件

# 验证配置文件位置
ls -la ~/.openviking/ov.conf

# OpenViking 也检查 OV_CONFIG 环境变量
export OV_CONFIG=/path/to/custom/ov.conf

嵌入维度不匹配

如果切换嵌入模型，存储的向量维度会发生冲突：

# 检查当前维度设置与存储的索引
# 解决方案：模型更改后重新索引
brain.reindex(force=True)

工作区权限错误

# 确保工作区目录可写
chmod -R 755 /home/user/openviking_workspace

# 检查磁盘空间（嵌入索引可能很大）
df -h /home/user/openviking_workspace

未检测到 LiteLLM 提供商

# 为不明确的模型使用显式前缀
{
  "vlm": {
    "provider": "litellm",
    "model": "openrouter/anthropic/claude-3-5-sonnet",  # 需要完整前缀
    "api_key": "$OPENROUTER_API_KEY",
    "api_base": "https://openrouter.ai/api/v1"
  }
}

Token 使用量高

启用分层加载以减少 L1/L2 获取：

# 严格限定搜索范围以避免过度获取
results = brain.search(
    query=user_message,
    directory="skills/relevant_domain/",  # 缩小范围
    top_k=2,                               # 更少的结果
    min_score=0.75,                        # 质量阈值
)

大型代码库索引缓慢

# 在配置中增加并发数
{
  "embedding": {
    "max_concurrent": 20  # 从默认值 10 增加
  },
  "vlm": {
    "max_concurrent": 50
  }
}

# 或使用异步批量写入
import asyncio

async def index_async(files):
    tasks = [brain.awrite(f"resources/{p}", c) for p, c in files]
    await asyncio.gather(*tasks)

环境变量参考

资源

• 网站：https://openviking.ai
• 文档：https://www.openviking.ai/docs
• GitHub：https://github.com/volcengine/OpenViking
• Issues：https://github.com/volcengine/OpenViking/issues
• Discord：https://discord.com/invite/eHvx8E9XF3
• LiteLLM 提供商：https://docs.litellm.ai/docs/providers