DEV Community

Cover image for 오픈바이킹이란?
Rihpig
Rihpig

Posted on • Originally published at apidog.com

오픈바이킹이란?

#ai #opensource #rag #agents

요약

OpenViking은 AI 에이전트를 위한 오픈소스 컨텍스트 데이터베이스로, 평면적인 벡터 스토리지를 파일 시스템 패러다임으로 대체합니다. 컨텍스트(기억, 리소스, 스킬)는 viking:// URI 아래 L0(~100 토큰), L1(~2k 토큰), L2(전체 콘텐츠)의 세 계층으로 구성됩니다. 벤치마크 결과, 기존 RAG 대비 토큰 비용은 91% 절감되고 작업 완료율은 43% 향상됩니다.

오늘 Apidog을 사용해보세요

소개

AI 에이전트를 개발하다 보면 같은 API 엔드포인트를 반복 요청하거나, 환경 설정을 무시하고, 과거 테스트 결과를 기억하지 못하는 등 기억 문제에 직면합니다.

대부분의 팀은 RAG 파이프라인, 벡터 DB, 커스텀 메모리 시스템 등을 임시로 조합해 사용합니다. 이로 인해 컨텍스트가 조각나고, 토큰 비용이 높아지며, 검색 실패가 자주 발생합니다.

LoCoMo10 데이터셋 벤치마크에서 기존 RAG 시스템은 2,400만~5,100만 입력 토큰을 소모하면서도 35-44%의 작업 완료율만 달성했습니다.

OpenViking은 ByteDance에서 개발한 오픈소스 시스템으로, 평면 벡터 스토리지를 계층적 파일 시스템으로 전환합니다. 모든 컨텍스트는 L0/L1/L2 계층으로 viking:// URI 아래 존재하며, 91% 적은 토큰으로 52%의 작업 완료율을 보여줍니다.

💡 Apidog 사용자는 OpenViking을 통합하여 테스트 실행 전반에 걸쳐 대화 컨텍스트를 유지하고, 사용자 환경 설정을 기억하며, 의미론적 검색을 위해 API 문서를 저장할 수 있습니다.

이 가이드에서는 OpenViking이 컨텍스트 파편화를 해결하는 방법, L0/L1/L2 계층 구조의 실제 동작 방식, 그리고 15분 만에 OpenViking 서버를 배포하는 방법을 다룹니다.

에이전트 컨텍스트 문제

AI 에이전트는 기존 앱에서 겪지 않았던 컨텍스트 처리 문제를 직면합니다.

예를 들어, API 테스트 보조 에이전트는 다음 정보를 추적해야 합니다.

  • 사용자 기본 설정(예: "스테이징 환경", "Python 대신 curl")
  • 프로젝트 컨텍스트(엔드포인트, 인증 방법, 테스트 결과)
  • 도구 패턴(실패 엔드포인트, 스키마 오류)
  • 작업 기록(테스트 내역, 발견된 버그)

RAG는 이 정보를 평면 벡터 DB에 청크로 저장하지만, 쿼리 시 구조적 맥락이나 계층 정보를 잃게 됩니다.

다섯 가지 핵심 과제

과제 기존 RAG OpenViking 솔루션
단편화된 컨텍스트 기억, 리소스, 스킬이 개별적으로 저장됨 viking:// 아래의 통합 파일 시스템 패러다임
급증하는 요구량 긴 작업은 방대한 컨텍스트를 생성 L0/L1/L2 계층적 로딩으로 토큰 91% 절감
미흡한 검색 평면 벡터 검색은 전역 보기가 부족 의도 분석을 통한 디렉토리 재귀 검색
관찰 불가능 블랙박스 검색 체인 디버깅을 위한 시각화된 검색 궤적
제한된 반복 사용자 상호작용 기록만 6가지 메모리 카테고리를 포함한 자동 세션 관리

이제 '막연하게 검색'에서 '구조적·정확하게 검색'으로 전환해야 합니다.

OpenViking이란?

OpenViking은 ByteDance에서 Apache 2.0 라이선스로 공개한 AI 에이전트용 오픈소스 컨텍스트 데이터베이스입니다.

