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: 함수 실행 결과
메모	- The returned NLUGeneratedCode object contains a needs_approval property indicating whether user approval is required - If needs_approval=True , you must call the approve() method before execution - You can view the generated code content via result.code
호환 로봇 소프트웨어 버전	협업(Copper): v7.7.0.0+ 산업용(Bronze): v7.7.0.0+

NLUGeneratedCode 클래스

개요

NLUGeneratedCode 클래스는 NLU 서비스에서 생성된 Python 코드 조각을 캡슐화, 관리 및 안전하게 실행하는 데 사용됩니다. 이 클래스는 코드 승인 및 실행을 위한 보안 메커니즘을 제공하여 승인이 필요한 코드가 실행 전에 명시적으로 승인되어야 함을 보장합니다.

속성

속성 이름	유형	설명
needs_approval	부울	코드의 위험도에 따라 실행 전 승인이 필요한지 여부
code	str	생성된 실행 가능 Python 코드 문자열

4.16.2 코드 실행 승인

메서드 이름	approve()
설명	Approve code execution. After calling this method, the code is marked as approved and can be executed via the execute_code() method.
요청 매개변수	매개변수 없음
반환 값	반품 불가
메모	- This method only needs to be called when needs_approval=True - Executing code that requires approval without calling approve() will return an error
호환 로봇 소프트웨어 버전	협업(Copper): v7.7.0.0+ 산업용(Bronze): v7.7.0.0+

4.16.3 생성된 코드 실행

메서드 이름	execute_code() -> tuple[Any, StatusCodeEnum]
설명	NLU 생성 코드를 실행합니다. 코드에 승인이 필요하지만 승인되지 않은 경우 오류가 반환됩니다.
요청 매개변수	매개변수 없음
반환 값	Any: 코드 실행 결과, 유형은 생성된 코드에 따라 다름 StatusCodeEnum: 함수 실행 결과
메모	- If needs_approval=True but approve() was not called, returns NLU_APPROVAL_REQUIRED error - Any exceptions during code execution are caught and returned as corresponding error status codes
호환 로봇 소프트웨어 버전	협업(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

#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 自然语言基础控制与安全评级示例 / NLU Basic Control with Safety Rating 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")
    danger_level = getattr(result, "danger_level", "unknown")
    warnings = getattr(result, "warnings", [])

    result.print_code()
    print(f"安全评级 / Danger level: {danger_level}")
    if warnings:
        print("安全提示 / Safety warnings:")
        for idx, warning in enumerate(warnings, 1):
            print(f"  {idx}. {warning}")

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

        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"代码执行失败 / Code execution failed: {ret.errmsg}")
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

#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 自然语言顺序执行与安全评级示例 / NLU Sequential Execution with Safety Rating 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")
    danger_level = getattr(result, "danger_level", "unknown")
    warnings = getattr(result, "warnings", [])

    result.print_code()
    print(f"安全评级 / Danger level: {danger_level}")
    if warnings:
        print("安全提示 / Safety warnings:")
        for idx, warning in enumerate(warnings, 1):
            print(f"  {idx}. {warning}")

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

        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"代码执行失败 / Code execution failed: {ret.errmsg}")
else:
    print(f"自然语言指令执行失败 / Natural language command failed: {ret.errmsg}")

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