MiroFish 배포 및 실전: 제로 베이스에서 여론 시뮬레이션 시스템 구축하기

서문

정책 발표 후 네티즌들의 반응이나, PR 위기가 가져올 연쇄적인 영향을 미리 알 수 있다면 어떨지 생각해 보신 적이 있나요?

전통적인 여론 분석은 과거 데이터와 전문가의 경험에 의존하며, 본질적으로는 「과거를 돌아보는 것」입니다. 하지만 MiroFish는 우리에게 완전히 새로운 사고방식을 제시합니다. AI가 고정밀 디지털 평행 세계를 구축하고, 독립적인 인격과 장기 기억을 가진 수만 명의 에이전트들이 그 안에서 자유롭게 상호작용하게 한 뒤, 집단 행동의 발현을 관찰하는 것입니다.

이것이 바로 이른바 「집단 지능」(Swarm Intelligence)입니다.

MiroFish는 2025년에 오픈 소스로 공개된 다중 에이전트(Multi-agent) 예측 엔진으로, OASIS 시뮬레이션 엔진을 기반으로 작동합니다. 어떤 시드 자료(보도 자료, 분석 보고서, 심지어 소설 플롯까지)라도 입력받아 자동으로 디지털 세계를 구축하고 예측 보고서를 출력할 수 있습니다.

오늘은 제로 베이스에서 시작하여 MiroFish를 배포하고 간단한 여론 시뮬레이션 시스템을 구축해 보겠습니다.

핵심 개념

시작하기 전에 몇 가지 핵심 개념을 먼저 이해해 봅시다.

시드 정보(Seed Information)

시드 정보는 예측의 시작점입니다. 뉴스 기사, 금융 분석 보고서, 소설의 한 대목, 혹은 소셜 미디어의 화제성 토론이 될 수도 있습니다. MiroFish는 이러한 자료에서 핵심 엔티티, 인물 관계 및 사건 배경을 추출합니다.

디지털 평행 세계

이것은 MiroFish의 가장 핵심적인 혁신입니다. 단순히 AI가 텍스트를 생성하는 것이 아니라, 실제로 하나의 「세계」를 구축합니다:

• 각 에이전트는 독립적인 인격, 기억, 행동 로직을 가집니다.
• 에이전트들끼리 상호작용하고, 정보를 전파하며, 파벌을 형성합니다.
• 시스템 전체에서 개별 행동으로는 예측할 수 없는 집단적 특성이 나타납니다.

가상의 뉴스 하나를 이 세계에 던져놓고 그것이 어떻게 확산되고, 반전되고, 최종적으로 여론을 형성하는지 관찰하는 것—이것이 바로 디지털 평행 세계의 힘입니다.

워크플로우

MiroFish의 전체 워크플로우는 5단계로 나뉩니다:

1. 그래프 구축: 시드 자료에서 엔티티와 관계를 추출하여 지식 그래프를 구축합니다.
2. 환경 설정: 에이전트 페르소나를 생성하고 시뮬레이션 파라미터를 설정합니다.
3. 시뮬레이션 실행: 듀얼 플랫폼 병렬 시뮬레이션을 통해 기억을 동적으로 업데이트합니다.
4. 보고서 생성: ReportAgent가 시뮬레이션 결과를 분석하여 예측 보고서를 생성합니다.
5. 심층 상호작용: 시뮬레이션 세계 속의 임의의 캐릭터와 대화할 수 있습니다.

---

환경 준비

MiroFish는 풀스택 프로젝트로, 프런트엔드와 백엔드를 분리하여 배포합니다.

하드웨어 요구 사항

소프트웨어 의존성

환경을 확인해 보세요:

node -v    # 18.0.0 이상이어야 함
python --version  # 3.11 - 3.12 사이여야 함
uv --version

---

빠른 배포

유연한 커스터마이징을 위해 소스 코드 배포 방식을 시연합니다.

1. 프로젝트 클론

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish

2. 환경 변수 설정

cp .env.example .env

.env 파일을 편집하여 API 설정을 입력합니다. 두 가지 옵션이 있습니다:

옵션 A: Alibaba Bailian 사용 (공식 권장)

LLM_API_KEY=your_aliyun_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

옵션 B: 기타 OpenAI 호환 API 사용

LLM_API_KEY=your_api_key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o

Zep Cloud 설정도 필요합니다 (에이전트 기억 관리용):

ZEP_API_KEY=your_zep_api_key

3. 의존성 설치

npm run setup:all

이 명령은 다음을 동시에 설치합니다:

• 루트 디렉터리의 Node 의존성
• 프런트엔드 의존성
• Python 의존성 (가상 환경 자동 생성)

네트워크가 느리다면 단계별로 실행할 수 있습니다:

npm run setup           # 프런트엔드
npm run setup:backend   # 백엔드

4. 서비스 시작

npm run dev

서비스 시작 후:

• 프런트엔드: http://localhost:3000
• 백엔드 API: http://localhost:5001

Docker 배포 대안

빠르게 시작하고 싶다면 Docker를 사용할 수도 있습니다:

# 1. 환경 변수 설정
cp .env.example .env

# 2. 컨테이너 실행
docker compose up -d

Docker 방식은 3000(프런트엔드) 및 5001(백엔드) 포트를 자동으로 매핑합니다.

---

실전 실습

이제 여론 시뮬레이션 작업을 만들어 보겠습니다.

1. Web UI 접속

브라우저에서 http://localhost:3000을 열면 MiroFish의 메인 인터페이스가 나타납니다.

2. 예측 작업 생성

「새 예측」을 클릭하고 「여론 시뮬레이션」 타입을 선택합니다.

3. 시드 자료 입력

텍스트 박스에 뉴스 소재를 입력합니다. 예:

한 유명 IT 기업이 오늘 핵심 분야 집중을 위해 직원의 10%를 감원하겠다고 발표했습니다.
소식 발표 직후 소셜 미디어에서 뜨거운 논쟁이 벌어졌습니다. 일부 직원은 사전 소통이 없었다며
불만을 표시했고, 일부 네티즌은 기업의 경영 압박을 이해한다는 반응을 보였습니다.
해당 기업 CEO는 내부 서신을 통해 어렵지만 필요한 결정이었음을 강조하며,
두둑한 퇴직금과 재취업 기회 추천을 약속했습니다.

4. 예측 요구 사항 설명

무엇을 예측하고 싶은지 자연어로 설명합니다:

이 감원 소식이 발표된 후 네티즌들의 반응이 어떻게 변할지 예측해 줘.
부정적인 여론이 형성될까? 얼마나 지속될까? 어떤 집단이 어떤 입장을 취할까?

5. 시뮬레이션 시작

「시뮬레이션 시작」을 클릭하면 시스템은:

1. 시드 자료에서 핵심 엔티티(회사, CEO, 직원, 네티즌)를 추출합니다.
2. 지식 그래프를 구축합니다.
3. 다양한 페르소나를 가진 에이전트를 생성합니다(직원에게 동조하는 네티즌, 이성적인 분석가, 방관자 등).
4. 상호작용 시뮬레이션을 시작합니다.

6. 예측 결과 확인

시뮬레이션이 완료되면 다음과 같은 상세 보고서가 표시됩니다:

• 여론 변화 추이 곡선
• 주요 관점 분포
• 핵심 전환점 예측
• 제안되는 대응 전략

7. 심층 상호작용

MiroFish의 가장 재미있는 부분입니다. 다음이 가능합니다:

• 임의의 에이전트와 1:1 대화: "당신은 직원을 동정하는 네티즌인데, 이 사건을 어떻게 보나요?"
• ReportAgent에게 구체적인 질문: "만약 회사가 공개 사과문을 발표한다면 여론이 어떻게 변할까?"

---

AI Provider 설정

위에서는 Alibaba Bailian 모델을 사용했습니다. 하지만 비용을 낮추거나 다른 모델을 사용하고 싶다면 Defapi 플랫폼을 고려해 보세요.