OpenViking 구조도

모든 컨텍스트를 가상 파일 시스템으로 통합하며, 기억·리소스·스킬이 각각 고유한 URI로 viking:// 아래 디렉토리로 매핑됩니다.

viking://
├── resources/
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/
Enter fullscreen mode Exit fullscreen mode

주요 컨텍스트 조작 예시

  • 디렉토리 탐색: ls viking://resources/my_project/docs/
  • 의미론적 검색: find "authentication methods"
  • 파일 읽기: read viking://resources/docs/auth.md
  • 요약 추출: abstract viking://resources/docs/

파일 시스템에서 정확히 원하는 파일을 찾는 것처럼, 원하는 컨텍스트에 빠르게 접근할 수 있습니다.

핵심 기능 1: 파일 시스템 관리 패러다임

파일 시스템 패러다임은 모든 컨텍스트 유형을 하나의 모델로 통합하여 컨텍스트 파편화를 해소합니다.

세 가지 컨텍스트 유형

유형 목적 수명 주기 주도 주체
리소스 외부 지식(문서, 코드, FAQ) 장기적, 정적 사용자 추가
기억 에이전트의 인지(기본 설정, 경험) 장기적, 동적 에이전트 추출
스킬 호출 가능한 기능(도구, MCP) 장기적, 정적 에이전트 호출

각 유형은 디렉토리로 분리되어 관리됩니다.

  • viking://resources/: 매뉴얼, 코드 저장소, 외부 문서
  • viking://user/memories/: 사용자 기본 설정, 엔티티, 이벤트
  • viking://agent/skills/: 도구 정의, MCP 구성
  • viking://agent/memories/: 학습된 패턴, 사례

유닉스 유사 API

OpenViking은 명령줄 스타일의 API를 제공합니다.

from openviking import OpenViking

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

# 의미론적 검색
results = client.find("user authentication")

# 디렉토리 리스트
contents = client.ls("viking://resources/")

# 파일 전체 읽기
doc = client.read("viking://resources/docs/auth.md")

# L0 요약 추출
abstract = client.abstract("viking://resources/docs/")

# L1 개요 추출
overview = client.overview("viking://resources/docs/")
Enter fullscreen mode Exit fullscreen mode

Python SDK 또는 HTTP 서버를 통해 에이전트 프레임워크와 통합할 수 있습니다.

핵심 기능 2: L0/L1/L2 계층적 컨텍스트 로딩

대용량 컨텍스트를 프롬프트에 넣으면 비용과 오류가 급증합니다. OpenViking은 모든 컨텍스트를 3계층으로 자동 분할합니다.

계층 이름 파일 토큰 제한 목적
L0 추상화 .abstract.md ~100 토큰 벡터 검색, 빠른 필터링
L1 개요 .overview.md ~2k 토큰 재순위 지정, 탐색
L2 세부 원본 파일 무제한 전체 콘텐츠, 온디맨드 로딩

작동 방식

리소스 파일을 추가하면 OpenViking은 다음을 자동 수행합니다.

  1. 문서를 텍스트로 파싱
  2. AGFS 스토리지에 디렉토리 트리 구축
  3. 의미론적 처리 비동기 큐 등록
  4. L0/L1 요약 생성

결과 구조 예시:

viking://resources/my_project/
├── .abstract.md
├── .overview.md
├── docs/
│   ├── .abstract.md
│   ├── .overview.md
│   ├── auth.md
│   ├── endpoints.md
│   └── rate-limits.md
└── src/
    └── ...
Enter fullscreen mode Exit fullscreen mode

토큰 예산 절감

계층 구조를 활용해 필요 시에만 L2 전체 텍스트를 로드합니다.

# 기존 RAG: 모든 문서 전체 로딩 (50k tokens)
full_docs = retrieve_all("authentication")

# OpenViking: 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

벤치마크 결과, 입력 토큰 비용 91% 절감, 작업 완료율 43% 향상.

핵심 기능 3: 디렉토리 재귀 검색

복잡한 쿼리 처리를 위해 OpenViking은 디렉토리 재귀 검색 전략을 사용합니다.

5단계 검색 프로세스 

