LLM-based Maritime Navigation Decision Agent 面向船舶驾驶台的航行决策支持系统
给定本船状态、周边 AIS 目标与海况,完成态势分析、碰撞风险判断、 避让动作可行性评估,并用自然语言给出可解释的建议。
本项目是决策支持(decision support),不是自动驾驶:
- 不控制舵机、主机,不替代驾驶员
- 不宣称「COLREGs 合规」——规则的解释与最终避让责任在驾驶员
- 贡献在于:把规则里可量化的部分(会遇局面分类、DCPA/TCPA、让路/直航判定) 算准,并让 Agent 在人能理解的层面组织多步决策与解释
不这样定位的项目,第一个问题就会是"出事谁负责"。
| 现状 | 痛点 | 本项目的做法 |
|---|---|---|
| 驾驶台已有 AIS / 雷达 / ECDIS | 数据各自呈现,靠人脑综合 | Agent 自动汇总、排序、给结论 |
| 繁忙水域需持续盯屏 | 疲劳、漏检、判断不一致 | 自动筛出最危险的目标 |
| 避碰规则条文复杂 | 新人上手慢,局面分类易错 | 几何判定 + 规则条款引用 |
| 大船回转需要数分钟 | 多数系统给出"转30度"却不检查来不来得及 | assess_maneuver 强制可行性检查 |
最后一条是本项目相对同类项目的关键差异。多数 LLM 海事项目会让模型 直接说"建议向右转向 30 度",但不检查这艘船转得过来吗。20 万吨级船舶 转向 30° 可能需要数分钟 —— 在 5 分钟 TCPA 下根本来不及。
驾驶员
│
▼
┌──────────────────┐
│ Maritime Agent │ ReAct 循环 + Tool Calling
│ (LLM 决策层) │ 失败按 error_code 分类处置
└────────┬─────────┘
│ tools
┌─────────┬───┴────┬──────────┬──────────┐
▼ ▼ ▼ ▼ ▼
态势查询 单目标 全量分析 动作可行性 场景载入
分析 评估
└─────────┴────────┴──────────┴──────────┘
│
▼
┌──────────────────┐
│ Deterministic │ ← 纯 Python,零 LLM,完全可单测
│ Core │ DCPA/TCPA/会遇分类/风险分级
└──────────────────┘
为什么这条线必须划清:模型算三角函数会错,而且错得没有规律; 无法审计(出了问题不知道该信谁);无法回归测试(同样输入不同输出)。
这条原则继承自作者的机器人项目 —— 那里也是「模型只输出语义地点名, 坐标由配置文件决定」。两个领域的教训完全一致:
把确定性计算留给代码,把推理与解释留给模型。
零第三方依赖(仅标准库),有 Python 3.8+ 即可运行。
# 1. 跑全部标准场景自检(不需要 API Key)
python3 main.py
# 2. 生成态势图
python3 demo.py --trajectory
# 3. 单元测试
python3 -m pytest tests/ -q用 LLM 分析(需 DEEPSEEK_API_KEY):
python3 main.py --ask "当前有哪些碰撞风险,我该怎么办?" --scenario head_on没有 Key 也能演示:未检测到 API Key 时自动回退到离线规则规划器, 走完同样的工具调用链。这是答辩现场断网时的保底方案。
标准场景自检(python3 main.py):
[head_on] 目标在正前方 3 NM,航向相反(对遇)
目标1: 距离 3.00 NM, DCPA 0.00 NM, TCPA 8.2 min, head_on, both, 风险 警告
[crossing_give_way] 目标在本船右舷(方位 045°)3 NM
目标1: 距离 3.00 NM, DCPA 0.27 NM, TCPA 11.5 min, crossing, give_way, 风险 注意
[crossing_stand_on] 目标在本船左舷(方位 315°)3 NM
目标1: 距离 3.00 NM, DCPA 0.27 NM, TCPA 11.5 min, crossing, stand_on, 风险 注意
[overtaking] 本船 14 kn 从后方接近正前方 1 NM 处同向 8 kn 的慢船
目标1: 距离 1.00 NM, DCPA 0.00 NM, TCPA 10.0 min, overtaking, give_way, 风险 警告
[being_overtaken] 本船 8 kn,后方 1 NM 处 14 kn 快船同向追越本船
目标1: 距离 1.00 NM, DCPA 0.00 NM, TCPA 10.0 min, overtaking, stand_on, 风险 警告
====================================================================
全部 6 个场景通过
Agent 完整链路(离线模式,python3 smoke_test.py):
--- 第 1 轮 --- [行动] get_own_ship_state({})
--- 第 2 轮 --- [行动] analyze_all_targets({"top_n": 3})
[观察] 1. 目标1:警告,DCPA 0.00 NM / TCPA 8.2 min, head_on
--- 第 3 轮 --- [行动] assess_maneuver({"turn_deg": 30})
[观察] 本船转 30° 需 90s,时间余量 +401s,可行
--- 第 4 轮 --- [行动] report_advice(...)
成功:True 轮数:4 工具调用:4 耗时:0.6s
maritime/ 确定性内核(零依赖、零 LLM、100% 可测)
├── units.py 海里/节/度 换算
├── geometry.py 方位角、相对方位、角度规约
├── vessel.py 船舶对象(含操纵性参数)
├── cpa.py DCPA/TCPA 解析解
├── colregs.py 会遇局面分类(规则 13/14/15)
├── risk.py 分级风险评估
├── scenarios.py 标准测试场景
└── viz.py 态势可视化(matplotlib,无 GUI)
agent/ Agent 层(LLM 决策)
├── contracts.py ToolResult / ErrorCode / TaskRecord
├── core.py ReAct 主循环
├── prompts.py 系统提示
├── llm_client.py OpenAI 兼容客户端 + 离线规划器
└── tools/
├── registry.py 工具注册、参数校验、禁用策略
├── maritime_tools.py 海事工具集
└── report_tools.py 终止类工具
tests/
├── test_core.py 内核测试(手算验证)
└── test_agent.py Agent 测试(假 LLM)
main.py 命令行入口
demo.py 可视化演示
smoke_test.py 端到端冒烟测试
同领域开源实现(CORALL, MIT)用相邻两帧位置差:
v_rel = |p_rel(t) - p_rel(t-1)| / ts三个问题:依赖采样率、把位置噪声放大到速度上、AIS 报文间隔不均匀 (锚泊 3 分钟、航行 2-10 秒、会丢包)导致相对速度跳变。
本项目用相对运动解析解,只依赖当前状态:
r = p_target - p_own
vr = v_target - v_own
TCPA = -(r·vr) / |vr|²
DCPA = |r + vr·TCPA| (TCPA>0)
结果与采样率无关,且可手算验证 —— 测试里每个 CPA 用例都是纸笔能算出来的。
规则 13 说的是「追越船让路」,不是「遇到追越局面本船让路」。 常见错误是把两者混淆。
所以分别判断:
目标在本船船尾扇区 -> 目标追越本船 -> 本船直航(stand_on)
本船在目标船尾扇区 -> 本船追越目标 -> 本船让路(give_way)
两种情形都有独立的测试用例(overtaking 与 being_overtaken),
只测一种无法证明实现真的区分了方向。
规则 13(e) 明确:追越局面在追越过程中始终存在, 即使两船随后进入交叉甚至对遇角度,仍按追越处理。
若先判对遇,"从正后方赶上同向慢船、逼近到正前方"会被误判成对遇 (相对方位接近 0)。代码里顺序固定为 追越 → 对遇 → 交叉。
加权平均会把"一个指标极度危险 + 其余安全"稀释成中等风险。 在避碰场景里这是危险的:DCPA 接近 0 意味着若都不转向就必然碰撞, 无论还剩多少时间,都必须开始行动。
所以除 DCPA+TCPA 联合判定外,还有一条独立规则: DCPA < 0.10 NM 时,等级下限是 WARNING(而非 CAUTION 的"保持关注")。
会遇局面在现实中是渐变的。几何判定落在扇区边界附近时,
confidence 会下降到阈值以下,needs_review 变 True,
工具返回里明确提示"建议人工确认"。
不假装确定是决策支持系统的基本要求。
Linux 服务器 / Docker / CI 环境普遍没有中文字体, matplotlib 会把中文渲染成方框并刷一屏警告。
viz.py 启动时探测一次,没有中文字体就把图上中文换成英文标签。
这不是配置问题,是"目标机器上可能没有字体"这个客观事实。
| 维度 | 本项目 | CORALL (MIT, ★36) |
|---|---|---|
| CPA 计算 | 解析解,与采样率无关 | 帧间差分,依赖 ts |
| 会遇分类 | 追越/对遇/交叉 + 让路责任 + 置信度 | 硬编码阈值,无置信度 |
| 动作可行性 | 强制检查回转时间 | 无 |
| 数值计算 | 完全由代码完成 | LLM 参与部分判断 |
| 评测 | 6 标准场景 + 65 项单测 | 22 个 Imazu 场景 |
| 无 Key 演示 | 支持(离线规划器) | 不支持 |
| 海况/海图 | 预留接入位 | 无 |
CORALL 的优点(22 个 Imazu 场景覆盖更全)值得学习, 本项目目前只实现了几何定义明确的 6 个场景。
诚实列出,这些是真实短板:
- 没有真实 AIS 数据接入。目前用解析场景,数据层是模拟的。
(
requirements.txt里预留了接入位,Open-Meteo Marine 海况 API 已实测可用) - 没有海图/浅水区约束。航线规划模块尚未实现。
- 没有船舶动力学模型。当前是运动学直线外推, 不含操纵性滞后、惯性、风流压差。
- 没有 Web 界面。只有 CLI 与静态图。
- Imazu 22 场景只实现了 6 个,未做完整基准对齐。
- 没有真人航行员的规则审核。阈值与扇区是工程约定,非法规原文。
- 《1972 年国际海上避碰规则》(COLREGs),规则 13/14/15/16/17
- Imazu, K. (1987). A study on the collision avoidance action of ships — 22 个标准测试场景,本领域通用评测基准
Klins101/CORALL(MIT) — 同领域 LLM 项目,本项目的对比对象nasa-jpl/rosa— 工具禁用(blacklist)机制借鉴来源
MIT