Qu'est-ce qu'OpenViking ?

En bref

OpenViking est une base de données de contexte open-source pour les agents IA qui remplace le stockage vectoriel plat par un paradigme de système de fichiers. Il organise le contexte (mémoires, ressources, compétences) sous des URI viking:// avec trois couches : L0 (~100 tokens), L1 (~2k tokens), L2 (contenu complet). Les benchmarks montrent une réduction de 91 % du coût des tokens et une amélioration de 43 % de l'achèvement des tâches par rapport au RAG traditionnel.

Introduction

Votre agent IA oublie constamment des choses. Il a demandé le même point de terminaison API deux fois. Il a ignoré votre préférence d'environnement de staging. Il a perdu la trace des tests réussis hier.

C'est la réalité de la construction d'agents aujourd'hui. La plupart des équipes bricolent des pipelines RAG, des bases de données vectorielles et des systèmes de mémoire personnalisés. Le résultat : un contexte fragmenté, des coûts de tokens qui explosent et une récupération qui échoue silencieusement.

Les données le confirment. Lors de tests de référence utilisant le jeu de données LoCoMo10, les systèmes RAG traditionnels n'ont atteint que des taux d'achèvement des tâches de 35 à 44 % tout en consommant 24 à 51 millions de tokens d'entrée.

OpenViking adopte une approche différente. Créé par l'équipe OpenViking de ByteDance, il remplace le stockage vectoriel plat par un paradigme de système de fichiers. Tout le contexte réside sous des URI viking:// avec un chargement hiérarchique L0/L1/L2. Le résultat : un achèvement des tâches de 52 % avec 91 % de tokens en moins.

Dans ce guide, vous apprendrez comment OpenViking résout la fragmentation du contexte, verrez le modèle L0/L1/L2 en action et déploierez votre premier serveur en 15 minutes.

Le problème du contexte des agents

Les agents IA sont confrontés à des défis de contexte que les applications traditionnelles n'ont jamais rencontrés.

Considérez un agent aidant les développeurs à tester des API. Sur une semaine, il doit suivre :

