# 智能体调试
#### 智能体调试说明
- 智能体调试时，模型服务需处于运行中状态，机器人需在线。
- 同一本体，支持切换不同的模型服务进行技能调试，方便您选择效果更优的模型服务。
- 部分模型仅支持执行固定的模型技能，不支持泛化技能；其他模型可执行泛化技能，您可根据需要输入需要执行的Prompt，验证模型的泛化性。
 
#### 部署模型服务
1. 在左侧导航选择"运行管理 \> 模型部署"，进入模型部署页面。
2. 单击"部署模型服务"，进入部署模型服务页面。
3. 输入基础信息，选择**部署SO101**可使用的模型，并选择资源配置。
4. 完成后单击"立即部署"，在模型部署页面可以单击![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002744091483.png)，实时刷新模型部署进展，并等待模型服务部署完成。
 
#### 调试模型技能
1. 在左侧导航选择"运行管理 \> 机器人"，进入机器人页面。
2. 在机器人列表，选择**在线**机器人，单击对应的"智能体调试"，进入"智能体调试"页面。
3. 单击"选择模型技能"，选择处于**运行中**的模型服务、模型技能，单击"确定"。
4. 在智能体调试页面，输入机器人执行Prompt或者保持默认技能，单击![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002714332582.png "点击放大")，开始技能调试。
   
   模型推理的默认步数为60 steps。
   如果已经达到最大推理的步数，但实际任务并未完成，您可重新发送Prompt，会重新执行任务。
   在**参数配置** 中适当调大**技能最大推理步数** 。该参数调整后仅对该机器人和当前选择的模型服务生效。您还可以在模型的**r2c.json**中修改，该修改对后续部署的推理服务生效。
   
   
 
#### 切换模型服务
在智能体界面底部，可单击模型服务名称，切换其他模型服务来验证模型技能。您可在调试记录中查看两个模型的执行结果。
#### 执行泛化性技能
在选择模型服务和模型技能时，如模型技能中有泛化技能选项，表示该模型支持自定义prompt执行泛化技能。
选择泛化技能后，在输入框中可自定义输入Prompt，验证模型的泛化性。
#### r2c.json配置说明
预置模型、空间资产中类型为感知模型和规划模型均不适用于r2c.json配置，可以直接跳过相关部分。
本章节用于描述r2c.json配置文件的结构和含义。该配置文件定义了机器人观测数据到模型输入、以及模型输出到机器人动作之间的映射关系。您可以根据需要调整r2c.json配置文件。
**方法一：从模型部署页面中配置**
![](https://support.huaweicloud.com/usermanual-cloudrobo/public_sys-resources/note_3.0-zh-cn.png)
r2c.json仅允许部署模型时上传，部署模型后仅可查看。如果需要更改该配置，请重新部署。
1. 在运行管理-模型部署中，可直接上传r2c.json配置。 
   图1模型部署页面   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002744091479.png "点击放大")
   
   
2. 上传后，可直接预览已上传的文件。 
   图2上传成功页面   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002743931509.png "点击放大")
   
   
3. 单击"部署"，即配置成功。如果显示r2c.json不正确，请确保上传的文件内容满足json格式，且符合配置结构要求。 
   图3部署成功页面   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002744091485.png "点击放大")
   
   
**方法二：** **从模型资产所在的OBS中配置**
配置文件位于模型资产所在的OBS目录下。
![](https://support.huaweicloud.com/usermanual-cloudrobo/public_sys-resources/note_3.0-zh-cn.png)
r2c.json仅在部署模型服务时会获取。如果通过OBS更新了r2c.json，已经部署的推理服务不会更新，重新启动也不会更新。因此请在部署模型服务之前，更新OBS中的r2c.json。
1. 在模型资产-模型详情中，复制需要部署的模型服务对应版本的obs路径。 
   图4复制模型资产所在的OBS路径   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002714172612.png "点击放大")
   
   
2. 登录OBS平台，找到对应的桶，并进入到OBS路径。 
   图5进入OBS存储模型路径   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002714172608.png "点击放大")
   
   
3. 单击上传对象，上传r2c.json文件。 
   图6上传文件   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002743931511.png "点击放大")
   
   
**方法三：** **从数据所在的OBS中配置**
配置文件位于数据资产所在的OBS中目录下。
![](https://support.huaweicloud.com/usermanual-cloudrobo/public_sys-resources/note_3.0-zh-cn.png)
r2c.json仅在训练模型终态（训练成功、手动终止、运行失败、任务失败）时获取。如果后续通过OBS更新了r2c.json，已经训练好的模型资产不会更新。因此请在训练模型结束之前，更新数据资产对应的OBS中的r2c.json。
如果数据集不存在r2c.json，而训练的源模型存在，则会在训练模型终态时将源模型的r2c.json复制到训练产物中。
1. 在数据资产-数据详情中，复制需要部署的模型服务对应版本的OBS路径。 
   图7数据资产详情页面   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002714332578.png "点击放大")
   
   
