O que é OpenViking? Guia Completo e Detalhes

TL;DR

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

Introdução

Seu agente de IA continua esquecendo as coisas. Ele pediu o mesmo endpoint de API duas vezes. Ele ignorou sua preferência de ambiente de testes. Ele perdeu o controle de quais testes foram aprovados ontem.

Esta é a realidade da construção de agentes hoje. A maioria das equipes remenda pipelines RAG, bancos de dados vetoriais e sistemas de memória personalizados. O resultado: contexto fragmentado, custos de tokens exorbitantes e recuperação que falha silenciosamente.

Os dados comprovam isso. Em testes de benchmark usando o conjunto de dados LoCoMo10, sistemas RAG tradicionais atingiram apenas 35-44% de taxas de conclusão de tarefas enquanto consumiam 24-51 milhões de tokens de entrada.

OpenViking adota uma abordagem diferente. Criado pela equipe OpenViking da ByteDance, ele substitui o armazenamento vetorial plano por um paradigma de sistema de arquivos. Todo o contexto reside sob URIs viking:// com carregamento hierárquico L0/L1/L2. O resultado: 52% de conclusão de tarefas com 91% menos tokens.

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

O Problema de Contexto do Agente

Agentes de IA enfrentam desafios de contexto que aplicações tradicionais nunca lidaram.

Considere um agente ajudando desenvolvedores a testar APIs. Ao longo de uma semana, ele precisa acompanhar:

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

O RAG tradicional armazena isso como blocos planos em um banco de dados vetorial. Ao consultá-lo, você obtém os fragmentos top-K mais semelhantes, sem estrutura, sem hierarquia e sem visibilidade do que foi perdido.

Cinco Desafios Principais

OpenViking identifica cinco problemas centrais no gerenciamento de contexto do agente:

Isso representa uma mudança de “armazenar tudo, recuperar vagamente” para “estruturar tudo, recuperar com precisão”.

O Que é OpenViking?

OpenViking é um banco de dados de contexto de código aberto para agentes de IA, criado pela equipe OpenViking da ByteDance sob a licença Apache 2.0.

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

viking://
├── resources/              # Conhecimento externo: docs, código, páginas web
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/                   # Específico do usuário: preferências, hábitos
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/                  # Capacidades do agente: habilidades, memórias de tarefas
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/

Agentes adquirem capacidades diretas de manipulação de contexto:

• Navegar em diretórios com ls viking://resources/my_project/docs/
• Buscar semanticamente com find "métodos de autenticação"
• Ler conteúdo completo com read viking://resources/docs/auth.md
• Obter resumos rápidos com abstract viking://resources/docs/
• Obter uma visão geral detalhada com overview viking://resources/docs/

Pense nisso como a diferença entre pesquisar todo o seu disco rígido e saber exatamente qual diretório contém o arquivo.

Recurso Principal 1: Paradigma de Gerenciamento de Sistema de Arquivos

O paradigma de sistema de arquivos resolve a fragmentação de contexto unificando todos os tipos de contexto sob um único modelo.

Três Tipos de Contexto

Cada tipo reside em seu próprio diretório:

• viking://resources/: Manuais de produtos, repositórios de código, documentação
• viking://user/memories/: Preferências do usuário, memórias de entidades, eventos
• viking://agent/skills/: Definições de ferramentas, configurações de MCP
• viking://agent/memories/: Padrões aprendidos, estudos de caso

API tipo Unix

OpenViking oferece operações de linha de comando familiares:

from openviking import OpenViking

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

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

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

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

# Obter resumo rápido (camada L0)
abstract = client.abstract("viking://resources/docs/")

# Obter visão geral detalhada (camada L1)
overview = client.overview("viking://resources/docs/")

A API funciona através do SDK Python ou servidor HTTP, compatível com qualquer framework de agente.

Recurso Principal 2: Carregamento Hierárquico de Contexto L0/L1/L2

Encher prompts com contexto massivo é caro e propenso a erros. OpenViking processa automaticamente todo o contexto em três camadas hierárquicas:

Como Funciona

Quando você adiciona um recurso (como um arquivo de documentação PDF), OpenViking:

1. Analisa o documento em texto (nenhuma chamada LLM ainda)
2. Constrói uma estrutura de árvore de diretórios no armazenamento AGFS
3. Enfileira o processamento semântico assincronamente
4. Gera resumos L0 e visões gerais L1 de baixo para cima

