Holoscan 应用程序包规范 (HAP)

Holoscan 应用程序包规范扩展了 MONAI Deploy 应用程序包规范，以提供 Holoscan SDK 的流式传输功能、多片段和其他特性。

本文档包含 Holoscan 应用程序包 (HAP) 的规范。HAP 是一个容器化的应用程序或服务，根据本文档的定义，它是自描述的。

目标

本文档旨在定义 HAP 的结构和用途，包括哪些部分是可选的，哪些部分是必需的，以便开发人员可以轻松创建符合规范的 HAP。

假设、约束、依赖

以下假设与 HAP 的执行、检查和一般用法有关

• 容器化应用程序将基于 Linux x64 (AMD64) 和/或 ARM64 (aarch64)。

• 容器化应用程序的主机环境将基于支持容器的 Linux x64 (AMD64) 和/或 ARM64 (aarch64)。

• 开发人员期望其应用程序的本地执行行为与容器化版本的执行行为相同。

• 开发人员期望其容器化应用程序的本地执行行为与部署中的执行行为相同。

• 开发人员和运维工程师希望应用程序包是自描述的。

• 应用程序可以使用 Holoscan SDK 或 MONAI Deploy App SDK 中提供的工具以外的其他工具创建。

• Holoscan 应用程序包可以使用 Holoscan SDK 或 MONAI Deploy App SDK 中提供的工具以外的其他工具创建。

• 预先存在的容器化应用程序必须“转换”为 Holoscan 应用程序包。

• 一个 Holoscan 应用程序包可能包含一个经典应用程序（非基于片段的）、一个单片段应用程序或一个多片段应用程序。（请参阅定义、首字母缩略词、缩写中片段的定义）

• 基于 Holoscan SDK 的多片段应用程序的可扩展性不在本文档的范围之内。

• 应用程序包预计将部署在支持的环境之一中。有关更多信息，请参阅Holoscan 运行环境。

以下要求必须由 HAP 规范满足，才能被认为是完整和批准的。标有 MUST 或 SHALL 的所有要求必须实施，以便 HAP 就绪的托管服务支持。

单一工件

• HAP 应包含单个容器，满足本文档规定的最低要求。

• HAP 应是一个容器化应用程序，以最大程度地提高其应用程序的可移植性。

自描述

• HAP 必须是自描述的，并提供一种提取其描述的机制。

  • HAP 应提供一种将元数据文件打印到控制台的方法。

  • HAP 应提供一种将元数据文件复制到用户指定目录的方法。

• 描述方法应采用机器可读和可写的格式。

• 描述方法应采用人类可读的格式。

• 描述方法应采用人类可写的格式。

• 描述方法应是声明式的和不可变的。

• 描述方法应提供有关 HAP 的以下信息

  • 执行要求，例如依赖项和限制。

  • 资源要求包括 CPU 核心、系统内存、共享内存、GPU 和 GPU 内存。

HAP 的运行时特性

• 当用户指定参数执行 HAP 时，HAP 应启动打包的应用程序。

• HAP 应将打包的应用程序描述为长期运行的服务或应用程序，以便外部代理可以管理其生命周期。

IO 规范

• HAP 应提供有关其预期输入的信息，以便外部代理可以确定 HAP 是否可以接收工作负载。

• HAP 应提供有关其输出的足够信息，以便外部代理知道如何处理结果。

本地执行

HAP 必须采用支持在开发环境中本地执行的格式。

兼容 Kubernetes

• HAP 应支持使用 Kubernetes 部署。

OCI 兼容性

HAP 的容器化部分应符合开放容器倡议格式标准。

镜像注解

HAP 的容器化部分的所有注解必须遵守开放容器注解规范中规定的规范

• org.opencontainers.image.title：HAP 容器镜像应提供人类可读的标题（字符串）。

• org.opencontainers.image.version：HAP 容器镜像应使用语义版本控制格式提供打包应用程序的版本。此值与应用程序清单字段表中 /etc/holoscan/app.json#version 中定义的值相同。

• 当可用时，应提供所有其他 OpenContainers 预定义键。

托管环境

HAP 托管环境执行 HAP，并在调用时为应用程序提供一组自定义的环境变量和命令行选项。