2. 登录OBS平台，找到对应的桶，并进入到OBS路径。 
   图8进入OBS存储模型路径   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002714172610.png "点击放大")
   
   
3. 单击上传对象，上传r2c.json文件。 
   图9上传文件   
   ![](https://support.huaweicloud.com/usermanual-cloudrobo/zh-cn_image_0000002743931507.png "点击放大")
   
   
**配置结构概览**
```
{
    "model_feature_mapping": { 
        "input_features": { ... },
        "output_features": { ... }
    },
    "stop_condition": { ... }
}
```
**顶层字段说明**
| 字段                    | 类型     | 必填 | 说明                                                                                 |
|:---|:---|:---|:---|
| model_feature_mapping | object | 是  | 模型特征映射配置对象                                                                         |
| stop_condition        | object | 否  | 模型执行停止条件配置，如果没有设置，则默认为{"max_iter_num": 100,"max_run_time": 10}，可通过前端修改推理服务的执行停止条件。 |
   
**模型特征映射（model_feature_mapping）**
该对象包含两个子对象：input_features和output_features，分别定义了模型输入和输出的映射规则。
**输入特征（input_features）**
该部分定义了如何将机器人的观测数据映射到模型的输入格式。系统支持三种类型的输入特征：
| 特征类型          | 说明                                                               |
|:---|:---|
| 状态数组 (STATE)  | 从joint_states、end_effector_states、end_effector_poses提取数值组成状态向量   |
| 视觉图像 (VISUAL) | 从observations.images.color.\*或observations.images.depth.\*提取图像数据 |
| 任务提示 (PROMPT) | 从observation.task获取任务描述文本                                        |
   
**特征类型分类标准**：
- **STATE类型** ：满足以下条件
  - 配置中包含values字段（必填）。
   
- **VISUAL类型** ：满足以下条件
  - 配置中有value字段且value路径格式符合以下规则之一。
    - 4段格式：observation(s).image(s).{color\|depth}.{image_name}。
    
    - 2段格式：{color\|depth}.{image_name}。
     
   
- **PROMPT类型** ：满足以下任一条件。
  - 配置中type字段值为"PROMPT"。
  
  - dtype为 "string" 且value以 "task" 开头。
  
  - dtype为 "string" 且value路径的第一段以observation开头，第二段以task开头。
  
  
  
  
**状态数组类型 (STATE)**
状态数组特征用于从观测数据中提取多个值组成状态向量。
**注意**：状态数组的shape和values数量必须与实际机器人配置一致。
```
"observation.state": {
    "shape": [7],
    "dtype": "float32",
    "values": [
        "observation.joint_states.position@{joint_1}",
        "observation.joint_states.position@{joint_2}",
        "observation.joint_states.position@{joint_3}",
        "observation.joint_states.position@{joint_4}",
        "observation.joint_states.position@{joint_5}",
        "observation.joint_states.position@{joint_6}",
        "observation.joint_states.position@{gripper_1}"
    ]
}
```
表1状态数组类型参数说明 
| 字段     | 值         | 说明                                  |
|:---|:---|:---|
| shape  | \[N\]     | 状态数组包含N个元素（关节数 + 夹爪数），**必须是一维数组**   |
| dtype  | "float32" | 使用32位浮点数表示（必须是整数或浮点类型，不能是字符串）       |
| values | 数组        | 按顺序提取所有关节位置和夹爪位置，顺序取决于模型推理状态数组的具体含义 |
   
配置要求
- shape必须存在且是一维数组（如\[7\]，不能是\[2, 3\]）。
- dtype必须是整数或浮点类型。
- values列表不能为空。
表2数据来源类型 
| 数据源                | 路径格式                                               | 说明                                           |
|:---|:---|:---|
| joint_states       | observation.joint_states.position@{joint_name}     | 关节位置                                         |
| end_effector_state | observation.end_effector_states.position@{ee_name} | 末端执行器/夹爪位置                                   |
| end_effector_poses | observation.end_effector_poses.pose@{ee_name}      | 末端执行器7D位姿（tx, ty, tz, qx, qy, qz, qw），返回完整7维 |
   
路径解析规则
- 使用@{name}从names数组中查找对应的索引。
- 路径必须以observation.开头。
占位符替换
- 配置中的{joint_1}, {joint_2}, {gripper_1}等占位符会在运行时查找关节/夹爪名称所对应的索引的取值。
- **关键**：具体的占位符名称（如joint_1、gripper_1）来自R2C协议中定义的observation_features.joint_states.names和observation_features.end_effector_states.names。
- 不同机器人的关节/夹爪名称可能不同，配置时需确保占位符与实际机器人配置匹配。
**视觉图像类型 (VISUAL)**
视觉特征用于从观测数据中提取图像数据（PNG格式）。
**注意**：图像的键名（如top、wrist）取决于R2C协议中定义的图像配置。不同机器人可能使用不同的相机名称。
```
"observation.images.top": {
    "dtype": "uint8",
    "value": "observations.images.color.top"
}
```
表3视觉图像类型参数说明 
| 字段    | 值                               | 说明             |
|:---|:---|:---|
| dtype | "uint8"                         | 无符号8位整数（0-255） |
| value | "observations.images.color.top" | R2C协议中的图像数据路径  |
   
表4支持的图像路径格式 
| 格式       | 示例                            | 说明         |
|:---|:---|:---|
| 完整路径（4段） | observations.images.color.top | 完整观测数据路径   |
| 短格式（2段）  | color.top                     | 仅包含类型.图像名称 |
| 深度图      | depth.top                     | 深度图像       |
   
路径格式验证
- **4段格式** ：observations.images.{color\|depth}.{image_name}。
  - 第1段必须以observation开头；
  
  - 第2段必须以images开头；
  
  - 第3段必须是color或depth；
  
  - 第4段为图像名称。
   
- **2段格式** ：{color\|depth}.{image_name}。
  - 第1段必须是color或depth；
  
  - 第2段为图像名称。
   
- 路径的图像类型（第3段或第1段）必须是color或depth。
支持的图像类型
- color.\*：彩色图像（RGB）。
- depth.\*：深度图像。
图像名称配置：图像的具体名称（如top、wrist、front）需与R2C协议中的observation_features.images定义保持一致。
**任务提示类型 (PROMPT)**
任务提示特征用于将任务描述传递给模型。
```
"task": {
    "dtype": "string",
    "value": "observation.task"
}
```
或：
```
"task":{
    "type": "PROMPT"  
}
```
表5任务提示类型参数说明 
| 字段    | 值                  | 说明                                         |
|:---|:---|:---|
| dtype | "string"           | 字符串类型                                      |
| value | "observation.task" | 从观测数据中提取任务描述（该字段仅记录为任务提示词，并未使用r2c中的task字段） |
| type  | PROMPT             | 表示该字段对应模型的任务描述字段（会从前端传入）                   |
   
![](https://support.huaweicloud.com/usermanual-cloudrobo/public_sys-resources/note_3.0-zh-cn.png)
- 系统只允许存在一个PROMPT类型特征。
- 配置文件只定义任务描述的**来源路径**（即从哪里获取任务），而不是静态的任务描述文本。任务描述必须从外部传入（前端）。如果为空，会报错"Task prompt not found in both skill config and observation data"，执行失败。
 
**输出特征（output_features）**
该部分定义了如何将模型输出的数据映射到机器人的动作指令。
**动作输出 (action)**
**注意**：output_features目前仅允许存在一个item（item的键与模型保持一致即可）。动作输出的shape和values数量必须与实际机器人配置一致。具体关节和夹爪名称来自R2C协议。
```
"action": {
    "chunk_size": 100,
    "shape": [7],
    "values": [
        "actions.joint_states.position@{joint_1}",
        "actions.joint_states.position@{joint_2}",
        "actions.joint_states.position@{joint_3}",
        "actions.joint_states.position@{joint_4}",
        "actions.joint_states.position@{joint_5}",
        "actions.joint_states.position@{joint_6}",
        "actions.joint_states.position@{gripper_1}"
    ]
}
```
表6动作输出参数 
| 字段         | 值     | 说明                                |
|:---|:---|:---|
| chunk_size | 100   | 模型一次性输出100个时间步的动作                 |
| shape      | \[N\] | 每个时间步包含N个值（关节数 + 夹爪数）             |
| values     | 数组    | 动作值映射到机器人关节/夹爪的路径列表，顺序取决于r2c.json |
   
**输出数据形状**：
- 实际输出形状为 \[chunk_size, shape\]。
- 即chunk_size个时间步，每个时间步N个值（N = 关节数 + 夹爪数）。
**动作映射关系**：
- 动作值按顺序映射到r2c.json中定义的关节和夹爪。
- 关节名称来自action_features.joint_states.names。
- 夹爪名称来自action_features.end_effector_poses。
- 夹爪名称来自action_features.end_effector_states.names。
**停止条件（stop_condition）**
该字段定义模型执行在何时停止的条件，避免无限循环或超时执行。
```
"stop_condition": {
    "max_iter_num": 60,
    "max_run_time": 5
}
```
表7停止条件参数 
| 字段           | 类型      | 值  | 说明         |
|:---|:---|:---|:---|
| max_iter_num | integer | 60 | 最大推理调用次数   |
| max_run_time | integer | 5  | 最大运行时间（分钟） |
   
**停止逻辑**
- 参数"max_iter_num"和"max_run_time"的停止条件是"或"关系，即任一条件满足时都会停止执行。
- 最多执行60次推理调用或最多运行5分钟。