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

本页目录

  • 类
  • ArchiveOutputMode
  • CalibrationSource
  • CommandName
  • CommandResult
  • ConfigSource
  • ConversionPhase
  • FailureReason
  • TelemetryFlowStep
  • 函数
  • bucket_count
  • bucket_memory_bytes
  • build_command_properties
  • build_conversion_result_properties
  • build_conversion_summary
  • build_flow_properties
  • command_failure_reason_from_exception
  • command_result_from_exception
  • detect_config_source
  • get_component_telemetry
  • get_conversion_run_id
  • peak_ram_usage_bytes
  • resolve_tool_version
  • runtime_failure_reason_from_exception
  • telemetry_environment
  • 属性
  • COMMAND_EVENT
  • CONFIGURED_EVENT
  • CONVERSION_RUN_ID_ENV_VAR
  • FLOW_NAME
  • MODELCONVERTER_TELEMETRY_DEFAULTS
  • RESULT_EVENT
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: modelconverter.utils.telemetrymodelconverter CLI 报告的遥测事件。构建 CLI 通过 luxonis_ml.telemetry 为转换运行发送的属性负载:运行了哪个命令,如何配置转换,以及转换如何结束。报告的值是枚举值、布尔值、数字设置和从配置派生的分桶计数,而不是原始模型名称、路径或文件内容。通过环境变量传播的转换运行 ID 将主机端命令事件与转换 Docker 容器内部发出的事件关联起来。

类

ArchiveOutputMode

转换后的模型交付形式。可以是普通模型文件 (native) 或 Luxonis NN 存档 (nn_archive)。

属性

NATIVE
NN_ARCHIVE

CalibrationSource

为输入配置的校准数据类型。

属性

IMAGE_DIRECTORY
RANDOM

CommandName

发出命令遥测事件的 CLI 命令。

属性

CONVERT

CommandResult

命令或转换运行的结果。

属性

FAILED
INTERRUPTED
SUCCESS

ConfigSource

用于转换的配置来源。

属性

ARCHIVE_DIRECTORY
DIRECT_MODEL_INPUT
NN_ARCHIVE
YAML_CONFIG

ConversionPhase

转换结束时所处的转换阶段。

属性

CONFIGURATION
CONVERSION
UPLOAD_INTERMEDIATE
UPLOAD_OUTPUT

FailureReason

命令或转换运行未成功的原因。

属性

CONFIG_ERROR
CONVERSION_ERROR
RUNTIME_ERROR
UPLOAD_ERROR
USER_INTERRUPT

TelemetryFlowStep

流事件所属的转换生命周期步骤。

属性

CONFIGURATION_RESOLVED
RESULT_RECORDED

函数

bucket_count

Python
1def bucket_count(value: int | None) -> str | None:
将计数减少为粗略的桶标签。参数
  • value (int | None): 要报告的计数。分桶可防止遥测事件携带转换模型的精确形状。
返回
  • str | None: "0"、"1"、"2_4" 或 "5_plus" 之一,如果 value 为 None,则为 None。

bucket_memory_bytes

Python
1def bucket_memory_bytes(value: int | None) -> str | None:
将以字节为单位的内存大小减少为粗略的桶标签。参数返回
  • str | None: "under_512m"、"512m_1g"、"1g_4g" 或 "above_4g" 之一,如果 value 为 None,则为 None。

build_command_properties

