规划大模型

使用准备

开发环境准备

能够提供环境状态消息，BDDL格式或Graph格式或当前场景图像

资源准备

接入前，需先申请模型试用服务，获取Access Token
如需大规模调用，可前往腾讯云购买算力资源

开发流程

API调用

a. 初始化：用户调用接口 发送机器人自身能力、VLA能力描述，启动规划框架
b. 提供环境信息：用户按照接口 提供机器人的自身信息/环境信息，其中BDDL或者Graph信息至少提供一种
c. 指令输入：用户输入文本指令，消息格式按照接口人机交互
d. 回复接收：用户接收机器人的文字回复，消息格式按照接口人机交互
e. 动作执行：
- 用户接收规划的动作序列后执行并反馈执行结果
- 动作序列输出格式按照接口规划决策并输出定义
- 当动作序列全部成功执行完成或执行过程中发生错误导致任务中断时，使用接口行动反馈将行动反馈信息传送给规划框架
f. 动作中断：
- 当用户在任务执行中输入指令/或规划框架主动响应时，会触发规划框架发出动作中断消息，消息格式为规划决策并输出
- 用户接收新的动作序列，并将前序动作执行结果按照接口行动反馈

API介绍

云API

规划大模型云API文档交互方式：需要双向通信（使用websocket连接）
地址wss://algo.tairos.tencent.com/keepalive

websocket建连时的http_header参数
-H "Content-Type: application/json"
-H "Authorization: Bearer $PLATFORM_API_KEY"
-H "Robot-Id: $robot-id"
-H "Module: $module"    #这里module填planning
-H "Model-Id: $model-id"   # 同个module有多个模型可选时填选中的，目前不用填

初始化机器人自身能力、VLA能力描述

可选请求，如果用户建连后没发送这条消息，则使用以前传入并存储下来的init信息，之前未传过需要报错；用户多次调用init消息后，后一条init信息会替换之前init信息

元动作描述方式：

client->server
send:
{
    "msg_type":"init",
    "msg_id": "1",    #调用方填入，回复方在回复的msg填入一样的id，标识是对于该条消息的回复（string，携带 uuid）
    "content":{
        # robot_desc 和 vla_desc 至少填一个
        "name": str,
        "scene": str, # 可选，当前场景 WAIC/House1/WAIC_perception/House1_perception
        "robot_desc": [ # 按照function_call格式给出
        {
            "type": "function",
            "function": {
                "name": "navigate", # 能力名
                "description": "Move towards a specified object",
                "parameters": {
                    "type": "object",
                    "properties": {    # 能力属性
                        "object": {
                            "type": "string",
                            "description": "The name of the specific object in the environment to navigate towards (e.g., 'door.n.01_1', 'table.n.01_1', 'window.n.01_1').",
                        },
                    },
                    "required": ["object"], # 必填属性
                },
            },
        }
    ],
        "vla_desc": JSON, # 可选，JSON格式数据描述 VLA 可具备的执行指令集，包含指令样例/执行条件/执行结果
        "preference": "", # 可选，用户对于执行动作顺序的偏好等
        "work_mode" : "WITH_PERCEPTION" | "STAND_ALONE"
    }
}
&nbsp;
reply:
{
    "msg_type":"init_reply",
    "msg": "success",
    "msg_id": "1",
    "code": 0
}

接收本体自身信息/环境信息（主动调用或者被动调用）

主动调用：

发送消息给本体，让本体提供信息（必须回复，不然无法做规划）

被动接收：

本体主动按固定的频率（10秒/次）发送环境信息（可选，定时发送环境信息有助于提高规划效果）

