捷勃特机器人 SDK
搜索 K

中文

English

中文

English

外观

4.16 自然语言控制 ​

说明 ​

NLUControl 模块提供了通过自然语言指令控制机器人的功能。用户可以使用日常语言描述期望的机器人动作，系统会自动将其转换为可执行的代码并在安全检查后执行。

类构造函数 ​

方法名NLUControl( controller_ip : str)
描述自然语言控制类，通过自然语言控制机器人运动。通常通过 arm.nlu 访问，无需手动实例化。
请求参数controller_ip : str 控制柜 IP 地址
返回值无返回值
备注该类会在 Arm 类实例化时自动创建，用户直接通过 arm.nlu 访问即可。
兼容的机器人软件版本协作 (Copper): v7.7.0.0+
工业 (Bronze): v7.7.0.0+

4.16.1 执行自然语言指令 ​

方法名execute( natural_language : str) -> tuple[NLUGeneratedCode, StatusCodeEnum]
描述通过自然语言指令控制机器人，系统会将自然语言翻译为可执行代码并返回。
请求参数natural_language : str 自然语言指令，例如 "机器人移动到零点，并获取当前位置"
支持复杂的多步骤指令，如顺序执行、条件判断等。
返回值NLUGeneratedCode: 生成的代码对象，包含可执行代码和审批状态
StatusCodeEnum: 函数执行结果
备注- 返回的 NLUGeneratedCode 对象包含 needs_approval 属性，指示是否需要用户审批
- 如果 needs_approval=True , 必须先调用 approve() 方法批准后才能执行
- 可以通过 result.code 查看生成的代码内容
兼容的机器人软件版本协作 (Copper): v7.7.0.0+
工业 (Bronze): v7.7.0.0+

NLUGeneratedCode 类 ​

说明 ​

NLUGeneratedCode 类用于封装、管理和安全执行由 NLU 服务生成的 Python 代码片段。该类提供了代码审批和执行的安全机制，确保需要审批的代码必须经过明确批准才能执行。

属性 ​

属性名类型描述
needs_approvalbool是否需要审批才能执行，根据代码危险等级确定
codestr生成的可执行 Python 代码字符串

4.16.2 批准代码执行 ​

方法名approve()
描述批准代码执行。调用此方法后，代码将被标记为已审批，可以通过 execute_code() 方法执行。
请求参数无参数
返回值无返回
备注- 仅当 needs_approval=True 时需要调用此方法
- 未调用 approve() 直接执行需要审批的代码会返回错误
兼容的机器人软件版本协作 (Copper): v7.7.0.0+
工业 (Bronze): v7.7.0.0+

4.16.3 执行生成的代码 ​

方法名execute_code() -> tuple[Any, StatusCodeEnum]
描述执行 NLU 生成的代码。如果代码需要审批且尚未批准，则返回错误。
请求参数无参数
返回值Any: 代码执行结果，类型取决于生成的代码
StatusCodeEnum: 函数执行结果
备注- 如果 needs_approval=True 但未调用 approve() , 会返回 NLU_APPROVAL_REQUIRED 错误
- 代码执行过程中的任何异常都会被捕获并返回相应的错误状态码
兼容的机器人软件版本协作 (Copper): v7.7.0.0+
工业 (Bronze): v7.7.0.0+

4.16.4 打印生成的代码 ​

方法名print_code()
描述打印生成的代码，便于用户审查。输出格式包含语法高亮。
请求参数无参数
返回值无返回
备注建议在需要审批时先调用此方法查看代码内容，再决定是否批准执行
兼容的机器人软件版本协作 (Copper): v7.7.0.0+
工业 (Bronze): v7.7.0.0+

使用示例 ​

示例 1: 基础查询操作 ​