Defapi는 API 중계 서비스로, 가격이 공식 가격의 절반 수준이며 다음을 지원합니다:

• OpenAI (GPT-4o, GPT-4.5)
• Anthropic (Claude Sonnet, Claude Opus)
• Google (Gemini)

OpenAI SDK와 완전히 호환되므로 두 개의 파라미터만 수정하면 됩니다:

# Defapi 사용 시
LLM_API_KEY=your_defapi_key
LLM_BASE_URL=https://api.defapi.org/v1
LLM_MODEL_NAME=openai/gpt-4o-mini

또는 코드에서 사용 시:

from openai import OpenAI

client = OpenAI(
    api_key="your_defapi_key",
    base_url="https://api.defapi.org/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

---

자주 발생하는 문제 해결

1. npm install 실패

Node.js 버전을 확인하세요:

node -v

18+ 버전이어야 합니다. 버전이 맞는데도 실패한다면 다음을 시도하세요:

npm cache clean --force
npm install --legacy-peer-deps

2. Python 의존성 설치 중단

Python 버전이 3.11-3.12 사이인지 확인하세요:

python --version

이 범위에 없다면 pyenv나 conda를 사용하여 버전을 관리해야 합니다.

3. 백엔드 시작 시 "Model not found" 오류

LLM_MODEL_NAME이 정확한지 확인하세요. Provider마다 모델 명칭 형식이 다릅니다:

• Alibaba Bailian: qwen-plus
• OpenAI: gpt-4o
• Defapi: openai/gpt-4o-mini

4. 시뮬레이션 실행이 너무 느림

최적화 방법:

• 시뮬레이션 라운드 수 줄이기 (40에서 20으로)
• 더 가벼운 모델 사용
• 에이전트 수 줄이기
• 네트워크 상태 확인 (API 호출 지연)

5. 메모리 점유율이 너무 높음

메모리가 16GB 미만이라면 .env에서 동시 실행 수를 제한하세요:

MAX_CONCURRENT_AGENTS=10

또는 매 라운드 상호작용하는 에이전트 수를 줄이세요.

6. 프런트엔드 페이지가 공백으로 나옴

백엔드가 정상 작동 중인지 확인하세요:

curl http://localhost:5001/health

오류가 반환된다면 .env 설정이 제대로 로드되었는지 확인하세요.

---

고급 활용 방향

에이전트 페르소나 커스터마이징

MiroFish는 작업 생성 시 에이전트 설정을 커스터마이징할 수 있습니다. 다음을 지정할 수 있습니다:

• 연령, 직업, 성격 특성
• 입장 성향 (찬성/반대/중립)
• 배경 스토리

정교한 페르소나 조정을 통해 시뮬레이션을 실제 상황에 더 가깝게 만들 수 있습니다.

더 많은 데이터 소스 연결

현재는 텍스트 시드 자료를 지원합니다. 향후 다음을 연결할 수 있습니다:

• 소셜 미디어 API (실제 여론 데이터 크롤링)
• 뉴스 RSS 피드
• 금융 데이터베이스

응용 시나리오 확장

여론 시뮬레이션뿐만 아니라 MiroFish는 다음과 같이 활용될 수 있습니다:

• 금융 예측: 시장 심리 변화 시뮬레이션
• 정책 시뮬레이션: 정책 발표 후 사회적 반응 예측
• 창의적 글쓰기: 소설 플롯 전개 예측 (예: AI에게 《홍루몽》 후반부 40회 예측 시키기)
• 위기 시뮬레이션: PR 위기 대응 전략 훈련

---

심화 학습

• GitHub 저장소: https://github.com/666ghj/MiroFish
• 온라인 데모: https://666ghj.github.io/mirofish-demo/
• 공식 문서: https://deepwiki.com/666ghj/MiroFish
• Defapi 플랫폼: https://defapi.org
• OASIS 엔진: https://github.com/camel-ai/oasis

다중 에이전트 시스템에 관심이 있고 「AI로 미래를 예측하는」 경험을 직접 해보고 싶다면 MiroFish는 훌륭한 시작점이 될 것입니다.