主动调用：
发送消息给本体，让本体提供信息（必须回复，不然无法做规划）
server->client:
send:
{
    "msg_type":"get_env",
    "msg_id": "1",    # 调用方填入，回复方在回复的msg填入一样的id，标识是对于该条消息的回复
    "content": {
        "condition":{}
    }
}
reply:
{
    "msg_type":"get_env_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success",
    "content":{
        "timestamp": 0, # client秒级时间戳
        # bddl与graph至少提供一种
        "bddl": str,    # 可选， 需(:objects ) (:init ) 的bddl格式信息，定义可参考 https://github.com/StanfordVL/bddl
        "graph":{},            # 可选，同感知的graph定义
        "agent_state": {       # 可选，agent自身状态信息
            "grasp": list[str],      # 可选，agent手抓物品
            "face": list[str],       # 可选，agent第一视角感知的物品
            "near": list[str],       # 可选，agent附近的物品
            "stand": str             # 可选，当前所在点位
        },
        "image": []    # 当前图像信息，格式：Base64编码
    }
}


被动接收：
本体主动按固定的频率（暂定10秒/次）发送环境信息（可选，定时发送环境信息有助于提高规划效果）
client->server:
send:
{
    "msg_type":"send_env",
    "msg_id": "1",      # 调用方填入，回复方在回复的msg填入一样的id，标识是对于该条消息的回复
    "content": {
        "timestamp": 0, # client秒级时间戳
        # bddl与graph至少提供一种
        "bddl": str,    # 可选， 需(:objects ) (:init ) 的bddl格式信息，定义可参考 https://github.com/StanfordVL/bddl
        "graph":{},            # 可选，同感知的graph定义  [{},{}]
        "agent_state": {       # 可选，agent自身状态信息
            "grasp": list[str],      # 可选，agent手抓物品
            "face": list[str],       # 可选，agent第一视角感知的物品
            "near": list[str],       # 可选，agent附近的物品
            "stand": str             # 可选，当前所在点位

        },
        "image": []    # 当前图像信息，格式：Base64编码
    }
}
reply:
{
    "msg_type":"send_env_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success"
}

人机交互

人类输入（必选）+当前本体看到的image（必选）

client->server
send:
{
  "msg_type": "human_interact",
  "msg_id": "1",
  "content": {
        "text": "消息内容",
        "human_id": str,       # 可选。交互的人的id，按场景需求是否需要区分交互人
        "instruction_id": "1", # 用户输入指令的 instruction_id，string 格式

        "timestamp": 0, # client秒级时间戳
  }
}
reply:
{
    "msg_type":"human_interact_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success"
}

server->client
send:
{
  "msg_type": "human_interact",
  "msg_id": "1",
  "content": {
        "timestamp": 0, # client秒级时间戳
        "instruction_id": "1", # 该回复对应的用户输入指令的 instruction_id，string 格式

        "text": "消息内容",
        "human_id": str,       # 可选。交互的人的id，按场景需求是否需要区分交互人. 系统消息见[特殊交互信息]
  }
}
reply:
{
    "msg_type":"human_interact_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success"
}

规划决策并输出

动作序列规划（细节动作）

server->client
send:
{
    "msg_type": "actions",
    "msg_id": "1",
    "content": {
        # 打断信号或执行动作序列。
        # 打断信号：interrupt为True，actions为空列表
        # 执行动作序列：interrupt为False，actions为动作列表
        "actions": list, # 规划的动作序列，例：[{"action_id":1, "action": "speak(我先把锅放到炉子上。)"},  ...]
        "interrupt": bool, # True 表示打断当前任务序列，此时需调用接口[行动反馈]返回执行情况。
        "instruction_id": "1", # 用户输入指令的 instruction_id，string 格式
    }
}
reply:
{
    "msg_type":"actions_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success",
}

行动反馈

在执行action序列遇到执行错误，或全部执行完成后，需要本体端返回执行结果以及当前的自身状态/环境状态，

