MiroFish는 뉴스 속보, 정책 초안, 금융 신호 등 현실 세계의 시드 정보를 추출해 고충실도의 병렬 디지털 세계를 구축하는 멀티 에이전트 기반 차세대 AI 예측 엔진입니다. 단일 대형 언어 모델(LLM)에 특정 상황의 미래를 단편적으로 묻는 기존 질의응답 방식과 달리, MiroFish는 사회 속 다양한 이해관계자와 역할을 모사하는 다수의 에이전트가 가상 공간에서 상호작용하도록 유도하는 군집 지능(Swarm Intelligence) 구조를 채택했습니다. 정책 수립, 공공 여론 분석, 서사적 시나리오 추론 등 복합적인 동태를 시뮬레이션할 수 있는 MiroFish의 동작 원리와 환경 구축 절차를 상세히 살펴봅니다.
MiroFish 아키텍처와 군집 지능의 예측 원리
MiroFish의 핵심 메커니즘은 현실에서 발생하는 다양한 데이터로부터 핵심 시드(Seed)를 도출한 뒤, 이를 기반으로 병렬 디지털 환경을 생성하여 수많은 지능형 에이전트 간의 상호작용을 관찰하는 데 있습니다. 이를 통해 복잡계 현상에서 나타나는 창발적 결과(Emergence)를 추적할 수 있습니다.
MiroFish는 활용 목적에 따라 거시적 차원과 미시적 차원의 두 가지 시나리오를 지원하도록 설계되었습니다.
- 거시적 차원(Macro Level): 정책 입안자나 위기관리 담당자를 위한 리허설 실험실 역할을 수행합니다. 새로운 정책 초안이나 홍보(PR) 대응 전략을 실제 현실에 적용하기 전에 제로 리스크(Zero Risk) 환경에서 사전 시뮬레이션하고 반응을 검증할 수 있습니다.
- 미시적 차원(Micro Level): 개인 사용자나 연구자를 위한 창의적 샌드박스로 동작합니다. 소설의 잃어버린 결말을 추론하거나 상상 속 시나리오를 구체화하는 등 다양한 ‘만약(What if)’ 가설의 결과를 유연하게 탐색할 수 있습니다.
5단계 시뮬레이션 및 예측 워크플로우 분석
MiroFish는 초기 데이터 수집부터 최종 보고서 작성에 이르기까지 정형화된 5단계 파이프라인을 거쳐 예측 시뮬레이션을 완성합니다. 각 단계는 데이터의 정합성과 에이전트 간 맥락 연속성을 유지하도록 유기적으로 연결되어 있습니다.
- 그래프 구축(Graph Building): 현실 데이터에서 시드 정보를 추출하고 개별 및 집단 메모리를 주입하며 GraphRAG(Graph Retrieval-Augmented Generation) 지식 체계를 구축합니다.
- 환경 설정(Environment Setup): 데이터 속 개체 간 관계를 도출하고, 각 에이전트가 수행할 세부 페르소나를 생성한 뒤 에이전트별 동작 구성을 주입합니다.
- 시뮬레이션(Simulation): 듀얼 플랫폼 병렬 시뮬레이션을 구동하며, 예측 요구사항을 자동으로 파싱하고 동적 시간 메모리를 지속해서 갱신합니다.
- 보고서 생성(Report Generation): 시뮬레이션이 종료된 후 풍부한 도구 모음을 갖춘 ReportAgent가 가상 환경 데이터와 상호작용하여 종합 예측 보고서를 생성합니다.
- 심층 상호작용(Deep Interaction): 시뮬레이션된 가상 세계 내의 모든 개별 에이전트와 직접 대화할 수 있으며, ReportAgent와의 질의응답을 통해 세부 분석 근거를 추가로 확인할 수 있습니다.
로컬 환경 구축 사양과 필수 요구사항
MiroFish를 소스 코드로부터 직접 빌드하고 실행하기 위해서는 프론트엔드 및 백엔드 런타임 환경과 전용 패키지 관리 도구가 사전에 준비되어 있어야 합니다. 공식 문서에서 요구하는 기본 환경 기준은 다음과 같습니다.
- Node.js: 18 버전 이상 (npm 포함, 프론트엔드 구동 환경)
- Python: 3.11 이상 3.12 이하 (백엔드 구동 환경)
- uv: 최신 버전 (고속 Python 패키지 관리 도구)
또한 에이전트 간 추론 및 메모리 관리를 위해 외부 서비스 연동 구성이 필요합니다.
- LLM API 구성: OpenAI SDK 규격을 지원하는 모델 엔드포인트가 필요합니다. 공식 가이드에서는 Alibaba Bailian 플랫폼의 Qwen-plus 모델 사용을 권장합니다.
- Zep Cloud 구성: 에이전트 메모리 및 문맥 처리를 위해 Zep Cloud API 키가 사용되며, 간단한 테스트의 경우 무료 제공량 범위 내에서 활용 가능합니다.
소스코드 기반 환경 설정 및 단계별 실행 절차
# 1. 예제 환경 설정 파일 복사
cp .env.example .env
# 2. .env 파일 내 필수 환경 변수 입력 예시
# OpenAI SDK 규격 호환 LLM 설정 (Qwen-plus 권장)
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
# Zep Cloud 메모리 설정
ZEP_API_KEY=your_zep_api_key
# 3. 프로젝트 전체 의존성 일괄 설치 실행
npm run setup:all설치와 초기 구동은 다음 순서로 차례대로 진행합니다.
- 터미널에서
node -v,python --version,uv --version명령을 각각 실행하여 지원 버전 기준을 충족하는지 확인합니다. - 루트 디렉터리의
.env.example을 복사하여.env파일을 생성하고, 발급받은 LLM API 키와 Zep Cloud API 키를 입력합니다. - 프로젝트 루트 경로에서
npm run setup:all명령을 실행하여 루트, 프론트엔드, 백엔드의 모든 의존성 패키지를 일괄 설치합니다.
정상 결과 확인: 설치 과정에서 Python 가상환경 구성과 프론트엔드 패키지 의존성 다운로드가 완료되고, 콘솔에 치명적 에러 없이 종료 코드가 반환되면 정상적으로 배포 준비가 끝납니다.
대표적인 실패 원인 및 해결 방법: 의존성 설치 또는 실행 과정에서 오류가 발생하는 경우, 터미널에 출력된 오류 로그 메시지를 먼저 확인해야 합니다. .env 파일에 정의된 API 키와 Base URL 설정값의 오탈자 여부를 점검하고, 설치된 Node.js 및 Python의 실제 버전이 프로젝트 공식 문서의 요구 범위와 일치하는지 공식 설치 가이드를 참조하여 재확인합니다.
시뮬레이션 라운드 설정과 토큰 소모 관리
MiroFish는 수많은 에이전트가 가상 공간 내에서 동시 다발적으로 발언하고 정보를 갱신하는 구조를 가지고 있습니다. 시뮬레이션 라운드가 길어질수록 컨텍스트 누적과 호출 횟수로 인해 LLM 토큰 소모량이 급증하게 됩니다.
공식 문서에서는 높은 토큰 소모량을 고려하여, 초기 실행 단계에서는 시뮬레이션 라운드 수를 40라운드 미만으로 작게 설정하여 동작을 테스트할 것을 권장하고 있습니다. 시나리오의 기초 동작과 프롬프트 응답 상태를 먼저 확인한 후 점진적으로 라운드 수를 확장하는 것이 효율적인 리소스 관리 방안입니다.
