# docker_utils

Python API: `modelconverter.utils.docker_utils`

`modelconverter` 命令背后的 Docker 管道。

转换不在主机上运行，而是在每个平台的镜像（`rvc2`、`rvc3`、`rvc4` 或 `hailo`）中运行，该镜像携带着供应商转换工具。此模块在本地查找此类镜像，拉取或构建它，将转换容器（其挂载、环境和资源限制）描述为 Docker Compose
配置，并在其中运行请求的命令。

## 函数

### check_docker

```python
def check_docker():
```

检查 Docker 命令是否可以从此处运行。

抛出

 * `RuntimeError`: 如果此进程已在容器内运行，或者此系统上未安装 Docker。

### docker_bin

```python
def docker_bin() -> str:
```

返回 `docker` 可执行文件的路径。

返回

 * `str`: 找到 `docker` 的路径。

抛出

 * `RuntimeError`: 如果此系统上未安装 Docker。

### docker_build

```python
def docker_build(platform: Literal['rvc2', 'rvc3', 'rvc4', 'hailo'], bare_tag: str, version: str | None = None, image: str | None = None) -> str:
```

构建给定平台的 Docker 镜像。

参数

 * `platform` (`Literal['rvc2', 'rvc3', 'rvc4', 'hailo']`): 要为其构建镜像的平台。
 * `bare_tag` (`str`): 镜像标签的后缀，附加到工具版本。`dev` 还会将测试工具安装到镜像中；对于 RVC4，任何其他标签首先使用
   [prepare_build_environment](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/docker_utils.md)
   准备一个干净的构建环境。
 * `version` (`str | None`): 底层转换工具的版本。默认为平台的默认版本。
 * `image` (`str | None`): 要构建的镜像的完整名称。如果它不带标签，则附加 `<version>-<bare_tag>` 标签。默认为 `luxonis/modelconverter-<platform>`。

返回

 * `str`: 构建的镜像的名称，包括其标签。

抛出

 * `RuntimeError`: 如果 `docker build` 调用失败。

### docker_exec

```python
def docker_exec(platform: Literal['rvc2', 'rvc3', 'rvc4', 'hailo'], *args: str, bare_tag: str, use_gpu: bool, version: str | None = None, image: str | None = None, memory: int | None = None, cpus: float | None = None):
```

在给定平台的容器内运行命令。

创建挂载到容器中的主机目录，为其写入临时 Compose 文件，并使用 `docker compose run` 运行命令。参数作为 `argv` 传递给容器的入口点，并且从不被 shell 重新评估。

> **注意**
> 这永远不会返回：主机进程以容器的返回码退出。

参数

 * `platform` (`Literal['rvc2', 'rvc3', 'rvc4', 'hailo']`): 命令运行所在的镜像平台。
 * `*args` (`str`): 命令及其参数。
 * `bare_tag` (`str`): 镜像标签的后缀，附加到工具版本，例如 `latest` 或 `dev`。
 * `use_gpu` (`bool`): 是否为容器提供 GPU。仅对 `hailo` 平台有效。
 * `version` (`str | None`): 底层转换工具的版本。默认为平台的默认版本。
 * `image` (`str | None`): 要使用的镜像的完整名称。默认为平台的官方镜像。
 * `memory` (`int | None`): 容器的内存限制（以字节为单位）。`None` 表示不设置限制。
 * `cpus` (`float | None`): 容器可以使用的 CPU 核心数，可能为小数。`None` 表示不设置限制。

抛出

 * `SystemExit`: 总是，携带容器的返回码。

### docker_user_namespace_mode

```python
def docker_user_namespace_mode() -> UserNamespaceMode:
```

返回活动 Docker 守护程序如何将容器的 root 用户映射到主机。

 * `rootless`: 守护程序本身作为调用用户运行，因此容器 root 已经是该用户。
 * `userns`: 守护程序作为 root 运行，并进行用户命名空间重新映射，因此容器 root 是一个从属 uid，甚至无法从容器内部 chown 到主机用户。
 * `rootful`: 容器 root 是主机 root，因此容器写入的内容必须返回给调用用户。
 * `unknown`: 无法询问守护程序。

答案在一次运行中不能改变，因此它被缓存：这是一个到守护程序的往返，否则每次生成的 compose 配置都会发生一次。

### download_snpe_archive

```python
def download_snpe_archive(version: str, dest: Path) -> Path:
```

下载给定版本的 SNPE 存档。

参数

 * `version` (`str`): 要下载的 Qualcomm AI Runtime (SNPE) 版本。
 * `dest` (`Path`): 放置存档的目录。如果缺少则创建。

返回

 * `Path`: 存档的路径。如果它已经存在，则直接返回，不下载任何内容。

抛出

 * `RuntimeError`: 如果下载失败。消息解释了如何手动下载存档。

### generate_compose_config

```python
def generate_compose_config(image: str, gpu: bool = False, memory: int | None = None, cpus: float | None = None, extra_environment: dict[str, str] | None = None) -> str:
```

生成转换服务的 Compose 配置。

该服务挂载 modelconverter 缓存和主机的 `./output` 目录，转发 bucket 存储凭据，并且——对于有根守护程序——转发主机用户的 uid 和 gid，以便容器可以将它写入的文件返回给调用用户。