nlu_control/get_controller_version.py
py
#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 自然语言基础控制示例 / Natural Language Basic Control Example
"""

from Agilebot import Arm, StatusCodeEnum

# [ZH] 初始化捷勃特机器人
# [EN] Initialize the Agilebot robot
arm = Arm()
# [ZH] 连接捷勃特机器人
# [EN] Connect to the Agilebot robot
ret = arm.connect("10.27.1.254")

# [ZH] 检查是否连接成功
# [EN] Check if connection is successful
if ret == StatusCodeEnum.OK:
    print("机器人连接成功 / Robot connected successfully")
else:
    print(f"机器人连接失败，错误代码 / Robot connection failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)


# [ZH] 示例：使用自然语言获取控制器版本信息
# [EN] Example: Use natural language to get controller version information
result, ret = arm.nlu.execute("获取控制器版本信息")

if ret == StatusCodeEnum.OK:
    print("自然语言指令执行成功 / Natural language command executed successfully")

    if result.needs_approval:
        print("\n" + "=" * 50)
        print("警告：需要用户确认 / Warning: User Approval Required")
        print("=" * 50)

        result.print_code()
        print("\n请确认是否执行此代码 / Please confirm if you want to execute this code:")
        user_input = input("\n(yes/no): ").strip().lower()
        if user_input not in ["yes", "y"]:
            print("用户拒绝执行代码 / User rejected code execution")
            arm.disconnect()
            exit(1)
        else:
            result.approve()
    exec_result, ret = result.execute_code()
    if ret == StatusCodeEnum.OK:
        print(f"执行结果 / Execution result: {exec_result}")
else:
    print(f"自然语言指令执行失败 / Natural language command failed: {ret.errmsg}")

# [ZH] 断开捷勃特机器人连接
# [EN] Disconnect from Agilebot robot
arm.disconnect()
print("\n机器人断开连接成功 / Robot disconnected successfully")

示例 2: 顺序执行多个任务 ​

nlu_control/serial_execution.py
py
#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 自然语言顺序执行示例 / Natural Language Sequential Execution Example
"""

from Agilebot import Arm, StatusCodeEnum

# [ZH] 初始化捷勃特机器人
# [EN] Initialize the Agilebot robot
arm = Arm()
# [ZH] 连接捷勃特机器人
# [EN] Connect to the Agilebot robot
ret = arm.connect("10.27.1.254")

# [ZH] 检查是否连接成功
# [EN] Check if connection is successful
if ret == StatusCodeEnum.OK:
    print("机器人连接成功 / Robot connected successfully")
else:
    print(f"机器人连接失败，错误代码 / Robot connection failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)


# [ZH] 示例：使用自然语言让机器人按顺序执行任务
# [EN] Example: Use natural language to instruct the robot to execute tasks sequentially
result, ret = arm.nlu.execute(
    """
按顺序执行：
1. 清除报警；
2. 控制机械臂所有关节运动至零点位置；
3. 启动程序 'Put_into_box'，等待下发完成，并等待其执行结束；
4. 获取当前位姿。
"""
)

if ret == StatusCodeEnum.OK:
    print("自然语言指令执行成功 / Natural language command executed successfully")
    if result.needs_approval:
        print("\n" + "=" * 50)
        print("警告：需要用户确认 / Warning: User Approval Required")
        print("=" * 50)

        result.print_code()
        print("\n请确认是否执行此代码 / Please confirm if you want to execute this code:")
        user_input = input("\n(yes/no): ").strip().lower()
        if user_input not in ["yes", "y"]:
            print("用户拒绝执行代码 / User rejected code execution")
            arm.disconnect()
            exit(1)
        else:
            result.approve()
    exec_result, ret = result.execute_code()
    if ret == StatusCodeEnum.OK:
        print(f"执行结果 / Execution result: {exec_result}")
else:
    print(f"自然语言指令执行失败 / Natural language command failed: {ret.errmsg}")

# [ZH] 断开捷勃特机器人连接
# [EN] Disconnect from Agilebot robot
arm.disconnect()
print("\n机器人断开连接成功 / Robot disconnected successfully")

Copyright © 2025-present Agilebot Robotics Co., Ltd.