DEV Community

Cover image for O que é OpenViking? Guia Completo e Detalhes
Lucas
Lucas

Posted on • Originally published at apidog.com

O que é OpenViking? Guia Completo e Detalhes

#agents #ai #database #opensource

TL;DR

OpenViking é um banco de dados de contexto open source para agentes de IA que substitui o armazenamento vetorial tradicional por um paradigma de sistema de arquivos. Ele organiza memórias, recursos e habilidades sob URIs viking:// com três camadas: L0 (~100 tokens), L1 (~2k tokens) e L2 (conteúdo completo). Benchmarks mostram redução de 91% no custo de tokens e 43% de melhoria na conclusão de tarefas frente ao RAG tradicional.

Experimente o Apidog hoje

Introdução

Seu agente de IA esquece informações importantes, repete solicitações de endpoints de API, ignora preferências de ambiente e perde o histórico de testes anteriores. Este é o cenário comum ao construir agentes atualmente, pois a maioria das equipes remenda pipelines RAG, bancos de dados vetoriais e sistemas de memória caseiros. O resultado: contexto fragmentado, custos altos de tokens e falhas silenciosas de recuperação.

Benchmarks com o dataset LoCoMo10 mostram que sistemas RAG tradicionais atingem apenas 35-44% de taxa de conclusão de tarefas, consumindo até 51 milhões de tokens de entrada.

OpenViking propõe um caminho diferente: substitui o armazenamento vetorial plano por um sistema de arquivos hierárquico via URIs viking:// e camadas L0/L1/L2. Resultado: 52% de conclusão de tarefas com 91% menos tokens.

💡 Dica: Usuários Apidog que criam agentes de teste de API podem integrar o OpenViking para manter o contexto da conversa entre execuções, lembrar preferências de ambiente e armazenar a documentação da API para recuperação semântica.

Neste guia prático você vai entender como o OpenViking resolve fragmentação de contexto, ver o modelo L0/L1/L2 em ação e implantar seu primeiro servidor em minutos.

O Problema de Contexto do Agente

Agentes de IA lidam com desafios de contexto superiores aos de aplicações tradicionais.

Imagine um agente auxiliando no teste de APIs. Ele precisa reter:

  • Preferências do usuário (“ambiente de testes”, “curl em vez de Python”)
  • Contexto do projeto (endpoints, autenticação, resultados de testes anteriores)
  • Padrões de ferramentas (quais endpoints falham, erros comuns)
  • Histórico de tarefas (o que foi testado, bugs encontrados)

O RAG tradicional armazena isso como blocos planos em bancos vetoriais. Na consulta, retorna os top-K mais similares, sem hierarquia, estrutura ou visibilidade do que foi ignorado.

Cinco Desafios Principais

OpenViking endereça cinco problemas centrais no gerenciamento de contexto:

Desafio RAG Tradicional Solução OpenViking
Contexto Fragmentado Memórias, recursos, habilidades separados Sistema de arquivos unificado sob viking://
Demanda Crescente Contexto massivo em tarefas longas Carregamento hierárquico L0/L1/L2 reduz tokens em 91%
Recuperação Ruim Busca vetorial plana, sem visão global Recuperação recursiva de diretório com análise de intenção
Não Observável Cadeias de recuperação caixa preta Trajetos de busca visualizados para depuração
Iteração Limitada Só histórico de interação do usuário Gerenciamento automático de sessão com 6 categorias de memória

A proposta é: “estruture tudo, recupere com precisão”.

O Que é OpenViking?

OpenViking é um banco de dados de contexto open source para agentes de IA, mantido pela ByteDance sob licença Apache 2.0.

Estrutura OpenViking

Unifica contexto em um sistema de arquivos virtual. Memórias, recursos e habilidades mapeiam para diretórios sob viking://, cada um com URI única.

viking://
├── resources/              # Docs, código, web
│   ├── my_project/
│   │   ├── docs/
│   │   └── src/
├── user/                   # Preferências e memórias do usuário
│   └── memories/
│       ├── preferences/
│       └── ...
└── agent/                  # Habilidades e memórias do agente
    ├── skills/
    └── memories/
