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

AI 房地产助手 – 概述

它是什么 – 一个开源的、AI 驱动的 Web 应用，允许用户搜索房屋、与虚拟助手聊天并运行财务分析工具——全部通过输入自然语言查询，如 “克拉科夫 50 万以下的 2 居室公寓”。核心产品是一个 FastAPI 后端（Python 3.12+），可连接多达 16 家 LLM 提供商、一个用于语义搜索的 ChromaDB 向量存储以及一个用于房产目录的 PostgreSQL/SQLite 数据库。Next.js 16 + React 19 前端提供 UI、地图和分析仪表板。

📦 核心功能（如 README 中所述）

功能	你获得什么	工作原理（高层）
自然语言房产搜索	输入一句话，接收匹配列表。	请求由查询分析器解析，它决定是简单的向量搜索（ChromaDB）还是更复杂的 RAG/代理流程。
AI 驱动的聊天助手	用于询问关于列表、社区等后续问题的对话式 UI。	后端将对话路由到选定的 LLM 提供商；回退链保证即使一个提供商宕机也能响应。
估值与价格预测（v5.1）	输入房产 ID（或手动特征）→ 当前价值 + 1、3、5、10 年预测及置信区间。	专门的 LLM 提示将房产属性输入估值模型；结果以 JSON 载荷返回给 UI。
社区一句话描述（v5.1）	对地区特色、生活方式和交通连接的 2-3 句 AI 摘要。	相同的 LLM 路由，但使用简洁提示，从向量存储的社区文档中提取。
财务计算器	抵押贷款、租购比较、投资回报率、总拥有成本、CMA 报告。	纯 Python 计算；UI 在列表旁边显示结果。
交互式地图	聚类房产标记、区域分析、城市概览地图。	前端使用 Mapbox/Leaflet；后端从数据库提供 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 提示包含语言标签，以符合欧盟 AI 法案。
企业级安全	速率限制、审计日志、SSRF 保护、API 密钥 + JWT 认证、CI 安全扫描。	在 FastAPI 中间件和 GitHub Actions 加固步骤中实现。
演示模式	实时演示（render.com）无需任何 API 密钥即可工作——AI 响应被模拟以便即时探索。	配置中的标志将提供商工厂切换到返回预设答案的模拟提供商。

🏗️ 架构快照

Next.js 前端  <--->  API 代理  <--->  FastAPI 后端
                                   │
                                   ├─ 查询分析器 → RAG 引擎（ChromaDB）或混合代理
                                   ├─ 工具（LangChain 封装）
                                   └─ LLM 提供商（16 个选项）

数据库：PostgreSQL/SQLite 用于关系数据
向量存储：ChromaDB 用于语义嵌入 + MMR 重排序

README 中的图表（Mermaid）显示相同的流程，UI 调用 API 代理，代理转发到 FastAPI，然后决定使用简单的 RAG 管道还是更复杂的代理工具链。

🚀 快速入门（快速开始）

克隆并启动 Docker（推荐使用 Windows PowerShell）

git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
cd ai-real-estate-assistant
.\start-docker.ps1   # 启动数据库、向量存储、API 和 Web 容器

前端：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 位于 `http://localhost:8082/docs`（FastAPI 自动文档）
前端组件	`apps/web/src/components/` – 例如，引导教程、搜索栏、地图小组件
发布说明	`CHANGELOG.md` – 最新 v5.1 添加了估值、内联支付、社区一句话描述
路线图	`docs/roadmap.md`（未来功能，如实时 MLS 提要、AI-CRM、多代理操作系统）

🛠️ 技术栈（如所列）

后端 – FastAPI（Python 3.12+）、Pydantic、SQLAlchemy、uvicorn
前端 – Next.js 16、React 19、TypeScript 5.x、Tailwind（根据 UI 推断）
向量数据库 – ChromaDB（语义搜索 + 最大边际相关性重排序）
关系数据库 – PostgreSQL（默认），SQLite 作为快速演示的回退
LLM 提供商 – 16 家主要商业 API + 本地 Ollama；路由由自定义工厂处理
容器化 – Docker 和 Docker-Compose；Render 免费层用于公共演示
CI/CD – GitHub Actions（单元测试、安全扫描、Docker 镜像构建、Render 部署）
监控 – Uptime Kuma + 结构化日志

📈 项目健康

星标 / 分叉 – 在 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