axisecp/acap-runtime

ACAP Runtime

ACAP Runtime是一种基于网络协议的服务，使用[gRPC][gRPC]实现。这使得该服务可被同一设备上不同语言编写的客户端访问。ACAP Runtime的详细说明也可在https://axiscommunications.github.io/acap-documentation/docs/api/computer-vision-sdk-apis.html#beta---acap-runtime中找到。

如果您刚接触ACAP，建议先查看https://axiscommunications.github.io/acap-documentation/docs/introduction/what-is-acap.html

目录

• 概述
  • 要求
  • API
• 安装和使用
  • 安装
    • 原生ACAP应用
    • 容器化版本
  • 配置
    • 原生ACAP应用
    • 容器化版本
    • 芯片ID
    • TLS
    • gRPC套接字
  • 示例
• 构建ACAP Runtime
  • 原生ACAP应用
  • 容器化版本
• 测试套件
• 贡献
• 许可证

概述

ACAP Runtime提供基于网络协议的服务，通过gRPC公开多个API。启动后，ACAP Runtime运行gRPC服务器，可被任何gRPC兼容语言编写的客户端应用访问。有关gRPC协议和客户端编写的更多信息，请参见[https://grpc.io/%5D%5BgRPC%5D%E3%80%82

!ACAP Runtime服务与gRPC客户端

ACAP Runtime可作为标准原生ACAP应用安装在设备上，也提供容器化版本，可在设备上以容器形式运行。前者主要适用于https://axiscommunications.github.io/acap-documentation/docs/introduction/acap-sdk-overview.html#acap-native-sdk，后者旨在与https://axiscommunications.github.io/acap-documentation/docs/introduction/acap-sdk-overview.html#acap-computer-vision-sdk配合使用，需要设备上安装https://github.com/AxisCommunications/docker-ac。容器化版本提供更多配置选项，详情见安装和使用中的相应配置小节。

注意

ACAP Runtime服务可启用或禁用TLS认证。禁用TLS认证极不安全，强烈建议启用TLS。 有关使用ACAP Runtime时生成TLS证书的信息，请参见TLS。

要求

需满足以下要求：

• Axis设备：

  • ACAP Runtime作为ACAP应用可安装在任何ACAP Native SDK支持的设备上。详见https://axiscommunications.github.io/acap-documentation/docs/axis-devices-and-compatibility#sdk-and-device-compatibility。
  • ACAP Runtime容器化版本还需安装并运行https://github.com/AxisCommunications/docker-ac。
  • AXIS OS 10.7或更高版本。
  • 如使用TLS，需证书文件。

• 计算机：

  • Docker Desktop 4.11.1或更高版本，或Docker Engine 20.10.17或更高版本，并启用BuildKit。

API

ACAP Runtime服务提供以下API：

• 机器学习API - [Tensorflow Serving][tensorflow]的实现。机器学习API的使用示例有[Python][minimal-ml-inference]和[C++][object-detector-cpp]版本。
• 参数API - 提供gRPC读取Axis设备参数的访问权限。参数API的使用示例有[Python][parameter-api-python]和[C++][paramter-api-cpp]版本。
• 视频捕获API - 支持从摄像头捕获图像。目前尚无该API的使用示例。

安装和使用

安装

ACAP Runtime的两种变体（原生ACAP应用和容器化版本）均在[Docker Hub][docker-hub-acap-runtime]上提供预构建镜像，推荐通过这些镜像安装和使用ACAP Runtime。

原生ACAP应用

安装时使用[axisecp/acap-runtime][docker-hub-acap-runtime]中标签格式为<version>-<ARCH>的镜像，其中<version>是ACAP Runtime的版本号，<ARCH>根据设备架构为armv7hf或aarch64（例如1.1.2-armv7hf）。运行该镜像会将ACAP Runtime作为ACAP应用安装在设备上，可在设备GUI的“应用”选项卡中控制。

sh
# 安装预构建镜像
docker run --rm docker.xuanyuan.run/axisecp/acap-runtime:<version>-<ARCH> <设备IP> <设备密码> install

其中<设备IP>是设备的IP地址，<设备密码>是root用户的密码。

安装后，可通过设备GUI的“应用”选项卡启动应用，或运行以下命令：

sh
docker run --rm docker.xuanyuan.run/axisecp/acap-runtime:<version>-<ARCH> <设备IP> <设备密码> start

应用日志可通过设备GUI中应用下拉菜单的“应用日志”查看，或直接访问：

sh
http://<设备IP>/axis-cgi/admin/systemlog.cgi?appname=acapruntime

可通过设备GUI或以下命令停止和卸载应用：

sh
docker run --rm docker.xuanyuan.run/axisecp/acap-runtime:<version>-<ARCH> <设备IP> <设备密码> stop
docker run --rm docker.xuanyuan.run/axisecp/acap-runtime:<version>-<ARCH> <设备IP> <设备密码> remove

容器化版本

标准ACAP Runtime Docker镜像将服务安装为ACAP应用，而容器化版本允许在设备上以容器形式运行。需确保设备已安装并运行https://github.com/AxisCommunications/docker-ac。

预构建的容器化镜像在[axisecp/acap-runtime][docker-hub-acap-runtime]上，标签格式为<version>-<ARCH>-containerized。要在项目中包含容器化ACAP Runtime服务器，可在项目的docker-compose.yml文件中添加该镜像。以下是使用armv7hf架构镜像的示例配置，完整说明见示例。

yml
version: '3.3'
services:
    acap-runtime-server:
      image: docker.xuanyuan.run/axisecp/acap-runtime:1.1.2-armv7hf-containerized
      entrypoint: ["/opt/app/acap_runtime/acapruntime", "-o", "-j", "4"]

    acap-runtime-client:
        image: docker.xuanyuan.run/<客户端应用镜像>
        environment:
            - INFERENCE_HOST=unix:///tmp/acap-runtime.sock
            - INFERENCE_PORT=0
    <其他应用>

配置

原生ACAP应用

要修改ACAP Runtime服务的配置，可使用设备GUI中应用下拉菜单的设置选项。注意，修改后需重启应用生效。

可用设置如下：

text
Verbose     启用扩展日志，默认'否'，
IpPort      gRPC服务器的IP端口。见注1，
Use TLS     启用SSL/TLS，默认'是'。见注2，
ChipId      机器学习API服务使用的芯片ID。见注3。

注：

(1) gRPC服务器可配置为unix套接字（默认）或网络套接字。要配置为网络套接字，需将IpPort设为非零值，此时套接字IP地址为0.0.0.0:。详见gRPC套接字。

(2) 使用TLS需提供证书文件和对应私钥文件。若任一文件缺失或设备设置中Use TLS为'否'，则不使用TLS。详见TLS。

(3) 使用机器学习API时，需提供设备对应的芯片ID。详见芯片ID。

容器化版本

从命令行启动ACAP Runtime服务（如容器化版本）时，支持以下设置：

text
-v                详细模式，启用扩展日志，
-a <IP地址>   gRPC服务器的IP地址，默认0.0.0.0。见注1，
-p <IP端口>      gRPC服务器的IP端口，默认0。见注1，
-t <秒数>      运行时间（用于测试），
-c <文件名>    TLS认证的证书文件。见注2，
-k <文件名>    TLS认证的私钥文件。见注2，
-j <芯片ID>      机器学习API服务使用的芯片ID。见注3，
-m <文件名>    机器学习API服务使用的推理模型文件，
-o                覆盖设备参数设置。见注4，

注：

(1) gRPC服务器可配置为unix套接字（默认）或网络套接字。要配置为网络套接字，需将IP端口设为非零值。IP地址仅在网络套接字模式下使用。详见gRPC套接字。

(2) 使用TLS需提供证书文件和对应私钥文件。若任一文件缺失，则不使用TLS。详见TLS。

(3) 使用机器学习API时，需提供设备对应的芯片ID。详见芯片ID。

(4) 若设备上已安装ACAP Runtime原生应用，设备参数也会生效。设置-o标志将覆盖-v、-p、-j、-c和-k设置（若对应设备参数值有效）。此设置主要用于调试/测试，不建议生产环境使用。

芯片ID

机器学习API使用https://axiscommunications.github.io/acap-documentation/docs/api/native-sdk-api.html#machine-learning-api进行图像处理，需选择设备对应的正确芯片ID。注意芯片ID与架构无直接关联。为方便使用，ACAP Runtime原生应用的预构建镜像默认将armv7hf架构的ChipId设为4，aarch64设为12（当前各架构最常用ID）。支持的芯片ID如下表：

若值设为0（LAROD_CHIP_INVALID），机器学习API推理服务将不会启动。

TLS

ACAP Runtime服务可运行在TLS认证模式或非安全模式。TLS认证模式提供gRPC通道的额外安全和加密，是推荐（默认）模式。服务在TLS认证模式下运行需证书文件和密钥文件，默认应放置在已安装应用的根目录，例如：

sh
/usr/local/packages/acapruntime/server.pem
/usr/local/packages/acapruntime/server.key

生成证书的一种方法是使用[openssl req][openssl-req]命令，例如：

sh
# 生成文件
openssl req -x509 \
            -batch \
            -subj '/CN=localhost' \
            -days <有效期天数> \
            -newkey rsa:4096 \
            -nodes \
            -out server.pem \
            -keyout server.key

其中<有效期天数>是证书的有效天数。

将ACAP Runtime作为ACAP应用使用时，需在主机生成文件并传输到设备：

sh
# 复制文件到设备
scp server.pem server.key root@<设备IP>:/usr/local/packages/acapruntime
# 在设备上设置文件所有权
ssh root@<设备IP> 'chown sdk /usr/local/packages/acapruntime/server.*'

其中<设备IP>是设备的IP地址。

gRPC套接字

默认情况下，ACAP Runtime服务使用Unix域套接字（UDS），地址为：

sh
unix:///tmp/acap-runtime.sock

此配置适用于设备本地项目。如需使用网络套接字，ACAP应用可通过IpPort设备参数配置，容器化版本可通过-a和-p设置配置。

示例

以下示例使用参数API和ACAP Runtime原生应用：

• [parameter-api-cpp][paramter-api-cpp]
• [parameter-api-python][parameter-api-python]

以下示例使用ACAP Runtime容器化版本和机器学习API服务：

• [minimal-ml-inference][minimal-ml-inference]
• [object-detector-cpp][object-detector-cpp]

构建ACAP Runtime

本仓库提供用于构建ACAP Runtime的Dockerfile。

原生ACAP应用

要构建原生ACAP应用，使用Dockerfile.armv7hf或Dockerfile.aarch64，选择与设备架构匹配的文件：

sh
# 构建ACAP Runtime镜像
docker build --file Dockerfile.<ARCH> --tag acap-runtime:<ARCH> .

其中<ARCH>为armv7hf或aarch64。

构建基于[axisecp/acap-native-sdk][docker-hub-acap-native-sdk]。如需使用不同于主分支的版本，可通过构建参数VERSION和UBUNTU_VERSION选择特定标签的acap-native-sdk镜像。例如，使用[axisecp/acap-native-sdk:1.4_beta1-armv7hf-ubuntu22.04][docker-hub-acap-native-sdk-1.4_beta1-armv7hf-ubuntu22.04]：

sh
docker build --file Dockerfile.<ARCH> --tag acap-runtime:<ARCH> --build-arg VERSION=1.4beta1 --build-arg UBUNTU_VERSION=22.04 .

容器化版本

要构建容器化版本，使用Dockerfile.armv7hf-containerized或Dockerfile.aarch64-containerized：

sh
# 构建ACAP Runtime容器化版本
docker build --file Dockerfile.<ARCH>-containerized --tag acap-runtime:<ARCH>-containerized .

构建会拉取标签为<BUILDVERSION>-<ARCH>的预构建[axisecp/acap-runtime][docker-hub-acap-runtime]镜像。如需使用本地构建的ACAP Runtime镜像，可重新标记或更新Dockerfile。注意基础镜像是Ubuntu，其版本（构建参数RUNTIME_UBUNTU_VERSION）必须与ACAP Runtime镜像基于的ACAP native sdk镜像版本匹配。

测试套件

本仓库包含测试套件项目，用于验证ACAP Runtime在支持设备上的功能。测试套件构建为独立ACAP应用Acapruntimetest并执行。

构建和安装命令如下：

sh
# 构建ACAP Runtime测试套件镜像
docker build --file Dockerfile.<ARCH> --tag acap-runtime:<ARCH>-test --build-arg TEST=yes .

docker run --rm docker.xuanyuan.run/acap-runtime:<ARCH>-test <设备IP> <设备密码> install

其中<ARCH>为armv7hf或aarch64，<设备IP>和<设备密码>是所用设备的IP和root密码。

可通过设备GUI的“应用”选项卡或以下命令启动、停止和卸载应用：

sh
docker run --rm docker.xuanyuan.run/acap-runtime:<ARCH>-test <设备IP> <设备密码> start|stop|remove

测试运行输出可通过设备GUI的“应用日志”链接查看，或直接访问：

sh
http://<设备IP>/axis-cgi/admin/systemlog.cgi?appname=acapruntimetest

测试通过时，日志以[ PASSED ]结束；若有测试失败，将列出失败项。

贡献

详见CONTRIBUTING.md文件。

许可证

Apache 2.0