# highwayguard-ai

**Repository Path**: wavef/highwayguard-ai

## Basic Information

- **Project Name**: highwayguard-ai
- **Description**: HighwayGuard AI 是一款基于计算机视觉的实时高速公路天气监测系统。它能够分析摄像头画面，检测影响行车安全的恶劣天气（雾、雨、雪），并融合外部传感器数据进行综合判断。
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# HighwayGuard AI / 高速公路智能天气卫士

HighwayGuard AI 是一款基于计算机视觉的实时高速公路天气监测系统。它能够分析摄像头画面，检测影响行车安全的恶劣天气（雾、雨、雪），并融合外部传感器数据进行综合判断。

本项目支持 **云端模式** (Google Gemini API) 和 **本地模式** (私有 AI 模型)，以满足隐私敏感场景的部署需求。

![HighwayGuard Interface](https://ax.minicg.com/images/highwayguard-ai-screenshot.jpg)

## 功能特点

- **实时检测**: 从实时摄像头画面中识别晴天、雾霾、降雨、降雪等情况。
- **多源数据融合**: 集成外部传感器数据（温度、湿度、能见度）以提高准确性。
- **安全风险指数**: 根据视觉危险因素和路面状况计算动态安全评分 (0-100)。
- **弱光/夜间模式**: 针对夜间或低对比度环境优化的提示词逻辑。
- **趋势分析**: 追踪历史天气和安全评分，识别天气恶化趋势。
- **私有化部署**: 支持连接自定义本地 AI 接口（如 LLaVA, Ollama），替代云端 API。
- **双语界面**: 支持一键切换英文和简体中文。

## 使用说明

1. **摄像头权限**: 允许浏览器访问摄像头。
2. **设置面板**:
   - **语言 (Language)**: 切换中文/英文。
   - **AI 提供商**: 选择 "Google Gemini Cloud" 或 "Custom / Local Model" (本地模型)。
   - **运行模式**: 切换 "实时分析" 或 "手动间隔" 模式。
   - **弱光模式**: 在夜间或大雾时开启。
   - **外部传感器**: 输入返回 JSON 数据的 API 地址 (例如 `{ "temperature": 20, "humidity": 80 }`)。
3. **调试模式**: 上传静态图片测试算法，无需等待实时视频流。

## 本地 / 私有化部署

出于隐私和数据主权的考虑，您可以部署本地视觉语言模型 (VLM) 并将其连接到 HighwayGuard AI。

### 1. 环境要求
- 一台运行 VLM 的本地服务器 (例如支持 LLaVA v1.5/v1.6, Yi-VL, BakLLaVA 的环境)。
- 一个接受 POST 请求的 HTTP 接口。

### 2. API 协议
配置您的本地推理服务以接受以下 JSON 格式的请求：

**请求 (POST):**
```json
{
  "image": "不带Header的Base64编码字符串",
  "prompt": "完整的分析提示词...",
  "response_format": "json_object"
}
```

**响应 (期望的 JSON):**
本地模型必须返回符合以下 Schema 的 JSON 对象：

```json
{
  "probabilities": {
    "clear": 80,
    "fog": 10,
    "rain": 5,
    "snow": 5
  },
  "primaryWeather": "Clear", 
  "safetyImpactScore": 10,
  "reasoning": "能见度良好，路面干燥。"
}
```

### 3. 示例：使用 Python 代理
如果您的本地模型输出格式不同，可以编写一个简单的 Python 代理 (FastAPI/Flask) 进行转换：

```python
from fastapi import FastAPI, Request
from pydantic import BaseModel
import uvicorn

app = FastAPI()

class AnalyzeRequest(BaseModel):
    image: str
    prompt: str

@app.post("/analyze")
async def analyze(req: AnalyzeRequest):
    # 1. 将 req.image 和 req.prompt 转发给您的本地模型 (如 Ollama, vLLM)
    # 2. 解析输出，确保严格符合上述 JSON 格式
    # 3. 返回 JSON
    return {
        "probabilities": {"clear": 100, "fog": 0, "rain": 0, "snow": 0},
        "primaryWeather": "Clear",
        "safetyImpactScore": 0,
        "reasoning": "测试用的模拟响应。"
    }

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

### 4. 应用配置
1. 打开应用左侧的 **设置面板**。
2. 将 **AI 提供商** 设置为 `Custom / Local Model`。
3. 将 **接口地址 (Endpoint)** 设置为您的本地地址 (例如 `http://localhost:8000/analyze`)。
4. (可选) 如果接口需要鉴权，请输入 API Key。

## AI 模型要求与训练指南

如果您计划使用自定义模型，请遵循以下指南以确保天气检测的准确性。

### 1. 模型能力要求
AI 模型必须支持 **视觉问答 (VQA)** 并具备 **JSON 输出** 能力。
- **推荐架构**: LLaVA-v1.6 (7B/13B), Yi-VL-34B, 或 Qwen-VL-Chat。
- **上下文理解**: 必须能理解关于“安全评分”和“概率”的系统指令。

### 2. 训练专属 AI 模型
为了在高速公路监控场景下获得高准确率，建议对基础 VLM 进行微调 (Fine-tuning)。

#### A. 数据集准备
您需要准备一个多样化的高速公路图像数据集。

| 天气类别 | 建议数量 | 需包含的视觉特征 |
| :--- | :--- | :--- |
| **Clear (晴朗)** | 2000+ 张 | 干燥沥青路面，清晰阴影，地平线可见，路牌清晰，蓝天/星空。 |
| **Fog (雾霾)** | 2000+ 张 | "白茫茫"环境，路灯光晕，距离标记模糊，低对比度。 |
| **Rain (降雨)** | 2000+ 张 | 路面反光 (眩光)，镜头水滴，车轮飞溅水雾，雨刮器动作 (若为行车记录仪视角)。 |
| **Snow (降雪)** | 2000+ 张 | 路边积雪，车道线被覆盖，飘落的白色颗粒，路面泥泞，车辙印。 |

**图片质量标准:**
- **分辨率**: 至少 1024x768 (720p)。避免使用高压缩率 (马赛克严重) 的 JPEG，因为会丢失雨雾细节。
- **角度**: 包含高位监控 (CCTV) 和平视 (行车记录仪) 两种视角，以增加模型鲁棒性。
- **光照**: 数据集应均匀分布在 白天、夜间、黄昏/黎明。

#### B. 标注策略
将训练数据格式化为 "指令微调 (Instruction Tuning)" 对。

**输入:** `<image>\nAnalyze the weather conditions and safety impact.`
**输出:** (JSON 格式)
```json
{
  "probabilities": { "clear": 0, "fog": 95, "rain": 5, "snow": 0 },
  "primaryWeather": "Fog",
  "safetyImpactScore": 85,
  "reasoning": "由于浓雾能见度不足50米，车道线难以辨认。"
}
```

#### C. 训练技巧
- **LoRA 微调**: 使用 Low-Rank Adaptation (LoRA) 技术，可在消费级显卡 (如 RTX 3090/4090) 上微调 7B+ 模型。
- **类别平衡**: 确保每种天气的图片数量大致相等，防止模型产生偏差 (例如倾向于一直猜测 "Clear")。
- **困难负样本**: 加入看起来像雾但并非雾的图片 (如镜头污渍或烟雾)，教会模型进行区分。

## 推荐训练工具与流程

为了简化微调过程，我们推荐使用 **LLaMA-Factory**，这是一个支持 100+ 种 LLM 和 VLM 的统一微调框架。

### 1. 工具: LLaMA-Factory
- **GitHub**: [hiyouga/LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory)
- **特点**: 支持 LLaVA, Yi-VL, Qwen-VL 等主流视觉模型。提供 Web UI 界面进行配置，支持 QLoRA (低显存占用)。

### 2. 使用 LLaMA-Factory 的流程

1.  **安装**:
    ```bash
    git clone https://github.com/hiyouga/LLaMA-Factory.git
    cd LLaMA-Factory
    pip install -r requirements.txt
    ```

2.  **准备数据 (dataset_info.json)**:
    创建一个符合 LLaMA-Factory LLaVA 格式的数据文件 `weather_data.json`:
    ```json
    [
      {
        "images": ["/path/to/img001.jpg"],
        "conversations": [
          {
            "from": "human",
            "value": "<image>\nAnalyze weather and safety."
          },
          {
            "from": "gpt",
            "value": "{\"probabilities\": {...}, \"safetyImpactScore\": 80, ...}"
          }
        ]
      }
    ]
    ```

3.  **启动 Web UI**:
    ```bash
    python src/train_web.py
    ```

4.  **配置训练**:
    - **模型名称 (Model Name)**: 选择 `LLaVA-1.5-7b` (或类似)。
    - **阶段 (Stage)**: Supervised Fine-Tuning (SFT)。
    - **数据集 (Dataset)**: 选择您刚刚注册的 `weather_data`。
    - **方法 (Method)**: LoRA (以降低显存需求)。
    - **精度 (Precision)**: 4-bit (如果使用消费级显卡)。

5.  **开始训练**: 点击 "Start" 并监控 Loss 曲线。目标 Loss 应降至 0.5 以下以确保收敛。

6.  **导出模型**: 使用 "Export" 标签页将 LoRA 权重合并到基础模型中，生成可用于推理服务的完整模型文件。

## 技术栈
- **前端**: React 19, TypeScript, Tailwind CSS, Recharts.
- **AI 集成**: Google GenAI SDK (Gemini 2.5 Flash) & 自定义 REST 接口集成.