AI 시대에는 데이터가 풍부하지만, 고품질의 컨텍스트 (Context)를 확보하기는 어렵습니다. AI 에이전트 (AI Agents)를 구축할 때 개발자들은 종종 다음과 같은 문제에 직면합니다:
파편화된 컨텍스트 (Fragmented Context): 메모리는 코드에 있고, 리소스는 벡터 데이터베이스 (Vector Databases)에 있으며, 기술은 여기저기 흩어져 있어 이를 일관되게 관리하기 어렵습니다.
급증하는 컨텍스트 수요 (Surging Context Demand): 에이전트의 장기 실행 작업은 매 실행마다 컨텍스트를 생성합니다. 단순한 절단 (Truncation) 또는 압축 (Compression)은 정보 손실로 이어집니다.
낮은 검색 효율성 (Poor Retrieval Effectiveness): 전통적인 RAG (Retrieval-Augmented Generation)는 평면적인 저장 방식을 사용하여 전역적인 관점이 부족하며, 정보의 전체 컨텍스트를 이해하기 어렵게 만듭니다.
관찰 불가능한 컨텍스트 (Unobservable Context): 전통적인 RAG의 암시적 검색 체인은 블랙박스와 같아서, 오류가 발생했을 때 디버깅하기가 어렵습니다.
제한된 메모리 반복 (Limited Memory Iteration): 현재의 메모리는 단순히 사용자 상호작용의 기록일 뿐이며, 에이전트 관련 작업 메모리 (Task Memory)가 부족합니다.
OpenViking은 AI 에이전트 (AI Agents)를 위해 특별히 설계된 오픈소스 **컨텍스트 데이터베이스 (Context Database)**입니다.
우리는 에이전트를 위한 미니멀리즘 컨텍스트 상호작용 패러다임을 정의하여, 개발자들이 컨텍스트 관리의 번거로움에서 완전히 벗어날 수 있도록 하는 것을 목표로 합니다. OpenViking은 전통적인 RAG의 파편화된 벡터 저장 모델을 버리고, 에이전트에게 필요한 메모리, 리소스, 기술의 구조적 조직화를 통합하기 위해 혁신적으로 **"파일 시스템 패러다임 (file system paradigm)"**을 채택했습니다.
OpenViking을 사용하면 개발자는 마치 로컬 파일을 관리하듯이 에이전트의 두뇌를 구축할 수 있습니다:
파일 시스템 관리 패러다임 (Filesystem Management Paradigm)
→ 파편화 문제 해결 (Solves Fragmentation): 파일 시스템 패러다임을 기반으로 메모리, 리소스, 기술을 통합적으로 관리하는 컨텍스트 관리 체계를 제공합니다.
계층형 컨텍스트 로딩 (Tiered Context Loading)
→ 토큰 소비 감소 (Reduces Token Consumption): L0/L1/L2의 3계층 구조를 통해 필요할 때만 로드함으로써 비용을 크게 절감합니다.
디렉토리 재귀적 검색 (Directory Recursive Retrieval)
→ 검색 효과 개선 (Improves Retrieval Effect): 네이티브 파일 시스템 검색 방식을 지원하며, 디렉토리 위치 지정과 시맨틱 검색 (Semantic Search)을 결합하여 재귀적이고 정밀한 컨텍스트 획득을 실현합니다.
시각화된 검색 경로 (Visualized Retrieval Trajectory)
→ 관측 가능한 컨텍스트 (Observable Context): 디렉토리 검색 경로의 시각화를 지원하여, 사용자가 문제의 근본 원인을 명확히 관찰하고 검색 로직 최적화를 유도할 수 있습니다.
자동 세션 관리 (Automatic Session Management)
→ 컨텍스트 자기 반복 (Context Self-Iteration): 대화 중 콘텐츠, 리소스 참조, 도구 호출 (Tool Calls) 등을 자동으로 압축하고 장기 메모리 (Long-term Memory)를 추출하여, 사용할수록 에이전트 (Agent)가 더 똑똑해지도록 만듭니다.
OpenViking을 시작하기 전에, 환경이 다음 요구 사항을 충족하는지 확인하십시오:
Python 버전: 3.10 이상
Rust 툴체인 (Rust Toolchain): Cargo (RAGFS 및 CLI 구성 요소를 소스에서 빌드하는 데 필요)
C++ 컴파일러: GCC 9+ 또는 Clang 11+ (핵심 확장 기능을 빌드하는 데 필요)
운영 체제 (Operating System): Linux, macOS, Windows
네트워크 연결: 안정적인 네트워크 연결 필요 (종속성 다운로드 및 모델 서비스 접속용)
pip install openviking --upgrade --force-reinstall
npm i -g @openviking/cli
또는 소스에서 빌드:
cargo install --git https://github.com/volcengine/OpenViking ov_cli
OpenViking은 다음과 같은 모델 역량을 필요로 합니다:
VLM 모델: 이미지 및 콘텐츠 이해용
임베딩 모델 (Embedding Model): 벡터화 및 시맨틱 검색 (Semantic Retrieval)용
OpenViking은 여러 VLM 제공업체를 지원합니다:
| 제공업체 (Provider) | 설명 | 설정 (Setup) |
|---|
volcengine | Volcengine Doubao 모델 | Volcengine Console |
openai | OpenAI 공식 API | OpenAI Platform |
openai-codex | Codex VLM | openviking-server init 사용 |
kimi | Kimi Code 멤버십 | openviking-server init 사용 |
glm | GLM 코딩 플랜 (Coding Plan) | openviking-server init 사용 |
Volcengine (Doubao)
Volcengine은 모델 이름과 엔드포인트 ID (Endpoint ID)를 모두 지원합니다. 단순함을 위해 모델 이름을 사용하는 것을 권장합니다:
{
"vlm": {
"provider": "volcengine",
...
또한 엔드포인트 ID (Volcengine ARK Console에서 확인 가능)를 사용할 수도 있습니다:
{
"vlm": {
"provider": "volcengine",
...
OpenAI
OpenAI의 공식 API를 사용하세요:
{
"vlm": {
"provider": "openai",
...
또한 OpenAI와 호환되는 커스텀 엔드포인트 (Custom OpenAI-compatible endpoint)를 사용할 수도 있습니다:
{
"vlm": {
"provider": "openai",
...
OpenAI Codex (OAuth)
표준 OpenAI API 키 대신, 사용자의 ChatGPT/Codex OAuth 세션을 통해 OpenViking이 Codex VLM을 호출하도록 하려면 이 제공업체를 사용하세요:
openviking-server init
# 프롬프트가 나타나면 OpenAI Codex를 선택하세요
openviking-server doctor
{
"vlm": {
"provider": "openai-codex",
...
💡
팁:
Codex OAuth를 사용할 수 있는 경우, openai-codex는 vlm.api_key를 요구하지 않습니다. OpenViking은 자체적인 Codex 인증 상태를 ~/.openviking/codex_auth.json에 저장합니다.
openviking-server doctor는 현재 Codex 인증을 사용할 수 있는지 검증합니다.
Kimi Coding (구독)
OpenViking이 전용 Kimi Coding 구독 엔드포인트를 직접 호출하도록 하려면 이 제공업체를 사용하세요:
openviking-server init
# 프롬프트가 나타나면 Kimi Coding을 선택하세요
openviking-server doctor
{
"vlm": {
"provider": "kimi",
...
💡
팁:
kimi는 기본 Kimi Coding 사용자 에이전트 (User Agent)인 kimi-code를 포함하여 권장되는 Kimi Coding 기본 설정을 자동으로 적용합니다.
kimi-coding은 제공업체 이름으로 허용되는 별칭 (Alias)입니다.
kimi-code는 Kimi의 업스트림 코딩 모델 (Upstream coding model)로 자동 정규화됩니다.
GLM Coding Plan (구독)
OpenViking이 Z.AI의 OpenAI 호환 Coding Plan 엔드포인트 (Endpoint)를 직접 호출하도록 설정하려면 이 프로바이더 (Provider)를 사용하세요:
openviking-server init
# 프롬프트가 나타나면 GLM Coding Plan을 선택하세요
openviking-server doctor
{
"vlm": {
"provider": "glm",
...
💡
팁:
glm, zhipu, zai, z-ai, 그리고 z.ai는 모두 동일한 퍼스트 클래스 (First-class) GLM 프로바이더로 해석됩니다.- 기본 엔드포인트는 일반 Z.AI 엔드포인트가 아닌 Coding Plan 엔드포인트입니다.
- 멀티모달 파싱 (Multimodal parsing)을 위해
glm-4.6v 또는 glm-5v-turbo와 같은 비전 기능이 있는 모델 (Vision-capable model)을 사용하세요.
Ollama를 통해 로컬 모델 (Local models)로 OpenViking을 실행하려면, 대화형 설정 마법사 (Interactive setup wizard)가 모든 과정을 자동으로 처리합니다:
openviking-server init
마법사는 다음 작업을 수행합니다:
- 필요한 경우 Ollama를 감지하고 설치합니다.
- 사용자의 하드웨어에 적합한 임베딩 (Embedding) 및 VLM 모델을 추천하고 다운로드(Pull)합니다.
- 즉시 사용 가능한
ov.conf 설정 파일을 생성합니다.
언제든지 설정을 검증하려면 다음을 실행하세요:
openviking-server doctor
doctor 명령어는 서버를 실행할 필요 없이 로컬 필수 요구 사항 (설정 파일, Python 버전, 임베딩/VLM 프로바이더 연결성, 디스크 공간)을 확인합니다.
클라우드 API 프로바이더 (Volcengine, OpenAI, Gemini 등)의 경우, 아래의 수동 설정을 진행하세요.
권장되는 최초 실행 흐름은 다음과 같습니다:
openviking-server init
openviking-server doctor
openviking-server init 과정에서 OpenAI Codex를 선택하면, 마법사가 기존 Codex 인증을 가져오거나 Codex 로그인 흐름을 시작할 수 있습니다.
수동 설정을 선호하는 경우, ~/.openviking/ov.conf 파일을 생성하고 복사하기 전에 주석을 제거하세요:
{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
...
참고: 임베딩 모델 (Embedding models)의 경우, 지원되는 프로바이더는 volcengine (Doubao), openai, azure, jina, ollama, voyage, dashscope, minimax, cohere, vikingdb, gemini (pip install "google-genai>=1.0.0" 필요), litellm, 그리고 local입니다. VLM 모델의 경우, 일반적인 프로바이더로는 volcengine, openai, openai-codex, kimi, 그리고 glm이 있습니다.
👇 모델 서비스에 대한 설정 예시를 보려면 확장하세요:
예시 1: Volcengine (Doubao Models) 사용 시
{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
...
예시 2: OpenAI Models 사용 시
{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
...
예시 3: Google Gemini Embedding 사용 시
먼저 필요한 패키지를 설치하세요:
pip install "google-genai>=1.0.0"
{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
...
Google API 키는 https://aistudio.google.com/apikey 에서 발급받을 수 있습니다.
예시 4: Volcengine Embedding + Codex VLM 사용 시
openviking-server init을 실행하고
OpenAI Codex를 선택한 다음,
openviking-server doctor를 실행하세요.
{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
...
설정 파일을 생성한 후, 해당 파일을 가리키도록 환경 변수 (Environment Variable)를 설정하세요 (Linux/macOS):
export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # 기본값
Windows에서는 다음 중 하나를 사용하세요:
PowerShell:
$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"
명령 프롬프트 (cmd.exe):
set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\/.openviking\/ov.conf"
💡
팁: 설정 파일을 다른 위치에 둘 수도 있으며, 환경 변수에 올바른 경로만 지정하면 됩니다.
ov config setup-cli 명령어를 통해 CLI/클라이언트 설정을 대화형으로 초기화할 수 있습니다. 여러 개의 OpenViking 서버를 운영하는 경우, ov config switch 명령어를 사용하여 다른 설정으로 전환할 수 있습니다.
👇 CLI/클라이언트에 대한 설정 예시를 보려면 확장하세요:
예시: localhost 서버 접속을 위한 ovcli.conf
{
"url": "http://localhost:1933",
"timeout": 60.0
...
설정 파일을 생성한 후, 해당 파일을 가리키도록 환경 변수를 설정하세요 (Linux/macOS):
export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # 기본값
Windows에서는 다음 중 하나를 사용하세요:
PowerShell:
$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"
명령 프롬프트 (cmd.exe):
set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"
📝
전제 조건: 이전 단계에서 설정(ov.conf 및 ovcli.conf)을 완료했는지 확인하세요.
이제 OpenViking의 핵심 기능을 경험할 수 있는 전체 예제를 실행해 보겠습니다.
openviking-server doctor
openviking-server
만약 provider=openai-codex를 설정했다면, openviking-server doctor가 이미 Codex 인증을 검증합니다.
또는 백그라운드에서 실행할 수 있습니다:
nohup openviking-server > /data/log/openviking.log 2>&1 &
ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
...
축하합니다! OpenViking을 성공적으로 실행했습니다 🎉
VikingBot은 OpenViking을 기반으로 구축된 AI 에이전트 (AI agent) 프레임워크입니다. 시작 방법은 다음과 같습니다:
# 옵션 1: PyPI에서 VikingBot 설치 (대부분의 사용자에게 권장)
pip install "openviking[bot]"
# 옵션 2: 소스에서 VikingBot 설치 (개발용)
...
공식 Docker 이미지를 사용하는 경우, vikingbot은 이미 이미지에 포함되어 있으며 OpenViking 서버 및 콘솔 UI와 함께 기본적으로 시작됩니다. 런타임(runtime) 시 --without-bot 또는 -e OPENVIKING_WITH_BOT=0을 사용하여 비활성화할 수 있습니다.
프로덕션 (production) 환경의 경우, AI 에이전트 (AI Agents)에 지속적이고 고성능인 컨텍스트 (context) 지원을 제공하기 위해 OpenViking을 독립적인 HTTP 서비스로 실행하는 것을 권장합니다.
🚀 클라우드에 OpenViking 배포하기:
최적의 스토리지 성능과 데이터 보안을 보장하기 위해, veLinux 운영체제를 사용하는 **Volcengine Elastic Compute Service (ECS)**에 배포하는 것을 권장합니다. 빠르게 시작할 수 있도록 상세한 단계별 가이드를 준비했습니다.
| 실험군 (Experimental Group) | 작업 완료율 (Task Completion Rate) | 비용: 입력 토큰 (총합) (Cost: Input Tokens (Total)) |
|---|
| OpenClaw(memory-core) | 35.65% | 24,611,530 |
| ... | | |
-
실험 결론 (Experimental Conclusions): OpenViking 통합 후:
-
기본 메모리 활성화 시 (With native memory enabled): 기존 OpenClaw 대비 43% 성능 향상 및 입력 토큰 비용 91% 절감; LanceDB 대비 15% 성능 향상 및 입력 토큰 비용 96% 절감.
-
기본 메모리 비활성화 시 (With native memory disabled): 기존 OpenClaw 대비 49% 성능 향상 및 입력 토큰 비용 83% 절감; LanceDB 대비 17% 성능 향상 및 입력 토큰 비용 92% 절감.
--
첫 번째 예시를 실행한 후, 이제 OpenViking의 설계 철학(design philosophy)을 자세히 살펴보겠습니다. 이 다섯 가지 핵심 개념은 앞서 언급된 솔루션들과 일대일로 대응하며, 함께 완전한 컨텍스트 관리 시스템(context management system)을 구축합니다:
우리는 더 이상 컨텍스트를 평면적인 텍스트 조각(flat text slices)으로 보지 않고, 이를 추상적인 가상 파일 시스템(virtual filesystem)으로 통합합니다. 메모리, 리소스, 또는 기능(capabilities)이 무엇이든 간에, 이들은 viking:// 프로토콜 하의 가상 디렉터리에 매핑되며, 각각 고유한 URI를 가집니다.