Enter fullscreen mode Exit fullscreen mode

Operações disponíveis:

  • Navegar: ls viking://resources/my_project/docs/
  • Busca semântica: find "métodos de autenticação"
  • Ler conteúdo: read viking://resources/docs/auth.md
  • Resumo rápido: abstract viking://resources/docs/
  • Visão geral: overview viking://resources/docs/

Recurso 1: Paradigma de Sistema de Arquivos

Três Tipos de Contexto

Tipo Propósito Ciclo de Vida Iniciativa
Recurso Docs, código, FAQs Longo prazo, estático Usuário adiciona
Memória Preferências, experiências Longo prazo, dinâmico Agente extrai
Habilidade Ferramentas, chamadas MCP Longo prazo, estático Agente invoca

Diretórios comuns:

  • viking://resources/ – Manuais, código, docs
  • viking://user/memories/ – Preferências, eventos
  • viking://agent/skills/ – Ferramentas
  • viking://agent/memories/ – Padrões aprendidos

API Unix-like 

from openviking import OpenViking

client = OpenViking(path="./data")

# Busca semântica
results = client.find("autenticação de usuário")

# Listar diretório
contents = client.ls("viking://resources/")

# Ler conteúdo
doc = client.read("viking://resources/docs/auth.md")

# Resumo L0
abstract = client.abstract("viking://resources/docs/")

# Visão geral L1
overview = client.overview("viking://resources/docs/")
Enter fullscreen mode Exit fullscreen mode

Funciona via SDK Python ou servidor HTTP, integrável a qualquer framework de agente.

Recurso 2: Carregamento Hierárquico L0/L1/L2

Preencher prompts com contexto massivo é caro. OpenViking processa contexto em três camadas:

Camada Nome Arquivo Tokens Propósito
L0 Resumo .abstract.md ~100 Busca vetorial, filtragem
L1 Overview .overview.md ~2k Rerank, navegação
L2 Detalhe Arquivo original Ilimitado Conteúdo completo

Como Funciona

  1. Analisa o documento
  2. Constrói árvore de diretórios no AGFS
  3. Enfileira processamento semântico
  4. Gera resumos L0 e L1

Exemplo de estrutura:

viking://resources/my_project/
├── .abstract.md
├── .overview.md
├── docs/
│   ├── .abstract.md
│   ├── .overview.md
│   └── auth.md
Enter fullscreen mode Exit fullscreen mode

Impacto no Orçamento de Tokens 

# RAG tradicional: carrega tudo (~50k tokens)
full_docs = retrieve_all("autenticação")

# OpenViking: começa com L1 (~2k tokens)
overview = client.overview("viking://resources/docs/auth/")

if needs_more_detail(overview):
    content = client.read("viking://resources/docs/auth/oauth.md")
Enter fullscreen mode Exit fullscreen mode

O resultado é até 91% de economia de tokens e 43% mais tarefas concluídas.

Recurso 3: Recuperação Recursiva de Diretório

OpenViking adota uma busca recursiva baseada em intenção:

1. Análise de Intenção
2. Posicionamento Inicial (diretórios mais relevantes)
3. Exploração Refinada (arquivos dentro do diretório)
4. Descida Recursiva (subdiretórios)
5. Agregação de Resultados
Enter fullscreen mode Exit fullscreen mode

Exemplo:

  • Consulta: “como autentico usuários?”
  • Análise identifica diretórios relevantes: viking://resources/docs/auth/ (0.92), busca arquivos: oauth.md (0.95), jwt.md (0.88)
  • Repete em subdiretórios se necessário

Essa abordagem melhora a precisão e a transparência da recuperação.

Recurso 4: Rastros de Recuperação Visualizados

A estrutura de arquivos permite rastrear cada passo da busca:

Rastro para "refresh de token OAuth"

