satax-575/Disaster-Relief-System-GEMMA-4-

# RAKSHA AI AI 驱动的灾害智能系统 ## 概述 RAKSHA AI 是一个灾害响应平台，利用 Gemma 4 31B 为紧急救援人员在自然灾害和大规模伤亡事件中提供实时智能支持。该系统结合了多模态损害评估、AI 引导的医疗分诊以及自主事件协调功能，以在分秒必争的时刻为现场行动提供支持。 该平台部署在 Render 上，可通过以下地址访问：https://rakshak-frontend.onrender.com ## 核心功能 ### 多模态损害评估 该系统通过两阶段视觉 pipeline 分析灾害现场照片。HuggingFace BLIP (Salesforce/blip-image-captioning-large) 生成详细的图像描述，将视觉数据转换为结构化的文本描述。然后，这个中间文本表示会由 Gemma 4 31B 进行处理，后者执行语义分析以提取 1-10 级别的损害严重程度评分，识别结构危险，估计被困人员，评估结构完整性状态，并生成包括团队数量和设备需求在内的具体资源需求。 这种架构允许 Gemma 4 将其卓越的推理能力应用于视觉任务，而无需原生的多模态支持。视觉 pipeline 包括备用提供商：当主要服务出现性能下降时，Groq Llama 4 Scout (meta-llama/llama-4-scout-17b-16e-instruct) 和 Mistral Pixtral (pixtral-large-2411) 可确保持续运行。 ### AI 引导的医疗分诊 该平台通过由 Gemma 4 31B 提供支持的对话式 AI 实施 START 协议大规模伤亡分诊。现场救援人员输入患者症状、生命体征、年龄估计和可观察的状况。模型分析这些临床数据，根据 START 协议分配分诊颜色：红色代表危及生命的紧急情况，黄色代表紧急但状况稳定，绿色代表轻微受伤，黑色代表濒死或已死亡。 除了颜色分类外，Gemma 4 还提供鉴别诊断、具体的即时干预措施、用于稳定病情的生命体征目标、用药考虑、转运优先级建议、带有临床推理的休克评估以及监测间隔指导。这使受过最少培训的志愿者能够利用专家级的临床推理做出符合协议的分诊决策。 ### 自主事件协调 一个后台监控代理会持续评估数据库中的活跃事件。当危急情况（严重程度 ≥5.0）在超过阈值时间后仍未被分配时，系统会利用 Gemma 4 的原生函数调用功能来自主执行协调行动。 该模型可以按角色和优先级派遣适当的救援团队，广播带有自动翻译的多语言紧急警报，记录符合 START 协议的医疗分诊条目，请求具有紧急程度级别的特定资源，生成疏散路线指导，并使用临床协议计算药物剂量。 这种自主协调消除了人工瓶颈，并确保对新兴威胁做出快速响应，而无需持续的人工监督。 ### 多语言支持 该平台原生支持 10 种以上的语言：英语、印地语、泰米尔语、泰卢固语、孟加拉语、马拉地语、阿拉伯语、斯瓦希里语、西班牙语和法语。所有 AI 响应、紧急警报和分诊指导都会自动适应用户的语言偏好。Gemma 4 负责处理翻译并保持跨语言的临床准确性。 ## 技术架构 ### 后端基础设施 后端基于 FastAPI 0.115.5 构建，这是一个现代 Python Web 框架，提供异步请求处理和自动 OpenAPI 文档生成功能。应用程序使用 uvicorn 0.32.1 作为 ASGI 服务器，支持 WebSocket 连接和 HTTP/2。 **数据库层**：带有预写式日志 (WAL) 模式的 SQLite 提供零延迟的本地持久性，并支持并发读取。aiosqlite 0.20.0 库支持非阻塞数据库操作。数据库 schema 包括用于事件、救援人员、分诊条目、警报、聊天会话的表，以及用于未来 mesh 网络功能的同步队列。 **数据验证**：Pydantic 2.10.3 负责处理请求/响应验证和序列化。所有 API 端点都使用强类型模型，包括 Incident、Responder、TriageEntry、Alert 和 ChatMessage，这些模型带有用于类型安全的基于枚举的状态字段。 **实时通信**：位于 /ws/dashboard 和 /ws/chat 的 WebSocket 端点为连接的客户端提供实时更新。ConnectionManager 类负责处理连接生命周期、广播和自动清理死连接。 **HTTP 客户端**：httpx 0.27.2 为所有对 Google AI、HuggingFace、Groq 和 Mistral 服务的外部 API 调用提供异步 HTTP 客户端功能。该库包括带有指数退避和连接池的自动重试逻辑。 **图像处理**：Pillow 11.0.0 负责处理视觉 pipeline 的图像验证、格式转换和 base64 编码/解码。 ### AI 模型集成 **主要模型**：Gemma 4 31B (gemma-4-31b-it) 通过位于 generativelanguage.googleapis.com/v1beta 的 Google Generative AI REST API 进行访问。该模型提供具有 8192 token 上下文窗口的文本生成、带有结构化参数 schema 的原生函数调用，以及通过基于文本的视觉分析的多模态功能。 **视觉 Pipeline**： - 通过 Inference API 使用 HuggingFace BLIP (Salesforce/blip-image-captioning-large) 进行图像到文本的转换 - Groq Llama 4 Scout (meta-llama/llama-4-scout-17b-16e-instruct) 作为视觉备选方案 - Mistral Pixtral (pixtral-large-2411) 作为次要视觉备选方案 **本地模型**：当云连接不可用时，Ollama 集成支持本地推理。系统会自动检测已安装的模型，优先顺序为：gemma4 > llama > mistral。通过 Ollama 位于 localhost:11434 的 REST API 进行通信。 **模型路由逻辑**：ModelSelector 类实现了具有 30 秒可用性缓存的智能提供商选择。它探测 Google AI API 以确认云端可用性，检查 Ollama /api/tags 端点以确认本地模型，并维护备用链以确保持续运行。 **函数调用**：Gemma 4 支持六个原生函数工具：dispatch_responder、broadcast_emergency_alert、get_evacuation_route、log_medical_triage、request_resources 和 calculate_dosage。每个函数都有一个定义所需参数和枚举约束的 JSON schema。GemmaClient 类自动执行被调用的函数，并将结果合并到响应中。 ### 前端实现 前端是一个使用原生 JavaScript（无框架依赖）构建的 Progressive Web App，旨在实现最大的兼容性和最小的打包体积。该应用程序使用带有客户端路由的单页架构。 **UI 组件**：使用纯 CSS 实现的自定义毛玻璃设计系统。界面包括响应式侧边栏导航、带有统计卡片的实时仪表板、使用 Leaflet.js 1.9.4 的交互式事件地图、用于数据输入的模态对话框以及用于用户反馈的 toast 通知。 **地图**：Leaflet.js 提供带有 OpenStreetMap 切片的交互式地理空间可视化。事件根据严重程度（红色代表危急，橙色代表高，黄色代表中等）渲染为颜色编码的标记。地图支持聚类、弹窗详细信息，并通过 WebSocket 实时更新标记。 **Service Worker**：使用 Cache API 实现离线资产缓存。Service Worker 拦截网络请求并在可用时提供缓存的响应，使 UI 即使在没有连接的情况下也能加载。缓存在版本更新时失效。 **WebSocket 客户端**：维护到 /ws/dashboard 的持久连接以获取实时事件更新，以及到 /ws/chat 的持久连接以获取流式 AI 响应。自动重连逻辑通过指数退避处理连接断开的情况。 **状态管理**：客户端状态通过原生 JavaScript 进行管理，并使用 localStorage 进行会话持久化。应用程序维护活跃事件列表、救援人员状态、警报历史和聊天会话数据。 ### 部署配置 应用程序使用 Docker 通过多阶段构建过程进行容器化。Dockerfile 使用 python:3.11-slim 作为基础镜像，安装系统依赖项 (sqlite3, libsqlite3-dev, curl)，复制后端要求并安装 Python 包，并公开端口 8000 以及健康检查配置。 **Docker Compose**：通过环境变量注入、用于数据库持久性的卷挂载、健康检查配置（30 秒间隔，10 秒超时，3 次重试）以及自动重启策略来编排后端服务。 **Render 部署**：应用程序部署在 Render 的免费套餐上，配置如下： - 运行时：Docker - 区域：Oregon (US West) - 实例类型：Free (512MB RAM, 0.1 CPU) - 健康检查：GET /health 端点 - 环境变量：GOOGLE_API_KEY, GEMMA_CLOUD_MODEL, HUGGINGFACE_TOKEN, GROQ_API_KEY, MISTRAL_API_KEY - 持久磁盘：1GB 挂载在 /data，用于 SQLite 数据库 - 自动部署：在 main 分支提交时启用 免费套餐包括在 15 分钟不活动后自动休眠，并在第一次请求时约有 30 秒的冷启动。健康检查端点确保 Render 正确检测服务可用性。 ### 安全实施 所有 API 密钥均使用 python-dotenv 1.0.1 从环境变量加载。源代码中没有硬编码的凭据。.env 文件通过 .gitignore 被排除在版本控制之外。 CORS 中间件配置了从 CORS_ORIGINS 环境变量加载的显式来源白名单。当启用凭据时，应用程序拒绝通配符来源，以符合 CORS 规范。 前端身份验证仅用于演示，使用基于 localStorage 的会话 token。生产部署需要实现带有 JWT token 或 OAuth2 流程的适当身份验证中间件。 ## 安装和本地开发 ### 前置条件 - Python 3.11 或更高版本 - Google AI API 密钥（可在 https://aistudio.google.com/app/apikey 免费获取） - 可选：Ollama，用于本地模型推理 ### 设置说明 克隆仓库： ``` git clone https://github.com/YOUR_USERNAME/raksha-ai.git cd raksha-ai ``` 创建 Python 虚拟环境： ``` cd backend python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate ``` 安装依赖项： ``` pip install -r requirements.txt ``` 配置环境变量： ``` cp .env.example .env # 编辑 .env 并添加你的 GOOGLE_API_KEY ``` 运行启动诊断： ``` python startup.py ``` 这将验证您的环境配置，测试与 Google AI、HuggingFace、Groq 和 Mistral 服务的 API 连接，检查 Ollama（如果已安装）的可用性，并验证数据库写入权限。 启动开发服务器： ``` uvicorn main:app --host 0.0.0.0 --port 8000 --reload ``` 在 http://localhost:8000 访问应用程序 ### Docker 部署 使用 docker-compose 构建并运行： ``` export GOOGLE_API_KEY=your_api_key_here docker-compose up --build ``` 应用程序将在 http://localhost:8000 上可用，持久化数据库存储在 raksha_data 卷中。 ### 环境变量 **必需：** - `GOOGLE_API_KEY`：用于访问 Gemma 4 31B 的 Google AI API 密钥 - `GEMMA_CLOUD_MODEL`：模型标识符（默认：gemma-4-31b-it） **可选：** - `HUGGINGFACE_TOKEN`：用于 BLIP 视觉的 HuggingFace API token（无 token 时限制为每天 50 个请求） - `GROQ_API_KEY`：用于 Llama 4 Scout 视觉备选方案的 Groq API 密钥 - `MISTRAL_API_KEY`：用于 Pixtral 视觉备选方案的 Mistral API 密钥 - `OLLAMA_BASE_URL`：Ollama 服务器 URL（默认：http://localhost:11434） - `GEMMA_LOCAL_MODEL`：本地模型名称（默认：gemma4:e4b） - `DATABASE_URL`：SQLite 数据库路径（默认：./raksha.db） - `PORT`：服务器端口（默认：8000） - `CORS_ORIGINS`：允许的 CORS 来源，格式为 JSON 数组 - `DEBUG`：启用调试日志记录（默认：false） **性能调优：** - `GEMMA_CLOUD_TIMEOUT`：云 API 超时时间，以秒为单位（默认：60） - `GEMMA_CLOUD_RETRIES`：重试次数（默认：3） - `OLLAMA_TIMEOUT`：Ollama 超时时间，以秒为单位（默认：120） - `MODEL_CHECK_INTERVAL`：可用性缓存 TTL，以秒为单位（默认：30） ### 本地模型设置 从 https://ollama.com 安装 Ollama 拉取支持的模型： ``` ollama pull gemma4:e2b # Lightweight, phones/Raspberry Pi ollama pull gemma4:e4b # Laptops, local assistants, multimodal ollama pull llama3.2:3b # Lightweight alternative, 2GB ollama pull mistral:7b # Alternative, 4.1GB ``` 系统会自动检测已安装的模型，并在云连接不可用时使用它们。 ## API 参考 ### 核心 REST 端点 **健康和状态** - `GET /health` - 返回服务状态的健康检查端点 - `GET /api/v1/status` - 系统状态，包括模型可用性、活跃事件和可用救援人员 **事件管理** - `GET /api/v1/incidents` - 列出事件，可选状态过滤和分页 - `POST /api/v1/incidents` -包含坐标和描述的新事件报告 - `GET /api/v1/incidents/{incident_id}` - 检索特定事件详情 - `PATCH /api/v1/incidents/{incident_id}` - 更新事件状态或详情 **损害评估** - `POST /api/v1/assess` - 带有分段形式图像上传的多模态损害评估 - `POST /api/v1/assess/base64` - 使用 base64 编码图像为 JavaScript 客户端进行损害评估 **AI 对话** - `POST /api/v1/chat` - 与 Gemma 4 31B 的 AI 对话，支持可选的图像附件、对话历史、语言选择和函数调用 **医疗分诊** - `POST /api/v1/triage` - 使用 AI 指导通过 START 协议创建医疗分诊条目 - `GET /api/v1/triage` - 列出分诊条目，可选事件过滤 **紧急警报** - `POST /api/v1/alerts` - 创建并广播带有自动多语言翻译的紧急警报 - `GET /api/v1/alerts` - 列出最近的警报，带分页 **救援人员管理** - `GET /api/v1/responders` - 列出救援人员，可选状态和角色过滤 - `POST /api/v1/responders` - 注册具有角色、团队和技能的新救援人员 - `GET /api/v1/responders/{responder_id}` - 检索特定救援人员的详细信息 - `POST /api/v1/dispatch` - 按优先级分配将救援人员派遣到事件现场 **疏散和资源** - `POST /api/v1/routes` - 生成带有危险感知的疏散路线指导 - `POST /api/v1/mesh/sync` - 用于未来离线功能的点对点 mesh 网络数据同步 ### WebSocket 端点 **实时仪表板** - `WS /ws/dashboard` - 实时事件、救援人员和警报更新 - 在连接时发送包含所有活跃数据的初始状态 - 广播 incident_created、incident_updated、responder_dispatched、new_alert、triage_entry 事件 - 支持 ping/pong 以进行连接健康监控 **流式 AI 聊天** - `WS /ws/chat` - 与 Gemma 4 31B 的流式 AI 对话 - 跨消息维护会话历史 - 在处理期间发送思考指示器 - 流式传输函数调用执行结果 - 支持通过 base64 附加图像 ### 交互式文档 - `/api/docs` - 带有交互式 API 测试的 Swagger UI - `/api/redoc` - 带有详细 schema 的 ReDoc 文档 ## 项目结构 ``` raksha-ai/ ├── backend/ │ ├── main.py # FastAPI application and routes │ ├── gemma_client.py # Gemma 4 unified client with routing │ ├── ai_core.py # Multi-provider cascade fallback │ ├── providers.py # Centralized provider configuration │ ├── vision_agent.py # Multimodal vision pipeline │ ├── triage_agent.py # Medical triage AI logic │ ├── medical_rag.py # Protocol retrieval system │ ├── multimodal_connectors.py # Vision API integrations │ ├── database.py # SQLite async database layer │ ├── models.py # Pydantic data models │ ├── config.py # Environment validation │ ├── startup.py # Diagnostic checks │ ├── requirements.txt # Python dependencies │ └── .env.example # Environment template ├── frontend/ │ ├── index.html # Main application interface │ ├── auth.html # Authentication gate │ ├── app.js # Core application logic │ ├── styles.css # Design system │ ├── dashboard_enhancements.css # Additional styling │ ├── manifest.json # PWA manifest │ └── sw.js # Service worker ├── Dockerfile # Container definition ├── docker-compose.yml # Service orchestration ├── ARCHITECTURE.md # Detailed architecture documentation └── README.md # This file ``` ## 系统架构 ### 模型路由和备选方案 RAKSHA AI 实施了智能提供商选择和自动回退机制，以确保持续运行： **主要路径：通过 Google AI API 使用 Gemma 4 31B** - 使用 8192 token 上下文窗口提供最高质量的响应 - 带有结构化参数 schema 的原生函数调用 - 通过基于文本的视觉分析提供多模态支持 - 3 次带有指数退避（2 秒、4 秒、8 秒延迟）的重试尝试 - 在配置了 GOOGLE_API_KEY 且 API 返回 200 状态时使用 **次要路径：通过 Ollama 使用本地模型** - 在没有互联网连接要求的情况下运行 - 从已安装的 Ollama 模型中自动检测模型 - 优先选择顺序：gemma4 > llama > mistral - 在云 API 不可达或返回 429/503 错误时使用 **第三路径：Groq 备选方案** - Groq Llama 4 Scout (meta-llama/llama-4-scout-17b-16e-instruct) 用于快速推理 - 在云 Gemma 和本地 Ollama 均不可用时使用 - 需要 GROQ_API_KEY 环境变量 **第四路径：静态紧急协议** - 印度（112、1078、108、101）的硬编码紧急联系电话 - 常见灾害场景的基本安全程序 - 永不失败，始终返回可操作的指导 - 在所有 AI 提供商均不可用时作为绝对的最后手段使用 模型可用性被缓存 30 秒，以尽量减少重复请求的延迟。ModelSelector 类探测 Google AI /models 端点和 Ollama /api/tags 端点以确定可用性。 ### 视觉处理 Pipeline 多模态损害评估使用两阶段架构来实现 Gemma 4 的视觉功能： **阶段 1：图像到文本转换** - 主要：通过 Inference API 使用 HuggingFace BLIP (Salesforce/blip-image-captioning-large) - 备选 1：带有原生视觉支持的 Groq Llama 4 Scout - 备选 2：带有原生多模态功能的 Mistral Pixtral - 输出：图像内容的详细自然语言描述 **阶段 2：语义分析** - 输入：来自阶段 1 的文本描述加上上下文（灾害类型、建筑类型） - 处理：Gemma 4 31B 以灾害响应的专业知识分析描述 - 输出：包含 damage_severity（1-10 浮点数）、hazards 数组、structural_integrity 枚举、estimated_trapped 整数、recommended_actions 数组、intelligence_summary 字符串、resource_requirements 对象的结构化 JSON 这种架构允许 Gemma 4 将其卓越的推理应用于视觉任务，而无需原生的多模态 API 支持。中间的文本表示保留了语义信息，同时支持结构化的输出生成。 ### 函数调用实现 Gemma 4 31B 支持使用 JSON schema 定义的六个原生函数工具： **dispatch_responder**：将紧急团队派遣到事件地点，参数包括 incident_id、responder_role（枚举：medical, search_rescue, firefighter, ndrf, volunteer）、priority（枚举：critical, high, medium, low）和 location_description。 **broadcast_emergency_alert**：分发多语言警报，参数包括 title、message、severity（枚举：extreme, severe, moderate, minor）和 languages 数组。 **get_evacuation_route**：生成疏散指导，参数包括 origin_description、hazard_type 和 mobility_level（枚举：full, limited, wheelchair, carrying_injured）。 **log_medical_triage**：创建患者分诊记录，参数包括 symptoms 数组、triage_color（枚举：red, yellow, green, black）、age_estimate 和 location。 **request_resources**：请求设备和物资，参数包括 resources 数组、urgency（枚举：immediate, within_hour, within_day）和 delivery_location。 **calculate_dosage**：计算药物剂量，参数包括 medication、patient_weight_kg、patient_age 和 route（枚举：IV, IM, PO）。 当 Gemma 4 确定应该执行某个函数时，它会在响应中返回一个 functionCall 对象。GemmaClient 类自动执行该函数，更新数据库状态，广播 WebSocket 事件，并将结果合并到最终的响应消息中。 ### 实时通信 WebSocket 连接支持服务器和客户端之间的双向实时通信： **仪表板 WebSocket (/ws/dashboard)** - 在连接时发送包含所有活跃事件、救援人员和警报的 initial_state 消息 - 广播 incident_created、incident_updated、responder_dispatched、new_alert、triage_entry、overwatch_action、mesh_sync 事件 - 支持 ping/pong 消息以进行连接健康监控 - 带有异常处理的死连接自动清理 **聊天 WebSocket (/ws/chat)** - 跨消息维护 session_id 和对话历史 - 在 AI 处理期间发送思考指示器 - 流式传输带有模型归属信息的响应消息 - 在响应中包含 function_calls 和 function_results - 通过 base64 编码处理图像附件 ConnectionManager 类管理活跃连接，实现带有 JSON 序列化的广播功能，并处理数据库时间戳的日期时间序列化。 ## 生产部署 该应用程序部署在 Render 上，地址为 https://rakshak-frontend.onrender.com，具有以下生产配置： **基础设施** - 平台：Render 免费套餐 - 运行时：Docker 容器 - 区域：Oregon (US West) - 实例：512MB RAM，0.1 CPU - 持久存储：1GB 磁盘挂载在 /data **配置** - 健康检查：GET /health 端点，间隔 30 秒，超时 10 秒，重试 3 次 - 自动部署：通过 GitHub 集成在 main 分支提交时启用 - 环境变量：通过 Render 仪表板注入（GOOGLE_API_KEY, HUGGINGFACE_TOKEN, GROQ_API_KEY, MISTRAL_API_KEY） - CORS 来源：为 https://rakshak-frontend.onrender.com 进行配置 - 数据库：带有持久卷的 SQLite 确保数据在容器重启后依然存在 **性能** - 服务器启动：约 2 秒（数据库初始化和模型可用性检查） - 云端 AI 响应：2-5 秒（通过 Google AI API 的 Gemma 4 31B） - 本地 AI 响应：5-15 秒（CPU 上的 Gemma 4 E4B） - 视觉评估：3-8 秒（BLIP 描述加上 Gemma 4 分析） - 数据库操作：<10ms（带有异步 I/O 的 SQLite WAL 模式） - WebSocket 延迟：实时更新 <100ms - 冷启动：15 分钟不活动后约 30 秒（免费套餐限制） **监控** - 健康检查端点监控服务可用性 - Render 仪表板提供 CPU、内存和带宽指标 - 应用程序日志可通过 Render CLI 或仪表板访问 若要进行免费套餐之外的生产部署，请升级到 Render 标准计划，以获得常驻实例、增加的资源以及零冷启动。 ## 致谢 基于 Google DeepMind 的 Gemma 4 31B 构建。视觉功能由 HuggingFace BLIP 提供支持。

标签：AI医疗, AI风险缓解, DLL 劫持, Gemma 4 31B, HuggingFace BLIP, IPv6支持, IP 地址批量处理, Llama 4 Scout, Mistral Pixtral, Render部署, 临床数据分析, 人工智能, 医疗分诊, 医疗急救, 图像描述生成, 图像识别, 多模态分析, 大规模伤亡, 大语言模型, 实时情报分析, 应急响应平台, 应急指挥, 救援协调, 数据可视化, 灾害响应, 灾情评估, 用户模式Hook绕过, 结构安全评估, 网络信息收集, 自动化攻击, 视觉分析, 请求拦截, 逆向工具