导言

目标读者

本书《TensorStack AI 计算平台 - 用户使用手册》 的目标读者是 “TensorStack AI 计算平台” 的使用者，包括：

• AI 研究人员
• 建模工程师
• 数据处理工程师
• 机器学习工程师
• AI 应用开发工程师等

系统管理员、运维人员需要参考另外的《TensorStack AI 计算平台 - 管理员手册》系列。

如何使用

概述 介绍了产品的基本功能和使用模式。

用户首次使用可以跟从快速开始的内容，快速完成基本的体验。

然后，用户可以阅读 AI 开发和应用章节，以学习 AI 开发相关的概念。

其他章节内容如下：

• 账户和安全 讨论用户账户和系统安全问题。
• 计算资源 讨论如何使用集群计算资源。
• 存储 章节对平台的存储方面的支持进行了说明。
• 辅助 章节描述平台提供的一些重要辅助功能，例如如何处理敏感秘密信息，打包容器镜像等。
• 命令行工具和 SDK 讨论 TensorStack 平台的提供的命令行工具和 Python SDK 。
• 操作示例 章节提供了一些具体的操作指南。
• 参考 章节对 API 提供了完整的描述。
• 示例 章节提供了一些具体的应用示例，特别是对 LLM 领域的场景提供了全面的支持演示。
• 集成 章节讨论了一些优秀的第三方工具在 TensorStack 平台上的集成及使用。
• 附录1：背景 介绍了产品的技术架构和设计思路等。

“TensorStack AI 计算平台” 是一个功能强大且灵活的产品，支持在大规模（10^3 节点）集群上进行各种 AI 场景的计算。用户在一定的时间的学习、使用、探索、积累之后，就能对其功能有深入的理解，并在上面完成各种优秀的工作。

本手册使用的例子一般存放在下列 repos：

• https://github.com/t9k/examples
• https://github.com/t9k/tutorial-examples

反馈

非常欢迎各种反馈，可在 Github Issues 页面 创建 issue。

版权声明

© 2023-2024 TensorStack.

本书/网站的内容版权由 TensorStack 所有，欢迎使用。

概述

产品介绍

“TensorStack AI 计算平台” 是面向 AI 集群的系统软件，针对 AI 集群的硬件架构和 AI 领域的计算任务的特性和需求，提供稳定、可扩展的 AI 技术平台能力，服务 AI 技术研发和规模化落地。

AI 集群的拥有者可以使用这套软件，构建自己的 “AI 私有云” 或 “AI 混合云” 基础设施服务。

通过先进的架构和丰富的 API + 系统服务，“TensorStack AI 计算平台” 合理地隐藏了分布式并行、异构计算、加速计算等技术的复杂细节，提高了抽象层次，并为 AI 领域的各种计算提供了针对性的支持，极大地提升了 AI 技术研究、开发、应用的工作效率。

基本流程

用户使用 “TensorStack AI 计算平台” 的基本交互流程：

1. 管理员 - 创建 - 项目（Project）并设定项目管理员。
   • 用户以项目管理员或者普通成员的方式使用项目。
   • 用户可以同时使用多个项目。
2. 管理员 - 创建 - 用户帐户。
3. 用户 - 使用其帐户 - 登录系统。
4. 用户 - 在项目中 - 完成工作（创建各种计算任务）。

使用功能

用户主要通过创建各种类型 CRD 的实例（instance）使用产品的功能。例如：

• 创建一个 Notebook CRD 的实例，以使用 Jupyter Notebook；
• 为了使用 DeepSpeed 进行大规模并行的 LLM 预训练，创建一个 DeepSpeedJob CRD 的实例；
• 为了部署一个模型推理服务，并支持服务规模的自动伸缩，创建一个 MLService CRD 的实例；

CLI

CRD 实例（instance）的创建总是可以通过命令行实现，例如使用 kubectl 可以方便的创建一个 Notebook：

# create a notebook
kubectle create -f notebook-tutorial.yaml 

# notebook-tutorial.yaml
apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
  name: tutorial
spec:
  type: jupyter
  template:
    spec:
      containers:
        - name: notebook
          image: t9kpublic/torch-2.1.0-notebook:1.77.1
          volumeMounts:
            - name: workingdir
              mountPath: /t9k/mnt
          resources:
            requests:
              cpu: '8'
              memory: 16Gi
              nvidia.com/gpu: 1
            limits:
              cpu: '16'
              memory: 32Gi
              nvidia.com/gpu: 1
      volumes:
        - name: workingdir
          persistentVolumeClaim:
            claimName: tutorial

UI

对于很多 CRD，TensorStack 的 Web 控制台（console）提供了通过表单（form）创建其实例的方式。

例如，可使用如下表单创建 Notebook 实例：

下一步

• 跟从快速开始的内容，快速完成基本的体验。
• 阅读 AI 开发和应用章节，以学习 AI 开发相关的概念。
• 阅读背景，了解产品的技术架构和设计思路等。

快速入门

欢迎使用“TensorStack AI 平台”！

本节将带领你快速体验 “TensorStack AI 平台” 的基本功能，并完成一个简单的 AI 项目，涵盖模型的构建、训练、部署等。

使用 TensorStack AI 平台之前，你需要：

• 拥有一个账户，以登录系统。
• 成为一个项目的成员，以使用集群资源。

下一步

• 使用 Notebook 训练你的第一个模型
• 使用 Job 进行并行训练
• 使用 SimpleMLService 部署模型

训练你的第一个模型

本教程带领你使用 Notebook，来构建和训练一个 AI 模型。

创建 Notebook

在 TensorStack AI 平台首页，点击模型构建进入构建控制台（Build Console）。

构建控制台（Build Console）的总览页面展示了多种资源，你可以点击右上角的按钮切换 Project，也可以点击事件和配额标签页以查看当前 Project 最近发生的事件以及计算资源（CPU、内存、GPU 等）配额。

创建 PVC

在创建 Notebook 之前，首先需要创建一个用于存储文件的 PVC（持久卷）。在左侧的导航菜单中点击存储 > 持久卷进入 PVC 管理页面，然后点击右上角的创建 PVC。

在 PVC 创建页面，如下填写各个参数：

• Name 填写 mnist。
• Size 填写 1Gi。

其他参数保持默认即可。完成之后，点击创建。

在跳转回到 PVC 管理页面之后，可点击右上角的刷新图标来手动刷新 PVC 状态。下图展示 PVC mnist 已经创建完成。

创建 Notebook

在左侧的导航菜单中点击构建 > Notebook 进入 Notebook 管理页面，然后点击右上角的创建 Notebook。

在 Notebook 创建页面，如下填写各个参数：

• 名称填写 mnist。
• 镜像类型选择 Jupyter，镜像选择 t9kpublic/torch-2.1.0-notebook:1.77.1。
• 存储卷选择 mnist。
• 调度器选择默认调度器，模板选择 large。

完成之后，点击创建。

在跳转回到 Notebook 管理页面之后，等待刚才创建的 Notebook 准备就绪。第一次拉取镜像可能会花费较长的时间，具体取决于集群的网络状况。点击右上角的刷新图标来手动刷新 Notebook 状态，待 Notebook 开始运行之后，点击右侧的打开进入其前端页面。

现在 Notebook 已经可以使用了，你可以在这里进行模型的开发与测试。

使用 Notebook 训练模型

在 Notebook 的前端页面，点击左上角的 +，然后点击 Notebook 下的 Python3 以新建一个 .ipynb 文件。

复制下面的训练脚本到该 .ipynb 文件的代码框中。该脚本基于 PyTorch 框架，建立一个简单的卷积神经网络模型，并使用 MNIST 数据集的手写数字图像进行训练和测试。

import os
import shutil

import torch
import torch.nn as nn
import torch.nn.functional as F
import torch.optim as optim
from torch.utils.tensorboard import SummaryWriter
from torchvision import datasets, transforms


class Net(nn.Module):

    def __init__(self):
        super().__init__()
        self.conv1 = nn.Conv2d(1, 32, 3, 1)
        self.conv2 = nn.Conv2d(32, 64, 3, 1)
        self.conv3 = nn.Conv2d(64, 64, 3, 1)
        self.pool = nn.MaxPool2d(2, 2)
        self.dense1 = nn.Linear(576, 64)
        self.dense2 = nn.Linear(64, 10)

    def forward(self, x):
        x = self.pool(F.relu(self.conv1(x)))
        x = self.pool(F.relu(self.conv2(x)))
        x = F.relu(self.conv3(x))
        x = torch.flatten(x, 1)
        x = F.relu(self.dense1(x))
        output = F.softmax(self.dense2(x), dim=1)
        return output


def train():
    global global_step
    for epoch in range(1, epochs + 1):
        model.train()
        for step, (data, target) in enumerate(train_loader, 1):
            data, target = data.to(device), target.to(device)
            optimizer.zero_grad()
            output = model(data)
            loss = criterion(output, target)
            loss.backward()
            optimizer.step()

            if step % 500 == 0:
                train_loss = loss.item()
                print('epoch {:d}/{:d}, batch {:5d}/{:d} with loss: {:.4f}'.
                      format(epoch, epochs, step, steps_per_epoch, train_loss))
                global_step = (epoch - 1) * steps_per_epoch + step

                writer.add_scalar('train/loss', train_loss, global_step)

        scheduler.step()
        global_step = epoch * steps_per_epoch
        test(val=True, epoch=epoch)


def test(val=False, epoch=None):
    label = 'val' if val else 'test'
    model.eval()
    running_loss = 0.0
    correct = 0

    with torch.no_grad():
        loader = val_loader if val else test_loader
        for data, target in loader:
            data, target = data.to(device), target.to(device)
            output = model(data)
            loss = criterion(output, target)
            running_loss += loss.item()
            prediction = output.max(1)[1]
            correct += (prediction == target).sum().item()

    test_loss = running_loss / len(loader)
    test_accuracy = correct / len(loader.dataset)
    msg = '{:s} loss: {:.4f}, {:s} accuracy: {:.4f}'.format(
        label, test_loss, label, test_accuracy)
    if val:
        msg = 'epoch {:d}/{:d} with '.format(epoch, epochs) + msg
    print(msg)

    writer.add_scalar('{:s}/loss'.format(label), test_loss, global_step)
    writer.add_scalar('{:s}/accuracy'.format(label), test_accuracy,
                      global_step)


device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
kwargs = {
    'num_workers': 1,
    'pin_memory': True
} if torch.cuda.is_available() else {}

torch.manual_seed(1)

model = Net().to(device)
criterion = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters(), lr=0.001)
scheduler = optim.lr_scheduler.StepLR(optimizer, step_size=1, gamma=0.7)

dataset_path = './data'
transform = transforms.Compose(
    [transforms.ToTensor(),
     transforms.Normalize((0.5), (0.5))])
train_dataset = datasets.MNIST(root=dataset_path,
                               train=True,
                               download=True,
                               transform=transform)
train_dataset, val_dataset = torch.utils.data.random_split(
    train_dataset, [48000, 12000])
test_dataset = datasets.MNIST(root=dataset_path,
                              train=False,
                              download=True,
                              transform=transform)
train_loader = torch.utils.data.DataLoader(train_dataset,
                                           batch_size=32,
                                           shuffle=True,
                                           **kwargs)
val_loader = torch.utils.data.DataLoader(val_dataset,
                                         batch_size=400,
                                         shuffle=False,
                                         **kwargs)
test_loader = torch.utils.data.DataLoader(test_dataset,
                                          batch_size=1000,
                                          shuffle=False,
                                          **kwargs)

log_dir = './log'
if os.path.exists(log_dir):
    shutil.rmtree(log_dir, ignore_errors=True)
writer = SummaryWriter(log_dir)

global_step = 0
epochs = 10
steps_per_epoch = len(train_loader)
train()
test()

torch.save(model.state_dict(), 'model_state_dict.pt')

点击上方的运行按钮，可以看到训练开始进行：

训练结束后，点击左上角的新建文件夹按钮，为新文件夹命名 first-model，并将当前教程产生的所有文件拖拽移动到其中。

下一步

• 针对同样的模型，使用 Job 进行并行训练
• 全面了解模型构建

进行并行训练

本教程带领你使用 PyTorchTrainingJob，将教程训练你的第一个模型中的模型训练改进为使用 GPU 加速的数据并行训练。

在 Notebook 中准备并行训练

回到 Notebook mnist，在 HOME 目录（即左侧边栏文件浏览器显示的根目录 /）下，点击左上角的 +，然后点击 Other 下的 Python File 以新建一个 Python 脚本文件。

向该文件复制以下代码，并将其命名为 torch_mnist_trainingjob.py。该脚本在上一篇教程的脚本的基础上进行了修改以支持数据并行训练。

import argparse
import logging
import os
import shutil

import torch
import torch.distributed as dist
import torch.nn as nn
import torch.nn.functional as F
from torch.nn.parallel import DistributedDataParallel as DDP
import torch.optim as optim
from torch.utils.tensorboard import SummaryWriter
from torchvision import datasets, transforms

parser = argparse.ArgumentParser(
    description='DDP training of PyTorch model for MNIST.')
parser.add_argument(
    '--backend',
    type=str,
    help='Distributed backend',
    choices=[dist.Backend.GLOO, dist.Backend.NCCL, dist.Backend.MPI],
    default=dist.Backend.GLOO)
parser.add_argument('--log_dir',
                    type=str,
                    help='Path of the TensorBoard log directory.')
parser.add_argument('--save_path',
                    type=str,
                    help='Path of the saved model.')
parser.add_argument('--no_cuda',
                    action='store_true',
                    default=False,
                    help='Disable CUDA training.')
logging.basicConfig(format='%(message)s', level=logging.INFO)


class Net(nn.Module):

    def __init__(self):
        super().__init__()
        self.conv1 = nn.Conv2d(1, 32, 3, 1)
        self.conv2 = nn.Conv2d(32, 64, 3, 1)
        self.conv3 = nn.Conv2d(64, 64, 3, 1)
        self.pool = nn.MaxPool2d(2, 2)
        self.dense1 = nn.Linear(576, 64)
        self.dense2 = nn.Linear(64, 10)

    def forward(self, x):
        x = self.pool(F.relu(self.conv1(x)))
        x = self.pool(F.relu(self.conv2(x)))
        x = F.relu(self.conv3(x))
        x = torch.flatten(x, 1)
        x = F.relu(self.dense1(x))
        output = F.softmax(self.dense2(x), dim=1)
        return output


def train():
    global global_step
    for epoch in range(1, epochs + 1):
        model.train()
        for step, (data, target) in enumerate(train_loader, 1):
            data, target = data.to(device), target.to(device)
            optimizer.zero_grad()
            output = model(data)
            loss = criterion(output, target)
            loss.backward()
            optimizer.step()

            if step % (500 // world_size) == 0:
                train_loss = loss.item()
                logging.info(
                    'epoch {:d}/{:d}, batch {:5d}/{:d} with loss: {:.4f}'.
                    format(epoch, epochs, step, steps_per_epoch, train_loss))
                global_step = (epoch - 1) * steps_per_epoch + step

                if args.log_dir and rank == 0:
                    writer.add_scalar('train/loss', train_loss, global_step)

        scheduler.step()
        global_step = epoch * steps_per_epoch
        test(val=True, epoch=epoch)


def test(val=False, epoch=None):
    label = 'val' if val else 'test'
    model.eval()
    running_loss = 0.0
    correct = 0

    with torch.no_grad():
        loader = val_loader if val else test_loader
        for data, target in loader:
            data, target = data.to(device), target.to(device)
            output = model(data)
            loss = criterion(output, target)
            running_loss += loss.item()
            prediction = output.max(1)[1]
            correct += (prediction == target).sum().item()

    test_loss = running_loss / len(loader)
    test_accuracy = correct / len(loader.dataset)
    msg = '{:s} loss: {:.4f}, {:s} accuracy: {:.4f}'.format(
        label, test_loss, label, test_accuracy)
    if val:
        msg = 'epoch {:d}/{:d} with '.format(epoch, epochs) + msg
    logging.info(msg)

    if args.log_dir and rank == 0:
        writer.add_scalar('{:s}/loss'.format(label), test_loss, global_step)
        writer.add_scalar('{:s}/accuracy'.format(label), test_accuracy,
                          global_step)


if __name__ == '__main__':
    args = parser.parse_args()

    logging.info('Using distributed PyTorch with %s backend', args.backend)
    dist.init_process_group(backend=args.backend)
    rank = dist.get_rank()
    world_size = dist.get_world_size()
    local_rank = int(os.environ['LOCAL_RANK'])

    use_cuda = not args.no_cuda and torch.cuda.is_available()
    if use_cuda:
        logging.info('Using CUDA')
    device = torch.device('cuda:{}'.format(local_rank) if use_cuda else 'cpu')
    kwargs = {'num_workers': 1, 'pin_memory': True} if use_cuda else {}

    torch.manual_seed(1)

    dataset_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),
                                'data')
    # rank 0 downloads datasets in advance
    if rank == 0:
        datasets.MNIST(root=dataset_path, train=True, download=True)

    model = Net().to(device)
    model = DDP(model)
    criterion = nn.CrossEntropyLoss()
    optimizer = optim.Adam(model.parameters(), lr=0.001 * world_size)
    scheduler = optim.lr_scheduler.StepLR(optimizer, step_size=1, gamma=0.7)

    transform = transforms.Compose(
        [transforms.ToTensor(),
         transforms.Normalize((0.5), (0.5))])
    train_dataset = datasets.MNIST(root=dataset_path,
                                   train=True,
                                   download=False,
                                   transform=transform)
    train_dataset, val_dataset = torch.utils.data.random_split(
        train_dataset, [48000, 12000])
    test_dataset = datasets.MNIST(root=dataset_path,
                                  train=False,
                                  download=False,
                                  transform=transform)
    train_loader = torch.utils.data.DataLoader(train_dataset,
                                               batch_size=32 * world_size,
                                               shuffle=True,
                                               **kwargs)
    val_loader = torch.utils.data.DataLoader(val_dataset,
                                             batch_size=400,
                                             shuffle=False,
                                             **kwargs)
    test_loader = torch.utils.data.DataLoader(test_dataset,
                                              batch_size=1000,
                                              shuffle=False,
                                              **kwargs)

    if args.log_dir and rank == 0:
        if os.path.exists(args.log_dir):
            shutil.rmtree(args.log_dir, ignore_errors=True)
        writer = SummaryWriter(args.log_dir)

    global_step = 0
    epochs = 10
    steps_per_epoch = len(train_loader)
    train()
    test()

    if rank == 0:
        torch.save(model.state_dict(), args.save_path)

创建 Job 进行并行训练

回到模型构建控制台，在左侧的导航菜单中点击构建 > Job 进入 Job 管理页面，然后点击右上角的创建 Job > PyTorch。

为了简化操作，在 Job 创建页面，点击预览 YAML，然后直接复制下面的 YAML 配置文件并粘贴到编辑框中，然后点击创建。

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: mnist                    # Job 名称
spec:
  tensorboardSpec:               # TensorBoard 服务器规约
    resources:
      limits:
        cpu: 1
        memory: 1Gi
    trainingLogFilesets:
      - t9k://pvc/mnist/log      # 日志文件路径
    image: tensorflow/tensorflow:2.14.0
                                 # TensorBoard 服务器使用的镜像
  torchrunConfig:
    enabled: true                # torchrun 启动
    maxRestarts: 3
    procPerNode: "4"             # 每个副本启动的进程数
    rdzvBackend: c10d
    extraOptions: []
  replicaSpecs:
    - type: node
      replicas: 1                # 副本数
      restartPolicy: ExitCode
      template:
        spec:
          securityContext:
            runAsUser: 1000
          containers:
            - name: pytorch
              image: t9kpublic/pytorch-1.13.0:sdk-0.5.2
                                       # 容器的镜像
              workingDir: /t9k/mnt     # 工作路径
              args:                    # `python`命令的参数
                - torch_mnist_trainingjob.py
                - "--log_dir"
                - "log"
                - "--save_path"
                - "./model_state_dict.pt"
                - "--backend"
                - "nccl"
              resources:               # 计算资源
                limits:                # 限制量
                  cpu: 8               # CPU
                  memory: 16Gi         # 内存
                  nvidia.com/gpu: 4    # GPU
                requests:              # 请求量
                  cpu: 4
                  memory: 8Gi
                  nvidia.com/gpu: 4
              volumeMounts:
                - name: data
                  mountPath: /t9k/mnt  # 挂载路径
                - name: dshm
                  mountPath: /dev/shm  # 挂载共享内存
          volumes:
            - name: data
              persistentVolumeClaim:
                claimName: mnist       # 要挂载的 PVC
            - name: dshm
              emptyDir:
                medium: Memory

在跳转回到 Job 管理页面之后，等待刚才创建的 Job 就绪。第一次拉取镜像可能会花费较长的时间，具体取决于集群的网络状况。点击右上角的刷新图标来手动刷新 Job 状态，待 Job 开始运行之后，点击其名称进入详情页面。

可以看到，Job 及其创建的 4 个 Worker（工作器）正在运行。

切换到副本标签页，点击副本的日志会显示其命令行输出，可以看到并行训练的当前进度。

torch_mnist_trainingjob.py 训练脚本在训练过程中添加了 TensorBoard 回调并将日志保存在了 log 目录下，Job 相应地启动了一个 TensorBoard 服务器用于可视化展示这些数据。点击 TensorBoard 右侧的 Running 进入其前端页面。

一段时间之后，Job 的状态变为 Done，表示训练已经成功完成。回到 Notebook mnist，将当前教程产生的所有文件移动到名为 parallel-training 的新文件夹下。

下一步

• 将训练完成的模型部署为推理服务
• 了解 Job
• 进一步学习如何进行并行训练
• 学习如何进行超参数优化

部署模型

本教程带领你使用 SimpleMLService，部署模型为推理服务。

在教程训练你的第一个模型和进行并行训练中，训练完成的模型都被保存为文件 model_state_dict.pt，这两个模型文件所对应的模型是相同的。本教程将部署这个模型为推理服务。

准备模型文件

这里我们使用 TorchServe 部署 PyTorch 模型。回到 Notebook mnist，在 HOME 目录（即左侧边栏文件浏览器显示的根目录 /）下新建以下文件：

import torch
from torch import nn
import torch.nn.functional as F


class Net(nn.Module):

    def __init__(self):
        super(Net, self).__init__()
        self.conv1 = nn.Conv2d(1, 32, 3, 1)
        self.conv2 = nn.Conv2d(32, 64, 3, 1)
        self.conv3 = nn.Conv2d(64, 64, 3, 1)
        self.pool = nn.MaxPool2d(2, 2)
        self.dense1 = nn.Linear(576, 64)
        self.dense2 = nn.Linear(64, 10)

    def forward(self, x):
        x = self.pool(F.relu(self.conv1(x)))
        x = self.pool(F.relu(self.conv2(x)))
        x = F.relu(self.conv3(x))
        x = torch.flatten(x, 1)
        x = F.relu(self.dense1(x))
        output = F.log_softmax(self.dense2(x), dim=1)
        return output

from torchvision import transforms
from ts.torch_handler.image_classifier import ImageClassifier
from torch.profiler import ProfilerActivity


class MNISTDigitClassifier(ImageClassifier):
    image_processing = transforms.Compose(
        [transforms.ToTensor(),
         transforms.Normalize((0.5), (0.5))])

    def __init__(self):
        super().__init__()
        self.profiler_args = {
            "activities": [ProfilerActivity.CPU],
            "record_shapes": True,
        }

    # def postprocess(self, data):
    #     return data.argmax(1).tolist()

点击左上角的 +，然后点击 Other 下的 Terminal 以新建一个终端。

执行以下命令以打包一个 torch 的模型包（model archive）：

# 使用 Notebook 中训练的模型
torch-model-archiver --model-name mnist \
  --version 1.0 \
  --model-file model.py \
  --handler handler.py \
  --serialized-file first-model/model_state_dict.pt

# 如果使用 Job 中训练的模型，切换参数
# --serialized-file parallel-training/model_state_dict.pt

部署推理服务

在 TensorStack AI 平台首页，点击Deploy进入模型部署控制台。

模型部署控制台的总览页面展示了当前部署服务的数量以及资源使用情况。在左侧的导航菜单中点击部署 > SimpleMLService，点击右上角的 + 弹出创建对话框，然后复制下面的 YAML 配置文件并粘贴到编辑框中，最后点击创建。

apiVersion: tensorstack.dev/v1beta1
kind: SimpleMLService
metadata:
  name: mnist
spec:
  replicas: 1
  storage:
    pvc:
      containerPath: /var/lib/t9k/models
      name: mnist
      subPath: .
  pytorch:
    image: pytorch/torchserve:0.9.0-cpu
    modelsFlag: "mnist=mnist.mar"
    resources: 
      requests:
        cpu: 1
        memory: 1Gi

在跳转回到 SimpleMLService 管理页面之后，等待刚才创建的 SimpleMLService 准备就绪。

• 第一次拉取镜像可能会花费较长的时间，具体取决于集群的网络状况。
• 点击右上角的刷新按钮以手动刷新 SimpleMLService 状态。

使用推理服务

查看推理服务地址

待 SimpleMLService 就绪之后，点击其名称进入详情页面。

页面中展示的 DNS 即为推理服务地址，注意该地址只能从集群内部访问。

访问推理服务

回到 Notebook mnist，在终端中执行以下命令以下载测试数据，并向推理服务发送请求。注意变量 URL 的值需要修改为实际部署的推理服务的地址。

# 下载测试图像文件
wget https://t9k.github.io/user-manuals/assets/get-started/deployment/{0,1,2}.png

# 注意：此 URL 只适合在集群内当前项目（Project）内部（例如当前项目的 Notebook 中）访问使用
URL="http://mnist.demo.svc.cluster.local/v1/models/mnist:predict"
curl -T 0.png $URL    # 或使用 `1.png`, `2.png`

响应体应是一个类似于下面的 JSON，其预测了图片最有可能是的 5 个数字以及相应的概率：

{
  "0": 1.0,
  "2": 1.7797361302828807e-16,
  "9": 6.094195260341553e-19,
  "6": 1.5410183526346253e-19,
  "5": 7.889719768364669e-20
}

清理

体验结束后，可将当前教程产生的所有文件移动到名为 deployment 的新文件夹下。

也可以将部署的推理服务删除：

# optional, delete service if desired.
kubectl delete SimpleMLService mnist

下一步

• 了解模型部署
• 进一步学习如何部署简单推理服务
• 进一步学习如何部署用于生产环境的模型推理服务

AI 开发和应用

TensorStack AI 平台提供了一套完整、全面的工具和服务，对 AI 模型的构建、训练和部署提供全流程的支持，从而助力研究人员轻松、高效地实现 AI 项目，加速 AI 模型的研究、开发和应用。

下图展示了在平台上开发一个深度学习模型的完整流程，以及各个模块发挥的功能：

下一步

• 学习并使用：模型构建
• 部署模型为推理服务：模型部署
• 在集群中运行大规模计算：Job、工作流
• 系统化 AI 计算的过程：存储 AI 资产、追踪 AI 实验

模型构建

一次完整的模型构建实验由许多步骤组成，包括准备实验数据、开发机器学习算法、选择训练超参数和执行训练等等。

TensorStack AI 平台的模型构建模块可以帮助你在分布式集群中快速方便地完成上述工作。模型构建模块的功能包括：

• Notebook：在线机器学习开发工具，你可以使用此模块直接在平台上开发机器学习脚本。
• TensorBoard：机器学习可视化工具，实现训练过程可视化、模型可视化。
• Job：一类任务型资源，其中包括 TensorFlowTrainingJob、MPIJob 等多种资源，使用各种机器学习框架、通信协议来进行分布式计算。其中 TensorFlowTrainingJob 和 PyTorchTrainingJob 集成了 TensorBoard 的创建功能，可以监控训练进程和查看训练结果。
• AutoTune：超参数调优实验，在给定的搜索空间中查找最优的超参数组合以及机器学习网络结构。AutoTune 在进行超参数调优的过程中需要使用 TrainingJob（根据训练框架选用 TensorFlowTrainingJob、PyTorchTrainingJob 或 XGBoostTrainingJob）对超参数的效果进行验证。

架构

如上图所示：

• TensorStack CLI 是 TensorStack AI 平台所使用的命令行工具，可以用于操作几乎所有 TensorStack AI 平台的模块，包括模型构建。
• Kubernetes API Server 是 Kubernetes 的重要组成部分，负责对外提供接口，接受对集群的操作请求。在此框架中，Kubernetes API Server 需要向模型构建模块提供集群中的资源信息，同时接收资源的创建、删除等请求。
• 红框中的内容为模型构建模块的组成部分：
  • 控制台（Console）：模块的交互界面，你可以通过此界面使用模块的全部功能。
  • 服务器（Server）：模块功能的提供者，为你提供查看、创建、修改和删除资源的接口。
  • 控制器（Controller）：资源控制器，用于处理资源的创建和修改请求。

下一步

• 学习使用 Notebook
• 学习使用 TensorBoard
• 学习使用 T9k Job
• 学习使用 AutoTune

Notebook

JupyterLab 是一款非常流行的机器学习开发工具，它通过友好易用的 Web 界面提供交互式计算环境，支持多种编程语言和执行环境，在机器学习、AI、数据处理、数值模拟、统计建模、数据可视化等领域被广泛使用。

用户可以使用 Notebook CRD 在集群中快速部署一个 JupyterLab 服务，同时本产品还提供 GPU 支持、SSH 访问支持等功能。

创建 Notebook

下面是一个基本的 Notebook 配置示例：

# notebook-tutorial.yaml
apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
  name: tutorial
spec:
  type: jupyter
  template:
    spec:
      containers:
        - name: notebook
          image: t9kpublic/torch-2.1.0-notebook:1.77.1
          volumeMounts:
            - name: workingdir
              mountPath: /t9k/mnt
          resources:
            requests:
              cpu: '8'
              memory: 16Gi
              nvidia.com/gpu: 1
            limits:
              cpu: '16'
              memory: 32Gi
              nvidia.com/gpu: 1
      volumes:
        - name: workingdir
          persistentVolumeClaim:
            claimName: tutorial

在该例中，spec.template.spec 字段定义所要创建的 Pod 的规约：

1. 指示 Pod 运行一个 notebook 容器 （spec.template.containers），该容器运行的镜像是 t9kpublic/torch-2.1.0-notebook:1.77.1，这是一个 Notebook 镜像；
2. 通过 spec.template.spec.volumes，spec.template.containers[].volumeMounts 指示挂载网络文件系统 PVC tutorial 到 /t9k/mnt；
3. 通过 spec.template.spec.containers[].resources 指定使用的 CPU、memory、GPU 资源 。

使用 GPU

Notebook 支持通过申请使用 GPU 资源，例如：

apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
  name: tutorial
spec:
  type: jupyter
  template:
    spec:
      containers:
        - name: notebook
          image: t9kpublic/torch-2.1.0-notebook:1.77.1
          volumeMounts:
            - name: workingdir
              mountPath: /t9k/mnt
          resources:
            limits:
              cpu: '16'
              memory: 32Gi
              nvidia.com/gpu: 1
          command: []
      volumes:
        - name: workingdir
          persistentVolumeClaim:
            claimName: tutorial

在该例中：

• 申请使用 16 个 CPU、32Gi 内存以及一个 NVIDIA GPU；系统会自动将 Notebook 调度到集群中某个能提供这些资源的节点上。

SSH 访问

Notebook 提供运行 SSH Server 的支持。下面的 Notebook 示例运行一个支持 SSH 连接的 JupyterLab 镜像：

apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
  name: tutorial
spec:
  type: jupyter
  template:
    spec:
      containers:
        - name: notebook
          image: t9kpublic/torch-2.1.0-notebook:1.77.1
          volumeMounts:
            - name: workingdir
              mountPath: /t9k/mnt
          resources:
            limits:
              cpu: '16'
              memory: 32Gi
              nvidia.com/gpu: 1
      volumes:
        - name: workingdir
          persistentVolumeClaim:
            claimName: tutorial
  ssh:
    authorized_keys:
      - example-user
    enabled: true
    serviceType: ClusterIP

在该例中，用户：

1. 设置 spec.ssh.enabled 字段的值为 true，T9k 系统将会自动创建一个处理 SSH 请求的 Service；
2. 通过 spec.ssh.serviceType 字段指定服务类型为 ClusterIP；
3. 设置自动挂载存放在 Secret/example-user 中的用户 SSH key；

使用此 SSH 服务需要通过 t9k-pf 工具进行端口转发。

资源回收

T9k 系统提供空闲 Notebook 资源回收的支持。系统在检测到 Notebook 处于空闲状态并超过一定时长时，就会自动删除工作负载以释放计算资源。目前，资源回收仅针对 Jupyter 类型的 Notebook，其他类型（例如 RStudio）的 Notebook 不会被回收。

管理员可设置回收策略，使得：

• Notebook 没有活跃运行超过 1h （管理员可修改此时长）后，标记该 Notebook 为 Idle。
• Notebook 进入 Idle 状态超过 24h （管理员可修改此时长）后，删除该 Notebook 底层工作负载。

如果需要再次使用该 Notebook，你可以在模型构建控制台中手动点击恢复按钮。

Notebook 镜像

T9k 提供了一些预先构建的镜像，与 JupyterLab 原生镜像相比内置了更丰富的工具包，请参阅 Notebook 标准镜像列表。

在这些镜像中：

• 默认启动一个 JupyterLab 服务。
• 预装了 Python3 以及 tensorflow、pytorch、keras、pandas、scikit-learn 等常用 Python 包。
• 身份是一个名为 t9kuser 的非 root 用户（用户 ID 为 1000，组 ID 为 1000），$HOME 目录为 /t9k/mnt。
• 预装了 tensorboard 插件，你可以在网页中创建 TensorBoard 以可视化数据。

用户也可以自行构建镜像，并上载到镜像 registry 中供使用。

下一步

用户可尝试如下功能：

• 创建 Notebook
• 使用 Notebook
• 通过 SSH 远程使用 Notebook

参考

• T9k 提供的 Notebook 标准镜像列表
• JupyterLab 文档

TensorBoard

TensorBoard 是 TensorFlow 提供的一种可视化机器学习过程和结果的工具，功能强大且广泛应用于多种框架。

你可以使用本产品在集群中一键部署 TensorBoard，可视化训练模型。

创建 TensorBoard

下面是一个基本的 TensorBoard 配置示例：

# tensorboard-example.yaml
apiVersion: tensorstack.dev/v1beta1
kind: TensorBoard
metadata:
  name: pytorchtrainingjob-tensorboard
  namespace: t9k-example
spec:
  image: docker.mirrors.ustc.edu.cn/tensorflow/serving:2.6.0-gpu
  trainingLogFilesets:
  - t9k://pvc/pytorchtrainingjob-tensorboard-pvc/log

在该例中，TensorBoard 使用 docker.mirrors.ustc.edu.cn/tensorflow/serving:2.6.0-gpu 镜像，对名为 pytorchtrainingjob-tensorboard-pvc 的 PVC 中 /log 路径下的模型数据进行可视化。

FileSet

FileSet 是一种特殊的资源定位符（URI），是一种用于定位多种存储技术中的资源的字符串。

FileSet 的格式为 t9k://storage-type/storage-identity/path，由下列四部分构成：

• 协议：t9k://。
• 存储器类型：当前 FileSet 支持 PVC（在 FileSet 中写作 pvc） 和 MinIO（在 FileSet 中写作 minio) 两种存储器。
• 存储器定位方式：FileSet 使用 PVC 的名称来定位 PVC 存储器，使用记录了 MinIO 地址、用户名和密码的 Secret 来定位 MinIO 存储器。
• 数据在存储器中的路径：模型在存储器中的准确位置。

下面是两个 FileSet 示例：

• t9k://pvc/pytorchtrainingjob-tensorboard-pvc/log/model 表示：所指向的资源被存储在名为 pytorchtrainingjob-tensorboard-pvc 的 PVC 中的 log/model 路径下。
• t9k://minio/secret-name/bucket1/log/model 表示：所指向的资源被存储在一个 MinIO 中名为 bucket1 的 Bucket 中的 log/model 路径下，该 MinIO 的地址、用户名和密码被存储在名为 secret-name 的 Secret 中。

TrainingJob 自动创建 TensorBoard

我们在 TensorFlowTrainingJob 和 PyTorchTrainingJob 中集成了 TensorBoard 的创建，你可以在创建 TrainingJob 后直接进入 TensorBoard 监控训练进程和查看训练结果。

资源回收

TensorBoard 提供空闲资源回收的支持，在检测到 TensorBoard 处于空闲状态并超过一定时长时，删除工作负载以释放计算资源。默认情况下（管理员可修改配置）：

• TensorBoard 无人使用超过 1h 后，标记该 TensorBoard 为 Idle。
• TensorBoard 进入 Idle 状态超过 24h 后，删除该 TensorBoard 底层工作负载。

如果需要再次使用该 TensorBoard，你可以在模型构建控制台中手动点击恢复按钮。

AutoTune

为了降低 AI 开发门槛和逐渐实现机器学习自动化，TensorStack AI 平台提供了自动化机器学习 （AutoML）工具 AutoTune。AutoTune 具有以下特点：

• 内置最新的自动机器学习算法，为用户自动地进行特征工程、神经网络架构搜索、超参调优和模型压缩。
• 提供可视化展示平台，实时跟踪超参数训练过程，以交互式图形和表格的形式刻画多个不同维度的信息，用户可以借此更好地比较、分析、决策出最优参数。
• 持海量实验数据的存储，让用户轻松地实现任意实验结果之间的比较。
• 融合领先的 AI 最佳实践，提供自动化、准确性和协作水平，提高企业 AI 生产效率。

基本结构

在上述结构图中：

• AutoTune Controller 是 AutoTuneExperiment 的控制器，可以看做是 AutoTune 实验的入口。用户在集群中创建 AutoTuneExperiment 资源后，由控制器创建 AutoTune Server 和 Web 来执行 AutoTune 实验。
• AutoTune Server 是执行实验的主体，其中包括：
  • Optimizer：超参数调优器，在限定的搜索空间内用特定的调优算法选择合适的超参数组合。
  • Training Manager：训练任务管理器，使用 Optimizer 产生的超参数，创建 TrainingJob 进行训练，并将训练结果反馈给 Optimizer 用于下一次超参数选择。AutoTune 可以同时创建多组 TrainingJob 来测试不同的超参数组合以加快训练效率。目前 AutoTune 支持使用 TensorFlowTrainingJob、PyTorchTrainingJob 和 XGBoostTrainingJob 进行训练。
• AutoTune Web 是 AutoTune 的可视化界面，你可以通过此界面实时查看实验状态，对比各组超参数对实验产生的影响。

AutoTuneExperiment

你可以通过创建 AutoTuneExperiment 来实现自动优化模型超参数。

创建 AutoTuneExperiment

下面是一个基本的 AutoTuneExperiment 示例：

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
metadata:
  name: experiment-sample
spec:
  maxExecSeconds: 7200
  maxTrialNum: 50
  trialConcurrency: 3
  searchSpace: |-
    {
      "batch_size": {"_type": "choice", "_value": [512, 1024, 2048, 4096, 8092]},
      "learning_rate": {"_type": "choice", "_value": [0.0001, 0.001, 0.01, 0.1]}
    }
  trainingConfig:
    type: tensorflow
    tasks:
      - type: worker
        replicas: 1
        template:
          spec:
            securityContext:
              runAsUser: 1000
            containers:
              - command:
                  - python3
                  - dist_mnist.py
                workingDir: /mnt/mnist-distributed
                imagePullPolicy: IfNotPresent
                image: t9kpublic/tensorflow-1.15.2:tuner-2.23
                name: tensorflow
  tuner:
    builtinTunerName: TPE
    classArgs: |-
      {
        "optimize_mode": "minimize", 
        "constant_liar_type": "min"
      }

在该例中：

• 使用 TensorFlowTrainingJob 进行训练（由 trainingConfig 字段指定，详细配置方法请参阅训练框架支持）。
• 使用 TPE 算法进行超参数调优，算法的参数为 {"optimize_mode": "minimize", "constant_liar_type": "min"}（由 tuner 字段指定，更多参数请参阅超参数调优算法）。
• 超参数的搜索空间为 {"batch_size": {"_type": "choice", "_value": [512, 1024, 2048, 4096, 8092]},"learning_rate": {"_type": "choice", "_value": [0.0001, 0.001, 0.01, 0.1]}}（由 searchSpace 字段指定，搜索空间的格式及含义请参阅搜索空间）。
• 可以同时测试 3 组超参数，最大测试次数为 50（分别由 trialConcurrency 和 maxTrialNum 字段指定），实验的最大执行时间为 2 小时（7200 秒，由 maxExecSeconds 字段指定），如果时间超出，实验进入 TIMEOUT 状态。

AIStore 的使用

AutoTuneExperiment 支持将实验数据存储在 AIStore 中，通过设置 spec.aistore 字段以使用 AIStore 数据库，其中：

• spec.aistore.folder 声明实验数据存储在哪个 AIStore 文件夹中，内容应填写文件夹的 ID。
• spec.aistore.secret 引用一个 K8s Secret，其中应记录 API Key，用于上传数据时进行身份验证。

下面是一个存储 APIKey 的 Secret 示例：

apiVersion: v1
data:
  apikey: ZDQyMjJjZjUtMmI0Ni00Mjk2LWFiMzYtYWI4NmVhZGUwZjQx
kind: Secret
metadata:
  name: aistore-secret
type: Opaque

搜索空间

搜索空间是实验过程中超参数的设置范围，AutoTuneExperiment 会在此范围中选择超参数进行训练，最后找出最优的超参数组合。

搜索空间是一个 JSON 结构，具体格式请参阅搜索空间。

训练框架支持

AutoTuneExperiment 支持对多种训练框架进行超参数的调优，包括 TensorFlow、PyTorch 和 XGBoost。

AutoTuneExperiment 通过设置 spec.trainingConfig 字段实现对上述框架的支持。其中：

• spec.trainingConfig.type 可设置为 tensorflow、pytorch 和 xgboost，分别表示使用 TensorFlow、PyTorch 和 XGBoost 框架进行训练。
• spec.trainingConfig.tasks 字段的设置请根据所使用的框架种类分别参阅 TensorFlowTrainingJob、PyTorchTrainingJob 和 XGBoostTrainingJob。

超参数调优算法

AutoTuneExperiment 在调参过程中需要使用超参数调优算法对超参数进行选择，对于不同的训练框架和不同的超参数种类，超参数调优算法的效率和效果也是不一样的。

算法根据功能和定义分为两类：

• Tuner 算法：超参数调优算法，用于选取合适的超参数组合。
• Assessor 算法：训练评估算法，用于判断当前训练是否符合预期，如果不符合则终止训练。

算法的详细介绍以及参数配置请参阅超参数调优算法。

实验状态

AutoTuneExperiment 的生命周期包括以下五个阶段：

• PENDING：AutoTune 的相关组件（包括 AutoTune Server 和 AutoTune Web）已经创建成功，等待控制器启动 AutoTuneExperiment。
• RUNNING：AutoTuneExperiment 运行中。
• TIMEOUT：如果达到最大执行时间（由 spec.maxExecSeconds 字段指定）后，实验仍未完成（实际训练次数小于 maxTrialNum 字段指定的训练次数），则实验超时，不再创建新的训练。
• DONE：AutoTuneExperiment 在最大执行时间内完成了 maxTrialNum 字段指定的训练次数（无论成功或失败），则实验完成。
• ERROR：AutoTuneExperiment 初始化阶段或运行阶段出现错误。

下一步

• 了解如何使用 AutoTune 进行超参数优化

搜索空间

搜索空间用于定义超参数的范围，AutoTune 会在这一范围内对超参数进行组合并测试，最后得到效果最好的一组训练。

格式

{
  "parameter1": {"_type": "choice", "_value":[1, 2, 3, 4]},
  "parameter2": {"_type": "randint", "_value":[1, 10]},
  ...
}

在上述结构中：

• 每一个条目都记录了一个超参数的名称和搜索方式：
  • 每一个条目的键值（例如 parameter1 和 parameter2）表示超参数的名称。
  • _type 是超参数搜索方法。
  • _value 表示搜索方法所使用的参数。
• choice 和 randint 表示超参数的搜索方法，其具体含义请参阅搜索方法。

搜索方法

超参数调优算法

AutoTuneExperiment 在调参过程中需要使用超参数调优算法对超参数进行选择，对于不同的训练框架和不同的超参数种类，超参数调优算法的效率和效果也是不一样的。

算法根据功能和定义分为两类：

• Tuner 算法：超参数调优算法，用于选取合适的超参数组合。
• Assessor 算法：训练评估算法，用于判断当前超参数的训练中间结果是否符合预期，如果不符合则终止训练。

Tuner 算法

HyperOpt 类算法

HyperOpt 是一个用于超参数调优的 Python 库，其中主要包含三种超参数调优算法：Random、Anneal 和 TPE。三种算法之间的区别以及算法的使用方法请参阅 HyperOpt 文档。

算法支持使用的搜索方法有：choice、randint、loguniform 和 qloguniform。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "tuner": {
    "builtinTunerName": "Anneal",
    "classArgs": {
      "optimize_mode": "minimize", 
      "constant_liar_type": "min"
    }
  }
}

Evolution

进化算法（Evolution）是受生物进化启发得到的一种优化算法。进化算法的详细介绍请参阅 Evolutionary algorithm WIKI 文档。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "tuner": {
    "builtinTunerName": "Evolution",
    "classArgs": {
      "optimize_mode": "minimize", 
      "population_size": 32
    }
  }
}

Batch

Batch 是一种最简单的选参算法，此算法只支持一种超参数的优化（搜索空间中只能有一个条目）且仅支持 choice 搜索方法。

下面是 AutoTuneExperiment 使用此算法的一个示例（Batch 算法不需要填写参数）：

{
  "searchSpace": {
      "learning_rate": {"_type": "choice", "_value": [0.0001, 0.001, 0.01, 0.1]}
  },
  "tuner": {
    "builtinTunerName": "Batch"
  }
}

上述示例中，搜索空间中只有一个超参数，且 _type 为 choice；Batch 算法不需要传入参数，所以没有填写 tuner.classArgs 字段。

GridSearch

一种基本的选参算法，根据搜索空间中的参数和范围，枚举所有可能的超参数组合，一一测试。

算法支持使用的搜索方法有：choice、randint 和 quniform。

下面是 AutoTuneExperiment 使用此算法的一个示例（GridSearch 算法不需要填写参数）：

{
  "tuner": {
    "builtinTunerName": "GridSearch"
  }
}

MetisTuner

Metis 算法的详细介绍请参阅论文 Metis: Robustly Optimizing Tail Latencies of Cloud Systems。

算法支持使用的搜索方法有：choice、randint、uniform 和 quniform。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "tuner": {
    "builtinTunerName": "MetisTuner",
    "classArgs": {
      "optimize_mode": "maximize",
      "no_resampling": true,
      "no_candidates": false,
      "selection_num_starting_points": 600,
      "cold_start_num": 10,
      "exploration_probability": 0.9
    }
  }
}

GPTuner

GPT 是一种能够极大减少超参数优化步骤的贝叶斯优化算法。算法的详细介绍请参阅 NNI GPTuner 文档。

算法支持使用的搜索方法有：randint、uniform、quniform、loguniform、qloguniform 和数字形式的 choice。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "tuner": {
    "builtinTunerName": "GPTuner",
    "classArgs": {
      "optimize_mode": "maximize",
      "utility": "ei",
      "kappa": 5,
      "xi": 0,
      "nu": 2.5,
      "alpha": 1e-6,
      "cold_start_num": 10,
      "selection_num_warm_up": 100000,
      "selection_num_starting_points": 250
    }
  }
}

PPOTuner

PPO 算法继承了 OpenAI 中 ppo2 的主要逻辑，并适应 NAS 场景。

算法支持使用的搜索方法有：layer_choice 和 input_choice。下面是一个搜索空间设置的示例：

{
  "first_conv": {"_type": "layer_choice", "_value": ["conv5x5", "conv3x3"]},
  "mid_conv": {"_type": "layer_choice", "_value": ["0", "1"]},
  "skip": {
    "_type": "input_choice",
    "_value": {"candidates": ["", ""], "n_chosen": 1}
  }
}

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "tuner": {
    "builtinTunerName": "PPOTuner",
    "classArgs": {
      "optimize_mode": "maximize",
      "trials_per_update": 20,
      "epochs_per_update": 4,
      "minibatch_size": 4,
      "ent_coef": 0.0,
      "lr": 3e-4,
      "vf_coef": 0.5,
      "max_grad_norm": 0.5,
      "gamma": 0.99,
      "lam": 0.95,
      "cliprange": 0.2
    }
  }
}

PBTTuner

PBT 算法得自 Population Based Training of Neural Networks。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "tuner": {
    "builtinTunerName": "PBTTuner",
    "classArgs": {
      "optimize_mode": "maximize",
      "population_size": 10,
      "factor": 0.2,
      "resample_probability": 0.25,
      "fraction": 0.2
    }
  }
}

Assessor 算法

Medianstop

Medianstop 算法的逻辑是：如果在某一步 S，当前运行的实验的最佳观测值比所有已经完成的训练的第 S 步前的观测值的中位数差，则停止此次训练。此策略出自论文 Google Vizier: A Service for Black-Box Optimization 。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "assessor": {
    "builtinAssessorName": "Medianstop",
    "classArgs": {
      "optimize_mode": "maximize",
      "start_step": 0
    }
  }
}

在上述示例中，start_step 表示从第几步开始上传观测值（过早上传观测值，可能会错误的停止一些刚开始表现较差的训练）。

Curvefitting

Curvefitting 算法使用学习曲线拟合算法来预测未来的学习曲线性能。其逻辑是：如果在某一步，当前训练的预测结果是收敛的并且比历史上的最佳结果差，则停止此次训练。Curvefitting 算法的详细介绍请参阅 NNI Curvefitting 文档。

下面是 AutoTuneExperiment 使用此算法的一个示例（示例中的 classArgs 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

{
  "assessor": {
    "builtinAssessorName": "Curvefitting",
    "classArgs": {
      "optimize_mode": "minimize",
      "epoch_num": 20,
      "start_step": 6,
      "threshold": 0.95,
      "gap": 1
    }
  }
}

模型部署

TensorStack AI 平台的模型部署模块可以帮助你快速地将训练完成的 AI 模型部署为推理服务。

针对不同的应用场景，有以下两种 TensorStack API可供使用：

• MLService 是完善的模型推理服务，可用于生产环境，具有以下特性：
  • 基于 Serverless 架构，服务容量（serving capacity）可根据负载自动伸缩；
  • 自动暴露服务到集群外部，快速上线。
• SimpleMLService 是精简的模型推理服务，可用于快速测试、固定容量部署等场景。具有以下特性：
  • 服务副本数目（replica）固定；
  • 集群外部访问需要额外配置 Ingress 等资源。

同时，TensorStack AI 平台对模型部署提供自动化的运维支持，包括性能和资源的监控告警以及故障检测，以保障推理服务长期可靠运行。

架构

模型部署模块的架构如下图：

根据用户提供的模型存储位置和 AI 框架等设置，模型部署模块的控制器（controller）协调模型下载并启动模型推理服务。

下一步

• 了解 SimpleMLService
• 了解 MLService

SimpleMLService

SimpleMLService 用于在 TensorStack AI 平台上简单、快捷地部署 AI 模型推理服务，可用于小规模模型部署，快速测试等场景。

SimpleMLService 具有以下特性：

• 直接支持 TensorFlow、PyTorch 框架，并允许用户自定义框架，具有良好的可扩展性。
• 支持 PVC、S3 模型存储方式。
• 直接支持从集群内部访问推理服务；集群外访问需要用户进行额外配置。
• 服务容量固定，不支持自动伸缩。

创建 SimpleMLService

下面是一个基本的 SimpleMLService 示例：

apiVersion: tensorstack.dev/v1beta1
kind: SimpleMLService
metadata:
  name: mnist
spec:
  replicas: 1
  storage:
    s3:
      secretName: s3-secret
      uri: s3://models/mnist/
      containerPath: /var/lib/t9k/model
  tensorflow:
    image: t9kpublic/tensorflow-serving:2.6.0
    resources: 
      requests:
        cpu: 1
        memory: 1Gi

本示例的 spec 字段的子字段释义如下：

• replicas: 定义运行推理服务的副本数量是 1。
• storage.s3: 设定使用 S3 存储模型，子字段的释义如下：
  • secretName: Secret s3-secret 中存储 S3 配置信息，其详情参见：创建-s3-secret。
  • uri: 模型在 S3 中的存储路径是 s3://models/mnist/。
  • containerPath: 模型被加载后，在容器中存储模型的文件系统路径是 /var/lib/t9k/model。
• tensorflow: 设定使用 tensorflow 推理框架，子字段释义如下：
  • image: 指定推理服务容器镜像 t9kpublic/tensorflow-serving:2.6.0。
  • resources: 这顶一个副本 Pod 使用的资源量。

直接支持的 AI 框架

SimpleMLService 目前直接支持 TensorFlow、PyTorch 两种框架。

TensorFlow

可以通过设置 spec.tensorflow 字段来部署 TensorFlow 框架，参考示例：创建 SimpleMLService。

当使用 TensorFlow 时，控制器会在容器中设置下列启动命令：

/usr/bin/tensorflow_model_server \
  --port=9090 \
  --rest_api_port=8080 \
  --model_name=<SimpleMLService name> \
  --model_base_path=<model-dir-in-container>

PyTorch

可以通过设置 spec.pytorch 字段来部署 PyTorch 框架，示例如下：

spec:
  pytroch:
    image: <pytorch-image>
    modelsFlag: "resnet-18=resnet-18.mar"
    resources: 
      requests:
        cpu: 1
        memory: 1Gi

当使用 PyTorch 时，控制器会在容器中设置下列启动命令：

torchserve \
  --start \
  --model-store=<mode-dir> \
  --models <spec.pytorch.modelsFlag>

自定义框架

如果需要使用 PyTorch, TensorFlow 之外的框架，可以通过设置 spec.custom 字段来自定义框架。

用户可在 spec.custom.spec 字段中定义一个完整的 PodSpec，并需要满足下列要求：

1. 至少设置一个 containers 成员。
2. 启动推理服务运行命令时，指定正确的模型路径。
3. 未设置 spec.service 时，推理服务的服务端口应该使用 8080。

示例如下：

apiVersion: tensorstack.dev/v1beta1
kind: SimpleMLService
metadata:
  name: pvc-custom
spec:
  replicas: 1
  storage:
    s3:
      secretName: s3-secret
      uri: s3://models/mnist/
      containerPath: /custom/path
  custom:
    spec:
      containers:
      - name: user-container
        args:
        - --port=9000
        - --rest_api_port=8080
        - --model_name=mnist
        - --model_base_path=/custom/path
        command:
        - /usr/bin/tensorflow_model_server
        image: "t9kpublic/tensorflow-serving:2.6.0"

副本数量

副本数量通过字段 spec.replicas 设置，用于定义 SimpleMLService 的 Pod 数量，默认值是 1。

暴露服务

通过设置 spec.service 字段来选择将服务的哪个端口暴露出来。未设置时，默认将 Pod 的 8080 端口映射到 Service 的 80 端口。

下面是一个示例：

spec:
  service:
    ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP
    type: ClusterIP

在该例中：

• 将 Pod 的 8080 端口映射到 Service 的 80 端口，协议是 TCP。
• Service 的 Type 是 ClusterIP。

调度器

SimpleMLService 支持使用两种调度器：

• Kubernetes 默认调度器
• T9k Scheduler 调度器

通过 spec.scheduler 字段可以设置欲使用的调度器：

• 不设置 spec.scheduler 字段，默认使用 Kubernetes 调度器。
• 设置 spec.scheduler.t9kScheduler 字段，使用 T9k Scheduler 调度器。

在下面的示例中，SimpleMLService 使用 T9k Scheduler 调度器，并申请使用 队列 default 中的资源。

spec:
  scheduler:
    t9kScheduler:
      queue: default

模型存储

SimpleMLService 支持使用 S3 或 PVC 中存储的模型。

S3

如需使用 S3 服务中存储的模型：

1. 创建存储 S3 服务信息的 Secret
2. 设置 SimpleMLService 的 spec.storage.s3 字段

创建 S3 Secret

存储 S3 信息的 Secret 需要满足下列条件：

1. 设置 label tensorstack.dev/resource: s3。
2. 设置 data[.s3cfg] 字段，内容是 Base64 编码的 s3cmd config。

YAML 示例如下：

apiVersion: v1
kind: Secret
metadata:
  name: s3-sample
  labels:
    tensorstack.dev/resource: s3
type: Opaque
data:
  .s3cfg: aG9zdF9iYXNlID0gZXhhbXBsZS5zMwpob3N0X2J1Y2tldCA9IGV4YW1wbGUuczMKYnVja2V0X2xvY2F0aW9uID0gdXMtZWFzdC0xCnVzZV9odHRwcyA9IEZhbHNlCmFjY2Vzc19rZXkgPSB1c2VyCnNlY3JldF9rZXkgPSBwYXNzd29yZApzaWduYXR1cmVfdjIgPSBGYWxzZQo=

其中 data[.s3cfg] 字段 Base64 解码后如下：

host_base = example.s3
host_bucket = example.s3
bucket_location = us-east-1
use_https = False
access_key = user
secret_key = password
signature_v2 = False

设置 spec.storage.s3

设置 SimpleMLService 的 spec.storage.s3 字段来使用存储在 S3 中的模型数据。spec.storage.s3 字段包含下列子字段:

• secretName: 前述步骤创建的 S3 配置信息的 Secret 名称。
• uri: 模型在 S3 中的存储标识。
• containerPath: 模型在容器中的存储路径。

示例如下：

spec:
  storage:
    s3:
      secretName: s3-secret
      uri: s3://models/mnist/
      containerPath: /var/lib/t9k/model

PVC

通过配置 spec.storage.pvc 字段可以使用存储在 PVC 中的模型数据。spec.storage.pvc 字段包含下列子字段：

• name: 存储模型数据的 PVC 的名称。
• subPath: 模型在 PVC 中的路径，不可以是绝对路径（即开头不能是 /）。
• containerPath: 模型在容器中的存储路径。

示例如下：

spec:
  storage:
    pvc:
      name: demo
      subPath: path/mnist
      containerPath: /var/lib/custom

服务状态

SimpleMLService 的状态记录在 status 字段中。

status.address 字段记录了推理服务在集群内的访问地址，子字段如下：

• url: 推理服务在集群内的访问地址
• ports: 推理服务可供访问的服务端口

status.conditions 字段表明了当前 SimpleMLService 的状态，包括下列 2 种类型：

• ModelDownloaded: 模型是否成功地被下载到本地。
• Ready: 推理服务是否就绪。

在下面的示例中：

• 访问推理服务的地址是 sample.demo.svc.cluster.local
• 模型已经下载到容器本地
• 推理服务处于就绪状态

status:
  address:
    url: sample.demo.svc.cluster.local
    ports:
    - port: 80
      protocol: TCP
  conditions:
  - lastTransitionTime: "2023-12-27T06:52:39Z"
    status: "True"
    type: ModelDownloaded
  - lastTransitionTime: "2023-12-27T06:52:41Z"
    message: Deployment has minimum availability.
    reason: MinimumReplicasAvailable
    status: "True"
    type: Ready

下一步

• 了解如何部署一个简单推理服务
• API 参考：SimpleMLService

MLService

MLService 用于在 TensorStack AI 平台上部署 AI 推理服务，其功能全面，可用于生产环境。

概述

MLService 是推理服务的核心 API，由 releases 和 transformer 两部分构成：

• spec.releases 定义一个或多个 releases，以提供多版本模型推理服务的支持。
• 可选的 transformer 定义前处理（pre-processing）和后处理（post-processing）计算。

MLService 的主要特性包括：

• 支持定义多个版本（release）的推理服务，每个 release 包含一个 predictor，其定义了：
  • 模型存储（storage）
  • 模型规约（model），包括 modelUri，parameters，runtime（引用 MLServiceRuntime 定义运行推理服务 Pod 的模版）
  • 计算资源（resources）
  • 其他部署参数（minReplicas, maxRelicas, logger ...）
• 每个 release 服务的容量可独立自动伸缩，可通过 minReplicas、maxReplicas 设置容量的上下限。
• 支持金丝雀（canary release）发布模式。
• 用户可定制 transformer 组件，以在调用推理服务时进行前处理（pre-processing），以及获得推理结果后进行后处理（post-processing）。
• transformer 的容量也可独立自动伸缩，可通过 minReplicas、maxReplicas 设置容量的上下限。

示例

下面是一个基本的 MLService 示例：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: torch-mnist
spec:
  default: version1
  releases:
    - name: version1
      predictor:
        minReplicas: 1
        maxReplicas: 3
        model:
          parameters:
            "MODEL_PATH": "mnist=model.mar"
          runtime: torchserve
          modelUri: pvc://tutorial/tutorial-examples/deployment/pvc/mlservice-torch/

MLServiceRuntime

在示例中，我们使用了 MLServiceRuntime torchserve。 MLServiceRuntime 定义了推理服务的模版，包含了推理服务的关键信息，例如镜像、启动命令、资源需求等，能够方便地帮助用户快速部署多种模型推理服务程序。

一个 MLServiceRuntime 可以被多个 MLService 使用。

定义

一个基本的 MLServiceRuntime 的示例：

apiVersion: tensorstack.dev/v1beta1
kind: MLServiceRuntime
metadata:
  name: torchserve
spec:
  enabled: true
  template:
    spec:
      containers:
      - name: user-container
        image: torchserve:0.9.0-cpu
        args:
          - torchserve
          - --start
          - --model-store=/var/lib/t9k/model
          - --models {{if .MODEL_PATH}}{{.MODEL_PATH}}{{else}}all{{end}}
        resources:
          limits:
            cpu: "200m"
            memory: 200Mi
        ports:
        - containerPort: 8080
          protocol: TCP

该 MLServiceRuntime 在 spec.template 中定义了推理服务的副本（Pod）的模版，以指定容器镜像 torchserve:0.9.0-cpu、启动命令 torchserve 及其他命令行参数等。

使用

用户可以在 MLService 的 predictor 定义中指定要使用的 MLServiceRuntime 名称，例如：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: demo
spec:
  default: version1
  releases:
  - name: version1
    predictor:
      model:
        runtime: torchserve
        modelUri: "<your-model-registry/your-model-path>"

用户在 release version1 的 .predictor.model.runtime 中指定了 torchserve，系统在创建推理服务器副本（Pod）时，将会使用名称为 torchserve 的 MLServiceRuntime。

进一步的配置

除了直接使用 MLServiceRuntime 定义好的 Pod 模版，MLService 还支持对其进行进一步的配置和修改。

Parameters

MLService 支持在 predictor 的 .model.parameters 设置参数，该字段是一个 map 类型，key 为参数名，value 为参数值。

在之前的 MLServiceRuntime 示例 中包含了 --models {{if .MODEL_PATH}}{{.MODEL_PATH}}{{else}}all{{end}} 的内容。这里使用了 golang template 的语法，含义为：

• 如果使用此 MLServiceRuntime 的 MLService 指定了 MODEL_PATH，这一行会被设置为 --model <用户指定的 MODEL_PATH>
• 如果没有指定 MODEL_PATH，这一行会被设置为 --model all

如下所示，在 MLService 中设置 MODEL_PATH：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: demo
spec:
  default: version1
  releases:
  - name: version1
    predictor:
      model:
        parameters:
          "MODEL_PATH": "mnist=model.mar"
        runtime: torchserve
        modelUri: "<your-model-registry/your-model-path>"

由上述 MLService 最终产生的副本（Pod）的 args 中会包含 --model mnist=model.mar，指定了使用模型的名称和文件。

StrategicMergePatch

MLServiceRuntime 定义了 Pod 模版，但不一定能适用于所有场景。MLService 支持用户在 MLServiceRuntime 的基础上，进行进一步的叠加修改，例如：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: demo
spec:
  default: version1
  releases:
  - name: version1
    predictor:
      model:
        parameters:
          "MODEL_PATH": "mnist=model.mar"
        runtime: torchserve
        modelUri: "<your-model-registry/your-model-path>"
      template:
        spec:
          containers:
            - name: user-container
              image: self-torchserve:latest

将上面 MLService 中 predictor version1 的 template.spec 和之前的 Runtime 定义示例 相比， 可以发现他们都定义了一个名为 user-container 的 container，但是 image 不同。 于是最终生成的 Pod 中，MLService 中定义的 image 会覆盖 MLServiceRuntime 中的 image，但是 MLServiceRuntime 中 args 等其余设置都会被保留。

上述的 StrategicMergePatch 给用户提供了完整的个性化改动方案。除此以外，针对改动频率更高的资源要求（resources），MLService 提供了更方便的个性化改动方案。用户可以直接通过 Predictor 中的 resources 覆盖 Runtime 的资源要求，例如：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: demo
spec:
  default: version1
  releases:
  - name: version1
    predictor:
      model:
        modelFormat:
          name: pytorch
        modelUri: "<your-model-registry/your-model-path>"
      resources:
        limits:
          cpu: 500m
          memory: 1Gi

模型存储

MLService 支持 S3 和 PVC 两种存储模型的方式，用户需要根据模型存储的类型填写 MLService 的配置。

PVC

在MLService中使用 PVC 存储模式需要在 spec.releases[*].predictor.model.modelUri 中设置包含前缀 pvc:// 的模型路径。

例如，下面的示例指定模型存储在 PVC tutorial 的 models/example/ 路径下：

...
  releases:
    - name: test1
      predictor:
        model:
          modelUri: "pvc://tutorial/models/example"
...

S3

S3 是一种对象存储服务和协议，具有良好的可扩展性、数据可用性和安全性等优点，其协议被多种商业和开源产品支持，并且被广泛部署。

可在 MLService 中通过 spec.releases[*].predictor.model.modelUri 和 spec.releases[*].predictor.storage.s3Storage.secretName 设定 S3 的配置参数，其中：

• modelUri 必需包含前缀 s3://。
• secretName 指向的Secret 存储的 S3 配置格式应当是 s3cmd 配置文件格式。

例如，下面的示例指定模型在 S3 中的存储 Uri 前缀为 s3://models/example/，S3 的配置信息存储在 Secret s3-model 中：

...
  releases:
    - name: test1
      predictor:
        model:
          modelUri: "s3://models/example/"
        storage:
          s3Storage:
            secretName: s3-model
...

更多配置

发布策略

多版本支持

一个 MLService 可以同时部署多个版本（release）的推理服务，以使用不同的模型文件，或者其他配置等。

在下面的示例中，MLService 同时部署了 nov-02（设置为默认）、nov-05 和 nov-11 三个版本的服务，这三个版本都使用同一个 MLServiceRuntime，但是使用的模型不同（不同的 modelUri）：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: multi-releases
spec:
  default: nov-02
  releases:
    - name: nov-02
      predictor:
        model:
          runtime: torchserve
          modelUri: pvc://tutorial/model-11-02
    - name: nov-05
      predictor:
        model:
          runtime: torchserve
          modelUri: pvc://tutorial/model-11-05
    - name: nov-11
      predictor:
        model:
          runtime: torchserve
          modelUri: pvc://tutorial/model-11-11

金丝雀发布

MLService 支持金丝雀（canary release）发布策略。用户可以通过 spec.canary 字段设置金丝雀发布对应的模型版本（release），spec.canaryTrafficPercent 字段设置金丝雀发布的路由权重。spec.default 是必需字段，用于设置默认发布。

例如上一节中我们部署了 3 个版本的模型，我们想主要（80% 流量）使用 nov-02 这个版本，并且将刚刚训练好的 nov-11 作为金丝雀版本：

• 默认发布：nov-02，路由权重为 80%。
• 金丝雀发布：nov-11，路由权重为 20%。

...
spec:
  default: nov-02
  canary: nov-11
  canaryTrafficPercent: 20
...

日志收集

MLService 支持对预测请求进行日志收集，详情见2.2.2.1日志收集

前处理及后处理

MLService 支持部署含有 transformer 模块的前处理（pre-processing）及后处理（post-processing）的推理服务：

• 预处理：用户发向推理服务的原始数据，先经过 transformer 预处理，然后再被发送到推理服务。
• 后处理：推理服务返回的预测结果，先经过 transformer 后处理，然后再返回给用户。

用户可以使用 Tensorstack SDK 编写 transformer 代码，制作镜像，并基于该镜像创建含有 transformer 的推理服务。详细示例请参阅制作并部署含有 Transformer 的模型推理服务。

下文展示了一个使用 transformer 的推理服务：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: pic-mnist
spec:
  default: origin
  transformer:
    minReplicas: 1
    minReplicas: 5
    template:
      spec:
        containers:
        - name: user-container
          image: t9kpublic/transformer-example:0.1.0
          resources:
            limits:
              cpu: "500m"
              memory: 500Mi

容量伸缩

MLService 支持自动伸缩服务容量：即根据服务负载的变化，自动调节推理服务的部署规模（副本数量）。具体原理可以查看 Knative Autoscaling。

用户可以通过设置 spec.releases[*].predictor.minReplicas 字段和 spec.releases[*].predictor.maxReplicas 字段来指定 Predictor 工作负载数量的下限和上限。

同样的，如果用户启用了 Transformer，可以通过 spec.transformer.minReplicas 字段和 spec.transformer.maxReplicas 字段来指定 Transformer 工作负载数量的下限和上限。

以下是一些特殊情况：

• minReplicas 不填时，工作负载数量的默认最小值为 1。
• minReplicas 等于 0 时，当没有流量请求时，MLService 会缩容到 0，不再占用系统资源。
• maxReplicas 不填或设为 0 时，工作负载数量没有上限。

除了负载数量的限制，用户还可以在具体的 Runtime 或者组件（Predictor 或者 Transformer）的 Pod 定义中设置 Knative Autoscaling 相关的 Annotation，例如：

...
spec:
  releases:
    - name: version1
      minReplicas: 1
      maxReplicas: 3
      predictor:
        template:
          metadata:
            annotations: 
              autoscaling.knative.dev/metric: "rps"
              autoscaling.knative.dev/target: "100"
...

在上面的示例中，我们设置了工作负载数量的范围为 [1,3]，自动伸缩指标(metric)为 rps，自动伸缩目标(target)为 100。这意味着当每个工作负载每秒处理的请求数量（requests-per-second）达到 100 时，负载会开始扩容，且扩容最大数量为 3，最小数量为 1。

调度器

MLService 支持使用两种调度器：Kubernetes 默认调度器（默认）和 T9k Scheduler。MLService 通过 spec.scheduler 字段设置调度器：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，使用了 T9k Scheduler 调度器，且工作负载处于队列 default 中。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
...

服务状态

通过 MLService 的状态字段可以获取如下信息：

• 推理服务的全局状态及服务地址：status.ready 表明推理服务是否准备就绪，status.address.url 表明全局推理服务地址。
• 每个部署的模型的状态及服务地址：status.releases[*].ready 表明该版本推理服务是否准备就绪，status.releases[*].url 表明该版本的推理服务地址。
• Transformer 的状态及服务地址：status.ready 表明 Transformer 服务是否准备就绪，status.transformer.url 表明 Transformer 服务地址。
• 推理服务没有就绪的原因：status.conditions 以及 status.releases[*].message 等字段中会记录相关报错信息。

以多版本支持的示例的状态为例，其 MLService 状态字段如下。从状态字段可以看出，该推理服务处于就绪状态，外部访问地址为 http://multi-releases.<project>.<domain>，某个 release 的访问地址为 http://multi-releases-predict-<release>.<project>.<domain>

status:
  address:
    url: http://multi-releases.<project>.<domain>
  canaryRelease: nov-02
  conditions:
  - lastTransitionTime: "2023-11-27T10:44:27Z"
    status: "False"
    type: Paused
  - lastTransitionTime: "2023-11-27T10:50:04Z"
    status: "True"
    type: Ready
  defaultRelease: nov-05
  releases:
  - name: nov-02
    ready: true
    readyReplicas: 1
    totalReplicas: 1
    trafficPercent: 80
    url: http://multi-releases-predict-nov-02.<project>.<domain>
  - name: nov-05
    ready: true
    readyReplicas: 1
    totalReplicas: 1
    trafficPercent: 20
    url: http://multi-releases-predict-nov-05.<project>.<domain>
  - name: nov-11
    ready: true
    readyReplicas: 1
    totalReplicas: 1
    trafficPercent: 0
    url: http://multi-releases-predict-nov-11.<project>.<domain>

如果推理服务没有就绪，你可以通过查看 status.conditions 中 type 为 Ready 的 reason 以及 message 来查看具体信息，同时 Event 中也会有相关的错误信息。

访问推理服务

MLService 部署成功后，通过状态字段 status.address.url 可以查询到全局推理服务的 Base URL，再加上部署模型对应的路径即可得到访问推理服务的地址。

以示例中的服务为例，推理服务地址的状态字段如下：

...
status:
  address:
    url: http://torch-mnist.<project>.<domain>
...

由于服务使用的是 TorchServe 框架，按照其 API 规范，用户可以通过下述命令查看服务状态：

$ curl http://torch-mnist.<project-name>.<domain-name>/v1/models/mnist
{
    "model_version_status": <model-status>
}

并调用推理服务：

# 数据在 https://github.com/t9k/tutorial-examples/blob/v20240206/deployment/pvc/mlservice-torch/test_data/0.png
$ curl -T test_data/0.png http://torch-mnist.<project-name>.<domain-name>/v1/models/mnist:predict
{
    "predictions": <predict-result>
}

下一步

• 了解如何部署一个模型推理服务
• 了解如何部署一个包含 Transformer 的推理服务
• 应用示例：使用 vLLM 部署 LLM 推理服务
• 应用示例：部署对话式搜索引擎

参考

• API 参考：MLService
• API 参考：MLServiceRuntime
• Knative Autoscaling

日志收集

MLService 支持对 predictor 和 transformer 服务进行日志收集，包括接收到的 request 和返回的 response 消息。开启日志收集后，系统会为 MLService 添加日志发送能力，其根据配置的接收 URL，将日志发送到 URL 指定的服务。

设置 MLService

用户可以为每个 predictor 和 transformer 设置日志收集功能：

1. predictor： MLService 的 spec.releases[*].predictor.logger 字段来启用 predictor 的日志收集功能。
2. transformer：通过设置 MLService 的 spec.transformer.logger 字段启用 transformer 的日志收集功能。

用户可以通过日志收集的下列字段，来设置日志收集配置：

• urls：url 数组，系统会将收集到的日志发送到 url 对应的服务。
• mode：表示对哪些内容进行收集记录。可选值是 all, response, request，默认值是 all。
  • all：requests 和 response 都会被收集记录。
  • response：只记录收集 response。
  • request：只记录收集 requests。

接收日志

日志数据通过 HTTP 协议被发送（HTTP POST）到用户提供的 URL。

日志数据格式是 CloudEvent，如下例所示：

Context Attributes,
  specversion: 1.0
  type: tensorstack.dev.mlservice.response
  source: torch-mnist-logger-predict-origin
  id: 0009174a-24a8-4603-b098-09c8799950e9
  time: 2021-04-10T00:23:26.080736102Z
  datacontenttype: application/json
Extensions,
  component: predict
  inferenceurl: /v1/models/mnist
  mlservicename: torch-mnist-logger
  namespace: example
  traceparent: 00-6d69e2d3917689ee301610780af06de8-be01c3cfdf8e446e-00
Data,
{
  "0": 1.0,
  "2": 1.3369853835154544e-10,
  "6": 7.10219507987428e-14,
  "5": 5.859705488843112e-14,
  "9": 3.2580891499658536e-15
}

在上述示例中：

• type：表明当前 CloudEvent 数据记录 response 内容。
• source：release 名称是 origin（source 命名规则是 <mlservice-name>-<component>-<release-name>）
• component：组件是 predict
• inferenceurl：URL path 是 /v1/models/mnist
• mlservicename：MLService 的名称是 torch-mnist-logger
• namespace：MLService 所在的 namespace 是 example
• Data：MLService 向用户返回的 response 内容是 {“0”: 1.0,“2”: 1.3369…}

在 HTTP Request 中：

1. CloudEvent 的 Data 内容存在 Request Body 中
2. CloudEvent 的其他内容存在 Request Header 中

可使用 CloudEvent 库来实现接收日志数据的 HTTP Server，具体实现可参考 CloudEvent Sample。

示例

部署日志接收服务

我们在集群内部署 event-display 服务来接受日志，注意：

1. event-display 仅简单地将接收到的 CloudEvents 打印出来；
2. event-display 作为演示的目的。

apiVersion: apps/v1
kind: Deployment
metadata:
 name: event-display
spec:
 replicas: 1
 selector:
   matchLabels:
     app: event-display
 template:
   metadata:
     labels:
       app: event-display
   spec:
     containers:
       - name: event-display
         image: t9kpublic/knative_event_display:1.0.0
         resources:
           limits:
             cpu: 100m
             memory: 100Mi
---
kind: Service
apiVersion: v1
metadata:
 name: event-display
spec:
 selector:
   app: event-display
 ports:
 - protocol: TCP
   port: 80
   targetPort: 8080

部署命令

kubectl create -f event-display.yaml

部署 MLService

请按照使用方法准备环境，基于部署用于生产环境的模型推理服务示例来部署 MLService logger-example。

首先将 mlservice.yaml 修改为下列内容，注意：

1. event-display 和 MLService 需要部署在同一个 namespace/project 中。
2. 这个 MLService 仅对 predictor 设置了 logger 服务。

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
 name: logger-example
spec:
 default: origin
 releases:
   - name: origin
     predictor:
       logger:
         mode: all
         resources:
           limits:
             cpu: "1"
             memory: 2Gi
           requests:
             cpu: "0.5"
             memory: 1Gi
         urls:
         - http://event-display
       minReplicas: 1
       model:
         parameters:
           "MODEL_PATH": "mnist=model.mar"
         runtime: t9k-torchserve
         modelUri: pvc://tutorial/tutorial-examples/deployment/mlservice/torch-pvc/
       containersResources:
       - name: user-container
         resources:
           limits:
             cpu: "500m"
             memory: 1Gi

然后按照 README 文档的操作步骤进行操作。

查看日志

查看 event-display 容器的日志，可看到日志中打印的 CloudEvent 记录了预测请求的详细信息：

$ k get pod -l app=event-display
NAME                             READY   STATUS    RESTARTS   AGE
event-display-7d8d9f97db-lpgg2   1/1     Running   0          14m


$ k logs event-display-7d8d9f97db-lpgg2 
Context Attributes,
  specversion: 1.0
  type: tensorstack.dev.mlservice.request
  source: logger-example-predict-origin
  id: ff726d6b-7fd8-471e-9ddc-de03b201d882
  time: 2024-02-29T08:07:00.849119273Z
Extensions,
  component: predict
  inferenceurl: /v1/models/mnist:predict
  mlservicename: logger-example
  namespace: demo
Data,
  PNG
IHDWfHIDATxc`X`ˬUvo>C0$ůشi˿_{ ZATI̶_Q%̓*y_:=U9;4ɺpJ^{oG8NIx$!K.w;@@4^0
                                                                                                                                     G$Qp֛q?{4g^B
                                                                                                                                                                      <`Rr330
ztB?IENDB`
☁️  cloudevents.Event
Context Attributes,
  specversion: 1.0
  type: tensorstack.dev.mlservice.response
  source: logger-example-predict-origin
  id: ff726d6b-7fd8-471e-9ddc-de03b201d882
  time: 2024-02-29T08:07:01.468872477Z
Extensions,
  component: predict
  inferenceurl: /v1/models/mnist:predict
  mlservicename: logger-example
  namespace: demo
Data,
  {
  "0": 1.0,
  "2": 1.3369905182969433e-10,
  "6": 7.102208632401436e-14,
  "5": 5.859716330864836e-14,
  "9": 3.2580891499658536e-15
}

参考

• API 参考：MLService
• CloudEvents
• event display 源码

模型存储

Job

TensorStack 定义了一系列 CRD（称为 Job）以支持批处理（Batch Processing）计算任务，特别是 AI 领域的大规模分布式并行训练类型性质的计算。

Job 类型

为了支持不同框架的计算任务，TensorStack 提供了一系列 Job：

• TrainingJob：一类使用分布式计算框架进行机器学习的 T9k Job。
  • PyTorchTrainingJob：服务于 PyTorch 分布式训练框架的 T9k Job。
  • TensorFlowTrainingJob：服务于 TensorFlow 分布式训练框架的 T9k Job。
  • XGBoostTrainingJob：服务于 XGBoost 分布式计算框架的 T9k Job。
  • ColossalAIJob：服务于 ColossalAI 分布式训练框架的 T9k Job。
  • DeepSpeedJob：服务于 DeepSpeed 分布式训练框架的 T9k Job。
• MPIJob：MPIJob 使用户能够方便地在集群环境中使用 OpenMPI 进行并行计算。
• BeamJob：用于在集群中通过 Apache Beam Python SDK 运行分布式计算任务，并支持多种底层计算引擎（例如 Apache Spark, Apache Flink）。
• GenericJob：一个通用的 T9k Job 资源，支持各种并行计算场景及 T9k 高级调度策略。
  • GenericJob 十分灵活，用户可以使用 GenericJob 实现 MPIJob、PyTorchTrainingJob 等特定功能的 T9k Job；但其自动化程度低，需要手工设置很多参数。
  • GenericJob 的目的是提供一个总是可行的 “通用” 机制，以支持一些其他特定功能 T9k Jobs 还未支持的新的计算场景。

运行模式

T9k Job 支持多种运行模式（spec.runMode）：

• 立即（Immediate）模式：默认、基本模式。Job 被分配资源后，将会立即开始运行。
• 调试（Debug）模式：帮助用户创建 Job 环境，但不立即执行，用户可以在训练环境中手动启动 Job 或者运行调试代码。
• 暂停（Pause）模式：暂停执行 Job；在一些场合下（如集群资源不足），用户可随时暂停 Job，待条件允许再继续执行 Job。
• 弹性（Elastic）伸缩模式：可以动态调整 Job 规模。

以下是各类型 Job 支持的模式列表：

各种模式的具体使用方式，请参考对应 Job 类型的文档。

GenericJob

GenericJob 是最基本的 T9k Job 资源，支持使用 T9k 高级调度策略。GenericJob 的使用十分灵活，一个熟练的使用者可以通过 GenericJob 实现 MPIJob、PyTorchTrainingJob 等特定功能的 T9k Job。

创建 GenericJob

下面是一个基本的 GenericJob 配置示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: GenericJob
metadata:
  name: generic-example
spec:
  successRules:
    - { "worker": [0] }
  failureRules:
    - { "worker": [0] }
    - { "worker": [1] }
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
            - command:
                - sleep
                - '365'
              image: nginx:latest
              name: sleep

在该例中：

• 创建 4 个副本（由 spec.replicaSpecs[0].replicas 字段指定），这些副本的角色为 worker（由 spec.replicaSpecs[0].type 字段指定）。每个副本执行命令 sleep 365（由 spec.replicaSpecs[0].template 字段指定）。
• GenericJob 的成功条件为序号为 0 且角色为 worker 的副本执行完成（由 spec.successRules 字段指定）。
• GenericJob 的失败条件有两个，任意一个条件达成都会导致 GenericJob 失败（由 spec.failureRules 字段指定）：
  • 序号为 0 且角色为 worker 的副本执行失败。
  • 序号为 1 且角色为 worker 的副本执行失败。

成功和失败

GenericJob 的成功和失败条件是通过 spec.successRules 和 spec.failureRules 字段指定的，其规则如下：

• spec.successRules 数组包含 GenericJob 的所有成功条件，其中：
  • 任意一个条件达成则 GenericJob 成功。
  • 每个条件是一个由若干副本组成的集合，如果这些副本都执行完成，则该条件达成。
• spec.failureRules 数组包含 GenericJob 的所有失败条件，其中
  • 任意一个条件达成则 GenericJob 失败。
  • 每个条件是一个由若干副本组成的集合，如果这些副本都失败或者重启次数耗尽，则该条件达成。

在下面的示例中，记录了 3 种 GenericJob 成功的判定条件：

• 角色为 master 且序号为 0 的副本执行完成。
• 角色为 worker 且序号为 0、1、2 的三个副本全部执行完成。
• 角色为 master 且序号为 2 和角色为 worker 且序号为 0、1 的三个副本全部执行完成。

和 1 种 GenericJob 失败的判定：

• 角色为 master 且序号为 0 的副本执行失败。

...
spec:
  successRules:
  - {"master": [0]}
  - {"worker": [0, 1, 2]}
  - {"master": [2], "worker": [0, 1]}
  failureRules:
  - {"master": [0]}

暴露副本的服务

在分布式计算中，有时需要不同的副本之间进行通信和数据交换。使用者可以通过设置 spec.service 字段来暴露副本的端口。

在下面的示例中，GenericJob 暴露出每一个副本的服务：端口为 2222，域名的格式为 [job-name]-[type]-[rank]，例如下例中角色为 worker 且序号为 0 的副本的域名为 generic-example-worker-0。

apiVersion: batch.tensorstack.dev/v1beta1
kind: GenericJob
metadata:
  name: generic-example
spec:
  service:
    ports:
      - name: http
        port: 2222
  replicaSpecs:
    - type: worker
      replicas: 1
...

变量替换

在副本的配置信息中有时需要传入副本自身或其他副本的信息，包括序号、角色和副本的服务地址等。GenericJob 通过变量替换的方式提供这些信息，主要有以下 5 种变量：

• $(type)：当前副本的角色。
• $(rank)：当前副本在同类副本中的序号。
• $(replicas[_type_])：扮演此角色的副本的数量。
• $(service._type_[_rank_].host)：各个副本的域名（当且仅当副本的服务被暴露出来，此变量可用）。
• $(service.port[_port-name_])：spec.service.ports 字段中定义的服务端口号（当且仅当副本的服务被暴露出来，此变量可用）。

上述变量中 _type_、_rank_ 和 _port-name_ 需填入具体的角色、序号和端口名称（由 spec.service.ports[*].name 字段指定）。

变量替换可以被使用在下列字段中：

• spec.replicaSpecs[*].template.command
• spec.replicaSpecs[*].template.args
• spec.replicaSpecs[*].template.env

以下是用 GenericJob 实现的 TensorFlow 分布式框架使用示例，其中 TF_CONFIG 环境变量需要填写所有副本的地址和当前副本的序号等信息，我们使用变量替换的方式添加：

apiVersion: batch.tensorstack.dev/v1beta1
kind: GenericJob
metadata:
  name: generic-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
            - command:
                - python
                - /mnt/training.py
              image: tensorflow/tensorflow:2.11.0
              name: tensorflow
              env:
                - name: TF_CONFIG
                  value: '{"task":{"type":"$(type)","index":$(rank)},"cluster":{"worker":["$(service.worker[0].host):$(service.port[http])","$(service.worker[1].host):$(service.port[http])","$(service.worker[2].host):$(service.port[http])","$(service.worker[3].host):$(service.port[http])"]}}'

重启机制

GenericJob 为副本提供以下重启机制：

1. Never：不重启
2. OnFailure：错误即重启
3. Always：总是重启（谨慎使用此策略，此策略可能导致 GenericJob 无法停止）

GenericJob 重启机制通过 spec.replicaSpecs[*].restartPolicy 字段指定:

• spec.replicaSpecs[*].restartPolicy.policy 表示当前副本所使用的重启策略，可以设置为 Never、OnFailure 或 Always。
• spec.replicaSpecs[*].restartPolicy.limit 表示当前副本的最大重启次数。

不同的角色可以使用不同的重启策略，比如 master 使用 Always，worker 使用 OnFailure。

清除策略

在 GenericJob 成功或失败后，控制器清理所创建的 Kubernetes 资源，使 GenericJob 不再浪费集群资源（内存、CPU 等）。GenericJob 提供三种策略，通过 spec.cleanUpPolicy 字段指定：

• All：清除全部副本
• None：不清除副本
• Unfinished：清除未结束（处于 Pending、Running 或 Unknown 阶段）的副本

`None` 策略主要用于训练脚本调试阶段。如果需要从副本中读取训练日志，则可以选用此策略。但由于这些副本可能占用资源并影响后续训练，建议你在调试完毕后手动删除这些副本或删除整个 GenericJob。

调度器

目前 GenericJob 支持两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler 调度器

调度器通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，GenericJob 启用 T9k Scheduler 调度器，将副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

调试模式

GenericJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，默认为 sleep inf。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了调试模式，副本使用默认调试设置，即不跳过 InitContainer，并执行 sleep inf。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

GenericJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 GenericJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

GenericJob 状态

GenericJob 的状态和阶段

status.conditions 字段用于描述当前 GenericJob 的状态，包括以下 6 种类型：

1. Initialized：GenericJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：GenericJob 成功。
5. Failed：GenericJob 失败。
6. Paused：GenericJob 进入暂停模式，所有副本都已删除或正在删除。

status.phase 字段用于描述当前 GenericJob 所处的阶段，GenericJob 的整个生命周期主要有以下7个阶段：

1. Pending：GenericJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Paused：GenericJob 进入暂停模式。
4. Resuming：GenericJob 正从暂停模式中恢复运行。恢复运行后，切换为 Running 阶段。
5. Succeeded：GenericJob 成功。
6. Failed：GenericJob 失败。
7. Unknown：控制器无法获得 GenericJob 的阶段。

在下面的示例中，GenericJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；GenericJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；但是 GenericJob 的训练结果是失败的，所以类型为 Failed 的 condition 被设置为 True（原因是 The job is failed with rule: { "worker": [0] }）。当前 GenericJob 运行阶段为 Failed。

...
status:
  conditions:
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "The job has been initialized successfully."
      reason: "-"
      type: Initializing
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "All pods are running normally."
      reason: "-"
      type: Running
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "False"
      message: "All pods are running normally."
      reason: "-"
      type: ReplicaFailure
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "False"
      message: 'The job is failed with rule: { "worker": [0] }'
      reason: "Failed"
      type: Completed
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "True"
      message: 'The job is failed with rule: { "worker": [0] }'
      reason: "Failed"
      type: Failed
  phase: Failed

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）；
• 副本当前的运行阶段，此处的“运行阶段”在 K8s Pod 的 5 个阶段的基础上，添加了 Creating 和 Deleted 分别表示正在创建和已删除；
• 副本在集群中对应的 Pod 的索引信息。

在下面的示例中，GenericJob 创建了 2 个角色为 worker 的副本，这 2 个副本的重启次数之和为 3，当前均处于 Running 阶段，分别运行在 generic-example-worker-0 和 generic-example-worker-1 这 2 个 Pod 上。

...
status:
  tasks:
  - type: worker
    restartCount: 3
    status:
    - phase: Running
      name: generic-example-worker-0
      uid: e3ec2ee3-6645-4e21-993f-1e472b94e0ae
      containers: []
    - phase: Running
      name: generic-example-worker-1
      uid: 908a93f0-7b8b-491e-85d5-3da0abcb4ca4
      containers: []

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面示例中，GenericJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

PyTorchTrainingJob

PyTorchTrainingJob 是服务于 PyTorch 分布式训练框架的 T9k Job。

你可以较为方便地使用 PyTorchTrainingJob 为 PyTorch 训练脚本提供训练环境，并监控训练进程。

创建 PyTorchTrainingJob

下面是一个基本的 PyTorchTrainingJob 配置示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: pytorch-example
spec:
  replicaSpecs:
  - replicas: 4
    restartPolicy: OnFailure
    template:
      spec:
        containers:
        - command:
          - python
          - dist_mnist.py
          image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel
          name: pytorch
    type: worker

在该例中：

• 创建 4 个副本（由 spec.replicaSpecs[*].replicas 字段指定），副本的角色为 worker（由 spec.replicaSpecs[*].type 字段指定）。
• 每个副本使用 pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel 镜像，执行命令 python dist_mnist.py（由 template 字段指定，此处的填写方式参考 PodTemplate）。
• 当副本失败后，会自动重启（由 spec.replicaSpecs[*].restartPolicy 字段指定）。

使用 torchrun 启动训练

前面的示例中所使用的训练方法比较原始，即直接用 python 启动训练脚本，执行训练。

PyTorch 在后续提供了 torch.distributed.launch 包和 torchrun 工具来更好地启动和管理训练，具体优点包括：支持一机多进程、高容错、弹性伸缩训练规模等。PyTorchTrainingJob 也支持使用 torchrun 启动训练来继承这些优点。

spec:
  torchrunConfig:
    enabled: true
    maxRestarts: 10
    procPerNode: "1"
    rdzvBackend: c10d
    extraOptions: []

在 PyTorchTrainingJob 的定义中加入上述片段，来使用 torchrun 启动训练，其中：

• enabled：是否启用 torchrun。
• maxRestarts：训练进程的最多重启次数。
• procPerNode：一个副本中启动多少个训练进程。除了可以指定一个数字字符串之外，还可以设置为 gpu，表示启动等同于副本所使用的 GPU 数量的训练进程。
• rdzvBackend：torchrun 所使用的汇合通信方式，可以设置为 c10d、etcd 或 etcd-v2，但是只有 c10d 是 torch 内置的。如果用户希望使用 etcd 需要自行搭建 etcd 服务器。
• extraOptions：torchrun 的其他参数，上面的参数是 torchrun 比较常用的设置，用户也可以通过 extraOptions 字段提供更多 torchrun 的其他设置。

弹性训练

使用 torchrun 启动的 PyTorchTrainingJob 支持弹性伸缩训练规模，通过 spec.elastic 设置伸缩范围和当前期望训练规模。

在下面的示例中，PyTorchTrainingJob 启用弹性训练功能，训练规模的伸缩范围是 [4,10]，当前期望训练规模为 7。

spec:
  elastic:
    enabled: true
    minReplicas: 4
    maxReplicas: 10
    expectedReplicas: 7

注：期望训练规模（spec.elastic.expectedReplicas）并不代表实际训练规模，当集群资源数量不足时，控制器可能无法创建足够的副本。

最佳实践

...
spec:
  torchrunConfig:
    enabled: false
    minNodes: 1
    maxRestarts: 10
    procPerNode: "1"
    rdzvBackend: c10d
    extraOptions: []
  replicaSpecs:
  - replicas: 4
    restartPolicy: OnFailure
    template:
      spec:
        containers:
        - command:
          - python
          args:
          - dist_mnist.py
          image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel
          name: pytorch
    type: worker
...

在上面的示例中：spec.replicaSpecs[*].template.spec.containers[0].command 只填写 python，其他参数填写在 spec.replicaSpecs[*].template.spec.containers[0].args 中。这样可以实现以下效果：

• 当 spec.torchrunConfig.enabled 设置为 false 时，控制器会为训练副本设置正确的环境变量，并通过 python dist_mnist.py 命令启动训练脚本。
• 当 spec.torchrunConfig.enabled 设置为 true 时，控制器会忽略 python 命令，而是改用 torchrun 命令，其格式为：torchrun <torchrun_args> dist_mnist.py。

这样做的优点就是，在切换 torchrun 模式时，不需要对其他字段进行改动。

另外，如果用户使用 Python Module 作为训练脚本，可以参考以下配置：

...
spec:
  torchrunConfig:
    enabled: false
    ...
  replicaSpecs:
  - replicas: 4
    restartPolicy: OnFailure
    template:
      spec:
        containers:
        - command:
          - python
          args:
          - -m
          - training.module
          image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel
          name: pytorch
    type: worker
...

在上面的示例中，当 spec.torchrunConfig.enabled 设置为 true 时，-m 参数同样可以被 torchrun 使用。

成功和失败

在 PyTorch 分布式训练框架中，需要设置 MASTER_ADDR 和 MASTER_PORT，PyTorchTrainingJob 会将第一个训练副本作为 master（主节点）。当分布式训练的主节点成功结束，PyTorch 分布式训练成功；反之，当分布式训练的主节点执行失败，PyTorch 分布式训练失败。

但是 master 的失败有时可能是因为环境因素导致的，比如集群网络断连、集群节点崩溃等等，此类原因导致的失败应该被允许自动恢复。针对这一情况，PyTorchTrainingJob 支持副本重启（请参阅重启机制），并设定了重启次数限制（由 spec.runPolicy.backoffLimit 字段指定），当副本重启次数达到上限后，如果主节点再次失败，则训练失败。此外，PyTorchTrainingJob 可以设置最长执行时间（由 spec.runPolicy.activeDeadlineSeconds 字段指定），当超过这个执行时间后，训练失败。

如果 PyTorchTrainingJob 在没有超过重启次数和没有超过最长执行时间的情况下成功完成了主节点的运行，则训练成功。

重启机制

PyTorchTrainingJob 的 spec.replicaSpec[*].template 字段使用 PodTemplate 的规范填写，但是 Pod 的重启策略并不能满足 PyTorchTrainingJob 的需求，所以 PyTorchTrainingJob 会给副本的重启策略都设置为 Never，并由控制器根据 spec.replicaSpec[*].restartPolicy 字段处理副本的重启。

可选的重启策略有以下四种：

• Never：不重启
• OnFailure：失败后重启
• Always：总是重启
• ExitCode：特殊退出码重启

使用 Never 重启策略时，Job 的副本失败后不会重启。如果需要调试代码错误，可以选择此策略，便于从副本中读取训练日志。

ExitCode 是一种比较特殊的重启策略，它将失败进程的返回值分为两类：一类是由于系统环境原因或用户操作导致的错误，此类错误可以通过重启解决；另一类是代码错误或者其他不可自动恢复的错误。可重启的退出码包括：

• 130（128+2）：使用 Control+C 终止容器运行。
• 137（128+9）：容器接收到 SIGKILL 信号。
• 143（128+15）：容器接收到 SIGTERM 信号。
• 138：用户可以自定义这个返回值的含义。如果用户希望程序在某处退出并重启，可以在代码中写入这个返回值。

重启次数限制

如果因为某种原因（例如代码错误或者环境错误并且长时间没有修复），PyTorchTrainingJob 不断地失败重启却无法解决问题，这会导致集群资源的浪费。用户可以通过设置 spec.runPolicy.backoffLimit 字段（默认为 3）来设置副本的最大重启次数。重启次数为所有副本共享，即所有副本重启次数累计达到此数值后，副本将不能再次重启。

清除策略

在训练结束后，可能有些副本仍处于运行状态。这些运行的副本仍然会占用集群资源，PyTorchTrainingJob 提供清除策略，在训练结束后删除这些副本。

PyTorchTrainingJob 提供以下三种策略：

• None：不删除副本。
• All：删除所有副本。
• Unfinished：只删除未结束的副本。

`None` 策略主要用于训练脚本调试阶段。如果需要从副本中读取训练日志，则可以选用此策略。但由于这些副本可能占用资源并影响后续训练，建议用户在调试完毕后手动删除这些副本或删除整个 PyTorchTrainingJob。

调度器

目前 PyTorchTrainingJob 支持使用以下两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler 调度器

调度器通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，PyTorchTrainingJob 启用 T9k Scheduler 调度器，将副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

TensorBoard 的使用

PyTorchTrainingJob 支持使用 TensorBoard 对训练过程和结果进行实时可视化（由 spec.tensorboardSpec 字段设置）。

在下面的示例中，PyTorchTrainingJob 使用 t9kpublic/tensorflow-2.11.0:cpu-sdk-0.5.2 镜像创建一个 TensorBoard，可视化名为 torch-tensorboard-pvc 的 PVC 中 /log 路径下的模型数据。

...
spec:
  tensorboardSpec:
    image: t9kpublic/tensorflow-2.11.0:cpu-sdk-0.5.2
    trainingLogFilesets:
    - t9k://pvc/torch-tensorboard-pvc/log

调试模式

PyTorchTrainingJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，默认为 sleep inf。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了调试模式，副本使用默认调试设置，即不跳过 InitContainer，并执行 sleep inf。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

PyTorchTrainingJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 PyTorchTrainingJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

PyTorchTrainingJob 状态

PyTorchTrainingJob 的状态和阶段

status.conditions 字段用于描述当前 PyTorchTrainingJob 的状态，包括以下 6 种类型：

1. Initialized：PyTorchTrainingJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：PyTorchTrainingJob 成功。
5. Failed：PyTorchTrainingJob 失败。
6. Paused：PyTorchTrainingJob 进入暂停模式，所有副本都已删除或正在删除。

status.phase 字段用于描述当前 PyTorchTrainingJob 所处的阶段，PyTorchTrainingJob 的整个生命周期主要有以下7个阶段：

1. Pending：PyTorchTrainingJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Paused：PyTorchTrainingJob 进入暂停模式。
4. Resuming：PyTorchTrainingJob 正从暂停模式中恢复运行。恢复运行后，切换为 Running 阶段。
5. Succeeded：PyTorchTrainingJob 成功。
6. Failed：PyTorchTrainingJob 失败。
7. Unknown：控制器无法获得 PyTorchTrainingJob 的阶段。

在下面的示例中，PyTorchTrainingJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；PyTorchTrainingJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；PyTorchTrainingJob 的训练成功结束，所以类型为 Completed 的 condition 被设置为 True（原因是 The job has finished successfully.）。当前 PyTorchTrainingJob 运行阶段为 Succeeded。

...
status:
  conditions:
    - lastTransitionTime: "2023-12-19T02:40:25Z"
      message: The job has been initialized successfully.
      reason: '-'
      status: "True"
      type: Initialized
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "False"
      type: Running
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "False"
      type: Failed
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "True"
      type: Completed
    - lastTransitionTime: "2023-12-19T02:40:25Z"
      message: All pods are running normally.
      reason: '-'
      status: "False"
      type: ReplicaFailure
  phase: Succeeded

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）；
• 副本当前的运行阶段，此处的“运行阶段”在 K8s Pod 的 5 个阶段的基础上，添加了 Creating 和 Deleted 分别表示正在创建和已删除；
• 副本在集群中对应的 Pod 的索引信息。

在下面的示例中，PyTorchTrainingJob 创建了 1 个角色为 worker 的副本，当前均处于 Succeeded 阶段，运行在 torch-mnist-trainingjob-5b373-worker-0 这个 Pod 上。

...
status:
  tasks:
  - replicas:
    - containers:
      - exitCode: 0
        name: pytorch
        state: Terminated
      name: torch-mnist-trainingjob-5b373-worker-0
      phase: Succeeded
      uid: d39f91d6-9c48-4c57-bb71-4131226395b6
    type: worker

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面示例中，PyTorchTrainingJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

TensorBoard 状态

status.tensorboard 字段用来记录 TensorBoard 的状态。

在下面的示例中，PyTorchTrainingJob 创建了名为 torch-mnist-trainingjob-5b373 的 TensorBoard，TensorBoard 目前运行正常。

status:
  tensorboard:
    action: NOP
    dependent:
      apiVersion: tensorstack.dev/v1beta1
      kind: TensorBoard
      name: torch-mnist-trainingjob-5b373
      namespace: demo
      uid: b09378f3-2164-4f14-a425-a1340fa32d7d
    note: TensorBoard [torch-mnist-trainingjob-5b373] is ready
    ready: true
    reason: DependentReady
    type: Normal

下一步

• 了解如何使用 PyTorchTrainingJob 进行数据并行训练
• 了解如何使用 PyTorchTrainingJob 进行参数服务器训练

TensorFlowTrainingJob

TensorFlowTrainingJob 是服务于 TensorFlow 分布式训练框架的 T9k Job。

你可以较为方便地使用 TensorFlowTrainingJob 为 TensorFlow 训练脚本提供训练环境，并监控训练进程。

创建 TensorFlowTrainingJob

下面是一个基本的 TensorFlowTrainingJob 配置示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: TensorFlowTrainingJob
metadata:
  name: tensorflow-example
spec:
  replicaSpecs:
  - replicas: 4
    restartPolicy: OnFailure
    template:
      spec:
        containers:
        - command:
          - python
          - dist_mnist.py
          image: tensorflow/tensorflow:2.11.0
          name: tensorflow
          resources:
            limits:
              cpu: 1
              memory: 2Gi
            requests:
              cpu: 500m
              memory: 1Gi
    type: worker

在该例中：

• 创建 4 个副本（由 spec.replicaSpecs[*].replicas 字段指定），副本的角色为 worker（由 spec.replicaSpecs[*].type 字段指定）。
• 每个副本使用 tensorflow/tensorflow:2.11.0 镜像，执行命令 python dist_mnist.py（由 spec.replicaSpecs<a target="_blank" rel="noopener noreferrer" href="https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates">*].template 字段指定，此处的填写方式参考 [PodTemplate）。
• 当副本失败后，会自动重启（由 spec.replicaSpecs[*].restartPolicy 字段指定）。

副本的角色

在 TensorFlow 分布式训练框架中，副本有 4 种类型：Chief、Worker、PS 和 Evaluator。

在 TensorFlowTrainingJob 中，副本的类型由 spec.replicaSpecs[*].type 字段指定，分别是 chief、worker、ps 和 evaluator。

成功和失败

在 TensorFlow 分布式训练框架中，Chief 是主节点。如果没有指定 Chief，则会选择第一个 Worker 作为主节点。当分布式训练的主节点执行完成时，TensorFlow 分布式训练成功；反之，当分布式训练的主节点执行失败时，TensorFlow 分布式训练失败。

在 TensorFlowTrainingJob 中，如果没有 Chief 副本，则选取序号为 0 的 Worker 节点作为主节点。主节点的失败有时可能是因为环境因素导致的，比如集群网络断连、集群节点崩溃等等，此类原因导致的失败应该被允许自动恢复。针对这一情况，TensorFlowTrainingJob 允许副本重启（请参阅重启机制），并设定了重启次数限制（由 spec.runPolicy.backoffLimit 字段指定），当副本重启次数达到上限后，如果主节点再次失败，则 TensorFlowTrainingJob 失败。此外，TensorFlowTrainingJob 可以设置最长执行时间（由 spec.runPolicy.activeDeadlineSeconds 字段指定），当超过这个执行时间后，TensorFlowTrainingJob 失败。

如果 TensorFlowTrainingJob 在没有超过重启次数和没有超过最长执行时间的情况下成功完成了主节点的运行，则 TensorFlowTrainingJob 成功。

重启机制

TensorFlowTrainingJob 的 spec.replicaSpec[*].template 字段使用 PodTemplate 的规范填写，但是 Pod 的重启策略并不能完全满足 TensorFlowTrainingJob 的需求，所以 TensorFlowTrainingJob 使用 spec.replicaSpec[*].restartPolicy 字段覆盖 spec.replicaSpec[*].template 中指定的重启策略。

可选的重启策略有以下四种：

• Never：不重启
• OnFailure：失败后重启
• Always：总是重启
• ExitCode：特殊退出码重启

使用 Never 重启策略时，Job 的副本失败后不会重启。如果需要调试代码错误，可以选择此策略，便于从副本中读取训练日志。

ExitCode 是一种比较特殊的重启策略，它将失败进程的返回值分为两类：一类是由于系统环境原因或用户操作导致的错误，此类错误可以通过重启解决；另一类是代码错误或者其他不可自动恢复的错误。可重启的退出码包括：

• 130（128+2）：使用 Control+C 终止容器运行。
• 137（128+9）：容器接收到 SIGKILL 信号。
• 143（128+15）：容器接收到 SIGTERM 信号。
• 138：用户可以自定义这个返回值的含义。如果用户希望程序在某处退出并重启，可以在代码中写入这个返回值。

重启次数限制

如果因为某种原因（例如代码错误或者环境错误并且长时间没有修复），TensorFlowTrainingJob 不断地失败重启却无法解决问题，这会导致集群资源的浪费。用户可以通过设置 spec.runPolicy.backoffLimit 字段来设置副本的最大重启次数。重启次数为所有副本共享，即所有副本重启次数累计达到此数值后，副本将不能再次重启。

清除策略

在训练结束后，可能有些副本仍处于运行状态，比如 TensorFlow 训练框架中的 PS 经常在训练完成后仍然保持运行。这些运行的副本仍然会占用集群资源，TensorFlowTrainingJob 提供清除策略，在训练结束后删除这些副本。

TensorFlowTrainingJob 提供以下三种策略：

• None：不删除副本。
• All：删除所有副本。
• Unfinished：只删除未结束的副本。

`None` 策略主要用于训练脚本调试阶段。如果需要从副本中读取训练日志，则可以选用此策略。但由于这些副本可能占用资源并影响后续训练，建议你在调试完毕后手动删除这些副本或删除整个 TensorFlowTrainingJob。

调度器

目前 TensorFlowTrainingJob 支持使用以下两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler 调度器

调度器通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，TensorFlowTrainingJob 启用 T9k Scheduler 调度器，将副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

TensorBoard 的使用

TensorFlowTrainingJob 支持使用 TensorBoard 对训练过程和结果进行实时可视化（由 spec.tensorboardSpec 字段设置）。

在下面的示例中，TensorFlowTrainingJob 使用 t9kpublic/tensorflow-2.11.0:cpu-sdk-0.5.2 镜像创建一个 TensorBoard，可视化名为 tensorflow-tensorboard-pvc 的 PVC 中 /log 路径下的模型数据。

...
spec:
  tensorboardSpec:
    image: t9kpublic/tensorflow-2.11.0:cpu-sdk-0.5.2
    trainingLogFilesets:
    - t9k://pvc/tensorflow-tensorboard-pvc/log
...

调试模式

TensorFlowTrainingJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，默认为 sleep inf。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了调试模式，副本使用默认调试设置，即不跳过 InitContainer，并执行 sleep inf。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

TensorFlowTrainingJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 TensorFlowTrainingJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

TensorFlowTrainingJob 状态

TensorFlowTrainingJob 的状态和阶段

status.conditions 字段用于描述当前 TensorFlowTrainingJob 的状态，包括以下 6 种类型：

1. Initialized：TensorFlowTrainingJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：TensorFlowTrainingJob 成功。
5. Failed：TensorFlowTrainingJob 失败。
6. Paused：TensorFlowTrainingJob 进入暂停模式，所有副本都已删除或正在删除。

status.phase 字段用于描述当前 TensorFlowTrainingJob 所处的阶段，TensorFlowTrainingJob 的整个生命周期主要有以下7个阶段：

1. Pending：TensorFlowTrainingJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Paused：TensorFlowTrainingJob 进入暂停模式。
4. Resuming：TensorFlowTrainingJob 正从暂停模式中恢复运行。恢复运行后，切换为 Running 阶段。
5. Succeeded：TensorFlowTrainingJob 成功。
6. Failed：TensorFlowTrainingJob 失败。
7. Unknown：控制器无法获得 TensorFlowTrainingJob 的阶段。

在下面的示例中，TensorFlowTrainingJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；TensorFlowTrainingJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；TensorFlowTrainingJob 的训练成功结束，所以类型为 Completed 的 condition 被设置为 True（原因是 The job has finished successfully.）。当前 TensorFlowTrainingJob 运行阶段为 Succeeded。

...
status:
  conditions:
    - lastTransitionTime: "2023-12-19T02:40:25Z"
      message: The job has been initialized successfully.
      reason: '-'
      status: "True"
      type: Initialized
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "False"
      type: Running
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "False"
      type: Failed
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "True"
      type: Completed
    - lastTransitionTime: "2023-12-19T02:40:25Z"
      message: All pods are running normally.
      reason: '-'
      status: "False"
      type: ReplicaFailure
  phase: Succeeded

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）；
• 副本当前的运行阶段，此处的“运行阶段”在 K8s Pod 的 5 个阶段的基础上，添加了 Creating 和 Deleted 分别表示正在创建和已删除；
• 副本在集群中对应的 Pod 的索引信息。

在下面的示例中，TensorFlowTrainingJob 创建了 1 个角色为 worker 的副本，当前均处于 Succeeded 阶段，运行在 mnist-trainingjob-5b373-worker-0 这个 Pod 上。

...
status:
  tasks:
  - replicas:
    - containers:
      - exitCode: 0
        name: pytorch
        state: Terminated
      name: mnist-trainingjob-5b373-worker-0
      phase: Succeeded
      uid: d39f91d6-9c48-4c57-bb71-4131226395b6
    type: worker

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面示例中，TensorFlowTrainingJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

TensorBoard 状态

status.tensorboard 字段用来记录 TensorBoard 的状态。

在下面的示例中，TensorFlowTrainingJob 创建了名为 mnist-trainingjob-5b373 的 TensorBoard，TensorBoard 目前运行正常。

status:
  tensorboard:
    action: NOP
    dependent:
      apiVersion: tensorstack.dev/v1beta1
      kind: TensorBoard
      name: mnist-trainingjob-5b373
      namespace: demo
      uid: b09378f3-2164-4f14-a425-a1340fa32d7d
    note: TensorBoard [mnist-trainingjob-5b373] is ready
    ready: true
    reason: DependentReady
    type: Normal

下一步

• 了解如何使用 TensorFlowTrainingJob 进行数据并行训练
• 了解如何使用 TensorFlowTrainingJob 进行参数服务器训练

DeepSpeedJob

DeepSpeedJob 是服务于 DeepSpeed 分布式训练框架的 T9k Job。

你可以较为方便地使用 DeepSpeedJob 为 DeepSpeed 训练脚本提供训练环境，并监控训练进程。

创建 DeepSpeedJob

下面是一个基本的 DeepSpeedJob 配置示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: DeepspeedJob
metadata:
  name: deepspeed-example
spec:
  config:
    slotPerWorker: 1
    run:
      python: /t9k/mnt/train.py
  worker:
    replicas: 4
    template:
      spec:
        restartPolicy: OnFailure
        containers:
        - image: deepspeed/deepspeed:v072_torch112_cu117
          imagePullPolicy: IfNotPresent
          name: worker
          resources:
            limits:
              cpu: 4
              memory: 4Gi
            requests:
              cpu: 2
              memory: 2Gi
          volumeMounts:
          - mountPath: /t9k/mnt
            name: code
        volumes:
        - name: code
          persistentVolumeClaim:
            claimName: deepspeed

在该例中：

• 创建 4 个训练副本，这些副本会启动 sshd 服务。
• 第一个副本会启动 deepspeed 程序，该程序会通过 pdsh（或其他方式）访问 4 个副本，并在每个副本上运行 /t9k/mnt/train.py 脚本。

训练配置

DeepSpeedJob 在 spec.config 中配置如何执行训练。有以下参数可以设置：

• run：如何启动训练，以下三个参数只能填写一个，否则报错：
  • python：使用 Python 脚本进行训练。指定 Python 文件以及启动参数。
  • module：使用 Python module 进行训练。指定 Python module 以及启动参数。
  • exec：使用可执行文件/命令进行训练。指定可执行文件以及启动参数。
• slotsPerWorker：每一个副本上设置多少个“插槽”。“插槽”是继承自 MPI 中的概念，表示一个副本上可以运行多少个训练进程。一般来说该值被设为每个副本分配的 GPU 数量。例如当创建了一个 replica 为 4 的任务，并且给每个副本分配了 2 个 nvidia.com/gpu，则应该将 slotsPerWorker 设为 2，这样最后一共会运行 4 * 2 = 8 个训练进程。
• localRank：是否传递 LOCAL_RANK 环境变量，默认为 true。
• autotune：启用超参数调优，可以设置为 none、run、tune，默认为 none。none 为不启动超参数调优；tune 只查找最合适的超参数组合，但是不执行训练；run 查找最合适的超参数组合，并用该超参数执行训练。
• otherArgs：设置其他 DeepSpeed 参数，详见下文。

otherArgs

DeepSpeedJob 希望提供用户足够的灵活性，所以支持用户通过 otherArgs 字段设置传入 DeepSpeed 的参数。config 中的配置实际上也是通过 DeepSpeed 参数实现的，以下列出除了在配置文件中指定的参数之外的其他可用参数：

• --launcher： 多节点训练使用的启动器后端，目前的选项包括 PDSH、OpenMPI、MVAPICH、SLURM、MPICH。（默认：pdsh）。目前 DeepSpeedJob 只支持 pdsh。
• --no_ssh_check：多节点训练时不执行 ssh 检查。
• --save_pid： 在 /tmp/<main-pid>.ds 处保存包含启动器进程 ID（pid），其中 <main-pid> 是第一个调用 DeepSpeed 的进程的 pid。PDSH 模式下不支持。
• --enable_each_rank_log： 将每个 Rank 的 stdout 和 stderr 重定向到不同的日志文件。PDSH 模式下不支持。
• --bind_cores_to_rank：将每个 Rank 绑定到主机的不同核心。PDSH 模式下不支持。
• --bind_core_list：要绑定的核心列表，以逗号分隔。例如 1,3-5,7 => [1,3,4,5,7]。 未指定时，系统上的所有核心都将被绑定。PDSH 模式下不支持。

训练的成功和失败判定

DeepSpeedJob 分布式训练框架中，第一个训练副本（下文记为 worker-0）是分布式任务的主节点。当 worker-0 成功结束，则 DeepSpeedJob 训练成功；反之，当 worker-0 执行失败，DeepSpeedJob 训练失败。

如果一次训练执行时间过长，用户可能需要考虑代码是否需要优化、是否需要分配更多资源等问题。DeepSpeedJob 可以设置最长执行时间（由 spec.runPolicy.activeDeadlineSeconds 字段指定），当超过这个执行时间后，训练失败。

清除策略

在训练完毕后，可能有些副本仍处于运行状态。这些运行的副本仍然会占用集群资源，DeepSpeedJob 提供清除策略，可以在训练结束后删除这些训练副本。

DeepSpeedJob 提供以下三种策略：

• None：不删除副本。
• All：删除所有副本。
• Unfinished：只删除未结束的副本。

`None` 策略主要用于训练脚本调试阶段。如果需要从副本中读取训练日志，则可以选用此策略。但由于这些副本可能占用资源并影响后续训练，建议你在调试完毕后手动删除这些副本或删除整个 DeepSpeedJob。

调度策略

目前 DeepSpeedJob 支持两种调度策略：

1. Kubernetes 的默认调度器
2. T9k Scheduler

调度策略通过 CRD 的 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度策略。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，MPIJob 启用 T9k Scheduler 调度器，将副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

调试模式

DeepSpeedJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，默认为 /usr/sbin/sshd -D。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 sleep inf。
• 示例二：开启了调试模式，副本使用默认调试设置，即不跳过 InitContainer，并执行 /usr/sbin/sshd -D。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["sleep", "inf"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

DeepSpeedJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 DeepSpeedJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

DeepSpeedJob 状态

DeepSpeedJob 的状态和阶段

status.conditions 字段用于描述当前 DeepSpeedJob 的状态，包括以下 5 种类型：

1. Initialized：DeepSpeedJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：DeepSpeedJob 成功。
5. Failed：DeepSpeedJob 失败。

status.phase 字段用于描述当前 DeepSpeedJob 所处的阶段，DeepSpeedJob 的整个生命周期主要有以下几个阶段：

1. Pending：DeepSpeedJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Succeeded：DeepSpeedJob 成功。
4. Failed：DeepSpeedJob 失败。
5. Unknown：控制器无法获得 DeepSpeedJob 的阶段。

在下面的示例中，DeepSpeedJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；DeepSpeedJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；但是 DeepSpeedJob 的训练结果是失败的，所以类型为 Failed 的 condition 被设置为 True。当前 DeepSpeedJob 运行阶段为 Failed。

...
status:
  conditions:
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "The job has been initialized successfully."
      reason: "-"
      type: Initializing
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "All pods are running normally."
      reason: "-"
      type: Running
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "False"
      message: "All pods are running normally."
      reason: "-"
      type: ReplicaFailure
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "False"
      message: "The job exited with an error code."
      reason: "Failed"
      type: Completed
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "True"
      message: "The job exited with an error code."
      reason: "Failed"
      type: Failed
  phase: Failed

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）
• 副本当前的运行阶段
• 副本在集群中对应的 Pod 的索引信息

在下面的示例中，DeepSpeedJob 创建了 2 个训练副本，当前均处于 Running 阶段，分别运行在 deepspeed-example-worker-0 和 deepspeed-example-worker-1 这 2 个 Pod 上。

...
status:
  tasks:
  - type: worker
    restartCount: 0
    status:
    - phase: Running
      name: deepspeed-example-worker-0
      uid: e3ec2ee3-6645-4e21-993f-1e472b94e0ae
      containers: []
    - phase: Running
      name: deepspeed-example-worker-1
      uid: 908a93f0-7b8b-491e-85d5-3da0abcb4ca4
      containers: []

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面的示例中，DeepSpeedJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

ColossalAIJob

ColossalAIJob 是服务于 ColossalAI 分布式训练框架的 T9k Job。

你可以较为方便地使用 ColossalAIJob 为 ColossalAI 训练脚本提供训练环境，并监控训练进程。

创建 ColossalAIJob

下面是一个基本的 ColossalAIJob 配置示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: ColossalAIJob
metadata:
  name: colossalai-example
spec:
  ssh:
    authMountPath: /root/.ssh
    sshdPath: /usr/sbin/sshd
  launcher:
    image: hpcaitech/colossalai:0.3.0
    workingDir: /workspace
    env: []
    resources: 
      limits:
        cpu: 1
        memory: 2Gi
      requests:
        cpu: 500m
        memory: 1Gi
  worker:
    replicas: 2
    procPerWorker: 1
    command:
      - train.py
      - arg1
    torchArgs: []
    template:
      spec:
        restartPolicy: OnFailure
        containers:
          - image: hpcaitech/colossalai:0.3.0
            imagePullPolicy: IfNotPresent
            name: worker
            resources:
              limits:
                cpu: 2
                memory: 8Gi
                nvidia.com/gpu: 1
              requests:
                cpu: 1
                memory: 4Gi
                nvidia.com/gpu: 1
            volumeMounts:
              - mountPath: /workspace
                name: code
        volumes:
          - name: code
            persistentVolumeClaim:
              claimName: colossalai

在该例中：

• 创建 1 个启动副本，该启动副本是 ColossalAI 在训练中所必须的，启动副本的配置参考 PodTemplate，这里不再赘述（启动副本的配置由 spec.launcher 字段指定）。
• 创建 2 个执行副本（由 spec.worker.replicas 字段指定），每个执行副本上启动 1 个训练进程（由 spec.worker.procPerWorker 字段指定），训练脚本和参数为 train.py arg1（由 spec.worker.command 字段指定），执行副本的其他配置参考 PodTemplate，这里不再赘述（这些配置由 spec.worker.template 字段指定）。
• 执行副本需要执行 sshd 程序，等待启动副本发来训练指令。sshd 的路径为 /user/sbin/sshd（由 spec.ssh.sshdPath 字段指定，使用该字段的原因是 sshd 程序必须使用绝对路径调用，所以需要其具体路径）。

成功和失败

在 ColossalAIJob 分布式训练框架中：

• 如果启动副本执行失败，ColossalAIJob 训练失败。
• 如果启动副本执行成功，ColossalAIJob 并不一定成功：启动副本的作用是启动训练和监测，无论是训练成功还是失败，启动副本都会正常结束，而不是报错。因此，如果要确定 ColossalAIJob 是否成功结束，需要检查启动副本的日志。

重启机制

与其他 TrainingJob 不同，ColossalAIJob 使用 colossalairun 作为启动命令，在这种情况下，Pod 失败重启后不会再加入到训练中。所以 ColossalAIJob 无法像其他 TrainingJob 那样支持 Pod 失败重启。

清除策略

在 ColossalAIJob 训练结束后，ColossalAIJob 控制器可以清理所创建的 Kubernetes 资源，使 ColossalAIJob 不再浪费集群资源（内存、CPU 等）。一般来说，你需要查看启动副本的日志来确定训练结果，所以启动副本不在清理范围之内，ColossalAIJob 控制器只清理执行副本（通过 spec.runPolicy.cleanUpWorkers 字段设置）。

在下面的示例中，ColossalAIJob 在训练结束后会自动删除所有执行副本：

...
spec:
  runPolicy:
    cleanUpWorkers: true

调度器

目前 ColossalAIJob 支持两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler 调度器

调度器通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，ColossalAIJob 启用 T9k Scheduler 调度器，将执行副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

调试模式

ColossalAIJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，默认为 sleep inf。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了调试模式，副本使用默认调试设置，即不跳过 InitContainer，并执行 sleep inf。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

ColossalAIJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 ColossalAIJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

ColossalAIJob 状态

ColossalAIJob 的状态和阶段

status.conditions 字段用于描述当前 ColossalAIJob 的状态，包括以下 5 种类型：

1. Initialized：ColossalAIJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：ColossalAIJob 成功。
5. Failed：ColossalAIJob 失败。
6. Paused：ColossalAIJob 进入暂停模式，所有副本都已删除或正在删除。

status.phase 字段用于描述当前 ColossalAIJob 所处的阶段，ColossalAIJob 的整个生命周期主要有以下几个阶段：

1. Pending：ColossalAIJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Paused：ColossalAIJob 进入暂停模式。
4. Resuming：ColossalAIJob 正从暂停模式中恢复运行。恢复运行后，切换为 Running 阶段。
5. Succeeded：ColossalAIJob 成功。
6. Failed：ColossalAIJob 失败。
7. Unknown：控制器无法获得 ColossalAIJob 的阶段。

在下面的示例中，ColossalAIJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；ColossalAIJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；但是 ColossalAIJob 的训练结果是失败的，所以类型为 Failed 的 condition 被设置为 True。当前 ColossalAIJob 运行阶段为 Failed。

...
status:
  conditions:
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "The job has been initialized successfully."
      reason: "-"
      type: Initializing
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "All pods are running normally."
      reason: "-"
      type: Running
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "False"
      message: "All pods are running normally."
      reason: "-"
      type: ReplicaFailure
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "False"
      message: "The job exited with an error code."
      reason: "Failed"
      type: Completed
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "True"
      message: "The job exited with an error code."
      reason: "Failed"
      type: Failed
  phase: Failed

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）
• 副本当前的运行阶段
• 副本在集群中对应的 Pod 的索引信息

在下面的示例中，ColossalAIJob 创建了 1 个启动副本和 2 个执行副本。执行副本当前均处于 Running 阶段，分别运行在 colossalai-example-worker-0 和 colossalai-example-worker-1 这 2 个 Pod 上；启动副本当前处于 Running 阶段，运行在 colossalai-example-launcher Pod 上。

...
status:
  tasks:
  - type: launcher
    restartCount: 0
    status:
    - phase: Running
      name: colossalai-example-launcher
      uid: 66634db2-35e7-4641-a4dc-adbd5479734e
      containers: []
  - type: worker
    restartCount: 0
    status:
    - phase: Running
      name: colossalai-example-worker-0
      uid: e3ec2ee3-6645-4e21-993f-1e472b94e0ae
      containers: []
    - phase: Running
      name: colossalai-example-worker-1
      uid: 908a93f0-7b8b-491e-85d5-3da0abcb4ca4
      containers: []

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面的示例中，ColossalAIJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

XGBoostTrainingJob

XGBoostTrainingJob 是服务于 XGBoost 分布式计算框架的 T9k Job。

你可以较为方便地使用 XGBoostTrainingJob 为 XGBoost 计算程序提供训练环境，并监控训练进程。

创建 XGBoostTrainingJob

下面是一个基本的 XGBoostTrainingJob 配置示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: XGBoostTrainingJob
metadata:
  name: training-iris-xgb
spec:
  replicaSpecs:
    - type: master
      replicas: 1
      restartPolicy: OnFailure
      template:
        spec:
          containers:
            - name: xgboost
              image: t9kpublic/xgboost-dist-iris:3.7
              command:
                - python3
                - /mnt/main.py
                - --job_type=Train
                - --xgboost_parameter=objective:multi:softprob,num_class:3
                - --n_estimators=10
                - --learning_rate=0.1
                - --model_path=/mnt/xgboost_model/
                - --model_storage_type=local
    - type: worker
      replicas: 2
      restartPolicy: OnFailure
      template:
          containers:
            - name: xgboost
              image: t9kpublic/xgboost-dist-iris:3.7
              command:
                - python3
                - /mnt/main.py
                - --job_type=Train
                - --xgboost_parameter=objective:multi:softprob,num_class:3
                - --n_estimators=10
                - --learning_rate=0.1
                - --model_path=/mnt/xgboost_model/
                - --model_storage_type=local

在该例中：

• 创建 1 个 master 副本和 2 个 worker 副本（由 spec.replicaSpecs[*].replicas 字段和 spec.replicaSpecs[*].type 字段指定）。
• 每个副本使用 registry.tensorstack.cn/t9kmirror/xgboost-dist-iris:1.1 镜像，执行命令 python3 /mnt/main.py --job_type=Train --xgboost_parameter=objective:multi:softprob,num_class:3 --n_estimators=10 --learning_rate=0.1 --model_path=/mnt/xgboost_model/ --model_storage_type=local（由 spec.replicaSpecs<a target="_blank" rel="noopener noreferrer" href="https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates">*].template 字段指定，此处的填写方式参考 [PodTemplate）。
• 当副本失败后，会自动重启（由 spec.replicaSpecs[*].restartPolicy 字段指定）。

成功和失败

在 XGBoost 分布式训练框架中，副本有 2 种类型：Master 和 Worker，其中 Master 是主节点。当分布式训练的主节点成功结束时，XGBoost 分布式训练成功；反之，当分布式训练的主节点执行失败时，XGBoost 分布式训练失败。

但是主节点的失败有时可能是因为环境因素导致的，比如集群网络断连、集群节点崩溃等等，此类原因导致的失败应该被允许自动恢复。针对这一情况，XGBoostTrainingJob 允许副本重启（请参阅重启机制），并设定了重启次数限制（由 spec.runPolicy.backoffLimit 字段指定），当副本重启次数达到上限后，如果主节点再次失败，则训练失败。此外，XGBoostTrainingJob 可以设置最长执行时间（由 spec.runPolicy.activeDeadlineSeconds 字段指定），当超过这个执行时间后，训练失败。

如果 XGBoostTrainingJob 在没有超过重启次数和没有超过最长执行时间的情况下成功完成了主节点的运行，则训练成功。

重启机制

XGBoostTrainingJob 的 spec.replicaSpec[*].template 字段使用 PodTemplate 的规范填写，但是 Pod 的重启策略并不能满足 XGBoostTrainingJob 的需求，所以 XGBoostTrainingJob 使用 spec.replicaSpec[*].restartPolicy 字段覆盖 spec.replicaSpec[*].template 中指定的重启策略。

可选的重启策略有以下四种：

• Never：不重启
• OnFailure：失败后重启
• Always：总是重启
• ExitCode：特殊退出码重启

使用 Never 重启策略时，Job 的副本失败后不会重启。如果需要调试代码错误，可以选择此策略，便于从副本中读取训练日志。

ExitCode 是一种比较特殊的重启策略，它将失败进程的返回值分为两类：一类是由于系统环境原因或用户操作导致的错误，此类错误可以通过重启解决；另一类是代码错误或者其他不可自动恢复的错误。可重启的退出码包括：

• 130（128+2）：使用 Control+C 终止容器运行。
• 137（128+9）：容器接收到 SIGKILL 信号。
• 143（128+15）：容器接收到 SIGTERM 信号。
• 138：用户可以自定义这个返回值的含义。如果用户希望程序在某处退出并重启，可以在代码中写入这个返回值。

重启次数限制

如果因为某种原因（例如代码错误或者环境错误并且长时间没有修复），XGBoostTrainingJob 不断地失败重启却无法解决问题，这会导致集群资源的浪费。用户可以通过设置 spec.runPolicy.backoffLimit 字段来设置副本的最大重启次数。重启次数为所有副本共享，即所有副本重启次数累计达到此数值后，副本将不能再次重启。

清除策略

在训练结束后，可能有些副本仍处于运行状态。这些运行的副本仍然会占用集群资源，XGBoostTrainingJob 提供清除策略，在训练结束后删除这些训练节点。

XGBoostTrainingJob 提供以下三种策略：

• None：不删除副本。
• All：删除所有副本。
• Unfinished：只删除未结束的副本。

`None` 策略主要用于训练脚本调试阶段。如果需要从副本中读取训练日志，则可以选用此策略。但由于这些副本可能占用资源并影响后续训练，建议你在调试完毕后手动删除这些副本或删除整个 XGBoostTrainingJob。

调度器

目前 XGBoostTrainingJob 支持使用以下两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler 调度器

调度器通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，XGBoostTrainingJob 启用 T9k Scheduler 调度器，将副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

调试模式

XGBoostTrainingJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，默认为 sleep inf。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了调试模式，副本使用默认调试设置，即不跳过 InitContainer，并执行 sleep inf。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

XGBoostTrainingJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 XGBoostTrainingJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

XGBoostTrainingJob 状态

XGBoostTrainingJob 的状态和阶段

status.conditions 字段用于描述当前 XGBoostTrainingJob 的状态，包括以下 6 种类型：

1. Initialized：XGBoostTrainingJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：XGBoostTrainingJob 成功。
5. Failed：XGBoostTrainingJob 失败。
6. Paused：XGBoostTrainingJob 进入暂停模式，所有副本都已删除或正在删除。

status.phase 字段用于描述当前 XGBoostTrainingJob 所处的阶段，XGBoostTrainingJob 的整个生命周期主要有以下7个阶段：

1. Pending：XGBoostTrainingJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Paused：XGBoostTrainingJob 进入暂停模式。
4. Resuming：XGBoostTrainingJob 正从暂停模式中恢复运行。恢复运行后，切换为 Running 阶段。
5. Succeeded：XGBoostTrainingJob 成功。
6. Failed：XGBoostTrainingJob 失败。
7. Unknown：控制器无法获得 XGBoostTrainingJob 的阶段。

在下面的示例中，XGBoostTrainingJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；XGBoostTrainingJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；XGBoostTrainingJob 的训练成功结束，所以类型为 Completed 的 condition 被设置为 True（原因是 The job has finished successfully.）。当前 XGBoostTrainingJob 运行阶段为 Succeeded。

...
status:
  conditions:
    - lastTransitionTime: "2023-12-19T02:40:25Z"
      message: The job has been initialized successfully.
      reason: '-'
      status: "True"
      type: Initialized
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "False"
      type: Running
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "False"
      type: Failed
    - lastTransitionTime: "2023-12-19T02:53:14Z"
      message: The job has finished successfully.
      reason: Succeeded
      status: "True"
      type: Completed
    - lastTransitionTime: "2023-12-19T02:40:25Z"
      message: All pods are running normally.
      reason: '-'
      status: "False"
      type: ReplicaFailure
  phase: Succeeded

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）；
• 副本当前的运行阶段，此处的“运行阶段”在 K8s Pod 的 5 个阶段的基础上，添加了 Creating 和 Deleted 分别表示正在创建和已删除；
• 副本在集群中对应的 Pod 的索引信息。

在下面的示例中，XGBoostTrainingJob 创建了 1 个角色为 worker 的副本，当前均处于 Succeeded 阶段，运行在 mnist-trainingjob-5b373-worker-0 这个 Pod 上。

...
status:
  tasks:
  - replicas:
    - containers:
      - exitCode: 0
        name: pytorch
        state: Terminated
      name: mnist-trainingjob-5b373-worker-0
      phase: Succeeded
      uid: d39f91d6-9c48-4c57-bb71-4131226395b6
    type: worker

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面示例中，XGBoostTrainingJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

MPIJob

OpenMPI 是一个开源的 MPI（Message Passing Interface）协议的实现项目。

MPIJob 是一种使用 OpenMPI 进行分布式计算的 T9k Job，此资源让你能够方便地在集群环境中使用 OpenMPI 进行训练。

创建 MPIJob

下面的 MPIJob 示例创建了 5 个执行副本，每个执行副本启动 3 个进程，运行随机游走程序：

apiVersion: batch.tensorstack.dev/v1beta1
kind: MPIJob
metadata:
  name: mpi-example
spec:
  worker:
    replicas: 5
    extraMPIArgs:
      - -N
      - "3"
      - --enable-recovery
      - --max-restarts
      - "100"
      - --allow-run-as-root
      - -bind-to
      - none
    cmd:
      - ./random_walk
      - "20"
      - "40"
      - "2"
    template:
      spec:
        containers:
          - name: mpi-worker
            image: t9kpublic/mpi-tutorial:2021022-2
            resources:
              limits:
                cpu: 100m
              requests:
                cpu: 50m
            workingDir: /usr/local/code
  mca:
    btl: ^openib
  runPolicy:
    cleanUpWorkers: true
  ssh:
    sshdPath: /usr/sbin/sshd
  mpiHome: /usr/local

在该例中：

• 创建 5 个执行副本（由 spec.worker.replicas 字段指定）。
• spec.worker.template 字段沿用 PodTemplate 的规约，配置执行副本和启动副本的环境。每个执行副本包含一个名为 mpi-worker 的容器（为了确定用于执行 MPI 进程的容器，执行副本定义中必须有一个名为 mpi-worker 的容器）。mpi-worker 容器创建后执行 sshd 命令并等待启动副本连接，所以此容器会忽略 PodTemplate 定义中的 command 和 args 字段（因此该例中没有填写这两个字段）。
• 在执行副本准备完毕后，启动副本向执行副本发送启动命令，令执行副本创建 3 个 MPI 进程，这些进程分别执行 ./random_walk 20 40 2（由 spec.worker.cmd 字段指定）命令。
• 在训练过程中不使用 Infiniband 进行通信（由 spec.mca.btl 字段指定）。
• 在训练结束后自动清除副本（由 spec.runPolicy.cleanUpWorkers 字段指定）来释放集群资源。
• sshd 的路径为 /user/sbin/sshd（由 spec.ssh.sshdPath 字段指定，使用该字段的原因是 sshd 程序必须使用绝对路径调用，所以需要其具体路径）。
• MPI 安装在 /usr/local 处（由 spec.mpiHome 字段指定，使用该字段的原因是 mpirun 的有些功能需要知道 MPI 的根目录地址才能正确运行）。

运行 Horovod 训练脚本

使用 Horovod 框架的分布式训练脚本也可以使用 MPIJob 进行训练。

在 MPIJob 中需要执行以下操作：

1. 在 spec.worker.template.spec.containers[mpi-worker].env 字段中添加 NCCL_DEBUG；
2. 在 spec.mca 字段中添加 pml:ob1 和 btl:^openib。

下面是使用 MPIJob 执行 Horovod 框架的分布式训练脚本的示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: MPIJob
metadata:
  name: mpi-example
spec:
  mca:
    btl: ^openib
    pml: ob1
  worker:
    template:
      spec:
        containers:
          - name: mpi-worker
            env: 
            - name: "NCCL_DEBUG"
              value: "INFO"
...

调度器

目前 MPIJob 支持使用以下两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler

调度策略通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，MPIJob 启用 T9k Scheduler 调度器，将执行副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50

调试模式

MPIJob 支持调试模式。在该模式下，训练环境会被部署好，但不会启动训练，用户可以连入副本测试环境或脚本。

该模式可以通过 spec.runMode.debug 字段来设置：

• spec.runMode.debug.enabled 表示是否启用调试模式。
• spec.runMode.debug.replicaSpecs 表示如何配置各个副本的调试模式：
  • spec.runMode.debug.replicaSpecs.type 表示作用于的副本类型。
  • spec.runMode.debug.replicaSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.debug.replicaSpecs.command 表示副本在等待调试的时候执行的命令，launcher 的默认命令为 sleep inf，worker 的默认命令为 /usr/bin/sshd -D。
  • 如果不填写 spec.runMode.debug.replicaSpecs 字段，则表示所有副本都使用默认设置。

在下面的示例中：

• 示例一：开启了调试模式，并配置 worker 跳过 InitContainer，并执行 sleep inf。
• 示例二：开启了调试模式，副本使用默认调试设置，即 worker 不跳过 InitContainer，并执行 /usr/bin/sshd -D。

# 示例一
...
spec:
  runMode:
    debug:
      enabled: true
      replicaSpecs:
        - type: worker
          skipInitContainer: true
          command: ["sleep", "inf"]

---
# 示例二
...
spec:
  runMode:
    debug:
      enabled: true

暂停模式

MPIJob 支持暂停模式。在该模式下，删除（或不创建）副本，停止训练。

该模式可以通过 spec.runMode.pause 字段来设置：

• spec.runMode.pause.enabled 表示是否启用暂停模式。
• spec.runMode.pause.resumeSpecs 表示结束暂停后，如何恢复各个副本：
  • spec.runMode.pause.resumeSpecs.type 表示作用于的副本类型。
  • spec.runMode.pause.resumeSpecs.skipInitContainer 表示让副本的 InitContainer 失效，默认为 false。
  • spec.runMode.pause.resumeSpecs.command 和 spec.runMode.pause.resumeSpecs.args 表示副本在恢复运行时候执行的命令，默认使用 spec.replicaSpecs[0].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

用户可以随时修改 spec.runMode.pause.enabled 来控制任务暂停，但是不可以更改 spec.runMode.pause.resumeSpecs，所以如果有暂停 MPIJob 的需求，请提前设置好恢复设置。

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[0].template 中设置的命令。

# 示例一
...
spec:
  runMode:
    pause:
      enabled: true
      resumeSpecs:
        - type: worker
          skipInitContainer: true
          command: ["/usr/bin/sshd"]

---
# 示例二
...
spec:
  runMode:
    pause:
      enabled: true

MPIJob 状态

MPIJob 的状态和阶段

status.conditions 字段用于描述当前 MPIJob 的状态，包括以下 5 种类型：

1. Initialized：MPIJob 已经成功创建各子资源，完成初始化。
2. Running：开始执行任务。
3. ReplicaFailure：有一个或多个副本出现错误。
4. Completed：MPIJob 结束。
5. Failed：MPIJob 失败。
6. Paused：MPIJob 进入暂停模式，所有副本都已删除或正在删除。

status.phase 字段用于描述当前 MPIJob 所处的阶段，MPIJob 的整个生命周期主要有以下几个阶段：

1. Pending：MPIJob 刚刚创建，等待副本启动。
2. Running：副本创建成功，开始执行任务。
3. Paused：MPIJob 进入暂停模式。
4. Resuming：MPIJob 正从暂停模式中恢复运行。恢复运行后，切换为 Running 阶段。
5. Succeeded：MPIJob 结束。
6. Failed：MPIJob 失败。
7. Unknown：控制器无法获得 MPIJob 的阶段。

在下面的示例中，MPIJob 所有子资源创建成功，所以类型为 Initalized 的 condition 被设为 True；MPIJob 运行结束，所以类型为 Completed 的 condition 被设置为 True；但是 MPIJob 的训练结果是失败的，所以类型为 Failed 的 condition 被设置为 True。当前 MPIJob 运行阶段为 Failed。

...
status:
  conditions:
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "The job has been initialized successfully."
      reason: "-"
      type: Initializing
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      message: "All pods are running normally."
      reason: "-"
      type: Running
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "False"
      message: "All pods are running normally."
      reason: "-"
      type: ReplicaFailure
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "False"
      message: "The job exited with an error code."
      reason: "Failed"
      type: Completed
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "True"
      message: "The job exited with an error code."
      reason: "Failed"
      type: Failed
  phase: Failed

副本的状态

status.tasks 字段用来记录副本的状态，记录的内容主要包括：

• 副本的重启次数（同一种角色的副本的重启次数之和）
• 副本当前的运行阶段
• 副本在集群中对应的 Pod 的索引信息

在下面的示例中，MPIJob 创建了 1 个启动副本和 2 个执行副本。当前均处于 Running 阶段，分别运行在 mpi-example-worker-0 和 mpi-example-worker-1 这 2 个 Pod 上；启动副本当前处于 Running 阶段，运行在 mpi-example-launcher Pod 上。

...
status:
  tasks:
  - type: launcher
    restartCount: 0
    status:
    - phase: Running
      name: mpi-example-launcher
      uid: 66634db2-35e7-4641-a4dc-adbd5479734e
      containers: []
  - type: worker
    restartCount: 0
    status:
    - phase: Running
      name: mpi-example-worker-0
      uid: e3ec2ee3-6645-4e21-993f-1e472b94e0ae
      containers: []
    - phase: Running
      name: mpi-example-worker-1
      uid: 908a93f0-7b8b-491e-85d5-3da0abcb4ca4
      containers: []

副本状态统计

status.aggregate 字段统计了各个阶段的副本数量。

在下面示例中，MPIJob 创建了 3 个副本，其中 1 个处于 Pending 阶段，另外两个处于 Running 阶段。

...
status:
  aggregate:
    creating: 0
    deleted: 0
    failed: 0
    pending: 1
    running: 2
    succeeded: 0
    unknown: 0
...

下一步

• 了解如何使用 Horovod 进行 Keras 模型的数据并行训练
• 了解如何使用 Horovod 进行 PyTorch 模型的数据并行训练

BeamJob

BeamJob 用于在集群中通过 Apache Beam Python SDK 运行分布式计算任务，并提供多种底层计算引擎，目前支持 Apache Flink，未来会支持 Apache Spark。

创建 BeamJob

下面是一个基本的 BeamJob 配置示例，负责统计输入文件中的英文单词出现次数，并将结果存储在输出文件中：

apiVersion: batch.tensorstack.dev/v1beta1
kind: BeamJob
metadata:
  name: beamjob-example
spec:
  flinkClusterTemplate:
    spec:
      flinkVersion: 1.10.1
      image:
        name: t9kpublic/flink:1.10.1
      jobManager:
        accessScope: Cluster
        resources:
          limits:
            cpu: "100m"
            memory: "1Gi"
      taskManager:
        replicas: 2
        resources:
          limits:
            cpu: "100m"
            memory: "2Gi"
      flinkProperties:
        taskmanager.numberOfTaskSlots: "1"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - image: t9kpublic/apache_beam_python3.7_sdk:2.22.0
            name: submit-job
            command:
              - "python3"
            args:
              - "-m"
              - "apache_beam.examples.wordcount"
              - "--input"
              - "/mypvc/input.txt"
              - "--output"
              - "/mypvc/output.txt"
            volumeMounts:
              - mountPath: "/mypvc"
                name: mypvc
          volumes:
            - name: mypvc
              persistentVolumeClaim:
                claimName: mypvc
          restartPolicy: OnFailure

在该例中：

• 你需要准备好一个名为 mypvc 的 PVC，并将名为 input.txt 的输入文件存放在 PVC 的根路径下。
• flinkClusterTemplate 字段描述了所要创建的 Flink 集群，其中包含 1 个 Job Manager{target=_blank}，所使用的 Flink 版本为 1.10.1。
• jobTemplate 字段描述了用户如何将所要运行的任务提交给 Flink 集群，其中所使用的 Apache Beam Python SDK 版本为 2.22.0，所运行的程序为 Apache Beam Python SDK 自带的单词统计程序 apache_beam.examples.wordcount。

BeamJob 状态

BeamJob 的状态和阶段

status.conditions 字段用于描述当前 BeamJob 的状态，包括以下 2 种类型：

• ClusterRunning：Flink 集群正在运行
• JobRunning：用户提交的任务正在运行

status.phase 字段用于描述当前 BeamJob 所处的阶段，BeamJob 的整个生命周期主要有以下几个阶段：

1. Initializing：BeamJob 刚刚创建，等待 Flink 集群启动。
2. Running：Flink 集群已启动，用户提交的任务正在运行。
3. Succeeded：BeamJob 成功。
4. Failed：BeamJob 失败。
5. Unknown：控制器执行错误，导致未能获取 BeamJob 当前运行阶段。

status.jobURL 字段是 Flink 集群的 Web UI 中用户提交的此次任务对应的详细信息页面。

在下面的示例中，Flink 集群已启动，所以类型为 ClusterRunning 的 condition 被设置为 True；用户所提交的任务正在运行，所以类型为 JobRunning 的 condition 被设置为 True。当前 BeamJob 运行阶段为 Running，如需在 Flink 集群的 Web UI 中查看任务的详细信息，请跳转至 jobURL。

...
status:
  conditions:
    - lastTransitionTime: "2021-01-18T02:36:09Z"
      status: "True"
      type: ClusterRunning
    - lastTransitionTime: "2021-01-18T02:36:31Z"
      status: "True"
      type: JobRunning
  phase: Running
  jobURL: /t9k/flink-cluster/beamjob-example-flinkcluster/namespace/t9k-example/#/job/c9f62e4d61d089f351ab1f8b29e1df32/overview/

Flink 集群的状态

status.flinkClusterStatus 字段用来记录 Flink 集群的状态，包括所有 Job Manager 和 Task Manager 的运行阶段以及对应的 Pod 索引。

在下面的示例中，BeamJob 创建的 Flink 集群包括 1 个 Job Manager 和 2 个 Task Manager，均处于 Running 阶段（记录在 phase 字段中），对应的 Pod 的索引信息记录在 reference 字段中（包括 Pod 的名称和 UID）。

...
status:
  flinkClusterStatus:
    jobManagerStatus:
    - phase: Running
      reference:
        name: beamjob-example-flinkcluster-jobmanager-0
        uid: 21c67b2d-88d4-4b0a-9044-2311edee5e83
    taskManagerStatus:
    - phase: Running
      reference:
        name: beamjob-example-flinkcluster-taskmanager-0
        uid: c120c704-0730-49c8-8995-5fb719840af7
    - phase: Running
      reference:
        name: beamjob-example-flinkcluster-taskmanager-1
        uid: f1326d53-c5b6-4869-b5e9-8c35b7a7637d

用户提交任务的状态

status.jobStatus 字段用来记录用户所提交的任务的状态，包括运行阶段以及对应的 Pod 索引。

在下面的示例中，BeamJob 创建的用户任务仅包含 1 个 Pod，处于 Succeeded 阶段（记录在 phase 字段中），对应的 Pod 的索引信息记录在 reference 字段中（包括 Pod 的名称和 UID）。用户所提交的任务运行可能出现错误并多次重试，因此 status.jobStatus 字段可能包含多个 Pod。

...
status:
  jobStatus:
  - phase: Succeeded
    reference:
      name: beamjob-example-batchjob-szsn8
      uid: 9aed0159-fe2a-4096-99a7-1c89af5a6f0e

清除策略

在 BeamJob 成功或失败后，所创建的 Flink 集群仍然在运行，占据较多的计算资源。在下面的示例中，你可以在 spec.runPolicy 字段中将 cleanUpCluster 设置为 true，在 BeamJob 运行完毕（无论成功还是失败）之后删除 Flink 集群。

...
spec:
  runPolicy:
    cleanUpCluster: true
...

调度器

目前 BeamJob 支持两种调度器：

1. Kubernetes 的默认调度器
2. T9k Scheduler 调度器

调度器通过 spec.scheduler 字段设置：

• 不设置 spec.scheduler 字段，则默认使用 Kubernetes 的默认调度器。
• 设置 spec.scheduler.t9kScheduler 字段，则使用 T9k Scheduler 调度器。

在下面的示例中，BeamJob 启用 T9k Scheduler 调度器，将副本插入 default 队列中等待调度，其优先级为 50。

...
spec:
  scheduler:
    t9kScheduler:
      queue: default
      priority: 50
...

资产管理

所谓 AI 资产，指数据集和模型等人工智能相关的数据。

TensorStack AI 平台的资产管理模块（AssetHub，以下简称 AH）对模型和数据集提供完善的管理功能，包括版本管理、持续开发和协同开发等功能。

产品架构

如上图所示，AH 使用 TensorStack AI 平台自研存储系统 AIStore 存储数据，用户可以通过 AH 控制台、命令行工具和 SDK 工具与 AIStore 连接，实现 AH 的各项功能。

版本控制

AH 支持多版本模型管理，用户可以训练和提交多个临时版本模型，发布其中符合预期的模型。

多版本管理通过以下机制实现：

• Branch：分支，用户可以创建一个新分支来记录模型的临时版本；将新分支合并到主分支上，完成模型的发布。
• Commit：“交付”，相当于版本快照，便于确定版本和追溯历史。
• Tag：标签，用户可以为具有“特殊意义”的 Commit 标记标签，比如 best、v1 等。

数据集同样支持 Branch、Commit 和 Tag 的管理方式，不过数据集不会如模型那样频繁产出，所以一般建议数据集只在主分支上持续更新。

S3 接口

在训练（或部署服务）时，除了将数据集和模型下载到本地使用，大多数框架也支持直接从 S3 数据服务上动态获取数据文件。

AH 提供 S3 接口，用户可以在 AH 控制台上创建 S3 凭证，然后使用页面上生成的 S3 配置文件在训练过程中直接通过 S3 接口获取数据。

协同开发

AH 支持文件夹粒度的权限共享。用户可以将一组模型或数据集分享给其他人，实现多人共同开发和训练结果共享的目的。

可分享的权限包括查看权限或编辑权限，编辑权限包含查看权限。分享的目标可以是另一个用户、用户组或者公开给所有人。

下一步

• 了解如何使用 Asset Hub 管理 AI 资产

实验管理

TensorStack AI 平台的实验管理模块（Experiment Management，以下简称 EM）提供完善的实验数据追踪功能，能够收集实验元数据、实验中间产物，并可视化和比较实验结果，推动模型进步。

产品架构

如上图所示，EM 使用 TensorStack AI 平台自研存储系统 AIStore 存储数据，用户可以通过 EM 控制台、命令行工具和 SDK 工具与 AIStore 连接，实现 EM 的各项功能。

存储结构

EM 使用树状结构组织一个用户的实验数据，在 Web UI 中体现为目录结构。

# EM 目录结构示意图
user:demo
  ├── em-example/
  │   ├── mnist_dataset
  │   └── mnist_keras
  └── autotune/
      └── keras-tune

节点类型

EM 树状结构中，节点根据存储方式分为四类，用 StorageType 表示：

• StorageType == 0：不存储数据文件，仅用于组织 EM 树状结构。EM 中文件夹即该类型节点。
• StorageType == 1：存储一个文件数据。
• StorageType == 2：存储一组数据文件。
• StorageType == 3：该类型节点可以创建和管理多个版本，每一个版本中可以存储一组数据文件。

在这四种存储类型的基础上，EM 根据用途实现以下 7 个节点类型：

• Folder：Storage Type == 0，文件夹结构，用来组织实验数据。
• Shotrcut：Storage Type == 0，快捷方式，指向另一个节点。
• Run：Storage Type == 2，记录实验元数据，包括实验基本信息、实验参数和实验指标。
• Artifact：Storage Type == 2，记录实验的中间产物，也包括未发布的数据集和模型。
• AutoTune：Storage Type == 2，记录超参数调优实验数据，参考超参数调优实验。
• Model：Storage Type == 3，记录机器学习模型。
• Dataset：Storage Type == 3，记录机器学习所使用的数据集。

Artifact 没有特定的文件组织结构，用户可根据需要组织上传。

Model 和 Dataset 由 TensorStack 平台的资产管理模块，具体请参考 EM 和 AssetHub 之间的关系 。

Run 和 Autotune 是实验元数据的存储节点，具有特定的文件组织结构，EM Web 根据这些特定的文件组织结构进行实验数据的可视化。

Run 节点

Run 记录实验元数据，包括实验基本信息、实验参数和实验指标。

Run 节点中包含一个 index.yaml 文件，其中记录其他实验数据在该节点中的相对路径：

hyperparameters: hyperparameters.yaml
metrics:
  train: metrics/train.yaml
  val: metrics/val.yaml
  test: metrics/test.yaml
platform: platform.yaml
git: git.yaml
log: stdout.log

• hypterparameters：机器学习超参数。
• metrics：训练指标，由于指标可能产生自不同阶段，同一阶段也可能有多种指标，所以使用上例中的结构记录多个指标文件。
• platform：平台信息，包括系统版本、python 包版本等。
• git：代码存储位置，我们一半会将机器学习脚本存储在 GitHub 中。
• log：日志文件。

上述文件的生成可以由 em 工具自动完成，用户只需要了解如何使用 em 工具。参考 em API 文档。

AutoTune 节点

AutoTune 记录超参数调优实验数据，包括实验的基本配置以及每一次训练的参数和指标。

AutoTune 节点的文件结构如下：

.
├── profile.json
├── 17671/
│   ├── metadata.json
│   └── metrics.yaml
...

• profile.json：记录超参数调优实验的训练配置、超参数搜索空间和调优配置等信息
• 17671：超参数调优过程中，每一次训练都会创建一个文件夹用来记录训练数据，文件夹名称即训练的 ID（随机生成）。
  • metadata.json：记录训练参数和训练状态。
  • metrics.yaml：记录训练指标，超参数调优创建的训练都只会产生一个指标，调优控制器会根据该指标调整超参数。

可视化

EM 支持使用以下方式对 Run 数据进行可视化：

• 数据流图：Run 和 Artifact 之间是存在使用和产出关系的，比如一次实验（Run）使用一个 Artifact 作为训练数据，最后产出另一个 Artifact。这种使用和产出关系构成了一个数据流动路线图，即数据流图。用户可以通过数据流图快速跳转到对应数据节点。

• 指标折线图

EM 支持使用以下方式对 AutoTune 数据进行可视化：

• “超参数-指标”图

• 指标优化曲线

• 各次训练的指标信息

权限管理

EM 支持节点粒度的权限控制：

• 用户可以将一个节点分享给另一个用户、用户组或者公开给所有人。
• 可分享的权限包括查看权限或编辑权限，编辑权限包含查看权限。
• 文件夹权限修改会传递给所有子节点（当用户被分享了一个文件夹的编辑权限，则该用户自动拥有文件夹中所有节点的编辑权限；取消分享同理）。
• 当一个节点被移动到另一个文件夹中，节点完全继承该文件夹的权限，覆盖节点之前的权限设置。

EM 和 AssetHub 之间的关系

AssetHub 是 TensorStack AI 平台的资产管理模块，用于管理数据集和模型。

数据集和模型作为实验的输入和输出，也应当作为实验管理的一部分，所以在 EM 中也可以看到 AssetHub 中的数据集和模型数据，如下图所示：

# EM 目录结构示意图
user:demo
  └── t9k-assethub/
      ├── model/
      │   ├── folder1
      │   │   ├── model1
      │   │   ...
      │   ├── folder2
      │   ...
      └── dataset/

数据集和模型分别记录在 EM 的 ./t9k-assethub/dataset 和 ./t9k-assethub/model 文件夹中，model 文件夹（dataset 文件夹同样）维护文件夹和模型两级结构，每一个模型都是一个具有版本管理功能的节点。

下一步

• 了解如何使用 EM 追踪模型训练

账户和安全

TensorStack AI 平台提供全面、系统性的安全支持，以保障平台本身、平台提供的各种工具（例如模型构建控制台）和用户的各种工作负载（例如训练任务）的安全。

账户

账户是用户在 TensorStack AI 平台身份和权限的代表。

在使用 TensorStack AI 平台前，用户需要先联系集群管理员为其创建一个平台账户。

API Key

在使用浏览器场景下（例如使用模型构建控制台），用户能够直接、同步地参与到身份认证和授权流程。用户可以方便地通过交互式的方式提供安全凭证（用户名 + 密码）来完成认证和授权，并随后通过 Cookie + Access Token 建立安全的交互过程。

但是，还有其他环境或者场景不适合采用前述方式。例如，用户通过命令行（环境受限，无法使用浏览器）或者在自动化脚本中向服务器发送请求，此时要求“用户同步进行交互”来获得访问令牌是非常不便捷的；或者，在此过程中需要通过客户程序输入密码，可能造成密码泄漏。同时，有些场景下，我们希望能够只授予客户端部分权限，但直接使用前述 access token 或者 Cookie 并不能更进一步缩小权限。

API Key 是 TensorStack AI 平台应对上述问题的解决方案。它是一种可撤销的、异步的、持久的安全授权方式，具有以下特点：

• 可以长期持有（适合在脚本中使用）
• 不会泄漏账户信息（无需使用用户名和密码）
• 可以选择性地包含账户的部分权限
• 方便在脚本程序、命令行工具等“非交互场景”进行集成使用
• 可以随时方便地取消该授权

下一步

• 了解如何为账户生成 API Key
• 了解在不同场景使用 API Key

项目

项目（Project）是 TensorStack AI 平台为了有效使用集群资源，实现多用户、多项目同时、安全、共享使用集群而提供的机制；它是一个 CRD。

它具有以下特征：

• 每个项目有一个项目管理员，他可以管理项目的成员。
• 只有项目的管理员和成员可以在项目中执行操作。
• 每个项目对应一个同名的 Kubernetes 命名空间（Namespace），项目的成员拥有当前命名空间中几乎所有 K8s 资源的操作权限。

项目定义

以下是一个项目的定义（Custom Resource）示例：

apiVersion: tensorstack.dev/v1beta1
kind: Project
metadata:
spec:
  networkPolicy:
    template:
      spec:
        egress:
          - to:
              - namespaceSelector:
                  matchLabels:
                    kubernetes.io/metadata.name: t9k-system
                podSelector:
                  matchLabels:
                    app: security-console-server
        ingress:
          - from:
              - namespaceSelector:
                  matchLabels:
                    kubernetes.io/metadata.name: t9k-system
        policyTypes:
          - Ingress
          - Egress
    useDefaultTemplate: false
  quotaProfile: demo
  resourceQuota:
    template:
      spec:
        hard:
          cpu: '200'
          memory: 1280Gi
          nvidia.com/gpu: '18'
          persistentvolumeclaims: 200Gi
          pods: 1k

注：普通用户（包括项目管理员）不可修改上述项目配置，这里仅用该配置进行演示和讲解。

在上述示例中：

• 该项目中设置以下网络策略：
  • 该项目中的工作负载可以访问 t9k-system 命名空间中的 security-console-server 服务（由字段 spec.networkPolicy.template.spec.egress 字段指定）。
  • 该项目中的服务可以被 t9k-system 命名空间的任一工作负载访问（由字段 spec.networkPolicy.template.spec.ingress 字段指定）。
• 该项目使用 demo 资源配额模版。

资源配额与配额模版

一个项目的资源配额（由 spec.resourceQuota 字段指定）表示：当前项目中所能使用的资源上限，包括但不限于 CPU、内存、GPU 和 Pod 数量。

值得说明的一点：项目的资源配额中关于 CPU、内存、GPU、Pod 等资源数量的限制都直接作用于 Pod。即如果你创建一个 T9k Job，它即将创建的 pod 需要申请超过项目资源配额的资源数量，则 T9k Job 会被成功创建，但是 T9k Job 创建 Pod 的请求会被拒绝。

管理员可以使用配额模版批量设置或修改项目的资源配额。项目控制器会自动查找配额模版（由 spec.quotaProfile 字段指定）的内容，据此同步项目的资源配额。

网络策略

管理员可以通过项目的网络策略（由字段 spec.networkPolicy 字段指定）实现以下功能：

1. 禁止普通用户访问系统级应用，避免保密信息泄漏和系统遭到恶意攻击。
2. 阻断项目间通信，避免项目之间的互相干扰。
3. 限定项目的访客 IP，构建安全的项目环境。

项目授权

项目授权信息存储在特定的授权服务器而非项目定义中。

普通用户（包括项目管理员）可以在安全控制台（Security Console）查看自己所在和所管理的项目以及项目的成员。

项目管理员可以通过安全控制台编辑项目成员。

项目的使用范围

项目可以被应用到 TensorStack AI 平台的模型构建、模型部署和工作流三个模块，集群管理员可以设置一个项目的使用范围。

目前项目可选的使用范围包括：

• build：用户可以在模型构建和工作流模块中使用此项目。
• deploy：用户可以在模型部署模块中使用此项目。

一个项目可以同时设置上述两个使用范围。

项目成员管理

项目管理员可以在安全控制台设置项目成员：

• 项目成员可以是用户或用户组，一个用户组被设置为项目成员表示该组中的所有用户都可以使用该项目。
• 设置项目成员时，可以对每一个成员单独设置项目的使用范围，对成员设置的项目使用范围应为项目所有使用范围的子集。

下一步

• 了解项目管理员如何：添加 Project 成员

计算资源

用户在向集群提交计算任务，使用计算资源时，需要遵循管理员设置的各种策略。

• 资源配额：用户提交的工作负载需要满足集群的配额策略；
• 使用 t9k-scheduler：可能需要通过特定的 scheduler 才能使用特定的资源。

资源配额

管理员可在 Project 和 Queue 分别设置资源（CPU、Memory、GPU、Storage 等）配额。

• 针对 Project 的配额限制单个 Project 里的各种计算资源使用上限；
• 设置在 Queue 上的配额则允许管理员设置特定容量的资源池供用户使用。

t9k-scheduler

t9k-scheduler 调度器专为大规模分布式并行计算及异构资源集群设计，可以更加有效地管理 AI 集群的计算资源和计算任务。相比于 K8s 的默认调度器 kube-scheduler，t9k-scheduler 在对 AI 计算场景的支持方面进行了增强，并增加了额外的机制以对集群进行更加精细化管理。

适用场景

为并行计算性质的工作负载分配资源，当用户需要部署多个 Pod 协同工作以运行任务时，推荐使用 t9k-scheduler。

Queue & PodGroup

t9k-scheduler 有两个重要的机制：

• Queue：t9k-scheduler 提供 queue 让用户工作负载申请集群资源，每一个使用 t9k-scheduler 的 Pod 都可指定一个 queue 为其分配资源。队列的创建/修改由集群管理员负责。
• PodGroup：PodGroup 是支持 coscheduling 机制重要组成部分。它代表一组 Pod，并定义了这组 Pod 在资源方面的限制条件。当限制条件被满足时，PodGroup 中的 Pod 才会被分配计算资源。

使用

当用户创建 Pod 使用 t9k-scheduler 时，需要进行下列操作：

1. 将 Pod 使用的调度器名称设置为 t9k-scheduler；
2. 设置 Pod 所属的队列。

当用户创建一组 Pod 协同完成一项任务，并使用 t9k-scheduler，需要进行下列操作 （用户一般通过使用 T9k-Job 自动化地使用 PodGroup）：

1. 创建一个 PodGroup，并在 PodGroup 中设置所属的队列；
2. 将 Pod 使用的调度器名称设置为 t9k-scheduler；
3. 设置 Pod 属于步骤一创建的 PodGroup。

下一步

• 了解资源配额
• 了解队列
• 了解 PodGroup
• 了解动化的资源回收机制
• 学习使用队列
• 学习使用 PodGroup

使用 GPU

用户提交的工作负载，如果需要使用 GPU，需要在工作负载的计算资源配置中指定 GPU 扩展资源。

GPU 使用模式

独占使用

独占模式是指在特定时间段，GPU 卡分配给单一工作负载单独使用。

适用场景：GPU 被满负荷使用，并且计算需要尽快完成。例如 AI 模型的训练。

共享使用

共享模式是指单个物理 GPU 可以同时被多个工作负载使用。

适用场景：对于有些计算，例如交互式的 Notebook，小规模或者低使用量的模型推理服务，经常只需要使用 GPU 的部分计算能力。在这些情况下，让多个计算任务共享使用 GPU，将能极大地提高 GPU 的利用率，进而获得有益的投资回报率。

共享 NVIDIA GPU

以 NVIDIA GPU 为例，下面是 NVIDIA 提供的多种 GPU 共享和并发使用的机制，以支持不同的场景。

MPS

CUDA MPS（多进程服务 / Multi-Process Service）是 CUDA API 的客户端-服务器架构的实现，用于提供同一 GPU 同时给多个进程使用。MPS 是一个 “AI 史前”（深度学习尚未在 GPU 上运行）的方案，是 NVIDIA 为了解决在科学计算领域单个 MPI 进程无法有效利用 GPU 的计算能力而推出的技术。

与时间切片（Time Slicing）相比，MPS 通过在多个客户端之间共享一个 CUDA Context 消除了多个 CUDA 应用之间上下文切换的开销，从而带来更好的计算性能。 此外，MPS 为每个 CUDA 程序提供了单独的内存地址空间，因而可以实现对单个 CUDA 程序实施内存大小使用限制，克服了 Time Slicing 机制在这方面的不足。

优点：

• 可以控制单个应用的内存大小使用限制；
• 由于消除了多个 CUDA 应用之间 context swtich 的代价，具有更好的性能；
• 是一个 CUDA 层面的方案，不依赖于 GPU 的特定架构，支持较早的 GPU 硬件。

缺点：

• CUDA 应用之间隔离不足：单个应用的错误可以导致整个 GPU 重置（reset）；
• NVIDIA 还未（截止2024/01）正式在 K8s 环境下提供支持。

Time Slicing

时间切片（Time Slicing） 也称为时间共享（Temporal Sharing）是指把多个 CUDA 程序分配到同一个 GPU 上运行，即一个简单的超额订阅（oversubscription）策略。NVIDIA 在 Pascal 架构（GP100，2016 年首发）之上提供了对此技术的支持。这些 GPU 卡上的调度器提供了指令粒度（不再需要等待 CUDA kernel 执行完成）的计算抢占（Compute Premption）技术。当抢占发生时， 当前 CUDA 程序的执行上下文（execution context：寄存器、共享内存等）被交换（swapped）到 GPU DRAM，以便另一个 CUDA 程序运行。

优点：

• 非常容易设置；
• 对分区数量无限制；
• 可在众多 GPU 架构上部署。

缺点：

• 上下文切换引起的效率降低；
• 共享 GPU 设备导致的的隔离不足、潜在的 GPU OOM 等；
• 时间片周期恒定，且无法为每个工作负载设置可用资源的优先级或大小。

MIG

MIG 可以把一个 GPU 划分为最多 7 个独立的 GPU 实例，从而为多个 CUDA 程序提供专用的 GPU 资源，包括流式多处理器 (Streaming Multiprocessors) 和 GPU 引擎。这些 MIG 实例可以为不同的 GPU 客户端（例如进程、容器或 VM）提供更加高级的故障隔离能力和 QoS。

优点：

• 硬件隔离，并发进程安全运行且互不影响；
• 在分区级别提供监控和遥测（monitoring & telemetry）数据；
• 每个分区可以叠加使用其他共享技术，例如 vGPU，time-slicing, MPS。

缺点：

• 仅在最新的 GPU 架构（Ampere, Hopper）上提供；
• 重新配置分区布局需在 GPU 空闲（驱逐所有正在运行的进程）时；
• 一些分区配置会导致部分 SM / DRAM 无法被利用。

vGPU

NVIDIA vGPU 是 NVIDIA 在数据中心提供的 GPU 虚拟化技术，它对具有完整输入输出内存管理单元 (IOMMU) 保护的 VM 提供支持，使得这些 VM 能够同时、直接地访问单个物理 GPU。

除了安全性之外，NVIDIA vGPU 还有其他优势，例如：

• 支持实时虚拟机迁移（live VM migration）；
• 可设置不同的调度策略，包括 best-effort、equal-share 和 fixed-sharez：
  • 当使用 fixed-share 调度器时可提供可预知的性能；
• 运行混合的 VDI (Virtual Desktop Infrastructure) 和计算工作负载的能力；
• 与业界广泛使用的虚拟机管理程序（hypervisor，如 vmware）的集成能力。

缺点:

• 部署 vGPU 需要额外的软件授权费用；
• 分区仍然通过时间片（time-slicing）完成。

扩展资源名称

如果用户想知道用户所使用的集群有哪些代表 GPU 的扩展资源名称，请咨询集群管理员。下面列举了一些常见的代表 GPU 的扩展资源。

NVIDIA GPU

当集群安装有 NVIDIA GPU 硬件资源时，通常有下列扩展资源名称：

• nvidia.com/gpu：一个扩展资源对应一个 NVIDIA GPU 硬件资源。可以申请使用多个 GPU 资源。例如当声明资源 nvidia.com/gpu: 8 时，会有 8 个 NVIDIA GPU 分配给这个工作负载使用。
• nvidia.com/gpu.shared：通过这个扩展资源，多个工作负载可以共享使用一个 NVIDIA GPU。需要注意，当共享机制是通过 time slicing 实现时，用户为工作负载设置 nvidia.com/gpu.shared 扩展资源的数量不能超过 1（参考）。

NVIDIA 还有其他形式的设备名称，例如，当部署了 MIG 技术时，常见的资源名称有：

• nvidia.com/mig-3g.20gb：一个扩展资源对应的计算能力是物理 GPU 的 3/7，显存大小是 20GB。
• nvidia.com/mig-2g.10gb：一个扩展资源对应的计算能力是物理 GPU 的 2/7，显存大小是 10GB。
• nvidia.com/mig-1g.5gb：一个扩展资源对应的计算能力是物理 GPU 的 1/7，显存大小是 5GB。

AMD GPU

当集群安装有 AMD GPU 硬件资源时，通常有下列扩展资源名称：

• amd.com/gpu：一个扩展资源对应一个 AMD GPU 硬件资源。同样的，可申请多个 GPU，例如 amd.com/gpu: 2 。

其他

请参考对应厂商的 device plugin 文档。

GPU 使用示例

独占 GPU

集群中部署了 NVIDIA GPU 后，一般配置扩展资源 nvidia.com/gpu 支持独占使用 GPU。

下面是一个使用 GPU 的 PytorchTrainingJob YAML 示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
 name: pytorch-example
spec:
 replicaSpecs:
 - replicas: 4
   restartPolicy: OnFailure
   template:
     spec:
       containers:
       - command:
         - python
         - dist_mnist.py
         image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel
         name: pytorch
         resources:
           limits:
             nvidia.com/gpu: 4
           requests:
             cpu: 10
             memory: 5Gi
   type: worker

在该例中，spec.replicaSpecs[0].template.spec.containers[0].resources.limits 字段设置了资源量 nvidia.com/gpu: 4，表明一个 replica 会独占使用 4 个 NVIDIA GPU。由于设置了 PyTorchTraiiningJob 的 replica 数量为 4，所以 PyTorchTraiiningJob 总共会占用 16 个 NVIDIA GPU。

共享 GPU

扩展资源 nvidia.com/gpu.shared 代表共享 GPU。

下面是一个以共享方式使用 GPU 的 Notebook YAML 示例：

apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
  name: tutorial
spec:
  type: jupyter
  template:
    spec:
      containers:
        - name: notebook
          image: t9kpublic/torch-2.1.0-notebook:1.77.1
          volumeMounts:
            - name: workingdir
              mountPath: /t9k/mnt
          resources:
            requests:
              cpu: '8'
              memory: 16Gi
              nvidia.com/gpu.shared: 1
            limits:
              cpu: '16'
              memory: 32Gi
              nvidia.com/gpu.shared: 1
      volumes:
        - name: workingdir
          persistentVolumeClaim:
            claimName: tutorial

在该例中：spec.template.spec.containers[0].resources.limits 字段定义了资源量 nvidia.com/gpu.shared: 1 ，表明这个 Notebook 以共享方式使用一个 NVIDIA GPU。

指定 GPU 型号

不同节点上安装的 GPU 型号经常是不同的，同一厂家的 GPU 对应的扩展资源名称常常是相同的，例如：对于 NVIDIA GPU，在不考虑共享 GPU 的情况下，A100 和 A40 型号对应的扩展资源名称都是 nvidia.com/gpu。

调度器为工作负载分配资源时忽略型号信息，如果用户想让工作负载使用特定型号的 GPU，例如：NVIDIA A100-80GB、NVIDIA A40，用户可以参考下列方式配置工作负载，使其能被分配到安装有特定型号 GPU 的节点上。

设置 nodeSelector

安装有 GPU 硬件的节点会通过节点标签来表明节点上安装的 GPU 型号。用户在创建工作负载时，可以为其设置 nodeSelector。 nodeSelector 的作用是通过节点标签来筛选节点，从而工作负载会被分配到期望的节点上。

如果用户将工作负载的 nodeSelector 设置为指定型号 GPU 对应的节点标签，并且为工作负载设置了代表 GPU 的扩展资源数量，那么工作负载就可以使用指定型号的 GPU。

常见的节点标签

如果用户想知道用户所使用的集群有哪些表明 GPU 型号的节点标签，请咨询管理员。

下面是一些表明 GPU 型号的节点标签示例：

常见工作负载的 nodeSelector 字段

下面列举了常见的工作负载，以及工作负载用于设置 nodeSelector 的字段：

示例

下面是一个设置了 nodeSelector 的 notebook 示例：

apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
 name: tutorial-nodeselector
spec:
 type: jupyter
 template:
   spec:
     containers:
       - name: notebook
         image: t9kpublic/torch-2.1.0-notebook:1.77.1
         volumeMounts:
           - name: workingdir
             mountPath: /t9k/mnt
         resources:
           limits:
             cpu: '16'
             memory: 32Gi
             nvidia.com/gpu: 1
     nodeSelector:
       nvidia.com/gpu.product: NVIDIA-A100-PCIE-40GB
     volumes:
       - name: workingdir
         persistentVolumeClaim:
           claimName: tutorial

在该例中： Notebook 的资源量设置了 nvidia.com/gpu: 1，表明 Notebook 要使用一个 GPU。 Notebook 的 nodeSelector 被设置为 nvidia.com/gpu.product: NVIDIA-A100-PCIE-40GB，所以 Notebook 的 Pod 会被分配到含有标签 nvidia.com/gpu.product: NVIDIA-A100-PCIE-40GB 的节点上运行。 从而 Notebook 会被分配一个 NVIDIA GPU A100-40GB。

设置队列

通过 nodeSelector 机制选择特定型号的 GPU 过程繁琐，而且管理员也缺乏对 GPU 使用权限的方便控制。TensorStack 提供了更加便捷的队列机制方便用户使用特定类型的资源。

当满足下列两个要求时，用户可以通过设置队列的方法来使用特定型号的 GPU：

1. 管理员为集群提供了恰当的配置。例如，设置了队列 A100 以选择安装有 A100 GPU 的计算节点；
2. 用户有权限使用这个队列。

用户在创建工作负载时，可以进行下列操作，选择特定型号的 GPU：

• 使用 t9k-scheduler ；
• 设置合适队列名称，例如 A100；
• 设置使用 GPU 扩展资源，例如 nvidia.com/gpu。

示例

假设管理员在集群中配置了两个队列，名称分别是：

• a100：队列可以使用的节点上都安装有 GPU NVIDIA A100-80GB
• a40：队列可以使用的节点上都安装有 GPU NVIDIA A40-40GB

并且，用户有权限使用这两个队列。

如果用户想创建一个使用 NVIDIA A100-80GB 的 Notebook，用户可以创建下列 Notebook:

apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
 name: tutorial
spec:
 type: jupyter
 scheduler:
   t9kScheduler:
     queue: a100
 template:
   spec:
     containers:
       - name: notebook
         image: t9kpublic/torch-2.1.0-notebook:1.77.1
         volumeMounts:
           - name: workingdir
             mountPath: /t9k/mnt
         resources:
           limits:
             cpu: '16'
             memory: 32Gi
             nvidia.com/gpu: 1
     volumes:
       - name: workingdir
         persistentVolumeClaim:
           claimName: tutorial

在该例中：

• Notebook 的资源量设置了 nvidia.com/gpu: 1，表明 Notebook 要使用一个 GPU。
• 字段 spec.scheduler.t9kScheduler.queue 被设置为 a100，表明 Notebook 使用 T9k Scheduler 进行资源调度，并且使用队列 a100。

用户通过队列的方式使用更加简洁、方便。同时，集群管理员可使用权限等机制，更加方便地实施集群资源管理策略。

参考

K8s Extended resources
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#extended-resources

Consuming extended resources
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#consuming-extended-resources

Schedule GPUs | Kubernetes
https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/

Device Plugins
https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/

Assigning Pods to Nodes
https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/

Improving GPU Utilization in Kubernetes
https://developer.nvidia.com/blog/improving-gpu-utilization-in-kubernetes

MIG：NVIDIA Multi-Instance GPU User Guide
https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest/gpu-operator-mig.html#configuring-mig-profiles

资源配额

为保证集群资源的合理分配和使用，管理员会在以下两个方面限制普通用户的资源使用（CPU、内存、GPU、Storage 等）：

1. 项目配额：限制用户在一个 Project（项目）中可以使用的资源总量。
2. 队列配额：限制一个 Queue（队列中）的工作负载可以使用的资源总量。

用户创建的工作负载（如 T9k Job）不能超过上述两种配额的限制，否则工作负载将被拒绝接受。

具体请参考 “项目资源配额” 和 “队列资源配额”。

队列

概述

队列（Queue）是 T9k-Scheduler 提供的集群资源管理机制。

如果使用了 T9k-Scheduler，用户创建工作负载时，则可以选择使用一个特定的 Queue 申请集群资源。

队列设置

管理员创建在集群中创建多个 Queue ，并可设置：

• Queue 的使用权限，以规定那些人员/组/项目可使用此 queue;
• Queue 对应的计算节点集合，以方便地管理计算节点的使用；
• 资源配额，限制通过此 Queue 使用的资源上限。

使用权限

Queue 的使用权限用于控制哪些用户、组、项目可以使用这个队列。队列的使用权限通过两种方式进行设置：

• 管理员直接设置有权使用队列的用户/用户组。
• 管理员设置队列的 spec.namespaceSelector（类型是 labelSelector）字段。

当项目满足下列任一条件时，用户有权在项目下创建使用某个队列的工作负载：

• 队列设置了 spec.namespaceSelector，并且项目对应的 namespace 的标签符合这个 namespaceSelector。
• 项目的用户有权使用这个队列。

节点限制

队列的节点限制用于指定队列可用的集群工作节点（worker node），T9k-Scheduler 只会将队列内的工作负载分配到这些特定的节点上。

队列的 spec.nodeSelector （类型是 labelSelector）字段用于设置队列的节点权限：

• 字段未设置时，队列可以使用集群内所有的节点
• 字段设置后，队列可以使用节点标签满足 nodeSelector 的节点。

在下面的节点权限示例中：说明队列可以使用节点标签包含 topology.kubernetes.io/zone: peking 或 topology.kubernetes.io/zone: tianjin 的节点。

spec:
  nodeSelector:
    matchExpressions:
    - key: topology.kubernetes.io/zone
      operator: In
      values:
      - peking
      - tianjin

资源配额

队列的资源配额用于限制队列可以使用的资源上限，如果用户创建的工作负载（例如 Job，Pod 等）会导致队列超出资源配额限制，那么系统会拒绝接受此工作负载。

队列的 spec.quota 字段定义队列的资源配额，队列的 status.allocated 字段表明队列已经使用的资源量。

在下面的示例中：

• 工作负载的 CPU 资源请求量（requests）总和不能超过 40；
• Queue 已经被分配了 38 个 CPU。

spec:
  quota:
    requests:
      cpu: 40
status:
  allocated:
    cpu: "38"

优先级

spec.priority 字段定义队列的优先级，值类型是 int，范围是 [0,100]，数值越大代表队列的优先级越高。队列的优先级会影响下列事件：

• 优先级较高的队列会被优先分配资源。
• 如果 T9k-Scheduler 开启了资源抢占行为，优先级较高的队列有权抢占低优先级队列使用的资源。

是否可被抢占资源

spec.preemptible 字段定义队列是否可以被其他队列抢占资源，字段值类型是 bool：

• false ，队列无法被抢占资源；
• true ，队列可以被抢占资源。

开启/关闭

spec.closed 字段定义队列是否处于关闭状态，当队列被关闭了，用户无法创建使用该队列的工作负载。字段值类型是 bool：

• 字段未设置或被设置为 false 时，队列处于开启状态；
• 字段被设置为 true 时，队列处于关闭状态。

最大运行时长

最大运行时长会限制队列中 Pod 的运行时长，如果 Pod 的存在时长（存在时长=当前时间 - Pod 创建时间）超过最大运行时长，Pod 会被删除。

队列的 spec.maxDuration 字段设置了队列的最大运行时长：

• 值类型是 string，并且需要满足正则表达式 ^(0|(([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?)$。
• 支持的时间单位：y, w（周）, d, h, m, s, ms。
• 示例：“3w”, “2h45m”。
• 未设置时，队列不受最大运行时长约束。

资源尺寸

资源尺寸（resource shape）会限制队列中工作负载请求资源量的上限，当用户创建超过资源尺寸的工作负载时，工作负载会被系统拒绝。

队列的 spec.resourceShapeProfile 字段设置了队列使用的资源尺寸模版，模型对应的资源尺寸详情存储在 ConfigMap t9k-system/resource-shapes 中。用户可以通过 T9k 产品前端查看队列的资源尺寸设置。

下一步

• 了解如何使用队列
• 队列 API Reference

PodGroup

概述

PodGroup 关联一组协同工作的 Pod，它们共同完成一项计算任务（例如分布式并行模型训练），因此需要作为一个整体来分配资源。通常情况下，用户可以通过创建 T9k Job 类的工作负载来间接使用 PodGroup，而不需要直接创建 PodGroup。

PodGroup 是 T9k 支持 coscheduling 机制的关键组成部分，可以为并行计算提供更好的支持，包括避免死锁场景和提高资源利用率。

规范

下面是一个基本的 PodGroup 示例：

apiVersion: scheduler.tensorstack.dev/v1beta1
kind: PodGroup
metadata:
  name: chorus
  namespace: default
spec:
  minMember: 3
  priority: 50
  queue: default

在该例中：

• 最少运行数量是 3 个成员 Pod（由 spec.minMember 字段指定）。
• PodGroup 的优先级是 50（由 spec.priority 字段指定）。
• PodGroup 使用 default 队列（由 spec.queue 字段指定）申请资源。

队列

spec.queue 设置 PodGroup 欲使用的资源队列，默认值是 default。

优先级

spec.priority 字段设置 PodGroup 的优先级 ，值类型是 int，范围是 [0,100]，默认值是 0，数值越大表明优先级越高。在同一个队列中，优先级高的 PodGroup 会被优先分配资源。

最少成员限制

成员数量限制包括两部分，必须同时满足，调度器才会为 PodGroup 分配资源：

• 最少数量（minMember）；
• 角色最少数量（role minMember），但非必须字段。当未填写时，则自动满足。

最少数量

spec.minMember 设置 PodGroup 的最小运行数量，表明 PodGroup 的 Pod 数量（不包括失败的 Pod）达到最小运行数量时，调度器才会为 PodGroup 分配资源。

本文开头的示例中设置的最小运行数量是 3，但未设置角色最少数量。

角色最少数量

基于角色（role）的最小运行数量通过字段 spec.roles 的子字段设置。

• spec.roles 是一个记录角色名称和该角色的最小运行数量的数组；
• PodGroup 的 Pod 通过标签来指定自己的角色。

下面是一个示例：

spec:
  roles:
  - name: master
    minMember: 1
  - name: worker
    minMember: 3

在该示例中，PodGroup 包含两类角色 master 和 worker。当可运行的 master Pod 数量达到 1，worker Pod 数量达到 3 时，调度器才会为 PodGroup 分配资源。

状态

PodGroup 的状态记录在 status 字段中。

status.conditions 字段记录了当前 PodGroup 的状态，包括下列 2 种类型：

• GroupScheduled: PodGroup 是否已经被分配过资源
• SufficientGroupMember: PodGroup 的 Pod 数量是否满足最小运行需求

status.allocated 字段记录了当前 PodGroup 使用的资源量。

PodGroup 的 Pod 的数量：

• status.pending：处于 Pending phase 的 Pod 数量
• status.running：处于 Running phase 的 Pod 数量
• status.succeeded：处于 Succeeded phase 的 Pod 数量
• status.failed：处于 Failed phase 的 Pod 数量
• status.unknown：处于 Unknown phase 的 Pod 数量

示例

下面的 YAML 片段展示了一个正常运行中的 PodGroup 的 status 字段：

• allocated：podgroup 被分配的资源总和；
• running: 3 个 pod 处于 running 状态；
• condition SufficientGroupMember 为 True，表示 PodGroup 满足最小成员约束，可以被分配资源；
• condition GroupScheduled 为 True，表示整个 PodGroup 已经被分配资源；

status:
  allocated:
    cpu: 3
    memory: 600M
  conditions:
  - lastTransitionTime: "2023--17T13:54:02Z"
    reason: SufficientMemberPods
    status: "True"
    transitionID: 82ce5bf5-313d-4294-b44b-9b44ffd52213
    type: SufficientGroupMember
  - lastTransitionTime: "2023-12-17T13:48:16Z"
    message: Resources have been allocated to PodGroup
    reason: PodGroupScheduled
    status: "True"
    transitionID: c5a70cac-769c-44c4-a6ba-f4b1227cb135
    type: GroupScheduled
  running: 3

下一步

• 了解如何使用 PodGroup
• PodGroup API Reference

资源回收

一些交互式工作负载（例如 Notebook、TensorBoard 和 Explorer）的计算资源经常被闲置。例如在非工作时间，用户创建的 Notebook 服务虽然没有用户使用，但仍占用大量集群计算资源，造成资源浪费。

为充分利用集群资源，TensorStack AI 平台提供资源回收机制，自动检测并暂停空闲的 Notebook、TensorBoard 和 Explorer 等服务，释放占用的资源。

原理

以 Notebook 为例，介绍资源回收的原理（TensorBoard、 Explorer 或者其他工作负载同理）。

如上图所示：

1. 集群管理员设置 “资源回收配置” 策略；
2. 根据配置，Resource Keeper 监听启用回收功能的项目（Project 2）中的 Notebook 状态；
3. 当 Notebook 空闲时间达到配置中规定的阈值，则 Resource Keeper 对该资源实施暂停操作，以释放资源。

状态检测

很多在 TensorStack AI 平台上运行的服务，使用 PEP Proxy 来处理身份验证和授权。由于其 proxy 所有客户端请求，这个 PEP Proxy 也可以作为检查服务是否空闲的信息来源。

对于 TensorBoard 和 Explorer，对应控制器会向 PEP Proxy 发送请求，检查其上一次请求的时间，如果给定时间内（比如 1 小时，由集群管理员配置）没有再次请求，则控制器判定其为空闲状态。

Jupyter Notebook 本身的 server 就提供了状态查询功能。因此，对于 Notebook 类型的工作负载，Notebook 的控制器会先尝试向 Notebook server 发送请求检查空闲状态。如果处于空闲或请求失败（可能 Notebook 使用的不是 Jupyter 内核，主要发生在自定义 Notebook 上），则继续向 PEP Proxy 发送请求，查询 PEP Proxy 观测到的服务使用情况：例如，如果 1 小时内（由管理员配置）没有请求，则控制器判定其为空闲状态。

对于 RStudio Notebook，目前没有空闲状态的判定，控制器将其视为永远处于活跃状态。

资源使用监控

在 Tensorstack AI 平台创建工作负载后，用户可以通过控制台或命令行工具查看工作负载的资源使用情况。

控制台

用户可以在下列控制台的工作负载的详情页面查看资源监测图表：

• 模型构建（Build Console）：
  • Notebook
  • T9k Job
  • Tensorboard
  • Pod
• 模型部署（Deploy Console）：
  • MLService

当用户定义工作负载时可以选择性地为每个容器设定所需要的资源数量，最常见的可设定资源是 CPU、内存和扩展资源。

以 PyTorchTrainingJob 为例，用户可以查看下面几类资源的使用情况。

CPU / Memory / 扩展资源

CPU（内存）的资源监测图如下所示，图中包含三条折线：

• 请求量：工作负载声明的 resources.requests.cpu（resources.requests.memory）
• 上限：工作负载声明的 resources.limits.cpu（resources.limits.memory）
• 使用量：工作负载实际使用的 CPU（内存）资源量

当工作负载声明扩展资源时，显示扩展资源的资源监测图。

在本例中，PytorchTrainingJob 声明了扩展资源 nvidia.com/gpu: 2，页面显示了工作负载声明的 resources.limits."nvidia.com/gpu" 资源量。

NVIDIA GPU

当工作负载声明的扩展资源是 nvidia.com/gpu 时，资源监测图会展示额外的 GPU 相关指标，包括：利用率、温度、功率、显存使用率、已用显存量、SM Clock、TensorCore 利用率。

下面是展示 GPU 利用率和显存使用率的图表：

网络带宽

网络带宽显示下面两项指标：

• 接收带宽：所有容器接收数据的网络带宽总计。
• 发送带宽：所有容器发送数据的网络带宽总计。

存储 I/O

存储 I/O 显示下面两项指标：

• IOPS（读+写）：所有容器在节点的物理磁盘上，进行读写的操作次数之和。
• 吞吐量（读+写）：所有容器在节点的物理磁盘上，读写数据的吞吐量。

命令行工具

用户可以在 Notebook 的终端中，使用 kubectl top 命令查看 Pod 的 CPU、内存使用情况。例如：

(base) [/t9k/mnt t9kuser@managed-notebook-933f6-0]
$ kubectl top pods
NAME                                         CPU(cores)   MEMORY(bytes)   
managed-notebook-933f6-0                     25m          153Mi           
managed-project-event-ctl-854b96f4dd-f6hn8   1m           29Mi 

下一步

• 监控 T9k Job 的资源使用
• 监控推理服务的资源使用
• 监控 Notebook 的资源使用（TODO: 完成 查看 Notebook 资源使用 相关用户文档）

存储

TensorStack 平台支持多种类型的存储服务：Block Storage Volumes（块存储卷），Shared Filesystem Volumes (共享文件系统卷)，及基于 S3 协议的对象存储。

存储卷（Storage Volumes）

用户可申请使用两种类型的存储卷（Storage Volumes）：块存储卷，或者共享文件系统卷。

这两种高性能的网络存储卷服务，可为各种类型的工作负载，如 Notebook、T9k Jobs、推理服务等提供持久化存储卷（Persistent Volumes）服务。

• 支持在集群中使用不同性能等级的存储服务。例如，管理员可设置集群同时提供高性能的 SSD 和海量的 HDD 两种等级的存储服务；
• 所有 SSD 和 HDD 等级均可创建为 Block Volumes（块存储卷）或 Shared Filesystem Volumes （共享文件系统存储卷）；
• 可随时调整 Volume 大小以增加容量；
• 存储与计算分开管理，并且可以在不同实例和硬件类型之间移动；
• 支持存储卷的快照、备份及恢复。
• 可通过 UI 或 命令行工具 kubectl 轻松管理；

块存储卷（Block Storage Volumes）

Block Storage Volumes （块存储卷）可作为高性能虚拟存储盘挂载到各种类型的工作负载上。这些卷被呈现为通用 Block Device (块设备)，操作系统将其视为物理连接存储设备，并且独占使用。

如果集群部署了高性能的 NVMe 的存储节点，并使用了足够快的网络，这种类型的存储卷的性能将会超过本地 SATA 接口的 SSD，并且可以扩展到 PB 级别容量。

共享文件系统卷（Shared Filesystem Volumes）

遵守 POSIX 标准的 Filesystem Volumes（文件系统卷）可以挂载到各种工作负载上，以提供原生共享文件系统。

同时，这些卷可以同时附加到多个工作负载实例上，非常适合作在 Notebook、大规模并行计算 Job、推理服务等场景的存储卷。

对象存储

平台提供基于 S3 协议的对象存储服务，支持方便、通用的数据共享机制及低成本的数据归档服务。

使用

TensorStack 的存储卷（Storage Volumes）系统支持建立在 Kubernetes 的 Storage API 基础之上，通过 API Persistent Volumes，Storage Class 等提供用户接口。

同时，为了支持一些特定场景的使用，TensorStack 提供 CRD StorageShim，Explorer 以提供扩展支持。

例 1：获得集群中的存储类型：

$ kubectl get sc

例 2：创建存储请求：

# 使用 StorageClass `generic-hdd` 的 Filesystem Volumes (文件系统卷)
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-example
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 100Gi
  storageClassName: generic-hdd
  volumeMode: Filesystem

CRD 资源

存储系统中普通用户相关的 CRD 资源，列表如下：

参考

• API reference Explorer
• API reference StorageShim

PVC（持久卷）

PVC 是一种 Kubernetes 原生资源，是对存储的需求声明，它抽象了底层存储细节，允许用户请求特定大小和访问模式的存储，而不必关心存储的具体实现。

创建 PVC

下面是一个基本的 PVC 配置示例：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-demo
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 1Gi
  storageClassName: cephfs-hdd

在该例中：

• spec.resources.requests.storage 字段定义了所申请的存储空间容量大小为 1Gi。
• spec.accessModes 字段定义了访问模式为 ReadWriteMany，表示该 PVC 能够同时被多个节点上的 Pod 使用。
• spec.storageClassName 字段定义了所使用的存储类名称为 cephfs-hdd，集群中可用的存储类由管理员提供。

使用 PVC

下面是在 Pod 中使用 PVC 的示例：

apiVersion: v1
kind: Pod
metadata:
  name: pod-demo
spec:
  containers:
  - name: myfrontend
    image: nginx
    volumeMounts:
    - mountPath: "/var/www/html"
      name: data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: pvc-demo

在该例中，pod-demo 将 pvc-demo 作为一个数据卷（volume）来使用，其中容器 myfrontend 将该数据卷挂载到 /var/www/html 目录下。

在 TensorStack AI 平台中，PVC 是通用的持久化存储资源，你在 Notebook、Job、MLService、Workflow 等 TensorStack 资源中都可以使用 PVC。以 Notebook 为例：

apiVersion: tensorstack.dev/v1beta1
kind: Notebook
metadata:
  name: notebook-demo
spec:
  type: jupyter
  template:
    spec:
      containers:
      - image: t9kpublic/torch-2.0.0-notebook:1.72.0
        name: notebook
        resources:
          limits:
            cpu: "4"
            memory: 4Gi
          requests:
            cpu: "0.5"
            memory: 500Mi
        volumeMounts:
        - name: workingdir
          mountPath: /t9k/mnt
      volumes:
      - name: workingdir
        persistentVolumeClaim:
          claimName: pvc-demo

在该例中，notebook-demo 将 pvc-demo 作为一个数据卷（volume）来使用，其中容器 notebook 将该数据卷挂载到 /t9k/mnt 目录下。

生命周期

PVC 有以下几种状态：

• Pending：PVC 正在由对应的存储类处理。
• Bound：PVC 创建成功，可以被使用。
• Unknown：无法获取 PVC 状态。

PVC 与 Pod

PVC 的生命周期独立于 Pod。一个 PVC 可以被多个 Pod 使用。当 PVC 正在被 Pod 使用时，它无法被删除。

PVC 与 StorageShim

在 TensorStack AI 平台中，你可以：

1. 创建一个独立的 PVC，申请全新的存储空间。
2. 创建一个 StorageShim，将已有存储系统的某个子目录挂载为一个 PVC。此时 StorageShim 控制器将为所创建的 StorageShim 创建一个同名的 PVC，此 PVC 的生命周期由 StorageShim 管理。

容量请求

创建 PVC 时，spec.resources.requests.storage 字段用于指定 PVC 的容量，你无法在 PVC 中存储超过此容量限制的文件。

访问模式

创建 PVC 时，spec.accessModes 字段用于指定 PVC 的访问模式，可选择以下几种访问模式：

• ReadWriteMany：PVC 能被多个节点上的 Pod 读写。
• ReadWriteOnce：PVC 只能被一个节点上的 Pod 读写。
• ReadOnlyMany：PVC 只能被多个节点上的 Pod 读。

一般选择 ReadWriteMany 即可。

存储类

创建 PVC 时，spec.storageClassName 字段用于指定 PVC 的存储类，集群中可用的存储类由管理员提供。

例如，一个集群可能提供两个存储类，名为 cephfs-hdd 和 cephfs-ssd，分别提供基于 HDD 机械硬盘和 SSD 固态硬盘的存储空间，用于不同的数据存储目的。

下一步

• 了解 PVC 的概念
• 了解 PVC 的定义
• 如何上传和下载文件到 PVC

PVC 快照

如果 PVC 存放了重要的数据，用户可适时制作快照（snapshot），以方便恢复。

CRD 资源

存储系统中与快照相关的 CRD 资源，列表如下：

创建快照

下面是一个基本的 PVC 配置示例：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-demo
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 1Gi
  storageClassName: cephfs-hdd

为了对该 PVC 进行快照，用户需要创建如下 VolumeSnapshot 资源：

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: pvc-demo-snapshot
spec:
  volumeSnapshotClassName: cephfs-hdd-snapshotclass
  source:
    persistentVolumeClaimName: pvc-demo

其中：

• spec.volumeSnapshotClassName 定义了所使用的快照类为 cephfs-hdd-snapshotclass，每个 StorageClass 都有对应的 VolumeSnapshotClass，由管理员负责创建；VolumeSnapshot 指定的 spec.volumeSnapshotClassName 应当与 PVC 的 spec.storageClassName 对应。
• spec.source.persistentVolumeClaimName 定义了所要快照的 PVC 名称为 pvc-demo。

创建完成后，用户可以对 PVC 中的数据进行继续修改；若需要放弃修改，则可方便地使用快照恢复到修改前的数据。

从快照中恢复

如果想将 PVC 中的数据恢复至快照创建时刻的状态，用户需要创建一个新的 PVC（之前的 PVC 仍然可以使用，两个 PVC 之间互不影响）：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-demo-restore
spec:
  accessModes:
  - ReadWriteMany
  dataSource:
    name: pvc-demo-snapshot
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  resources:
    requests:
      storage: 1Gi
  storageClassName: cephfs-hdd

其中：

• spec.accessModes 必须与原 PVC 一致。
• spec.dataSource 引用了所要恢复的名为 pvc-demo-snapshot 的快照，本 PVC 中的数据将与该快照中的数据完全一致。
• spec.resources.requests.storage 必须与原 PVC 一致。
• spec.storageClassName 必须与原 PVC 一致。

下一步

• 了解 VolumeSnapshot 的概念

StorageShim

StorageShim 用于将已有的存储系统以 PVC 的形式提供给用户使用，例如 S3 bucket 的某个子路径可以作为一个 PVC，分布式文件系统的某个子目录可以作为一个 PVC。通过 StorageShim，用户能够方便地访问已经上传到各类存储系统中的数据，而无需进行复制。目前支持的存储系统包括 S3 和 CephFS，未来可能支持更多的存储系统类型。

创建 StorageShim

S3 类型

下面是一个 S3 类型的 StorageShim 配置示例：

apiVersion: tensorstack.dev/v1beta1
kind: StorageShim
metadata:
  name: storageshim-s3-demo
spec:
  type: s3
  s3:
    uri: "s3://bucket/path/subpath"
    readOnly: false
    secretRef:
      name: s3-secret-demo

其中所引用的 Secret s3-secret-demo 配置如下：

apiVersion: v1
kind: Secret
metadata:
  name: s3-secret-demo
  labels:
    tensorstack.dev/resource: s3-cfg
stringData:
  .s3cfg: <s3cfg>

在该例中，StorageShim storageshim-s3-demo 被创建后，StorageShim 控制器将创建一个同名的 PVC storageshim-s3-demo，该 PVC 的根目录对应 S3 路径 s3://bucket/path/subpath，访问该 S3 路径的登录凭证存储在 Secret s3-secret-demo 中，该 Secret 必须为 S3-cfg 类型。

CephFS 类型

下面是一个 CephFS 类型的 StorageShim 配置示例：

apiVersion: tensorstack.dev/v1beta2
kind: StorageShim
metadata:
  name: storageshim-cephfs-demo
spec:
  type: cephfs
  cephfs:
    path: /cephfs/data/user/mydata
    client:
      secretRef:
        name: ceph-client-key-demo
    server:
      configMapRef:
        name: ceph-cluster-config-demo

其中所引用的 Secret ceph-client-key-demo 配置示例如下：

apiVersion: v1
kind: Secret
metadata:
  name: ceph-client-key-demo
  labels:
    tensorstack.dev/resource: ceph-client
stringData:
  userID: <user-id>
  userKey: <user-key>

其中所引用的 ConfigMap ceph-cluster-config-demo 配置示例如下：

apiVersion: v1
kind: ConfigMap
metadata:
  name: ceph-cluster-config-demo
  labels:
    tensorstack.dev/resource: ceph-cluster
data:
  driver: <driver-name>
  clusterID: <cluster-id>
  fsName: <fs-name>

在该例中，StorageShim storageshim-cephfs-demo 被创建后，StorageShim 控制器将创建一个同名的 PVC storageshim-cephfs-demo，该 PVC 的根目录对应 CephFS 文件系统的子目录 /cephfs/data/user/mydata，访问该子目录的登录凭证存储在 Secret ceph-client-key-demo 中，该 Secret 必须为 S3-cfg 类型，该 CephFS 文件系统的相关信息存储在 ConfigMap ceph-cluster-config-demo 中。

下一步

• 使用 StorageShim 适配 S3 服务

Explorer

Explorer 提供几种展示和管理集群中数据的方法。

创建 Explorer

下面是一个基本的 Explorer 配置示例：

apiVersion: tensorstack.dev/v1beta1
kind: Explorer
metadata:
  name: example
spec:
  storageName: test
  storageType: pvc

在该例中，Explorer 展示和管理名为 test 的持久卷（Persistent Volume）中的数据。

存储方式

Explorer 目前仅支持展示存储在 PVC 中的文件（即 spec.storageType 字段暂时只能设置为 pvc）。

展示和管理方式

Explorer 会自动以多种方式展示和管理文件，目前支持文件浏览器和代码编辑器两种。

文件浏览器

使用第三方软件 File Browser 提供文件管理器形式的界面，支持文件系统浏览、文件上传、文件下载、基本的文件编辑等功能。

代码编辑器

使用第三方软件 VS Code 提供云端集成开发环境（IDE）的支持。开发者可以方便地运行网页版 VS Code，进行远程项目开发。

资源回收

Explorer 提供空闲资源回收的支持，在检测到 Explorer 处于空闲状态并超过一定时长时，删除工作负载以释放计算资源。默认情况下（管理员可修改配置）：

• Explorer 无人使用超过 1h 后，标记该 Explorer 为 Idle。
• Explorer 进入 Idle 状态超过 24h 后，删除该 Explorer 底层工作负载。

如果需要再次使用该 Explorer，你可以在模型构建控制台中手动点击恢复按钮。

下一步

• 使用 Explorer

辅助

TensorStack AI 平台提供了一些辅助性资源，它们为其他资源提供支持，或者为用户提供便捷、实用的功能。下表总结了所有辅助性资源：

Secret

Secret 是一种 Kubernetes 原生资源，用于存储少量敏感信息，比如密码、OAuth 令牌、SSH 密钥等。使用 Secret 可以避免将敏感数据直接写入到 Pod 的定义中或者应用程序代码里，从而提高了安全性。

创建 Secret

下面是一个基本的 Secret 配置示例：

apiVersion: v1
kind: Secret
metadata:
  name: secret-demo
type: Opaque
data:
  key1: dmFsdWUxCg==
  key2: dmFsdWUyCg==

在该例中，secret-demo 存储了两对键值对，其中值经过了 base64 编码。

使用 Secret

与 PVC 类似，Secret 可以以同样的方式作为数据卷被 Pod、Notebook、Job 等资源挂载。以 PyTorchTrainingJob 为例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: pytorchtrainingjob-demo
spec:
  replicaSpecs:
    - type: worker
      replicas: 1
      restartPolicy: OnFailure
      template:
        spec:
          containers:
            - image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel
              name: pytorch
              command:
                - python
                - dist_mnist.py
              resources:
                limits:
                  cpu: '1'
                  memory: 1Gi
                requests:
                  cpu: 500m
                  memory: 500Mi
              volumeMounts:
                - name: data
                  mountPath: /data
                - name: secret
                  mountPath: /secret
          volumes:
            - name: data
              persistentVolumeClaim:
                claimName: pvc-demo
            - name: secret
              secret:
                name: secret-demo

在该例中，pytorchtrainingjob-demo 将 pvc-demo 和 secret-demo 均作为数据卷（volume）来使用，其中容器 pytorch 将两个数据卷分别挂载到 /data 和 /secret 目录下。因此，容器 pytorch 的 /secret 目录下将存在两个文件 /secret/key1 和 /secret/key2，文件内容是经过 base64 解码后的对应的值。

Secret 用途

TensorStack AI 平台通过 label tensorstack.dev/resource 来标识 Secret 的用途，主要有以下几种：

• API Key：拥有 label tensorstack.dev/resource: apikey，用于存放 API Key，可在安全管理控制台创建 API Key。
• S3-cfg：拥有 label tensorstack.dev/resource: s3-cfg，用于存放 S3 配置文件的内容，可从本地的 $HOME/.s3cfg 文件中获取。
• S3-env：拥有 label tensorstack.dev/resource: s3-env，用于存放 S3 配置文件的每个字段，请从本地的 $HOME/.s3cfg 文件中获取。
• Docker：拥有 label tensorstack.dev/resource: docker，用于存放 Docker 配置文件的内容，可从本地的 $HOME/.docker/config.json 文件中获取。
• SSH Public Key：拥有 label tensorstack.dev/resource: ssh，用于存放 SSH 公钥，可从本地的 $HOME/.ssh/id_rsa.pub 文件中获取。
• Ceph Client：拥有 label tensorstack.dev/resource: ceph-client，用于存放 Ceph 客户端配置，可从管理员处获取。
• Custom：拥有 label tensorstack.dev/resource: other，自定义用途。

例如：

• SSH Public Key 类型的 Secret 可用于 Notebook SSH 访问
• Docker 类型的 Secret 可用于 ImageBuilder 构建并上传镜像
• S3-cfg 类型的 Secret 可用于创建 S3 类型的 StorageShim
• Ceph Client 类型的 Secret 可用于创建 CephFS 类型的 StorageShim

下一步

• 了解 Secret 的概念
• 了解 Secret 的定义

ConfigMap

ConfigMap 是一种 Kubernetes 原生资源，用于存储非机密性配置信息，它可以用来保存配置文件、命令行参数和环境变量等数据。ConfigMap使得容器化应用程序的配置与镜像内容分离，从而提高了应用的可移植性和灵活性。

创建 ConfigMap

下面是一个基本的 ConfigMap 配置示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: configmap-demo
data:
  key1: value1
  key2: value2

在该例中，configmap-demo 明文存储了两对键值对。

使用 ConfigMap

与 PVC 类似，ConfigMap 可以以同样的方式作为数据卷被 Pod、Notebook、Job 等资源挂载。以 PyTorchTrainingJob 为例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: pytorchtrainingjob-demo
spec:
  replicaSpecs:
    - type: worker
      replicas: 1
      restartPolicy: OnFailure
      template:
        spec:
          containers:
            - image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-devel
              name: pytorch
              command:
                - python
                - dist_mnist.py
              resources:
                limits:
                  cpu: '1'
                  memory: 1Gi
                requests:
                  cpu: 500m
                  memory: 500Mi
              volumeMounts:
                - name: data
                  mountPath: /data
                - name: configuration
                  mountPath: /config
          volumes:
            - name: data
              persistentVolumeClaim:
                claimName: pvc-demo
            - name: configuration
              configMap:
                name: configmap-demo

在该例中，pytorchtrainingjob-demo 将 pvc-demo 和 configmap-demo 均作为数据卷（volume）来使用，其中容器 pytorch 将两个数据卷分别挂载到 /data 和 /config 目录下。因此，容器 pytorch 的 /config 目录下将存在两个文件 /config/key1 和 /config/key2，文件内容分别是 value1 和 value2。

下一步

• 了解 ConfigMap 的概念
• 了解 ConfigMap 的定义

Pod

Pod 是可以在 Kubernetes 中创建和管理的、最小的可部署的计算单元。

Pod 是一组（一个或多个）容器；这些容器共享存储、网络、以及怎样运行这些容器的声明。Pod 中的内容总是并置的并且一同调度，在共享的上下文中运行。Pod 模拟一个特定应用的“逻辑主机”，其中包含一个或多个应用容器，这些容器相对紧密地耦合在一起。在非云环境中，在相同的物理机或虚拟机上运行的应用类似于在同一逻辑主机上运行的云应用。

除了应用容器，Pod 还可以包含在 Pod 启动期间运行的 Init 容器。你也可以在集群支持临时性容器的情况下，为调试的目的注入临时性容器。

通常你不需要直接创建 Pod，甚至单实例 Pod。你会使用诸如 Deployment 或 Job 这类工作负载资源来创建 Pod。如果 Pod 需要跟踪状态，可以考虑 StatefulSet 资源。

Kubernetes 集群中的 Pod 主要有两种用法：

• 运行单个容器的 Pod：最常见的 Kubernetes 用例； 在这种情况下，可以将 Pod 看作单个容器的包装器，并且 Kubernetes 直接管理 Pod，而不是容器。
• 运行多个协同工作的容器的 Pod：Pod 可能封装由多个紧密耦合且需要共享资源的共处容器组成的应用程序。这些位于同一位置的容器可能形成单个内聚的服务单元 —— 一个容器将文件从共享卷提供给公众，而另一个单独的 sidecar 容器则刷新或更新这些文件。Pod 将这些容器和存储资源打包为一个可管理的实体。

每个 Pod 都旨在运行给定应用程序的单个实例。如果希望横向扩展应用程序（例如，运行多个实例以提供更多的资源），则应该每个实例使用一个 Pod。在 Kubernetes 中，这通常被称为副本。通常使用一种工作负载资源及其控制器来创建和管理一组 Pod 副本。

Pod 示例

以下是一个 Pod 的 YAML 示例：

apiVersion: v1
kind: Pod
metadata:
  name: test-sdk
spec:
  containers:
    - name: sdk
      image: t9kpublic/t9k-sdk:0.6.0-torch-2.0.1
      command:
        - sleep
        - inf
      resources:
        limits:
          cpu: 500m
          memory: 200Mi

在上述示例中：

• Pod 使用 t9kpublic/t9k-sdk:0.6.0-torch-2.0.1（由 spec.containers[0].image 字段指定）镜像启动容器 sdk（由 spec.containers[0].name 字段指定）。
• 容器中执行 sleep inf（由 spec.containers[0].command 字段指定）命令。
• sdk 容器最多可使用 0.5 个 CPU 和 200Mi 内存（由 spec.containers[0].resources.limits 字段指定）。

应用场景

在 TensorStack AI 平台，你可以使用 Pod 实现以下操作：

• 测试镜像：在你使用 ImageBuilder 构建镜像后，可通过创建 Pod 并进入 Pod 终端来验证镜像是否符合预期。
• 存储卷预处理：在训练前，需提前下载好数据，此时可以通过创建 Pod 绑定对应 PVC，在 Pod 终端向其中下载数据。
• 测试代码：你在 Notebook 中开发后的脚本在训练镜像中并不一定能正常运行，可以用训练镜像创建一个 Pod，来测试训练脚本在新镜像中是否可用。

下一步

• 了解 Pod 的概念。
• 了解 Pod 的定义。

ImageBuilder

TensorStack 平台提供 CRD ImageBuilder，方便用户在集群中构建容器镜像。

创建 ImageBuilder

下面是一个基本的 ImageBuilder 定义示例：

# image-builder-example.yaml
apiVersion: tensorstack.dev/v1beta1
kind: ImageBuilder
metadata:
  name: imagebuilder-example
spec:
  dockerConfig:
    secret: docker-config
  tag: t9kpublic/kaniko-executor:v1.19.2
  workspace:
    pvc:
      name: kaniko
      dockerfilePath: ./Dockerfile
      contextPath: "."
  builder:
    kaniko: {}

在该例中：

• spec.dockerConfig.secret 字段指定使用 Secret docker-config 中记录的 docker 配置，以上传镜像。
• spec.tag 字段指定目标镜像的名称和标签为 t9kpublic/kaniko-executor:v1.19.2。
• spec.workspace 字段指定构建镜像使用 PVC kaniko 作为工作空间，其中：
  • 在 PVC 相对路径 ./Dockerfile 中存放构建镜像所需的 Dockerfile。
  • 在 PVC 相对路径 . 中存放构建镜像所需要的上下文。
• spec.builder 字段指定使用 kaniko 来构建镜像。

构建工具

目前 ImageBuilder 支持使用 kaniko 工具来构建镜像。

kaniko

用户可以通过 spec.builder.kaniko 字段来设置 kaniko 的参数。

在下面示例中，ImageBuilder 使用 t9kpublic/kaniko-executor:v1.19.2 启动 kaniko，并在该容器中构建用户镜像；ImageBuilder 不额外设置 kaniko 参数。

spec:
  builder:
    kaniko:
      image: t9kpublic/kaniko-executor:v1.19.2
      args: []

spec.builder.kaniko 的参数介绍：

• image：如忽略，ImageBuilder 控制器会指定一个默认镜像，所以一般来说可以不设置该字段。
• args：如忽略，ImageBuilder 构建镜像时执行 kaniko --destination=[image-tag] --context=[context-path] --dockerfile=[dockerfile-path] 命令。如果用户需要使用其他参数，可以在该字段中指定。参考 kaniko additional flags。

参考

更加详细的 ImageBuilder API 可直接在集群中查询：

kubectl explain imagebuilder

下一步

• 使用控制台：构建镜像
• Github 上的 ImagerBuilder 示例
• kaniko 的详细参考

工作流

AI 应用由很多基础计算步骤构成，具有很大灵活性，在不同场景需要做各种定制计算处理。例如，一个模型训练过程可能包含数据取样、数据转换、模型训练、模型质检、模型导出等步骤。

为此 TensorStack AI 平台提供了一个灵活的工作流服务，将这些计算步骤组合在一起，集中进行管理和调度，自动化复杂的流程。

架构

工作流模块提供了 WorkflowTemplate、WorkflowRun、CronWorkflowRun 等自定义扩展资源，以及控制台、服务器、操作器等组件。整体架构如下图所示：

其中：

• 控制台（Console）提供前端界面，方便用户对 WorkflowTemplate、WorkflowRun 等资源进行创建、查看、删除等操作。
  • 用户也可以直接使用命令行工具 kubectl 创建 workflow 的资源。
• 服务器（Server）向工作流控制台提供 API 接口，帮助获取 WorkflowTemplate、WorkflowRun 等资源的详细信息。
• 控制器（Controller），负责监控集群中的 WorkflowTemplate、WorkflowRun 等资源，并执行一些与资源相关的操作，使资源当前的状态与其理想状态一致。

与其他模块的关系

如下图所示，Workflow 可以将分布式并行作业、非并行作业组合在一起成为复合作业，而且复合作业中可以嵌套复合作业，并通过 T9k 调度器进行计算资源的匹配，最终完成复杂的多步骤计算。

WorkflowTemplate

WorkflowTemplate 用于在 Kubernetes 中有序、高效、方便地组织运行各类工作负载，例如机器学习流水线中的数据处理、模型训练、推理测试等具有依赖关系的多个步骤。WorkflowTemplate 是一个静态模板，指定了任务的详细规范，最终由 WorkflowRun 实例化并真正开始运行。

创建 WorkflowTemplate

下面的 WorkflowTemplate 示例创建并运行一个 Kubernetes Pod。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: workflowtemplate-sample
spec:
  description: This WorkflowTemplate creates and runs a Pod.
  type: Pod
  pod:
    containers:
      - name: hello
        image: ubuntu:latest
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["echo"]
        args: ["Hello TensorStack!"]

在该例中：

• description 字段简要介绍了该 WorkflowTemplate 的用途，会在控制台中展示。
• WorkflowTemplate 的类型（由 type 字段指定）是 Pod，表示 WorkflowTemplate 会创建并运行一个 Pod。
• pod 字段定义所要创建的 Pod 的规约，指示 Pod 运行一个 hello 容器，该容器运行镜像 ubuntu:latest 并打印一个字符串 Hello TensorStack!。

WorkflowTemplate 类型

WorkflowTemplate 的 spec.type 字段用于指定 WorkflowTemplate 的类型，可能的取值有：

• Pod
• SeqPod
• Resource
• DAG
• GenericJob
• TensorFlowTrainingJob
• PyTorchTrainingJob
• XGBoostTrainingJob
• ColossalAIJob
• DeepSpeedJob
• MPIJob
• BeamJob

Pod WorkflowTemplate

Pod WorkflowTemplate 用于创建一个原生的 Kubernetes Pod。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: pod-workflowtemplate-sample
spec:
  type: Pod
  pod:
    containers:
      - name: hello
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["sh", "-c"]
        args: ["echo Hello World!"]

spec.pod 中可以填写的字段与 Kubernetes Pod 相同。

SeqPod WorkflowTemplate

SeqPod WorkflowTemplate 用于创建一个经过包装的 Pod，在 Pod 中按顺序执行一些步骤。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: seqpod-workflowtemplate-sample
spec:
  type: SeqPod
  seqPod:
    steps:
      - name: hello
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["sh", "-c"]
        args: ["echo Hello World!"]
      - name: working
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["sh", "-c"]
        args: ["echo I am working!"]
      - name: bye
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["sh", "-c"]
        args: ["echo Goodbye!"]

SeqPod 中的每个步骤（step）对应 Kubernetes Pod 中的一个容器，但 SeqPod 会按照顺序依次执行每个步骤，直到所有的步骤成功运行完毕，或者其中某个步骤失败（后续的步骤不会再运行）。

在 pod.containers[*].command、pod.containers[*].args、seqPod.steps[*].command、seqPod.steps[*].args 等字段中，你有时候可能需要填写带有引号的字符串，有以下几种合法的方式：

command: ["echo"]
args: ["this is a 'quote'"]

command: ['echo']
args: ['this is a "quote"']

command:
  - echo
args:
  - this is a "quote"

command:
  - echo
args:
  - this is a 'quote'

指定 script

SeqPod 的每个步骤可以指定 script 字段，即一段脚本语言（例如 Bash、Python）编写的代码，用于代替 command 字段。script 脚本会在容器开始运行时代替 command 被调用，而 args 会被当做参数传递给 script 脚本。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: seqpod-workflowtemplate-sample-script
spec:
  type: SeqPod
  seqPod:
    steps:
      - name: hello
        image: python
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        script: |
          #!/usr/bin/env python3
          print("Hello from Python!")

如果 script 脚本的开头不包含以 #! 开头的字符串（shebang），以下字符串会被自动添加到 script 脚本的开头：

#!/bin/bash
set -e # Immediately exit if any command exited with non-zero status. 

保留目录

为了 SeqPod WorkflowTemplate 的正常工作，最终生成的 Pod 有一些特殊的保留目录：

• /t9k/workspaces：用于挂载 workspaces，你可以通过 $(workspaces.<workspaceName>.path) 来使用该路径。
• /t9k/results：用于存储 results，你可以通过 $(results.<resultName>.path) 来使用该路径。
• /t9k/tools：用于保证 SeqPod 中 steps 顺序执行的辅助工具，与用户无关。
• /t9k/termination：用于写入 Pod 的 termination message，与用户无关。

Resource WorkflowTemplate

Resource WorkflowTemplate 用于创建另一个 Kubernetes 资源，并监测该资源的运行状态。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: resource-workflowtemplate-sample
spec:
  type: Resource
  resource:
    manifest: |
      apiVersion: batch/v1
      kind: Job
      metadata:
        generateName: pi-job-
      spec:
        template:
          metadata:
            name: pi
          spec:
            containers:
            - name: pi
              image: perl
              command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
            restartPolicy: Never
        backoffLimit: 4
    successRules:
      fieldSelector: status.succeeded > 0
    failureRules:
      fieldSelector: status.failed > 3

spec.resource 的各个字段含义如下：

• manifest：所要创建的 Kubernetes 资源的详细配置。
• successRules：如果所创建的资源满足该条件，本 WorkflowTemplate 视为成功。
• failureRules：如果所创建的资源满足该条件，本 WorkflowTemplate 视为失败。

fieldSelector 的写法与 Kubernetes 标签选择器的语法相同但更强大，除了标签之外还能应用到资源的任意字段，支持的运算符有 >、<、==、!=、in、notin 等，多个需要同时满足的条件可以用逗号连接。例如，以下都是合法的 fieldSelector：

• status.succeeded>0
• status.succeeded > 0
• status.succeeded > 0,status.failed == 0
• status.phase in (Succeeded, Failed),status.workflowTemplateSpec.type == DAG

另外，successRules 和 failureRules 还支持设置 conditionSelector。如果所创建的资源的 status.conditions 字段包含一个 condition，其 type 和 status 都与 conditionSelector 相同，就认为该资源满足条件。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: resource-workflowtemplate-sample-condition
spec:
  type: Resource
  resource:
    manifest: |
      apiVersion: batch.tensorstack.dev
      kind: TensorFlowTrainingJob
      metadata:
        generateName: t9k-training-job-
      spec:
        ...
    successRules:
      conditionSelector:
        type: Succeeded
        status: "True"
    failureRules:
      conditionSelector:
        type: Failed
        status: "True"

如果所创建的资源类型是下列 T9k Jobs 之一，系统将自动帮助填写 successRules 和 failureRules，以减轻你的负担：

• GenericJob
• MPIJob
• BeamJob
• TensorFlowTrainingJob
• PyTorchTrainingJob
• XGBoostTrainingJob

创建 Resource WorkflowTemplate 对应的 WorkflowRun 时需要提供一个 Service Account，使得 WorkflowRun 具有在 Kubernetes 中创建该 Resource 的权限。例如：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowRun
metadata:
  name: resource-workflowtemplate-sample-run
spec:
  workflowTemplateRef: resource-workflowtemplate-sample
  serviceAccountName: managed-project-sa

在网页中创建 WorkflowRun 时，系统将自动为你配置名为 managed-project-sa 的 Service Account，你不用关心这一项的填写。

T9k Jobs WorkflowTemplate

T9k Workflow 系统对 T9k Jobs 提供更进一步的原生支持，添加以下 WorkflowTemplate 类型：

• GenericJob
• TensorFlowTrainingJob
• PyTorchTrainingJob
• XGBoostTrainingJob
• ColossalAIJob
• DeepSpeedJob
• MPIJob
• BeamJob

并在 WorkflowTemplate 的 spec 中添加了相应字段用于填写 T9k Job 的 spec：

• spec.genericJob
• spec.tensorflowTrainingJob
• spec.pytorchTrainingJob
• spec.xgboostTrainingJob
• spec.colossalaiJob
• spec.deepspeedJob
• spec.mpiJob
• spec.beamJob

相比于在 Resource 类型中将资源的 spec 视作一个很长的字符串，添加原生类型支持的好处是在创建 WorkflowTemplate 时 T9k Job 的 spec 就会得到语法检查，能更早地发现错误，加深了 T9k Workflow 系统和 T9k Job 系统的集成配合。

例如，创建一个 MPIJob 可以使用如下格式（其中 MPIJob 示例来自 MPIJob 文档）：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: mpijob-workflowtemplate-sample
spec:
  type: MPIJob
  mpiJob:
    spec:
      worker:
        replicas: 5
        processesPerWorker: 3
        processRecovery:
          enable: true
          limit: 100
        cmd:
          - ./random_walk
          - "20"
          - "40"
          - "2"
        template:
          spec:
            containers:
              - name: mpi-worker
                image: t9kpublic/mpi-tutorial:2021022-2
                resources:
                  limits:
                    cpu: 100m
                  requests:
                    cpu: 50m
                workingDir: /usr/local/code
      mca:
        btl: ^openib
      runPolicy:
        cleanUpWorkers: true
      ssh:
        sshdPath: /usr/sbin/sshd
      mpiHome: /usr/local

DAG WorkflowTemplate

DAG WorkflowTemplate 用于创建一个由其他 WorkflowTemplate 组成的有向无环图（DAG，Directed Acyclic Graph），按照有向无环图中的依赖关系按顺序执行这些 WorkflowTemplate。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: dag-workflowtemplate-sample
spec:
  type: DAG
  dag:
    templates:
      - name: a
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: []
      - name: b1
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: ["a"]
      - name: b2
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: ["a"]
      - name: c
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: ["b1", "b2"]

在上面的示例中，首先运行 WorkflowTemplate a，等待 WorkflowTemplate a 运行完毕之后再同时运行 WorkflowTemplate b1 和 b2。WorkflowTemplate c 会在 b1 和 b2 都结束后运行。这些 WorkflowTemplates 组成一个从上往下顺序执行的有向无环图：

   a
 /   \
b1   b2
 \   /
   c

指定参数

你可以为 WorkflowTemplate 指定一些参数，并在 spec 中用 $(params.<paramName>) 来引用参数。WorkflowRun 会在运行时为这些参数提供实际值。支持 params 的 WorkflowTemplate 类型有 Pod、SeqPod、DAG，详见支持变量替换的 WorkflowTemplate 字段。

Pod WorkflowTemplate 示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: pod-workflowtemplate-sample-params
spec:
  params:
    - name: message
      default: "hi"
  type: Pod
  pod:
    containers:
      - name: hello
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["sh", "-c"]
        args: ["echo $(params.message)"]

SeqPod WorkflowTemplate 示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: seqpod-workflowtemplate-sample-params
spec:
  params:
    - name: message
      default: hi
  type: SeqPod
  seqPod:
    steps:
      - name: hello
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        script: |
          #!/bin/sh
          echo $(params.message)

DAG WorkflowTemplate 在引用其他的 WorkflowTemplate 作为节点时，必须提供该节点需要的 params，可以是静态的字符串，也可以引用 DAG WorkflowTemplate 自身的 params 变量或其他变量。示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: dag-workflowtemplate-sample-params
spec:
  params:
    - name: dag-param
  type: DAG
  dag:
    templates:
      - name: step0
        workflowTemplateRef: pod-workflowtemplate-sample-params
        dependencies: []
        params:
          - name: message
            value: Hello World!
      - name: step1
        workflowTemplateRef: seqpod-workflowtemplate-sample-params
        dependencies: ["step0"]
        params:
          - name: message
            value: "$(params.dag-param)"
      - name: step2
        workflowTemplateRef: seqpod-workflowtemplate-sample-params
        dependencies: ["step1"]
        params:
          - name: message
            value: "DAG WorkflowTemplate provides param $(params.dag-param) for you"

指定工作空间

你可以为 WorkflowTemplate 指定可用的存储空间，并在 spec 中用 $(workspaces.<workspaceName>.path) 来引用存储空间的路径。WorkflowRun 会在运行时指定具体挂载何种存储空间，例如 PVC、Secret、ConfigMap 等。支持 workspaces 的 WorkflowTemplate 类型有 Pod、SeqPod、DAG。

Pod WorkflowTemplate 示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: pod-workflowtemplate-sample-workspace
spec:
  workspaces:
    - name: pod-workspace
  type: Pod
  pod:
    containers:
      - name: hello
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["sh", "-c"]
        args: ["echo Hello World! > $(workspaces.pod-workspace.path)/output.txt"]

SeqPod WorkflowTemplate 示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: seqpod-workflowtemplate-sample-workspaces
spec:
  workspaces:
    - name: seqpod-workspace
  type: SeqPod
  seqPod:
    steps:
      - name: hello
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        script: |
          #!/bin/sh
          echo Hello World! > $(workspaces.seqpod-workspace.path)/output.txt

DAG WorkflowTemplate 在引用其他的 WorkflowTemplate 作为节点时，必须提供该节点需要的 workspaces，一般通过 DAG WorkflowTemplate 自身的 workspaces 继承而来。示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: dag-workflowtemplate-sample-workspaces
spec:
  workspaces:
    - name: dag-workspace
  type: DAG
  dag:
    templates:
      - name: step0
        workflowTemplateRef: pod-workflowtemplate-sample-workspace
        dependencies: []
        workspaces:
          - name: pod-workspace
            workspace: dag-workspace
      - name: step1
        workflowTemplateRef: seqpod-workflowtemplate-sample-workspace
        dependencies: ["step0"]
        workspaces:
          - name: seqpod-workspace
            workspace: dag-workspace
      - name: step2
        workflowTemplateRef: seqpod-workflowtemplate-sample-workspace
        dependencies: ["step1"]
        workspaces:
          - name: seqpod-workspace
            workspace: dag-workspace

输出结果

WorkflowTemplate 可以在运行过程中输出一些字符串，并最终展示在 WorkflowRun 的 status 中。支持 results 的 WorkflowTemplate 类型有 SeqPod、DAG。

每个 result 本质上是一个文件，如下例所示，你可以向 $(results.<resultName>.path) 这个路径写入想要输出的内容。注意写入内容的总和不能超过 4096 字节。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: seqpod-workflowtemplate-sample-result
spec:
  results:
    - name: my-status
      description: "My status"
  type: SeqPod
  seqPod:
    steps:
      - name: echo
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        script: |
          echo I am OK > $(results.my-status.path)

results 更重要的用途是在 DAG WorkflowTemplate 的节点之间传递信息。DAG 的各个节点可以通过 $(templates.<workflowtemplateName>.results.<resultName>) 来引用这些 results，一般有两种用途：

• DAG 的下层节点可以在 params 或 when 字段引用上层节点的 results。
• DAG WorkflowTemplate 可以组合节点的 results 来输出自身的 results。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: add-workflowtemplate
spec:
  params:
    - name: first
      description: the first operand
    - name: second
      description: the second operand
  results:
    - name: sum
      description: the sum of the first and second operand
  type: SeqPod
  seqPod:
    steps:
      - name: add
        image: ubuntu
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        env:
          - name: OP1
            value: $(params.first)
          - name: OP2
            value: $(params.second)
        command: ["/bin/sh", "-c"]
        args:
          - echo -n $((${OP1}+${OP2})) | tee $(results.sum.path);
---
apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: sum-three-workflowtemplate
spec:
  params:
    - name: first
      description: the first operand
    - name: second
      description: the second operand
    - name: third
      description: the third operand
  type: DAG
  dag:
    templates:
      - name: first-add
        workflowTemplateRef: add-workflowtemplate
        params:
          - name: first
            value: $(params.first)
          - name: second
            value: $(params.second)
      - name: second-add
        workflowTemplateRef: add-workflowtemplate
        params:
          - name: first
            value: $(templates.first-add.results.sum)
          - name: second
            value: $(params.third)
  results:
    - name: total-sum
      description: the sum of all three operands
      value: $(templates.second-add.results.sum)
    - name: partial-sum
      description: the sum of first two operands
      value: $(templates.first-add.results.sum)

条件分支

在 DAG WorkflowTemplate 中，如果需要在某个条件满足时才执行某个节点，可以设置 when 字段。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: flip-coin
spec:
  results:
    - name: coin
      description: Which side? Heads or tails?
  type: SeqPod
  seqPod:
    steps:
      - name: flip-coin
        image: python
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        script: |
          #!/usr/bin/env python3
          import random
          f = open("$(results.coin.path)", "w")
          if random.random() > 0.5:
            f.write("heads")
          else:
            f.write("tails")
          f.close()
---
apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: dag-workflowtemplate-sample-when
spec:
  type: DAG
  dag:
    templates:
      - name: flip-coin
        workflowTemplateRef: flip-coin
      - name: execute-only-if-heads
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: ["flip-coin"]
        when:
          - input: "$(templates.flip-coin.results.coin)"
            operator: in
            values: ["heads"]

when 字段包含一些表达式：

• input：表达式的输入，可以是静态字符串或 params、results 等变量。如果未填写，默认为一个空的字符串。
• operator：表示 input 和 values 的关系，可以是 in 或者 notin。
• values：字符串数组，可以是静态字符串或 params、results 等变量。

只有当 when 字段包含的所有表达式结果都为真时，该节点才会被运行，否则会跳过该节点继续运行其他节点。

如果一个节点的 when 表达式中引用了其他节点的 results 变量，相当于引入了前者对后者的依赖关系，前者会在后者运行结束后才开始运行。

失败处理

对于 Pod/SeqPod/Resource WorkflowTemplate，一个 WorkflowRun 只对应一次运行，即使失败也不会重启。也就是说，一个 WorkflowRun 对应产生的 Pod 的 spec 中 restartPolicy 永远是 Never。

对于 DAG WorkflowTemplate，DAG 的每个节点都有可能会失败，我们使用 retries 字段来控制节点的重启。

• retries = 0（默认选项）表示不重启失败的节点。
• retries > 0 表示会重启失败的节点，并用一个正整数来限制最多可重启的次数。

如果 DAG 的某个节点失败并超过了最大可重启次数，该节点将被视为永久失败，并由 spec.dag.failureStrategy 决定接下来的行为：

• failureStrategy = StopAllWorkflowTemplates（默认选项）表示停止创建任何新的节点。
• failureStrategy = StopDependentWorkflowTemplates 表示只停止创建依赖于失败节点的节点，其他分支上的节点正常创建。

注意无论是哪种策略，已开始运行的节点都会等待其运行结束。

在下面的 DAG WorkflowTemplate 示例中，共有两个节点 a 和 b。

• 如果 a 节点运行失败，它最多可以重试 5 次。
• 如果 b 节点运行失败，它不能进行重试，直接被认定为失败。
• 如果任意一个节点被认定为失败，整个 DAG WorkflowTemplate 也会被认定为失败，并且由于 spec.dag.failureStrategy 字段的值为 StopAllWorkflowTemplates，所有未开始运行的节点都不再运行。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: dag-workflowtemplate-sample-retries
spec:
  type: DAG
  dag:
    failureStrategy: StopAllWorkflowTemplates
    templates:
      - name: a
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: []
        retries: 5
      - name: b
        workflowTemplateRef: pod-workflowtemplate-sample
        dependencies: ["a"]
        retries: 0

下一步

• 了解 WorkflowRun

WorkflowRun

WorkflowRun 是 WorkflowTemplate 的一次执行，为 WorkflowTemplate 提供运行时所需的一切资源，例如参数（params）、工作空间（workspaces）。

创建引用某个 WorkflowTemplate 的 WorkflowRun

下面的 WorkflowRun 示例为一个 WorkflowTemplate 创建一次运行。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowRun
metadata:
  name: workflowrun-sample
spec:
  workflowTemplateRef: workflowtemplate-sample

在该例中，workflowTemplateRef 字段标明所要运行的 WorkflowTemplate 的名称，该 WorkflowTemplate 必须是一个已经创建好的、与该 WorkflowRun 在同一个命名空间的 WorkflowTemplate。

创建内嵌 WorkflowTemplate 规约的 WorkflowRun

下面的 WorkflowRun 示例也是为一个 WorkflowTemplate 创建一次运行，但是该 WorkflowTemplate 的规约直接在 WorkflowRun 的规约中填写。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowRun
metadata:
  name: embedded-workflowrun-sample
spec:
  workflowTemplateSpec:
    type: Pod
    pod:
      containers:
        - name: hello
          image: ubuntu:latest
          command: ["echo"]
          args: ["Hello TensorStack!"]

在该例中，workflowTemplateSpec 字段用于填写所要运行的 WorkflowTemplate 的规约，WorkflowTemplate 规约的写法详见 WorkflowTemplateSpec（坏链）。

WorkflowRun 状态

在下面的示例中，首先创建一个类型为 DAG 的 WorkflowTemplate，然后创建一个 WorkflowRun 引用该 WorkflowTemplate。

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: dag-workflowtemplate-sample
spec:
  type: DAG
  dag:
    templates:
      - name: a
        workflowTemplateRef: pod-workflowtemplate-sample
      - dependencies:
          - a
        name: b1
        workflowTemplateRef: pod-workflowtemplate-sample
      - dependencies:
          - a
        name: b2
        workflowTemplateRef: pod-workflowtemplate-sample
      - dependencies:
          - b1
          - b2
        name: c
        workflowTemplateRef: pod-workflowtemplate-sample
---
apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowRun
metadata:
  labels:
    batch.tensorstack.dev/workflowTemplate: dag-workflowtemplate-sample
  name: dag-workflowtemplate-sample-run
spec:
  serviceAccountName: ''
  workflowTemplateRef: dag-workflowtemplate-sample
status:
  completionTime: '2021-04-16T07:39:05Z'
  conditions:
    - lastTransitionTime: '2021-04-16T07:39:05Z'
      status: 'False'
      type: Running
    - lastTransitionTime: '2021-04-16T07:39:05Z'
      status: 'True'
      type: Completed
  message: All nodes in DAG have succeeded
  nodes:
    a:
      phase: Succeeded
      workflowRunName: dag-workflowtemplate-sample-run-a-pmb2m
    b1:
      phase: Succeeded
      workflowRunName: dag-workflowtemplate-sample-run-b1-mssn6
    b2:
      phase: Succeeded
      workflowRunName: dag-workflowtemplate-sample-run-b2-5db66
    c:
      phase: Succeeded
      workflowRunName: dag-workflowtemplate-sample-run-c-sjpb2
  phase: Succeeded
  startTime: '2021-04-16T07:38:10Z'
  workflowTemplateSpec:
    dag:
      templates:
        - name: a
          workflowTemplateRef: pod-workflowtemplate-sample
        - dependencies:
            - a
          name: b1
          workflowTemplateRef: pod-workflowtemplate-sample
        - dependencies:
            - a
          name: b2
          workflowTemplateRef: pod-workflowtemplate-sample
        - dependencies:
            - b1
            - b2
          name: c
          workflowTemplateRef: pod-workflowtemplate-sample
    type: DAG

WorkflowTemplate dag-workflowtemplate-sample 有四个节点，分别是：

• a
• b1
• b2
• c

WorkflowRun dag-workflowtemplate-sample-run 被创建后，WorkflowRun 控制器会为这四个节点创建四个 WorkflowRun，分别是

• dag-workflowtemplate-sample-run-a-pmb2m
• dag-workflowtemplate-sample-run-b1-mssn6
• dag-workflowtemplate-sample-run-b2-5db66
• dag-workflowtemplate-sample-run-c-sjpb2

如果这四个 WorkflowRun 均运行成功，WorkflowRun dag-workflowtemplate-sample-run 即运行成功。

WorkflowRun dag-workflowtemplate-sample-run 的 status 字段显示，该 WorkflowRun 处于 Succeeded 状态（见 status.phase 字段），原因是 “All nodes in DAG have succeeded”（见 status.message 字段）。status.nodes 字段记录了该 WorkflowRun 中每个 DAG 节点的名称以及对应的 WorkflowRun 名称和状态。

下一步

• 了解如何建立自动化工作流

CronWorkflowRun

CronWorkflowRun 用于方便地定时执行 WorkflowRun，对于创建周期性的、反复重复的任务很有用。

cron 是一种书写定时计划的格式，用一个字符串指定何时触发任务的执行，通常由以空格分隔的 5 个部分组成：

# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of the month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday;
# │ │ │ │ │                                   7 is also Sunday on some systems)
# │ │ │ │ │
# │ │ │ │ │
# * * * * *

例如：

• 1 0 * * * 表示在每天的 00:01 执行。
• 45 23 * * 6 表示在每个星期六的 23:45 执行。
• */5 1,2,3 * * * 表示在每天的第 1、2、3 个小时每隔 5 分钟执行一次（即 01:00，01:05，01:10，…，03:55）。

注意 */n 表示每隔 n 个时间单位执行一次，在某个时间单位多次执行可以用逗号连接（例如 1,2,3）。

为了更方便地创建 cron 表达式，可以使用第三方网页工具，例如 crontab.guru。

创建 CronWorkflowRun

下面的 CronWorkflowRun 示例会每分钟创建一个 WorkflowRun。

apiVersion: batch.tensorstack.dev/v1beta1
kind: CronWorkflowRun
metadata:
  name: cronworkflowrun-sample
spec:
  schedule: "*/1 * * * *"
  workflowRun:
    spec:
      workflowTemplateRef: workflowtemplate-sample

在该例中：

• schedule 字段是一个 cron 格式的字符串，表示每分钟触发一次 WorkflowRun 的运行。
• 所要运行的 WorkflowRun 由 workflowRun 字段定义，是一个引用 workflowtemplate-sample 的 WorkflowRun。

详细配置 CronWorkflowRun

下面是一个经过详细配置的 CronWorkflowRun 示例，与上一节类似，也会每分钟创建一个 WorkflowRun。

apiVersion: batch.tensorstack.dev/v1beta1
kind: CronWorkflowRun
metadata:
  name: cronworkflowrun-sample
spec:
  schedule: "*/1 * * * *"
  startingDeadlineSeconds: 30
  concurrencyPolicy: "Allow"
  suspend: true
  successfulRunsHistoryLimit: 10
  failedRunsHistoryLimit: 10
  workflowRun:
    spec:
      workflowTemplateRef: workflowtemplate-sample

在该例中：

• 如果某个 WorkflowRun 由于任何原因未能准时在预设的时间点开始执行，它在 30 秒钟的期限内必须开始执行（由 startingDeadlineSeconds 字段指定），否则将被认为该次执行已失败。
• 如果到了某个 WorkflowRun 应该开始执行的时间点，但是上一个 WorkflowRun 仍未运行完成，允许这两个 WorkflowRun 同时运行（由 concurrencyPolicy 字段指定）。
• suspend 字段为 true 表示暂时停止创建新的 WorkflowRun，该字段可以随时变化。
• 由该 CronWorkflowRun 创建的所有 WorkflowRun 中，最多保留 10 个运行成功的 WorkflowRun 和 10 个运行失败的 WorkflowRun（分别由 successfulRunsHistoryLimit 和 failedRunsHistoryLimit 字段指定），多余的运行时间较早的 WorkflowRun 会被删除。

CronWorkflowRun 状态

下面是 CronWorkflowRun 的状态示例：

apiVersion: batch.tensorstack.dev/v1beta1
kind: CronWorkflowRun
metadata:
  name: cronworkflowrun-sample
spec:
  schedule: "*/1 * * * *"
  startingDeadlineSeconds: 30
  concurrencyPolicy: "Allow"
  suspend: true
  successfulRunsHistoryLimit: 10
  failedRunsHistoryLimit: 10
  workflowRun:
    spec:
      workflowTemplateRef: workflowtemplate-sample
status:
  active:
  - apiVersion: batch.tensorstack.dev/v1beta1
    kind: WorkflowRun
    name: cronworkflowrun-sample-1631093400
    namespace: t9k-example
    resourceVersion: "220623640"
    uid: 39634803-d8cf-41d4-8a8e-649e0133b11b
  lastScheduleTime: "2021-09-08T09:30:00Z"
  conditions:
  - lastTransitionTime: "2021-09-08T09:23:00Z"
    message: At least one WorkflowRun has started
    status: "True"
    type: HasStarted
  - lastTransitionTime: "2021-09-08T09:30:00Z"
    message: There are running WorkflowRuns
    status: "True"
    type: IsRunning
  - lastTransitionTime: "2021-09-08T09:23:35Z"
    message: There are successful WorkflowRuns
    status: "True"
    type: HasSuccessfulRun
  - lastTransitionTime: "2021-09-08T09:22:08Z"
    message: No failed WorkflowRuns yet
    status: "False"
    type: HasFailedRun

该 CronWorkflowRun 的 status 字段显示：

• 正在执行中的 WorkflowRun 有一个，其基本信息记录在 status.active 字段中。
• 最新的 WorkflowRun 的创建时间是 2021-09-08T09:30:00Z（由 status.lastScheduleTime 字段描述）。
• 在由该 CronWorkflowRun 创建的 WorkflowRun 中，已开始过至少一次 WorkflowRun（可能已结束或未结束），有正在运行中的 WorkflowRun，有已成功的 WorkflowRun，没有失败的 WorkflowRun（由 status.conditions 字段描述）。

WorkflowTrigger

TensorStack AI 平台提供了一个灵活的工作流服务，除了支持手动执行工作流 WorkflowRun，还提供了 CronWorkflowRun 用于定时执行。

Workflow Trigger 模块额外提供了一种基于特定事件自动触发执行 WorkflowRun 的能力，便于用户在一些特定场景下的自动化工作流运行。

架构

Workflow Trigger 模块提供了 EventListener 和 WorkflowTrigger 自定义扩展资源，整体架构如下图所示：

其中：

• EventListener 作为事件入口接收 JSON 格式的 HTTP POST 请求，同时将请求信息转换成 CloudEvents 格式并转发至事件队列。
• WorkflowTrigger 绑定一个或多个 EventListener 作为事件源，接收来自这些 EventListener 的 CloudEvents 格式的事件消息，并触发一个 WorkflowRun 的运行。特别地，支持对事件内容进行过滤，以及解析事件的某些字段的值填充到 WorkflowRun 的参数中。

快速开始

下面将通过几个简单的步骤来演示 Workflow Trigger 模块的基本使用方法。下面创建的所有资源请确保属于同一个命名空间。

1）创建 WorkflowTemplate

创建文件 workflow-template-sample.yaml：

apiVersion: batch.tensorstack.dev/v1beta1
kind: WorkflowTemplate
metadata:
  name: workflow-template-sample
spec:
  description: This WorkflowTemplate creates and runs a Pod.
  params:
    - name: message
      default: "TensorStack"
  type: Pod
  pod:
    containers:
      - name: hello
        image: ubuntu:latest
        resources:
          limits:
            cpu: 100m
            memory: 100Mi
        command: ["echo"]
        args: ["Hello $(params.message)!"]

上面的示例定义了一个名为 message 的参数，同时将该参数值以 $(params.message) 的形式传递到 Pod 的容器的 args 参数上，执行下面的命令创建 WorkflowTemplate：

kubectl apply -f workflow-template-sample.yaml

该 WorkflowTemplate 将作为一个静态模版用于执行一次 WorkflowRun 的运行。

2）创建 EventListener

创建文件 event-listener-sample.yaml：

apiVersion: tensorstack.dev/v1beta1
kind: EventListener
metadata:
  name: event-listener-sample
spec:
  replicas: 1

执行下面的命令创建一个 EventListener：

kubectl apply -f event-listener-sample.yaml

3）创建 WorkflowTrigger

创建文件 workflow-trigger-sample.yaml：

apiVersion: tensorstack.dev/v1beta1
kind: WorkflowTrigger
metadata:
  name: workflow-trigger-sample
spec:
  eventSources:
  - eventListenerName: event-listener-sample
  replicas: 1
  serviceAccountName: managed-project-sa
  workflowRunSpec:
    params:
    - name: message
      value: $(body.hello)
    workflowTemplateRef: workflow-template-sample

上面的示例以 $(body.hello) 的形式将 HTTP 请求体中的 hello 字段值传递到 param message 上，执行下面的命令创建 WorkflowTrigger：

kubectl apply -f workflow-trigger-sample.yaml

4）触发事件

通过执行下面的命令来查询 EventListener HTTP 服务的访问地址：

$ kubectl get eventlisteners event-listener-sample -o json | jq .status.address
{
  "inClusterURL": "http://event-listener-sample-eventlistener-2dbfe.default.svc.cluster.local",
  "url": "https://<tensorstack-host>/t9k/workflow/triggers/default/event-listener-sample"
}

其中 url 字段为集群外部访问 EventListener HTTP 服务的地址，使用 curl 命令向此地址发送 HTTP 请求来模拟触发事件：

curl -X POST https://<tensorstack-host>/t9k/workflow/triggers/default/event-listener-sample \
  -d '{"hello": "world"}'

其中 -d '{"hello": "world"}' 标识 HTTP 请求的 JSON 格式的 body 内容为 {"hello": "world"}，hello 字段值 "world" 将作为参数传递到 WorkflowRun，HTTP 服务将返回 success 表示请求已经发送成功。

5）查看 WorkflowRun

上面的步骤全部执行成功以后，WorkflowTrigger 将会触发一次 WorkflowRun 的运行，通过下面的命令进行查询：

$ kubectl get workflowruns
NAME                                                  PHASE
event-listener-sample-workflow-trigger-sample-87a0d   Succeeded

根据返回的结果可以看出，WorkflowRun 已经创建成功。该 WorkflowRun 将根据上面 WorkflowTemplate 静态模块的内容创建一个 Pod，通过下面的命令进行查询：

$ kubectl get po -l batch.tensorstack.dev/workflowRun=event-listener-sample-workflow-trigger-sample-87a0d
NAME                                                            READY   STATUS      RESTARTS   AGE
event-listener-sample-workflow-trigger-sample-87a0d-pod-6stvb   0/1     Completed   0          3m23s

根据返回的结果可以看出，Pod 已经创建成功，通过查询该 Pod 日志来校验参数传递：

$ kubectl logs event-listener-sample-workflow-trigger-sample-87a0d-pod-6stvb
Hello world!

Pod 日志成功打印出 “world” 内容，其为手动触发事件中发送的 HTTP 请求的 body 内容，参数成功传递。

至此，Workflow Trigger 模块的基本使用方法已经介绍完成，阅读下面的章节来获取更详细的配置信息。

EventListener

EventListener 内部运行着一个 HTTP 服务，用于接收第三方的请求，同时将请求消息转换成 CloudEvents 并将它们转发至事件队列。当前 EventListener 只支持 JSON 格式的 HTTP POST 请求。

创建 EventListener

下面是一个基本的 EventListener 示例：

apiVersion: tensorstack.dev/v1beta1
kind: EventListener
metadata:
  name: event-listener-sample
spec:
  replicas: 1
  resources:
    requests:
      memory: "100Mi"
      cpu: "100m"
    limits:
      memory: "200Mi"
      cpu: "200m"

在该例中：

• replicas 字段定义所要创建的 Pod 副本数量，默认是 1。
• resources 字段定义每个 Pod 的资源限制，上述示例为缺省时的默认值。

EventListener 状态

通过 EventListener 的状态字段可以获取其访问地址和运行状态信息，示例如下：

status:
  address:
    inClusterURL: http://<eventlistener-service-name>.default.svc.cluster.local
    url: https://<tensorstack-host>/t9k/workflow/triggers/default/<eventlistener-name>
  conditions:
  - lastTransitionTime: "2022-12-05T10:23:49Z"
    message: The EventListener is Ready
    status: "True"
    type: Ready

其中：

• status.address 表示 EventListener 所创建的 HTTP 服务的访问地址，第三方可向此地址发送请求，其中：
  • inClusterURL 是只能从集群内部访问的地址。
  • url 是可以从集群外部访问的地址。
• status.conditions 表示 EventListener 的状态：
  • type: Ready 表示 EventListener 是否就绪，可能的值有 True、False、Unknown。

WorkflowTrigger

WorkflowTrigger 从一个或多个 EventListener 事件源获取事件消息，并触发一个 WorkflowRun 的运行。

WorkflowTrigger 支持对每个 EventListener 配置过滤条件，只有符合过滤条件的事件消息才会被进一步处理；WorkflowTrigger 同时支持将事件消息的某些字段解析并填充到 WorkflowRun 的参数执行。

创建 WorkflowTrigger

下面是一个基本的 WorkflowTrigger 示例：

apiVersion: tensorstack.dev/v1beta1
kind: WorkflowTrigger
metadata:
  name: workflow-trigger-sample
spec:
  eventSources:
  - eventListenerName: event-listener-sample
  replicas: 1
  resources:
    requests:
      memory: "100Mi"
      cpu: "100m"
    limits:
      memory: "200Mi"
      cpu: "200m"
  serviceAccountName: managed-project-sa
  workflowRunSpec:
    workflowTemplateRef: workflow-template-sample

在该例中：

• eventSources 字段定义了该 WorkflowTrigger 需要订阅事件消息的事件源集合，其中：
• eventListenerName 表示上述 EventListener 的名称，该 EventListener 必须与该 WorkflowTrigger 同命名空间、且已成功创建。
• replicas 字段定义了该 WorkflowTrigger 创建的 Pod 副本数量，默认是 1。
• resources 字段定义每个 Pod 的资源限制，上述示例为缺省时的默认值。
• serviceAccountName 字段定义了该 WorkflowTrigger 创建的 Pod 的 ServiceAccount，为创建 WorkflowRun 提供权限。
• workflowRunSpec 字段定义了将要创建的 WorkflowRun 的配置规约，其中：
  • workflowTemplateRef 表示所要运行的 WorkflowTemplate 的名称，该 WorkflowTemplate 必须与该 WorkflowTrigger 同命名空间、且已成功创建。该字段同时支持内嵌 WorkflowTemplate 规约，详见 WorkflowRun。

过滤事件

WorkflowTrigger 支持对来自 EventListener 的事件消息进行过滤，只有符合过滤条件的事件消息才会被进一步处理。下面是一个包含过滤条件的 WorkflowTrigger 示例：

apiVersion: tensorstack.dev/v1beta1
kind: WorkflowTrigger
metadata:
  name: filter-workflow-trigger-sample
spec:
  eventSources:
  - eventListenerName: event-listener-sample
    filters:
    - path: body.object_attributes.work_in_progress
      type: bool
      values:
      - "false"
    - path: body.labels.0.id
      type: number
      values:
      - "219"
      - "3"
      - "99"
    - path: body.object_kind
      type: string
      values:
      - "merge_request"
  serviceAccountName: managed-project-sa
  workflowRunSpec:
    workflowTemplateRef: workflow-template-sample

在该例中，spec.eventSources.filters 定义了该 EventListener 的过滤条件集合，其中：

• path 表示 HTTP 请求路径，例如 header.X-Github-Event、body.pull_request.state。
• type 表示该路径指向字段的值的类型，当前支持 bool、number、string。
• values 表示该路径指向字段的值的可允许值的集合，其为 string 类型。

每个 EventListener 的 filters 互不影响，针对某一个 EventListener，其所有的 filters 必须全部通过才算符合条件。

解析参数

WorkflowTrigger 支持对来自 EventListener 的事件消息进行解析，并将指定字段的值通过参数的形式传递到 WorkflowRun。下面是一个包含解析参数的 WorkflowTrigger 示例：

apiVersion: tensorstack.dev/v1beta1
kind: WorkflowTrigger
metadata:
  name: param-workflow-trigger-sample
spec:
  eventSources:
  - eventListenerName: event-listener-sample
  serviceAccountName: managed-project-sa
  workflowRunSpec:
    params:
    - name: bool-name
      value: $(body.test.boolT)
    - name: number-name
      value: $(body.test.numberT)
    - name: string-name
      value: $(body.test.stringT)
    workflowTemplateRef: workflow-template-sample

在该例中，spec.workflowRunSpec.params 定义了将创建的 WorkflowRun 的参数集合，其中：

• name 表示参数名称。
• value 表示参数的值，可通过 $() 形式从事件消息中获取指定字段的值。当前不支持 $() 嵌套。

WorkflowTrigger 状态

通过 WorkflowTrigger 的状态字段可以获取其运行状态信息，示例如下：

status:
  conditions:
  - lastTransitionTime: "2022-12-05T10:26:46Z"
    message: The WorkflowTrigger is Ready
    status: "True"
    type: Ready

其中：

• status.conditions 表示 WorkflowTrigger 的状态：
  • type: Ready 表示 WorkflowTrigger 是否就绪，可能的值有 True、False、Unknown。

操作指南

使用模型构建控制台

模型构建控制台提供了大量功能，你可以在此进行模型构建，并管理 Job、存储和辅助资源。本部分将演示如何在模型构建控制台中使用 Notebook 和 TensorBoard，构建和调试镜像，以及管理存储、配置和隐私信息。

对于如何使用 T9k Job 和 AutoTune，请分别参阅运行模型训练和进行超参数优化。

创建 Notebook

本教程演示如何创建 Notebook。

准备工作

• 了解 Notebook 的基本概念。
• 成为一个项目的管理员或成员。

创建 PVC

创建 Notebook 时，需要至少绑定一个 PVC 来存储代码、数据等文件。如果你的项目中已有合适的持久卷，则可以直接进入下一节。

在模型构建控制台的左侧导航菜单中点击存储 > 持久卷进入 PVC 管理页面。然后点击右上角的创建 PVC 进入创建页面：

在 PVC 创建页面，名称填写 create-notebook，存储填写 1Gi，其他参数保持默认值，然后点击创建：

创建标准的 Notebook

在模型构建控制台的左侧导航菜单中点击构建 > Notebook 进入 Notebook 管理页面，然后点击右上角的创建 Notebook 进入创建页面：

在 Notebook 创建页面，如下填写各个参数：

• 名称填写 create-notebook。
• 存储卷选择上一节创建的 create-notebook（或其他合适的存储卷）。存储卷会被挂载到 Notebook 的 /t9k/mnt 目录下。
• 镜像根据你想使用的机器学习框架（如 TensorFlow、PyTorch 等）及其版本选择一个标准 Notebook 镜像。
• 模版根据你的资源需求选择一个合适大小的资源模版。

其他参数保持默认值，完成之后，点击创建：

回到 Notebook 管理页面查看新创建的 Notebook：

Notebook 就绪后，就可以使用 Notebook。

其他配置

使用 T9k 调度器

计算资源模块还提供了选项，使用调度器 t9k-scheduler，以支持便捷的资源使用申请，使用 t9k-scheduler 调度任务时必须指定一个队列。相比默认调度器，t9k-scheduler 需要额外填写如下参数：

• 队列 (queue)：必填，选择一个队列（如果没有队列，请联系管理员创建一个队列）。
• 优先级 (priority)：可选，默认值是 0。代表任务在队列内部的优先级。当发生资源抢占时，优先级数字较小的工作负载会比同一个队列中的其他负载优先被驱逐。

使用数据卷

可以为 Notebook 绑定额外的数据卷（存放数据的 PVC），如下图所示：

每绑定一个数据卷需要填写如下参数：

• 名称：使用的 PVC 名称。
• 绑定路径：将 PVC 绑定到 Notebook 的指定路径下。

在上图的示例中，我们将 PVC examples 绑定到了 Notebook 的 /t9k/examples 路径下。你可以在 Notebook 中通过对应路径访问 PVC 中的数据。

启用 SSH 选项

如果你想使用 SSH 连接到 Notebook 容器中来管理其中的文件，或者使用本地的 IDE 来编辑 Notebook 中的代码，启用 SSH 能够帮助你在 Notebook 中运行一个 SSH 服务。

Notebook 的 SSH 服务只允许通过密钥对进行验证，因此你需要上传公钥以使用 SSH 连接。TensorStack AI 平台使用 Secret 存储公钥信息。如果你已经创建了包含公钥的 Secret，则可以直接进入下一节。

在模型构建控制台的左侧导航菜单中点击辅助 > Secret，然后点击右上角的创建 Secret 进入的创建页面：

在 Secret 创建页面，选择类型为 SSH Public Key，填写名称和公钥内容。最后点击创建 Secret 进行创建：

创建 Notebook 时，开启启用 SSH 按钮，然后选择前面创建的 Secret（此处为一个多选框，你可以同时设置多个 SSH 公钥）：

点击创建，等待运行之后，你可以通过 SSH 连接远程使用 Notebook。

使用 Notebook

本教程演示如何使用 Notebook 进行模型开发相关的工作。

打开 JupyterLab

在模型构建控制台的左侧导航菜单中点击构建 > Notebook 进入 Notebook 管理页面，然后点击运行中的 Notebook 右侧的打开：

进入到 JupyterLab 的页面：

使用 Jupyter Notebook

点击 Launcher 标签页下，Notebook 下方的 Python3 图标以创建 Jupyter Notebook：

Jupyter Notebook 提供了交互式的 Python 开发环境。你可以在这里分块编辑并运行 Python 代码。比如运行 keras_mnist.py：

from tensorflow.keras import callbacks, datasets, layers, models, optimizers

model = models.Sequential([
    layers.Conv2D(32, 3, activation='relu', input_shape=(28, 28, 1)),
    layers.MaxPool2D((2, 2)),
    layers.Conv2D(64, 3, activation='relu'),
    layers.MaxPool2D((2, 2)),
    layers.Conv2D(64, 3, activation='relu'),
    layers.Flatten(),
    layers.Dense(64, activation='relu'),
    layers.Dense(10, activation='softmax'),
])
model.compile(optimizer=optimizers.Adam(learning_rate=0.001),
            loss='sparse_categorical_crossentropy',
            metrics=['accuracy'])


(train_images, train_labels), (test_images,
                            test_labels) = datasets.mnist.load_data()

train_images = train_images.reshape((60000, 28, 28, 1))
test_images = test_images.reshape((10000, 28, 28, 1))

train_images, test_images = train_images / 255.0, test_images / 255.0

model.fit(train_images,
        train_labels,
        batch_size=32,
        epochs=5,
        validation_split=0.2)
model.evaluate(test_images, test_labels)

编辑文件

在左侧的文件系统导航菜单空白处右击，可以创建文件和目录：

创建名为 keras_mnist.py 的文件，双击以进行编辑。复制上文中 keras_mnist.py 的内容，粘贴在文本编辑器中并保存：

使用 Terminal

点击左上角蓝色底色的 + 符号打开新的 Launcher 标签页，然后点击 Other 中的 Terminal 进入命令行终端。你可以在这里运行各种 bash 命令，例如运行 python ./keras_mnist.py 来进行模型训练：

查看详情

在 Notebook 管理页面，点击 Notebook 的名称进入其详情页面：

Notebook 的详情页面展示了 Notebook 的基本信息、状况和事件。点击 Pod 右侧的链接可以查看 Pod 的日志、状况、事件、资源监测等信息：

查看日志

点击日志，查看 Notebook Pod 的运行日志：

查看资源监测

点击资源监测，查看 Notebook Pod 运行时实际使用的资源，包括 CPU、内存、存储 I/O 的使用量：

通过 SSH 远程使用 Notebook

本教程演示如何通过 SSH 连接远程使用 Notebook。

准备

• 创建了一个启用 SSH 选项的 Notebook。
• 确认该 Notebook 处于正常运行状态。

端口转发

命令行工具 t9k-pf

命令行工具 t9k-pf 的功能类似于 kubectl port-forward，可以让用户能够在本地通过端口转发的方式访问 TensorStack AI 平台的各种资源。

请参照用户指南，下载安装 t9k-pf 并配置身份认证和授权。

端口转发命令

在 Notebook 详情页面，查看并复制SSH 服务提示的命令：

在终端执行该命令以进行端口转发：

$ t9k-pf notebook <URL> <Port>
now you can forward to your target by 127.0.0.1:<Port>

参数说明如下：

• URL：Notebook 的 Web UI 地址。除上述获取方式外，你也可以在打开 Notebook 后，复制浏览器地址栏中的地址作为 URL 参数使用。
• Port：转发的本地端口。在 SSH 远程连接教程中会使用到该端口。

根据终端打印的提示信息，使用本地的端口与目标 Notebook 建立 SSH 连接，具体命令请参阅 SSH 远程连接。

建立 SSH 连接

使用终端

在终端中运行以下命令以连接到 Notebook：

ssh t9kuser@localhost -p <Port> \
  -o StrictHostKeyChecking=no \
  -o GlobalKnownHostsFile=/dev/null \
  -o UserKnownHostsFile=/dev/null

然后在终端中操作 Notebook：

使用 VSCode

安装 Remote SSH 插件

在 VSCode 中搜索 Remote - SSH 插件并安装：

添加 SSH Config

安装完成后，需要在 SSH Config 中添加主机（Notebook）的信息。

VSCode 提供了编辑 SSH Config 的方式。点击左下角的绿色 >< 符号，选择 Connect to Host，然后拉动滚动条到最下方，点击 Add New SSH Host：

根据提示，输入以下内容，然后按下回车键（Enter）：

ssh t9kuser@localhost -p <Port>

VSCode 会提示 Select SSH configuration file to update，第一个选择项通常是位于 $HOME/.ssh/config 的配置文件，你可以选择将主机的信息存储在第一个配置文件中。

连接到 Notebook

点击左下角的绿色 >< 符号，选择 Connect to Host：

然后选择 SSH Config 中对应的主机名（使用上述配置方式时，主机名为 localhost）：

VSCode 会新建一个窗口，等待连接建立之后，左下角会提示 SSH: Host。

点击 Open Folder 可以选择打开的目录或者文件。你可以和本地开发一样使用 VSCode 来操作 Notebook：

使用 PyCharm

使用 PyCharm 远程连接到 Notebook 需要满足以下前提条件：

1. 安装了 PyCharm 专业版，且版本不低于 2022.2。PyCharm 有专业版（Professional）和社区版（Community），目前仅 PyCharm Professional 支持远程 SSH 开发。
2. Notebook 的资源配置至少为 3 个 CPU，3 GiB 内存，Notebook 绑定的持久卷至少有 2.5 GiB 的可用空间。推荐配置为至少 4 个 CPU，4 GiB 内存，5 GiB 持久卷。

打开 PyCharm，在左侧的导航菜单中点击 Remote Development > SSH，然后点击右侧的 New Connection：

在弹出的对话框中填写如下参数：

• Username：SSH 使用的用户名。
• Host：主机地址，通常为 127.0.0.1。
• Port：端口。
• Specify private key：建议勾选，并选择与你上传的公钥对应的私钥。

点击 Check Connection and Continue，进入下一步：

这里选择了在 Notebook 中安装的 IDE Backend 版本为 PyCharm 2022.2.3，远程打开的项目目录为 /t9k/mnt。点击 Download IDE and Connect 后，就可以通过 PyCharm 访问 Notebook 中的文件了。

你可以和本地开发一样使用 PyCharm 来操作 Notebook：

参考

• https://code.visualstudio.com/docs/remote/ssh
• https://www.jetbrains.com/help/pycharm/remote-development-overview.html

创建 TensorBoard

本教程演示如何创建 TensorBoard。

准备工作

• 了解 TensorBoard 的基本概念。
• 成为一个项目的管理员或成员。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

查看训练指标

TensorBoard 处于 Running 状态后，进入模型构建控制台的 TensorBoard 页面，可以看到 TensorBoard tensorboard 正在运行：

点击 TensorBoard 右侧的 打开 进入 TensorBoard 页面，查看可视化展示的训练和验证指标：

构建镜像

本教程演示如何在平台上构建容器镜像（container image）并推送到指定的容器镜像仓库（container registry）。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

其中，创建包含身份信息的 Secret 这一步骤也可以在模型构建控制台中通过创建 Docker 类型的 Secret 来完成，如下图所示。详情请参阅创建 Secret。

检查构建进度和结果

在模型构建控制台的左侧导航菜单中点击构建 > Image Builder，然后点击刚创建的 Image Builder 右侧的详情，查看其详情和日志。拉取基础镜像、构建镜像和推送镜像都需要花费一定的时间，请耐心等待。

一段时间后，构建完成的镜像被推送到相应的 registry 中。

FAQs

Unpacking rootfs 失败

使用 ImageBuilder 制作镜像时，有时会出现类似以下的错误：

INFO[0009] Unpacking rootfs as cmd RUN apt-get -qq update &&     apt-get -qq install --no-install-recommends -y curl requires it. 
error building image: error building stage: failed to get filesystem from image: stream error: stream ID 17; PROTOCOL_ERROR; received from peer

但是该错误信息并不准确，经分析，实际导致镜像 build 失败的可能原因是：镜像（Dockerfile 中 FROM 语句所引用的镜像）提取失败。

提取失败可能有以下原因：

• 镜像来源于无法访问或下载速度过慢的仓库

解决方法：

1. 切换到服务质量更好的的 Registry，例如本地网络部署的私有化 Registry，或其他 caching Regisry。
2. 使用代理服务器，通过该代理下载镜像。

调试镜像

本教程演示如何方便地在模型构建控制台通过命令行进入一个镜像，以便对镜像进行探索和测试。

准备工作

• 成为一个项目的管理员或成员。

示例

假设我们想知道镜像 t9kpublic/tensorflow-2.11.0-notebook-cpu:1.70.0 中安装了哪些 pip 包。

进入模型构建控制台后，点击构建 > Pod 进入 Pod 管理页面。

点击右上角的创建以创建一个 Pod，执行 sleep 命令使镜像保持运行状态，以便我们连接镜像中的 bash（或 sh）终端。

分别填写项目名称、镜像名称、运行命令和资源使用量，然后点击创建。

所创建的 Pod 变为运行状态后，点击 Pod 名称进入 Pod 详情页面。

点击终端按钮，打开终端。

在打开的终端中，输入 pip list 显示该镜像中安装的所有 pip 包，或者输入其他任何命令。

最后，点击右上角的 X 关闭终端。

管理 PVC

本教程演示如何在模型构建控制台中管理和使用 PVC。

准备工作

• 了解 PVC 的概念和 Kubernetes API。
• 成为一个项目的管理员或成员。

创建 PVC

进入模型构建控制台，在左侧导航菜单（或右侧卡片）中点击存储 > 持久卷进入 PVC 管理页面。

点击 PVC 管理页面右上角的创建 PersistentVolumeClaim 进入 PVC 创建页面。

在 PVC 创建页面填写名称和存储卷大小，选择存储卷访问模式和存储类，然后点击创建。

你可以点击左上角的导入 PersistentVolumeClaim 以加载当前存在的 PVC 的配置。

删除 PVC

在 PVC 管理页面，点击要删除的 PVC 右侧的更多按钮 > 删除。

使用 Explorer

本教程演示如何使用 Explorer 查看和修改存储在 PVC 和 StorageShim 中的文件。

启动 Explorer

在模型构建控制台的左侧导航菜单中点击存储 > 持久卷进入 PVC 管理页面，点击 PVC 右侧的启动：

将光标悬停在打开上，等待 File Browser 和 VS Code 就绪。随后点击 File Browser 和 VS Code 即可进入。

使用 File Browser

进入 File Browser 的前端页面，我们可以看到 PVC 中的所有文件和目录：

这里支持以下操作：

• 浏览目录和文本文件
• 创建、删除、重命名、复制、移动目录和文件
• 上传、下载文件
• 修改文本文件

使用 VS Code

进入 File Browser 的前端页面，我们可以看到 PVC 中的所有文件和目录：

这里支持以下操作：

• 浏览目录和文本文件
• 创建、删除、重命名、复制、移动目录和文件
• 修改文本文件，进行轻量级代码修改
• 启动终端并执行命令
• 进行源代码控制
• 安装 VS Code 插件

暂停和关闭 Explorer

使用结束后，我们可以关闭 Explorer。之后重新启用即可。

使用 StorageShim 适配 S3 服务

概述

TensorStack AI 平台支持用户在多个环节使用 S3 协议的存储服务。本教程演示如何通过 StorageShim 把 S3 存储服务转换成 PVC，以方便在一些需要使用 POSIX 文件系统接口的场景。

本教程涉及如下基本概念：

• S3（Simple Storage Service）提供可扩展、安全、高可用的对象存储服务，可以存储和检索任意数量和类型的数据，包括文档、图片、视频、音频等。更多详细信息请参阅附录。
• PVC（PersistentVolumeClaim）是 Kubernetes 提供的一种声明式的存储卷请求，用于向 Kubernetes 集群申请持久化存储卷。PVC 使应用程序与存储资源解耦，提高了存储资源的管理和使用效率。
• StorageShim 提供了把 S3 服务转换为 PVC 的能力，让用户能够以 Kubernetes 原生的方式使用 S3。

详细过程

要访问 S3 服务，需要提供使用其服务的相应配置，包括：

• S3 访问凭证：用于访问 S3 服务的一组密钥，包括访问密钥（access key）和秘密访问密钥（secret key）。S3 访问凭证是必需的，以在访问 S3 服务时进行身份验证和授权。
• S3 服务的终端地址（endpoint）：HTTP 或 HTTPS 格式的地址，例如：http://100.1.1.2:8000。
• S3 bucket：存储用户数据的容器；访问特定的 bucket 需要有合适权限的访问凭证。

准备 S3 配置

以下面的格式准备一个名为 s3cfg 的文件：

[default]
# Setup access keys
access_key = <you-access-key>
secret_key = <your-secret-key>

# Setup endpoint
host_base = http[s]://<host-or-ip>:<port>
use_https = <False | True>

其中需要修改的内容包括：

• access_key：你的访问密钥（access key）。
• secret_key：你的秘密访问密钥（secret key）。
• host_base：S3 服务的地址（endpoint）。
• use_https：是否使用 HTTPS。

你可以安装 s3cmd，在本地运行命令来验证 s3cfg 是否正确配置：

s3cmd -c s3cfg ls s3://<my-bucket>

创建 Secret

通过控制台

进入模型构建控制台，选择左侧导航菜单的辅助 > Secret，点击创建 Secret。

选择类型为 S3-cfg，填写名称，然后填写 Details 的内容：

• 服务端点：S3 服务的地址（endpoint）
• Access Key ID：你的访问密钥（access key）。
• 密码：你的秘密访问密钥（secret key）。

最后点击创建 Secret：

通过命令行工具

用户也可以使用 kubectl 命令行工具创建 Secret：

kubectl -n <project> create secret generic <s3cfg-secret> \
  --from-file=.s3cfg=<s3cfg>

其中需要修改的内容包括：

• <project>：项目名称。
• <s3cfg-secret>：Secret 的名称。
• <s3cfg>：本地 s3cfg 文件的路径。前面的 --from-file=.s3cfg= 不需要修改。

验证

运行以下命令，查看 Secret 中保存的 .s3cfg 内容：

kubectl -n <project> get secret <s3cfg-secret> \
    -o jsonpath={.data."\.s3cfg"} | base64 -d

其中需要修改的内容包括：

• <project>：项目名称。
• <s3cfg-secret>：Secret 的名称。

对比输出内容与你本地的 s3cfg，确认内容一致，重点是 access_key、host_base 和 secret_key 字段。

创建 StorageShim

通过控制台

进入模型构建控制台，选择左侧导航菜单的存储 > 持久卷，点击上方的 S3，然后点击右上角的创建 StorageShim：

输入持久卷名称、S3 URI（s3://<your-bucket>），然后选择 S3 Secret 名称，最后点击右上角的创建 StorageShim 完成创建：

在 S3 标签页查看新创建的 StorageShim：

通过命令行工具

使用以下命令创建 StorageShim 类型的 PVC：

kubectl -n <project> create -f - <<EOF
apiVersion: tensorstack.dev/v1beta1
kind: StorageShim
metadata:
  name: dataset
spec:
  readOnly: false
  s3:
    uri: 's3://42a3de90-d9e7-4769-8fc4-48a65fb561d5'
  secretRef:
    name: s3cfg-secret
EOF

其中需要修改的内容包括：

• <project>：项目名称。
• .spec.s3.uri：S3 bucket 的路径，你也可以具体指定 bucket 中的一个文件夹。
• .spec.secretRef.name：保存 S3 凭证的 Secret 名称。
• readOnly：如果为 true，那么用户只能读取这个 StorageShim 的内容，而不能修改它。

查看 PVC 状态，确认 STATUS 为 Bound：

$ kubectl -n <project> get pvc
NAME                STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS     AGE
dataset             Bound    pvc-cc7f789a-6fcb-44a0-8f42-0e6c86e51a1a   1          RWX            csi-s3           4m5s

附录

S3 基本概念

S3（Simple Storage Service）提供了可扩展、安全、高可用的对象存储服务，可以存储和检索任意数量和类型的数据，包括文档、图片、视频、音频等。

S3 使用：

• Bucket：Bucket 是 S3 存储中的基本容器，类似于文件夹，用于存储和组织对象。每个 Bucket 必须具有唯一的名称，并且名称必须符合 DNS 命名规则。
• Object：Object 是 S3 存储中的基本数据单元，可以是任意类型的数据，例如文档、图片、视频、音频等。每个 Object 由一个唯一的键（Key）和一个值（Value）组成，键是 Object 在 Bucket 中的唯一标识符，值是 Object 的实际数据。

S3 管理：

• Region：Region 是 S3 存储的物理位置，用于指定 Bucket 存储的地理位置。每个 Region 都由多个可用区域（Availability Zone）组成，以提供高可用性和容错性。
• ACL：ACL（Access Control List）是 S3 存储的访问控制列表，用于控制 Bucket 和 Object 的访问权限。ACL 可以指定特定用户或组的访问权限，也可以指定公共访问权限。
• Versioning：Versioning 是 S3 存储的版本控制功能，用于保留 Object 的所有版本。启用版本控制后，每次更新 Object 时都会创建一个新版本，并可以通过指定版本号来访问特定版本的 Object。
• Lifecycle：Lifecycle 是 S3 存储的生命周期管理功能，用于自动化管理 Bucket 和 Object 的生命周期。Lifecycle 可以指定 Object 的存储期限、转换存储类别、自动删除 Object 等操作，以优化存储成本和管理效率。

S3 基本使用：s3cmd

有多种工具（s3browser、WinSCP、s3cmd、s5cmd、rclone 等）可以访问 S3 存储服务，以下使用 s3cmd 演示 S3 的基本操作：

安装 s3cmd 工具：在 Linux 系统中使用命令行安装 s3cmd 工具，例如在 Ubuntu 系统中可以使用以下命令进行安装：

sudo apt-get install s3cmd

配置 s3cmd 工具：在命令行中执行 s3cmd --configure 命令，按照提示输入 S3 访问密钥和秘密访问密钥，以及 S3 服务的访问地址和区域等参数，完成 s3cmd 工具的配置。

创建 S3 存储桶：使用 s3cmd mb 命令创建 S3 存储桶，例如：

s3cmd mb s3://my-bucket-name

上传对象：使用 s3cmd put 命令上传对象到 S3 存储桶中，例如：

s3cmd put /path/to/local/file s3://my-bucket-name/path/to/remote/file

下载对象：使用 s3cmd get 命令从 S3 存储桶中下载对象到本地，例如：

s3cmd get s3://my-bucket-name/path/to/remote/file /path/to/local/file

删除对象：使用 s3cmd del 命令从 S3 存储桶中删除对象，例如：

s3cmd del s3://my-bucket-name/path/to/remote/file

设置对象 ACL：使用 s3cmd setacl 命令设置对象的 ACL，例如：

s3cmd setacl --acl-public s3://my-bucket-name/path/to/remote/file

对象存储（object storage）

对象存储是一种将数据存储为对象的数据存储架构，这与文件系统将数据作为文件层次结构进行管理不同。 每个对象通常包括数据本身（object）、元数据（metadata）和全局唯一标识符（object key）。

对象存储是存储海量非结构化数据（例如图像、视频和文档）的不错选择，例如大规模机器学习中使用的海量训练数据、特征、模型等。

与其他存储架构相比，对象存储具有许多优势，包括：

• 可扩展性：对象存储可以轻松扩展以满足不断增长的应用程序的需求。
• 耐用性：对象存储被设计成高度耐用的，数据以冗余方式存储在多个位置。
• 可用性：对象存储旨在提供高可用性，可以从世界任何地方访问数据。
• 安全性：对象存储提供了许多安全功能，包括加密和访问控制。

对象存储是一种强大而灵活的数据存储架构，是存储大量非结构化数据、需要从多个位置访问的数据以及需要高可用性和安全性的数据的不错选择。

参考

• Wikipedia: S3 协议
• Wikipedia: 对象存储
• AWS: S3 (Simple Storage Service)
• Kubernetes: PVC(PersistentVolumeClaim)

管理 Secret

本教程演示如何在模型构建控制台中管理和使用 Secret。

准备工作

• 了解 Secret 的概念和 Kubernetes API。
• 成为一个项目的管理员或成员。

创建 Secret

进入模型构建控制台，在左侧导航菜单（或右侧卡片）中点击辅助 > Secret 进入 Secret 管理页面。

点击 Secret 管理页面右上角的创建 Secret 进入 Secret 创建页面。

在 Secret 创建页面选择模板，填写名称和要存储的数据，然后点击创建。

你可以点击左上角的导入 Secret 以加载当前存在的 Secret 的配置。

删除 Secret

在 Secret 管理页面，点击要删除的 Secret 右侧的更多按钮 > 删除。

管理 ConfigMap

本教程演示如何在模型构建控制台中管理和使用 ConfigMap。

准备工作

• 了解 ConfigMap 的概念和 Kubernetes API。
• 成为一个项目的管理员或成员。

创建 ConfigMap

进入模型构建控制台，在左侧导航菜单（或右侧卡片）中点击辅助 > ConfigMap 进入 ConfigMap 管理页面。

点击 ConfigMap 管理页面右上角的创建 ConfigMap 进入 ConfigMap 创建页面。

在 ConfigMap 创建页面填写名称、标签和要存储的数据，然后点击创建。

你可以点击左上角的导入 ConfigMap 以加载当前存在的 ConfigMap 的配置。

删除 ConfigMap

在 ConfigMap 管理页面，点击要删除的 ConfigMap 右侧的更多按钮 > 删除。

运行模型训练

这一部分演示如何使用 T9k Job 运行不同机器学习框架的模型训练任务。对于常用的机器学习框架，如 PyTorch、TensorFlow、Horovod，你都可以在这里找到相应的教程来帮助你开始训练模型。

使用 PyTorchTrainingJob 进行数据并行训练

本教程演示如何使用 PyTorchTrainingJob 对 PyTorch 模型进行多工作器同步训练（使用 torch.nn.parallel.DistributedDataParallel 分布式数据并行模块）。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

检查训练日志和指标

训练开始后，进入模型构建控制台的 Job 页面，可以看到名为 torch-mnist-trainingjob 的 PyTorchTrainingJob 正在运行：

点击该名称进入详情页面，可以看到刚才创建的 PyTorchTrainingJob 的基本信息、状况信息和事件信息：

点击 TensorBoard 右侧的 Running 打开 TensorBoard，可以查看可视化展示的训练和验证指标：

点击上方标签页的副本，查看 PyTorchTrainingJob 的 Pod 信息：

点击副本右侧的更多按钮 > 日志以查看训练脚本执行过程中的日志输出：

点击上方标签页的资源监测，查看 PyTorchTrainingJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，PyTorchTrainingJob 的状态变为 Succeeded，表示训练成功完成。

若 PyTorchTrainingJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

使用 PyTorchTrainingJob 进行参数服务器训练

本教程演示如何使用 PyTorchTrainingJob 对 PyTorch 模型进行基于 RPC 的参数服务器训练（使用分布式 RPC 框架 torch.distributed.rpc）。示例修改自 PyTorch 官方教程 Implementing a Parameter Server Using Distributed RPC Framework，关于训练脚本的更多细节信息请参考此教程。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

检查训练日志和指标

训练开始后，进入模型构建控制台的 Job 页面，可以看到名为 torch-mnist-trainingjob-ps 的 PyTorchTrainingJob 正在运行：

点击该名称进入详情页面，可以看到刚才创建的 PyTorchTrainingJob 的基本信息、状况信息和事件信息：

点击 TensorBoard 右侧的 Running 打开 TensorBoard，可以查看可视化展示的训练和验证指标：

点击上方标签页的副本，查看 PyTorchTrainingJob 的 Pod 信息：

点击副本右侧的更多按钮 > 日志以查看训练脚本执行过程中的日志输出：

点击上方标签页的资源监测，查看 PyTorchTrainingJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，PyTorchTrainingJob 的状态变为 Succeeded，表示训练成功完成。

若 PyTorchTrainingJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

使用 TensorFlowTrainingJob 进行数据并行训练

本教程演示如何使用 TensorFlowTrainingJob 对 Keras 模型进行数据并行训练（采用 tf.distribute.MultiWorkerMirroredStrategy 分布式策略）。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

检查训练日志和指标

训练开始后，进入模型构建控制台的 Job 页面，可以看到名为 keras-mnist-trainingjob 的 TensorFlowTrainingJob 正在运行：

点击该名称进入详情页面，可以看到刚才创建的 TensorFlowTrainingJob 的基本信息、状况信息和事件信息：

点击 TensorBoard 右侧的 Running 打开 TensorBoard，可以查看可视化展示的训练和验证指标：

点击上方标签页的副本，查看 TensorFlowTrainingJob 的 Pod 信息：

点击副本右侧的更多按钮 > 日志以查看训练脚本执行过程中的日志输出：

点击上方标签页的资源监测，查看 TensorFlowTrainingJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，TensorFlowTrainingJob 的状态变为 Succeeded，表示训练成功完成。

若 TensorFlowTrainingJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

使用 TensorFlowTrainingJob 进行参数服务器训练

本教程演示如何使用 TensorFlowTrainingJob 对 Keras 模型进行参数服务器（parameter server）训练（采用 tf.distribute.experimental.ParameterServerStrategy 分布式策略）。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

检查训练日志和指标

训练开始后，进入模型构建控制台的 Job 页面，可以看到名为 keras-mnist-trainingjob-ps 的 TensorFlowTrainingJob 正在运行：

点击该名称进入详情页面，可以看到刚才创建的 TensorFlowTrainingJob 的基本信息、状况信息和事件信息：

点击 TensorBoard 右侧的 Running 打开 TensorBoard，可以查看可视化展示的训练和验证指标：

点击上方标签页的副本，查看 TensorFlowTrainingJob 的 Pod 信息：

点击副本右侧的更多按钮 > 日志以查看训练脚本执行过程中的日志输出：

点击上方标签页的指标，查看 TensorFlowTrainingJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，TensorFlowTrainingJob 的状态变为 Succeeded，表示训练成功完成。

若 TensorFlowTrainingJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

使用 Horovod 进行 PyTorch 模型的数据并行训练

本教程演示如何使用 MPIJob 对 PyTorch 模型进行多工作器同步训练（使用 horovod.torch 模块）。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

检查训练日志和指标

训练开始后，进入模型构建控制台的 Job 页面，可以看到名为 torch-mnist-mpijob 的 MPIJob 正在运行：

点击该名称进入详情页面，可以看到刚才创建的 MPIJob 的基本信息、状况信息和事件信息：

点击上方标签页的副本，查看 MPIJob 的 Pod 信息：

点击副本右侧的更多按钮 > 日志以查看训练脚本执行过程中的日志输出：

点击上方标签页的指标，查看 MPIJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，MPIJob 的状态变为 Succeeded，表示训练成功完成：

若 MPIJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

使用 Horovod 进行 Keras 模型的数据并行训练

本教程演示如何使用 MPIJob 对 Keras 模型进行多工作器同步训练（使用 horovod.tensorflow.keras 模块）。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

检查训练日志和指标

训练开始后，进入模型构建控制台的 Job 页面，可以看到名为 keras-mnist-mpijob 的 MPIJob 正在运行：

点击该名称进入详情页面，可以看到刚才创建的 MPIJob 的基本信息、状况信息和事件信息：

点击上方标签页的副本，查看 MPIJob 的 Pod 信息：

点击副本右侧的更多按钮 > 日志以查看训练脚本执行过程中的日志输出：

点击上方标签页的指标，查看 MPIJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，MPIJob 的状态变为 Succeeded，表示训练成功完成：

若 MPIJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

使用 Profiler 分析模型训练性能

概述

PyTorch 提供的 profiler 工具允许在训练和推理过程中收集性能指标，从而帮助用户更好地理解运算的代价和内存等资源消耗，测量 CPU 计算代价，CPU-GPU 之间数据复制成本，研究 GPU 内核程序性能并可视化执行追踪等。用户在 Notebook 中可以方便地使用这一工具。

本教程将介绍如何在 Notebook 中对启动 LLM 大规模预训练中的训练进行性能分析。

准备

在启动 LLM 大规模预训练给出的准备工作的基础上，还需要修改 Megatron-DeepSpeed 的训练代码，用 profiler 上下文管理器包装训练循环的代码。直接使用 Notebook 的文本编辑器修改代码即可。

# Megatron-DeepSpeed/megatron/training.py
...

    profile_path = os.path.join(os.path.dirname(args.tensorboard_dir), 'profiling')

    with torch.profiler.profile(
            schedule=torch.profiler.schedule(wait=1, warmup=1, active=3, repeat=2),
            on_trace_ready=torch.profiler.tensorboard_trace_handler(profile_path),
            record_shapes=True,
            profile_memory=True,
            with_stack=True,
            with_flops=True,
            with_modules=True
    ) as prof:  # profiler context manager
        while iteration < args.train_iters and (args.train_tokens is None or \
            args.consumed_train_tokens < args.train_tokens):  # training loop

            ...

            prof.step()

...

其中对于 profiler 的配置为：

• profiler 跳过 1 个 step，热身 1 个 step，然后记录 3 个 step；总共重复 2 次。
• 生成用于 TensorBoard 展示的结果文件，与 TensorBoard 日志文件保存到同一父目录下。
• 记录算子的源信息和输入形状，记录模块（module）的调用栈，估计 FLOPS，跟踪张量内存的分配和释放。

启动性能分析

以 4 个 GPU 训练 125M 参数的 GPT 模型，启动训练：

kubectl create -f \
  examples/deepspeed/megatron-gpt/training/gpt-125m-4xdp.yaml

通过以下命令查看训练过程中打印的日志：

kubectl logs gpt-125m-4xdp-worker-0 -f

性能分析完成之后，结果文件被保存在 output/gpt-125m-4xdp/profiling 路径下，前往该路径并启动一个 TensorBoard 实例以查看可视化结果。

查看可视化结果

Overview 展示了训练性能的总体情况，包含 GPU 的总体情况、不同执行类别花费的时间和占比，以及自动生成的性能优化建议：

Operator View 展示了所有 PyTorch 算子被调用的次数、花费的时间以及它的调用栈：

Kernel View 展示了所有 GPU 内核被调用的次数、花费的时间的统计以及它是否使用了 Tensor Core 等：

Memory View 展示了内存使用曲线图、内存事件（分配和释放）以及内存统计数据：

TensorBoard 所展示的数据和提供的功能还远不止这些，请参阅官方教程以了解更多。这些数据应当能为用户分析和改进性能提供非常有用的帮助。

调试 Job

本教程演示如何使用 Job 的调试模式这一功能来对计算任务进行调试。

运行示例

请按照使用方法准备环境，然后前往本教程对应的示例，参照其 README 文档运行。

通过 SSH 远程连接

对于开启了 SSH 服务的容器，建立 SSH 连接的操作步骤和 Notebook 相同，请参照通过 SSH 远程使用 Notebook进行操作。唯一不同的是端口转发使用 t9k-pf pod 命令，而非 t9k-pf notebook 命令：

t9k-pf pod <POD_NAME> 5001:2222 -n <PROJECT_NAME>

进行调试

不论是进入休眠的容器，还是远程连接开启了 SSH 服务的容器，调试都是通过执行一些命令来进行。例如使用 nvidia-smi 命令检查当前可用的 GPU，再使用 ls 命令检查训练脚本是否存在：

# 在容器中
nvidia-smi
ls

然后使用 torchrun 命令启动训练：

# 在容器中
cd ~/tutorial-examples/job/debug
torchrun --nnodes 1 --nproc_per_node 4 --rdzv_backend c10d torch_mnist_trainingjob.py --save_path model_state_dict.pt --log_dir log --backend nccl

随即分布式训练开始进行。如果训练脚本出错，则可以立即在终端中进行调试，不会造成 Job 的失败。调试完成后禁用 debug 模式（将 spec.runMode.debug.enable 设为 false，或直接注释第 6-12 行），再次创建 PyTorchTrainingJob 则正常启动训练。

进行超参数优化

超参数优化是机器学习中的一项关键任务，其目标是选择一组最佳的超参数来改进模型性能。这一任务面临多重挑战：超参数通常不可微分，搜索空间高维且非凸，评估成本高，手动调参既繁琐又低效。为此 TensorStack AI 平台提供了自动化工具 AutoTune，其支持多种超参数优化算法，能够自动搜索超参数空间、存储搜索结果并进行可视化，并且配置简单，使用方便。

这一部分将使用 AutoTune 进行模型的超参数优化。

使用 AutoTune 进行超参数优化

本教程演示如何使用 AutoTune 对模型进行超参数优化（以 Keras 模型的单机训练为例）。

准备训练脚本

在开始超参数优化实验之前，你需要提前准备训练脚本。你可以使用模型构建控制台中的 Notebook 编辑训练脚本。

创建 PVC

参照创建 PVC 教程创建名为 autotune-mnist-keras、大小为 1Gi 的 PVC。

创建 Notebook

从模型构建控制台进入 Notebook 列表，点击右上角的创建 Notebook。

创建 Notebook 时，在存储卷选择前面创建的 PVC 的名称 autotune-mnist-keras。

创建完成之后，点击打开进入 Notebook。

在 Notebook 中编辑训练脚本

以下是一个 Keras 训练脚本，在此基础上做简单的修改以应用在 AutoTune 实验中。

import argparse
import json
import logging
import os
import time

import tensorflow as tf
from tensorflow.keras import callbacks, datasets, layers, models, optimizers

parser = argparse.ArgumentParser(
    description='Distributed training of Keras model for MNIST with '
    'MultiWorkerMirroredStrategy.')
parser.add_argument('--log_dir',
                    type=str,
                    default=None,
                    help='Path of the TensorBoard log directory.')
parser.add_argument('--no_cuda',
                    action='store_true',
                    default=False,
                    help='Disable CUDA training.')
parser.add_argument('--save_path',
                    type=str,
                    default=None,
                    help='Save path of the trained model.')
args = parser.parse_args()
logger = logging.getLogger('print')
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler())
logger.propagate = False

if args.no_cuda:
    tf.config.set_visible_devices([], 'GPU')
gpus = tf.config.get_visible_devices('GPU')
if gpus:
    # Print GPU info
    logger.info('NVIDIA_VISIBLE_DEVICES: {}'.format(
        os.getenv('NVIDIA_VISIBLE_DEVICES')))
    logger.info('T9K_GPU_PERCENT: {}'.format(os.getenv('T9K_GPU_PERCENT')))
    logger.info('Visible GPUs: {}'.format(
        tf.config.get_visible_devices('GPU')))
    # Set memory growth
    for gpu in gpus:
        tf.config.experimental.set_memory_growth(gpu, True)
    # # Set GPU memory limit
    # tf.config.set_logical_device_configuration(
    #     gpus[0], [tf.config.LogicalDeviceConfiguration(memory_limit=1024)])

strategy = tf.distribute.MultiWorkerMirroredStrategy()

# Get information for current worker.
tf_config = json.loads(os.environ['TF_CONFIG'])
world_size = len(tf_config['cluster']['worker'])
task_index = tf_config['task']['index']

params = {
    # Search space:
    # 'batch_size': ...
    # 'learning_rate': ...
    # 'conv_channels1': ...
    'epochs': 10,
    'conv_channels2': 64,
    'conv_channels3': 64,
    'conv_kernel_size': 3,
    'maxpool_size': 2,
    'linear_features1': 64,
    'seed': 1,
}

with strategy.scope():
    model = models.Sequential([
        layers.Conv2D(params['conv_channels1'],
                      params['conv_kernel_size'],
                      activation='relu',
                      input_shape=(28, 28, 1)),
        layers.MaxPooling2D((params['maxpool_size'], params['maxpool_size'])),
        layers.Conv2D(params['conv_channels2'],
                      params['conv_kernel_size'],
                      activation='relu'),
        layers.MaxPooling2D((params['maxpool_size'], params['maxpool_size'])),
        layers.Conv2D(params['conv_channels3'],
                      params['conv_kernel_size'],
                      activation='relu'),
        layers.Flatten(),
        layers.Dense(params['linear_features1'], activation='relu'),
        layers.Dense(10, activation='softmax'),
    ])
    model.compile(
        optimizer=optimizers.Adam(learning_rate=params['learning_rate']),
        loss='sparse_categorical_crossentropy',
        metrics=['accuracy'])

(train_images, train_labels), (test_images,
                               test_labels) = datasets.mnist.load_data(
                                   path=os.path.join(os.getcwd(), 'mnist.npz'))
train_images = train_images.reshape((60000, 28, 28, 1)).astype("float32") / 255
test_images = test_images.reshape((10000, 28, 28, 1)).astype("float32") / 255
train_images, val_images = train_images[:48000], train_images[48000:]
train_labels, val_labels = train_labels[:48000], train_labels[48000:]
train_dataset = tf.data.Dataset.from_tensor_slices(
    (train_images, train_labels)).shuffle(
        48000, seed=params['seed']).repeat().batch(params['batch_size'])
val_dataset = tf.data.Dataset.from_tensor_slices(
    (val_images, val_labels)).batch(400)
test_dataset = tf.data.Dataset.from_tensor_slices(
    (test_images, test_labels)).batch(1000)

model.fit(train_images,
          train_labels,
          batch_size=params['batch_size'],
          epochs=params['epochs'],
          validation_split=0.2,
          verbose=2)

# TODO: Automatically save best n models.
# if args.save_path and task_index == 0:
#     t9k.autotune.utils.save_best_n_models(model, args.save_path)

model.evaluate(test_images, test_labels, callbacks=test_callbacks, verbose=2)

if task_index > 0:
    # wait a while for index 0
    time.sleep(1)

在上述脚本中导入 t9k.tuner 模块，在训练模型之前调用 get_next_parameter() 函数获取训练超参数，替换原来的参数。

from t9k import tuner

def main():
    ...
    tuner_params = tuner.get_next_parameter()
    params.update(tuner_params)
    ...

在训练过程中，添加 AutoTuneCallback 上传实验指标。

train_callbacks = []
test_callbacks = []

if task_index == 0:
    from t9k.tuner.keras import AutoTuneFitCallback, AutoTuneEvalCallback
    train_callbacks.append(AutoTuneFitCallback(metric='accuracy'))
    test_callbacks.append(AutoTuneEvalCallback(metric='accuracy'))
    if args.log_dir:
        tensorboard_callback = callbacks.TensorBoard(log_dir=args.log_dir)
        train_callbacks.append(tensorboard_callback)

如下为修改后的训练脚本：

import argparse
import json
import logging
import os
import time

import tensorflow as tf
from tensorflow.keras import callbacks, datasets, layers, models, optimizers

from t9k import tuner

parser = argparse.ArgumentParser(
    description='Distributed training of Keras model for MNIST with '
    'MultiWorkerMirroredStrategy.')
parser.add_argument('--log_dir',
                    type=str,
                    default=None,
                    help='Path of the TensorBoard log directory.')
parser.add_argument('--no_cuda',
                    action='store_true',
                    default=False,
                    help='Disable CUDA training.')
parser.add_argument('--save_path',
                    type=str,
                    default=None,
                    help='Save path of the trained model.')
args = parser.parse_args()
logger = logging.getLogger('print')
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler())
logger.propagate = False

if args.no_cuda:
    tf.config.set_visible_devices([], 'GPU')
gpus = tf.config.get_visible_devices('GPU')
if gpus:
    # Print GPU info
    logger.info('NVIDIA_VISIBLE_DEVICES: {}'.format(
        os.getenv('NVIDIA_VISIBLE_DEVICES')))
    logger.info('T9K_GPU_PERCENT: {}'.format(os.getenv('T9K_GPU_PERCENT')))
    logger.info('Visible GPUs: {}'.format(
        tf.config.get_visible_devices('GPU')))
    # Set memory growth
    for gpu in gpus:
        tf.config.experimental.set_memory_growth(gpu, True)
    # # Set GPU memory limit
    # tf.config.set_logical_device_configuration(
    #     gpus[0], [tf.config.LogicalDeviceConfiguration(memory_limit=1024)])

strategy = tf.distribute.MultiWorkerMirroredStrategy()

# Get information for current worker.
tf_config = json.loads(os.environ['TF_CONFIG'])
world_size = len(tf_config['cluster']['worker'])
task_index = tf_config['task']['index']

tuner_params = tuner.get_next_parameter()
params = {
    # Search space:
    # 'batch_size': ...
    # 'learning_rate': ...
    # 'conv_channels1': ...
    'epochs': 10,
    'conv_channels2': 64,
    'conv_channels3': 64,
    'conv_kernel_size': 3,
    'maxpool_size': 2,
    'linear_features1': 64,
    'seed': 1,
}
params.update(tuner_params)

with strategy.scope():
    model = models.Sequential([
        layers.Conv2D(params['conv_channels1'],
                      params['conv_kernel_size'],
                      activation='relu',
                      input_shape=(28, 28, 1)),
        layers.MaxPooling2D((params['maxpool_size'], params['maxpool_size'])),
        layers.Conv2D(params['conv_channels2'],
                      params['conv_kernel_size'],
                      activation='relu'),
        layers.MaxPooling2D((params['maxpool_size'], params['maxpool_size'])),
        layers.Conv2D(params['conv_channels3'],
                      params['conv_kernel_size'],
                      activation='relu'),
        layers.Flatten(),
        layers.Dense(params['linear_features1'], activation='relu'),
        layers.Dense(10, activation='softmax'),
    ])
    model.compile(
        optimizer=optimizers.Adam(learning_rate=params['learning_rate']),
        loss='sparse_categorical_crossentropy',
        metrics=['accuracy'])

(train_images, train_labels), (test_images,
                               test_labels) = datasets.mnist.load_data(
                                   path=os.path.join(os.getcwd(), 'mnist.npz'))
train_images = train_images.reshape((60000, 28, 28, 1)).astype("float32") / 255
test_images = test_images.reshape((10000, 28, 28, 1)).astype("float32") / 255
train_images, val_images = train_images[:48000], train_images[48000:]
train_labels, val_labels = train_labels[:48000], train_labels[48000:]
train_dataset = tf.data.Dataset.from_tensor_slices(
    (train_images, train_labels)).shuffle(
        48000, seed=params['seed']).repeat().batch(params['batch_size'])
val_dataset = tf.data.Dataset.from_tensor_slices(
    (val_images, val_labels)).batch(400)
test_dataset = tf.data.Dataset.from_tensor_slices(
    (test_images, test_labels)).batch(1000)

train_callbacks = []
test_callbacks = []

if task_index == 0:
    from t9k.tuner.keras import AutoTuneFitCallback, AutoTuneEvalCallback
    train_callbacks.append(AutoTuneFitCallback(metric='accuracy'))
    test_callbacks.append(AutoTuneEvalCallback(metric='accuracy'))
    if args.log_dir:
        tensorboard_callback = callbacks.TensorBoard(log_dir=args.log_dir)
        train_callbacks.append(tensorboard_callback)

model.fit(train_images,
          train_labels,
          batch_size=params['batch_size'],
          epochs=params['epochs'],
          validation_split=0.2,
          callbacks=train_callbacks,
          verbose=2)

# TODO: Automatically save best n models.
# if args.save_path and task_index == 0:
#     t9k.autotune.utils.save_best_n_models(model, args.save_path)

model.evaluate(test_images, test_labels, callbacks=test_callbacks, verbose=2)

if task_index > 0:
    # wait a while for index 0
    time.sleep(1)

在 Notebook 中创建文件 main.py，写入上述脚本并保存文件。

创建 download_dataset.py 文件，写入并执行以下脚本来下载实验数据。

import os
import tensorflow as tf

_, _ = tf.keras.datasets.mnist.load_data(os.path.join(os.getcwd(), 'mnist.npz'))

准备数据库

你可以使用实验管理平台（以下称 EM）记录超参数调优实验中的超参数组合和训练结果。（如果你选择不使用 EM 持久记录 AutoTune 实验结果，请忽略这一步，并在开始实验时删掉 AutoTuneExperiment 的 spec.aistore 字段）

在实验管理控制台中新建文件夹

EM 的实验数据是以文件夹形式管理的，所以你首先需要在实验管理控制台点击右上角的 + 新建一个文件夹。

进入文件夹，点击 ID 来复制该文件夹的 ID。

获得访问 EM 所需的 API Key

在超参数优化实验中，如果你希望使用 EM 来存储实验数据，需要生成一个具有访问 EM 文件夹权限的 API Key，你可以通过这个 API Key 上传实验数据。

你需要按照生成 API Key 教程中的步骤，在安全控制台中生成一个 API Key，其中必须勾选 AIStore 选项。

生成 API Key 之后，点击复制按钮复制该 API Key。

然后，你需要按照管理 Secret 教程中的步骤，在模型构建控制台中将所复制的 API Key 存入名为 aistore 的 Secret 中，以方便后续实验使用。

开始实验

在模型构建控制台的 AutoTune 列表页面，点击右上角的创建 AutoTuneExperiment 进入 AutoTuneExperiment 创建页面。

在 AutoTuneExperiment 创建页面，点击预览 YAML，输入以下配置，点击创建：

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
metadata:
  name: autotune-mnist-keras
spec:
  maxExecSeconds: 3600
  maxTrialNum: 20
  trialConcurrency: 3
  storage: 100Mi
  aistore:
    secret: 'aistore'
    folder: 'b6c17378-965c-4467-9a43-eed65597f976'
  searchSpace: |-
    {
      "batch_size": {"_type": "choice", "_value": [16, 32, 64, 128]},
      "learning_rate": {"_type": "choice", "_value": [0.0001, 0.001, 0.01, 0.1]},
      "conv_channels1": {"_type": "choice", "_value": [16, 32, 64, 128]}
    }
  trainingConfig:
    type: tensorflow
    tasks:
      - type: worker
        replicas: 4
        template:
          spec:
            securityContext:
              runAsUser: 1000
            containers:
              - command:
                  - sh
                  - -c
                  - "python3 main.py --log_dir /mnt/log --no_cuda"
                workingDir: /mnt/
                imagePullPolicy: IfNotPresent
                image: t9kpublic/tensorflow-2.5.1:20220216
                name: tensorflow
                resources:
                  requests:
                    cpu: 2000m
                    memory: 2Gi
                  limits:
                    cpu: 4000m
                    memory: 4Gi
                volumeMounts:
                  - mountPath: /mnt
                    name: data
            volumes:
              - name: data
                persistentVolumeClaim:
                  claimName: autotune-mnist-keras
  tuner:
    builtinTunerName: TPE
    classArgs: |-
      {
        "optimize_mode": "maximize", 
        "constant_liar_type": "min"
      }

在此例中，实验绑定了准备过程中创建的名为 autotune-mnist-keras 的 PVC，其中存有在 Notebook 中编辑的训练脚本；使用了名为 aistore 的存有 API Key 的 Secret；填入了前面创建的 EM Folder 的 ID。

查看实验

你可以在 AutoTune 列表页面看到已创建的 AutoTuneExperiment，点击连接进入实验详情页面。

下图为实验详情页面，你可以在该页面查看实验基本信息、各试验的参数与结果，以及查看试验之间的对比。

部署模型推理服务

这一部分演示如何使用平台的模型部署模块部署推理服务。

• 使用 SimpleMLService 部署 简单模型推理服务
• 使用 MLService 部署 模型推理服务
• 部署 包含 Transformer 的模型推理服务

简单推理服务

本教程演示如何使用 SimpleMLService 快速部署一个模型推理服务。

运行示例

请按照使用方法准备环境，然后前往本教程的示例，参照其 README 文档运行。本示例使用 PVC 中存储的模型创建了一个 SimpleMLService 服务。

查看推理服务状态

部署完成后，进入模型部署控制台的 SimpleMLService 页面，可以看到名为 mnist 的 SimpleMLService。

点击 SimpleMLService 的名称 mnist 可以看见 SimpleMLService 的基本信息，其中 URL 是在集群内访问这个推理服务的地址：

参考

• SimpleMLService 介绍
• API 参考：SimpleMLService

模型推理服务

本教程演示如何使用 MLService 部署一个功能完善、自动化程度高，可用于生产环境的模型推理服务。

运行示例

请按照使用方法准备环境，然后前往本教程的示例，参照其 README 文档运行。本示例使用 PVC 中存储的模型创建了一个 MLService 服务。

查看推理服务状态

部署完成后，进入模型部署控制台的 MLService 页面，可以看到名为 torch-mnist-pvc 的 MLService，稍等片刻，等其进入 Ready 状态：

使用推理服务

你可以直接使用命令行工具访问 MLService 的预测服务。运行命令获取 MLService 的 URL：

url=$(kubectl get mlservice torch-mnist-pvc -o jsonpath='{.status.address.url}') && echo $url

发送推理请求：

curl -T test_data/0.png ${url}/v1/models/mnist:predict # or use `1.png`, `2.png`

监控推理服务

在模型部署控制台，点击对应的 MLService，然后切换到资源监测页面，可以查看该 MLService 的资源统计：

参考

• MLService 介绍
• API 参考：MLService
• API 参考：MLServiceRuntime

包含 Transformer 的推理服务

本教程演示如何使用 TensorStack SDK 创建 Transformer 镜像，然后部署包含该 Transformer 的 MLService。

准备工作

请按照使用方法准备此次部署需要用到的 PVC 和 Notebook。

编写 Transformer 逻辑

接下来开始制作供 MLService 使用的 Transformer 镜像。首先进入 Notebook，启动一个终端，切换到对应目录：

cd ~/tutorial-examples/deployment/mlservice/transformer

查看文件 server.py ，内容如下：

import json
from t9k import mlservice

import argparse
import io
import numpy as np
from PIL import Image
from typing import Dict

# inherit parser to get command-line-args help
# feel free to add your command line args
par = argparse.ArgumentParser(parents=[mlservice.option.parser])
args, _ = par.parse_known_args()

def image_transform(instance):
    image = Image.open(io.BytesIO(instance))
    a = np.asarray(image)
    a = a / 255.0
    return a.reshape(28, 28, 1).tolist()

class_names = ['T-shirt/top', 'Trouser', 'Pullover', 'Dress', 'Coat',
               'Sandal', 'Shirt', 'Sneaker', 'Bag', 'Ankle boot']

def get_prediction(prediction: list)->str:
    max_value = max(prediction)
    max_index = prediction.index(max_value)
    return class_names[max_index]

class Transformer(mlservice.MLTransformer):
    def preProcess(self, path: str, requestData: bytes, headers: Dict[str, str]) -> any:
        return json.dumps({'instances': [image_transform(requestData)]})

    def postProcess(self, path: str, statusCode: int, responseContent: bytes, headers: Dict[str, str]) -> bytes:
        data = responseContent.decode('utf-8')
        jsonData = json.loads(data)
        jsonStr = json.dumps({'predictions': [get_prediction(predict) for predict in jsonData['predictions']]})
        return jsonStr.encode('utf-8')
    
if __name__ == "__main__":
    transformer = Transformer()
    server = mlservice.MLServer()
    server.start(transformer=transformer)

代码中使用了 TensorStack SDK，通过重载 preprocess 和 postprocess 方法实现了一个 Transformer：

• preprocess：预处理函数，Transformer 收到用户发送的数据，使用 preprocess 对数据进行处理，然后再发送给推理服务。在这个示例中，先转换输入图片的数据格式，需要保持与训练的模型的输入数据一致，然后再转换为推理服务的输入格式。
• postprocess：后处理函数，Transformer 收到推理服务返回的结果，使用 postprocess 对其进行处理，然后再返回给用户。在这个示例中，模型用于处理分类问题，从推理服务返回的预测概率向量中解析出该图片的分类类别，并返回给用户。

用户可以参考该文件来实现自定义的 Transformer 逻辑。

制作镜像

基于上述代码，我们创建对应的 Dockerfile 如下：

FROM python:3.8-slim

COPY t9k-sdk.tar.gz t9k-sdk.tar.gz
COPY server.py server.py

RUN pip install --upgrade pip
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple \
    numpy \
    pillow \
    requests
RUN pip install t9k-sdk.tar.gz  -i https://pypi.tuna.tsinghua.edu.cn/simple

ENTRYPOINT ["python", "server.py"]

上述 Dockerfile 引入了相关依赖，并将上一步的 server.py 文件作为启动命令。用户可以参考该文件来实现自定义的镜像。

然后我们通过运行一个 ImageBuilder 来制作镜像，为了使用 ImageBuilder，首先我们需要参照创建 Secret准备上传镜像所需要的 DockerConfig Secret。

完成后修改 imagebuilder.yaml 文件，将 spec.dockerConfig.secret 修改为上一步中创建的 DockerConfig Secret 的名称，并将 spec.tag 修改为目标镜像，并执行以下命令：

kubectl apply -f imagebuilder.yaml

查看 ImageBuilder 状态，等待 Phase 一栏变为 Succeeded：

kubectl get -f imagebuilder.yaml -w

部署 MLService

进入模型部署控制台，先点击左侧导航栏辅助一栏下的的 MLServiceRuntime，再点击 创建 MLServiceRuntime ，然后点击 预览 YAML， 并将下面内容复制到 YAML 编辑框中，最后点击 创建 创建 MLServiceRuntime。

apiVersion: tensorstack.dev/v1beta1
kind: MLServiceRuntime
metadata:
  name: t9k-tensorflow-serving
spec:
  enabled: true
  template:
    spec:
      containers:
      - name: user-container
        image: t9kpublic/tensorflow-serving:2.13.1
        command:
          - /usr/bin/tensorflow_model_server
        args:
          - --model_name={{if .MODEL_NAME}}{{.MODEL_NAME}}{{else}}model{{end}}
          - --port={{if .GRPC_PORT}}{{.GRPC_PORT}}{{else}}9000{{end}}
          - --rest_api_port=8000
          - --model_base_path=/var/lib/t9k/model
        resources:
          limits:
            cpu: "200m"
            memory: 200Mi
        ports:
        - containerPort: 8000
          protocol: TCP

进入模型部署控制台的 MLService 页面，点击右上角创建 MLService，然后点击预览 YAML。如下图所示，将下述内容复制到右侧的 YAML 编辑框，最后点击 创建 创建 MLService：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: pic-mnist
spec:
  default: origin
  transformer:
    minReplicas: 1
    template:
      spec:
        containers:
        - name: user-container
          image: "<your-docker-registry-address>/mnist-transformer:test"
  releases:
    - name: origin
      predictor:
        minReplicas: 1
        model:
          runtime: t9k-tensorflow-serving
          modelUri: pvc://tutorial/tutorial-examples/deployment/mlservice/transformer/model/

<<<<<<< HEAD 你可以直接使用命令行工具访问 MLService 的预测服务。运行命令获取 MLService 的 URL：

发送预测请求

使用图片 shoe.png 作为测试数据发送预测请求。 >>>>>>> parent of 816714b (Update mlservice (#51))

address=$(kubectl get mls pic-mnist -ojsonpath='{.status.address.url}') && echo $address
curl --data-binary @./shoe.png ${address}/v1/models/model:predict

参考

• MLService 介绍
• API 参考：MLService
• API 参考：MLServiceRuntime

管理 AI 资产

这一部分演示如何使用 AsestHub 上传、使用和分享模型和数据集。

• 操作文件夹、模型和数据集
• 通过 S3 访问模型和数据集
• 修改文件夹、模型和数据集的基本信息
• 操作模型和数据集的分支、tag 和 commit
• 操作模型和数据集的对象

操作文件夹、模型和数据集

本教程演示如何通过多种方式操作文件夹、模型和数据集，包括创建、查看和删除。

准备工作

• 安装 TensorStack SDK 并阅读用户指南。

通过命令行工具

切换到你的工作路径下：

$ cd /your/workpath

假设当前用户（这里假设用户名为 demo）没有可以访问的文件夹，使用 ah create 命令创建一个模型文件夹和一个数据集文件夹：

$ ah create model/llm
AH INFO: Folder /demo/t9k-assethub/model/llm created

$ ah create dataset/text
AH INFO: Folder /demo/t9k-assethub/dataset/text created

然后使用 ah create 命令在模型文件夹中创建一个模型，以及在数据集文件夹中创建一个数据集：

$ ah create model/llm/gpt2
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm

$ ah create dataset/text/openwebtext
AH INFO: Dataset openwebtext created for Folder /demo/t9k-assethub/dataset/text

创建完成之后，使用 ah ls 命令查看当前用户的模型文件夹和数据集文件夹：

$ ah ls model
NAME    PATH                          LABELS    PERMISSION
llm     /demo/t9k-assethub/model/llm             own

$ ah ls dataset
NAME    PATH                              LABELS    PERMISSION
text    /demo/t9k-assethub/dataset/text              own

使用 ah ls 命令查看模型文件夹下的所有模型以及数据集文件夹下的所有数据集：

$ ah ls model/llm
NAME    PATH                              LABELS    PERMISSION
gpt2    /demo/t9k-assethub/model/llm/gpt2            own

$ ah ls dataset/text
NAME         PATH                                        LABELS    PERMISSION
openwebtext  /demo/t9k-assethub/dataset/text/openwebtext            own

最后使用 ah delete 命令删除所有创建的模型、数据集和文件夹：

$ ah delete model/llm/gpt2
AH INFO: Model /demo/t9k-assethub/model/llm/gpt2 deleted

$ ah delete dataset/text/openwebtext
AH INFO: Dataset /demo/t9k-assethub/dataset/text/openwebtext deleted

# 可以直接删除文件夹, 其中的模型或数据集都会被一并删除
$ ah delete model/llm
AH INFO: Folder /demo/t9k-assethub/model/llm deleted

$ ah delete dataset/text
AH INFO: Folder /demo/t9k-assethub/dataset/text deleted

通过 Python SDK

切换到你的工作路径下，然后以任意方式执行下面的 Python 代码。

导入 t9k.ah 模块，使用 ah.login() 函数登录到 Asset Hub 服务器（如果配置文件中的凭据仍有效，则无需提供参数）：

from t9k import ah

ah.login(host='<asset-hub-server-url>',
         api_key='<your-api-key>')

AH INFO: Logged in to Asset Hub server and AIStore server as user <your-user-name>

假设当前用户（这里假设用户名为 demo）没有可以访问的文件夹，使用 ah.create() 函数创建一个模型文件夹和一个数据集文件夹，各返回一个 Folder 实例：

model_folder = ah.create('model/llm')
dataset_folder = ah.create('dataset/text')

AH INFO: Folder /demo/t9k-assethub/model/llm created
AH INFO: Folder /demo/t9k-assethub/dataset/text created

继续使用 ah.create() 函数在模型文件夹中创建一个模型，以及在数据集文件夹中创建一个数据集：

model = ah.create('model/llm/gpt2')
dataset = ah.create('dataset/text/openwebtext')

AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm
AH INFO: Dataset openwebtext created for Folder /demo/t9k-assethub/dataset/text

创建完成之后，使用 ah.list() 函数返回当前用户的文件夹：

from pprint import pprint

pprint(ah.list('model'))
pprint(ah.list('dataset'))

[{'description': '',
  'editor': 'demo',
  'extra': '{"createdTimestamp": "2023-08-17T08:05:24.044319Z"}',
  'id': '967a5135-8b13-4283-9fad-ba53503612b3',
  'labels': [],
  'modifiedTimestamp': '2023-08-17T08:05:24.390002Z',
  'name': 'llm',
  'path': '/demo/t9k-assethub/model/llm',
  'permission': 'own',
  'storageType': 0,
  'type': 'Folder'}]
[{'description': '',
  'editor': 'demo',
  'extra': '{"createdTimestamp": "2023-08-17T08:05:24.196610Z"}',
  'id': 'd0d9f4b2-6c15-4dbb-b2d1-0619b6774c4a',
  'labels': [],
  'modifiedTimestamp': '2023-08-17T08:05:24.519213Z',
  'name': 'text',
  'path': '/demo/t9k-assethub/dataset/text',
  'permission': 'own',
  'storageType': 0,
  'type': 'Folder'}]

继续使用 ah.list() 函数返回模型文件夹下的所有模型和数据集文件夹下的所有数据集：

pprint(ah.list('model/llm'))
pprint(ah.list('dataset/text'))

[{'description': '',
  'editor': 'demo',
  'extra': '{"createdTimestamp": "2023-08-17T08:11:09.948554Z"}',
  'id': '2157a139-e20b-4736-9e25-d4495e287af8',
  'labels': [],
  'modifiedTimestamp': '2023-08-17T08:11:10.327166Z',
  'name': 'gpt2',
  'path': '/demo/t9k-assethub/model/llm/gpt2',
  'permission': 'own',
  'storageType': 3,
  'type': 'Model'}]
[{'description': '',
  'editor': 'demo',
  'extra': '{"createdTimestamp": "2023-08-17T08:11:10.508407Z"}',
  'id': '6826131c-2c88-483e-8a48-0f6d8fa59cfa',
  'labels': [],
  'modifiedTimestamp': '2023-08-17T08:11:10.830665Z',
  'name': 'openwebtext',
  'path': '/demo/t9k-assethub/dataset/text/openwebtext',
  'permission': 'own',
  'storageType': 3,
  'type': 'Dataset'}]

最后使用 ah.delete() 函数删除所有创建的模型、数据集和文件夹：

ah.delete('model/llm/gpt2')
ah.delete('dataset/text/openwebtext')
ah.delete('model/llm')    # 可以直接删除文件夹, 其中的模型或数据集都会被一并删除
ah.delete('dataset/text')

AH INFO: Model /demo/t9k-assethub/model/llm/gpt2 deleted
AH INFO: Dataset /demo/t9k-assethub/dataset/text/openwebtext deleted
AH INFO: Folder /demo/t9k-assethub/model/llm deleted
AH INFO: Folder /demo/t9k-assethub/dataset/text deleted

通过控制台

数据集文件夹、数据集的控制台操作分别和模型文件夹、模型完全一致。本教程后续仅展示模型文件夹和模型的创建、查看、删除、分享功能，你可以用同样的方式操作数据集文件夹和数据集。

在左侧的导航菜单中点击模型，选择查看范围为 My Own，查看当前用户的所有模型文件夹。然后点击右上角的 + 创建新的模型文件夹：

填写名称 image-classification，点击创建：

接下来分享这个文件夹。点击文件夹右侧的 更多 > 分享：

点击添加分享目标，选择分享的对象为 Public（所有用户可见），分享的权限是 Edit，最后点击分享：

回到 Asset Hub 控制台，点击模型文件夹 image-classification 查看其中的模型：

新创建的模型文件夹中没有模型，点击右上角的 + 创建一个模型：

填写名称 mnist，然后点击创建：

创建成功后，在模型文件夹中可以看到模型信息：

点击更多 > 删除，删除创建的模型，然后点击左上角的返回，返回模型文件夹的页面：

最后，返回 Asset Hub 控制台，点击更多 > 删除，删除模型文件夹：

通过 S3 访问模型和数据集

本教程演示如何 S3 访问模型。

数据集同理。

准备工作

• 完成教程操作文件夹、模型和数据集。

创建 S3 凭证

在 AssetHub 控制台进入模型详情页面，点击 S3 凭证可以查看目前已有的所有 S3 凭证。然后点击表格右上角的 + 创建一个 S3 凭证：

填写名称 s3-rw，选择类型为可读/可写，最后点击创建：

查看 S3 凭证

创建完成后，点击表格左上角的可读/可写，查看所有类型为可读/可写的 S3 凭证：

点击刚刚创建的 S3 凭证 s3-rw，查看其详情：

S3 凭证有三种格式：

1. .s3cfg：命令行工具 s3cmd 的配置文件。
2. S3-cfg Secret：s3cfg 形式的 Secret YAML，创建后可在 Notebook、Job、Workflow 等工作负载时挂载此 Secret。
3. S3-env Secret：s3 环境变量形式的 Secret YAML，创建后可在 Notebook、Job、Workflow 等工作负载时挂载此 Secret。

通过 s3cmd 访问模型

点击右侧的复制，复制 .s3cfg 格式的 S3 凭证，保存在 $HOME/.s3cfg 文件中，即可通过 s3cmd 命令行工具访问此模型中的文件。

例如，在上述示例中，所创建的 S3 凭证 s3-rw 仅可用于访问名为 neox 的模型。根据页面上的提示，此模型对应的 bucket 名称为 adb2a768-f01a-467b-b146-e82c0693c16b，用户可以通过以下命令查看此模型的 main 分支的 README.md 文件：

s3cmd ls s3://baa98ded-2f93-4e9b-835a-6515a63a6eb4/main/README.md

通过以下命令下载此模型的某个分支下某个路径的文件：

s3cmd get s3://baa98ded-2f93-4e9b-835a-6515a63a6eb4/branch-name/path/to/object

通过 StorageShim 访问模型

除了通过命令行工具访问，用户还可以创建一个 StorageShim，将 S3 bucket 的某个子路径形式化为一个持久卷，以便在 Notebook、Job、Workflow 等工作负载中挂载，直接以文件系统的形式查看、编辑 S3 bucket 中的文件。

在创建 StorageShim 之前，用户首先需要创建一个 Secret 保存 S3 bucket 的相关信息。在 S3 凭证的详情页面，点击左侧的 S3-cfg Secret 标签，然后点击右上角的复制：

在模型构建控制台的左侧导航菜单中点击辅助 > Secret 进入 Secret 管理页面，然后点击右上角的创建 Secret进入 Secret 创建页面：

在 Secret 创建页面，点击预览 YAML，将所复制的 S3-cfg Secret 粘贴到 YAML 编辑框中，最后点击创建。

在模型构建控制台的左侧导航菜单中点击存储 > 持久卷进入持久卷管理页面，然后点击上方的 S3 进入 S3 类型的持久卷管理页面，最后点击右上角的创建进入 StorageShim 创建页面：

在 StorageShim 创建页面，

1. 名称填写 neox；
2. 类型选择 S3；
3. S3 URI 填写 s3://adb2a768-f01a-467b-b146-e82c0693c16b/main，以便把上述示例模型的 main 分支挂载为持久卷；
4. S3 Secret 选择刚刚创建的 s3-rw。

最后点击创建。

StorageShim 创建完成后，等待其阶段变为 Bound，用户即可通过以下方式使用这个名为 neox 的持久卷：

1. 点击启动，创建一个 Explorer 来浏览持久卷中的文件。
2. 在创建 Notebook 时，添加持久卷 neox，以便在 Notebook 中查看和编辑此模型中的文件。
3. 在创建 Job 时，添加持久卷 neox，以便在 Job 中使用此模型中的文件。

修改文件夹、模型和数据集的基本信息

本教程演示如何通过多种方式修改文件夹、模型和数据集的基本信息。

准备工作

• 完成教程操作文件夹、模型和数据集。

通过命令行工具

切换到你的工作路径下：

$ cd /your/workpath

修信息的方式对于文件夹、模型和数据集都是相同的。下面将以模型文件夹和模型为例进行演示（这里假设用户名为 demo）。

依次创建模型文件夹和模型：

$ ah create model/llm
AH INFO: Folder /demo/t9k-assethub/model/llm created

$ ah create model/llm/gpt2
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm

使用 ah update 命令修改文件夹和模型的名称：

$ ah update model/llm -n chat
AH INFO: Folder /demo/t9k-assethub/model/llm updated to /demo/t9k-assethub/model/chat

$ ah update model/chat/gpt2 -n gpt3
AH INFO: Model /demo/t9k-assethub/model/chat/gpt2 updated to /demo/t9k-assethub/model/chat/gpt3

使用 ah ls 命令查看文件夹和模型的标签：

$ ah ls model --detail
NAME    PATH                          ...  LABELS  ...
chat    /demo/t9k-assethub/model/chat

$ ah ls model/chat
NAME    PATH                               LABELS  ...
gpt3    /demo/t9k-assethub/model/chat/gpt3

两者都没有标签，再次使用 ah update 命令为它们添加标签：

$ ah update model/chat --label "NLP" --label "AIGC"
AH INFO: Folder /demo/t9k-assethub/model/chat updated

$ ah ls model --detail
NAME    PATH                          ...  LABELS     ...
chat    /demo/t9k-assethub/model/chat       AIGC, NLP

$ ah update model/chat/gpt3 --label "GPT"
AH INFO: Model /demo/t9k-assethub/model/chat/gpt3 updated

$ ah ls model/chat
NAME    PATH                               LABELS    PERMISSION
gpt3    /demo/t9k-assethub/model/chat/gpt3  GPT       own

通过 Python SDK

切换到你的工作路径下，然后以任意方式执行下面的 Python 代码。

导入 t9k.ah 模块，使用 ah.login() 函数登录到 AssetHub 服务器（如果配置文件中的凭据仍有效，则无需提供参数）：

from t9k import ah

ah.login(host='<asset-hub-server-url>',
         api_key='<your-api-key>')

AH INFO: Logged in to Asset Hub server and AIStore server as user <your-user-name>

修改信息的方式对于文件夹、模型和数据集都是相同的。下面将以模型文件夹和模型为例进行演示（这里假设用户名为 demo）。

依次创建模型文件夹和模型：

model_folder = ah.create('model/llm')
model = ah.create('model/llm/gpt2')

AH INFO: Folder /demo/t9k-assethub/model/llm created
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm

使用 ah.update() 函数修改文件夹和模型的名称：

ah.update('model/llm', name='chat')
ah.update('model/chat/gpt2', name='gpt3')

AH INFO: Folder /demo/t9k-assethub/model/llm updated to /demo/t9k-assethub/model/chat
AH INFO: Model /demo/t9k-assethub/model/chat/gpt2 updated to /demo/t9k-assethub/model/chat/gpt3

使用 ah.list() 函数查看文件夹和模型的标签：

from pprint import pprint

pprint(ah.list('model'))
pprint(ah.list('model/chat'))

[{...
  'labels': [],
  'name': 'chat',
  'path': '/demo/t9k-assethub/model/chat',
  'type': 'Folder'}]
[{...
  'labels': [],
  'name': 'gpt3',
  'path': '/demo/t9k-assethub/model/chat/gpt3',
  'type': 'Model'}]

两者都没有标签，继续使用 ah.update() 函数为它们添加标签：

ah.update('model/chat', labels=['NLP', 'AIGC'])
ah.update('model/chat/gpt3', labels=['GPT'])

AH INFO: Folder /demo/t9k-assethub/model/chat updated
AH INFO: Model /demo/t9k-assethub/model/chat/gpt3 updated

pprint(ah.list('model'))
pprint(ah.list('model/chat'))

[{...
  'labels': ['AIGC', 'NLP'],
  'name': 'chat',
  'path': '/demo/t9k-assethub/model/chat',
  'type': 'Folder'}]
[{...
  'labels': ['GPT'],
  'name': 'gpt3',
  'path': '/demo/t9k-assethub/model/chat/gpt3',
  'type': 'Model'}]

通过控制台

数据集文件夹、数据集的控制台操作分别和模型文件夹、模型完全一致。本教程后续仅展示如何修改模型文件夹和模型的基本信息，你可以用同样的方式操作数据集文件夹和数据集。

在进行教程之前，先按照操作文件夹、模型和数据集一节完成模型文件夹和模型的创建（chat/gpt2）。

在模型文件夹列表中，选中需要修改的模型文件夹，点击更多 > 编辑：

填写新的名称和描述信息，添加新标签，点击更新按钮：

回到文件夹列表，可以看到文件夹信息发生改变：

点击文件夹名称，进入模型列表，选中需要修改的模型，点击更多 > 编辑：

填写新的名称和描述信息，添加新标签，点击更新按钮：

回到模型列表，可以看到模型信息发生改变：

操作模型和数据集的分支、tag 和 commit

本教程演示如何通过多种方式操作模型的分支、tag 和 commit，包括创建、查看和删除分支，创建、查看和删除 tag，以及查看 commit。

数据集同理。

准备工作

• 完成教程操作文件夹、模型和数据集。

通过命令行工具

切换到你的工作路径下：

$ cd /your/workpath

操作 tag 和 commit 的方式对于模型和数据集都是相同的，只有模型允许操作分支。下面将以模型为例进行演示（这里假设用户名为 demo）。

依次创建模型文件夹和模型：

$ ah create model/llm
AH INFO: Folder /demo/t9k-assethub/model/llm created

$ ah create model/llm/gpt2
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm

继续使用 ah create 命令为模型创建一个分支：

$ ah create model/llm/gpt2:v1
AH INFO: Branch v1 created for Model /demo/t9k-assethub/model/llm/gpt2

使用 ah ls --branch 命令查看模型的所有分支：

$ ah ls model/llm/gpt2 --branch
NAME    COMMIT_ID
main    fe46da7e
v1      fe46da7e

继续使用 ah create 命令为模型创建一个 tag：

$ ah create model/llm/gpt2:20230101 --tag --source v1
AH INFO: Tag 20230101 created from branch v1 for Model /demo/t9k-assethub/model/llm/gpt2

使用 ah ls --tag 命令查看模型的所有 tag：

$ ah ls model/llm/gpt2 --tag
    NAME  COMMIT_ID
20230101  fe46da7e

使用 ah ls --commit 命令查看模型的一个分支下的所有 commit：

$ ah ls model/llm/gpt2:v1 --commit
COMMIT_ID    MESSAGE             CREATED
fe46da7e     Repository created  3m16s ago

最后使用 ah delete 命令删除所有创建的分支和 tag：

$ ah delete model/llm/gpt2:v1
AH INFO: Branch v1 deleted for Model /demo/t9k-assethub/model/llm/gpt2

$ ah delete model/llm/gpt2:20230101
AH INFO: Tag 20230101 deleted for Model /demo/t9k-assethub/model/llm/gpt2

通过 Python SDK

切换到你的工作路径下，然后以任意方式执行下面的 Python 代码。

导入 t9k.ah 模块，使用 ah.login() 函数登录到 AssetHub 服务器（如果配置文件中的凭据仍有效，则无需提供参数）：

from t9k import ah

ah.login(host='<asset-hub-server-url>',
         api_key='<your-api-key>')

AH INFO: Logged in to Asset Hub server and AIStore server as user <your-user-name>

操作 tag 和 commit 的方式对于模型和数据集都是相同的，只有模型允许操作分支。下面将以模型为例进行演示（这里假设用户名为 demo）。

依次创建模型文件夹和模型：

model_folder = ah.create('model/llm')
model = ah.create('model/llm/gpt2')

AH INFO: Folder /demo/t9k-assethub/model/llm created
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm

继续使用 ah.create() 函数为模型创建一个分支：

branch = ah.create('model/llm/gpt2:v1')

AH INFO: Branch v1 created for Model /demo/t9k-assethub/model/llm/gpt2

使用 ah.list() 函数查看模型的所有分支：

from pprint import pprint

pprint(ah.list('model/llm/gpt2', resource='branch'))

[{'commit_id': 'a15799f8f601d514a1a385a57b3078f8e178614a66aa920217175f6dcac2b083',
  'id': 'main'},
 {'commit_id': 'a15799f8f601d514a1a385a57b3078f8e178614a66aa920217175f6dcac2b083',
  'id': 'v1'}]

继续使用 ah.create() 函数为模型创建一个 tag：

tag = ah.create('model/llm/gpt2:20230101', create_tag=True, source='v1')

AH INFO: Tag 20230101 created from branch v1 for Model /demo/t9k-assethub/model/llm/gpt2

使用 ah.list() 函数查看模型的所有 tag：

pprint(ah.list('model/llm/gpt2', resource='tag'))

[{'commit_id': 'a15799f8f601d514a1a385a57b3078f8e178614a66aa920217175f6dcac2b083',
  'id': '20230101'}]

最后使用 ah.delete() 函数删除所有创建的分支和 tag：

ah.delete('model/llm/gpt2:v1')
ah.delete('model/llm/gpt2:20230101')

AH INFO: Branch v1 deleted for Model /demo/t9k-assethub/model/llm/gpt2
AH INFO: Tag 20230101 deleted for Model /demo/t9k-assethub/model/llm/gpt2

操作模型和数据集的对象

本教程演示如何通过多种方式操作模型的对象，包括修改、查看和下载 AssetHub 中存储的对象文件。

数据集同理。

准备工作

• 完成教程操作模型/数据集的分支、tag 和 commit。

通过命令行工具

切换到你的工作路径下：

$ cd /your/workpath

操作对象的方式对于模型和数据集都是相同的，除了数据集只允许操作主分支（main 分支）中的对象。下面将以模型为例进行演示（这里假设用户名为 demo）。

依次创建模型文件夹、模型和分支：

$ ah create model/llm
AH INFO: Folder /demo/t9k-assethub/model/llm created

$ ah create model/llm/gpt2
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm

$ ah create model/llm/gpt2:v1
AH INFO: Branch v1 created for Model /demo/t9k-assethub/model/llm/gpt2

使用 ah commit 命令向该分支上传本地文件（这里以 model_state_dict.pt 和 README.md 为例）作为对象存储：

$ ah commit model/llm/gpt2:v1 --message "Add model file" --add model_state_dict.pt --add README.md
AH INFO: Committing changes to branch /demo/t9k-assethub/model/llm/gpt2:v1
AH INFO: Uploading object 1/2 model_state_dict.pt:
         Done        
AH INFO: Uploading object 2/2 README.md:
         Done        
AH INFO: Commit 29d6f29e created

使用 ah ls 命令查看分支的所有对象：

$ ah ls model/llm/gpt2:v1
PATH                   BYTES  CHECKSUM                          MODIFIED
README.md               110B  d1f0e72bd20091c3869cefff8c72661b  1m29s ago
model_state_dict.pt  375943B  1203ee282c235c9fb4c2ea932a7b7cc8  1m29s ago

再次使用 ah commit 命令，当重复上传文件到同一路径时，原有的对象会被替换：

$ ah commit model/llm/gpt2:v1 --message "Update README" --add README.md
AH INFO: Committing changes to branch /demo/t9k-assethub/model/llm/gpt2:v1
AH INFO: Uploading object 1/1 README.md:
         Done        
AH INFO: New commit 53097cba created

$ ah ls model/llm/gpt2:v1
PATH                   BYTES  CHECKSUM                          MODIFIED
README.md               221B  84c44f1510389ea7de91e550be8a7130  15s ago
model_state_dict.pt  375943B  1203ee282c235c9fb4c2ea932a7b7cc8  5m37s ago

使用 -d PATH 选项以删除指定路径的对象：

$ ah commit model/llm/gpt2:v1 --message "Remove README" --delete README.md
AH INFO: Committing changes to branch /demo/t9k-assethub/model/llm/gpt2:v1
AH INFO: Deleting object README.md:
         Done
AH INFO: Commit cf8dcc26 created

$ ah ls model/llm/gpt2:v1
PATH                   BYTES  CHECKSUM                          MODIFIED
model_state_dict.pt  375943B  1203ee282c235c9fb4c2ea932a7b7cc8  6m2s ago

每次使用 ah commit 命令修改分支（添加、覆盖或删除对象）时，分支都会创建一个新的 commit。使用 ah ls commit 命令查看上面的操作所创建的 3 个 commit：

$ ah ls model/llm/gpt2:v1 --commit
COMMIT_ID     MESSAGE               CREATED
cf8dcc26      Remove README         5m47s ago
53097cba      Update README         21m46s ago
29d6f29e      Add model file        33m8s ago
c4bebb3a      Repository created    33m18s ago   # 初始 commit

之后想要使用这些对象时，使用 ah download 命令下载对象保存为本地文件：

$ ah download model/llm/gpt2:v1
AH INFO: Downloading object 1/1 model_state_dict.pt:
         ━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 375.9/375.9 kB • 2.6 MB/s • 0:00:00

$ ls
model_state_dict.pt ...

通过 Python SDK

切换到你的工作路径下，然后以任意方式执行下面的 Python 代码。

导入 t9k.ah 模块，使用 ah.login() 函数登录到 Asset Hub 服务器（如果配置文件中的凭据仍有效，则无需提供参数）：

from t9k import ah

ah.login(host='<asset-hub-server-url>',
         api_key='<your-api-key>')

AH INFO: Logged in to Asset Hub server and AIStore server as user <your-user-name>

操作对象的方式对于模型和数据集都是相同的，除了数据集只允许操作主分支（main 分支）中的对象。下面将以模型为例进行演示（这里以 user 表示当前用户）。

依次创建模型文件夹、模型和分支：

model_folder = ah.create('model/llm')
model = ah.create('model/llm/gpt2')
branch = ah.create('model/llm/gpt2:v1')

AH INFO: Folder /demo/t9k-assethub/model/llm created
AH INFO: Model gpt2 created for Folder /demo/t9k-assethub/model/llm
AH INFO: Branch v1 created for Model /demo/t9k-assethub/model/llm/gpt2

使用 ah.commit() 函数向该分支上传本地文件作为对象存储：

commit1 = ah.commit('model/llm/gpt2:v1',
                    msg='Add model file',
                    add=['model_state_dict.pt', 'README.md'])

AH INFO: Committing changes to branch /demo/t9k-assethub/model/llm/gpt2:v1
AH INFO: Uploading object model_state_dict.pt:
         Done        
AH INFO: Uploading object README.md:
         Done        
AH INFO: Commit 6a57546b created

使用 ah.list() 函数查看分支的所有对象：

from pprint import pprint

pprint(ah.list('model/llm/gpt2:v1'))

[{'checksum': 'f0db68fc4327c528b3a23fdc47c30c9e',
  'content_type': 'application/octet-stream',
  'mtime': 1683881423,
  'path': 'README.md',
  'path_type': 'object',
  'physical_address': 's3://t9k-aistore/d3a98ad0-50ca-42df-becf-8bbf4351d2c9/data/gnoggd0i2hci2stu7uhg/chevrjoi2hci2stu7un0',
  'size_bytes': 110},
 {'checksum': '1203ee282c235c9fb4c2ea932a7b7cc8',
  'content_type': 'application/octet-stream',
  'mtime': 1683881423,
  'path': 'model_state_dict.pt',
  'path_type': 'object',
  'physical_address': 's3://t9k-aistore/d3a98ad0-50ca-42df-becf-8bbf4351d2c9/data/gnoggd0i2hci2stu7uhg/chevrjgi2hci2stu7umg',
  'size_bytes': 375943}]

再次使用 ah.commit() 函数，当重复上传文件到同一路径时，原有的对象会被替换：

commit2 = ah.commit('model/llm/gpt2:v1', msg='Update README', add=['README.md'])

pprint(ah.list('model/llm/gpt2:v1'))

AH INFO: Committing changes to branch /demo/t9k-assethub/model/llm/gpt2:v1
AH INFO: Uploading object README.md:
         Done        
AH INFO: Commit 8183e1df created
[{'checksum': '1cbd5021ee923905bbdc29883c50a1b0',
  'content_type': 'application/octet-stream',
  'mtime': 1683881478,
  'path': 'README.md',
  'path_type': 'object',
  'physical_address': 's3://t9k-aistore/d3a98ad0-50ca-42df-becf-8bbf4351d2c9/data/gnoggd0i2hci2stu7uhg/chevs1gi2hci2stu7uog',
  'size_bytes': 221},
 {'checksum': '1203ee282c235c9fb4c2ea932a7b7cc8',
  'content_type': 'application/octet-stream',
  'mtime': 1683881423,
  'path': 'model_state_dict.pt',
  'path_type': 'object',
  'physical_address': 's3://t9k-aistore/d3a98ad0-50ca-42df-becf-8bbf4351d2c9/data/gnoggd0i2hci2stu7uhg/chevrjgi2hci2stu7umg',
  'size_bytes': 375943}]

使用 delete 选项以删除指定路径的对象：

commit3 = ah.commit('model/llm/gpt2:v1', msg='Remove README', delete=['README.md'])

pprint(branch.list_object())

AH INFO: Committing changes to branch /demo/t9k-assethub/model/llm/gpt2:v1
AH INFO: Deleting object README.md:
         Done
AH INFO: Commit 00af1151 created
[{'checksum': '1203ee282c235c9fb4c2ea932a7b7cc8',
  'content_type': 'application/octet-stream',
  'mtime': 1683881423,
  'path': 'model_state_dict.pt',
  'path_type': 'object',
  'physical_address': 's3://t9k-aistore/d3a98ad0-50ca-42df-becf-8bbf4351d2c9/data/gnoggd0i2hci2stu7uhg/chevrjgi2hci2stu7umg',
  'size_bytes': 375943}]

每次使用 ah.commit() 函数修改分支（添加、覆盖或删除对象）时，分支都会创建一个新的 commit。继续使用 ah.list() 函数查看上面的操作所创建的 3 个 commit：

pprint(ah.list('model/llm/gpt2:v1', resource='commit'))

[{'committer': 'admin',
  'creation_date': 1683881538,
  'id': '00af1151865121a79233af326b21864f2f6dbcc3b5bebb2f8768e2b13154f754',
  'message': 'Remove README',             # commit3
  'meta_range_id': 'c959b9ce4301591b82517c97ca277b034fd4a4d181b63db7571a2a8174844848',
  'metadata': {},
  'parents': ['8183e1dfb0dcded478aff1b5cb2975ae22e83ca4f37333fb904e5bcd27897923']},
 {'committer': 'admin',
  'creation_date': 1683881479,
  'id': '8183e1dfb0dcded478aff1b5cb2975ae22e83ca4f37333fb904e5bcd27897923',
  'message': 'Update README',             # commit2
  'meta_range_id': '2184d241abdc0ce3e26db44ad2c1df3e1e6a7a6b231fa1f17db7684982a55243',
  'metadata': {},
  'parents': ['6a57546b1275ba6b7f1399e0f7213552ac7bdf545de8692e494db47b93623b9d']},
 {'committer': 'admin',
  'creation_date': 1683881423,
  'id': '6a57546b1275ba6b7f1399e0f7213552ac7bdf545de8692e494db47b93623b9d',
  'message': 'Add model file',            # commit1
  'meta_range_id': '0b8943e0b3b4a3b8661f6146f47f85562aea5c7eb88bc2c66f2adf7443a08451',
  'metadata': {},
  'parents': ['610af4d2991e5c9b9d527dedf34db3cd11c8bd5bb7cc0e8ed0b97505319f8f11']},
 {'committer': '',
  'creation_date': 1683881388,
  'id': '610af4d2991e5c9b9d527dedf34db3cd11c8bd5bb7cc0e8ed0b97505319f8f11',
  'message': 'Repository created',        # 初始 commit
  'meta_range_id': '',
  'metadata': {},
  'parents': []}]

之后想要使用这些对象时，使用 ah.download() 函数下载对象保存为本地文件：

ah.download('model/llm/gpt2:v1')

import os
print(os.listdir())

AH INFO: Downloading object 1/1 model_state_dict.pt:
         ━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 375.9/375.9 kB • 2.6 MB/s • 0:00:00
['model_state_dict.pt', ...]

通过控制台

数据集的控制台操作和模型完全一致。本教程后续仅展示模型对象的上传和下载，你可以用同样的方式操作数据集。

在进行教程之前，先按照操作文件夹、模型和数据集一节完成模型文件夹和模型的创建（chat/gpt3）。

进入模型详情页后，点击所有文件 > 上传图标：

点击选择文件选择所要上传的文件，填写描述信息，然后点击提交：

完成提交后，可以在所有文件中看到刚刚上传的文件，点击下载图标下载该文件：

点击介绍 > 添加介绍：