Python
1def build_command_properties(*, conversion_run_id: str, platform: Platform, runs_in_docker: bool, dev_image: bool, gpu_enabled: bool, tool_version: str | None, custom_image_provided: bool, memory_limit_set: bool, cpu_limit_set: bool, result: CommandResult, duration_ms: int, failure_reason: FailureReason | None = None) -> dict[str, ParamValue]:
构建命令遥测事件的属性。参数
  • conversion_run_id (str): 将事件与转换运行关联的 ID。
  • platform (Platform): 命令调用的平台。
  • runs_in_docker (bool): 转换是否在 Docker 容器内运行。
  • dev_image (bool): 是否使用开发镜像标签。
  • gpu_enabled (bool): 是否请求了 GPU 访问。
  • tool_version (str | None): 平台的已解析工具版本,如果由自定义镜像标签决定,则为 None。
  • custom_image_provided (bool): 是否提供了自定义 Docker 镜像。镜像名称本身从不报告。
  • memory_limit_set (bool): 是否设置了内存限制。限制本身从不报告。
  • cpu_limit_set (bool): 是否设置了 CPU 限制。限制本身从不报告。
  • result (CommandResult): 命令的结果。
  • duration_ms (int): 命令的挂钟持续时间(毫秒)。
  • failure_reason (FailureReason | None): 命令失败的原因,如果未失败,则为 None。
返回
  • dict[str, ParamValue]: 事件属性,None 值已删除。

build_conversion_result_properties

Python
1def build_conversion_result_properties(*, result: CommandResult, duration_ms: int, uploaded_output: bool, uploaded_intermediate_outputs: bool, failure_reason: FailureReason | None = None, output_artifact_count: int | None = None, peak_ram_bytes: int | None = None) -> dict[str, ParamValue]:
构建转换结果事件的属性。参数
  • result (CommandResult): 转换的结果。
  • duration_ms (int): 转换的挂钟持续时间(毫秒)。
  • uploaded_output (bool): 输出模型是否已上传到远程位置。
  • uploaded_intermediate_outputs (bool): 中间输出是否已上传到远程位置。
  • failure_reason (FailureReason | None): 转换失败的原因,如果未失败,则为 None。
  • output_artifact_count (int | None): 生成的输出工件数量。在报告之前由 bucket_count 分桶。
  • peak_ram_bytes (int | None): 峰值 RAM 使用量(字节)。在报告之前由 bucket_memory_bytes 分桶。
返回
  • dict[str, ParamValue]: 事件属性,None 值已删除。

build_conversion_summary

Python
1def build_conversion_summary(cfg: Config, *, platform: Platform, config_source: ConfigSource, archive_output_mode: ArchiveOutputMode, archive_preprocess: bool, main_stage_provided: bool) -> dict[str, ParamValue]:
总结遥测的已解析转换配置。仅报告枚举值、布尔值、数字设置和从配置派生的分桶计数。参数
  • cfg (Config): 已解析的转换配置。
  • platform (Platform): 模型转换的平台。
  • config_source (ConfigSource): 配置的来源。
  • archive_output_mode (ArchiveOutputMode): 输出的交付形式。
  • archive_preprocess (bool): 预处理是否添加到 NN 存档而不是模型。
  • main_stage_provided (bool): 是否明确提供了主阶段的名称。
返回
  • dict[str, ParamValue]: 事件属性,None 值已删除。

build_flow_properties

Python
1def build_flow_properties(conversion_run_id: str, flow_step: TelemetryFlowStep, properties: Mapping[str, ParamValue]) -> dict[str, ParamValue]:
使用转换流元数据扩展事件属性。参数
  • conversion_run_id (str): 将事件与转换运行关联的 ID。
  • flow_step (TelemetryFlowStep): 事件所属的转换流步骤。
  • properties (Mapping[str, ParamValue]): 要扩展的事件属性。
返回
  • dict[str, ParamValue]: 属性,已添加流名称、转换运行 ID 和流步骤。

command_failure_reason_from_exception

Python
1def command_failure_reason_from_exception(exc: BaseException | None) -> FailureReason | None:
从异常中推导出命令失败原因。参数
  • exc (BaseException | None): 终止命令的异常,如果命令正常完成,则为 None。
返回
  • FailureReason | None: 如果命令未失败,则为 None;对于键盘中断或退出代码 130,则为 FailureReason.USER_INTERRUPT;否则为 FailureReason.RUNTIME_ERROR。

