DEV Community

Cover image for ¿Qué es OpenViking?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Qué es OpenViking?

#ai #database #opensource #rag

En resumen

OpenViking es una base de datos de contexto de código abierto para agentes de IA que reemplaza el almacenamiento de vectores planos con un paradigma de sistema de archivos. Organiza el contexto (memorias, recursos, habilidades) bajo URIs viking:// en tres capas: L0 (~100 tokens), L1 (~2k tokens), L2 (contenido completo). Los benchmarks muestran una reducción del 91% en el coste de tokens y una mejora del 43% en la finalización de tareas frente al RAG tradicional.

Prueba Apidog hoy

Introducción

Tu agente de IA sigue olvidando cosas. Pidió el mismo endpoint de API dos veces. Ignoró tu preferencia de entorno de staging. Perdió el rastro de qué pruebas pasaron ayer.

Actualmente, la mayoría de los equipos ensamblan pipelines de RAG, bases de datos vectoriales y sistemas de memoria personalizados. Resultado: contexto fragmentado, costes de tokens altos y procesos de recuperación poco fiables.

Los datos lo confirman. En pruebas con el dataset LoCoMo10, los sistemas RAG tradicionales lograron solo tasas de finalización de tareas del 35-44% consumiendo entre 24 y 51 millones de tokens de entrada.

OpenViking adopta un enfoque diferente. Reemplaza el almacenamiento de vectores planos por un sistema de archivos, alojando todo el contexto bajo URIs viking:// con carga jerárquica L0/L1/L2. Resultado: 52% de finalización de tareas con un 91% menos de tokens.

💡 Los usuarios de Apidog que construyen agentes de prueba de API pueden integrar OpenViking para mantener el contexto conversacional entre ejecuciones de prueba, recordar preferencias de entorno y almacenar documentación de API para recuperación semántica.

En esta guía, verás cómo OpenViking resuelve la fragmentación del contexto, el modelo L0/L1/L2 en acción y cómo desplegar tu primer servidor en 15 minutos.

El Problema del Contexto del Agente

Los agentes de IA enfrentan retos de contexto que las apps tradicionales no tenían:

  • Preferencias del usuario (“entorno de staging”, “curl en lugar de Python”)
  • Contexto del proyecto (endpoints, métodos de autenticación, resultados de pruebas)
  • Patrones de herramientas (endpoints fallidos, errores comunes)
  • Historial de tareas (qué se probó, qué errores surgieron)

El RAG tradicional almacena esto como fragmentos planos en una base de datos vectorial, devolviendo los K fragmentos más similares sin estructura ni jerarquía.

Cinco Desafíos Principales

Desafío RAG Tradicional Solución OpenViking
Contexto Fragmentado Memorias, recursos, habilidades dispersas Sistema de archivos unificado bajo viking://
Demanda Creciente Tareas largas → contexto masivo Carga jerárquica L0/L1/L2 (reduce tokens 91%)
Recuperación Deficiente Búsqueda plana sin visión global Recuperación recursiva de directorios
Inobservable Recuperación de caja negra Trazas visuales de recorrido
Iteración Limitada Solo histórico de usuario Gestión automática de sesiones (6 tipos de memoria)

El cambio es de “almacenar todo, recuperar vagamente” a “estructurar y recuperar con precisión”.

¿Qué es OpenViking?

OpenViking es una base de datos de contexto open source para agentes de IA, creada por ByteDance bajo Apache 2.0.

Arquitectura de OpenViking mostrando los componentes de agentes de IA, SDK, API HTTP y almacenamiento AGFS

Centraliza el contexto en un sistema de archivos virtual. Memorias, recursos y habilidades se mapean a directorios bajo viking://, cada uno con un URI único:

viking://
├── resources/              # Documentos, código, páginas web
├── user/                   # Preferencias, hábitos
└── agent/                  # Habilidades, memorias de tareas
Enter fullscreen mode Exit fullscreen mode

Operaciones clave:

  • Navegar directorios: ls viking://resources/my_project/docs/
  • Búsqueda semántica: find "métodos de autenticación"
  • Leer contenido: read viking://resources/docs/auth.md
  • Resúmenes rápidos: abstract viking://resources/docs/

Característica Clave 1: Paradigma de Sistema de Archivos

El sistema de archivos unifica todos los tipos de contexto en un solo modelo.

Tres Tipos de Contexto

Tipo Propósito Ciclo de Vida Iniciativa
Recurso Docs, código, FAQs Largo plazo, estático Usuario añade
Memoria Preferencias, experiencias Largo plazo, dinámico Agente extrae
Habilidad Herramientas, MCP Largo plazo, estático Agente invoca

