YTP 城市智慧助理 (AI City Assistant)

整合 RAG 知識庫、AI Agent 工具調用與 TDX 交通即時資料的前後端分離專案，提供完整的 SSE 流式輸出與地理資訊可視化。本專題旨在運用大語言模型與智慧化演算法，深入挖掘在地隱藏地點，打造最具溫度的個人化隨身城市導遊。

功能特色

• 現代化前端：HTML5 + Tailwind CSS + 原生 JS（單文件設計，無須打包編譯）。
• SSE 流式對話：支援 Server-Sent Events 打字機效果與 AI 生成串流推薦理由。
• RAG 架構與來源引用：即時顯示 AI 回答參考的文獻與可靠度。
• Agent 工具調用可視化：清楚展示 AI 調用哪些 API（TDX、天氣、YouBike 等）與耗時。
• Leaflet 地圖整合：自動偵測對話中的 POI (Points of Interest) 並標記在地圖上。
• 真實 AI API 串接：抽象層 ai_provider.py 統一支援 Anthropic Claude（含 prompt caching）、OpenAI、Gemini、及 demo 模式。
• 真實爬蟲模組：scraper.py 提供三種可插拔資料源 — OpenStreetMap Overpass（免金鑰）、Google Places API、通用 BeautifulSoup HTML 擷取器。
• 向量資料庫：vector_store.py 純 Python 實作（numpy + JSON 持久化）— 有 OPENAI_API_KEY 自動切換 text-embedding-3-small；否則使用本地 char-ngram hashing embedder，無需 Native build dependency。
• 啟動自動 Seed：首次啟動若向量庫為空，自動從 OSM Overpass 抓取台北 60+ POI，demo 立即可用。
• 動態評分補償模型：根據即時天氣、時間與人潮給出地點評分輔助（如下雨天自動提升室內標籤權重）。
• 隱藏小店推論引擎：對數降權演算法挖掘低評價數但高分的巷弄店鋪。
• 語意 + 動態雙層推薦：向量檢索取候選 → 動態評分重排，兼顧語意相關性與情境適配度。

系統需求

• 作業系統: Windows / macOS / Linux
• Python: v3.10 或以上版本
• 瀏覽器: 建議使用最新版 Chrome、Edge 或 Safari
• (選用): OpenAI API Key 或 Google Gemini API Key (用於真實推論模式，專案內附 Demo 模式可免金鑰測試)

安裝教學

1. 取得專案

git clone https://github.com/orange0730/ytp-hackDemo.git
cd ytp-hackDemo

2. 環境變數設定

後端使用 .env 檔案管理配置，請先複製範例檔：

cp .env.example .env

打開 .env 檔案設定你要使用的 AI 引擎 AI_PROVIDER：

• demo：（預設）不需任何 API Key，使用模擬資料展示完整運作邏輯。
• anthropic：需填入 ANTHROPIC_API_KEY（推薦，支援 prompt caching 降本）。
• openai：需填入 OPENAI_API_KEY（同時作為向量嵌入預設來源）。
• gemini：需填入 GEMINI_API_KEY。

向量資料庫會持久化到 CHROMA_PERSIST_DIR（預設 ./vector_store_data）。 若 AUTO_SEED_ON_STARTUP=true 且資料庫為空，首次啟動會自動從 OSM 抓取 Seed 資料。

3. 配置後端伺服器 (FastAPI)

cd backend

# (建議) 建立虛擬環境
python -m venv venv

# 啟動虛擬環境 (Windows)
venv\Scripts\activate
# 啟動虛擬環境 (Mac/Linux) 
# source venv/bin/activate

# 安裝所需套件
pip install -r requirements.txt

# 啟動伺服器
python main.py

伺服器將在 http://localhost:8000 運行。開發者 API 文件可至 http://localhost:8000/docs 查看。

4. 開啟前端介面

前端為純靜態檔案，直接在瀏覽器開啟專案根目錄下的 index.html 即可。

# macOS
open index.html

# Windows
start index.html

註：若你修改了 FastAPI 的預設執行埠號，請同步開啟 index.html 修改裡面的 API_BASE 變數網址。

---

API 速查

Method	Path	說明
POST	/api/chat/stream	SSE 串流對話（recommendation 場景走向量檢索 + 動態排序）
POST	/api/chat	非串流對話
POST	/api/knowledge/search	真實向量語意檢索（接 ChromaDB-like store）
POST	/api/ingest/scrape	觸發爬蟲 + LLM 結構化 + 寫入向量庫
POST	/api/recommend/hidden	動態評分推薦 Top N
GET	/api/stats	查看 AI provider、向量庫筆數、嵌入模型
GET	/api/tools/available	可用工具清單

爬蟲範例

# 從 OSM 匯入台北咖啡廳 / 餐廳 / 公園（免金鑰）
curl -X POST http://localhost:8000/api/ingest/scrape \
     -H "Content-Type: application/json" \
     -d '{"source":"osm","city":"Taipei","limit":50}'

# 用 Google Places（需 GOOGLE_MAPS_API_KEY）
curl -X POST http://localhost:8000/api/ingest/scrape \
     -d '{"source":"google","query":"台北 隱藏 咖啡"}'

# 單篇部落格文章
curl -X POST http://localhost:8000/api/ingest/scrape \
     -d '{"source":"html_article","url":"https://example.com/hidden-cafes"}'

向量檢索範例

curl -X POST http://localhost:8000/api/knowledge/search \
     -H "Content-Type: application/json" \
     -d '{"query":"下雨天想找安靜看書的地方","top_k":5}'

---

架構

backend/
├── main.py                # FastAPI 入口 + SSE 路由 + 啟動 seed
├── ai_provider.py         # Anthropic / OpenAI / Gemini / demo 抽象
├── vector_store.py        # numpy + JSON 持久化向量庫
├── scraper.py             # OSM Overpass / Google Places / BS4
├── ingestion_pipeline.py  # raw → LLM 結構化 → hidden_index → 向量庫
├── recommendation.py      # 語意檢索 + 動態排序 + LLM 串流
├── inference.py           # SpotInferenceEngine（動態評分）
└── dynamic_scoring.py     # 天氣/人潮/時間補償模型

供 YTP (Young Turing Program) 黑客松 展示與參考之用。