1. 의도 분석
2. 초기 위치 지정 (고득점 디렉토리)
3. 디렉토리 내부 탐색
4. 재귀 하강 (하위 디렉토리)
5. 결과 집계 및 순위화
Enter fullscreen mode Exit fullscreen mode

실제 예시

  • 의도 분석: "사용자 인증 방법" → 인증 관련 가이드, OAuth 흐름 등 식별
  • 초기 위치: viking://resources/docs/auth/ (0.92점)
  • 정제 탐색: oauth.md (0.95점), jwt.md (0.88점)
  • 재귀 하강: auth/providers/ 하위 탐색
  • 집계: 검색 트레이스와 함께 관련성 높은 결과 반환

이 방식은 단순 청크가 아니라 정보의 전체 맥락을 이해해 검색 정확도를 높입니다.

핵심 기능 4: 시각화된 검색 추적

기존 RAG는 검색 실패 원인 파악이 어렵습니다.

OpenViking은 파일 시스템 구조를 활용해 검색 과정을 시각화/관찰 가능하게 만듭니다.

쿼리: "OAuth token refresh"

├── viking://resources/docs/
│   ├── [SCORE: 0.45] .abstract.md: 건너뜀
│   └── [SCORE: 0.89] auth/: 선택됨
│       ├── [SCORE: 0.92] oauth.md: 반환됨
│       ├── [SCORE: 0.34] jwt.md: 건너뜀
│       └── [SCORE: 0.78] providers/
│           └── [SCORE: 0.85] google.md: 반환됨
Enter fullscreen mode Exit fullscreen mode

이를 통해 검색 흐름, 선택/건너뜀 이유, 경로 등을 추적·디버깅할 수 있습니다.

핵심 기능 5: 자동 세션 관리

OpenViking은 메모리 자체 반복 루프를 내장해 세션 종료 시 자동으로 기억을 추출·업데이트합니다.

여섯 가지 메모리 카테고리

카테고리 소유자 위치 설명 업데이트 전략
프로필 사용자 user/memories/.overview.md 기본 사용자 정보 추가 가능
기본 설정 사용자 user/memories/preferences/ 주제별 기본 설정 추가 가능
엔티티 사용자 user/memories/entities/ 사람, 프로젝트, 조직 추가 가능
이벤트 사용자 user/memories/events/ 결정, 이정표 업데이트 없음
사례 에이전트 agent/memories/cases/ 학습된 사례 업데이트 없음
패턴 에이전트 agent/memories/patterns/ 학습된 패턴 업데이트 없음

메모리 추출 자동화 

# 세션 시작
session = client.session()

# 메시지 추가
await session.add_message("user", [{"type": "text", "text": "I prefer dark mode in the UI"}])
await session.add_message("assistant", [{"type": "text", "text": "Got it. I'll use dark mode for all future screenshots."}])

# 도구 사용 기록
await session.add_usage({
    "tool": "screenshot",
    "parameters": {"theme": "dark"},
    "result": "success"
})

# 세션 커밋(메모리 추출 트리거)
await session.commit()
Enter fullscreen mode Exit fullscreen mode

커밋 시 세션 압축, LLM 분석 기반 메모리 추출, 디렉토리 업데이트, 새로운 요약/개요가 자동 생성됩니다.

→ 에이전트가 점점 더 똑똑해집니다.

아키텍처 개요

OpenViking은 관심사를 분리한 아키텍처를 채택합니다.

OpenViking 아키텍처

이중 계층 스토리지

계층 기술 저장소
AGFS 사용자 지정 파일 시스템 L0/L1/L2 콘텐츠, 멀티미디어, 관계
벡터 인덱스 벡터 DB URI, 임베딩, 메타데이터(본문 없음)

이 분리를 통해,

  • 모든 파일 읽기는 AGFS에서 일관 처리
  • 벡터 인덱스는 경량 참조만 저장
  • 중복 저장 및 불필요한 벡터 DB 비용 최소화

빠른 시작: 첫 OpenViking 서버 배포

전제 조건

  • Python 3.10+
  • Go 1.22+ (AGFS 구성요소용)
  • C++ 컴파일러: GCC 9+ 또는 Clang 11+
  • OS: Linux, macOS, Windows