Ejemplo de directorios:

  • viking://resources/: Documentos, código
  • viking://user/memories/: Preferencias, eventos
  • viking://agent/skills/: Herramientas, configuraciones

API tipo Unix 

from openviking import OpenViking

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

results = client.find("autenticación de usuario")
contents = client.ls("viking://resources/")
doc = client.read("viking://resources/docs/auth.md")
abstract = client.abstract("viking://resources/docs/")
overview = client.overview("viking://resources/docs/")
Enter fullscreen mode Exit fullscreen mode

Funciona vía SDK de Python o servidor HTTP, compatible con cualquier framework de agente.

Característica Clave 2: Carga Jerárquica de Contexto L0/L1/L2

Introducir contexto masivo es costoso. OpenViking procesa el contexto en tres capas:

Capa Nombre Archivo Tokens aprox Propósito
L0 Resumen .abstract.md ~100 Búsqueda rápida
L1 Vista Gral. .overview.md ~2k Navegación, reclasificación
L2 Detalle Archivos originales Ilimitado Contenido completo bajo demanda

Cómo funciona:

  1. Analiza el documento (sin LLM)
  2. Construye árbol de directorios AGFS
  3. Encola procesamiento semántico asíncrono
  4. Genera L0 y L1 de abajo a arriba

Ejemplo de estructura:

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

Ahorro de tokens:

# RAG tradicional
full_docs = retrieve_all("autenticación")  # 50k tokens

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

En benchmarks, redujo el coste de tokens de entrada un 91% y mejoró la finalización de tareas un 43%.

Característica Clave 3: Recuperación Recursiva de Directorios

OpenViking usa recuperación recursiva para búsquedas complejas:

1. Análisis de Intención
2. Posicionamiento Inicial (directorios relevantes)
3. Exploración Refinada (archivos dentro)
4. Descenso Recursivo (subdirectorios)
5. Agregación de Resultados (clasificados)
Enter fullscreen mode Exit fullscreen mode

Ejemplo de traza para "¿cómo autentico usuarios?":

├── viking://resources/docs/
│   └── auth/: seleccionado
│       ├── oauth.md: DEVUELTO
│       └── jwt.md: omitido
Enter fullscreen mode Exit fullscreen mode

Así, la recuperación es precisa, jerárquica y trazable.

Característica Clave 4: Trazas de Recuperación Visualizadas

La recuperación deja trazas detalladas:

Traza de Recuperación para: "actualización de token OAuth"

├── viking://resources/docs/
│   ├── [PUNTUACIÓN: 0.45] .abstract.md: omitido
│   └── [PUNTUACIÓN: 0.89] auth/: seleccionado
│       ├── [PUNTUACIÓN: 0.92] oauth.md: DEVUELTO
│       └── [PUNTUACIÓN: 0.85] providers/google.md: DEVUELTO
Enter fullscreen mode Exit fullscreen mode

Esto permite depuración: ves qué directorios y archivos fueron relevantes o ignorados.

Característica Clave 5: Gestión Automática de Sesiones

OpenViking incluye bucle de auto-iteración de memoria. Al final de cada sesión, extrae memorias y actualiza el conocimiento del agente.

Seis Categorías de Memoria

Categoría Propietario Ubicación Descripción Estrategia
perfil usuario user/memories/.overview.md Información básica Añadible
preferencias usuario user/memories/preferences/ Preferencias Añadible
entidades usuario user/memories/entities/ Personas, proyectos Añadible
eventos usuario user/memories/events/ Decisiones, hitos No actualiza
casos agente agent/memories/cases/ Casos aprendidos No actualiza
patrones agente agent/memories/patterns/ Patrones aprendidos No actualiza

Extracción de memoria:

session = client.session()
await session.add_message("usuario", [{"type": "text", "text": "Prefiero el modo oscuro"}])
await session.add_message("asistente", [{"type": "text", "text": "Entendido."}])
await session.add_usage({"tool": "captura_de_pantalla", "parameters": {"theme": "oscuro"}, "result": "éxito"})
await session.commit()
Enter fullscreen mode Exit fullscreen mode

Al confirmar, se comprime la sesión, extraen memorias, se actualizan directorios y se generan L0/L1.

Visión General de la Arquitectura

Diagrama de arquitectura de OpenViking

OpenViking separa contenido e índice:

Capa Tecnología Almacena
AGFS Sistema de archivos custom L0/L1/L2, multimedia, relaciones
Índice Vectorial Base de datos vectorial URIs, embeddings, metadatos

Lecturas de contenido: siempre de AGFS. El vectorial solo almacena referencias ligeras.

Inicio Rápido: Despliega Tu Primer Servidor OpenViking

Requisitos Previos

  • Python: 3.10+
  • Go: 1.22+ (AGFS)
  • C++: GCC 9+ o Clang 11+
  • SO: Linux, macOS o Windows

