此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 函数
  • check_docker
  • docker_bin
  • docker_build
  • docker_exec
  • docker_user_namespace_mode
  • download_snpe_archive
  • generate_compose_config
  • get_container_memory_available
  • get_container_memory_limit
  • get_docker_client_from_active_context
  • get_docker_image
  • get_local_docker_image
  • prepare_build_environment
  • pull_image
  • rvc4_tag_version
  • 属性
  • UserNamespaceMode
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

docker_utils

最后更新
Python API: modelconverter.utils.docker_utilsmodelconverter 命令背后的 Docker 管道。转换不在主机上运行,而是在每个平台的镜像(rvc2、rvc3、rvc4 或 hailo)中运行,该镜像携带着供应商转换工具。此模块在本地查找此类镜像,拉取或构建它,将转换容器(其挂载、环境和资源限制)描述为 Docker Compose 配置,并在其中运行请求的命令。

函数

check_docker

Python
1def check_docker():
检查 Docker 命令是否可以从此处运行。抛出
  • RuntimeError: 如果此进程已在容器内运行,或者此系统上未安装 Docker。

docker_bin

Python
1def docker_bin() -> str:
返回 docker 可执行文件的路径。返回
  • str: 找到 docker 的路径。
抛出
  • RuntimeError: 如果此系统上未安装 Docker。

docker_build

Python
1def 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 准备一个干净的构建环境。
  • version (str | None): 底层转换工具的版本。默认为平台的默认版本。
  • image (str | None): 要构建的镜像的完整名称。如果它不带标签,则附加 <version>-<bare_tag> 标签。默认为 luxonis/modelconverter-<platform>。
返回
  • str: 构建的镜像的名称,包括其标签。
抛出
  • RuntimeError: 如果 docker build 调用失败。

docker_exec

Python
1def 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
1def docker_user_namespace_mode() -> UserNamespaceMode:
返回活动 Docker 守护程序如何将容器的 root 用户映射到主机。
  • rootless: 守护程序本身作为调用用户运行,因此容器 root 已经是该用户。
  • userns: 守护程序作为 root 运行,并进行用户命名空间重新映射,因此容器 root 是一个从属 uid,甚至无法从容器内部 chown 到主机用户。
  • rootful: 容器 root 是主机 root,因此容器写入的内容必须返回给调用用户。
  • unknown: 无法询问守护程序。
答案在一次运行中不能改变,因此它被缓存:这是一个到守护程序的往返,否则每次生成的 compose 配置都会发生一次。

download_snpe_archive

Python
1def download_snpe_archive(version: str, dest: Path) -> Path:
下载给定版本的 SNPE 存档。参数
  • version (str): 要下载的 Qualcomm AI Runtime (SNPE) 版本。
  • dest (Path): 放置存档的目录。如果缺少则创建。
返回
  • Path: 存档的路径。如果它已经存在,则直接返回,不下载任何内容。
抛出
  • RuntimeError: 如果下载失败。消息解释了如何手动下载存档。

generate_compose_config

Python
1def 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
1def get_container_memory_available() -> int:
返回此容器仍可用的内存字节数。即其内存限制减去其中运行的每个进程的常驻内存,永远不小于零。

get_container_memory_limit

Python
1def get_container_memory_limit() -> int:
返回当前容器的内存限制(以字节为单位)。

get_docker_client_from_active_context

Python
1def get_docker_client_from_active_context() -> docker.DockerClient:
为活动的 Docker 上下文创建 Docker 客户端。守护程序端点从 docker context show 报告的上下文读取,因此非默认上下文(无根、远程、Colima 等)将优先于环境默认值。对于 tcp:// 端点,除非上下文跳过验证,否则启用 TLS。返回
  • docker.DockerClient: 与活动上下文的守护程序通信的客户端。

get_docker_image

Python
1def 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
1def 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
1def 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
1def pull_image(client: docker.DockerClient, image: str) -> str:
拉取镜像,为每个层显示进度条。使用 Docker SDK 而不是 docker pull 子进程,因为后者在镜像为私有时会交互式地请求登录凭据。参数
  • client (docker.DockerClient): 用于拉取的 Docker 客户端。
  • image (str): 要拉取的镜像,可选地包括标签。
返回
  • str: 拉取的镜像的名称。
抛出
  • RuntimeError: 如果守护程序在拉取时报告错误。

rvc4_tag_version

Python
1def rvc4_tag_version(version: str) -> str:
从版本字符串中删除构建组件。参数
  • version (str): 要剥离的版本字符串,例如 2.41.0.251128。
返回
  • str: 没有构建组件的版本,例如 2.41.0。

属性

UserNamespaceMode