FastAPI와 LangGraph로 구축된 확장 가능한 AI 챗봇 플랫폼으로, 멀티 에이전트 오케스트레이션 (Multi-agent orchestration), 멀티 테넌트 벡터 스토리지 (Multi-tenant vector storage), 교차 채팅 메모리 (Cross-chat memory), 그리고 LiveKit 통합을 통한 음성 통화 기능을 특징으로 합니다.

demo.mp4

OAuth2 Password Flow: 보안 API 액세스를 위한 JWT 토큰 기반의 업계 표준 인증
User Registration System: 사용자 이름, 비밀번호, tenant_id를 포함한 완전한 등록 흐름
Multi-Tenant Architecture: 보안 및 프라이버시 강화를 위한 서로 다른 테넌트 간의 데이터 격리
Role-Based Access Control: 다양한 사용자 유형에 대한 세분화된 권한 제어

Multi-Agent System: 복잡한 작업을 해결하기 위해 함께 작동하는 전문화된 에이전트들
Supervisor Agent: 워크플로우를 조정하고 전문화된 에이전트에게 작업을 위임
Research Agent: 웹 및 지식 베이스에서 정보를 검색
Scraper Agent: 웹 페이지에서 콘텐츠를 추출하고 요약

Complex Workflows: 다단계 추론 및 작업 분해 처리
State Management: 여러 턴에 걸쳐 대화 문맥 유지

Multi-Tenant Vector Store: 테넌트 격리를 통해 대화 기록을 효율적으로 저장 및 검색
Semantic Search: 의미론적 유사성 (Semantic similarity)을 사용하여 관련 과거 대화 검색
Payload Filtering: 데이터 보안 및 성능을 위해 tenant_id를 통한 효율적인 필터링
Metadata Storage: 벡터 임베딩 (Vector embeddings)과 함께 추가적인 문맥을 저장 및 검색

Cross-Chat Memory: 서로 다른 대화 간에 중요한 정보를 기억
Long-Term Context: 장기적인 상호작용 동안 문맥 유지
Selective Memory: 어떤 정보를 기억할지 지능적으로 결정
Memory Retrieval: 대화 문맥을 기반으로 관련 메모리 검색

Firecrawl: 고급 웹 스크래핑 및 콘텐츠 추출

• 웹사이트에서 구조화된 데이터 추출
• 긴 형식의 콘텐츠 요약
• 표 및 목록 처리

Tavily: 지능형 웹 검색 기능

• 웹 전반에 걸친 시맨틱 검색 (Semantic search)
• 실시간 정보 검색 (Real-time information retrieval)
• 출처 표기 및 인용 (Source attribution and citation)

실시간 음성 통신 (Real-Time Voice Communication): LiveKit의 WebRTC 플랫폼을 사용한 자연스러운 음성 상호작용
고품질 음성 인식 (High-Quality Speech Recognition): Deepgram의 고급 STT (Speech-to-Text)를 통한 정확한 전사
자연스러운 텍스트 음성 변환 (Natural Text-to-Speech): Cartesia TTS를 통한 생생한 음성 응답
음성 활동 감지 (Voice Activity Detection): Silero VAD를 통한 지능적인 발화 순서 제어
다국어 지원 (Multilingual Support): 다양한 언어로 음성 상호작용 가능

포괄적인 트레이싱 (Comprehensive Tracing): 모든 LangChain 및 LangGraph 실행의 상세한 트레이스 캡처
시각적 디버깅 (Visual Debugging): 멀티 에이전트 워크플로우 및 메시지 전달 시각화
성능 모니터링 (Performance Monitoring): 다양한 구성 요소 전반의 지연 시간 (Latency), 토큰 사용량 및 비용 추적
피드백 수집 (Feedback Collection): 모델 응답에 대한 사용자 피드백 수집 및 분석
실험 추적 (Experiment Tracking): 다양한 프롬프트, 모델 및 에이전트 구성 비교

깔끔한 Material-UI 디자인 (Clean Material-UI Design): 현대적인 디자인 원칙을 적용한 직관적인 인터페이스
반응형 레이아웃 (Responsive Layout): 데스크톱과 모바일 기기 모두에서 원활한 경험 제공
실시간 채팅 인터페이스 (Real-Time Chat Interface): 사용자/어시스턴트 아바타가 포함된 동적 메시지 버블
마크다운 지원 (Markdown Support): 메시지 내 풍부한 텍스트 서식 지원
음성 모드 통합 (Voice Mode Integration): 텍스트와 음성 상호작용 간의 원활한 전환

FastAPI 프레임워크 (FastAPI Framework): 자동 OpenAPI 문서화를 지원하는 고성능 비동기 API 프레임워크
SQLAlchemy ORM: SQLite를 사용한 비동기 데이터베이스 작업 (PostgreSQL/MySQL로 구성 가능)
Pydantic 모델 (Pydantic Models): 타입 안전한 데이터 검증 및 직렬화
JWT 인증 (JWT Authentication): OAuth2 비밀번호 플로우를 사용한 보안 토큰 기반 인증

