Skip to content

About

LLM-based maritime navigation decision agent: CPA/TCPA, COLREGs encounter classification, maneuver feasibility. Deterministic core + LLM reasoning layer.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

海事航行决策 Agent

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 下根本来不及。


核心设计:LLM 不参与数值计算

                驾驶员
                  │
                  ▼
        ┌──────────────────┐
        │ 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            端到端冒烟测试

六项关键技术决策

1. CPA 用解析解,不用帧间差分

同领域开源实现(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 用例都是纸笔能算出来的。

2. 追越判定用对称定义,不靠拍脑袋

规则 13 说的是「追越船让路」,不是「遇到追越局面本船让路」。 常见错误是把两者混淆。

所以分别判断:

目标在本船船尾扇区  -> 目标追越本船 -> 本船直航(stand_on)
本船在目标船尾扇区  -> 本船追越目标 -> 本船让路(give_way)

两种情形都有独立的测试用例(overtaking 与 being_overtaken), 只测一种无法证明实现真的区分了方向。

3. 追越判定必须优先于对遇

规则 13(e) 明确:追越局面在追越过程中始终存在, 即使两船随后进入交叉甚至对遇角度,仍按追越处理。

若先判对遇,"从正后方赶上同向慢船、逼近到正前方"会被误判成对遇 (相对方位接近 0)。代码里顺序固定为 追越 → 对遇 → 交叉。

4. 风险分级用「多指标取最严」,不用加权平均

加权平均会把"一个指标极度危险 + 其余安全"稀释成中等风险。 在避碰场景里这是危险的:DCPA 接近 0 意味着若都不转向就必然碰撞, 无论还剩多少时间,都必须开始行动。

所以除 DCPA+TCPA 联合判定外,还有一条独立规则: DCPA < 0.10 NM 时,等级下限是 WARNING(而非 CAUTION 的"保持关注")。

5. 扇区边界要给低置信度

会遇局面在现实中是渐变的。几何判定落在扇区边界附近时, confidence 会下降到阈值以下,needs_review 变 True, 工具返回里明确提示"建议人工确认"。

不假装确定是决策支持系统的基本要求。

6. 中文字体缺失时体面降级

Linux 服务器 / Docker / CI 环境普遍没有中文字体, matplotlib 会把中文渲染成方框并刷一屏警告。

viz.py 启动时探测一次,没有中文字体就把图上中文换成英文标签。 这不是配置问题,是"目标机器上可能没有字体"这个客观事实。


与同类项目的对比

维度 本项目 CORALL (MIT, ★36)
CPA 计算 解析解,与采样率无关 帧间差分,依赖 ts
会遇分类 追越/对遇/交叉 + 让路责任 + 置信度 硬编码阈值,无置信度
动作可行性 强制检查回转时间 无
数值计算 完全由代码完成 LLM 参与部分判断
评测 6 标准场景 + 65 项单测 22 个 Imazu 场景
无 Key 演示 支持(离线规划器) 不支持
海况/海图 预留接入位 无

CORALL 的优点(22 个 Imazu 场景覆盖更全)值得学习, 本项目目前只实现了几何定义明确的 6 个场景。


已知不足

诚实列出,这些是真实短板:

  1. 没有真实 AIS 数据接入。目前用解析场景,数据层是模拟的。 (requirements.txt 里预留了接入位,Open-Meteo Marine 海况 API 已实测可用)
  2. 没有海图/浅水区约束。航线规划模块尚未实现。
  3. 没有船舶动力学模型。当前是运动学直线外推, 不含操纵性滞后、惯性、风流压差。
  4. 没有 Web 界面。只有 CLI 与静态图。
  5. Imazu 22 场景只实现了 6 个,未做完整基准对齐。
  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

About

LLM-based maritime navigation decision agent: CPA/TCPA, COLREGs encounter classification, maneuver feasibility. Deterministic core + LLM reasoning layer.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages