租房推荐智能体 — 项目开发全景报告

项目阶段：全栈联调与 AI Agent 接入

一、 项目概览：架构与管线

在今天的项目汇合中，我们成功将后端爬虫、地理信息服务与 AI Agent 进行了整合。本系统旨在解决多源房产数据孤岛问题，通过“数据采集 → 标准化 → 地理富化 → 智能评分 → AI 交互”的闭环，为用户提供科学的租房决策支持。

系统架构图解：

[TypeScript CLI Agent] 
         ↓ (HTTP API)
[FastAPI 后端]
   ├── [Crawler Module] → 三平台竞速 + 代理池
   ├── [Map Service]    → 高德地理编码 + 步行规划
   └── [Scoring Engine] → 6维加权评分

二、 核心模块深度解析

1. 爬虫模块：三端竞速与反爬体系
这是系统的“眼睛”，负责实时获取链家、安居客、房天下的原始数据。

竞速机制：
不再是简单的并发，而是“赛跑”。三平台请求同时发出，一旦有任意一方返回有效数据，立即取消其余两个平台的请求，极大降低了响应延迟，保证了数据的新鲜度。

代理 IP 池：

动态维护：基于“巨量IP”API，实现了 TTL（生存时间）自动清理和库存不足自动补货。

认证方式：采用 Proxy-Authorization Header 进行 Base64 认证，区别于传统的 URL 传参，安全性更高。

高可用策略：当代理池失效时，系统会自动降级为直连模式，确保核心业务不中断。

数据持久化与兜底：利用 SQLite 进行本地缓存，通过 (house_id, source) 联合主键防止重复入库。

智能兜底：若实时爬取失败，系统会自动在数据库中搜索 3 天内的历史数据作为替补，保证用户体验不降级。

2. 评分引擎：6维加权评分模型
这是系统的“大脑”，将冷冰冰的数据转化为可比较的分数。

我们设计了一套可配置的加权评分体系，默认权重分配如下表所示：

评分维度	权重	计算逻辑
通勤	30%	基于高德地图步行规划，距离地铁站越近得分越高（阶梯式衰减）。
价格	25%	高斯分布匹配，完美契合用户预算区间得分最高，超预算线性惩罚。
配套	20%	周边 3km 内 POI（超市/医院/商场）数量加权统计。
户型	15%	匹配房间数、厅室结构及租住类型（整租/合租）。
朝向/楼层	7%	南北通透、高层视野加分；暗卫、底层减分。
装修	3%	基于 Jaccard 相似度，比对用户偏好标签（如“精装”、“独卫”）。

注：所有维度得分归一化处理，最终得分 = Σ(维度得分 × 权重)。

3. 地图服务：地理数据富化
这是系统的“尺子”，负责将文本地址转化为空间数据。

高德 API 深度集成：实现了地理编码（Geocoding）与逆地理编码。

步行路径规划：不仅仅是直线距离，而是真实的步行时间和步行距离。这直接决定了“通勤分”的准确性。

QPS 保护：为了防止触发高德 API 的频率限制（30次/秒），在批量处理房源时加入了 150ms 的间隔延时，体现了良好的工程素养。

三、 AI Agent 智能交互层

今天的重点在于接入了 TypeScript CLI 智能体，实现了自然语言交互。

• 技术栈：LangChain + OpenAI + ReAct 模式。
• 工作流：
  1. 记忆层：拥有会话级记忆（ConversationMemory）和持久化偏好记忆（PreferenceMemoryStore），记住用户的历史选择。
  2. 推理层：通过 AGENT_MAX_ITERATIONS 限制防止死循环，利用 Zod 进行严格的 Schema 校验。
  3. 执行层：Agent 将用户意图解析后，通过 HTTP 调用 Python 后端的 /scoring/recommend 一站式接口，获取处理结果并反馈给用户。

四、 环境部署与接口清单

运行环境

• 后端：Python 3.12+
• 前端/Agent：TypeScript (Node.js)
• 关键配置：
  • Windows 用户需设置 PYTHONIOENCODING=utf-8 防止乱码。
  • 必须在 api/.env 中配置 AMAP_API_KEY 和 OPENAI_API_KEY。

核心 API 端表格

模块	路径	功能描述
Crawler	POST /crawler/search	三平台并发竞速爬取房源
Crawler	GET /crawler/status	查看爬虫运行状态
Map	POST /map/analyze	分析单个地址的坐标与周边 POI
Map	POST /map/enrich	批量为房源添加地图数据（步行时间等）
Scoring	POST /scoring/score	对已富化的房源进行打分排序
Scoring	POST /scoring/recommend	核心接口：一键完成从搜索到推荐的全流程

五、 展示与总结与展望

今天的汇合标志着项目从“单点功能开发”进入了“系统集成测试”阶段。AI Agent 的接入使得复杂的租房决策变得极其简单——用户只需说出需求，系统便能自动完成数据获取、清洗、评分和推荐。

优化 Agent 提示词：提高 ReAct 模式下工具调用的准确率。

前端联调：将 CLI 的能力移植到 Web 前端界面。

评分权重微调：收集真实用户反馈，动态调整 6 个维度的权重系数，使推荐结果更符合人类直觉。