# device_handlers

Python API: `modelconverter.utils.device_handlers`

用于驱动物理设备的处理器。

RVC4 模型的基准测试和分析是在真实设备上进行的，而不是在转换容器中：模型及其输入被推送到设备，在那里运行命令，然后将结果拉回。此模块将用于此目的的两种传输——ADB 和 SSH——封装在一个接口后面，因此调用者不必关心设备可以通过哪种方式访问。

## 类

### AdbHandler

基于 Android 调试桥的设备处理器实现。

#### 方法

##### init

```python
def __init__(device_id: str | None = None, silent: bool = True):
```

为目标设备初始化 ADB 处理器。

如果未提供设备 ID，则选择第一个连接的设备。

参数

 * `device_id` (`str | None`): 可选的 ADB 设备标识符。
 * `silent` (`bool`): 如果为 `True`，则抑制命令日志记录。

引发

 * `RuntimeError`: 如果设备枚举失败或没有可用的连接设备。
 * `ValueError`: 如果指定的设备未连接。
 * `FileNotFoundError`: 如果 `adb` 可执行文件不可用。

##### pull

```python
def pull(src: PathType, dst: PathType, *, check: bool = True) -> tuple[int, str, str]:
```

将文件或目录从设备复制到本地计算机。

参数

 * `src` (`PathType`): 设备上的源路径。
 * `dst` (`PathType`): 本地计算机上的目标路径。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

##### push

```python
def push(src: PathType, dst: PathType, *, check: bool = True) -> tuple[int, str, str]:
```

将文件或目录从本地计算机复制到设备。

参数

 * `src` (`PathType`): 本地计算机上的源路径。
 * `dst` (`PathType`): 设备上的目标路径。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

##### run

```python
def run(*args, check: bool = True, **kwargs) -> tuple[int, str, str]:
```

运行子进程命令并返回其结果。

命令参数在执行前转换为字符串。输出始终被捕获并使用尽力而为的策略进行解码。

参数

 * `*args`: 传递给 `subprocess.run` 的位置命令参数。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。
 * `silent`: 如果为 `True`，则抑制命令日志记录。
 * `**kwargs`: 转发给 `subprocess.run` 的其他关键字参数。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

引发

 * `subprocess.CalledProcessError`: 如果 `check` 已启用且子进程以非零状态退出。

##### shell

```python
def shell(cmd: str, *, check: bool = True, silent: bool | None = None) -> tuple[int, str, str]:
```

在目标设备上执行 shell 命令。

参数

 * `cmd` (`str`): 要在设备上执行的 shell 命令。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。
 * `silent` (`bool | None`): 如果为 `True`，则抑制命令日志记录。如果为 `None`，则使用处理器的默认日志记录行为。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

### DeviceHandler

与设备通信的抽象接口。

实现通过 SSH 或 ADB 等具体传输提供 shell 访问和文件传输操作。

#### 方法

##### init

```python
def __init__(silent: bool = True):
```

初始化设备处理器。

参数

 * `silent` (`bool`): 如果为 `True`，则默认抑制命令日志记录。

##### pull

```python
def pull(src: PathType, dst: PathType, *, check: bool = True) -> tuple[int, str, str]:
```

将文件或目录从设备复制到本地计算机。

参数

 * `src` (`PathType`): 设备上的源路径。
 * `dst` (`PathType`): 本地计算机上的目标路径。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

##### push

```python
def push(src: PathType, dst: PathType, *, check: bool = True) -> tuple[int, str, str]:
```

将文件或目录从本地计算机复制到设备。

参数

 * `src` (`PathType`): 本地计算机上的源路径。
 * `dst` (`PathType`): 设备上的目标路径。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

##### run

```python
def run(*args, check: bool = False, silent: bool = True, **kwargs) -> tuple[int, str, str]:
```

运行子进程命令并返回其结果。

命令参数在执行前转换为字符串。输出始终被捕获并使用尽力而为的策略进行解码。

参数

 * `*args`: 传递给 `subprocess.run` 的位置命令参数。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。
 * `silent` (`bool`): 如果为 `True`，则抑制命令日志记录。
 * `**kwargs`: 转发给 `subprocess.run` 的其他关键字参数。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

引发

 * `subprocess.CalledProcessError`: 如果 `check` 已启用且子进程以非零状态退出。

##### shell

```python
def shell(cmd: str, *, check: bool = True, silent: bool | None = None) -> tuple[int, str, str]:
```

在目标设备上执行 shell 命令。

参数

 * `cmd` (`str`): 要在设备上执行的 shell 命令。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。
 * `silent` (`bool | None`): 如果为 `True`，则抑制命令日志记录。如果为 `None`，则使用处理器的默认日志记录行为。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

### SSHHandler

基于 SSH 和 SCP 的设备处理器实现。

#### 方法

##### init

```python
def __init__(ip: str, silent: bool = True):
```

为目标设备初始化 SSH 处理器。

参数

 * `ip` (`str`): 目标设备 IP 地址。
 * `silent` (`bool`): 如果为 `True`，则抑制命令日志记录。

##### pull

```python
def pull(src: PathType, dst: PathType, *, check: bool = True) -> tuple[int, str, str]:
```

将文件或目录从设备复制到本地计算机。

参数

 * `src` (`PathType`): 设备上的源路径。
 * `dst` (`PathType`): 本地计算机上的目标路径。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

##### push

```python
def push(src: PathType, dst: PathType, *, check: bool = True) -> tuple[int, str, str]:
```

将文件或目录从本地计算机复制到设备。

参数

 * `src` (`PathType`): 本地计算机上的源路径。
 * `dst` (`PathType`): 设备上的目标路径。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

##### shell

```python
def shell(cmd: str, *, check: bool = True, silent: bool | None = None) -> tuple[int, str, str]:
```

在目标设备上执行 shell 命令。

参数

 * `cmd` (`str`): 要在设备上执行的 shell 命令。
 * `check` (`bool`): 如果为 `True`，则将子进程失败作为异常传播。
 * `silent` (`bool | None`): 如果为 `True`，则抑制命令日志记录。如果为 `None`，则使用处理器的默认日志记录行为。

返回

 * `tuple[int, str, str]`: 包含返回码、标准输出和标准错误的元组。

## 函数

### create_handler

```python
def create_handler(device_ip: str | None, device_adb_id: str | None) -> DeviceHandler:
```

为要运行的设备创建处理器。

ADB 是首选；只有在无法创建
[AdbHandler](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/device_handlers.md)
且有 IP 地址可供回退时，才会构建
[SSHHandler](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/device_handlers.md)。

参数

 * `device_ip` (`str | None`): 设备的 IP 地址，用于 SSH 回退。如果没有回退，则为 `None`。
 * `device_adb_id` (`str | None`): 设备的 ADB 标识符，如果使用第一个连接的设备，则为 `None`。

返回

 * `DeviceHandler`: 设备的处理器。

引发

 * `RuntimeError`: 如果没有连接 ADB 设备，或者无法查询 ADB，并且没有提供 IP 地址。
 * `ValueError`: 如果请求的 ADB 设备未连接且没有提供 IP 地址。
 * `FileNotFoundError`: 如果 `adb` 可执行文件不可用且没有提供 IP 地址。