├── viking://resources/docs/
│   ├── [0.45] .abstract.md: ignorado
│   └── [0.89] auth/: selecionado
│       ├── [0.92] oauth.md: RETORNADO
│       └── [0.78] providers/
│           └── [0.85] google.md: RETORNADO
Enter fullscreen mode Exit fullscreen mode

Você pode depurar facilmente onde o contexto foi perdido ou ignorado.

Recurso 5: Gerenciamento Automático de Sessão

OpenViking possui autoiteração de memória: ao final de cada sessão, o agente extrai memórias e atualiza o contexto automaticamente.

Seis Categorias de Memória

Categoria Proprietário Localização Descrição Atualização
perfil usuário user/memories/.overview.md Dados básicos Adicionável
preferências usuário user/memories/preferences/ Preferências por tópico Adicionável
entidades usuário user/memories/entities/ Pessoas, projetos Adicionável
eventos usuário user/memories/events/ Decisões, marcos Sem atualização
casos agente agent/memories/cases/ Casos aprendidos Sem atualização
padrões agente agent/memories/patterns/ Padrões aprendidos Sem atualização

Extração de Memória na Prática 

session = client.session()
await session.add_message("user", [{"type": "text", "text": "Prefiro modo escuro"}])
await session.add_message("assistant", [{"type": "text", "text": "Entendido. Modo escuro ativado."}])
await session.add_usage({
    "tool": "screenshot",
    "parameters": {"theme": "dark"},
    "result": "success"
})
await session.commit()  # Extrai e atualiza memórias
Enter fullscreen mode Exit fullscreen mode

Assim, o agente aprende preferências e experiências automaticamente.

Visão Geral da Arquitetura

Arquitetura OpenViking

Armazenamento de Dupla Camada

Camada Tecnologia O que armazena
AGFS FS customizado L0/L1/L2, multimídia, relações
Índice Vetorial DB vetorial URIs, embeddings, metadados (sem conteúdo)

Separação garante leitura única do conteúdo real e índice leve apenas para busca.

Início Rápido: Implante OpenViking

Pré-requisitos

  • Python 3.10+
  • Go 1.22+ (para AGFS)
  • GCC 9+ ou Clang 11+
  • Linux/macOS/Windows

1. Instale o OpenViking 

pip install openviking --upgrade --force-reinstall
Enter fullscreen mode Exit fullscreen mode

Opcional: CLI Rust

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

2. Configure Modelos

Crie ~/.openviking/ov.conf:

{
  "storage": {
    "workspace": "/home/seu-nome/openviking_workspace"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "sua-chave-api-openai",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    }
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "sua-chave-api-openai",
    "provider": "openai",
    "model": "gpt-4o"
  }
}
Enter fullscreen mode Exit fullscreen mode

Provedores suportados: volcengine, openai, litellm (Claude, Gemini, DeepSeek, Qwen, Ollama, vLLM).

3. Inicie o servidor 

openviking-server
# Ou em background
nohup openviking-server > /data/log/openviking.log 2>&1 &
Enter fullscreen mode Exit fullscreen mode

4. Adicione recursos 

# CLI Rust
ov add-resource https://docs.example.com/api-guide.pdf

# SDK Python
from openviking import OpenViking
client = OpenViking(path="./data")
client.add_resource("https://docs.example.com/api-guide.pdf")
Enter fullscreen mode Exit fullscreen mode

5. Busque e recupere 

ov find "métodos de autenticação"
ov ls viking://resources/
ov tree viking://resources/docs -L 2
ov grep "OAuth" --uri viking://resources/docs/
Enter fullscreen mode Exit fullscreen mode

6. (Opcional) Habilite o VikingBot 

pip install "openviking[bot]"
openviking-server --with-bot
ov chat
Enter fullscreen mode Exit fullscreen mode

Benchmarks de Desempenho

Comparação com LanceDB e memória nativa usando LoCoMo10 (1.540 diálogos longos):