client->server
send:
{
    "msg_type": "action_feedback",
    "msg_id": "1",
    "content": {
        "status": "success/error/interrupt", # 执行结果,  当中断的时候，返回 interrupt
        "last_action": dict, # 最后执行的动作信息 {"action_id":1, "action": "speak(我先把锅放到炉子上。)"}
        "error_message": str, # 错误消息

        # 本体执行完指令之后将执行后的环境感知结果、自身状态回复回来，规划用于确认效果和下一步动作规划
        # bddl与graph至少提供一种
        "bddl": str,   # 可选， 需(:objects ) (:init ) 的bddl格式信息，定义可参考 https://github.com/StanfordVL/bddl
        "graph":{},            # 可选，同感知的graph定义
        "agent_state": {        # 可选，agent自身状态信息
            "grasp": list[str],      # 可选，agent手抓物品
            "face": list[str],       # 可选，agent第一视角感知的物品
            "near": list[str],       # 可选，agent附近的物品
            "stand": str             # 可选，当前所在点位
        },
        "image": []    # 当前图像信息，格式：Base64编码
    }
}
reply:
{
    "msg_type":"action_feedback_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success"
}

心跳保活

用户每隔3分钟需要发送一次心跳消息，声明自己处于使用规划的状态，连续n隔周期没有发送心跳，则server端主动结束规划任务

client->server
send:
{
  "msg_type": "heartbeat",
  "msg_id": "1",
  "content": {
      "message": "消息内容", # 预留字段，可用于传递一些信息，具体信息待扩展
  }
}
reply:
{
    "msg_type":"heartbeat_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success"
}

主动结束规划任务

websocket成功建连后即表示session的开始，结束可以通过server或client端主动结束、或session超时退出（用户侧无消息发送一段时间后触发超时）

client->server  or server->client
send:
{
    "msg_type": "end",
    "msg_id": "1",
    "content": {
        "reason": "end|error|..."
    }
}
reply: (主调方等待一段时间后退出，即使没收到reply消息)
{
    "msg_type":"end_reply",
    "msg_id": "1",
    "code": 0,
    "msg": "success"
}

特殊交互信息

每次状态更新，server 都主动发给 client

server->client
send:
{
  "msg_type": "human_interact",
  "msg_id": "1",
  "content": {
        "text": "{'plan_task': ['plan_task', 'status'],'mid_task': [['mid_task1', 'status'], ['mid_task2', 'status'],['mid_task3', 'status']]}" # status 包含：pending, running, interrupted, success,failed，现在暂时没有interrupted。特殊内容：Instruction Processed,指令处理结束。
        "human_id": "SYSTEM_",            # 可选。交互的人的id，按场景需求是否需要区分交互人
        "timestamp": 0, # client秒级时间戳,
        "instruction_id": str # 透传的id返来
  }
}

SYSTEM_TASK_STATUS
例子：
{'plan_task': ['Put all the fruits in the fridge, then throw the bread into the trash bin.', 'running'], 'mid_task': [['Pick up the apple.n.01_1 from the countertop.n.01_1.', 'running'], ['Navigate to the fridge.n.01_1 and place the apple.n.01_1 inside.', 'pending'], ['Return to the countertop.n.01_1 and pick up the bread.n.01_1.', 'pending'], ['Navigate to the garbagecan.n.01_1 and dispose of the bread.n.01_1.', 'pending']]}

SYSTEM_INSTRUCTION ——>
text: Instruction Processed # server->client 指令处理结束
text: Instruction Interrupted # client->server 打断

SYSTEM_TOOL

reply中的error表示

reply:
{
    "msg_type":"xxx_reply",
    "msg_id": "1",
    "msg":"xxx", # 错误原因
    "code": 0 # 错误类型 0 成功， 大于0业务错误，无法完成；小于0是参数/系统错误。
}

错误信息码：
-1 未知消息类型
0 成功
1 客户端未初始化
2 处理信息时出现错误

使用准备​

开发环境准备​

资源准备​

开发流程​

API调用​

API介绍​

云API​

初始化机器人自身能力、VLA能力描述​

接收本体自身信息/环境信息（主动调用或者被动调用）​

人机交互​

规划决策并输出​

行动反馈​

心跳保活​

主动结束规划任务​

特殊交互信息​

reply中的error表示​