DEV Community

Cover image for Apa itu OpenViking? Panduan Lengkap dan Fitur Unggulan
Walse
Walse

Posted on • Originally published at apidog.com

Apa itu OpenViking? Panduan Lengkap dan Fitur Unggulan

#ai #opensource #rag #agents

TL;DR

OpenViking adalah basis data konteks sumber terbuka untuk agen AI yang menggantikan penyimpanan vektor datar dengan paradigma sistem file. Ia mengatur konteks (memori, sumber daya, keterampilan) di bawah URI viking:// dengan tiga lapisan: L0 (~100 token), L1 (~2k token), L2 (konten penuh). Tolok ukur menunjukkan pengurangan biaya token sebesar 91% dan penyelesaian tugas 43% lebih baik dibandingkan RAG tradisional.

Coba Apidog hari ini

Pendahuluan

Agen AI Anda sering melupakan sesuatu: menanyakan endpoint API yang sama dua kali, mengabaikan preferensi lingkungan staging, atau lupa tes mana yang lolos kemarin. Ini adalah masalah utama dalam pengembangan agen saat ini karena fragmentasi konteks, membengkaknya biaya token, dan pengambilan yang gagal.

Data LoCoMo10 membuktikan bahwa RAG tradisional hanya mencapai tingkat penyelesaian tugas 35-44% sambil menggunakan 24-51 juta token input. OpenViking menggantikan penyimpanan vektor datar dengan sistem file hierarkis di bawah viking:// dan pemuatan L0/L1/L2, menghasilkan 52% penyelesaian tugas dengan konsumsi token 91% lebih rendah.

💡 Tips: Pengguna Apidog yang membangun agen pengujian API dapat mengintegrasikan OpenViking untuk menjaga konteks antar eksekusi tes, mengingat preferensi lingkungan, dan menyimpan dokumentasi API untuk pengambilan semantik.

Panduan ini membahas cara OpenViking mengatasi fragmentasi konteks, demonstrasi model L0/L1/L2, dan cara menerapkan server dalam waktu singkat.

Masalah Konteks Agen

Agen AI menghadapi tantangan konteks unik yang tidak dialami aplikasi tradisional. Contoh: agen penguji API perlu melacak preferensi pengguna, konteks proyek, pola alat, dan riwayat tugas selama berhari-hari.

RAG tradisional menyimpan semua ini dalam basis data vektor datar, menghasilkan fragmentasi, tanpa struktur, dan tidak ada visibilitas apa yang terlewat.

Lima Tantangan Utama

OpenViking mengidentifikasi masalah inti berikut:

Tantangan RAG Tradisional Solusi OpenViking
Konteks Terfragmentasi Memori, sumber daya, keterampilan disimpan terpisah Sistem file terpadu di bawah viking://
Permintaan Meningkat Tugas panjang → konteks masif Pemuatan hierarkis L0/L1/L2, token -91%
Pengambilan Buruk Pencarian vektor tanpa tampilan global Pengambilan rekursif direktori + analisis intensi
Tidak Dapat Diamati Rantai pengambilan kotak hitam Jejak pencarian divisualisasikan untuk debugging
Iterasi Terbatas Hanya riwayat percakapan pengguna Manajemen sesi otomatis dengan 6 kategori memori

Pendekatan: dari "simpan semua, ambil samar" menjadi "strukturkan dan ambil tepat".

Apa Itu OpenViking?

OpenViking adalah basis data konteks open source untuk agen AI (lisensi Apache 2.0).

OpenViking: Basis Data Konteks Sistem File untuk Agen AI

Semua konteks diatur dalam sistem file virtual di bawah URI viking://:

viking://
├── resources/        # Pengetahuan eksternal: dokumen, kode, web
├── user/             # Preferensi pengguna, memori
└── agent/            # Keterampilan, memori tugas, instruksi
Enter fullscreen mode Exit fullscreen mode

Agen dapat:

  • Navigasi: ls viking://resources/my_project/docs/
  • Pencarian semantik: find "metode otentikasi"
  • Membaca konten: read viking://resources/docs/auth.md
  • Ringkasan cepat: abstract viking://resources/docs/

Fitur Utama 1: Paradigma Sistem File

Tiga Jenis Konteks

Tipe Tujuan Siklus Hidup Inisiatif
Sumber Daya Pengetahuan eksternal (dokumen, dll) Jangka panjang Pengguna
Memori Preferensi, pengalaman Jangka panjang Agen
Keterampilan Alat yang dapat dipanggil Jangka panjang Agen

Contoh struktur direktori:

  • viking://resources/ : Dokumen, repositori kode
  • viking://user/memories/ : Preferensi pengguna, peristiwa
  • viking://agent/skills/ : Definisi alat, MCP

