RealChar: 오픈소스 플랫폼으로 AI 역할에 "생명" 불어넣기
2026년, AI 챗봇이 넘쳐나는 시대에 여전히 대부분의 제품은 "텍스트 대화" 수준에 머무르고 있습니다——텍스트를 입력하면 AI가 텍스트로 응답하고, 상호작용은 단조롭고 몰입감이 떨어집니다.RealChar은 이 정체를 깨뜨립니다: 완전 오픈소스 AI 실시간 역할 상호작용 플랫폼으로, 사용자는 독특한 성격과 배경을 가진 AI 역할을 생성하는 것뿐 아니라 음성을 통해 실시간으로 대화할 수 있습니다. 마치 실제 사람과 이야기하는 것처럼요.
RealChar 프로젝트는 GitHub에서 8,000개 이상의 별을 얻었고, LangChain 공식 블로그에서는 "오픈소스 도구를 사용하여 AI 동반자 구축"의 전형 사례로 추천합니다. 핵심 아이디어는 간단합니다:누구나 코딩 없이 자신만의 AI 역할을 만들고, 가장 자연스러운 방법——음성——으로 상호작용할 수 있도록 하는 것.
이 글에서는 RealChar의 기술 아키텍처, 배포 방법, 역할 생성 프로세스, 실시간 상호작용 메커니즘을 상세히 살펴보고, 교육, 엔터테인먼트, 고객 서비스 분야에서의 응용 가능성도 탐구합니다.
기술 아키텍처: 모듈러 설계로 유연한 확장성 지원
RealChar의 기술 스택은 일반적인 현대 웹 애플리케이션 아키텍처를 기반으로 하지만, AI 기능 통합에는 많은 혁신이 있었습니다. 시스템은 네 개의 핵심 레이어로 나눌 수 있습니다.
프론트엔드 상호작용 레이어
RealChar는 세 가지 유형의 클라이언트를 제공합니다.
- 웹 클라이언트: React.js와 Vanilla JS로 구축되어 WebSocket을 통해 실시간 양방향 통신을 구현합니다. 인터페이스는 간결하고 직관적이며 텍스트 및 음성 두 가지 상호작용 모드를 모두 지원합니다.
- 모바일 클라이언트: iOS용으로 Swift 네이티브로 개발되었으며, 마찬가지로 WebSocket 기반입니다. 모바일 경험이 부드럽고, 오픈소스 모바일 AI 역할 앱은 극히 드뭅니다.
- 터미널 CLI: 개발자를 대상으로 하는 커맨드라인 클라이언트로, 빠른 테스트 및 통합에 적합합니다.
백엔드 서비스 레이어
백엔드는 FastAPI 프레임워크를 사용합니다. FastAPI는 높은 성능을 가진 Python 웹 프레임워크로, 비동기 처리와 WebSocket을 기본적으로 지원합니다. FastAPI의 주요 역할은 다음과 같습니다.
- 사용자 세션 및 역할 상태 관리
- LLM 추론, 음성 인식, 음성 합성 호출 흐름 조정
- WebSocket을 통해 프론트엔드로 실시간 오디오 스트림 푸시
- 외부 시스템 통합을 위한 RESTful API 제공
데이터 스토리지에는 개발 환경에서는 SQLite, 프로덕션 환경에서는 PostgreSQL을 사용하며, 역할 구성, 대화 기록, 사용자 정보 등 구조화된 데이터를 저장합니다.
AI 기능 레이어
여기서 RealChar의 진정한 경쟁 우위가 드러납니다. 최상위 수준의 AI 서비스를 통합했습니다.
대규모 언어 모델(LLM): 다음의 주요 LLM을 지원합니다.
- OpenAI GPT-4 / GPT-3.5
- Anthropic Claude 2
- Anyscale Llama2 (오픈소스 모델)
- ReByte 플랫폼 (권장, 통합된 API 인터페이스 제공)
- 로컬 LLM (OpenAI 호환 API를 통해)
음성 인식(STT):
- 로컬 Whisper / WhisperX (로컬 배포에 권장)
- OpenAI Whisper API
- Google Speech-to-Text
음성 합성(TTS):
- Edge TTS (기본값, 무료)
- ElevenLabs (고품질, 음성 클론 지원)
- Google Text-to-Speech
벡터 데이터베이스: Chroma를 사용하여 역할의 지식 베이스를 벡터 형태로 저장합니다. 이를 통해 RAG(Retrieval-Augmented Generation)를 활성화하여 역할이 특정 분야의 지식을 바탕으로 대화할 수 있게 합니다.
데이터 섭취 레이어
LlamaIndex를 이용해 지식을 ingest(섭취)합니다. 문서, 웹 페이지, 데이터베이스 등 외부 지식 소스를 벡터로 변환해 Chroma에 저장합니다.こう함으로써 예를 들어 "역사학자" 역할에 역사 문서를 먹이거나, "제품 전문가" 역할에 제품 매뉴얼을 공급할 수 있습니다.
Docker 배포: 5분 내 빠른 시작
RealChar는 완전한 Docker 지원을 제공하며, 이것이 권장 배포 방법입니다. 단계는 단 3가지입니다.
단계 1: 리포지토리 복제 및 환경 변수 설정
git clone https://github.com/Shaunwei/RealChar.git
cd RealChar
cp .env.example .env
.env 파일을 편집해 API 키를 입력합니다. 최소 구성이라면 LLM API 키 1개만 필요합니다.
# 방법 1: ReByte 사용 (권장)
REBYTE_API_KEY=당신의_rebyte_api_key
# 방법 2: OpenAI 사용
OPENAI_API_KEY=당신의_openai_api_key
# 음성 인식 설정 (로컬 Whisper 권장)
SPEECH_TO_TEXT_USE=LOCAL_WHISPER
LOCAL_WHISPER_MODEL=base
# 음성 합성 설정 (Edge TTS는 무료)
EDGE_TTS_DEFAULT_VOICE=en-US-ChristopherNeural
단계 2: Docker 컨테이너 시작
docker compose up
이 명령은 세 가지 서비스를 자동으로 빌드하고 시작합니다.
- db: PostgreSQL 데이터베이스 서비스
- backend: FastAPI 백엔드 서비스 (포트 8000)
- web: React 프론트엔드 서비스 (포트 3000)
docker-compose.yaml의 전체 내용은 다음과 같습니다.
version: '3.8'
services:
db:
build:
context: .
dockerfile: Dockerfile.postgres
restart: always
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
PGDATA: /var/lib/postgresql/data/realchar
ports:
- '5432:5432'
volumes:
- db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
backend:
build:
context: .
dockerfile: Dockerfile
ports:
- "8000:8000"
depends_on:
db:
condition: service_healthy
env_file:
- ./.env
environment:
- DATABASE_URL=postgresql://postgres:***@db:5432/postgres
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/status"]
interval: 10s
timeout: 5s
retries: 5
web:
build:
context: ./client/next-web/
dockerfile: Dockerfile.dev
ports:
- "3000:3000"
depends_on:
backend:
condition: service_healthy
db:
condition: service_healthy
environment:
- NEXT_PUBLIC_API_HOST=http://localhost:8000
- API_HOST=http://backend:8000
volumes:
db:
driver: local
단계 3: 애플리케이션 접근
브라우저에서 http://localhost:3000을 열어 RealChar 웹 인터페이스를 확인합니다. 사전 설정된 역할을 선택하고 대화를 시작하세요!
참고 사항:
- Docker Desktop(Windows/Mac)을 사용할 경우 충분한 메모리를 할당하세요(권장: 8 GB+).
- 첫 시작 시 의존성과 모델 다운로드가 발생하며, 10~20분 정도 소요될 수 있습니다.
- 원격 접근이 필요할 경우 SSL 설정이 필수입니다(WebSocket은 HTTPS를 요구함).
Python 배포: 개발자 친화적
직접 Python 환경을 관리하거나 소스 코드를 수정하고 싶다면 Python 배포 방법도 이용 가능합니다.
환경 준비
# 리포지토리 복제
git clone https://github.com/Shaunwei/RealChar.git
cd RealChar
# 시스템 의존성 설치
# macOS
brew install portaudio ffmpeg
# Ubuntu
sudo apt update
sudo apt install portaudio19-dev ffmpeg
# 가상 환경 생성 (권장)
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\\Scripts\\activate # Windows
# Python 의존성 설치
pip install -r requirements.txt
# (선택 사항) 로컬 음성 인식을 빠르게 하기 위해 WhisperX 설치
pip install git+https://github.com/m-bain/whisperX.git
데이터베이스 초기화
# SQLite 데이터베이스 생성
sqlite3 test.db "VACUUM;"
# 데이터베이스 마이그레이션 실행
alembic upgrade head
서비스 시작
# 환경 변수 설정
cp .env.example .env
# .env 파일을 편집해 API 키 입력
# 백엔드 시작
python cli.py run-uvicorn
# 또는 직접 uvicorn 사용
uvicorn realtime_ai_character.main:app
# 프론트엔드 시작 (새 터미널 창)
cd client/next-web
cp .env.example .env
npm install
npm run dev
이제 http://localhost:3000에서 애플리케이션에 접근할 수 있습니다.
맞춤형 AI 역할 생성
RealChar의 핵심 가치는 독특한 AI 역할을 생성할 수 있는 능력에 있습니다. 두 가지 방법이 있습니다.
방법 1: 웹 UI를 이용한 생성 (코딩 불필요)
- 웹 인터페이스에 로그인한 뒤 "Create Character"를 클릭합니다.
- 역할 정보를 입력합니다. - 이름: 역할 이름 - 설명: 역할에 대한 간단한 설명 - 성격: 성격 설명 (예: "친절하고 유머러스하며 인내심 있음") - 배경: 역할의 배경 스토리 (예: "십자군에 참여한 중세 기사") - 인사말: 역할의 첫 마디
- (선택 사항) 아바타를 업로드합니다.
- 음성을 선택합니다 (ElevenLabs를 쓰는 경우 특정 음성을 클론할 수 있음).
- "저장"을 클릭해 역할을 생성합니다.
방법 2: 코드를 이용한 생성 (고급 사용자 대상)
realtime_ai_character/character_catalog/ 디렉터리에 새로운 YAML 파일을 만듭니다.
# my_character.yaml
name: "역사학자 아리스토텔레스"
description: "고대 그리스 철학자, 철학·과학·정치에 정통"
personality: |
당신은 erudite한 고대 그리스 철학자로, 말에는 지혜가 가득하며 비유와 스토리를 활용해 복잡한 개념을 설명하는 것을 즐깁니다.
지식을 향한 열정이 넘치며 대화의 본질을 파고들도록 이끕니다.
배경: |
아리스토텔레스(기원전 384년~기원전 322년)는 고대 그리스 철학자로, 플라톤의 제자이며 알렉산더 대제의 스승입니다.
그의 저작물은 물리학, 형태학, 윤리학, 정치학, 생물학 등 다양한 영역을 포괄합니다.
관찰과 논리적 추론을 통해 세계의 본질을 이해할 수 있다고 믿습니다.
인사말: "젊은 지식의 탐구자여, 안녕. 나는 아리스토텔레스. 함께 진리의 비밀을 탐구해 보자."
음성: "en-US-ChristopherNeural" # Edge TTS 음성
# 또는 ElevenLabs: voice_id: "당신의 음성 ID"
파일을 저장한 뒤 백엔드를 재시작하면 역할이 자동으로 로드됩니다.
역할에 지식베이스 추가
RealChar는 RAG(Retrieval-Augmented Generation)를 지원하여 역할이 특정 지식에 기반해 대화할 수 있게 합니다.
# LlamaIndex를 이용해 지식 섭취
from llama_index import VectorStoreIndex, SimpleDirectoryReader
from realtime_ai_character.database.chroma import get_chroma
# 문서 로드
documents = SimpleDirectoryReader("knowledge_docs/").load_data()
# 벡터 인덱스 생성
index = VectorStoreIndex.from_documents(documents)
# Chroma에 저장
chroma = get_chroma()
chroma.add_character_knowledge("아리스토텔레스", index)
이제 "아리스토텔레스"에게 윤리에 대해 물었을 때, 사용자가 제공한 문서를 기반으로 전문적인 답변을 돌려줄 수 있습니다.
실시간 상호작용 메커니즘
실시간 경험이야말로 RealChar의 biggest 강점입니다. 상호작용 흐름은 다음과 같습니다.
음성 상호작용 흐름
- 사용자 발화: 브라우저 마이크가 음성을 포착합니다.
- 음성 인식: 음성이 WebSocket을 통해 백엔드로 전송되고, Whisper/WhisperX로 텍스트로 변환됩니다.
- LLM 추론: 텍스트가 LLM(예: GPT-4)으로 전송되어 응답이 생성됩니다.
- 음성 합성: 응답 텍스트가 ElevenLabs/Edge TTS로 음성으로 변환됩니다.
- 실시간 푸시: 음성이 WebSocket을 통해 스트림 형태로 프론트엔드로 푸시되어 재생됩니다.
전체 과정은 보통 1~3초 정도 소요되며, 지연의 주요 원인은 LLM 추론과 음성 합성입니다.
지연 줄이는 팁
- GPT-3.5 사용 (추론이 더 빠름)
- 로컬 WhisperX에 GPU 추가 (로컬 음성 인식을 가속화)
- ElevenLabs V2 사용 (더 빠른 TTS)
- 스트리밍 응답 활성화 (RealChar는 기본적으로 지원)
텍스트 상호작용
음성을 사용하고 싶지 않다면 텍스트 상자에 직접 입력할 수 있습니다.这样的话音성 인식 및 음성 합성 단계를 건너뛰고 순수 텍스트 응답만 반환됩니다.
활용 사례
유연한 아키텍처 덕분에 RealChar는 다양한 시나리오에 적용할 수 있습니다.
1. 가상 어시스턴트
"제품 관리자 어시스턴트" 역할을 만들어 제품 문서, 사용자 피드백, 경쟁사 정보를 학습시킵니다. 팀원은 음성으로 질문할 수 있습니다: "지난 주 사용자 피드백에서 가장 큰 불만점은 무엇이었나요?" 역할은 지식 기반에 따라 답변합니다.
2. 온라인 교육
"물리 선생님 뉴턴" 역할을 만들어 물리 교재를 임포트합니다. 학생은 "뉴턴"과 역학에 대해 토론하며 역사와 물리학을 결합한 몰입형 학습 경험을 얻을 수 있습니다. 기존 교과서보다 훨씬 매력적입니다.
3. 엔터테인먼트 및 동반자
"유머러스한 스탠드업 코미디언" 역할을 만들어 유머러스한 성격과 배경을 설정합니다. 사용자는 편안히 대화를 나누거나 심지어 "코미디 대결"을 펼칠 수 있습니다.
4. 고객 서비스 봇
전자상거래 사이트를 위해 "전문 고객 서비스 소왕" 역할을 만들어 제품 매뉴얼, 반품 정책, FAQ를 학습시킵니다. 고객은 음성으로 주문 상태 또는 반품 절차 등을 문의할 수 있으며, 기존의 텍스트 기반 고객 서비스보다 훨씬 자연스러운 상호작용이 가능합니다.
5. 언어 학습
"영어 선생님 엠마" 역할을 만들어 인내심 있고 친절한 미국 교사로 설정합니다. 학습자는 엠마와 영어 회화를 연습하면서 발음 교정 및 학습 조언을 받을 수 있습니다.
다른 AI 채팅 플랫폼과의 비교
RealChar는 일반적인 AI 채팅 제품과 명확히 구분됩니다.
| 기능 | RealChar | Character.AI | 간단한 챗봇 |
|---|---|---|---|
| 오픈소스 | ✅ 완전 오픈 | ❌ 폐쇄형 | ❌ 폐쇄형 |
| 음성 상호작용 | ✅ 실시간 음성 | ❌ 텍스트만 | ❌ 텍스트만 |
| 셀프 호스팅 | ✅ Docker/Python | ❌ 클라우드 전용 | ❌ 클라우드 전용 |
| LLM 선택 | ✅ 다중 모델 지원 | ❌ 고정 모델 | ❌ 고정 모델 |
| 지식 베이스는 | ✅ RAG 지원 | ❌ 제한적 | ❌ 제한적 |
| 음성 클론 | ✅ ElevenLabs | ❌ 미지원 | ❌ 미지원 |
| 데이터 프라이버시 | ✅ 로컬 호스팅 | ❌ 클라우드 저장 | ❌ 클라우드 저장 |
| 커스터마이징 | ✅ 고도로 커스터마이징 가능 | ⚠️ 제한적 | ⚠️ 제한적 |
RealChar의 장점: - 완전 오픈소스: 소스 코드를 자유롭게 수정하여 특정 요구사항에 맞출 수 있음. - 실시간 음성 상호작용: 진정한 "대화" 경험을 제공하며 텍스트 채팅에 머무르지 않음. - 데이터 프라이버시: 로컬 호스팅으로 데이터가 외부로 유출되지 않음. - 확장성: 모듈러 구조 덕분에 신규 기능 추가가 용이함.
RealChar의 단점: - 셀프 호스팅 및 유지 관리가 필요함. - API 키가 필요함(사용 시 비용이 발생할 수 있음). - 모바일 앱은 현재 iOS만 지원함.
향후 로드맵
RealChar의 GitHub 로드맵에 따르면 향후 중점 개발 분야는 다음과 같습니다.
- ✅ 세션 관리: 멀티턴 대화의 컨텍스트 관리를 지원.
- ✅ RAG 강화: 지식베이스 관리 기능을 더욱 강화.
- ✅ Agents/GPTs 지원: 에이전트 기능을 통합해 역할이 복잡한 작업을 수행할 수 있도록 함.
- ✅ 다양한 TTS 서비스: 추가 음성 합성 엔진 지원.
- ⏳ 멀티모달 상호작용: 앞으로 이미지·비디오 입력을 지원할 가능성.
- ⏳ 역할 마켓플레이스: 사용자가 역할 설정을 공유하고 다운로드할 수 있는 플랫폼.
커뮤니티는 Discord에서 활발히 활동하며 정기적인 업데이트 및 유지보수가 이루어지고 있습니다. 프로젝트는 MIT 라이선스로 공개되어 있으며, 기여를 환영합니다.
결론
RealChar는 오픈소스 AI 실시간 역할 상호작용 플랫폼으로서 매우 유망합니다. 단순한 기술 스택 제공을 넘어, 실시간 음성 상호작용을 통해 전통적인 텍스트 채팅의 한계를 넘어섭니다.
대상 사용자: - 맞춤형 AI 동반자를 만들고 싶은 모든 사람 - AI 역할 기능이 필요한 개발자 - 데이터 프라이버시를 중시하고 로컬 배포를 선호하는 기업 - AI 에이전트 및 실시간 상호작용에 관심 있는 연구자
빠른 시작:
git clone https://github.com/Shaunwei/RealChar.git
cd RealChar
cp .env.example .env
# .env에 API 키 입력
docker compose up
# 브라우저에서 http://localhost:3000 접속
일상적인 가상 대화 상대를 찾고 있든, 기업용 인텔리전트 고객 서비스 시스템을 구축하고 있든, RealChar는 견고한 기반을 제공합니다. 오픈소스라는 특성 덕분에 커뮤니티가 협력하여 플랫폼을 continually 발전시키고 끊임없이 놀라운 응용 프로그램을 만들어낼 수 있습니다.