Open-source AI real estate search with RAG, vector search, multi-provider LLMs, FastAPI, Next.js, ChromaDB, and a live demo.

AI 부동산 어시스턴트 – 개요

정의 – 사용자가 "크라쿠프에서 500k 미만의 2베드룸 아파트" 같은 자연어 쿼리를 입력하여 주택을 검색하고, 가상 어시스턴트와 대화하며, 재무 분석 도구를 실행할 수 있는 오픈소스 AI 기반 웹 앱입니다. 핵심 제품은 최대 16개 LLM 제공업체와 통신하는 FastAPI 백엔드(Python 3.12+), 의미 검색을 위한 ChromaDB 벡터 저장소, 그리고 부동산 카탈로그를 위한 PostgreSQL/SQLite 데이터베이스입니다. Next.js 16 + React 19 프론트엔드는 UI, 지도, 분석 대시보드를 제공합니다.

📦 핵심 기능 (README에 설명된 대로)

기능	제공 내용	작동 방식 (개괄)
자연어 부동산 검색	문장을 입력하면 일치하는 목록을 받습니다.	요청은 쿼리 분석기에 의해 파싱되어 단순 벡터 검색(ChromaDB)이 필요한지, 더 복잡한 RAG/에이전트 흐름이 필요한지 결정합니다.
AI 기반 채팅 어시스턴트	목록, 동네 등에 대한 후속 질문을 위한 대화형 UI.	백엔드는 대화를 선택된 LLM 제공업체로 라우팅합니다. 장애 조치 체인은 한 제공업체가 다운되어도 응답을 보장합니다.
가치 평가 및 가격 예측 (v5.1)	부동산 ID(또는 수동 기능) 입력 → 현재 가치 + 1, 3, 5, 10년 예측과 신뢰 구간.	특수 LLM 프롬프트가 부동산 속성을 평가 모델에 공급합니다. 결과는 UI용 JSON 페이로드로 반환됩니다.
동네 한 줄 요약 (v5.1)	해당 지역의 특성, 생활 방식, 교통 연결에 대한 2~3문장 AI 요약.	동일한 LLM 라우팅이지만, 벡터 저장소의 동네 문서에서 가져오는 간결한 프롬프트를 사용합니다.
재무 계산기	모기지, 월세 vs 구매, ROI, 총 소유 비용, CMA 보고서.	순수 Python 계산. UI는 목록과 함께 결과를 표시합니다.
대화형 지도	클러스터형 부동산 마커, 지역 분석, 도시 개요 지도.	프론트엔드는 Mapbox/Leaflet을 사용하고, 백엔드는 DB에서 GeoJSON을 제공합니다.
다중 제공업체 LLM 라우팅	16개 제공업체(OpenAI, Anthropic, Google, Grok, DeepSeek, OpenRouter, Together AI, Fireworks AI, HuggingFace, Groq, Mistral, Qwen, ZAI, Moonshot, OpenCode, 로컬 Ollama).	`apps/api/models/provider_factory.py`가 장애 조치 체인을 구축합니다. 요청별 제공업체는 헤더/파라미터로 강제할 수 있습니다.
9개 언어 현지화	영어, 폴란드어, 러시아어, 독일어, 스페인어, 이탈리아어, 포르투갈어, 터키어, 우크라이나어로 UI 및 AI 출력 제공.	로케일 파일은 Next.js 앱과 함께 제공됩니다. AI 프롬프트에는 EU AI 법을 준수하는 언어 태그가 포함됩니다.
엔터프라이즈급 보안	속도 제한, 감사 로그, SSRF 보호, API 키 + JWT 인증, CI 보안 스캔.	FastAPI 미들웨어 및 GitHub Actions 강화 단계에서 구현됩니다.
데모 모드	API 키 없이 라이브 데모(render.com)가 작동합니다 – AI 응답은 즉시 탐색을 위해 시뮬레이션됩니다.	구성의 플래그가 제공업체 팩토리를 미리 생성된 답변을 반환하는 목 제공업체로 전환합니다.

🏗️ 아키텍처 스냅샷

Next.js 프론트엔드  <--->  API 프록시  <--->  FastAPI 백엔드
                                   │
                                   ├─ 쿼리 분석기 → RAG 엔진(ChromaDB) 또는 하이브리드 에이전트
                                   ├─ 도구(LangChain 래퍼)
                                   └─ LLM 제공업체(16개 옵션)

데이터베이스: 관계형 데이터용 PostgreSQL/SQLite
벡터 저장소: 의미 임베딩 + MMR 재정렬용 ChromaDB

