오픈바이킹이란?

요약

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

소개

귀하의 AI 에이전트가 자꾸 무언가를 잊어버립니다. 같은 API 엔드포인트를 두 번 요청하고, 스테이징 환경 기본 설정을 무시하며, 어제 어떤 테스트가 통과되었는지 기억하지 못합니다.

이것이 오늘날 에이전트를 구축하는 현실입니다. 대부분의 팀은 RAG 파이프라인, 벡터 데이터베이스, 맞춤형 메모리 시스템을 임시방편으로 조합합니다. 그 결과: 조각난 컨텍스트, 폭증하는 토큰 비용, 그리고 조용히 실패하는 검색이 발생합니다.

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

OpenViking은 다른 접근 방식을 취합니다. ByteDance의 OpenViking 팀에서 개발한 이 시스템은 평면적인 벡터 스토리지를 파일 시스템 패러다임으로 대체합니다. 모든 컨텍스트는 계층적인 L0/L1/L2 로딩을 통해 viking:// URI 아래에 존재합니다. 그 결과: 91% 더 적은 토큰으로 52%의 작업 완료율을 달성했습니다.

이 가이드에서는 OpenViking이 컨텍스트 파편화를 어떻게 해결하는지, L0/L1/L2 모델이 실제로 어떻게 작동하는지, 그리고 15분 안에 첫 서버를 배포하는 방법을 배울 수 있습니다.

에이전트 컨텍스트 문제

AI 에이전트는 기존 애플리케이션이 결코 다루지 않았던 컨텍스트 문제에 직면합니다.

개발자가 API를 테스트하도록 돕는 에이전트를 생각해 봅시다. 일주일 동안 다음을 추적해야 합니다.

• 사용자 기본 설정("스테이징 환경", "Python 대신 curl")
• 프로젝트 컨텍스트(엔드포인트, 인증 방법, 과거 테스트 결과)
• 도구 패턴(어떤 엔드포인트가 실패하는지, 일반적인 스키마 오류)
• 작업 기록(무엇이 테스트되었는지, 어떤 버그가 발견되었는지)

기존 RAG는 이를 벡터 데이터베이스에 평면적인 청크로 저장합니다. 이를 쿼리하면 구조, 계층, 그리고 무엇이 누락되었는지에 대한 가시성 없이 상위 K개의 유사한 조각들을 얻게 됩니다.

다섯 가지 핵심 과제

이는 '모든 것을 저장하고, 막연하게 검색하는' 방식에서 '모든 것을 구조화하고, 정확하게 검색하는' 방식으로의 전환을 의미합니다.

OpenViking이란?

OpenViking은 ByteDance의 OpenViking 팀이 Apache 2.0 라이선스 하에 개발한 AI 에이전트를 위한 오픈소스 컨텍스트 데이터베이스입니다.

이것은 모든 컨텍스트를 가상 파일 시스템으로 통합합니다. 기억, 리소스, 스킬은 각각 고유한 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/

에이전트는 직접적인 컨텍스트 조작 기능을 얻습니다.

• ls viking://resources/my_project/docs/로 디렉토리 탐색
• find "authentication methods"로 의미론적 검색
• read viking://resources/docs/auth.md로 전체 내용 읽기
• abstract viking://resources/docs/로 빠른 요약 얻기

이것을 전체 하드 드라이브를 검색하는 것과 파일이 저장된 정확한 디렉토리를 아는 것의 차이라고 생각하십시오.

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

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

세 가지 컨텍스트 유형

각 유형은 자체 디렉토리에 존재합니다.

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

유닉스 유사 API

OpenViking은 친숙한 명령줄 작업을 제공합니다.

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/")

이 API는 Python SDK 또는 HTTP 서버를 통해 작동하며, 모든 에이전트 프레임워크와 호환됩니다.

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

방대한 컨텍스트를 프롬프트에 채워 넣는 것은 비용이 많이 들고 오류 발생 가능성이 높습니다. OpenViking은 모든 컨텍스트를 세 가지 계층적 계층으로 자동 처리합니다.

작동 방식

리소스(예: PDF 문서 파일)를 추가하면 OpenViking은 다음을 수행합니다.

1. 문서를 텍스트로 파싱합니다(아직 LLM 호출 없음).
2. AGFS 스토리지에 디렉토리 트리 구조를 구축합니다.
3. 의미론적 처리를 비동기적으로 큐에 추가합니다.
4. L0 추상 및 L1 개요를 상향식으로 생성합니다.

그 결과는 계층적 구조입니다.

viking://resources/my_project/
├── .abstract.md               # L0: "인증, 엔드포인트, 속도 제한을 다루는 API 문서"
├── .overview.md               # L1: 섹션 탐색이 포함된 상세 요약
├── docs/
│   ├── .abstract.md          # 각 디렉토리에는 L0/L1이 있습니다
│   ├── .overview.md
│   ├── auth.md               # L2: 전체 콘텐츠
│   ├── endpoints.md
│   └── rate-limits.md
└── src/
    └── ...

토큰 예산에 미치는 영향

이 계층 구조는 상당한 비용 절감을 가능하게 합니다.

# 기존 RAG: 모든 콘텐츠 로드
full_docs = retrieve_all("authentication")  # 50k tokens

# OpenViking: L1부터 시작, 필요할 때만 L2 로드
overview = client.overview("viking://resources/docs/auth/")  # 2k tokens

if needs_more_detail(overview):
    content = client.read("viking://resources/docs/auth/oauth.md")  # 특정 L2 로드

벤치마크 테스트에서 이 접근 방식은 기존 RAG에 비해 입력 토큰 비용을 91% 절감하면서 작업 완료율을 43% 향상시켰습니다.

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