1단계: OpenViking 설치 

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

터미널 CLI 사용을 원하면 Rust CLI도 설치하세요.

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

2단계: 모델 구성

임베딩 및 VLM 모델 설정이 필요합니다.

~/.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
  }
}
Enter fullscreen mode Exit fullscreen mode

지원 공급자:

공급자 임베딩 모델 VLM 모델
volcengine doubao-embedding-vision doubao-seed-2.0-pro
openai text-embedding-3-large gpt-4o, gpt-4-vision
litellm LiteLLM 프록시 Claude, Gemini, DeepSeek, Qwen, Ollama, vLLM

litellm을 통해 Anthropic, Google, 로컬 Ollama 등 다양한 모델 활용 가능.

3단계: 서버 시작 

openviking-server
Enter fullscreen mode Exit fullscreen mode

혹은 백그라운드 실행:

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

4단계: 첫 리소스 추가 

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

# Python SDK
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단계: 검색 및 활용 

# 의미론적 처리 후 검색
ov find "authentication methods"

# 디렉토리 리스트
ov ls viking://resources/

# 트리 구조 보기
ov tree viking://resources/docs -L 2

# 특정 내용 grep
ov grep "OAuth" --uri viking://resources/docs/
Enter fullscreen mode Exit fullscreen mode

6단계: VikingBot 활성화(선택) 

pip install "openviking[bot]"

# 봇 활성화 서버 실행
openviking-server --with-bot

# 대화형 챗 실행
ov chat
Enter fullscreen mode Exit fullscreen mode

성능 벤치마크

OpenViking은 LoCoMo10 데이터셋(1,540개 장거리 대화) 기반으로 기존 RAG(LanceDB) 및 네이티브 메모리 시스템과 벤치마크되었습니다.

작업 완료율

시스템 완료율 입력 토큰
OpenClaw (네이티브 메모리) 35.65% 24.6M
OpenClaw + LanceDB 44.55% 51.6M
OpenClaw + OpenViking 52.08% 4.3M

주요 결과

  • 네이티브 메모리 대비 43% 완료율 향상, 91% 토큰 절감
  • LanceDB 대비 17% 향상, 92% 토큰 절감
  • 계층적 검색 덕분에 더 적은 토큰으로 더 관련성 높은 정보 검색

이 결과는 OpenClaw AI 보조도구에 OpenViking을 플러그인으로 붙여 얻은 실제 데이터입니다.

Apidog와 OpenViking 통합

Apidog 사용자는 OpenViking으로 대화 컨텍스트를 유지하고, API 문서를 저장하며, 세션별 사용자 기본 설정을 기억할 수 있습니다.

통합 아키텍처

1단계: OpenViking 서버 배포

위의 빠른 시작 가이드를 참고해 VLM/임베딩 모델을 선택, OpenViking 서버를 실행합니다.

2단계: Apidog API 문서 리소스 등록 

# Apidog 공식 문서 추가
ov add-resource https://docs.apidog.com/overview
ov add-resource https://docs.apidog.com/api-testing
Enter fullscreen mode Exit fullscreen mode

→ 문서가 viking://resources/로 등록되고, L0/L1/L2 자동 처리됩니다.

3단계: 사용자 기본 설정 저장 

from openviking import OpenViking

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

# 환경 설정 입력
await session.add_message("user", [{
    "type": "text",
    "text": "Always use the staging environment for API tests"
}])
await session.commit()  # 자동으로 기본 설정 메모리 추출
Enter fullscreen mode Exit fullscreen mode

4단계: 테스트 중 컨텍스트 쿼리 

# 테스트 전 API 엔드포인트 검색
results = client.find("authentication endpoints")
for ctx in results.resources:
    print(f"Found: {ctx.uri}")

# 사용자 환경 설정 검색
prefs = client.find("staging environment preference", target_uri="viking://user/memories/")
Enter fullscreen mode Exit fullscreen mode

OpenViking을 활용하면 API 테스트 에이전트의 기억·검색·세션 관리가 한층 견고해집니다.

Apidog과 함께 실전 적용해 보세요!

Top comments (0)