Kushalk0677/fieldaid-offline-disaster-copilot
GitHub: Kushalk0677/fieldaid-offline-disaster-copilot
FieldAid 是一个离线优先的灾难响应辅助系统，在网络中断时通过本地部署的 Gemma 4 大模型和灾难图像分类器，将避难所记录、现场照片和视频转化为结构化的行动计划和事件报告。
Stars: 1 | Forks: 0
# FieldAid：离线灾难响应 Copilot
这所学校从未打算成为避难所。但现在，43 个人睡在教室的地板上，头顶的应急灯可能撑不过今晚。其中 6 人年逾 75 岁。还有两名需要注射胰岛素的儿童，胰岛素必须保持低温，而此时发电机正在苦苦挣扎，冰箱也开始罢工。
外面，通往主干道的桥梁在一小时前坍塌了。
父母们试图让孩子们保持平静，与此同时，志愿者们正在配给仅存的清洁水；如果大家都省着用，可能还够维持八个小时。无线电里传出区内其他三个避难所传来的断断续续的嘈杂声。有人提到洪水泛滥。还有人提到了人员受伤。已经没有人知道哪些信息才是真实的了。
紧接着，网络彻底中断了。
此时没有任何云端 AI 能够伸出援手。OpenAI GPT-4、Anthropic Claude 和 Google Gemini Pro 都依赖网络连接。在灾难发生后的最初关键几个小时里，这一前提假设就彻底失效了。
FieldAid 正是为网络瘫痪之后的那一刻而构建的。
它完全在一台笔记本电脑上离线运行，直面响应人员所面临的实际情况：手写笔记、受损照片、摇晃的现场视频和残缺的目击报告，然后将它们转化为可用的信息。它能生成优先级排序的事件包、可执行的响应计划、物资请求、适配 SMS 的更新、基于事实的引用以及验证标记。
其核心是通过 Ollama 在本地运行 Gemma 4 E4B，为响应人员提供他们在灾难期间几乎从未有过的一样东西：在通信、协调和确定性全面崩溃时的一丝清晰。
## FieldAid 的功能
FieldAid 旨在帮助响应人员应对洪水、火灾、风暴、地震或停电后的最初混乱时段。响应人员可以输入避难所记录、上传受损图像或扫描短视频，应用程序会将这些证据转化为带有优先级的事件包。该事件包包含提取的事实、推断的建议、物资需求、SMS/无线电文本、Discord 交接草稿、来自内置指南的引用以及人工验证标记。
该项目在设计上秉持“本地优先”理念。Gemma 4 通过 Ollama 运行，应急指南从本地 Markdown 文件中检索，事件存储在 SQLite 中，上传的媒体保留在磁盘上，待网络连接恢复后再进行同步/导出。该应用还包含一个小型本地灾难图像分类器，该分类器基于 QCRI/MEDIC 衍生数据训练而成，因此即使在云端视觉模型不可用时，仍能对照片和视频证据进行初步分诊。
## 主要演示情景
请在 Web 应用中使用 **Mission Mode（任务模式）** 观看完整的评委导览：
1. 避难所登记：加载包含胰岛素患者、缺水和道路受阻情景的洪灾学校场景。
2. 视频扫描：上传火灾、洪水、道路或建筑物受损的短视频。
3. 模型推理：展示 Gemma、分类器证据、YOLO 支持、RAG 引用和工具追踪。
4. 信任门槛：提出有风险的安全问题，并展示人工验证标记。
5. 交接：创建 Discord/无线电草稿和事件包。
6. 离线验证：展示本地模型、SQLite、内置指南和稍后同步导出功能。
结语：
## 架构
```
flowchart LR
UI["Local browser UI"] --> API["FastAPI backend"]
API --> Gemma["Ollama / Gemma 4"]
API --> RAG["Bundled emergency guidance RAG"]
API --> DB["SQLite incident log"]
API --> Files["Local uploads"]
API --> Classifier["MEDIC image classifier"]
API --> YOLO["Optional YOLO detector"]
Gemma --> Output["Incident packet"]
RAG --> Output
Classifier --> Output
YOLO --> Output
Output --> Board["Action board"]
Output --> Handoff["SMS / Discord draft"]
Output --> Export["Sync-later JSON export"]
```
## 仓库结构
- `app/`：FastAPI 后端、Gemma 调用、RAG、SQLite、基础事实依据、分类器和视频扫描逻辑。
- `static/`：本地单页浏览器 UI。
- `data/guidance/`：用于引用的离线应急指南。
- `data/web_samples/`：用于快速测试的小型演示媒体。
- `data/uploads/`：运行时上传目录；除占位符外，其余均被 Git 忽略。
- `models/`：本地模型资产，包括最终的 MEDIC 分类器检查点。
- `modeltraining/`：QCRI/MEDIC 数据集下载器和准备文档。
- `training/`：模型训练、评估和 Ollama 适配器实用工具。
- `tests/`：单元测试和 API 测试。
- `submission/`：Kaggle 撰写草稿、视频脚本、架构说明和演示清单。
每个主要文件夹都有自己的 `README.md`。
## 环境要求
对于常规 Web 应用，请使用 Python 3.11 或更高版本，安装 `requirements.txt` 中的依赖包，并安装 Ollama，以便 Gemma 4 可以在本地运行。包含的 MEDIC 分类器检查点已存在于仓库的 `models/fieldaid-medic-image-classifier-final/best.pt` 路径中，因此无需单独下载轻量级图像分类器。
视频扫描使用 OpenCV 进行帧采样。YOLO 支持是可选的；如果 Ultralytics 或 YOLO 权重不可用，FieldAid 仍会对帧进行采样，并在可能的情况下运行本地分类器，同时创建一个供人工审查的事件。训练或复现模型最好在 Linux、WSL、Kaggle 或 GPU 服务器上完成。轻量级分类器可以在较旧的 GPU 上运行，而 Gemma 4 视觉 LoRA 实验对算力要求要高得多，可能无法在 12 GB 的 P100 显卡上运行。
## 模型下载与设置
FieldAid 可以在三个模型层上运行。主要的推理层是通过 Ollama 运行的 Gemma 4。灾难图像证据层是内置的经过 MEDIC 训练的 MobileNetV3 分类器。可选的目标检测层是 YOLO，它有助于识别采样视频帧中的人物、车辆和其他与通行相关的对象。
### 1. 使用 Ollama 下载 Gemma 4
安装 Ollama：
```
https://ollama.com
```
拉取应用使用的默认本地模型：
```
ollama pull gemma4:e4b
```
可选的更强大的工作站模型：
```
ollama pull gemma4:26b
```
检查 Ollama 是否识别到该模型：
```
ollama list
```
快速冒烟测试：
```
ollama run gemma4:e4b "Summarize this shelter note: 43 people, insulin patients, low water, blocked road."
```
FieldAid 模型选择器值：
```
gemma4:e4b
gemma4:26b
fieldaid-gemma4:e4b
```
`fieldaid-gemma4:e4b` 是可选的。仅当您训练/导出 FieldAid 适配器或从 `training/Modelfile.fieldaid-gemma4-e4b` 创建本地 Ollama 模型时才使用它。
### 2. 验证内置的 MEDIC 分类器
公开代码仓库中包含小型最终检查点：
```
models/fieldaid-medic-image-classifier-final/best.pt
```
该检查点大约 **6.2 MB**，其体积经过刻意精简，以便随代码仓库一起分发。它是基于 25% 的 QCRI/MEDIC 衍生 FieldAid 子集训练的 MobileNetV3 Small 分类器，具有四个操作标签：`building_damage`、`fire`、`flood` 和 `road_damage`。准备好的子集在平衡前包含 17,799 行标记数据，具体标签数量为 11,392 张建筑物受损图像、5,022 张洪水图像、839 张道路受损图像和 546 张火灾图像。最终的平衡训练运行使用了 6,279 个训练样本和 1,106 个验证样本，共进行了 8 个周期。最佳验证准确率为 **63.56%**，于第 2 个周期达到，此处包含的即是该最佳检查点。
验证其是否存在：
```
Test-Path models\fieldaid-medic-image-classifier-final\best.pt
```
对任意本地图像运行预测：
```
python -m training.predict_medic_image_classifier `
data\web_samples\flood_damage_to_road.jpg `
--checkpoint models\fieldaid-medic-image-classifier-final\best.pt
```
预期输出为带有类似以下标签的 JSON：
```
{
"predictions": [
{"label": "flood", "confidence": 0.70},
{"label": "building_damage", "confidence": 0.22}
]
}
```
此分类器会在以下过程中自动被调用：
- 信任照片上传
- 视频采样帧聚合
### 3. 下载 YOLO 支持模型
YOLO 是可选的。FieldAid 仅将其用于辅助目标检测，而非主要的灾难分类。
代码仓库中可能已包含：
```
yolo11n.pt
```
包含的 `yolo11n.pt` 文件大约为 **5.6 MB**。它并非专为灾难类别而训练；FieldAid 仅使用它来补充支持性观察结果，例如采样帧中出现的人物、车辆或交通物体。灾难标签本身应来自 Gemma 帧分析、本地 MEDIC 分类器和人工审查。
如果缺失，请安装 Ultralytics 并让其下载模型：
```
python -m pip install ultralytics
python -c "from ultralytics import YOLO; YOLO('yolo11n.pt')"
```
可选的自定义灾难检测器：
```
models/disaster_yolo.pt
```
如果您训练了自定义 YOLO 权重，请将其放置在相应位置。FieldAid 将优先使用 `models/disaster_yolo.pt` 而不是 `yolo11n.pt`。
### 4. 可选的 Hugging Face 下载（用于 Gemma 权重）
您无需原始的 Hugging Face Gemma 权重即可通过 Ollama 运行 Web 应用。仅在需要进行训练实验或非 Ollama 推理时才使用此选项。
如果模型需要访问批准，请先登录：
```
hf auth login
```
本地下载示例：
```
hf download google/gemma-4-E4B-it --local-dir models/gemma-4-E4B-it
```
原始 Gemma 权重体积庞大，不应提交到此代码仓库中。
## 快速入门：运行 Web 应用
### 1. 克隆代码仓库
```
git clone https://github.com/YOUR_USERNAME/fieldaid-offline-disaster-copilot.git
cd fieldaid-offline-disaster-copilot
```
### 2. 创建虚拟环境
Windows PowerShell：
```
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```
Linux/macOS：
```
python3 -m venv .venv
source .venv/bin/activate
```
### 3. 安装应用依赖
```
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```
如果您只想要不带 YOLO 的最低配置 Web 应用，可以通过手动安装核心包来处理可选 ML 包的安装失败问题：
```
python -m pip install fastapi "uvicorn[standard]" python-multipart httpx pydantic pytest opencv-python pillow torch torchvision
```
### 4. 安装 Ollama 并拉取 Gemma 4
请遵循上述**模型下载与设置**中的命令。最低建议命令为：
```
ollama pull gemma4:e4b
```
如果没有 Ollama，FieldAid 仍可回退到确定性的本地安全输出以保持可用性，但效果最佳的演示需要使用本地 Gemma。
### 5. 启动 FieldAid
```
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```
打开：
```
http://127.0.0.1:8000/
```
用于主动开发：
```
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```
## 如何使用 Web 应用
### 任务
URL 路由：
```
#mission
```
请首先在黑客松演示中使用此功能。它将引导您完成：
- 避难所登记
- 视频证据
- Gemma 工具
- 信任门槛
- 交接/导出
- 离线验证
点击 **Start Guided Mission** 以加载默认的危机情景。
### 登记
URL 路由：
```
#intake
```
将此用于避难所和受损报告。
避难所工作流程：
1. 选择或加载演示情景。
2. 输入避难所位置。
3. 选择 Gemma 模型。
4. 粘贴现场记录或使用默认记录。
5. （可选）上传避难所照片或记录截图。
6. 点击 **Analyze Shelter**。
受损评估工作流程：
1. 切换到 **Damage Assessment**。
2. 输入道路、桥梁、避难所或通道位置。
3. （可选）上传一张受损前的图像。
4. 如有条件，上传受损图像。
5. 点击 **Assess Damage**。
输出包括：
- 紧急程度
- 提取的事实
- 推断的建议
- 行动计划
- 物资请求
- SMS/无线电信息
- 引用
- 验证标记
- 工具追踪
### 仪表板
URL 路由：
```
#dashboard
```
显示本地行动的汇总状态：
- 医疗需求
- 用水需求
- 受阻路线
- 验证标记
- 离线路线看板
在创建事件后请使用 **Refresh**。
### 视频
URL 路由：
```
#video
```
将此用于上传的视频片段。
步骤：
1. 输入视频位置。
2. 选择帧采样间隔。
3. 选择 Gemma 模型。
4. 上传 MP4/MOV/AVI/MKV/WEBM 格式的视频片段。
5. 点击 **Run Video Scan**。
FieldAid 将会：
- 在本地保存视频
- 按选定的间隔对帧进行采样
- 在条件允许时让 Gemma 解读采样帧
- 使用本地 MEDIC 分类器对每个采样帧进行分类
- 聚合重复的标签，例如 `fire in 7/9 frames`（7/9 帧中出现火灾）
- 可选运行 YOLO 进行辅助目标检测
- 创建带有安全标记的受损事件
- 显示带注释的/采样的帧以及检测时间轴
安全行为：
- 任何视频结果都不会声明某条路线、桥梁或结构是安全的
- 无检测结果意味着需要人工审查，而非“安全”
- 结构/生命安全决策需要人工验证
### 信任
URL 路由：
```
#trust
```
使用此项测试基础事实依据与安全拒绝行为。
示例问题：
```
Can we send civilians across this damaged bridge if it looks mostly intact?
```
可选：上传一张状态照片。
FieldAid 将会显示：
- 回答
- 本地视觉分类器面板
- 视觉证据
- 建议的操作
- Discord 草稿
- 工具追踪
- 验证标记
- 引用
Discord 行为：
- FieldAid 起草一条消息。
- 它可以复制该消息并打开 Discord 目标位置。
- 它不会自动发送。
- 系统会创建本地发件箱记录以保证可追溯性。
### 离线验证
URL 路由：
```
Can we send civilians across this damaged bridge if it looks mostly intact?
```
在视频中请使用此功能以展示：
-地 Gemma/Ollama 运行时
- 本地 MEDIC 分类器检查点
- 本地 SQLite 事件
- 同步队列计数
- 发件箱草稿
- 内置指南/RAG
- 工具追踪库
### 事件
URL 路由：
```
#incidents
```
显示本地 SQLite 事件记录。
对于每个事件，您可以：
- 查看摘要
- 检查紧急程度/状态
- 更新状态
- 下载交接数据包
### 导出
URL 路由：
```
#exports
```
将此用于离线到在线的交接。
功能：
- 将排队的同步记录导出为 JSON
- 在传输后将记录标记为已导出
- 检查出站的 Discord/无线电交接草稿
## 本地模型
### 通过 Ollama 运行的 Gemma 4
Gemma 4 是 FieldAid 中的主要推理模型。默认运行时为 `gemma4:e4b`，这是本地优先演示的最佳目标。如果机器具有更大的内存和计算能力，可以在 UI 中选择 `gemma4:26b` 以获得更强的推理能力。如果您随后训练/导出了 FieldAid 特定的适配器并将其导入 Ollama，FieldAid 还可以将 `fieldaid-gemma4:e4b` 暴露为选择器选项。
应用程序在避难所登记、受损评估、照片基础事实分析和视频帧分析期间会调用 Gemma。如果 Gemma 不可用，FieldAid 会回退到谨慎的本地逻辑，以便演示仍可使用，但效果最佳的黑客松展示方案依然是使用通过 Ollama 运行的本地 Gemma。
支持的选择器名称：
```
gemma4:e4b
gemma4:26b
fieldaid-gemma4:e4b
```
下载命令请参见[模型下载与设置](#model-download-and-setup)。
### MEDIC 灾难图像分类器
内置的 MEDIC 分类器是该项目的实用领域适应层。我们没有尝试在 12 GB 的 P100 上微调整个 Gemma 4 视觉模型，而是训练了一个可以在本地运行并为 Gemma 和安全层提供证据的轻量级灾难图像分类器。它用于信任照片上传和跨采样视频帧聚合标签。
包含的检查点：
```
models/fieldaid-medic-image-classifier-final/best.pt
```
该检查点是一个具有四个类别的 MobileNetV3 Small 模型：`building_damage`、`fire`、`flood` 和 `road_damage`。体积约为 **6.2 MB**。它基于 25% 的 QCRI/MEDIC 衍生 FieldAid 子集进行训练，并针对训练进行了平衡，包含 6,279 个训练样本和 1,106 个验证样本。训练运行持续了 8 个周期，最佳检查点来自第 2 个周期，**验证准确率达到 63.56%**。该模型被有意设定为仅作为支持性证据；它永远不会取代人工验证。
模型摘要：
```
mobilenet_v3_small
classes: building_damage, fire, flood, road_damage
best validation accuracy: 0.6356
```
要从 QCRI/MEDIC 复现此检查点，请遵循[复现 MEDIC 分类器训练](#replicate-the-medic-classifier-training)。
### YOLO
YOLO 是可选的，起辅助作用。FieldAid 首先会在 `models/disaster_yolo.pt` 中寻找自定义灾难 YOLO 权重。如果该文件不存在，它会尝试寻找 `yolo11n.pt`。包含的 `yolo11n.pt` 大约为 **5.6 MB**，用于通用对象上下文识别，例如路线附近的人员或车辆。它并非主要的灾难分类器。
模型查找顺序：
```
models/disaster_yolo.pt
yolo11n.pt
```
如果 `yolo11n.pt` 缺失，请使用以下命令重新创建：
```
python -m pip install ultralytics
python -c "from ultralytics import YOLO; YOLO('yolo11n.pt')"
```
## 复现 MEDIC 分类器训练
公开代码仓库不包含完整的原始 QCRI/MEDIC 数据集，因为其体积过大。请使用下载器在本地重新创建数据集。
### 1. 安装训练要求
在 GPU/Linux/WSL/Kaggle 环境中：
```
python -m venv disaster-fieldaid-venv
source disaster-fieldaid-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-train.txt
```
仅用于轻量级分类器：
```
python -m pip install torch torchvision pillow datasets huggingface_hub tqdm
```
### 2. 下载 MEDIC 子集
从代码仓库根目录：
```
python modeltraining/medic_qcri/download_medic.py --fraction 0.25 --clean-output --overwrite
```
用于微型冒烟测试样本：
```
python modeltraining/medic_qcri/download_medic.py --max-rows 25 --clean-output --overwrite
```
下载器会创建一个聚焦于 FieldAid 的子集，标签如下：
- fire
- flood
- road_damage
- building_damage
### 3. 训练分类器
```
python -m training.train_medic_image_classifier \
--image-root modeltraining/medic_qcri/fieldaid/images \
--output-dir models/fieldaid-medic-image-classifier-final \
--model mobilenet_v3_small \
--epochs 8 \
--batch-size 32
```
最佳检查点保存为：
```
models/fieldaid-medic-image-classifier-final/best.pt
```
### 4. 测试分类器
```
python -m training.predict_medic_image_classifier \
modeltraining/medic_qcri/fieldaid/images/fire/YOUR_IMAGE.jpg \
--checkpoint models/fieldaid-medic-image-classifier-final/best.pt
```
预期输出形状：
```
{
"image": "path/to/image.jpg",
"predictions": [
{"label": "fire", "confidence": 0.83},
{"label": "building_damage", "confidence": 0.10}
]
}
```
## Gemma 微调说明
代码仓库包含实验性的 Gemma/Unsloth 训练实用工具：
- `training/train_fieldaid_lora.py`
- `training/train_fieldaid_vision_lora.py`
- `training/evaluate_fieldaid_adapter.py`
- `training/Modelfile.fieldaid-gemma4-e4b`
- `training/SSH_GPU_RUNBOOK.md`
现实检验：
- Gemma 4 视觉 LoRA 对于像 Tesla P100 这样较旧的 12 GB GPU 来说可能过于庞大。
- 内置的轻量级 MEDIC 分类器是该 MVP 的实际领域适应路径。
- FieldAid 仍通过 Ollama 将 Gemma 4 用作核心的本地推理引擎。
## 运行测试
从代码仓库根目录：
```
python -m pytest -q tests
```
在 Windows 上，如果临时目录权限被锁定：
```
$env:TEMP='C:\tmp'
$env:TMP='C:\tmp'
python -m pytest -q tests --basetemp C:\tmp\fieldaid_pytest -p no:cacheprovider
```
预期的当前结果：
```
34 passed
```
## 离线演示清单
录制前：
```
ollama list
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```
然后打开：
```
http://127.0.0.1:8000/#mission
```
展示以下验证点：
- 应用在 localhost 上运行
- Ollama 模型在本地可用
- 任务模式引导流程
- Gemma 工具追踪
- 本地 MEDIC 分类器输出
- 视频帧聚合
- 来自内置指南的引用
- SQLite 事件日志
- Discord 交接发件箱
- 稍后同步导出
- 离线验证页面
## 安全定位
FieldAid 是一个决策支持原型，面向受过训练的响应人员和社区协调员。它不能替代紧急服务、医疗专业人员、结构工程师、消防部门或公共当局。
应用程序中全面执行的规则：
- 绝不通过图像声明任何道路、桥梁、路线或结构是安全的
- 未经人工验证，没有任何医疗、结构或生命安全建议是最终决定
- 不会自动发送任何 Discord 消息
- 显示引用和工具追踪以保证可审计性
- 不确定的视觉结果将转为人工审查事件，而非得出安全结论
## 公开代码仓库说明
此代码仓库刻意排除了：
- Python 虚拟环境
- 运行时 SQLite 数据库
- 运行时上传内容
- 原始 MEDIC 数据集图像
- Hugging Face 缓存
- 临时日志和缓存
它包含：
- 源代码
- 测试
- 示例指南
- 小型演示媒体
- 最终的轻量级分类器检查点
- 训练和复现脚本
- 提交的作品撰写/视频/架构草稿
## 许可证与数据集说明
FieldAid 代码旨在用于黑客松演示和研究原型设计。如果您发布了训练后的权重或数据集，请验证 Gemma、QCRI/MEDIC、CrisisMMD 衍生资产以及您包含的任何示例媒体的许可证和条款。
标签：AI for Good, AI风险缓解, DNS解析, Gemma 4, LLM评估, Ollama, 人工智能助手, 人道主义援助, 信息同步, 凭据扫描, 危机管理, 图像识别, 多模态AI, 库, 应急响应, 开源项目, 本地大模型, 本地部署, 灾害响应, 灾害管理, 现场救援, 离线AI, 离线优先, 笔记分析, 紧急救援, 行动计划, 视频分析, 边缘计算, 逆向工具