단일 벡터 검색은 복잡한 쿼리에 어려움을 겪습니다. OpenViking은 디렉토리 재귀 검색 전략을 구현합니다.

5단계 프로세스

1. 의도 분석
   ↓
2. 초기 위치 지정 (고득점 디렉토리 찾기)
   ↓
3. 정제된 탐색 (디렉토리 내 검색)
   ↓
4. 재귀적 하강 (하위 디렉토리로 드릴 다운)
   ↓
5. 결과 집계 (순위가 매겨진 컨텍스트 반환)

1단계: 의도 분석

쿼리 "사용자를 어떻게 인증하나요?"는 다음을 식별하기 위해 분석됩니다.

• 의도 유형: 절차적 방법 질문
• 핵심 엔티티: "인증", "사용자"
• 예상 콘텐츠: 인증 가이드, OAuth 흐름

2단계: 초기 위치 지정

벡터 검색은 빠르게 고득점 디렉토리를 찾습니다.

• viking://resources/docs/auth/ (점수: 0.92)
• viking://resources/docs/security/ (점수: 0.78)

3단계: 정제된 탐색

상위 디렉토리 내에서 보조 검색은 특정 파일을 찾습니다.

• viking://resources/docs/auth/oauth.md (점수: 0.95)
• viking://resources/docs/auth/jwt.md (점수: 0.88)

4단계: 재귀적 하강

하위 디렉토리(예: auth/providers/)가 존재하면 프로세스는 재귀적으로 반복됩니다.

5단계: 결과 집계

최종 결과는 검색 추적과 함께 관련성에 따라 집계되고 순위가 매겨집니다.

이 '먼저 디렉토리를 잠그고, 그 다음 콘텐츠를 탐색하는' 전략은 고립된 청크가 아닌 정보의 전체 컨텍스트를 이해함으로써 검색 정확도를 향상시킵니다.

핵심 기능 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: 반환됨

이 추적은 다음을 보여줍니다.

• 어떤 디렉토리가 방문되었는지
• 특정 파일이 왜 선택되거나 건너뛰어졌는지
• 검색이 진행된 정확한 경로

디버깅을 위해 이것은 매우 유용합니다. 에이전트가 잘못된 디렉토리에 있었거나, L0 요약이 부실했거나, 점수 임계값 아래로 떨어져서 컨텍스트를 놓쳤는지 확인할 수 있습니다.

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

OpenViking에는 내장된 메모리 자체 반복 루프가 있습니다. 각 세션이 끝나면 시스템은 자동으로 기억을 추출하고 에이전트의 지식을 업데이트할 수 있습니다.

여섯 가지 메모리 카테고리

메모리 추출 작동 방식

# 세션 시작
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()

커밋되면 OpenViking은 다음을 수행합니다.

1. 세션을 압축합니다(최근 N개의 턴을 유지하고, 오래된 턴은 보관합니다).
2. LLM 분석을 사용하여 기억을 추출합니다.
3. 적절한 메모리 디렉토리를 업데이트합니다.
4. 새로운 메모리 콘텐츠에 대한 L0/L1을 생성합니다.

이것은 에이전트가 사용할수록 더 똑똑해지도록 만듭니다. 사용자 기본 설정을 학습하고, 작업 경험을 축적하며, 시간이 지남에 따라 의사 결정을 향상시킵니다.

아키텍처 개요

OpenViking의 시스템 아키텍처는 여러 계층에 걸쳐 관심사를 분리합니다.

이중 계층 스토리지

OpenViking은 콘텐츠와 인덱스를 분리합니다.

이러한 분리는 다음을 보장합니다.

• 모든 콘텐츠 읽기가 단일 소스(AGFS)에서 이루어집니다.
• 벡터 인덱스는 경량 참조만 저장합니다.
• 벡터 스토리지에 대규모 텍스트 블롭이 중복되지 않습니다.

빠른 시작: 첫 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

터미널 액세스를 위해 Rust CLI를 선택적으로 설치할 수 있습니다.

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

2단계: 모델 구성

OpenViking은 두 가지 모델 기능이 필요합니다.

• 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
  }
}

지원되는 공급자:

LiteLLM 지원은 Anthropic, Google, 로컬 Ollama 모델 또는 OpenAI 호환 엔드포인트를 사용할 수 있음을 의미합니다.

3단계: 서버 시작

openviking-server

또는 백그라운드에서 실행:

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

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")

5단계: 검색 및 가져오기

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

# 디렉토리 내용 목록
ov ls viking://resources/

# 디렉토리 트리 보기
ov tree viking://resources/docs -L 2

# 특정 콘텐츠 grep
ov grep "OAuth" --uri viking://resources/docs/

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

VikingBot은 OpenViking을 기반으로 구축된 AI 에이전트 프레임워크입니다.

pip install "openviking[bot]"

# 봇이 활성화된 상태로 서버 시작
openviking-server --with-bot

# 다른 터미널에서 대화형 채팅 시작
ov chat

성능 벤치마크

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

작업 완료율

주요 결과

• 네이티브 메모리 대비 43% 향상 및 91% 토큰 절감
• LanceDB 대비 17% 향상 및 92% 토큰 절감
• OpenViking의 계층적 검색은 더 적은 토큰을 소비하면서 더 관련성 높은 컨텍스트를 찾았습니다.

이러한 결과는 오픈소스 AI 코딩 비서인 OpenClaw에 OpenViking을 플러그인으로 통합하여 얻은 것입니다. 테스트 데이터셋은 기억 유지가 중요한 장거리 대화를 기반으로 했습니다.

Apidog와 OpenViking 통합

API 테스트용 AI 에이전트를 구축하는 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

이는 Apidog 문서를 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()  # 기본 설정 메모리를 자동으로 추출

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/")

5