用户手册¶

本文档提供2种方法接入NPU Runners。 Github App使得同一个组织内的仓库只需配置一次即可接入NPU Runners，但是安装Github App需要联系组织管理员处理。而Personal access tokens (classic)允许用户配置单个仓库，无需组织管理员同意。

通过 GitHub App 安装¶

准备工作¶

需要具备组织的管理权限.

安装 Github App¶

浏览器访问apps/ascend-runner-mgmt并且点击Install。 alt text 选择组织，选择仓库，点击Install。

配置Runner group¶

依次点击组织的Settings, Actions, Runner groups, New runner group，进入创建页面。 alt text

在新建页面配置仓库和workflow。保存Group name，稍后会用到。如果想让public仓库接入NPU Runners，必须点击Allow public repositories。 alt text

提交申请激活应用¶

浏览器输入https://github.com/ascend-gha-runners/org-archive/issues，点击New issue选择模板。

Add Or Modify Organizaiton表示新建或者更新组织配置。
Delete Organization表示删除组织。

alt text

添加或者修改组织¶

填写配置参数后点击Create。 org-name表示您的组织名称。 runner-group-name表示Runner group的名称。 npu-counts表示NPU Runners挂载的NPU卡数量。 alt text

删除组织¶

填写配置参数后点击Create。 org-name表示您的组织名称。 alt text

通过 Personal access tokens (classic) 安装¶

准备工作¶

需要具备仓库的访问权限。公共仓库和私有仓库都可以通过PAT接入NPU Runners。

生成 token¶

依次点击个人账户的Settings, Developer settings, Personal access tokens, Tokens (classic), Generate new token, Generate new token (classic)。填写名称，选择过期时间，点击repo，点击Generate token，即生成token。 alt text

提交申请激活应用¶

考虑到token保密需求，申请方式是向gouzhonglin@huawei.com发送邮件。邮件主题模板：Request Ascend NPU Runners 邮件内容模板：

repo: my-org/my-repo
token: ghp_xxx
expire-at: 30days

使用¶

NPU Runners命名规范¶

NPU Runners由以下部分组成：

linux-amd64-npu-x
^     ^     ^   ^
|     |     |   |
|     |     |   Number of NPUs Available
|     |     NPU Designator
|     Architecture
Operating System

查看 NPU Runners¶

通过归档文件查看¶

我们在https://github.com/ascend-gha-runners/org-archive/tree/main/org-archive/目录维护接入NPU Runners的所有组织的最新配置状态。在<your-org>.yaml中查看您的组织。其中online-runners字段展示NPU Runners。

通过Runner group查看¶

依次点击组织的Settings, Actions, Runner groups。在自己配置的runner group里就能看到runners，比如图中的linux-arm64-npu-1, linux-arm64-npu-2。 alt text

在workflow中使用NPU Runners¶

NPU jobs必须运行在容器中(比如：ascendai/cann:latest)。如果未指定容器，则job不会调用NPU资源。以下例子展示Github Action workflow如何使用NPU Runners。

name: Test NPU Runner
on:
  workflow_dispatch:
jobs:
  job_0:
    runs-on: linux-arm64-npu-1
    container:
      image: ascendai/cann:latest

    steps:
      - name: Show NPU info
        run: |
          npu-smi info

如果有任何问题，请提出discussion。