开源 | EmbodiedAgentsSys：第一个从感知到执行的具身智能Agent全栈框架

铮铭

551人浏览 · 2026-03-18 23:31:19

铮铭 · 2026-03-18 23:31:19 发布

项目地址：https://github.com/hzm8341/EmbodiedAgentsSys

欢迎 Star ⭐ / Fork / 提 Issue，一起把这个框架做好。

一、为什么做这个项目？

做了一年具身智能，踩了很多坑。

在自动驾驶干了将近10年，转来具身智能之后发现：这个行业有大量优秀的模型，但严重缺乏把这些模型串联起来的工程框架。

大家都在单点突破：

搞感知的在卷 VLA 模型
搞控制的在卷轨迹规划
搞交互的在搞语音或者遥操

但真实的机器人任务需要的是一个完整的闭环：看到 → 理解 → 决策 → 执行，这四步缺一不可。

EmbodiedAgentsSys 就是我在这个背景下做的一个尝试——一个覆盖感知、认知、控制、交互四层的具身智能 Agent 框架，基于 ROS2 原生构建，纯 Python，生产可用。

二、框架整体架构

┌─────────────────────────────────────────────────┐
│              交互层  Interaction                  │
│   语音输入(Whisper) │ 语音输出(TTS) │ VR遥操      │
├─────────────────────────────────────────────────┤
│              认知决策层  Cognition                │
│   LLM │ MLLM(Qwen2-VL) │ RAG │ 语义路由          │
│   时空语义记忆(ChromaDB) │ LLM代码生成控制         │
├─────────────────────────────────────────────────┤
│              感知层  Perception                   │
│   目标检测 │ 3D位姿估计 │ 深度感知 │ 工件分类      │
├─────────────────────────────────────────────────┤
│              执行控制层  Execution                │
│   机械臂运动技能 │ 夹爪技能 │ 力控技能 │ 抓取规划  │
├─────────────────────────────────────────────────┤
│              基础设施层  Infrastructure           │
│         ROS2 原生 │ 事件驱动 │ 异步多组件编排       │
└─────────────────────────────────────────────────┘

每一层都是独立模块，可以单独使用，也可以自由组合。

三、核心功能详解

3.1 语音示教 Agent

用自然语言直接控制机械臂。说人话，机器人动。

agent = VoiceTeachingAgent()

# 支持多层级指令
await agent.execute("向前20厘米")         # L1：基础运动
await agent.execute("把夹爪打开")         # L2：复合动作
await agent.execute("把零件拿到拍照位置")  # L3：任务级指令

框架自动完成：语义解析 → 意图识别 → 技能调度 → 机械臂执行 的完整链路。

3.2 LLM 代码生成控制机器人

受 ChatGPT for Robotics 启发，用户用自然语言描述任务，LLM 自动生成可执行的机械臂控制代码，内置安全验证器过滤高风险操作。

skill = AgxArmCodeGenSkill()
result = await skill.execute("让机械臂画一个圆形轨迹", robot_type="nero")

# 自动生成完整 Python 控制脚本
# 包含连接、使能、运动、等待的标准安全流程
# 自动校验并过滤 move_mit 等高风险操作
print(result.output["generated_code"])

3.3 多模态感知 + RAG 问答

集成 Qwen2-VL 多模态理解，结合 ChromaDB 向量检索，机器人可以看图说话并检索历史知识。

qwen_vl = OllamaModel(name="qwen_vl", checkpoint="qwen2.5vl:latest")
qwen_client = OllamaClient(qwen_vl)

mllm = MLLM(
    inputs=[query_topic, image_topic, detections_topic],
    outputs=[answer_topic],
    model_client=qwen_client,
    trigger=query_topic,
)

mllm.set_component_prompt(template="""
    你是一个工厂机器人。
    当前画面中有：{{ detections }}。
    请回答：{{ text0 }}
""")

3.4 时空语义记忆地图

机器人不只是"看"，还能"记住"。MapEncoding 组件实现分层时空记忆：

动态层：跟踪移动物体，带时序变化
静态层：记录空间语义（这里是仓储区/这里是质检台）
语义检索：基于 ChromaDB 实现自然语言位置查询（"电池托盘在哪里？"）

layer1 = MapLayer(subscribes_to=detections_topic, temporal_change=True)
layer2 = MapLayer(subscribes_to=room_type_topic, resolution_multiple=3)

map_encoder = MapEncoding(
    layers=[layer1, layer2],
    position=odom_topic,
    db_client=chroma_client,
    trigger=15.0,
)

3.5 语义路由：一句话自动分发到正确的 Agent

# 根据用户意图，自动路由到不同处理组件
goto_route = Route(
    routes_to=goto_query,
    samples=["去厨房", "去门口", "帮我拿个杯子"]
)
llm_route = Route(
    routes_to=llm_query,
    samples=["法国首都是哪里", "今天天气怎么样"]
)
mllm_route = Route(
    routes_to=mllm_query,
    samples=["你看到什么了", "前面有什么东西"]
)

router = SemanticRouter(
    inputs=[query_topic],
    routes=[llm_route, goto_route, mllm_route],
    default_route=llm_route,
    db_client=chroma_client,
)

四、支持的模型和工具链

类别	支持的模型 / 工具
多模态理解	Qwen2-VL、GenericMLLM（OpenAI兼容）
语言模型	Llama3、Qwen2.5、Ollama全系、RoboBrain2
VLA 策略	LeRobot（ACT、Diffusion Policy等）
语音识别	Whisper（OpenAI）
语音合成	SpeechT5、Bark、MeloTTS
目标检测	DINO-4scale、mmdet系列
向量数据库	ChromaDB
机器人中间件	ROS2 Humble+（原生支持）
边缘部署	NVIDIA Orin、Thor

五、快速上手

环境要求

Python 3.8+
ROS2 Humble 或以上
CUDA（可选，推荐用于本地模型推理）

安装

git clone https://github.com/hzm8341/EmbodiedAgentsSys.git
cd EmbodiedAgentsSys
pip install -r requirements.txt

运行语音示教 Demo

python examples/voice_teaching_agent.py

运行完整多模态 Agent

# 先启动 Ollama 并拉取模型
ollama pull qwen2.5vl:latest

python examples/complete_agent.py

六、目录结构

EmbodiedAgentsSys/
├── agents/                     # 核心框架
│   ├── components/             # 组件（LLM/MLLM/VLA/Vision/STT/TTS）
│   ├── clients/                # 模型客户端（Ollama/LeRobot/RoboML）
│   └── utils/                  # 工具函数
├── skills/                     # 技能库
│   ├── arm_control/            # 机械臂运动 / 夹爪 / 关节技能
│   ├── manipulation/           # 抓取规划 / 力控技能
│   ├── vision/                 # 视觉感知技能
│   ├── teaching/               # 示教录制与技能生成
│   └── agx_arm_codegen/        # LLM 代码生成技能
├── examples/                   # 完整可运行示例
│   ├── complete_agent.py       # 完整多模态 Agent
│   ├── voice_teaching_agent.py # 语音示教 Agent
│   ├── semantic_router.py      # 语义路由示例
│   └── go_to_x.py              # 导航示例
└── msg/                        # ROS2 自定义消息定义