Paso 1: Instala OpenViking 

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

Opcional: CLI de Rust:

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

Paso 2: Configura Modelos

Crea ~/.openviking/ov.conf:

{
  "storage": {
    "workspace": "/home/tu-nombre/espacio_de_trabajo_openviking"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "tu-clave-api-openai",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "tu-clave-api-openai",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}
Enter fullscreen mode Exit fullscreen mode

Proveedores compatibles:

Proveedor Modelos de Embedding Modelos VLM
volcengine doubao-embedding-vision doubao-seed-2.0-pro
openai text-embedding-3-large gpt-4o, gpt-4-vision
litellm Proxy LiteLLM Claude, Gemini, etc.

Paso 3: Inicia el Servidor 

openviking-server
Enter fullscreen mode Exit fullscreen mode

O en segundo plano:

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

Paso 4: Añade Tu Primer Recurso 

# 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

Paso 5: Buscar y Recuperar 

ov find "métodos de autenticación"
ov ls viking://resources/
ov tree viking://resources/docs -L 2
ov grep "OAuth" --uri viking://resources/docs/
Enter fullscreen mode Exit fullscreen mode

Paso 6: Habilitar VikingBot (Opcional) 

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

Puntos de Referencia de Rendimiento

OpenViking fue comparado con RAG tradicional (LanceDB) y memoria nativa usando LoCoMo10.

Tasas de Finalización de Tareas

Sistema Tasa de Finalización Tokens Entrada
OpenClaw (memoria nativa) 35.65% 24.6M
OpenClaw + LanceDB 44.55% 51.6M
OpenClaw + OpenViking 52.08% 4.3M

Hallazgos:

  • 43% mejora sobre memoria nativa, 91% menos tokens
  • 17% mejor que LanceDB, 92% menos tokens
  • Recuperación jerárquica = contexto más relevante con menos tokens

Integrando OpenViking con Apidog

Los usuarios de Apidog pueden usar OpenViking para mantener contexto de conversación, almacenar documentación de API y preferencias de usuario entre sesiones.

Diagrama de integración de Apidog con OpenViking

Paso 1: Configurar el Servidor OpenViking

Sigue el inicio rápido para desplegar OpenViking con tus modelos preferidos.

Paso 2: Importar la Documentación de la API de 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

Esto importa la documentación a viking://resources/ con procesamiento automático L0/L1/L2.

Paso 3: Almacenar Preferencias del Usuario 

from openviking import OpenViking

client = OpenViking(path="./datos-agente-apidog")
session = client.session()

await session.add_message("usuario", [{
    "type": "text",
    "text": "Siempre usa el entorno de staging para las pruebas de API"
}])
await session.commit()
Enter fullscreen mode Exit fullscreen mode

Paso 4: Consultar el Contexto Durante las Pruebas 

results = client.find("endpoints de autenticación")
for ctx in results.resources:
    print(f"Encontrado: {ctx.uri}")

prefs = client.find("preferencia de entorno de staging", target_uri="viking://user/memories/")
Enter fullscreen mode Exit fullscreen mode

Paso 5: Conectar a Tu Framework de Agente 

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

# O API HTTP
import httpx
response = httpx.post(
    "http://localhost:1933/api/v1/search/find",
    json={"query": "endpoints de autenticación"},
    headers={"X-API-Key": "tu-clave-api"}
)
Enter fullscreen mode Exit fullscreen mode

Técnicas Avanzadas y Mejores Prácticas

Consejos para Producción

1. Precalentar contexto frecuentemente accedido

ov add-resource https://docs.example.com --wait
Enter fullscreen mode Exit fullscreen mode

2. Implementar expiración de contexto

await session.archive(max_age_days=7)
Enter fullscreen mode Exit fullscreen mode

3. Monitorizar salud del índice vectorial

ov debug stats
Enter fullscreen mode Exit fullscreen mode

Errores Comunes a Evitar

  1. No cargar L2 antes de L0/L1
  2. Confirmar sesiones para extraer memoria
  3. No sobrecargar directorios individuales
  4. Usar trazas para depuración de recuperaciones pobres

Optimización de Rendimiento

Escenario Recomendación
Gran volumen consultas Servidor HTTP con pooling
Documentos grandes Dividir en fragmentos temáticos
Baja latencia Pre-generar L0/L1 para contenido crítico
Multi-inquilino Usar workspaces separados

Seguridad

  • Claves API en variables de entorno
  • Habilitar HTTPS en despliegues HTTP
  • Limitación de tasas en endpoints públicos
  • Claves API separadas para dev/prod

Casos de Uso en el Mundo Real

1. Asistentes de Codificación de IA

  • Navegación por estructura de proyecto (viking://resources/my_project/src/)
  • Recuerdo de preferencias del usuario
  • Recuperación de documentación relevante

Resultado: 67% menos olvidos, 43% ahorro en tokens.

2. Agentes de Soporte al Cliente

  • Docs en viking://resources/product/
  • Historial en viking://user/memories/past_issues/
  • Manuales de soporte como habilidades

Resultado: Resolución en primer contacto 52% → 71%.

3. Asistentes de Investigación

  • Artículos en viking://resources/papers/nlp/
  • Metodologías como habilidades
  • Extracción automática de hallazgos

Resultado: 3x más rápido encontrar artículos relevantes.

Alternativas y Comparaciones

OpenViking vs. Bases Vectoriales Tradicionales

Aspecto RAG Tradicional OpenViking
Modelo de almacenamiento Fragmentos planos Sistema de archivos jerárquico
Recuperación Similitud Top-K Recursivo + análisis de intención
Observabilidad Caja negra Trazas visuales
Eficiencia de tokens Cargar todo/truncar Carga progresiva L0/L1/L2
Iteración de memoria Manual/nula Gestión automática de sesiones
Tipos de contexto Solo documentos Recursos, memorias, habilidades
Depuración Adivinación Registros de recorrido de directorios

OpenViking vs. Memoria de LangChain

Aspecto Memoria de LangChain OpenViking
Persistencia Solo buffer de conversación Sistema de archivos
Escalabilidad Limitado por contexto Carga jerárquica
Recuperación Lineal Recursivo + semántico
Tipos de memoria Buffer único 6 categorías

¿Cuándo usar alternativas?

Usa bases vectoriales si:

  • Necesitas latencia < 100ms
  • Solo buscas palabras clave
  • Ya tienes un pipeline RAG estable

Usa OpenViking si:

  • Necesitas conversaciones de larga duración
  • Contexto mixto (docs, preferencias, herramientas)
  • Optimización de tokens importa
  • Quieres trazabilidad y depuración

Comparación con RAG Tradicional

Aspecto RAG Tradicional OpenViking
Almacenamiento Fragmentos planos Sistema de archivos
Recuperación Similitud Top-K Recursivo + intención
Observabilidad Caja negra Trazas visuales
Eficiencia de tokens Cargar todo/truncar Carga L0/L1/L2
Iteración de memoria Manual/nula Automática
Tipos de contexto Solo docs Recursos/memorias/habilidades
Depuración Adivinación Registros de recorrido

Despliegue en Producción

Ejecuta OpenViking como servicio HTTP.

Infraestructura Recomendada

  • Nube: Volcengine ECS o similar
  • SO: veLinux o Ubuntu 22.04+
  • Almacenamiento: SSD para AGFS
  • Red: Baja latencia a APIs de modelo

Seguridad

  • Claves API en variables de entorno/secret managers
  • Autenticación en endpoints HTTP
  • HTTPS en toda la comunicación
  • Limitación de tasas

Monitorización

Ejemplo de config de logging:

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

Monitorea: cola semántica, latencia vectorial, operaciones AGFS, éxito de extracción de memoria.

Limitaciones y Consideraciones

Limitaciones

  • SDK principal en Python (otros lenguajes: vía HTTP)
  • Requiere modelos externos (no hay inferencia local)
  • Nuevo paradigma de sistema de archivos
  • Proyecto en desarrollo activo (APIs pueden cambiar)

¿Cuándo usar OpenViking?

Buen ajuste:

  • Conversaciones de larga duración con memoria
  • Contexto mixto (docs, preferencias, herramientas)
  • Necesidad de recuperación observable
  • Optimización de tokens

Alternativas:

  • Apps sencillas de Q&A
  • Pipeline RAG ya funcionando bien
  • Latencia ultra-baja (<100ms)

El Camino a Seguir

OpenViking está en fase temprana (v0.1.x). Roadmap:

  • Soporte multi-inquilino
  • Métricas de recuperación y paneles de memoria
  • Plugins para frameworks de agentes populares
  • Edge deployment
  • Mejor soporte de MCP

Se buscan colaboradores. Código abierto bajo Apache 2.0. Documentación.

Conclusión

OpenViking representa un cambio en la gestión de contexto para agentes de IA. Organizar la información como un sistema de archivos soluciona la fragmentación, el derroche de tokens y la recuperación opaca de los RAG tradicionales.

Puntos Clave

  • Sistema de archivos unificado: Todo bajo viking://
  • Carga L0/L1/L2: Reduce tokens un 91%
  • Recuperación recursiva: Mejor precisión
  • Trazas visuales: Fácil depuración
  • Gestión automática de sesiones: Aprendizaje continuo

Top comments (0)