Sistema Conclusão (%) Tokens Entrada
OpenClaw (memória nativa) 35.65 24.6M
OpenClaw + LanceDB 44.55 51.6M
OpenClaw + OpenViking 52.08 4.3M
  • 43% melhor que memória nativa, 91% menos tokens
  • 17% melhor que LanceDB, 92% menos tokens

Integrando OpenViking com Apidog

Usuários Apidog podem usar OpenViking para contexto de conversa, docs de API e preferências persistentes.

Integração Apidog

1. Configure o servidor OpenViking

Siga o início rápido acima.

2. Importe docs da API Apidog 

ov add-resource https://docs.apidog.com/overview?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation
ov add-resource https://docs.apidog.com/api-testing?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation
Enter fullscreen mode Exit fullscreen mode

Docs Apidog serão processadas com L0/L1/L2 automaticamente.

3. Armazene preferências do usuário 

from openviking import OpenViking
client = OpenViking(path="./apidog-agent-data")
session = client.session()

await session.add_message("user", [{
    "type": "text",
    "text": "Sempre use o ambiente de testes para testes de API"
}])
await session.commit()
Enter fullscreen mode Exit fullscreen mode

4. Consulte contexto nos testes 

# Buscar endpoints relevantes
results = client.find("endpoints de autenticação")
for ctx in results.resources:
    print(f"Encontrado: {ctx.uri}")

# Recuperar preferência do usuário
prefs = client.find("preferência de ambiente de testes", target_uri="viking://user/memories/")
Enter fullscreen mode Exit fullscreen mode

5. Conecte ao seu framework de agente 

# SDK Python
from openviking import OpenViking
client = OpenViking(path="./data")

# API HTTP
import httpx
response = httpx.post(
    "http://localhost:1933/api/v1/search/find",
    json={"query": "endpoints de autenticação"},
    headers={"X-API-Key": "sua-chave-api"}
)
Enter fullscreen mode Exit fullscreen mode

Técnicas Avançadas e Melhores Práticas

Dicas Pro

  1. Pré-aqueça contexto crítico 
   ov add-resource https://docs.example.com --wait
Enter fullscreen mode Exit fullscreen mode
  1. Implemente expiração de contexto 
   await session.archive(max_age_days=7)
Enter fullscreen mode Exit fullscreen mode
  1. Monitore saúde do índice vetorial 
   ov debug stats
Enter fullscreen mode Exit fullscreen mode

Erros Comuns

  1. Carregar L2 prematuramente — prefira L0/L1.
  2. Não confirmar sessões — memórias só são extraídas na confirmação.
  3. Sobrecarga de diretórios únicos — divida recursos grandes.
  4. Ignorar rastros — use-os para depurar.

Otimização de Desempenho

Cenário Recomendação
Alto volume de consultas Execute como serviço HTTP com pool de conexões
Documentos grandes Divida em blocos por tópico antes de importar
Baixa latência Pré-gerar L0/L1 para conteúdo mais acessado
Multi-tenant Isolar workspaces por tenant

Segurança

  • Armazene chaves de API em variáveis de ambiente/secret managers
  • Habilite HTTPS no servidor HTTP
  • Implemente rate limit em endpoints públicos
  • Separe chaves de API para dev/prod

Casos de Uso Reais

1. Assistentes de Codificação de IA

  • Navegação via viking://resources/my_project/src/
  • Preferências de codificação persistentes
  • Recuperação de docs relevantes

Resultado: 67% menos esquecimentos, 43% de economia de tokens.

2. Agentes de Suporte

  • Docs em viking://resources/product/
  • Conversas em viking://user/memories/past_issues/
  • Playbooks em viking://agent/skills/

Resultado: Resolução no primeiro contato de 52% para 71%.

3. Assistentes de Pesquisa

  • Artigos por tópico em viking://resources/papers/nlp/
  • Extração automática de insights
  • Busca semântica acelerada

Resultado: Pesquisa 3x mais rápida.

Alternativas e Comparações

OpenViking vs Bancos Vetoriais