• 默认情况下，托管服务必须按照 /etc/holoscan/app.json#command 的定义执行应用程序，然后在应用程序或服务完成时退出。

• 托管服务必须提供 /etc/holoscan/app.json#environment 指定的任何环境变量。

• 托管服务应监控应用程序进程，并记录其 CPU、系统内存和 GPU 利用率指标。

• 托管服务应监控应用程序进程，并强制执行 /etc/holoscan/app.json#timeout 中指定的任何超时值。

环境变量表

如果用户未在应用程序清单 /etc/holoscan/app.json#environment 中指定，则 HAP 应包含以下环境变量及其默认值。

描述

Holoscan 应用程序包 (HAP) 是一个功能包，旨在处理规定格式的数据集。HAP 是一个容器镜像，它遵循本文档中提供的规范。

应用程序

HAP 的主要组件是应用程序。应用程序由应用程序开发人员提供，并使用 Holoscan 应用程序打包器合并到 HAP 中。

所有应用程序代码和二进制文件应位于 /opt/holoscan/app/ 文件夹中，除非在创建 HAP 期间 Holoscan 应用程序打包器安装了任何依赖项。

所有 AI 模型（PyTorch、TensorFlow、TensorRT 等）应位于 /opt/holoscan/models/ 文件夹的单独子文件夹中。在特定用例中，如果应用程序包开发人员由于知识产权问题而无法将模型文件包含在包/容器中，则可以在运行应用程序包时从主机系统提供模型，例如，通过卷挂载映射和使用容器环境变量。

清单

HAP 应包含两个清单：应用程序清单和包清单。包清单应存储在 /etc/holoscan/pkg.json 中，应用程序清单应存储在 /etc/holoscan/app.json 中。一旦创建了 HAP，其清单预计是不可变的。

应用程序清单

应用程序清单字段表

应用程序清单文件提供有关 HAP 应用程序的信息。