O resultado é uma estrutura hierárquica:

viking://resources/my_project/
├── .abstract.md               # L0: "Documentação de API cobrindo autenticação, endpoints, limites de taxa"
├── .overview.md               # L1: Resumo detalhado com navegação por seção
├── docs/
│   ├── .abstract.md          # Cada diretório tem L0/L1
│   ├── .overview.md
│   ├── auth.md               # L2: Conteúdo completo
│   ├── endpoints.md
│   └── rate-limits.md
└── src/
    └── ...

Impacto no Orçamento de Tokens

Esta hierarquia permite economias significativas de custo:

# RAG Tradicional: Carrega todo o conteúdo
full_docs = retrieve_all("autenticação")  # 50k tokens

# OpenViking: Começa com L1, carrega L2 apenas se necessário
overview = client.overview("viking://resources/docs/auth/")  # 2k tokens

if needs_more_detail(overview):
    content = client.read("viking://resources/docs/auth/oauth.md")  # Carrega L2 específico

Em testes de benchmark, esta abordagem reduziu os custos de tokens de entrada em 91% em comparação com o RAG tradicional, enquanto melhorava as taxas de conclusão de tarefas em 43%.

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

A busca vetorial única tem dificuldades com consultas complexas. OpenViking implementa uma estratégia de recuperação recursiva de diretório:

O Processo de Cinco Etapas

1. Análise de Intenção
   ↓
2. Posicionamento Inicial (encontrar diretórios com alta pontuação)
   ↓
3. Exploração Refinada (buscar dentro de diretórios)
   ↓
4. Descida Recursiva (detalhar subdiretórios)
   ↓
5. Agregação de Resultados (retornar contextos classificados)

Passo 1: Análise de Intenção

A consulta “como autentico usuários?” é analisada para identificar:

• Tipo de intenção: pergunta procedural de como fazer
• Entidades chave: “autenticar”, “usuários”
• Conteúdo esperado: guias de autenticação, fluxos OAuth

Passo 2: Posicionamento Inicial

A busca vetorial localiza rapidamente diretórios com alta pontuação:

• viking://resources/docs/auth/ (pontuação: 0.92)
• viking://resources/docs/security/ (pontuação: 0.78)

Passo 3: Exploração Refinada

Dentro do diretório principal, uma busca secundária encontra arquivos específicos:

• viking://resources/docs/auth/oauth.md (pontuação: 0.95)
• viking://resources/docs/auth/jwt.md (pontuação: 0.88)

Passo 4: Descida Recursiva

Se existirem subdiretórios (como auth/providers/), o processo se repete recursivamente.

Passo 5: Agregação de Resultados

Os resultados finais são agregados e classificados por relevância, com rastros de recuperação preservados.

Esta estratégia de “bloquear o diretório primeiro, depois explorar o conteúdo” melhora a precisão da recuperação ao compreender o contexto completo da informação, não apenas pedaços isolados.

Recurso Principal 4: Rastros de Recuperação Visualizados

O RAG tradicional é uma caixa preta. Quando a recuperação falha, você não consegue dizer se é um problema de similaridade vetorial, um problema de chunking ou dados ausentes.

A estrutura do sistema de arquivos do OpenViking torna a recuperação observável:

Rastro de Recuperação para consulta: "refresh de token OAuth"

├── viking://resources/docs/
│   ├── [PONTUAÇÃO: 0.45] .abstract.md: ignorado (baixa relevância)
│   └── [PONTUAÇÃO: 0.89] auth/: selecionado (alta relevância)
│       ├── [PONTUAÇÃO: 0.92] oauth.md: RETORNADO
│       ├── [PONTUAÇÃO: 0.34] jwt.md: ignorado
│       └── [PONTUAÇÃO: 0.78] providers/
│           └── [PONTUAÇÃO: 0.85] google.md: RETORNADO

Este rastro mostra:

• Quais diretórios foram visitados
• Por que certos arquivos foram selecionados ou ignorados
• O caminho exato que a recuperação seguiu

Para depuração, isso é inestimável. Você pode ver se o agente perdeu o contexto porque estava no diretório errado, tinha um resumo L0 ruim ou ficou abaixo do limiar de pontuação.

Recurso Principal 5: Gerenciamento Automático de Sessão

OpenViking possui um loop de autoiteração de memória integrado. Ao final de cada sessão, o sistema pode extrair memórias e atualizar o conhecimento do agente automaticamente.

Seis Categorias de Memória

Como a Extração de Memória Funciona

# Iniciar uma sessão
session = client.session()

# Adicionar mensagens (turnos de conversa)
await session.add_message("user", [{"type": "text", "text": "Prefiro o modo escuro na interface do usuário"}])
await session.add_message("assistant", [{"type": "text", "text": "Entendi. Usarei o modo escuro para todas as capturas de tela futuras."}])

# Registrar uso de ferramenta
await session.add_usage({
    "tool": "screenshot",
    "parameters": {"theme": "dark"},
    "result": "success"
})

# Confirmar a sessão: aciona a extração de memória
await session.commit()

Quando confirmada, o OpenViking:

1. Compacta a sessão (mantém os N turnos recentes, arquiva os mais antigos)
2. Extrai memórias usando análise LLM
3. Atualiza os diretórios de memória apropriados
4. Gera L0/L1 para novo conteúdo de memória

Isso torna os agentes mais inteligentes com o uso: eles aprendem as preferências do usuário, acumulam experiência em tarefas e melhoram a tomada de decisões ao longo do tempo.

Visão Geral da Arquitetura

A arquitetura do sistema OpenViking separa as preocupações em várias camadas:

Armazenamento de Dupla Camada

OpenViking separa conteúdo de índice:

Esta separação garante:

• Todas as leituras de conteúdo vêm de uma única fonte (AGFS)
• O índice vetorial armazena apenas referências leves
• Nenhuma duplicação de grandes blocos de texto no armazenamento vetorial

Início Rápido: Implante Seu Primeiro Servidor OpenViking

Pré-requisitos

• Python: 3.10 ou superior
• Go: 1.22+ (para componentes AGFS)
• Compilador C++: GCC 9+ ou Clang 11+
• SO: Linux, macOS ou Windows

Passo 1: Instalar OpenViking

pip install openviking --upgrade --force-reinstall

Opcionalmente, instale o CLI Rust para acesso via terminal:

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

Passo 2: Configurar Modelos

OpenViking requer duas capacidades de modelo:

• Modelo VLM: Para compreensão de imagens e conteúdo
• Modelo de Embedding: Para vetorização e busca semântica

Crie ~/.openviking/ov.conf:

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

Provedores Suportados:

O suporte LiteLLM significa que você pode usar modelos Anthropic, Google, Ollama local ou qualquer endpoint compatível com OpenAI.

Passo 3: Iniciar o Servidor

openviking-server

Ou rodar em segundo plano:

nohup openviking-server > /data/log/openviking.log 2>&1 &

Passo 4: Adicionar Seu Primeiro Recurso

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

# Ou usando o SDK Python
from openviking import OpenViking

client = OpenViking(path="./data")
client.add_resource("https://docs.example.com/api-guide.pdf")

Passo 5: Buscar e Recuperar

# Espere pelo processamento semântico, depois busque
ov find "métodos de autenticação"

# Listar conteúdo do diretório
ov ls viking://resources/

# Visualizar árvore de diretórios
ov tree viking://resources/docs -L 2

# Pesquisar por conteúdo específico
ov grep "OAuth" --uri viking://resources/docs/

Passo 6: Habilitar VikingBot (Opcional)

VikingBot é um framework de agente de IA construído sobre OpenViking:

pip install "openviking[bot]"

# Iniciar servidor com bot habilitado
openviking-server --with-bot

# Em outro terminal, iniciar chat interativo
ov chat

Benchmarks de Desempenho

OpenViking foi comparado com RAG tradicional (LanceDB) e sistemas de memória nativa usando o conjunto de dados LoCoMo10 (1.540 casos de diálogo de longo alcance).

Taxas de Conclusão de Tarefas

Principais Descobertas

• Melhoria de 43% sobre a memória nativa com redução de 91% de tokens
• Melhoria de 17% sobre LanceDB com redução de 92% de tokens
• A recuperação hierárquica do OpenViking encontrou contexto mais relevante enquanto consumia menos tokens

Esses resultados vêm da integração do OpenViking como um plugin com o OpenClaw, um assistente de codificação de IA de código aberto. O conjunto de dados de teste foi baseado em diálogos de longo alcance onde a retenção de memória é crítica.

Integrando OpenViking com Apidog

Usuários Apidog que constroem agentes de IA para testes de API podem aproveitar o OpenViking para manter o contexto da conversa, armazenar a documentação da API e lembrar as preferências do usuário entre as sessões.

Passo 1: Configurar Servidor OpenViking

Siga o início rápido acima para implantar o OpenViking com seus modelos VLM e de embedding preferidos.

Passo 2: Importar Documentação da API Apidog

# Adicione a documentação do seu projeto Apidog como um recurso
ov add-resource https://docs.apidog.com/overview
ov add-resource https://docs.apidog.com/api-testing

Isso importa a documentação Apidog para viking://resources/ com processamento automático L0/L1/L2.

Passo 3: Armazenar Preferências do Usuário

from openviking import OpenViking

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

# Registrar a preferência de ambiente padrão do usuário
await session.add_message("user", [{
    "type": "text",
    "text": "Sempre use o ambiente de testes para testes de API"
}])
await session.commit()  # Extrai memória de preferência automaticamente

Passo 4: Consultar Contexto Durante os Testes

# Encontre endpoints de API relevantes antes de executar os testes
results = client.find("endpoints de autenticação")
for ctx in results.resources:
    print(f"Encontrado: {ctx.uri}")

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

Passo 5: Conectar ao Seu Framework de Agente

OpenViking expõe tanto o SDK Python quanto a API HTTP:

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

# Ou 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"}
)

Técnicas Avançadas e Melhores Práticas

Dicas Pro para Implantações em Produção

1. Pré-aquecer Contexto Acessado Frequentemente

Carregue a documentação crítica em L0/L1 durante horários de pico para reduzir a latência durante as operações do agente.

# Acionar processamento semântico imediatamente
ov add-resource https://docs.example.com --wait

2. Implementar Expiração de Contexto

Configure a limpeza automática para dados de sessão obsoletos:

# Arquivar sessões com mais de 7 dias
await session.archive(max_age_days=7)

3. Monitorar a Saúde do Índice Vetorial

Acompanhar o tamanho do índice e a latência da consulta:

ov debug stats

Erros Comuns a Evitar

1. Carregar conteúdo L2 prematuramente: Sempre comece com L0/L1 para economizar tokens
2. Pular confirmações de sessão: A extração de memória só ocorre na confirmação
3. Sobrecarga de diretórios únicos: Divida grandes recursos em subdiretórios baseados em tópicos
4. Ignorar rastros de recuperação: Use rastros visualizados para depurar resultados ruins

Otimização de Desempenho

Melhores Práticas de Segurança

• Armazene chaves de API em variáveis de ambiente ou gerenciadores de segredos (nunca em arquivos de configuração)
• Habilite HTTPS para todas as implantações de servidor HTTP
• Implemente limite de taxa em endpoints públicos
• Use chaves de API separadas para desenvolvimento e produção

Casos de Uso no Mundo Real

1. Assistentes de Codificação de IA

Uma equipe de desenvolvimento integrou o OpenViking com seu assistente de codificação interno. O agente agora:

• Navega pela estrutura do projeto via viking://resources/my_project/src/
• Lembra as preferências de codificação do usuário (convenções de nomenclatura, frameworks de teste)
• Recupera documentação de API relevante durante a geração de código

Resultado: Redução de 67% em comportamentos de agente “esquecidos”, 43% de economia de custo de tokens.

2. Agentes de Suporte ao Cliente

Uma empresa SaaS implantou o OpenViking para seu chatbot de suporte:

• Documentação do produto armazenada em viking://resources/product/
• Histórico de conversas do cliente em viking://user/memories/past_issues/
• Playbooks de suporte como habilidades em viking://agent/skills/

Resultado: A resolução no primeiro contato melhorou de 52% para 71%.

3. Assistentes de Pesquisa

Um laboratório de pesquisa usa o OpenViking para organizar artigos e notas:

• Artigos categorizados por tópico (viking://resources/papers/nlp/)
• Metodologias de pesquisa armazenadas como habilidades
• Extração automática de descobertas chave para a memória

Resultado: Pesquisadores encontram artigos relevantes 3x mais rápido com busca semântica.

Alternativas e Comparações

OpenViking não é a única solução de gerenciamento de contexto. Veja como ele se compara às alternativas:

OpenViking vs. Bancos de Dados Vetoriais Tradicionais

OpenViking vs. Memória LangChain

Quando Considerar Alternativas

Use bancos de dados vetoriais tradicionais se:

• Você precisa de latência de recuperação abaixo de 100ms
• Seu caso de uso é uma busca simples por palavras-chave
• Você já tem um pipeline RAG funcionando sem problemas

Use OpenViking se:

• Você está construindo conversas de agente de longa duração
• Você precisa de contexto multi-tipo (documentos + preferências + ferramentas)
• A otimização de custo de tokens é importante
• Você quer recuperação observável e depurável

Comparação com RAG Tradicional

Implantação em Produção

Para ambientes de produção, execute o OpenViking como um serviço HTTP autônomo:

Infraestrutura Recomendada

• Nuvem: Volcengine ECS ou equivalente
• SO: veLinux ou Ubuntu 22.04+
• Armazenamento: Volume com suporte SSD para AGFS
• Rede: Conexão de baixa latência para APIs de modelos

Considerações de Segurança

• Armazene chaves de API em variáveis de ambiente ou gerenciador de segredos
• Habilite autenticação para endpoints HTTP
• Use HTTPS para toda comunicação cliente-servidor
• Implemente limite de taxa para prevenir abuso

Monitoramento

OpenViking suporta registro de logs e métricas:

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

Monitorar:

• Profundidade da fila de processamento semântico
• Latência da busca vetorial
• Operações de leitura/escrita AGFS
• Taxas de sucesso de extração de memória

Limitações e Considerações

Limitações Atuais

• Focado em Python: O SDK principal é Python; outras linguagens requerem integração HTTP
• Dependências de modelo: Requer modelos VLM e de embedding externos (sem inferência integrada)
• Curva de aprendizado: O paradigma de sistema de arquivos é diferente dos DBs vetoriais tradicionais
• Estágio inicial: O projeto está em desenvolvimento ativo; as APIs podem mudar

Quando Usar OpenViking

Boa opção:

• Conversas de agente de longa duração que requerem memória
• Contexto multi-tipo (documentos + preferências + ferramentas)
• Necessidade de recuperação observável e depurável
• A otimização de custo de tokens é importante

Considere alternativas:

• Aplicações simples de Q&A de uma única vez
• Já tem um pipeline RAG funcionando sem problemas
• Precisa de latência de recuperação abaixo de 100ms (OpenViking adiciona sobrecarga de processamento)

O Caminho a Seguir

OpenViking está em desenvolvimento inicial (versão 0.1.x a partir do início de 2025). O roteiro inclui:

• Suporte multi-tenant: Workspaces isolados para equipes
• Análise avançada: Métricas de qualidade de recuperação, dashboards de uso de memória
• Ecossistema de plugins: Integrações pré-construídas com frameworks de agente populares
• Implantação Edge: Modo leve para aplicações local-first
• Suporte MCP aprimorado: Integração nativa do Model Context Protocol

A equipe por trás do OpenViking está buscando ativamente contribuidores da comunidade. O projeto é de código aberto sob a licença Apache 2.0, com documentação disponível.

Conclusão

OpenViking representa uma mudança na forma como os agentes de IA gerenciam o contexto. Ao organizar informações como um sistema de arquivos em vez de blocos planos, ele resolve a fragmentação, o desperdício de tokens e a recuperação de caixa preta que assolam os sistemas RAG tradicionais.

Principais Pontos

• O paradigma do sistema de arquivos unifica o contexto: Todas as memórias, recursos e habilidades sob URIs viking://
• O carregamento L0/L1/L2 reduz os tokens em 91%: Carregamento progressivo em vez de despejar tudo em prompts
• A recuperação recursiva de diretório aumenta a precisão: Bloqueie diretórios de alta pontuação primeiro, depois explore o conteúdo
• Rastros visualizados permitem a depuração: Veja exatamente quais caminhos a recuperação seguiu
• O gerenciamento automático de sessão permite o aprendizado: Agentes extraem memórias de cada conversa