Aspecto RAG Tradicional (Pinecone, LanceDB) OpenViking
Modelo de Armazenamento Blocos vetoriais planos Sistema de arquivos hierárquico
Recuperação Similaridade Top-K Recursivo de diretório + intenção
Observabilidade Caixa preta Rastros visualizados
Eficiência de Tokens Carrega tudo/trunca L0/L1/L2 progressivo
Iteração de Memória Manual ou nenhuma Sessão automática
Tipos de Contexto Só docs Recursos, memórias, habilidades
Depuração Adivinhação Logs de travessia

OpenViking vs LangChain Memory

Aspecto Memória LangChain OpenViking
Persistência Buffer de conversa FS completo L0/L1/L2
Escalabilidade Limitado pela janela Hierárquico, sem limite rigído
Recuperação Busca linear Recursiva e semântica
Tipos de Memória Buffer único 6 categorias

Quando Considerar Alternativas

Prefira bancos vetoriais se:

  • Precisa de latência <100ms
  • Caso é só busca simples
  • Pipeline RAG já funciona

Use OpenViking se:

  • Agentes longos, multi-tipo de contexto
  • Otimização de tokens importa
  • Precisa de observabilidade

Comparação com RAG Tradicional

Aspecto RAG Tradicional OpenViking
Armazenamento Vetorial plano Arquivo hierárquico
Recuperação Top-K Recursiva + intenção
Observabilidade Caixa preta Rastros visualizados
Eficiência de Tokens Carrega tudo L0/L1/L2 progressivo
Iteração de Memória Manual Sessão automática
Tipos de Contexto Só docs Recursos, memórias, habilidades
Depuração Adivinhação Logs de travessia

Implantação em Produção

Execute OpenViking como serviço HTTP autônomo.

Infraestrutura Recomendada

  • Nuvem: Volcengine ECS ou similar
  • SO: veLinux ou Ubuntu 22.04+
  • Armazenamento: SSD para AGFS
  • Rede: baixa latência para APIs de modelos

Segurança

  • Chaves de API em variáveis/secret managers
  • Autenticação endpoints HTTP
  • HTTPS obrigatório
  • Rate limit ativado

Monitoramento 

{
  "log": {
    "level": "INFO",
    "output": "file",
    "path": "/var/log/openviking/server.log"
  }
}
Enter fullscreen mode Exit fullscreen mode

Monitore:

  • Fila de processamento semântico
  • Latência de busca vetorial
  • Leituras/escritas AGFS
  • Sucesso em extração de memória

Limitações e Considerações

Limitações Atuais

  • SDK principal em Python; outras linguagens via HTTP
  • Depende de modelos externos (VLM, embedding)
  • Paradigma diferente de bancos vetoriais comuns
  • APIs podem mudar (projeto inicial)

Quando Usar

Use se:

  • Agentes de longa duração/memória
  • Contexto multi-tipo
  • Recuperação depurável
  • Otimização de tokens é prioridade

Considere alternativas se:

  • App simples de Q&A
  • Pipeline RAG já é suficiente
  • Precisa de latência <100ms

O Caminho a Seguir

OpenViking está no início (v0.1.x). Roadmap inclui:

  • Multi-tenant (workspaces isolados)
  • Dashboards de uso/memória
  • Plugins para frameworks populares
  • Edge (aplicações local-first)
  • Integração MCP nativa

O projeto é aberto e busca contribuidores. Veja documentação aqui.

Conclusão

OpenViking muda a forma como agentes de IA gerenciam contexto: estrutura tipo sistema de arquivos, menos fragmentação, menor custo de tokens e recuperação observável.

Principais Pontos

  • Paradigma de arquivos unifica contexto: Tudo sob URIs viking://
  • Carregamento L0/L1/L2: Até 91% menos tokens
  • Recuperação recursiva de diretórios: Mais precisão e controle
  • Rastros visualizados: Depuração facilitada
  • Gerenciamento de sessão automático: Aprendizado contínuo do agente

Top comments (0)