Molayo

© 2026 Molayo

GitHub요약2026. 06. 25. 17:35

FastAPI와 LangGraph를 사용하여 구축한 벡터 스토어 메모리, MCP 도구 및 음성 모드를 갖춘 확장 가능한 AI 챗봇 플랫폼

요약

FastAPI와 LangGraph를 활용하여 멀티 에이전트 오케스트레이션, 멀티 테넌트 벡터 스토리지, 음성 모드를 갖춘 확장 가능한 AI 챗봇 플랫폼 구축 방법을 소개합니다. 보안 인증, 데이터 격리, 실시간 음성 통신 기능을 포함한 엔터프라이즈급 아키텍처를 다룹니다.

핵심 포인트

  • LangGraph 기반의 멀티 에이전트 워크플로우 및 상태 관리
  • 테넌트 격리를 지원하는 멀티 테넌트 벡터 스토리지 구현
  • LiveKit, Deepgram, Cartesia를 활용한 실시간 음성 상호작용
  • OAuth2 및 RBAC를 적용한 보안 및 권한 제어 시스템
  • Firecrawl과 Tavily를 이용한 고급 웹 검색 및 스크래핑

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

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

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0