API Mirip Unix 

from openviking import OpenViking

client = OpenViking(path="./data")
results = client.find("otentikasi pengguna")
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

API tersedia via SDK Python atau HTTP server, integrasi mudah ke agent framework apa pun.

Fitur Utama 2: Pemuatan Konteks Hierarkis L0/L1/L2

OpenViking otomatis membagi konteks menjadi 3 lapisan:

Lapisan Nama File Batas Token Tujuan
L0 Abstrak .abstract.md ~100 Pencarian vektor, filter
L1 Ikhtisar .overview.md ~2k Navigasi, peringkat ulang
L2 Detail File asli Tak terbatas Konten penuh, on-demand

Cara Kerja

  1. Menguraikan dokumen → teks
  2. Membangun struktur direktori AGFS
  3. Mengantrekan proses semantik async
  4. Menghasilkan L0/L1 secara bottom-up

Contoh struktur:

viking://resources/my_project/
├── .abstract.md   # L0
├── .overview.md   # L1
├── docs/
│   ├── auth.md    # L2
Enter fullscreen mode Exit fullscreen mode

Dampak Anggaran Token 

# Tradisional: muat semua (50k token)
full_docs = retrieve_all("otentikasi")

# OpenViking: mulai dari L1, lanjut ke L2 bila perlu
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

Terbukti menghemat 91% token input, tingkat penyelesaian tugas +43%.

Fitur Utama 3: Pengambilan Rekursif Direktori

OpenViking menggunakan strategi pengambilan rekursif direktori lima langkah:

1. Analisis Intensi
2. Penempatan Awal (direktori skor tinggi)
3. Eksplorasi dalam direktori
4. Penelusuran rekursif subdirektori
5. Agregasi & peringkat hasil
Enter fullscreen mode Exit fullscreen mode

Contoh proses pengambilan:

  • Analisis kueri "bagaimana cara mengautentikasi pengguna?"
  • Temukan direktori skor tinggi: viking://resources/docs/auth/
  • Eksplorasi file: oauth.md, jwt.md
  • Rekursif ke subdirektori jika ada
  • Agregasi hasil dengan jejak pengambilan

Fitur Utama 4: Jejak Pengambilan Visual

Pengambilan OpenViking dapat diamati secara penuh, memudahkan debugging:

Jejak Pengambilan untuk: "penyegaran token OAuth"
├── viking://resources/docs/
│   ├── [SKOR: 0.45] .abstract.md: dilewati
│   └── [SKOR: 0.89] auth/: terpilih
│       ├── [SKOR: 0.92] oauth.md: DIKEMBALIKAN
│       └── [SKOR: 0.85] providers/google.md: DIKEMBALIKAN
Enter fullscreen mode Exit fullscreen mode

Jejak ini memperlihatkan jalur pencarian dan alasan file terpilih/dilewati.

Fitur Utama 5: Manajemen Sesi Otomatis

OpenViking memiliki loop iterasi memori otomatis. Setiap sesi percakapan dapat diekstrak menjadi memori, memperkaya pengetahuan agen.

Enam Kategori Memori

Kategori Pemilik Lokasi Deskripsi Update
profil pengguna user/memories/.overview.md Info dasar Bisa
preferensi pengguna user/memories/preferences/ Preferensi topik Bisa
entitas pengguna user/memories/entities/ Orang/proyek/org Bisa
peristiwa pengguna user/memories/events/ Keputusan/pencapaian Tidak
kasus agen agent/memories/cases/ Kasus dipelajari Tidak
pola agen agent/memories/patterns/ Pola dipelajari Tidak

Contoh Penggunaan 

session = client.session()
await session.add_message("user", [{"type": "text", "text": "Saya lebih suka mode gelap di UI"}])
await session.add_message("assistant", [{"type": "text", "text": "Baik, akan saya gunakan mode gelap."}])
await session.add_usage({"tool": "screenshot", "parameters": {"theme": "dark"}, "result": "success"})
await session.commit()  # Memicu ekstraksi memori
Enter fullscreen mode Exit fullscreen mode

Gambaran Umum Arsitektur

Arsitektur Sistem OpenViking

Penyimpanan Dua Lapisan

Lapisan Teknologi Penyimpanan
AGFS File system custom Konten L0/L1/L2, multimedia, relasi
Indeks Vektor DB Vektor URI, embedding, metadata (tanpa file)

Semua pembacaan konten dilakukan via AGFS, indeks vektor hanya untuk referensi ringan.

Mulai Cepat: Deploy Server OpenViking