参数

 * `image` (`str`): 服务运行的镜像。名称以 `-dev` 结尾的镜像还会将主机的源、测试和 `pyproject.toml` 挂载到其中。
 * `gpu` (`bool`): 是否使用 `nvidia` 运行时运行容器。
 * `memory` (`int | None`): 容器的内存限制（以字节为单位）。`None` 表示不设置限制。
 * `cpus` (`float | None`): 容器可以使用的 CPU 核心数，可能为小数。`None` 表示不设置限制。
 * `extra_environment` (`dict[str, str] | None`): 容器的额外环境变量，合并到默认值之上。

返回

 * `str`: 作为 YAML 文档的 Compose 配置。

### get_container_memory_available

```python
def get_container_memory_available() -> int:
```

返回此容器仍可用的内存字节数。

即其内存限制减去其中运行的每个进程的常驻内存，永远不小于零。

### get_container_memory_limit

```python
def get_container_memory_limit() -> int:
```

返回当前容器的内存限制（以字节为单位）。

### get_docker_client_from_active_context

```python
def get_docker_client_from_active_context() -> docker.DockerClient:
```

为活动的 Docker 上下文创建 Docker 客户端。

守护程序端点从 `docker context show` 报告的上下文读取，因此非默认上下文（无根、远程、Colima 等）将优先于环境默认值。对于 `tcp://` 端点，除非上下文跳过验证，否则启用 TLS。

返回

 * `docker.DockerClient`: 与活动上下文的守护程序通信的客户端。

### get_docker_image

```python
def get_docker_image(platform: Literal['rvc2', 'rvc3', 'rvc4', 'hailo'], bare_tag: str, version: str, image: str | None = None) -> str:
```

返回用于运行给定平台转换的镜像。

如果存在匹配的本地镜像，则使用它。否则，从 `ghcr.io` 拉取候选镜像，如果也失败，则在本地构建镜像。

参数

 * `platform` (`Literal['rvc2', 'rvc3', 'rvc4', 'hailo']`): 镜像所属的平台。
 * `bare_tag` (`str`): 镜像标签的后缀，附加到工具版本，例如 `latest` 或 `dev`。
 * `version` (`str`): 底层转换工具的版本。
 * `image` (`str | None`): 要使用的镜像的完整名称。如果它不带标签，则附加 `<version>-<bare_tag>` 标签。默认为 `luxonis/modelconverter-<platform>`。

返回

 * `str`: 要运行的镜像的名称，包括其标签。

### get_local_docker_image

```python
def get_local_docker_image(platform: Literal['rvc2', 'rvc3', 'rvc4', 'hailo'], bare_tag: str, version: str, image: str | None = None) -> str | None:
```

返回本地守护程序上已存在的匹配镜像。

在本地镜像中查找裸候选名称及其 `docker.io` 和 `ghcr.io` 拼写。

参数

 * `platform` (`Literal['rvc2', 'rvc3', 'rvc4', 'hailo']`): 镜像所属的平台。
 * `bare_tag` (`str`): 镜像标签的后缀，附加到工具版本，例如 `latest` 或 `dev`。
 * `version` (`str`): 底层转换工具的版本。
 * `image` (`str | None`): 要查找的镜像的完整名称。如果它不带标签，则附加 `<version>-<bare_tag>` 标签。默认为 `luxonis/modelconverter-<platform>`。

返回

 * `str | None`: 第一个匹配的本地镜像的完整名称，包括其标签，如果本地没有可用的候选镜像，则为 `None`。

### prepare_build_environment

```python
def prepare_build_environment(platform: Literal['rvc2', 'rvc3', 'rvc4', 'hailo'], version: str) -> Path:
```

准备一个目录，可以从中构建平台的镜像。

下载并提取运行版本的 modelconverter 源，并将 `version` 的 SNPE 存档放置到位，通过复制本地可用的存档或下载它。

参数

 * `platform` (`Literal['rvc2', 'rvc3', 'rvc4', 'hailo']`): 准备构建的平台。仅支持 `rvc4`。
 * `version` (`str`): 构建所需的 SNPE 存档的转换工具版本。

返回

 * `Path`: 用于构建镜像的提取源树的路径。

抛出

 * `NotImplementedError`: 如果 `platform` 不是 `rvc4`。

### pull_image

```python
def pull_image(client: docker.DockerClient, image: str) -> str:
```

拉取镜像，为每个层显示进度条。

使用 Docker SDK 而不是 `docker pull` 子进程，因为后者在镜像为私有时会交互式地请求登录凭据。

参数

 * `client` (`docker.DockerClient`): 用于拉取的 Docker 客户端。
 * `image` (`str`): 要拉取的镜像，可选地包括标签。

返回

 * `str`: 拉取的镜像的名称。

抛出

 * `RuntimeError`: 如果守护程序在拉取时报告错误。

### rvc4_tag_version

```python
def rvc4_tag_version(version: str) -> str:
```

从版本字符串中删除构建组件。

> **示例**
> ```pycon
>>> rvc4_tag_version("2.41.0.251128")
'2.41.0'
>>> rvc4_tag_version("2.41.0")
'2.41.0'
```

参数

 * `version` (`str`): 要剥离的版本字符串，例如 `2.41.0.251128`。

返回

 * `str`: 没有构建组件的版本，例如 `2.41.0`。

## 属性

### UserNamespaceMode