계정 등록 (Register an Account):

• /register 경로의 등록 페이지로 이동합니다.

• 고유한 사용자 이름, 안전한 비밀번호 및 할당된 tenant_id로 계정을 생성합니다.

• 각 tenant_id는 귀하의 데이터를 위한 격리된 환경을 생성합니다.

플랫폼 로그인 (Login to the Platform):- 메인 페이지에서 귀하의 자격 증명을 사용하여 로그인합니다.

• 귀하의 JWT 토큰은 이후의 API 호출을 위해 안전하게 저장됩니다.

대화 생성 (Creating Conversations):- 사이드바의 "+" 버튼을 클릭하여 새로운 대화를 시작합니다.

• 나중에 쉽게 참조할 수 있도록 대화에 의미 있는 제목을 지정합니다.

• 각 대화는 데이터 격리를 위해 귀하의 tenant_id와 함께 저장됩니다.

AI와 상호작용 (Interacting with the AI):- 입력 필드에 메시지를 입력하고 Enter를 누르거나 전송 버튼을 클릭합니다.

• AI 응답은 토큰 단위 업데이트와 함께 실시간으로 스트리밍됩니다.

• 메시지는 사용자와 어시스턴트를 쉽게 구분할 수 있도록 명확한 아바타와 함께 표시됩니다.

• 시스템은 사용자 및 어시스턴트 메시지 모두에서 마크다운 (Markdown) 형식을 지원합니다.

대화 관리 (Managing Conversations):- 사이드바 탐색을 통해 이전 대화에 접근합니다.

• 대화 기록을 검색합니다.

음성 모드 실행 (Launching Voice Mode):- 채팅 인터페이스의 마이크 아이콘을 클릭하여 음성 모드를 활성화합니다.

• 아직 권한이 부여되지 않은 경우 시스템이 마이크 권한을 요청합니다.

• 말을 하기 전에 "Voice Assistant Ready" 메시지가 나타날 때까지 기다립니다.

음성 상호작용 (Voice Interaction):- "Listening..." 표시가 나타나면 자연스럽게 말씀하세요.

• 어시스턴트가 귀하의 음성을 처리하고 음성으로 응답합니다.

• 시각적 피드백을 통해 귀하의 음성과 어시스턴트의 응답에 대한 전사 (Transcription) 내용을 확인할 수 있습니다.

• 음성 어시스턴트는 대화 중 자연스러운 차례 주고받기 (Turn-taking)를 지원합니다.

고급 음성 기능 (Advanced Voice Features):- 시스템이 귀하의 말이 끝났음을 자동으로 감지합니다.

• 음성 활동 감지 (Voice Activity Detection, VAD)가 배경 소음을 필터링합니다.

• 다국어 지원을 통해 다양한 언어로 상호작용할 수 있습니다.

• 다양한 환경에 맞춰 음성 품질 설정을 조정할 수 있습니다.

음성 세션 종료 (Ending a Voice Session):- 연결 해제 버튼을 클릭하여 음성 세션을 종료합니다.

• 대화 기록은 향후 참조를 위해 보존됩니다.

AI 어시스턴트는 귀하의 경험을 향상시키기 위해 강력한 외부 도구들을 활용할 수 있습니다:

웹 검색 (Web Search): 웹에서 최신 정보가 필요한 질문을 합니다.
웹 스크래핑 (Web Scraping): 특정 웹사이트로부터 요약 또는 정보를 요청합니다.

• Python 3.13+

• Node.js 16+

• npm 8+

• Qdrant (Docker를 통해 실행 가능)

• 저장소(Repository) 복제

git clone <repository-url>
cd ruban_fastapi-langgraph-chatbot

• 가상 환경(Virtual Environment) 생성 및 활성화

python -m venv venv
source venv/bin/activate # Windows의 경우: venv\Scripts\activate

• Python 의존성(Dependencies) 설치

pip install -r requirements.txt

• 환경 변수(Environment Variables) 설정

루트 디렉토리에 다음과 같은 변수들을 포함하는 .env 파일을 생성합니다:

# FastAPI 설정
SECRET_KEY=your_secret_key_here
ACCESS_TOKEN_EXPIRE_MINUTES=30
...

• 프론트엔드(Frontend) 디렉토리로 이동

cd frontend

• Node.js 의존성(Dependencies) 설치

npm install

• MCP 서버 시작 (별도의 터미널에서 실행)

# 터미널 1: 검색 서버 시작
python -m app.mcp_server.search_server
# 터미널 2: 웹 스크래핑 서버 시작
...

• 메인 FastAPI 서버 시작

python app.py

• LiveKit 음성 어시스턴트 시작

python app/agent/livekit_agent.py dev

cd frontend
npm start

• 백엔드 API 문서: http://localhost:8000/docs
• 프론트엔드 인터페이스: http://localhost:3000

계정이 없는 경우, 먼저 등록한 후 로그인하여 채팅 인터페이스에 접속하세요.