Prasyarat

  • Python 3.10+
  • Go 1.22+ (AGFS)
  • C++ Compiler (GCC 9+ / Clang 11+)
  • OS: Linux/macOS/Windows

Langkah 1: Instal OpenViking 

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

Opsional: CLI Rust

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

Langkah 2: Konfigurasi Model

Buat file ~/.openviking/ov.conf:

{
  "storage": {
    "workspace": "/home/nama-anda/openviking_workspace"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "kunci-api-openai-anda",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    }
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "kunci-api-openai-anda",
    "provider": "openai",
    "model": "gpt-4o"
  }
}
Enter fullscreen mode Exit fullscreen mode
Penyedia Model Embedding Model VLM
volcengine doubao-embedding-vision doubao-seed-2.0-pro
openai text-embedding-3-large gpt-4o, gpt-4-vision
litellm via proxy LiteLLM Claude, Gemini, dll.

Langkah 3: Jalankan Server 

openviking-server
Enter fullscreen mode Exit fullscreen mode

Atau background:

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

Langkah 4: Tambahkan Sumber Daya 

# 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

Langkah 5: Pencarian & Pengambilan 

ov find "metode otentikasi"
ov ls viking://resources/
ov tree viking://resources/docs -L 2
ov grep "OAuth" --uri viking://resources/docs/
Enter fullscreen mode Exit fullscreen mode

Langkah 6: Aktifkan VikingBot (Opsional) 

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

Tolok Ukur Kinerja

Sistem Penyelesaian Token Masukan
OpenClaw (memori asli) 35.65% 24.6M
OpenClaw + LanceDB 44.55% 51.6M
OpenClaw + OpenViking 52.08% 4.3M
  • Peningkatan 43% dari memori asli, token -91%
  • Peningkatan 17% dari LanceDB, token -92%
  • Pengambilan hierarkis menemukan konteks lebih relevan, token lebih hemat

Integrasi OpenViking dengan Apidog

Pengguna Apidog dapat memanfaatkan OpenViking untuk menjaga konteks percakapan, mengimpor dokumentasi API, dan menyimpan preferensi pengguna.

Mengintegrasikan OpenViking dengan Apidog

Langkah 1: Deploy Server OpenViking

Ikuti langkah mulai cepat di atas.

Langkah 2: Impor Dokumentasi 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

Langkah 3: Simpan Preferensi Pengguna 

from openviking import OpenViking

client = OpenViking(path="./apidog-agent-data")
session = client.session()
await session.add_message("user", [{
    "type": "text",
    "text": "Selalu gunakan lingkungan staging untuk tes API"
}])
await session.commit()
Enter fullscreen mode Exit fullscreen mode

Langkah 4: Kueri Konteks Selama Pengujian 

results = client.find("endpoint otentikasi")
for ctx in results.resources:
    print(f"Ditemukan: {ctx.uri}")

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

Langkah 5: Integrasi ke Kerangka Agent 

# 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": "endpoint otentikasi"},
    headers={"X-API-Key": "kunci-api-anda"}
)
Enter fullscreen mode Exit fullscreen mode

Teknik Lanjutan & Praktik Terbaik

Tips Pro

  1. Hangatkan Konteks: Muat L0/L1 saat non-peak untuk mengurangi latensi.

    ov add-resource https://docs.example.com --wait

  2. Kedaluwarsa Otomatis: Arsipkan sesi lama.

    await session.archive(max_age_days=7)

  3. Pantau Kesehatan Indeks:

    ov debug stats

Kesalahan yang Harus Dihindari

  1. Memuat L2 terlalu dini
  2. Tidak melakukan commit sesi (ekstraksi memori gagal)
  3. Meletakkan semua sumber daya dalam satu direktori besar
  4. Mengabaikan jejak pengambilan untuk debugging

Optimasi Kinerja

Skenario Rekomendasi
Kueri tinggi Jalankan sebagai HTTP server + connection pooling
Dokumen besar Bagi berdasarkan topik sebelum import
Latensi rendah Pra-generasi L0/L1
Multi-tenant Workspace terpisah per penyewa

Praktik Terbaik Keamanan

  • Simpan API key di env/secret manager, bukan file config
  • Aktifkan HTTPS untuk HTTP server
  • Batasi rate pada endpoint publik
  • Gunakan API key berbeda untuk dev dan prod

Kasus Penggunaan Dunia Nyata

1. Asisten Pengkodean AI

  • Agen menavigasi viking://resources/my_project/src/
  • Mengingat preferensi pengkodean pengguna
  • Mengambil dokumentasi relevan saat coding
  • Hasil: Pengurangan 67% perilaku lupa, biaya token -43%