• 应用程序清单必须定义容器化应用程序的类型 (/etc/holoscan/app.json#type)。

  • 类型应具有 service 或 application 的值。

• 应用程序清单必须定义用于运行应用程序的命令 (/etc/holoscan/app.json#command)。

• 应用程序清单应定义清单文件模式的版本 (/etc/holoscan/app.json#apiVersion)。

  • 清单模式版本应作为语义版本字符串提供。

  • 如果未提供，则应假定默认值 0.0.0。

• 应用程序清单应定义用于创建应用程序的 SDK (/etc/holoscan/app.json#sdk)。

• 应用程序清单应定义用于创建应用程序的 SDK 版本 (/etc/holoscan/app.json#sdkVersion)。

  • SDK 版本应作为语义版本字符串提供。

  • 如果未提供，则应假定默认值 0.0.0。

• 应用程序清单应定义应用程序自身的版本 (/etc/holoscan/app.json#version)。

  • 应用程序版本应作为语义版本字符串提供。

  • 如果未提供，则应假定默认值 0.0.0。

• 应用程序清单应定义应用程序的工作目录 (/etc/holoscan/app.json#workingDirectory)。

  • 应用程序将在其当前目录设置为此值的情况下执行。

  • 提供的值必须是绝对路径（第一个字符是 /）。

  • 如果未提供，则应假定默认路径 /var/holoscan/。

• 应用程序清单应定义应用程序使用的数据输入路径，该路径相对于工作目录 (/etc/holoscan/app.json#input.path)。

  • 输入路径应是相对于工作目录的相对路径或目录的绝对文件系统路径。

    • 当值是相对文件系统路径（第一个字符不是 /）时，它相对于应用程序的工作目录。

    • 当值是绝对文件系统路径（第一个字符是 /）时，文件系统路径按原样使用。

  • 如果未提供，则应假定默认值 input/。

• 应用程序清单应定义应用程序支持的输入数据格式 (/etc/holoscan/app.json#input.formats)。

  • 可能的值包括但不限于 none、network、file。

• 应用程序清单应定义应用程序使用的输出路径，该路径相对于工作目录 (/etc/holoscan/app.json#output.path)。

  • 输出路径应是相对于工作目录的相对路径或目录的绝对文件系统路径。

    • 当值是相对文件系统路径（第一个字符不是 /）时，它相对于应用程序的工作目录。

    • 当值是绝对文件系统路径（第一个字符是 /）时，文件系统路径按原样使用。

  • 如果未提供，则应假定默认值 output/。

• 应用程序清单应定义应用程序产生的输出数据格式 (/etc/holoscan/app.json#output.format)。

  • 可能的值包括但不限于 none、screen、file、network。

• 应用程序清单应配置检查以确定应用程序是否“就绪”。

  • 应用程序清单应定义要执行的探针类型 (/etc/holoscan/app.json#readiness.type)。

    • 可能的值包括 tcp、grpc、http-get 和 command。

  • 当类型为 command 时，应用程序清单应定义要执行的探针命令 (/etc/holoscan/app.json#readiness.command)。

    • 数据结构预计是字符串数组。

  • 当类型为 grpc、tcp 或 http-get 时，应用程序清单应定义要执行就绪探针的端口。（/etc/holoscan/app.json#readiness.port）

    • 提供的值必须是介于 1 到 65535 之间的有效端口号。（请注意，1024 以下的端口号是仅限 root 用户的特权端口。）

  • 当类型为 http-get 时，应用程序清单应定义要执行就绪探针的路径 (/etc/holoscan/app.json#readiness.path)。

    • 提供的值必须是绝对路径（第一个字符是 /）。

  • 应用程序清单应定义容器启动后、初始化就绪探针之前的秒数。（/etc/holoscan/app.json#readiness.initialDelaySeconds）。

    • 如果未提供，则应假定默认值 0。

  • 应用程序清单应定义执行就绪探针的频率 (/etc/holoscan/app.json#readiness.periodSeconds)。

    • 如果未提供，则应假定默认值 10。

  • 应用程序清单应定义探针超时的秒数 (/etc/holoscan/app.json#readiness.timeoutSeconds)

    • 如果未提供，则应假定默认值 1。

  • 应用程序清单应定义在认为服务未就绪之前要执行探针的次数 (/etc/holoscan/app.json#readiness.failureThreshold)

    • 如果未提供，则应假定默认值 3。

• 应用程序清单应配置检查以确定应用程序是否“存活”。

  • 应用程序清单应定义要执行的探针类型 (/etc/holoscan/app.json#liveness.type)。

    • 可能的值包括 tcp、grpc、http-get 和 command。

  • 当类型为 command 时，应用程序清单应定义要执行的探针命令 (/etc/holoscan/app.json#liveness.command)。

    • 数据结构预计是字符串数组。

  • 当类型为 grpc、tcp 或 http-get 时，应用程序清单应定义要执行存活探针的端口。（/etc/holoscan/app.json#liveness.port）

    • 提供的值必须是介于 1 到 65535 之间的有效端口号。（请注意，1024 以下的端口号是仅限 root 用户的特权端口。）

  • 当类型为 http-get 时，应用程序清单应定义要执行存活探针的路径 (/etc/holoscan/app.json#liveness.path)。

    • 提供的值必须是绝对路径（第一个字符是 /）。

  • 应用程序清单应定义容器启动后、初始化存活探针之前的秒数。（/etc/holoscan/app.json#liveness.initialDelaySeconds）。

    • 如果未提供，则应假定默认值 0。

  • 应用程序清单应定义执行存活探针的频率 (/etc/holoscan/app.json#liveness.periodSeconds)。

    • 如果未提供，则应假定默认值 10。

  • 应用程序清单应定义探针超时的秒数 (/etc/holoscan/app.json#liveness.timeoutSeconds)

    • 如果未提供，则应假定默认值 1。

  • 应用程序清单应定义在认为服务未存活之前要执行探针的次数 (/etc/holoscan/app.json#liveness.failureThreshold)

    • 如果未提供，则应假定默认值 3。

• 应用程序清单应定义应用于应用程序的任何超时 (/etc/holoscan/app.json#timeout)。

  • 当值为 0 时，应禁用超时。

  • 如果未提供，则应假定默认值 0。

• 应用程序清单必须启用应用程序环境变量的规范 (/etc/holoscan/app.json#environment)

  • 数据结构预计是对象的 "name": "value" 成员。

  • 字段名称将是环境变量的名称原文，并且必须符合环境变量和 JSON 字段名称的所有要求。

  • 字段值将是环境变量的值，并且必须符合环境变量的所有要求。

包清单

包清单字段表

包清单文件提供有关 HAP 包布局的信息。它并非旨在作为控制 HAP 的使用方式或 HAP 应用程序的执行方式的机制。

• 包清单必须采用 UTF-8 编码，并使用 JavaScript 对象表示法 (JSON) 格式。

• 包清单应支持 CRLF 或 LF 样式的行尾。

• 包清单应指定包含应用程序的文件夹 (/etc/holoscan/pkg.json#applicationRoot)。

  • 如果未提供，则应假定默认路径 /opt/holoscan/app/。

• 包清单应提供包文件清单模式的版本 (/etc/holoscan/pkg.json#apiVersion)。

  • 清单模式版本应作为语义版本字符串提供。

• 包清单应提供其自身的包版本 (/etc/holoscan/pkg.json#version)。

  • 包版本应作为语义版本字符串提供。

• 包清单应提供用户提供的模型目录路径。( /etc/holoscan/pkg.json#modelRoot)。

  • 提供的值必须是绝对路径（第一个字符是 /）。

  • 如果未提供，则应假定默认路径 /opt/holoscan/models/。

• 包清单应列出应用程序使用的模型 (/etc/holoscan/pkg.json#models)。

  • 模型应按名称定义 (/etc/holoscan/pkg.json#models[*].name)。

    • 模型名称不应包含任何 Unicode 空白字符或控制字符。

    • 模型名称的长度不应超过 128 字节。

  • 如果模型包含在 HAP 本身中，则模型应提供文件系统路径 (/etc/holoscan/pkg.json#models[*].path)。

    • 当值是相对文件系统路径（第一个字符不是 /）时，它相对于 /etc/holoscan/pkg.json#modelRoot 中定义的模型根目录。

    • 当值是绝对文件系统路径（第一个字符是 /）时，文件系统路径按原样使用。

    • 当未提供值时，名称被假定为相对于 /etc/holoscan/pkg.json#modelRoot 中定义的模型根目录的目录名称。

• 包清单应指定执行应用程序和多片段应用程序的片段所需的资源。

  此信息用于在使用兼容的应用程序部署服务运行容器化应用程序时配置资源。

• 经典应用程序或单片段应用程序应在 /etc/holoscan/pkg.json#resource 对象中定义其资源。

  • /etc/holoscan/pkg.json#resource 对象用于整个应用程序。它也可以用作多片段应用程序中所有片段的兜底，如果适用的话。

  • CPU 需求应使用 CPU 核心的十进制计数表示 (/etc/holoscan/pkg.json#resources.cpu)。

  • 可选的 CPU 限制应使用 CPU 核心的十进制计数表示 (/etc/holoscan/pkg.json#resources.cpuLimit)

  • GPU 需求应使用 GPU 的十进制计数表示 (/etc/holoscan/pkg.json#resources.gpu)。

  • 可选的 GPU 限制应使用 GPU 的十进制计数表示 (/etc/holoscan/pkg.json#resources.gpuLimit)

  • 内存需求应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.memory)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 可选的内存限制应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.memoryLimit)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • GPU 内存需求应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.gpuMemory)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 可选的 GPU 内存限制应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.gpuMemoryLimit)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 共享内存需求应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.sharedMemory)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 可选的共享内存限制应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.sharedMemoryLimit)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 整数值必须为正数，且不包含任何位置分隔符。

    • 合法值示例：1、42、2048

    • 非法值示例：-1、1.5、2,048

  • 十进制值必须为正数，四舍五入到最接近的十分位，使用点 (.) 字符分隔整数值和小数值，且不包含任何位置分隔符。

    • 合法值示例：1、1.0、0.5、2.5、1024

    • 非法值示例：1,024、-1.0、3.14

  • 如果未提供，则将假定默认值为 cpu=1、gpu=0、memory="1Gi" 和 sharedMemory="64Mi"。

• 多片段应用程序应在其 /etc/holoscan/pkg.json#resource.fragments.<fragment-name> 对象中定义其资源。

  • 当找不到匹配的 fragment-name 时，将使用 /etc/holoscan/pkg.json#resource 定义。

  • 片段名称 (fragment-name) 不得包含任何 Unicode 空白字符或控制字符。

  • 片段名称 (fragment-name) 的长度不得超过 128 字节。

  • 片段的 CPU 需求应使用 CPU 核心的十进制计数表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.cpu)。

  • 片段的可选 CPU 限制应使用 CPU 核心的十进制计数表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.cpuLimit)。

  • 片段的 GPU 需求应使用 GPU 的十进制计数表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.gpu)。

  • 片段的可选 GPU 限制应使用 GPU 的十进制计数表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.gpuLimit)。

  • 片段的内存需求应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.memory)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 片段的可选内存限制应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.memoryLimit)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 片段的 GPU 内存需求应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.gpuMemory)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 片段的可选 GPU 内存限制应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.gpuMemoryLimit)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 片段的共享内存需求应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.sharedMemory)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 片段的可选共享内存限制应使用十进制值后跟单位表示 (/etc/holoscan/pkg.json#resources.fragments.<fragment-name>.sharedMemoryLimit)。

    • 支持的单位应为兆字节 (MiB) 和吉字节 (GiB)。

      • 示例：1.5Gi、2048Mi

  • 整数值必须为正数，且不包含任何位置分隔符。

    • 合法值示例：1、42、2048

    • 非法值示例：-1、1.5、2,048

  • 十进制值必须为正数，四舍五入到最接近的十分位，使用点 (.) 字符分隔整数值和小数值，且不包含任何位置分隔符。

    • 合法值示例：1、1.0、0.5、2.5、1024

    • 非法值示例：1,024、-1.0、3.14

  • 如果未提供，则将假定默认值为 cpu=1、gpu=0、memory="1Gi" 和 sharedMemory="64Mi"。

• HAP 应打包用户提供的补充应用程序文件。

  • 补充文件应位于 /opt/holoscan/docs/ 文件夹的子文件夹中。

  • 补充文件包括但不限于以下内容

    • README.md

    • License.txt

    • Changelog.txt

    • EULA

    • 文档

    • 第三方许可证

容器行为和交互

HAP 是一个单容器，启动时支持以下定义的行为。

默认行为

当 HAP 从 CLI 或其他方式启动且没有任何参数时，HAP 应执行包含的应用程序。HAP 内部可以使用 Entrypoint、CMD 或两者的组合。

清单导出

HAP 应提供至少一种方法来访问嵌入式应用程序、模型、许可证、README 或清单文件，即 app.json 和 package.json。

• 该方法应提供一个容器命令 show，用于将一个或多个清单文件打印到控制台。

• 该方法应提供一个容器命令 export，用于将一个或多个清单文件复制到已挂载的卷路径，如下所述

  • /var/run/holoscan/export/app/：检测到时，该方法会将 /opt/holoscan/app/ 的内容复制到该文件夹。

  • /var/run/holoscan/export/config/：检测到时，该方法会将 /var/holoscan/app.yaml、/etc/holoscan/app.json 和 /etc/holoscan/pkg.json 复制到该文件夹。

  • /var/run/holoscan/export/models/：检测到时，该方法会将 /opt/holoscan/models/ 的内容复制到该文件夹。

  • /var/run/holoscan/export/docs/：检测到时，该方法会将 /opt/holoscan/docs/ 的内容复制到该文件夹。

  • /var/run/holoscan/export/：当检测到但未检测到上述任何内容时，该方法应复制上述所有内容。

由于 HAP 是一个符合 OCI 标准的容器，因此用户还可以运行 HAP 并登录到交互式 shell，方法是使用容器引擎及其命令行界面支持的方法；例如，Docker 通过设置 entrypoint 选项来支持这一点。然后可以使用 shell 命令或脚本打开或复制 HAP 中的文件到映射的卷。HAP 的特定实现可以选择使用脚本和适用的用户文档来简化此过程。

重要路径表

Holoscan SDK 支持以下运行环境。