VoyageGuard · 出行气象决策助手

AI Agent 驱动的气象风险决策工具，专注飞机与船只出行场景。将实时气象数据与行业安全红线自动比对，直接给出"能不能走"的决策建议。支持中英文双语切换。

🚀 Live Demo

→ 在线体验 · Hugging Face Spaces

无需部署，打开即用。

功能演示

输入出发地、目的地、出行日期和交通方式，AI 自动调用天气工具和预警搜索，输出结构化风险评估：

• 低风险（绿）：建议按原计划出行
• 中风险（琥珀）：大概率延误，建议关注动态
• 高风险（红）：极大概率停航/取消，建议启动备选

内置三个示例场景按钮，一键填入典型场景（航空高风险 / 海事高风险 / 低风险出行）。

界面右上角提供 中/EN 语言切换，切换后所有 UI 文字及 AI 输出均以对应语言展示。

快速启动（三步）

1. 安装依赖

pip install -r requirements.txt

2. 配置 API Key

echo "DASHSCOPE_API_KEY=your_key_here" > .env

3. 启动服务

uvicorn app:app --reload

打开浏览器访问 http://localhost:8000

技术栈

• 后端：FastAPI + Python
• LLM：DeepSeek-V3（via Dashscope OpenAI 兼容接口）
• 气象数据：wttr.in（免费，无需 Key）
• 搜索：DDGS（DuckDuckGo，免费，无需 Key）
• 前端：纯 HTML/CSS/JS 单文件，Mission-Critical Operations Center 风格
• 部署：Hugging Face Spaces（Docker runtime）

AI 系统设计

Agent 架构（ReAct 模式）

模型自主决定调用哪些工具、调用几次：

航空场景：查出发地天气 → 查目的地天气 → 比对规则 → 输出（2次调用）
航海场景：查目的地天气 → 发现风力偏高 → 追加搜索预警 → 综合研判（3次调用）

安全阀：最大工具调用次数 5 次，超过后强制输出当前信息的评估结果。

规则引擎安全网（V1.5）

LLM 判断结果经过 Python 硬编码规则做二次校验：

用户请求 → ReAct Agent（LLM + 工具调用）→ LLM 输出 JSON
                                              ↓
                              rule_validator（Python 硬规则）
                                              ↓
                              最终结果（可能含 rule_override: true）

• Override UP：气象数据明确越过硬红线（如风速 ≥ 15 m/s），但 LLM 保守判了低风险 → 强制升级，同步将 is_go_recommended 置为 false
• Override DOWN：所有结构化指标均低于触发阈值，但 LLM 判了 HIGH → 降级。仅对 HIGH 生效，不干预 MEDIUM——MEDIUM 代表 LLM 对多因素边缘组合（如冻雨 + 接近阈值的能见度）的综合判断，硬阈值无法捕获，应予保留
• 输出字段 rule_override: true/false 明确告知是否发生了规则校正，is_go_recommended 随最终风险等级同步更新

为什么不直接用规则引擎替代 LLM？ 规则引擎只处理"有明确阈值的硬红线"——灰色地带（多因素叠加、气象文字描述判断）仍由 LLM 负责，保留了 Agent 对复杂场景的灵活性。

安全规则知识库

场景	红线	判定
航空	侧风 > 15 m/s	高风险
航空	能见度 < 0.4 km	高风险
航空	起降地有雷暴	至少中风险
近海游船	阵风 ≥ 6 级（10.8 m/s）	高风险
跨海客滚船	阵风 ≥ 8 级（17.2 m/s）	高风险
海事	有效浪高 > 2.5 m	高风险
海事	浪高 1.5-2.5 m 或风力 5-6 级	中风险

双语支持

• 前端 UI 右上角切换按钮（中 / EN）
• 切换后同步传递 lang 字段至后端
• 后端根据 lang 调整：用户问句语言、System Prompt 语言指令、规则引擎 override 提示文字
• LLM 的所有输出字段（weather_summary、core_reason、alternative_advice、risk_label）随之切换为英文

防刷保护

内存级 Rate Limiting：每 IP 每小时最多 20 次请求，超出返回 HTTP 429。

模型横评（Eval）

项目包含 eval.py，30 条标注测试用例，覆盖边界值、灰色地带、多因素叠加场景。全部 mock 工具执行，测试纯 LLM 推理能力。

最新结果（V1.6：LLM + 规则引擎安全网）

模型	LLM 准确率	安全网后	提升	JSON 合规率	平均响应时间
deepseek-v3-250324 ✓	90.0%	96.7%	+6.7%	100%	7.4s
qwen-plus	90.0%	93.3%	+3.3%	100%	9.0s
hunyuan-turbos-latest	73.3%	86.7%	+13.3%	100%	14.1s

综合准确率与响应时延，选定 DeepSeek-V3 作为生产模型（96.7%，均速 7.4s）。规则引擎将最弱模型（Hunyuan）准确率从 73.3% 拉升至 86.7%（+13.3%），体现了"LLM 负责灰色地带，硬规则守住红线"的架构分层价值。

运行 python eval.py 获取最新结果

评测亮点

• 灰色地带评分：对"雷暴 + 风速接近但未超红线"等本身存在合理争议的用例，标注 acceptable_levels: ["MEDIUM", "HIGH"]，命中任一值均算正确，避免把 prompt 模糊性误计为模型错误
• 硬判 vs 灰色区分：每条用例结果标注"硬判"或"灰色"，方便分析失败原因
• 多模型对比：同一用例集同时测三个模型，定位各自失败模式（精度不足 / 语义理解差异 / 保守偏差）

部署到 Hugging Face Spaces

本项目已部署至 HF Spaces Docker runtime：https://huggingface.co/spaces/wenboxia/voyageguard

自行部署步骤：

1. 在 huggingface.co 创建新 Space，选择 Docker runtime
2. 在 Space 的 Settings → Repository secrets 中添加 DASHSCOPE_API_KEY
3. git remote add origin https://huggingface.co/spaces/<用户名>/<space名>
4. git push，HF 自动构建 Docker 镜像，约 2-3 分钟后上线

切换为本地 Ollama 模型

修改 app.py 中的 client 配置（注释已标注）：

client = OpenAI(api_key="ollama", base_url="http://localhost:11434/v1")
MODEL = "qwen2.5:7b"

后续演进方向（V2）

• 接入专业气象 API（OpenWeatherMap、StormGlass）替代 wttr.in
• 规则库扩展至不同船型/机场，迁移至 RAG 架构
• 增加"出发前提醒"（邮件/推送）
• 接入航班动态 API，交叉验证 AI 判断 vs 实际航班状态
• 历史准确率看板（追踪 AI 判断 vs 实际结果，持续优化 prompt）

License

MIT © 2025 wenboxia