kanakmohanj/astram-backend

# 🚦 ASTRAM：AI 驱动的交通编排引擎 **ASTRAM**（Automated System for Traffic Response and Management）是一个企业级的 agentic AI 后端，旨在预测、管理和编排对实时交通事故的响应。 ASTRAM 专为 Flipkart Hackathon 打造，超越了基础的 CRUD 应用程序，它将确定性的 Machine Learning 预测与 Generative AI 和持续学习 (RAG) 相结合。它为现场交通执法人员动态起草高度结合情境的战术计划，创建了一个从过往成功操作中不断学习的闭环系统。 ## 📖 执行摘要与核心 Pipeline 该后端基于 **FastAPI** 构建，以确保高并发异步处理。核心编排由 **LangGraph** 驱动，它通过多 agent pipeline 路由事故： 1. **⚡ 实时摄取：** 安全的 REST endpoint 和 WebSockets，能够摄取来自 IoT 摄像头或人工报告的高频事故数据。 2. **📈 预测性 ML 引擎：** 直接加载到 RAM 中的 XGBoost 回归器会评估 13 个时空特征（例如，高峰时段、周末、优先级得分），以即时预测事故清理持续时间。 3. **⚙️ 基于规则的资源分配：** 确定性算法根据 ML 影响得分计算精确的物理资源需求（警察、拖车、路障）。 4. **🧠 持续学习记忆 (RAG)：** 利用本地 FAISS Vector Database 存储获得 4/5 或 5/5 成功率的历史事故。它使用 `all-mpnet-base-v2` embeddings 执行语义相似性搜索，赋予 AI 对过往操作的“记忆”。 5. **🤖 LLM 战术综合：** Google Gemini 1.5 Pro 摄取 ML 预测、资源逻辑和历史 RAG 上下文，为调度员起草自然语言的可执行简报。 ## 🛠️ 技术栈 - **框架：** FastAPI, Uvicorn - **AI 编排：** LangGraph, LangChain - **Generative AI：** Google Gemini 1.5 Pro - **Machine Learning：** XGBoost, Pandas - **Vector Database：** FAISS (Facebook AI Similarity Search) - **Embeddings：** HuggingFace (`all-mpnet-base-v2`) ## 🏗️ 工程挑战与架构成就 在开发过程中，我们将系统设计为对现实世界的部署挑战具有高度弹性： - **挑战 1：HuggingFace API 限流与超时** - _问题：_ RAG pipeline 最初试图在每次请求时 ping HuggingFace API 以验证 embedding 模型版本，导致超过 15 秒的超时。 - _解决方案：_ 通过将 438MB 的 `all-mpnet-base-v2` 模型直接缓存到服务器环境中并强制设置 `HF_HUB_OFFLINE="1"` 变量，我们迁移到了 **100% 离线本地 Embeddings**。 - _结果：_ 零延迟文本 embedding 操作。系统不再依赖外部 API 的正常运行时间。 - **挑战 2：企业网络对云数据库的封锁** - _问题：_ 严格的机构防火墙主动阻止了到云端 vector database 的出站连接，导致 LangGraph pipeline 完全崩溃。 - _解决方案：_ 我们实施了 **100% 本地 Vector Database (FAISS)**，并将连接包装在优雅降级块中。如果发生网络断开，AI 会捕获错误，绕过 RAG 步骤，并成功生成基线战术计划而不会崩溃。 - _结果：_ 即使在高度受限或不稳定的网络环境中，也能保证核心 AI 编排器 100% 的正常运行时间。 - **挑战 3：不可预测的 LLM JSON 输出** - _问题：_ 生成式模型偶尔会返回非结构化数据，导致前端在重新渲染期间崩溃。 - _解决方案：_ 在 FastAPI 中标准化 Pydantic schema，以便在数据离开后端之前强制执行严格的输出验证。 ## 🚀 本地设置与安装 按照以下步骤在本地运行 ASTRAM 后端。 ### 前置条件 - Python 3.10 或更高版本 - Git ### 步骤 1：克隆仓库 ``` git clone [https://github.com/YOUR_USERNAME/astram-backend.git](https://github.com/YOUR_USERNAME/astram-backend.git) cd astram-backend ``` ### 步骤 2：创建虚拟环境 # Windows python -m venv .venv .venv\Scripts\activate # Mac/Linux python3 -m venv .venv source .venv/bin/activate ### 步骤 3：安装依赖项 pip install fastapi uvicorn xgboost pandas langchain langgraph google-generativeai faiss-cpu langchain-community langchain-huggingface sentence-transformers ### 步骤 4：配置环境变量 在项目的根目录下创建一个名为 .env 的文件，并添加以下内容： # 从此处获取：[https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) GEMINI_API_KEY="your-gemini-api-key-here" # 当前环境状态 ENVIRONMENT="development" # 关键：强制 HuggingFace 使用本地缓存。防止超时错误。 HF_HUB_OFFLINE="1" ### 步骤 5：运行服务器 uvicorn app.main:app --reload 后端将启动，把 ML 模型加载到 RAM 中，并在 http://127.0.0.1:8000 暴露 API。 ### 📡 API Endpoint 概述 在以下地址查看交互式 API 文档：👉 http://127.0.0.1:8000/docs POST /api/v1/events/ingest - 从外部设备或 UI 摄取新的交通事故。 POST /api/v1/events/{event_id}/orchestrate - 触发 LangGraph AI pipeline。 POST /api/v1/events/feedback - 提交 1-5 星评分以训练 RAG 记忆。 WS /ws/dashboard - 用于实时前端更新的实时 WebSocket 数据流。 ### 🔮 未来路线图 交互式地理空间指挥中心：将 Leaflet.js 集成到 React 仪表板中，以根据 WebSocket 坐标在地图上标记实时事故。 全渠道摄取：扩展 /ingest webhook 以接收来自 Google Maps/Waze 交通 API 的自动警报。 自动化云同步：实施 cron 作业，将本地 FAISS 数据库与集中式云端数据仓库同步，以实现跨城市学习。 专为 Flipkart Hackathon 打造 🚀

标签：AI智能体, Apex, AV绕过, FastAPI, RAG, 事件编排, 后端开发, 智能交通, 机器学习, 逆向工具