README의 다이어그램(Mermaid)은 동일한 흐름을 보여줍니다. UI가 API 프록시를 호출해 FastAPI로 전달하고, FastAPI는 단순 RAG 파이프라인을 사용할지 더 복잡한 에이전트-도구 체인을 사용할지 결정합니다.

🚀 시작하기 (빠른 시작)

클론 및 Docker 시작 (Windows PowerShell 권장)

git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
cd ai-real-estate-assistant
.\start-docker.ps1   # DB, 벡터 저장소, API 및 웹 컨테이너 시작

프론트엔드: http://localhost:3082 백엔드: http://localhost:8082/docs

또는 수동 실행 백엔드 – 가상 환경 생성, uv pip install -e "[dev]", 그런 다음 uvicorn api.main:app --reload. 프론트엔드 – apps/web 안에서 npm install && npm run dev.
데모 모드 – LLM API 키가 필요 없습니다. 앱은 미리 생성된 답변을 반환하는 목 제공업체를 사용합니다. 프로덕션의 경우 .env 파일에 제공업체 키를 설정하세요(deploy/compose/.env.example 참조).

📚 문서 및 리소스

영역	참고 위치
아키텍처 세부 사항	`docs/architecture/large-saas-overview.md`
로컬 데모 설정	`scripts/demo/README.md` (Docker 시작, 데이터 생성, 종료용 PowerShell 스크립트)
API 참조	Swagger UI at `http://localhost:8082/docs` (FastAPI 자동 문서)
프론트엔드 컴포넌트	`apps/web/src/components/` – 예: 온보딩 투어, 검색 바, 지도 위젯
릴리스 노트	`CHANGELOG.md` – 최신 v5.1은 가치 평가, 인라인 결제, 동네 한 줄 요약 추가
로드맵	`docs/roadmap.md` (실시간 MLS 피드, AI-CRM, 멀티 에이전트 OS 같은 향후 기능)

🛠️ 기술 스택 (나열된 대로)

백엔드 – FastAPI(Python 3.12+), Pydantic, SQLAlchemy, uvicorn
프론트엔드 – Next.js 16, React 19, TypeScript 5.x, Tailwind(UI에서 추정)
벡터 DB – ChromaDB(의미 검색 + Max-Marginal-Relevance 재정렬)
관계형 DB – PostgreSQL(기본) 및 빠른 데모용 SQLite 폴백
LLM 제공업체 – 16개 주요 상용 API + 로컬 Ollama; 라우팅은 사용자 지정 팩토리로 처리
컨테이너화 – Docker 및 Docker-Compose; 공개 데모에 Render 무료 티어 사용
CI/CD – GitHub Actions(단위 테스트, 보안 스캔, Docker 이미지 빌드, Render 배포)
모니터링 – Uptime Kuma 및 구조화된 로그

📈 프로젝트 상태

Stars / forks – GitHub 배지에 표시됩니다. 저장소는 작지만 활동적인 커뮤니티(7명의 기여자, >1k 커밋)를 보유하고 있습니다.
테스트 – CI에서 >7,000개 테스트(백엔드 + 프론트엔드) 실행; README는 전체 테스트 스위트를 언급합니다.
릴리스 주기 – 빈번한 패치 릴리스(예: 2026년 9월 CVE 수정) 및 기능 릴리스(v5.1).
메모리 최적화 – Render의 512 MiB 무료 티어에서 배포 시 지연 제공업체 로딩; 그 외 VPS/Docker에서는 즉시 로딩.

🎯 누가 사용할까?

개발자: 자체 호스팅하거나 확장할 수 있는 스타터 SaaS 스타일 AI 강화 부동산 플랫폼을 원하는 개발자.
제품 팀: 다중 제공업체 LLM 라우팅, 하이브리드 RAG/에이전트 파이프라인, 다국어 AI 출력의 참조 구현을 찾는 제품 팀.
연구자: 실제 부동산 데이터셋에서 LLM 기반 가치 평가 또는 동네 설명 프롬프트를 평가하는 데 관심이 있는 연구자.

📌 결론

ai-real-estate-assistant는 부동산 목록을 위한 자연어 검색, 대화형 어시스턴트, 재무 분석을 결합한 진정한 풀스택 AI 애플리케이션입니다. 그 아키텍처, 다중 제공업체 라우팅, 데모 준비 배포는 현대 LLM 강화 SaaS의 훌륭한 예이며, 저장소에는 로컬 실행 또는 프로덕션급 인스턴스 구동에 필요한 모든 것이 포함되어 있습니다.

AleksNeStu/ai-real-estate-assistant