• Préférences de l'utilisateur (« environnement de staging », « curl plutôt que Python »)
• Contexte du projet (points de terminaison, méthodes d'authentification, résultats des tests passés)
• Modèles d'outils (quels points de terminaison échouent, erreurs de schéma courantes)
• Historique des tâches (ce qui a été testé, les bugs apparus)

Le RAG traditionnel stocke cela sous forme de fragments plats dans une base de données vectorielle. Interrogez-le, et vous obtenez les K fragments les plus similaires sans structure, sans hiérarchie et sans visibilité sur ce qui a été manqué.

Cinq défis fondamentaux

OpenViking identifie cinq problèmes fondamentaux dans la gestion du contexte des agents :

Cela représente un passage de « tout stocker, récupérer vaguement » à « tout structurer, récupérer précisément ».

Qu'est-ce qu'OpenViking ?

OpenViking est une base de données de contexte open-source pour les agents IA, créée par l'équipe OpenViking de ByteDance sous licence Apache 2.0.

Il unifie tout le contexte en un système de fichiers virtuel. Les mémoires, ressources et compétences sont mappées à des répertoires sous viking://, chacun avec un URI unique.

viking://
├── resources/              # Connaissances externes : docs, code, pages web
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/                   # Spécifique à l'utilisateur : préférences, habitudes
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/                  # Capacités de l'agent : compétences, mémoires de tâches
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/

Les agents acquièrent des capacités de manipulation directe du contexte :

• Naviguer dans les répertoires avec ls viking://resources/my_project/docs/
• Rechercher sémantiquement avec find "méthodes d'authentification"
• Lire le contenu complet avec read viking://resources/docs/auth.md
• Obtenir des résumés rapides avec abstract viking://resources/docs/

Pensez-y comme la différence entre la recherche sur tout votre disque dur et le fait de savoir exactement quel répertoire contient le fichier.

Fonctionnalité clé 1 : Paradigme de gestion du système de fichiers

Le paradigme du système de fichiers résout la fragmentation du contexte en unifiant tous les types de contexte sous un modèle unique.

Trois types de contexte

Chaque type réside dans son propre répertoire :

• viking://resources/: Manuels produits, dépôts de code, documentation
• viking://user/memories/: Préférences utilisateur, mémoires d'entités, événements
• viking://agent/skills/: Définitions d'outils, configurations MCP
• viking://agent/memories/: Modèles appris, études de cas

API de type Unix

OpenViking fournit des opérations de ligne de commande familières :

from openviking import OpenViking

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

# Recherche sémantique à travers tous les types de contexte
results = client.find("user authentication")

# Lister le contenu du répertoire
contents = client.ls("viking://resources/")

# Lire le contenu complet
doc = client.read("viking://resources/docs/auth.md")

# Obtenir un résumé rapide (couche L0)
abstract = client.abstract("viking://resources/docs/")

# Obtenir un aperçu détaillé (couche L1)
overview = client.overview("viking://resources/docs/")

L'API fonctionne via le SDK Python ou un serveur HTTP, compatible avec tout framework d'agent.

Fonctionnalité clé 2 : Chargement de contexte hiérarchique L0/L1/L2

Empiler un contexte massif dans les prompts est coûteux et sujet aux erreurs. OpenViking traite automatiquement tout le contexte en trois couches hiérarchiques :

Comment ça marche

Lorsque vous ajoutez une ressource (comme un fichier de documentation PDF), OpenViking :

1. Analyse le document en texte (pas encore d'appels LLM)
2. Construit une structure arborescente de répertoires dans le stockage AGFS
3. Met en file d'attente le traitement sémantique de manière asynchrone
4. Génère des résumés L0 et des aperçus L1 de bas en haut

Le résultat est une structure hiérarchique :

viking://resources/my_project/
├── .abstract.md               # L0 : "Documentation API couvrant l'authentification, les points de terminaison, les limites de débit"
├── .overview.md               # L1 : Résumé détaillé avec navigation par section
├── docs/
│   ├── .abstract.md          # Chaque répertoire a L0/L1
│   ├── .overview.md
│   ├── auth.md               # L2 : Contenu complet
│   ├── endpoints.md
│   └── rate-limits.md
└── src/
    └── ...

Impact sur le budget de tokens

Cette hiérarchie permet des économies significatives :

# RAG traditionnel : Charger tout le contenu
full_docs = retrieve_all("authentication")  # 50k tokens

# OpenViking : Commencer avec L1, charger L2 uniquement si nécessaire
overview = client.overview("viking://resources/docs/auth/")  # 2k tokens

if needs_more_detail(overview):
    content = client.read("viking://resources/docs/auth/oauth.md")  # Charger un L2 spécifique

Lors des tests de référence, cette approche a réduit les coûts de tokens d'entrée de 91 % par rapport au RAG traditionnel tout en améliorant les taux d'achèvement des tâches de 43 %.

Fonctionnalité clé 3 : Récupération récursive de répertoire

La recherche vectorielle simple a du mal avec les requêtes complexes. OpenViking met en œuvre une stratégie de récupération récursive de répertoire :

Le processus en cinq étapes

1. Intent Analysis
   ↓
2. Initial Positioning (find high-score directories)
   ↓
3. Refined Exploration (search within directories)
   ↓
4. Recursive Descent (drill into subdirectories)
   ↓
5. Result Aggregation (return ranked contexts)

Étape 1 : Analyse de l'intention

La requête « comment authentifier les utilisateurs ? » est analysée pour identifier :

• Type d'intention : question procédurale de type « comment faire »
• Entités clés : « authentifier », « utilisateurs »
• Contenu attendu : guides d'authentification, flux OAuth

Étape 2 : Positionnement initial

La recherche vectorielle localise rapidement les répertoires à score élevé :

• viking://resources/docs/auth/ (score : 0,92)
• viking://resources/docs/security/ (score : 0,78)

Étape 3 : Exploration raffinée

Dans le répertoire supérieur, une recherche secondaire trouve des fichiers spécifiques :

• viking://resources/docs/auth/oauth.md (score : 0,95)
• viking://resources/docs/auth/jwt.md (score : 0,88)

Étape 4 : Descente récursive

Si des sous-répertoires existent (comme auth/providers/), le processus se répète de manière récursive.

Étape 5 : Agrégation des résultats

Les résultats finaux sont agrégés et classés par pertinence, avec les traces de récupération conservées.

Cette stratégie « verrouiller le répertoire d'abord, puis explorer le contenu » améliore la précision de la récupération en comprenant le contexte complet de l'information, et non pas seulement des fragments isolés.

Fonctionnalité clé 4 : Traces de récupération visualisées

Le RAG traditionnel est une boîte noire. Lorsque la récupération échoue, vous ne pouvez pas savoir s'il s'agit d'un problème de similarité vectorielle, d'un problème de découpage ou de données manquantes.

La structure de système de fichiers d'OpenViking rend la récupération observable :

Trace de récupération pour la requête : "Actualisation du token OAuth"

├── viking://resources/docs/
│   ├── [SCORE: 0.45] .abstract.md : ignoré (faible pertinence)
│   └── [SCORE: 0.89] auth/ : sélectionné (haute pertinence)
│       ├── [SCORE: 0.92] oauth.md : RENVOYÉ
│       ├── [SCORE: 0.34] jwt.md : ignoré
│       └── [SCORE: 0.78] providers/
│           └── [SCORE: 0.85] google.md : RENVOYÉ

Cette trace montre :

• Quels répertoires ont été visités
• Pourquoi certains fichiers ont été sélectionnés ou ignorés
• Le chemin exact emprunté par la récupération

Pour le débogage, c'est inestimable. Vous pouvez voir si l'agent a manqué de contexte parce qu'il était dans le mauvais répertoire, avait un résumé L0 insuffisant, ou est tombé en dessous du seuil de score.

Fonctionnalité clé 5 : Gestion automatique des sessions

OpenViking dispose d'une boucle d'auto-itération de la mémoire intégrée. À la fin de chaque session, le système peut extraire des mémoires et mettre à jour automatiquement les connaissances de l'agent.

Six catégories de mémoire

Comment fonctionne l'extraction de mémoire

# Démarrer une session
session = client.session()

# Ajouter des messages (tours de conversation)
await session.add_message("user", [{"type": "text", "text": "Je préfère le mode sombre dans l'interface utilisateur"}])
await session.add_message("assistant", [{"type": "text", "text": "Bien compris. J'utiliserai le mode sombre pour toutes les captures d'écran futures."}])

# Enregistrer l'utilisation de l'outil
await session.add_usage({
    "tool": "screenshot",
    "parameters": {"theme": "dark"},
    "result": "success"
})

# Valider la session : déclenche l'extraction de mémoire
await session.commit()

Une fois validé, OpenViking :

1. Compresse la session (garde les N tours récents, archive les plus anciens)
2. Extrait les mémoires en utilisant l'analyse LLM
3. Met à jour les répertoires de mémoire appropriés
4. Génère L0/L1 pour le nouveau contenu de mémoire

Cela rend les agents plus intelligents à l'usage : ils apprennent les préférences de l'utilisateur, accumulent de l'expérience de tâche et améliorent la prise de décision au fil du temps.

Vue d'ensemble de l'architecture

L'architecture système d'OpenViking sépare les préoccupations en plusieurs couches :

Stockage double couche

OpenViking sépare le contenu de l'index :

Cette séparation garantit :

• Toutes les lectures de contenu proviennent d'une source unique (AGFS)
• L'index vectoriel ne stocke que des références légères
• Pas de duplication de grands blocs de texte dans le stockage vectoriel

Démarrage rapide : Déployez votre premier serveur OpenViking

Prérequis

• Python: 3.10 ou supérieur
• Go: 1.22+ (pour les composants AGFS)
• Compilateur C++: GCC 9+ ou Clang 11+
• SE: Linux, macOS ou Windows

Étape 1 : Installer OpenViking

pip install openviking --upgrade --force-reinstall

Installez optionnellement l'interface CLI Rust pour l'accès au terminal :

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

Étape 2 : Configurer les modèles

OpenViking requiert deux capacités de modèle :

• Modèle VLM: Pour la compréhension d'images et de contenu
• Modèle d'embedding: Pour la vectorisation et la recherche sémantique

Créez ~/.openviking/ov.conf :

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

Fournisseurs supportés :

Le support LiteLLM signifie que vous pouvez utiliser des modèles Anthropic, Google, Ollama locaux, ou tout point de terminaison compatible OpenAI.

Étape 3 : Démarrer le serveur

openviking-server

Ou exécuter en arrière-plan :

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

Étape 4 : Ajouter votre première ressource

# Utilisation de l'interface CLI Rust
ov add-resource https://docs.example.com/api-guide.pdf

# Ou en utilisant le SDK Python
from openviking import OpenViking

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

Étape 5 : Rechercher et récupérer

# Attendre le traitement sémantique, puis rechercher
ov find "authentication methods"

# Lister le contenu du répertoire
ov ls viking://resources/

# Afficher l'arborescence du répertoire
ov tree viking://resources/docs -L 2

# Rechercher du contenu spécifique
ov grep "OAuth" --uri viking://resources/docs/

Étape 6 : Activer VikingBot (facultatif)

VikingBot est un framework d'agent IA construit sur OpenViking :

pip install "openviking[bot]"

# Démarrer le serveur avec le bot activé
openviking-server --with-bot

# Dans un autre terminal, démarrer le chat interactif
ov chat

Benchmarks de performance

OpenViking a été évalué par rapport au RAG traditionnel (LanceDB) et aux systèmes de mémoire native en utilisant le jeu de données LoCoMo10 (1 540 cas de dialogue à longue portée).

Taux d'achèvement des tâches

Principales conclusions

• Amélioration de 43 % par rapport à la mémoire native avec une réduction de 91 % des tokens
• Amélioration de 17 % par rapport à LanceDB avec une réduction de 92 % des tokens
• La récupération hiérarchique d'OpenViking a trouvé un contexte plus pertinent tout en consommant moins de tokens

Ces résultats proviennent de l'intégration d'OpenViking comme plugin avec OpenClaw, un assistant de codage IA open-source. Le jeu de données de test était basé sur des dialogues à longue portée où la rétention de la mémoire est cruciale.

Intégrer OpenViking avec Apidog

Les utilisateurs d'Apidog qui développent des agents IA pour les tests d'API peuvent exploiter OpenViking pour maintenir le contexte de conversation, stocker la documentation API et mémoriser les préférences de l'utilisateur d'une session à l'autre.

Étape 1 : Configurer le serveur OpenViking

Suivez le démarrage rapide ci-dessus pour déployer OpenViking avec vos modèles VLM et d'embedding préférés.

Étape 2 : Importer la documentation API Apidog

# Ajouter la documentation de votre projet Apidog comme ressource
ov add-resource https://docs.apidog.com/overview
ov add-resource https://docs.apidog.com/api-testing

Ceci importe la documentation Apidog dans viking://resources/ avec un traitement L0/L1/L2 automatique.

Étape 3 : Stocker les préférences de l'utilisateur

from openviking import OpenViking

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

# Enregistrer la préférence d'environnement par défaut de l'utilisateur
await session.add_message("user", [{
    "type": "text",
    "text": "Toujours utiliser l'environnement de staging pour les tests API"
}])
await session.commit()  # Extrait automatiquement la mémoire de préférence

Étape 4 : Interroger le contexte pendant les tests

# Trouver les points de terminaison API pertinents avant d'exécuter les tests
results = client.find("points de terminaison d'authentification")
for ctx in results.resources:
    print(f"Found: {ctx.uri}")

# Récupérer la préférence d'environnement de l'utilisateur
prefs = client.find("préférence d'environnement de staging", target_uri="viking://user/memories/")

Étape 5 : Connecter à votre framework d'agent

OpenViking expose à la fois un SDK Python et une 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": "points de terminaison d'authentification"},
    headers={"X-API-Key": "votre-clé-api"}
)

Techniques avancées et bonnes pratiques

Conseils de pro pour les déploiements en production

1. Pré-charger le contexte fréquemment accédé

Chargez la documentation critique dans L0/L1 pendant les heures creuses pour réduire la latence pendant les opérations de l'agent.

# Déclencher le traitement sémantique immédiatement
ov add-resource https://docs.example.com --wait

2. Mettre en œuvre l'expiration du contexte

Configurez le nettoyage automatique des données de session obsolètes :

# Archiver les sessions de plus de 7 jours
await session.archive(max_age_days=7)

3. Surveiller la santé de l'index vectoriel

Suivez la taille de l'index et la latence des requêtes :

ov debug stats

Erreurs courantes à éviter

1. Charger le contenu L2 prématurément : Toujours commencer par L0/L1 pour économiser des tokens
2. Omettre les validations de session : L'extraction de mémoire ne se produit qu'à la validation
3. Surcharger des répertoires uniques : Divisez les grandes ressources en sous-répertoires basés sur des sujets
4. Ignorer les traces de récupération : Utilisez les traces visualisées pour déboguer les résultats médiocres

Optimisation des performances

Bonnes pratiques de sécurité

• Stocker les clés API dans des variables d'environnement ou des gestionnaires de secrets (jamais dans les fichiers de configuration)
• Activer HTTPS pour tous les déploiements de serveurs HTTP
• Implémenter une limitation de débit sur les points de terminaison publics
• Utiliser des clés API séparées pour le développement et la production

Cas d'utilisation réels

1. Assistants de codage IA

Une équipe de développement a intégré OpenViking à son assistant de codage interne. L'agent maintenant :

• Navigue dans la structure du projet via viking://resources/my_project/src/
• Se souvient des préférences de codage de l'utilisateur (conventions de nommage, frameworks de test)
• Récupère la documentation API pertinente pendant la génération de code

Résultat : Réduction de 67 % des comportements d'agent « oublieux », économie de 43 % sur le coût des tokens.

2. Agents de support client

Une entreprise SaaS a déployé OpenViking pour son chatbot de support :

• Documentation produit stockée dans viking://resources/product/
• Historique des conversations client dans viking://user/memories/past_issues/
• Guides de support comme compétences dans viking://agent/skills/

Résultat : La résolution au premier contact s'est améliorée, passant de 52 % à 71 %.

3. Assistants de recherche

Un laboratoire de recherche utilise OpenViking pour organiser des articles et des notes :

• Articles classés par sujet (viking://resources/papers/nlp/)
• Méthodologies de recherche stockées comme compétences
• Extraction automatique des découvertes clés en mémoire

Résultat : Les chercheurs trouvent des articles pertinents 3 fois plus rapidement grâce à la recherche sémantique.

Alternatives et comparaisons

OpenViking n'est pas la seule solution de gestion de contexte. Voici comment il se compare aux alternatives :

OpenViking vs. Bases de données vectorielles traditionnelles

OpenViking vs. Mémoire LangChain

Quand considérer les alternatives

Utilisez les bases de données vectorielles traditionnelles si :

• Vous avez besoin d'une latence de récupération inférieure à 100 ms
• Votre cas d'utilisation est une simple recherche par mots-clés
• Vous avez déjà un pipeline RAG fonctionnel sans points faibles

Utilisez OpenViking si :

• Vous construisez des conversations d'agents de longue durée
• Vous avez besoin d'un contexte multi-type (docs + préférences + outils)
• L'optimisation du coût des tokens est importante
• Vous voulez une récupération observable et débogable

Comparaison avec le RAG traditionnel

Déploiement en production

Pour les environnements de production, exécutez OpenViking comme un service HTTP autonome :

Infrastructure recommandée

• Cloud: Volcengine ECS ou équivalent
• SE: veLinux ou Ubuntu 22.04+
• Stockage: Volume basé sur SSD pour AGFS
• Réseau: Connexion à faible latence aux API des modèles

Considérations de sécurité

• Stocker les clés API dans des variables d'environnement ou un gestionnaire de secrets
• Activer l'authentification pour les points de terminaison HTTP
• Utiliser HTTPS pour toutes les communications client-serveur
• Implémenter une limitation de débit pour prévenir les abus

Surveillance

OpenViking prend en charge la journalisation et les métriques :

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

Surveiller :

• Profondeur de la file d'attente de traitement sémantique
• Latence de la recherche vectorielle
• Opérations de lecture/écriture AGFS
• Taux de succès de l'extraction de mémoire

Limitations et considérations

Limitations actuelles

• Orienté Python : Le SDK principal est Python ; d'autres langages nécessitent une intégration HTTP
• Dépendances de modèle : Nécessite des modèles VLM et d'embedding externes (pas d'inférence intégrée)
• Courbe d'apprentissage : Le paradigme du système de fichiers est différent des bases de données vectorielles traditionnelles
• Phase précoce : Le projet est en développement actif ; les API peuvent changer

Quand utiliser OpenViking

Bonne adéquation :

• Conversations d'agents de longue durée nécessitant de la mémoire
• Contexte multi-type (docs + préférences + outils)
• Besoin d'une récupération observable et débogable
• L'optimisation du coût des tokens est importante

Considérez les alternatives :

• Applications simples de questions-réponses ponctuelles
• Vous avez déjà un pipeline RAG fonctionnel sans points faibles
• Besoin d'une latence de récupération inférieure à 100 ms (OpenViking ajoute une surcharge de traitement)

La feuille de route

OpenViking est en début de développement (version 0.1.x au début de 2025). La feuille de route inclut :

• Prise en charge multi-locataire : Espaces de travail isolés pour les équipes
• Analyses avancées : Métriques de qualité de récupération, tableaux de bord d'utilisation de la mémoire
• Écosystème de plugins : Intégrations pré-construites avec les frameworks d'agents populaires
• Déploiement en périphérie : Mode léger pour les applications locales d'abord
• Support MCP amélioré : Intégration native du protocole de contexte de modèle

L'équipe derrière OpenViking recherche activement des contributeurs de la communauté. Le projet est open source sous licence Apache 2.0, avec une documentation disponible.

Conclusion

OpenViking représente un changement dans la manière dont les agents IA gèrent le contexte. En organisant l'information comme un système de fichiers au lieu de fragments plats, il résout la fragmentation, le gaspillage de tokens et la récupération en boîte noire qui affligent les systèmes RAG traditionnels.

Points clés à retenir

• Le paradigme du système de fichiers unifie le contexte : Toutes les mémoires, ressources et compétences sous des URI viking://
• Le chargement L0/L1/L2 réduit les tokens de 91 % : Chargement progressif au lieu de tout déverser dans les prompts
• La récupération récursive de répertoire améliore la précision : Verrouiller d'abord les répertoires à score élevé, puis explorer le contenu
• Les traces visualisées permettent le débogage : Voir exactement les chemins empruntés par la récupération
• La gestion automatique des sessions permet l'apprentissage : Les agents extraient des mémoires de chaque conversation