起降工具已实现:模型可调用 {"tool": "takeoff"} 或 {"tool": "land"},无需参数。
工具复用环境自动起降逻辑,并在完成后同步 agent 与无人机状态机。
调用方法及完成判据见 tools/README.md。
斜面/墙面脱附起飞使用无参数 {"tool":"aggressive_takeoff"}:仅 ON_GROUND、绝对 pitch 为 15~90° 且已有成功吸附的名义比推力记录时允许调用。
规划 2 s minimum-snap 轨迹,沿起飞初始机体 +Z 位移 h=1+sqrt((abs(pitch_deg)-15)/75) 米;
起终点速度和终点加速度为零,起始比推力与初始加速度联合优化。规划成功后释放四吸盘,稳定悬停后返回。
基于现有 MuJoCo 无人机环境,逐步搭建本地 VLM 驱动的具身 agent。 当前提供本地 Ministral 3B 和 DeepSeek API 推理、起降与航点工具、agent 与无人机状态机。 已实现独立 Environment Runtime、模型 Agent Runner 和 PySide6 桌面界面。
中文总体架构、两个状态机及模型通信格式见 工程架构图。
模型可调用 {"tool":"detect_planes"} 只读观测平面:本地使用默认640×480同步RGB-D,
返回世界坐标几何和真实 annotated_rgb 附件。Agent 设置可调整检测尺寸及保存标注图开关(默认开启,artifacts/planes)。
安装 python -m pip install -r requirements-planes.txt;示例与限制见 平面检测说明。
独立重放界面:python replay_app.py logs/agent_log_11091541_agperch.jsonl --map map1。
从日志读取全部模型输入输出与工具决策,无需加载模型;工具在 MuJoCo 中重新执行,支持工具结束后暂停及继续。
操作方式与可恢复范围见 日志重放说明。
现有 8 张地图,可在前端顶部的“仿真地图”下拉框选择并点击“重载环境”,
或使用 python app.py --map map3 指定初始地图。重载保留模型,重置无人机与仿真时间并清空模型对话历史;
任务运行中需先终止并等待退出。布局、材质及扩展方法见 地图说明。
首次安装完整环境(Linux,包含 CUDA 12.8 的本地模型后端):
conda env create -f requirement.yaml该文件参照当前 mm_planner 的核心依赖版本编写,不包含本机环境绝对路径。
若已有同名环境,可用 conda env create -n mm_planner_new -f requirement.yaml 创建新环境,
或用 conda env update -n mm_planner -f requirement.yaml 更新现有环境。
环境安装不包含模型权重、API Key 或 NVIDIA 驱动;首次使用本地模型还需准备 Hugging Face
模型缓存并运行下文的 scripts/cache_fp8_kernel.py。仅使用 DeepSeek 不需要本地模型权重。
桌面显示和 EGL 渲染依赖主机可用的图形驱动;此配置针对当前 Linux 工程。
conda activate mm_planner
python app.py点击“加载模型”,有手柄时将 Axis4 切为1后发送任务;启动时未检测到手柄则自动授权 Agent。
自动授权只开放任务输入,不自动推理或起飞;可用界面的“终止本轮任务”停止任务。
未授权的消息不会发送给模型;
OOM 等运行错误会显示在对话框。左侧用 ◀ / ▶ 切换第一视角和世界视角,模型始终使用第一视角。
世界视角下可左键旋转、右键平移、滚轮缩放、Ctrl+滚轮调整 FOV,双击或点击按钮重置视角。
界面预览默认 1280×960,发送给模型的第一视角默认保持 224×224;两者可独立配置。
预览标签还可查看第一视角深度;Agent 设置可开启发送深度图并选择分辨率,默认 56×56。
也可用 python app.py --backend deepseek --depth --depth-size 56 启动。
详细架构、参数与验证方法见 runtime/README.md。
DeepSeek API 可通过界面顶部后端选择启用,也可直接启动:
python app.py --backend deepseek在界面填写 API Key 或预先设置 DEEPSEEK_API_KEY 环境变量,点击“配置 API”。
默认模型 deepseek-flash,支持第一视角图片、思考模式和 JSON Output;默认生成上限 4096 token。
该后端会将任务、对话历史、状态和第一视角图片发送至所配置的 API。
详细配置、取消行为及测试范围见 agent/DEEPSEEK.md。
无人机始终使用位置控制。Axis4=1 授权 agent,屏蔽其他遥控器输入;
Axis4 从1切到0时终止 agent(END),取消轨迹/自动起降并进入 HOVERING,恢复手动控制。
HOVERING 允许摇杆控制运动;Axis7 负责手动起降并同步飞行状态。
手动模式下,ON_GROUND 且未执行起飞时,Axis6 从 <=0 切为 >0 启动 CRAWLING;
从 >0 切为 <=0 请求停止。停止时等步态进入第一阶段,保持一组对角吸盘吸附,
将腿平滑回到中立位,再恢复四个吸盘吸附并等待一个阶段,最后返回 ON_GROUND。
爬行及收尾期间关闭旋翼、禁止起飞;Axis4 请求接管时先完成收尾,再授权 Agent。
步态阶段时长为 CRAWL_STAGE_DURATION=0.8 秒,摆角为 CRAWL_SERVO_AMPLITUDE=0.3 弧度。
CRAWLING 与 ON_GROUND 互相切换;吸盘开关由独立的 sucker_states 四元布尔向量维护,顺序为左前、左后、右后、右前,可在任何运动状态和控制模式下修改。
手动爬行停止后保持吸附;下次起飞前自动释放吸盘。Agent 接管后不读取 Axis6。
Agent 可调用 {"tool":"crawl","steps":2,"attached":true}:一个四阶段周期算一步,
仅允许 ON_GROUND;完成后仍为 ON_GROUND,按 attached 设置四个吸盘开关。
详见 爬行工具。
大角度吸附工具示例:{"tool":"aggressive_perch","position":[2,0,1.5],"yaw":0,"wall_angle_deg":90,"time":2}。
仅允许悬停调用,position 表示表面接触中心;工具开启四吸盘、用 minimum-snap 规划法向接触,
采用有界优化末端比推力(8~20 m/s²),限制 time≤2s、平均法向速度≥1m/s,并施加参考 Z≥0.25m。
确认稳定接触后进入 ON_GROUND(表面支撑)并停桨,四个吸盘开关保持 true。角度、法线及超时约定见 工具说明。
原 FLYING 状态已改名为 FLY_AGENT,专用于授权后的 agent 轨迹执行;Axis5 不再使用。
MMUAVEnv.set_model_stop_callback() 已接入 runner 的生成取消事件。
完整状态规则和入口见 env/README.md。
conda activate mm_planner
python -m pip install -r requirements-ministral.txt
# 首次部署需联网缓存 FP8 CUDA 算子;之后测试完全离线。
python scripts/cache_fp8_kernel.py
python scripts/test_ministral.py默认复用 Hugging Face 本地缓存中的
mistralai/Ministral-3-3B-Instruct-2512,不下载模型权重,也不依赖 foundation 环境。
模型加载使用 local_files_only=True、trust_remote_code=False、
原生 FP8 权重、BF16 非量化模块以及 SDPA attention;需要可用的 CUDA GPU,
计算能力至少 8.9。本机已有 PyTorch 2.10.0+cu128,依赖文件不重新安装 PyTorch。
FP8 算子固定到 v4 的 commit 8c178950e8710e26a2210e4e909cd02dc16c8715;
缓存脚本下载整个小型源码快照,以满足 huggingface-hub 的离线完整性检查。
后端为固定的 Transformers 5.18 设置对应算子映射;升级依赖时需重新验证此兼容设置。
可以显式指定已有模型目录:
python scripts/test_ministral.py --model-path /path/to/local/snapshot测试结果写入 artifacts/ministral_smoke.json,相机图像写入
artifacts/mujoco_fpv.png。测试失败返回非零退出码。四项测试分别检查:
- 文本算术生成是否得到
5。 - NWU 坐标下向北移动 0.5 米,经过单层 Markdown 包装清理和 JSON 校验后,
是否得到目标
[0.5, 0, 1]。 - 红色图像输入是否识别为
red。 - 从现有场景渲染
fpv_camera图像并完成 VLM 描述。
最后一项只检查渲染与视觉推理链路,不衡量描述准确率、避障或飞行成功率。 报告中的生成耗时包括 prefill 和 decode;首个请求可能包含 Triton 编译开销。 本机测试中,首个请求的算子编译/调优约需 50 秒,后续相机描述请求约 2.5 秒。 仿真步长为 0.002 秒(500 Hz),模型适合低频规划层。
最初仅提示 NWU means x=north, y=west, z=up 时,模型输出了 Markdown 代码块,
并将北向位移误写为负 Y。原始失败结果保留在 artifacts/ministral_baseline.json。
当前测试明确约束北向增加 X、西向增加 Y,以及纯 JSON 输出;
即使单次样例通过,也不能据此推断模型具备可靠的导航或避障能力。
实际模型仍可能添加代码块。agent/waypoint.py 只允许清理一个完整的 JSON 代码块,
然后校验字段、坐标数量和有限数值;不从混杂文本中任意提取对象。
该校验未包含场景边界、碰撞、速度和轨迹可行性,尚不能直接执行目标。
最终 ministral_smoke.json 的航点项是在实际 GPU 输出上重新执行解析器校验;
只修改解析器后没有重复模型推理,报告的 validation 字段记录了这一点。
未清理包装时的严格 JSON 检查结果保留在 artifacts/ministral_strict_json.json。
observations/ 提供可替换的观测模块:当前位置、姿态(wxyz 四元数和弧度制 RPY)、
飞行状态、从启动起的仿真时间,以及默认 224×224 的第一视角 RGB。
可配置分辨率、相机,并追加传感器或替换整套 provider。
packet.to_json() 输出带 PNG/base64 的完整 JSON;
backend.generate(**packet.to_model_inputs()) 将状态 JSON 与 PIL 图像传给当前本地模型。
collect_for_agent(provider, environment) 负责采集及 OBSERVATION → THINK 的状态推进,
采集时失去 Axis4 授权或发生轮次切换会丢弃观测。
完整字段、调用及扩展方式见 observations/README.md。
from PIL import Image
from agent.ministral import MinistralBackend
backend = MinistralBackend() # 只加载一次
result = backend.generate("当前画面有哪些障碍物?", image=Image.open("artifacts/mujoco_fpv.png"))
print(result["text"])agent/ministral.py 同时支持纯文本和单图输入。默认图像最长边 448 像素,
可以通过 MinistralBackend(image_size=...) 调整。缓存的模型快照缺少
preprocessor_config.json,因此从模型配置读取 14 像素 patch 和 2 倍 spatial merge,
显式构造 PixtralProcessor,避免使用不匹配的默认 patch 设置。
模型资料:官方模型卡。
env/scene.xml:场景,包含mmuav.xml和assets/map1.xml。env/mmuav_env.py:手柄输入、位置控制回调、控制权切换与起降/轨迹入口。env/controller/:SE3 位置控制、姿态控制、角速度 PID、滤波和电机混控。env/trajectory_optimizer/:将位置/yaw 航点拟合为平滑分段多项式。
世界坐标使用 NWU:x 北、y 西、z 上;yaw 使用弧度。
仿真状态可从 d.qpos[:3] 和 d.qvel[:3] 读取,相机包括
fpv_camera、fpv_camera_far、world_camera。
未来闭环可以使用以下路径:
任务 + 状态 + 相机图像
→ Ministral 低频规划
→ JSON 校验 / 航点约束
→ PolynomialTrajectoryOptimizer
→ set_planner_target_provider
→ SE3 / Rate PID / Mixer
→ MuJoCo stepping
→ 新观测与任务反馈
控制接口说明:
set_planner_target_provider(provider)仅在位置模式、且自动起降没有接管时生效。 环境固定使用位置控制,provider 只在 Axis4 授权 agent 后生效。- provider 接收
m, d, current_rotation, omega, dt,返回对象需包含position, velocity, acceleration, yaw;可选yaw_rate,但当前代码会直接读取omega。MMUAVEnv.follow_trajectory()已适配轨迹状态及 body-frame yaw 前馈。 - 模型推理应在规划线程/进程执行;MuJoCo 控制回调只读取已生成的轨迹, Environment Runtime 持续推进仿真和处理 Axis4,模型 runner 独立运行,不直接调用 env.step。
另:轨迹 README 中 yaw 的 C4/四阶目标描述与当前配置不一致;
实际 config_trajectory_optimizer.py 使用 yaw 连续阶数 2、目标导数阶数 2。