command_result_from_exception

Python
1def command_result_from_exception(exc: BaseException | None) -> CommandResult:
从结束命令的异常中推导出命令结果。参数
  • exc (BaseException | None): 终止命令的异常,如果命令正常完成,则为 None。
返回
  • CommandResult: 对于没有异常或代码为 None 或 0 的 SystemExit,则为 CommandResult.SUCCESS;对于键盘中断或退出代码 130,则为 CommandResult.INTERRUPTED;否则为 CommandResult.FAILED。

detect_config_source

Python
1def detect_config_source(path: str | None, opts: list[str], archive_cfg: NNArchiveConfig | None) -> ConfigSource:
检测转换配置的来源。参数
  • path (str | None): 命令行上给定的路径(如果有)。
  • opts (list[str]): CLI 配置覆盖,作为交替的键和值令牌。
  • archive_cfg (NNArchiveConfig | None): 从 NN 存档中提取的配置,如果输入是存档或存档目录。
返回
  • ConfigSource: 当给定存档配置时为 ConfigSource.NN_ARCHIVE 或 ConfigSource.ARCHIVE_DIRECTORY;当给定模型文件或 input_model 覆盖时为 ConfigSource.DIRECT_MODEL_INPUT;否则为 ConfigSource.YAML_CONFIG。

get_component_telemetry

Python
1def get_component_telemetry() -> Telemetry:
返回共享的 modelconverter 遥测客户端。客户端在首次使用时创建,从环境中配置,并以 modelconverter 遥测默认值作为回退。返回
  • Telemetry: 为 modelconverter 注册的 Telemetry 实例。

get_conversion_run_id

Python
1def get_conversion_run_id() -> str:
返回当前转换运行的 ID。ID 存储在 MODELCONVERTER_CONVERSION_RUN_ID 环境变量中,并在首次使用时生成,以便主机端命令和 Docker 容器内运行的转换报告相同的 ID。返回
  • str: 当前进程的转换运行 ID。

peak_ram_usage_bytes

Python
1def peak_ram_usage_bytes() -> int:
返回此进程的峰值 RAM 使用量(字节)。该值来自 resource.getrusage,其 ru_maxrss 在 macOS 上以字节报告,在其他地方以 kibibytes 报告。返回
  • int: 峰值驻留集大小(字节)。

resolve_tool_version

Python
1def resolve_tool_version(*, platform: Platform, tool_version: str | None, image: str | None) -> str | None:
解析平台转换所用的工具版本。参数
  • platform (Platform): 模型转换的平台。
  • tool_version (str | None): 明确请求的工具版本(如果有)。
  • image (str | None): 自定义 Docker 镜像(如果有)。
返回
  • str | None: 请求的工具版本,或平台的默认版本。当给定带有显式标签的自定义镜像时,返回 None,因为版本由该标签决定。

runtime_failure_reason_from_exception

Python
1def runtime_failure_reason_from_exception(exc: BaseException | None, *, phase: ConversionPhase) -> FailureReason | None:
从异常中推导出转换失败原因。参数
  • exc (BaseException | None): 结束转换的异常,如果转换正常完成,则为 None。
  • phase (ConversionPhase): 转换结束时所处的转换阶段。
返回
  • FailureReason | None: 如果没有异常,则为 None;对于键盘中断或退出代码 130,则为 FailureReason.USER_INTERRUPT;否则为与阶段匹配的失败原因。

telemetry_environment

Python
1def telemetry_environment() -> dict[str, str]:
收集要转发到容器的遥测变量。返回
  • dict[str, str]: 当前环境中设置的转换运行 ID 和 LUXONIS_TELEMETRY_* 变量。未设置的变量将被省略。

属性

COMMAND_EVENT

CONFIGURED_EVENT

CONVERSION_RUN_ID_ENV_VAR

FLOW_NAME

MODELCONVERTER_TELEMETRY_DEFAULTS

RESULT_EVENT