2. Agen Dukungan Pelanggan

  • Dokumentasi produk di viking://resources/product/
  • Riwayat pelanggan di viking://user/memories/past_issues/
  • Buku pedoman dukungan di viking://agent/skills/
  • Hasil: First contact resolution naik dari 52% → 71%

3. Asisten Penelitian

  • Makalah dikategorikan di viking://resources/papers/nlp/
  • Metodologi penelitian sebagai keterampilan
  • Ekstraksi temuan otomatis ke memori
  • Hasil: Peneliti menemukan makalah 3x lebih cepat

Alternatif & Perbandingan

OpenViking vs Basis Data Vektor Tradisional

Aspek RAG Tradisional OpenViking
Model Penyimpanan Potongan vektor datar Sistem file hierarkis
Pengambilan Kesamaan Top-K Rekursif + Analisis Intensi
Dapat Diamati Kotak Hitam Jejak pencarian visual
Efisiensi Token Muat semua/potong L0/L1/L2 progresif
Iterasi Memori Manual/tidak ada Sesi otomatis
Jenis Konteks Hanya dokumen Sumber daya, memori, keterampilan
Debugging Tebak-tebakan Log penelusuran direktori

OpenViking vs Memori LangChain

Aspek Memori LangChain OpenViking
Persistensi Buffer percakapan Sistem file L0/L1/L2
Skalabilitas Dibatasi window Hierarkis, tanpa batas
Pengambilan Linier Rekursif + Semantik
Jenis Memori Buffer tunggal 6 kategori memori

Kapan Memilih Alternatif

  • Vektor tradisional: Latensi <100ms, pencarian sederhana, pipeline RAG sudah stabil
  • OpenViking: Agen percakapan panjang, konteks multi-jenis, penghematan token penting, debugging pengambilan

Perbandingan dengan RAG Tradisional

Aspek RAG Tradisional OpenViking
Model Penyimpanan Potongan vektor datar Sistem file hierarkis
Pengambilan Kesamaan Top-K Rekursif + Analisis Intensi
Dapat Diamati Kotak Hitam Jejak pencarian visual
Efisiensi Token Muat semua/potong L0/L1/L2 progresif
Iterasi Memori Manual/tidak ada Sesi otomatis
Jenis Konteks Hanya dokumen Multi-jenis
Debugging Tebak-tebakan Log penelusuran direktori

Penerapan Produksi

Jalankan OpenViking sebagai HTTP service mandiri.

Infrastruktur Direkomendasikan

  • Cloud: Volcengine ECS / setara
  • OS: veLinux/Ubuntu 22.04+
  • Penyimpanan: SSD untuk AGFS
  • Jaringan: Latensi rendah ke API model

Keamanan

  • Simpan API key di env/secret manager
  • Aktifkan otentikasi & HTTPS pada endpoint
  • Batasi rate untuk publik

Pemantauan 

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

Pantau: antrean pemrosesan semantik, latensi pencarian, operasi AGFS, ekstraksi memori.

Keterbatasan & Pertimbangan

Keterbatasan Saat Ini

  • SDK utama Python, bahasa lain via HTTP
  • Butuh model VLM & embedding eksternal
  • Paradigma sistem file baru, perlu adaptasi
  • Masih tahap awal, API bisa berubah

Kapan Menggunakan OpenViking

Cocok:

  • Agen percakapan panjang, butuh memori
  • Konteks multi-jenis (dokumen, preferensi, alat)
  • Butuh observabilitas & debugging
  • Optimasi token penting

Pertimbangkan alternatif jika:

  • QA satu kali/sederhana
  • Pipeline RAG sudah stabil
  • Latensi di bawah 100ms sangat penting

Jalan ke Depan

OpenViking masih tahap awal (v0.1.x, awal 2025). Roadmap:

  • Multi-tenant: workspace terisolasi
  • Analitik lanjutan: metrik pengambilan, dashboard memori
  • Ekosistem plugin: integrasi agent framework
  • Edge deployment: mode lightweight
  • Dukungan MCP native

Proyek open source, kontribusi komunitas terbuka. Lihat dokumentasi resmi.

Kesimpulan

OpenViking mengubah paradigma manajemen konteks agen AI: dari potongan datar ke sistem file hierarkis, fragmentasi hilang, efisiensi token meningkat, dan debugging pengambilan menjadi mudah.

Poin Penting

  • Sistem file menyatukan konteks: Semua di bawah URI viking://
  • Pemuatan L0/L1/L2 hemat token: -91% token, progresif
  • Pengambilan rekursif akurat: Kunci direktori dulu, eksplorasi konten belakangan
  • Jejak visual: Mudah debugging
  • Manajemen sesi otomatis: Agen belajar dari setiap percakapan

Top comments (0)