寫這個模擬國三高速公路車流即時交通網頁程式，本來是要參加一個比賽的，但發現主辦單位還要求參加者要用紙本方式郵寄，這世代居然還有不是全然用網站上傳的方式的AI類比賽，最後讓我打了退堂鼓。
網頁程式畫面如下:
主要程式發想如下:
智慧交通模擬系統 程式碼說明
這份文件詳細說明了 檔案的架構、功能與核心邏輯。此程式碼使用 Python 的 FastAPI 框架，建構一個功能豐富的後端服務，用於模擬一個基於多智能體強化學習 (MARL) 的國道動態路徑推薦系統。
一、 系統概覽 📜
本系統旨在模擬一個真實且複雜的交通環境，並在其中運行一個 MARL 路徑推薦模型，以達成兼顧「單車效益」與「路網總體效率」的目標。
核心功能包括：
- 真實路網建模： 基於真實的國道三號交流道位置與路段資訊，建構一個詳細的交通網絡圖。
- 多樣化車輛模擬： 模擬不同類型的車輛（私家車、貨車、公車、緊急車輛），每種車輛具有不同的行為模式與優先級。
- 複雜交通情境： 能夠模擬多種真實世界的交通事件，如主線事故、連鎖反應、道路施工、尖峰時段、惡劣天氣、大型活動等。
- MARL 推薦核心： 內建一個以 Q-Learning 為基礎的 MARL 推薦器，智能體（車輛）能夠在模擬中學習與演化其路徑選擇策略。
- 智能體協調機制： 包含多種協調策略（如拍賣、共識），以解決多智能體之間的潛在衝突。
- 動態 API 服務： 提供多個 API 端點，允許前端（如
index.html）即時獲取交通狀態、觸發事件、重置模擬等，實現動態視覺化。
二、 程式碼架構解析 🏗️
程式碼主要由以下幾個部分組成：
1. FastAPI 應用程式設置
- 使用
FastAPI()創建主應用實例。 - 透過
CORSMiddleware設置跨域資源共享 (CORS)，允許來自任何來源（origins = ["*"]）的前端頁面訪問後端 API，這對於開發階段非常重要。 - 設置一個靜態文件根目錄，使 FastAPI 可以直接提供
index.html。
2. 國道路網定義 (NODE_COORDS, SEGMENT_DEFINITIONS)
這是系統模擬的基礎，定義了交通網絡的物理屬性。
NODE_COORDS(節點座標):- 一個字典 (Dictionary)，儲存了國道三號沿線所有交流道、系統交流道、服務區的真實地理座標（緯度、經度）。
- 同時也包含了部分替代道路、省道與國道一號的重要節點，用於模擬跨路網的交通行為。
SEGMENT_DEFINITIONS(路段定義):- 一個字典，定義了連接各節點的路段。
- 每個路段包含其 起始節點、結束節點、長度(km)、速限(km/h)、車道數 等關鍵資訊。
- 涵蓋了國道三號主線、系統交流道連接段以及替代道路，構建了一個龐大且複雜的路網圖。
3. 車輛與事件定義 (VEHICLE_POOL, event_queue)
VEHICLE_POOL(車輛池):- 一個列表 (List)，預先定義了多種類型的車輛，用於在模擬開始時初始化交通流。
- 每輛車包含 ID、起點、終點、車輛類型 (private, truck, bus, emergency) 和 優先級。
- 車輛類型涵蓋了長途、中途、區域、短途以及緊急車輛，使模擬更具真實性。
event_queue(事件佇列):- 一個列表，用於儲存所有預定發生的交通事件。
- 透過 add_event() 函數將事件（如事故、施工）安排在特定的模擬時間步 (time_step) 發生。系統會在每個時間步檢查並觸發相應事件。
4. 多智能體強化學習核心 (MARLPathRecommender, QLearningAgent)
這是系統的智慧大腦 🧠，負責決策與學習。
QLearningAgentClass:- 定義了單一智能體（車輛）的行為。
- 使用 Q-Learning 演算法，每個智能體維護一個 Q-Table，記錄在特定狀態 (state)下採取特定動作 (action) 的預期回報。
- 採用 ε-貪婪 (epsilon-greedy) 策略在「探索」（隨機選擇）和「利用」（選擇 Q 值最高的動作）之間進行權衡。
- update_q_value() 函數根據獎勵 (reward) 和貝爾曼方程 (Bellman equation) 來更新 Q-Table，實現學習。
MARLPathRecommenderClass:- 這是管理所有智能體的中央協調器。
- get_or_create_agent(): 為新加入的車輛創建對應的 QLearningAgent 實例。
- calculate_reward(): 核心獎勵函數。獎勵的計算綜合考慮了多種因素：旅行時間：時間越長，獎勵越低。路段狀態：選擇暢通路段（green）有高獎勵，選擇壅塞路段（red）會受懲罰。路段利用率：避免選擇已過度擁擠的路段。協調獎勵：鼓勵智能體們做出差異化選擇，避免扎堆。
- predict_congestion(): 一個簡單的擁塞預測模型，基於歷史數據預測未來路段的擁塞可能性。
- coordinate_agents(): 智能體協調機制。提供多種策略（如基於出價的拍賣或避免衝突的共識），解決多個智能體同時請求路徑時的資源分配問題。
- recommend_path(): 根據車輛類型（普通或緊急）、當前路況和 Q-Learning 策略，為車輛推薦最佳路徑。
5. 模擬循環與狀態更新 (simulate_traffic_update)
這是模擬系統的心跳 ❤️，每個時間步都會執行一次，推動整個世界的演進。
- 處理事件 (
process_events): 檢查event_queue，觸發當前時間步需要發生的所有事件。 - 更新路段狀態: 根據路段利用率、時間因素（尖峰/離峰）、天氣因素等多重因子，動態計算每個路段的
current_speed和status(green,yellow,red)。 - 智能體協調與學習:
- 為每個需要重新規劃路徑的智能體收集資訊。
- 調用 coordinate_agents 進行協調。
- 調用 update_learning 更新每個智能體的 Q-Table。
- 車輛移動:
- 根據路段的有效速度 (effective_speed) 和車輛類型，計算車輛在一個時間步內移動的距離。
- 更新車輛在路段上的進度 (progress_on_segment) 和地理座標 (lat, lon)。
- 當車輛到達路段終點時，將其移動到推薦路徑的下一個路段。
- 當車輛到達最終目的地時，將其從模擬中移除。
- 生成新需求: 以一定機率隨機生成新的車輛，使交通流持續不斷。
- 更新系統指標: 匯總計算整個路網的平均速度、總旅行時間等宏觀指標。
6. API 端點 (Endpoints)
系統提供了一系列 RESTful API，供前端調用。
GET /: 回傳index.html頁面。GET /traffic_update: 核心接口，回傳當前模擬時間步的所有交通狀態數據 (路段、車輛、事件、指標)。GET /marl_stats: 提供 MARL 模型的學習統計數據。POST /trigger_event: 允許前端手動觸發一個自定義交通事件。POST /reset_simulation: 重置整個模擬到初始狀態。POST /clear_events: 清除所有待處理的事件。POST /retrain_agents: 重置所有智能體的學習進度，用於重新訓練。GET /simulation_status: 獲取模擬器的簡要狀態。
7. 啟動事件 (startup_event)
- 在 FastAPI 服務啟動時，會自動執行此函數。
- 這裡預設了一系列複雜的、環環相扣的交通情境，例如：
- 主線事故與連鎖二次事故。
- 道路施工與尖峰時段疊加。
- 緊急車輛通行測試。
- 惡劣天氣事件。
- 大型活動散場模擬。
- 動態改變 MARL 協調機制。
- 系統壓力測試。
這使得模擬一開始就充滿了各種挑戰，能充分展示系統的動態應變與學習能力。
三、 如何運行與使用 ▶️
- 安裝依賴:
pip install fastapi uvicorn "python-multipart[standard]" numpy
- 啟動後端服務: 在終端機中，於
app.py檔案所在的目錄下執行以下命令：uvicorn app:app --reload
服務將啟動於http://localhost:8000。 - 訪問前端頁面: 在瀏覽器中打開
http://localhost:8000，即可看到視覺化模擬界面。前端頁面（index.html）會定期調用/traffic_updateAPI 來獲取數據並更新畫面。
