概述

目标读者

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

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

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

产品概述

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

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

产品提供了全面的可扩展性：用户可方便的安装各种 Apps 以满足具体应用场景的需求；管理员可以在线安装各种 APIs 以支持系统服务能力扩展；集群规模上，支持在 1～10^3 节点部署。

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

User Console

“User Console（用户控制台）” 是 TensorStack AI 计算平台的用户交互界面，它为 AI 集群使用者提供了一个集中使用集群功能的图形化环境。

Apps

用户可在 User Console 中方便的安装和使用各种 Apps（应用），是用户使用平台功能的入口。无论是进行 AI 研究、开发还是部署，用户都是通过安装和使用相应的 App 来完成。例如：

• AI 研究员可能通过 JupyterLab App 作为其日常开发环境，使用 Job Manager App 运行和管理并行训练任务。
• AI 应用工程师可能使用 vLLM App 或 Stable Diffusion WebUI App 来部署和测试 AI 模型。

APIs

APIs 提供集群系统服务，用户可以通过 User Console 直接或间接使用。它们或为 Apps 提供必要的支持：

• 存储如持久卷（PV + PVC） 和适配器（StorageShim）为 Apps 持久化保存数据，存储模型、数据集和训练日志文件等。
• 网络服务如 Service 和 Ingress 为 Apps 提供内部通信和外部访问的能力，使得 Apps 能够相互协作并对外提供服务。
• 辅助资源如 Secret 和 ConfigMap 为 Apps 提供配置管理和敏感信息保护，确保 Apps 能够安全且灵活地运行。

或作为工作负载执行某项特定计算：

• Job 如 PyTorchTrainingJob 和 DeepSpeedJob 运行以 AI 模型训练为主的批处理计算任务。
• 推理服务如 MLService 和 SimpleMLService 部署 AI 模型为推理服务。
• 工作流 APIs 将多个平台操作步骤组合为一个工作流，进行集中管理和运行
• AutoTuneExperiment 进行 AI 模型训练的自动超参数调优。

除此之外，User Console 还提供了账户设置功能，帮助用户管理账户的项目和 API Key，接受账单和来自平台的告警信息。

下一步

• 跟随 快速开始 的内容，快速上手平台的基本使用
• 阅读 Apps 和 APIs 章节，了解平台提供的各种 App 和 API
• 参照 操作指南 的教程，执行更多具体的操作，完成更加复杂的任务

快速入门

欢迎使用“TensorStack AI 平台”！

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

User Console 是用户的功能入口，基本使用流程如下：

1. 获得账号，登录系统；
2. 安装各种 Apps，例如 Jupyter Notebook，Job Manager，TensorBoard，Ollama；
3. 使用多个 Apps 互相协同，调用 APIs，完成各项工作；
4. 卸载不再使用的 Apps，释放计算资源。

下一步

• 训练你的第一个模型

训练你的第一个模型

本教程带领你构建和训练一个最简单的 AI 模型。

本教程是一个小规模的训练，通过 JupyterLab App 即可完成，主要步骤如下：

1. 通过创建 PVC 申请集群存储空间，用于保存训练脚本、数据、及模型等；
2. 安装 JupyterLab App，使用其作为 IDE；
3. 在 JupyterLab 中创建训练脚本，并运行这个训练。

创建 PVC

首先需要创建一个用于存储文件的 PVC。进入 User Console，在左侧导航菜单点击存储 > 存储卷进入 PVC 管理页面，然后点击右上角的创建 PVC：

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

• 名称填写 mnist。
• 存储填写 1Gi。

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

在跳转回到 PVC 管理页面之后，等待 PVC 的状态变为 （这里打开了右上角的自动刷新开关，否则需要点击旁边的刷新图标来手动刷新 PVC 状态）：

安装 JupyterLab (CPU) App

在左侧导航菜单点击应用进入 App 管理页面，然后点击右上角的安装：

在应用目录中找到 JupyterLab (CPU)，点击其卡片，再点击右上角的立刻安装：

在安装页面，通过表单填写配置，填写 pvc 字段的值为 mnist，其他字段保持默认即可。完成之后，点击右上角的安装：

在跳转回到 App 管理页面之后，等待刚才安装的 JupyterLab (CPU) App 准备就绪。第一次拉取镜像可能会花费较长的时间，具体取决于集群的网络状况。待 App 就绪后，点击右侧的 进入网页 UI：

接下来在这里进行模型的构建和训练：

构建和训练模型

点击左上角的 +，然后点击 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 进行并行训练

进行并行训练

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

准备并行训练

回到 JupyterLab (CPU) App 的网页 UI，在 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.module.state_dict(), args.save_path)

创建 Job 进行并行训练

安装一个 Job Manager App，操作步骤参照安装 JupyterLab (CPU) App，使用默认配置即可（无需修改任何字段）。

进入 Job Manager 的网页 UI（控制台），在左侧导航菜单点击 Job 进入 Job 管理页面，然后点击右上角的创建 > PyTorch：

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

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: mnist                    # Job 名称
spec:
  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 及其创建的 1 个副本（Pod）正在运行。

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

一段时间之后，Job 的状态变为 Succeeded，表示训练已经成功完成。回到 JupyterLab (CPU) App 的网页 UI，将当前教程产生的所有文件移动到名为 parallel-training 的新文件夹下。

下一步

• 将训练完成的模型部署为推理服务
• 了解 Job
• 进一步学习如何训练模型

部署模型

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

教程训练你的第一个模型和进行并行训练训练了相同架构的模型，并且都将模型参数保存为文件 model_state_dict.pt。本教程将这两个模型文件中的任意一个部署为推理服务。

准备模型文件

这里我们使用 TorchServe 部署 PyTorch 模型。回到 JupyterLab (CPU) App 的网页 UI，在 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）：

# 使用 JupyterLab (CPU) App 中训练的模型
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

部署推理服务

安装一个 Service Manager App，同样地，操作步骤参照安装 JupyterLab (CPU) App，使用默认配置即可（无需修改任何字段）。

进入 Service Manager 的网页 UI（控制台），在左侧导航菜单点击部署 > SimpleMLService，点击右上角的 + 弹出创建对话框，然后复制下面的 YAML 配置文件并粘贴到编辑框中，完成后点击创建。

apiVersion: tensorstack.dev/v1beta1
kind: SimpleMLService
metadata:
  name: mnist
spec:
  replicas: 1
  storage:
    pvc:
      mountPath: /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 就绪之后，点击其名称进入详情页面。

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

访问推理服务

回到 JupyterLab (CPU) App 的网页 UI，在终端中执行以下命令以下载测试数据，并向推理服务发送请求。注意将 <URL> 替换为推理服务地址。

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

ENDPOINT="http://<URL>/v1/models/mnist:predict"
curl -T 0.png $ENDPOINT    # 或使用 `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 的新文件夹下。

下一步

• 了解 T9k Service
• 进一步学习如何部署模型推理服务

Apps

概念

Apps（应用）是 TensorStack AI 平台在用户 “应用场景” 的扩展机制，用于支持多样性的应用场景及个人偏好，类似于智能手机上的 “应用商店” 机制。

这里的 Apps 既包括由 AI 模型驱动的应用程序，例如 vLLM、Open WebUI、Stable Diffusion WebUI，也包含在 AI 研究、开发过程中可能使用到的软件、工具，例如 JupyterLab、TensorBoard、Dify。利用这些 Apps，用户能够高效地完成模型开发、训练和部署，AI 应用构建和部署等任务，全面开展与 AI 有关的工作。

用户在完成某一项任务时可以根据任务的性质和自身的偏好，灵活地安装和使用多个 Apps，并且这些 Apps 可以通过共享存储、API 调用等方式进行协作，如下图所示：

例如：

1）在任务 进行数据并行训练 中：

• 用户在 JupyterLab App 中进行交互式开发。
• 用户在 Job Manager App 中查看运行的 PyTorchTrainingJob。
• JupyterLab、PyTorchTrainingJob 和 TensorBoard App 挂载同一个 PVC，通过文件系统共享数据：
  • 用户在 JupyterLab 中拉取的训练代码可以被 PyTorchTrainingJob 执行。
  • PyTorchTrainingJob 中产生的 tfevents 日志文件可以被 TensorBoard 所读取并可视化展示。

2）在任务 部署 LLM 推理服务和聊天服务 中：

• JupyterLab App 和 vLLM App 共享存储，在 JupyterLab 中下载的模型文件可以被 vLLM 所加载。
• NextChat 调用 vLLM 的 LLM 推理服务 API。
• 用户通过 NextChat 提供的简洁美观的 UI 中与 vLLM 部署的 LLM 聊天。

Apps 目录

在 User Console 中，用户可以方便的查看可安装的 Apps，并根据需求，随时安装、卸载各种 Apps。

Apps 列表

这里给出可用（需要管理员注册）的 Apps 的列表，最新及完整的 Apps 支持列表请参看 GitHub。

下列部分 Apps 提供了链接指向更详细的文档。

下一步

• 进一步了解各个 App
• 了解如何 管理 App
• 查看支持的 App 列表： https://github.com/t9k/apps/tree/master/user-console

JupyterLab

JupyterLab 是一个强大的交互式开发环境，为数据分析和科学计算提供了一站式解决方案。它集成了代码编辑、执行、可视化和文档编写等功能，使用户能够高效地进行数据探索和模型开发。JupyterLab 支持多种编程语言，如 Python、R 和 Julia，用户可以在同一个界面中无缝切换不同的语言环境。JupyterLab 在机器学习、深度学习、数据处理、数值模拟、统计建模、数据可视化等领域被广泛使用。

在日常使用中，JupyterLab 的笔记本功能尤为实用。用户可以将代码、运行结果、数据可视化和富文本说明组合在一起，形成一个完整的分析流程。这不仅有助于记录思路和实验过程，还便于与他人分享和协作。此外，JupyterLab 的文件管理系统允许用户直接在界面中组织和访问项目文件，提高了工作效率。

JupyterLab Apps 是一个系列，包括 JupyterLab (CPU)、JupyterLab (NVIDIA GPU)、JupyterLab (Enflame GCU) 和 JupyterLab (Hygon DCU)，它们之间的区别仅在于支持不同的加速设备：

• 所有 App 均支持 CPU。
• JupyterLab (NVIDIA GPU) 另外支持 NVIDIA GPU。
• JupyterLab (Enflame GCU) 另外支持燧原 GCU。
• JupyterLab (Hygon DCU) 另外支持海光 DCU。

请根据集群的可用资源和自身的需求选择合适的 App。

本手册的其他文档中提及的“JupyterLab App”指代 JupyterLab Apps 中的任意一个。

使用方法

通过网页 UI 使用

待 App 就绪后，点击右侧的 进入网页 UI，即可进行开发工作。

网页 UI 的使用方法请参阅 JupyterLab Documentation 或它的中文版本。TensorBoard 插件的使用方法请参阅使用说明。

通过 SSH 远程连接

除了网页 UI，App 还支持通过 SSH 远程连接（需要启用 SSH 服务），让你能够使用熟悉的本地终端或 IDE，像在本地开发一样进行远程开发。限于篇幅，具体步骤请参阅如何通过 SSH 远程连接。

配置和使用说明

镜像

JupyterLab Apps 系列的每个 App 分别可以选用的镜像请参阅相应 README 的镜像列表部分。

每个镜像都包含 JupyterLab 和特定的环境（机器学习框架或 conda 环境），预装了一些 Python 包、命令行工具和平台工具，并且创建并使用一个新的用户：

• 每个镜像预装的 Python 包各不相同，请执行 pip list 命令以查看。
• 所有镜像均预装了以下命令行工具：

• 所有镜像均预装了最新版本的平台工具。
• 所有镜像均创建 GID 为 1000、名称为 t9kuser 的用户组，以及属于该用户组、UID 为 1000、名称为 t9kuser、HOME 目录为 /t9k/mnt 的用户，并使用该用户。

挂载 PVC

必须为 App（的容器）挂载一个 PVC 作为工作空间。下面的配置示例挂载 PVC demo 作为工作空间：

pvc: "demo"

...

PVC 的挂载路径为 /t9k/mnt，即镜像使用的 t9kuser 用户的 HOME 目录。

挂载的 PVC 负责存储开发相关的文件，这些文件可以是通过 JupyterLab 的 UI 上传或创建的，也可以是通过 JupyterLab 的终端从网络下载或运行程序产生的。此外，挂载的 PVC 还负责存储 conda 环境和 conda 包的文件（位于 /t9k/mnt/.conda 路径下），以及 Python 包的文件（位于 /t9k/mnt/.local/lib/python3.10 路径下）。如果你需要安装较多、较大的 conda 包或 Python 包，请确保挂载的 PVC 留有足够的存储空间。

T9k Job、T9k Service 等工作负载可以和 App 挂载同一个 PVC 以共享存储。例如创建一个 PyTorchTrainingJob，其利用通过 JupyterLab 准备好的训练脚本和数据集文件以启动训练；或者创建一个 SimpleMLService，其读取下载好的模型文件以启动推理服务。

用户权限

在 App 的容器环境中，用户的 UID:GID 为 1000:1000，这会导致系统级操作受到限制（权限不足）。例如，用户无法使用 apt install 命令安装开发所需的库，无法执行 rm 命令删除没有写权限的文件（这些文件可能是由挂载了同一个 PVC 且使用 root 用户的 Job 产生的）。

在某些情况下，进行系统级操作是必要或便利的，解决方案是为 App 选用标签带有 -sudo 后缀的镜像，在需要提升权限的命令前加上 sudo，以 root 身份执行该命令。

TensorBoard 插件

所有镜像还预装了 JupyterLab 的 TensorBoard 插件 jupyterlab_tensorboard_pro，其将 TensorBoard 集成到 JupyterLab 环境中，使用户能够在同一个界面内实时监控和分析训练过程中的指标和图表，无需切换到单独的应用或浏览器标签页。

TensorBoard 插件的使用方法请参阅使用说明。

你也可以选择安装一个 TensorBoard App，展示的内容是相同的。

常见问题

• 如何上传下载文件
• 如何查看挂载 PVC 的剩余存储空间
• 如何查看目录和文件的权限、大小等信息
• 如何使用 conda 环境
• 如何通过 SSH 远程连接
• 无法使用 sudo 命令
• 命令执行失败，显示 Killed

下一步

在下列任务中学习使用 JupyterLab Apps：

• 进行数据并行训练
• 进行 LLM 大规模预训练
• 分析性能
• 指令微调 LLM
• 部署 LLM 推理服务和聊天服务

Code Server

Code Server 是一个基于浏览器的开源开发环境，它将 Visual Studio Code 的强大功能带到了云端。这个工具允许开发者通过网页访问完整的 VS Code 编辑器，无需在本地安装任何软件。Code Server 支持多种编程语言和框架，并且可以在远程服务器或云平台上运行，使得开发者能够在任何设备上进行编码工作。

在实际应用中，Code Server 特别适合远程工作和协作开发场景。它支持多人同时编辑同一项目，并且可以轻松集成版本控制系统如 Git。Code Server 还保留了 VS Code 的插件生态系统，用户可以安装和使用各种扩展来增强开发体验。此外，由于代码和开发环境都在服务器上，Code Server 可以帮助团队统一开发环境，减少因本地环境差异导致的问题。

使用方法

待 App 就绪后，点击右侧的 进入网页 UI，即可进行开发工作。

网页 UI 的使用方法请参阅 Visual Studio Code Docs 和 FAQ of Code Server。

配置和使用说明

镜像

App 可以选用的镜像请参阅 README 的镜像列表部分。

每个镜像都包含 Code Server 和特定的环境（机器学习框架或 conda 环境），预装了一些 Python 包、命令行工具和平台工具，并且创建并使用一个新的用户：

• 每个镜像预装的 Python 包各不相同，请执行 pip list 命令以查看。
• 所有镜像均预装了以下命令行工具：

• 所有镜像均预装了最新版本的平台工具。
• 所有镜像均创建 GID 为 1000、名称为 t9kuser 的用户组，以及属于该用户组、UID 为 1000、名称为 t9kuser、HOME 目录为 /t9k/mnt 的用户，并使用该用户。

挂载 PVC

必须为 App（的容器）挂载一个 PVC 作为工作空间。下面的配置示例挂载 PVC demo 作为工作空间：

pvc: "demo"

...

PVC 的挂载路径为 /t9k/mnt，即镜像使用的 t9kuser 用户的 HOME 目录。

挂载的 PVC 负责存储开发相关的文件，这些文件可以是通过 Code Server 的 UI 上传或创建的，也可以是通过 Code Server 的终端从网络下载或运行程序产生的。此外，挂载的 PVC 还负责存储 conda 环境和 conda 包的文件（位于 /t9k/mnt/.conda 路径下）、Python 包的文件（位于 /t9k/mnt/.local/lib/python3.11 路径下），以及扩展的文件（位于 /t9k/mnt/.local/share/code-server 路径下）。如果你需要安装较多、较大的 conda 包、Python 包或扩展，请确保挂载的 PVC 留有足够的存储空间。

T9k Job、T9k Service 等工作负载可以和 App 挂载同一个 PVC 以共享存储。例如创建一个 PyTorchTrainingJob，其利用通过 JupyterLab 准备好的训练脚本和数据集文件以启动训练；或者创建一个 SimpleMLService，其读取下载好的模型文件以启动推理服务。

用户权限

在 App 的容器环境中，用户的 UID:GID 为 1000:1000，这会导致系统级操作受到限制（权限不足）。例如，用户无法使用 apt install 命令安装开发所需的库，无法执行 rm 命令删除没有写权限的文件（这些文件可能是由挂载了同一个 PVC 且使用 root 用户的 Job 产生的）。

在某些情况下，进行系统级操作是必要或便利的，解决方案是为 App 选用标签带有 -sudo 后缀的镜像，在需要提升权限的命令前加上 sudo，以 root 身份执行该命令。

扩展

和 VS Code 一样，你也可以在 Code Server 中安装、管理、配置和使用扩展。所有镜像还预装了以下扩展：

常见问题

• 如何上传下载文件
• 如何查看挂载 PVC 的剩余存储空间
• 如何查看目录和文件的权限、大小等信息
• 如何使用 conda 环境
• 无法使用 sudo 命令
• 命令执行失败，显示 Killed

RStudio

RStudio 是一个专为 R 语言设计的集成开发环境（IDE），它为数据分析师、统计学家和 R 程序员提供了一个功能丰富、用户友好的工作平台。RStudio 集成了代码编辑器、控制台、图形输出和项目管理等功能，使 R 编程和数据分析变得更加高效和直观。它的界面分为多个窗格，包括脚本编辑器、R 控制台/终端、环境/历史记录、文件/图形/包/帮助等，让用户能够同时查看和操作多个工作区域。

RStudio 的项目管理功能允许用户将相关的代码、数据和结果组织在一起，便于版本控制和协作。RStudio 还提供了强大的数据可视化工具，用户可以轻松创建各种统计图表，并直接在 IDE 中预览。此外，RStudio 支持 R Markdown，这是一个非常实用的功能，允许用户将 R 代码、分析结果和解释性文本集成到一个文档中，方便生成报告和共享分析过程。

使用方法

待 App 就绪后，点击右侧的 进入网页 UI，即可进行开发工作。

网页 UI 的使用方法请参阅 RStudio User Guide。

除了网页 UI，App 还支持通过 SSH 远程连接（需要启用 SSH 服务），让你能够使用熟悉的本地终端或 IDE，像在本地开发一样进行远程开发。限于篇幅，具体步骤请参阅如何通过 SSH 远程连接。

配置和使用说明

镜像

App 可以选用的镜像请参阅 README 的镜像列表部分。

每个镜像都包含 RStudio，以及 R 和 Python 环境，预装了一些命令行工具，并且创建并使用一个新的用户：

• 所有镜像均预装了以下命令行工具：

• 所有镜像均创建 GID 为 1000、名称为 t9kuser 的用户组，以及属于该用户组、UID 为 1000、名称为 t9kuser、HOME 目录为 /t9k/mnt 的用户，并使用该用户。

挂载 PVC

必须为 App（的容器）挂载一个 PVC 作为工作空间。下面的配置示例挂载 PVC demo 作为工作空间：

pvc: "demo"

...

PVC 的挂载路径为 /t9k/mnt，即镜像使用的 t9kuser 用户的 HOME 目录。

挂载的 PVC 负责存储开发相关的文件，这些文件可以是通过 RStudio 的 UI 上传或创建的，也可以是通过 RStudio 的终端从网络下载或运行程序产生的。此外，挂载的 PVC 还负责存储 Python 包的文件（位于 /t9k/mnt/.local/lib/python3.10 路径下）。如果你需要安装较多、较大的 Python 包，请确保挂载的 PVC 留有足够的存储空间。

用户权限

在 App 的容器环境中，用户的 UID:GID 为 1000:1000，这会导致系统级操作受到限制（权限不足）。例如，用户无法使用 apt install 命令安装开发所需的库，无法执行 rm 命令删除没有写权限的文件（这些文件可能是由挂载了同一个 PVC 且使用 root 用户的 Job 产生的）。

在某些情况下，进行系统级操作是必要或便利的，解决方案是为 App 选用标签带有 -sudo 后缀的镜像，在需要提升权限的命令前加上 sudo，以 root 身份执行该命令。

常见问题

• 如何上传下载文件
• 如何查看挂载 PVC 的剩余存储空间
• 如何查看目录和文件的权限、大小等信息
• 如何通过 SSH 远程连接
• 无法使用 sudo 命令
• 命令执行失败，显示 Killed

Terminal

ttyd 是一个简单而强大的工具，它允许用户通过 HTTP 或 HTTPS 协议在 web 浏览器中访问远程服务器的终端，无需安装额外的客户端软件。ttyd 支持多种终端程序，如 sh、bash、zsh 等，使用户可以在熟悉的 shell 环境中工作。

Terminal 是一个基于 ttyd 的 web 终端 App，允许用户在浏览器中访问并执行命令。Terminal 预装了多种常用的命令行工具（如 kubectl、tmux、helm 和 vim），支持多种 shell 环境（如 sh、bash 和 zsh），并且可以挂载 PVC。

使用方法

待 App 就绪后，点击右侧的 进入网页 UI，即可输入并执行命令。

web 终端的使用方法与本地终端类似：在提示符后面输入命令并按下回车键，远程服务器会接收这些命令，执行后将结果返回并显示。

使用说明

• App（的镜像）预装了以下命令行工具：

• App 不可使用 GPU 等加速设备。

• sh、bash 和 zsh 是类 Unix 系统中常见的几种 shell：

  • sh：这是最早的 Unix shell，主要用于基本的脚本和系统管理任务。功能简单，兼容性高，但功能相对较少。
  • bash：bash 是 sh 的增强版，提供了更多的功能，比如命令行编辑、命令补全和脚本编程功能。它是许多 Linux 发行版的默认 shell。
  • zsh：zsh 是功能最强大的 shell 之一，提供了强大的命令补全、自动化脚本处理、插件系统等功能。它在兼容 bash 的同时，在用户界面和自定义方面比 bash 更加灵活。

  进一步参阅：

  • Bash 快捷键大全
  • Bash 脚本教程
  • Zsh 开发指南

• 在使用上，Terminal App、JupyterLab App 的终端和 Code Server App 的终端几乎没有区别，除了预装的软件不同，Terminal 可以选用多种 shell 环境，以及 JupyterLab 和 Code Server 可以同时打开多个终端。

File Browser

File Browser 是一个轻量级的基于网络的文件管理系统，为用户提供了一个简单而功能强大的界面来管理服务器上的文件和目录。它允许用户通过网页浏览器远程访问、上传、下载、编辑和共享文件，无需使用复杂的 FTP 客户端或命令行工具。

File Browser 的直观界面使文件管理变得简单高效，用户可以轻松执行拖放上传、创建文件夹、重命名文件等操作。它还提供了文件预览功能，支持多种文件格式的在线查看，如文本、图片、音频和视频。

使用方法

待 App 就绪后，点击右侧的 进入网页 UI，即可管理文件。

网页 UI 的使用方法简单直观，请用户自行尝试。

配置和使用说明

挂载 PVC

必须为 App（的容器）挂载一个 PVC 作为工作空间，App 的网页 UI 展示了该 PVC 中的所有文件。下面的配置示例挂载 PVC demo 作为工作空间：

pvc: demo

...

用户权限

在 App 的容器环境中，用户的 UID:GID 为 1000:1000（fsgroup 为 2000），这意味着没有权限修改所有者和所有组都是 root 的文件（这些文件可能由挂载了同一个 PVC 且使用 root 用户的 Job 产生）。

上传和下载

根据管理员配置，App 有可能限制上传的单个文件的大小。与此同时，上传和下载过程也容易因为网络波动而出错，建议 > ~2GB（也取决于具体网络环境）的单个文件使用其他方法上传或下载。

App 不限制单次上传的文件数量，并且支持上传整个目录，在小文件数量较多的情况下也不容易出错；单次下载多个文件时下载的是包含这些文件的压缩包，可以选择压缩格式。

下一步

• 学习如何上传和下载文件

TensorBoard

TensorBoard 是一款专为深度学习项目设计的可视化工具套件，主要用于监控和分析深度学习模型的训练过程。它能够实时展示模型训练中的各种指标，如损失函数、准确率、梯度分布等，帮助开发者直观地了解模型的性能和训练进展。TensorBoard 还提供了模型结构可视化功能，使用户能够清晰地查看复杂神经网络的架构。

使用方法

待 App 就绪后，点击右侧的 进入网页 UI，查看可视化数据。

对于 TensorFlow 框架，记录各种类型数据和使用网页 UI 的方法请参阅 TensorBoard 指南。

对于 PyTorch 框架，记录各种类型数据和使用网页 UI 的方法请参阅：

• torch.utils.tensorboard
• Visualizing models, data, and training with TensorBoard
• PyTorch Profiler With TensorBoard

配置和使用说明

数据源

App 支持 PVC 和 S3 两种数据源，配置时必须且只能选择其中一种。

如使用 PVC 作为数据源，将 logDir.pvc[0].name 和 logDir.pvc[0].subPath 字段的值分别设为 PVC 的名称和目录，位于该目录及其子目录下的所有 tfevents 文件都将被可视化展示。

下面的配置示例可视化展示 PVC tutorial 的 train/logs 目录下的所有 tfevents 文件：

logDir:
  pvc:
    - name: tutorial
      subPath:
        - "train/logs"

...

如使用 S3 作为数据源，将 logDir.s3️.secretRef.name 字段的值设为 S3-env 类型的 Secret 的名称，将 logDir.s3️.uri 字段的值设为以 / 结尾的 S3 URL，所有以该 URL 作为前缀的 tfevents 文件都将被可视化展示。

下面的配置示例可视化展示 URL 匹配 s3://folder/** 的所有 tfevents 文件，由 Secret my-s3-env 提供访问凭证：

logDir:
  s3:
    secretRef:
      name: "my-s3-env"
    uri:
      - "s3://folder/"

...

下一步

在下列任务中学习使用 TensorBoard App：

• 进行数据并行训练
• 进行 LLM 大规模预训练
• 分析性能

Virtual Machine

kubevirt 是一个强大的虚拟化工具，它允许用户在 Kubernetes 容器化环境下启动一个虚拟机，并利用 Kubernetes 的扩展能力，让用户可以轻松地使用和管理虚拟机。

Virtual Machine 是一个基于 kubevirt 的虚拟机 App，允许用户快速部署一个虚拟机。

使用方法

连接虚拟机终端

用户需要同时安装 0.1.5 及以上版本的 Terminal App。

待 Virtual Machine App 就绪后，点击右侧的 > 查看信息，复制连接虚拟机终端的命令，其格式为：

kubectl virt console <virtual-machine-name> -n <namespace>

待 Terminal App 就绪后，点击右侧的 进入 Terminal 网页 UI：

粘贴并执行上述命令，以连接虚拟机终端。

使用图形界面

请参照安装图形界面配置 Virtual Machine App 并安装图形桌面。

在本地终端执行以下命令：

t9k-pf service <virtual-machine-name> 5901:5901 -n <namespace> -k

上述命令会将远程桌面端口暴露在本地的 5901 端口。

在本地打开一个 VNC Client，输入 VNC 地址 localhost:5901 即可打开远程桌面。

配置和使用说明

cloud-init 初始化

虚拟机首次启动时，会根据 cloudInit.userData 字段的值进行系统初始化，这个过程通常需要几分钟。用户需要等待初始化完成后再使用虚拟机。

cloud-init 是业界标准的多发行版跨平台云实例初始化方法。在启动过程中，cloud-init 会识别其运行的云环境，并相应地初始化系统，自动配置网络、存储、SSH 密钥、软件包以及其他各种系统方面。

cloud-init 的配置模块和示例请参阅 Module reference 和 Cloud config examples。

定制系统镜像

准备工作

安装一个 Virtual Machine App，选择合适的基础镜像：

rootDisk:
  dataVolume:
    enabled: true
    fromOCIRegistry:
      enabled: true
      image:
        registry: registry.cn-hangzhou.aliyuncs.com
        repository: t9k/ubuntu-server-cloud
        tag: 20.04-240819
    pvc:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 5Gi

内容定制

待 Virtual Machine App 就绪后，连接到虚拟机终端，本节后续操作都是在虚拟机终端中进行。

用户可以在虚拟机中执行安装软件、修改系统配置等操作，只要这些操作的最终修改发生在系统盘中，就可以被记录在新镜像中。

镜像上传

安装一个 JupyterLab App，绑定 Vritual Machine App 自动创建的 PVC（PVC 名称可以从 App 的详情页面获取）：

待 JupyterLab App 就绪后，进入网页 UI，在工作目录下创建 Dockerfile 文件，内容为：

FROM scratch
ADD disk.img /disk/

使用如下 YAML 配置创建 ImageBuilder 构建镜像：

# image-builder.yaml
apiVersion: tensorstack.dev/v1beta1
kind: ImageBuilder
metadata:
  name: vm-image
spec:
  builder:
    kaniko: {}
  dockerConfig:
    secret: t9kpublic
    subPath: .dockerconfigjson
  resources:
    limits:
      cpu: 8
      memory: 16Gi
  tag: t9kpublic/vm-jupyter:0.0.1
  workspace:
    pvc:
      contextPath: .
      dockerfilePath: ./Dockerfile
      name: <pvc-name>

kubectl create -f image-builder.yaml

在 Image Builder 执行完毕后，系统镜像会被上传并保存为 t9kpublic/vm-jupyter:0.0.1，在下次创建 Virtual Machine App 时可以直接设置 rootDisk.dataVolume.fromOCIRegistry.image 字段使用该镜像。

安装图形界面

准备工作

安装一个 Virtual Machine App，修改如下配置：

1. 暴露 5901 端口
2. 增加 PVC 的大小（大于默认的 3Gi）

rootDisk:
  dataVolume:
    enabled: true
    fromOCIRegistry:
      enabled: true
      image:
        registry: registry.cn-hangzhou.aliyuncs.com
        repository: t9k/ubuntu-server-cloud
        tag: 20.04-240819
    pvc:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 5Gi

network:
  ports: 
  - name: "http"
    port: 5901
    protocol: "TCP"

本示例中的系统镜像大小为 2.6Gi，因此配置 5Gi 的 PVC 以容纳系统文件和桌面管理软件。如果用户的桌面管理程序需要更多的磁盘空间，请根据需求自行调整 PVC 大小。

安装桌面并启动

待 Virtual Machine App 就绪后，连接到虚拟机终端，本节后续操作都是在虚拟机终端中进行。

安装 xfce4 和 vnc server：

sudo apt install xfce4 xfce4-goodies tightvncserver

安装 xfce4 时，需要选择一个 Desktop Manager，其中：

1. gdm3 提供更全面的桌面功能，但需要消耗更多资源。
2. lightdm 则是更轻量化的桌面管理服务。

用户可以根据需要进行选择。

启动 vncserver 进行初始化（设置密码等）：

vncserver

关闭 vncserver，设置使用 xfce4 桌面：

​​vncserver -kill :1
echo startxfce4 >> ~/.vnc/xstartup

再次启动 vncserver，此时 VNC 服务已经启动，用户可以使用虚拟机图形界面。

其他桌面

上面介绍了如何使用 xfce4 桌面，该桌面比较简陋，用户可以自行寻找习惯的桌面。这里再介绍一个 Gnome 桌面，以供参考。

下载 Gnome 相关组件和 vncserver：

# 替代前一节中 sudo apt install xfce4 xfce4-goodies tightvncserver 命令
sudo apt install tightvncserver gnome-panel gnome-settings-daemon metacity nautilus gnome-terminal xserver-xorg-core -y

vncserver 初始化操作与前一节相同。

修改 ~/.vnc/xstartup 文件，以使用 gnome 桌面：

#!/bin/bash

unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS

[ -x /etc/vnc/xstartup ] && exec /etc/vnc/xstartup
[ -r $HOME/.Xresources ] && xrdb $HOME/.Xresources

export XKL_XMODMAP_DISABLE=1
export XDG_CURRENT_DESKTOP="GNOME-Flashback:Unity"
export XDG_MENU_PREFIX="gnome-flashback-"

gnome-session --session=gnome-flashback-metacity --disable-acceleration-check &

再次启动 vncserver。

使用 GPU

按如下方式，在 extraDevices 字段中添加 GPU 设备信息：

extraDevices:
  gpus:
    - deviceName: nvidia.com/GA100_A100_PCIE_40GB
      name: gpu1

在上述配置中，deviceName 字段填写 GPU 的 k8s 扩展资源名称，该扩展资源由 kubevirt-gpu-device-plugin 探测并扩展。name 字段表示设备名称，在虚拟机中不应出现两个相同的设备名称。

设置启动盘

目前，我们支持以下三种启动盘形式：

1. 使用 DataVolume 下载系统镜像并构建启动盘；
2. 使用一个容器作为启动盘；
3. 使用一个已经进行过磁盘格式化并安装了系统文件的 PVC 作为启动盘。

使用 DataVolume 下载系统镜像并构建启动盘

rootDisk:
  dataVolume:
    enabled: true
    fromOCIRegistry:
      enabled: true
      image:
        registry: docker.io
        repository: t9kpublic/ubuntu-server-cloud
        tag: 20.04-240819
    pvc:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 3Gi

在上述配置中，虚拟机控制器会创建一个 PVC（名称即为 App 名称），从 docker.io/t9kpublic/ubuntu-server-cloud:20.04-240819 下载系统镜像并安装到 PVC 中，将该 PVC 作为虚拟机启动盘。

除 OCI 仓库以外，虚拟机还支持修改 rootDisk.dataVolume.template.source 从其他数据源下载系统镜像：

rootDisk:
  dataVolume:
    enabled: true
    fromOCIRegistry:
      enabled: false
    template:
      source:
        http:
          url: https://cloud-images.ubuntu.com/releases/focal/release/ubuntu-20.04-server-cloudimg-amd64.img
      pvc:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 3Gi

上述配置中，虚拟机控制器会从 https://cloud-images.ubuntu.com/releases/focal/release/ubuntu-20.04-server-cloudimg-amd64.img 下载系统镜像。（虚拟机默认从 OCI 仓库下载系统镜像，使用其他系统镜像下载源时，需要将 rootDisk.dataVolume.fromOCIRegistry.enabled 设置为 false。）

更多数据源的设置方式，请参阅 DataVolumeSource。

使用容器作为启动盘

rootDisk:
  containerDisk:
    enabled: true
    image: 
      registry: docker.io
      repository: t9kpublic/fedora-cloud-container-disk-demo
      tag: v0.36.4
  dataVolume:
    enabled: false

在上述配置中，虚拟机会使用 docker.io/t9kpublic/fedora-cloud-container-disk-demo:latest 镜像创建一个容器，作为启动盘。（虚拟机默认使用 DataVolume 作为启动盘，使用容器作为启动盘时，需要将 rootDisk.dataVolume.enabled 设置为 false。）

kubevirt 原生支持的、可以作为启动盘的容器镜像请参阅 KubeVirt container-disk images。

containerDisk 属于临时存储设备，不具备持久性，即如果虚拟机重启则系统的修改丢失。

使用一个 PVC 作为启动盘

rootDisk:
  containerDisk:
    enabled: false
  dataVolume:
    enabled: false

volumes:
  disks:
    - persistentVolumeClaim:
        name: "pvc-name"
      name: "volume-name"

在上述配置中，禁用了 ContainerDisk 和 DataVolume。这种情况下，虚拟机会将第一个以 Disk 形式绑定的 PVC 作为启动盘。该 PVC 应已经进行格式化且安装过系统，否则虚拟机无法启动。

设置数据卷

volumes:
  filesystems:
    - persistentVolumeClaim:
        name: "pvc-as-fs"
      name: "fs-name"
  disks:
    - persistentVolumeClaim:
        name: "pvc-as-disk"
      name: "disk-name"

cloudInit:
  userData: |-
    ...
    runcmd:
    - "sudo mkdir /mnt/pvc"
    - "sudo mount -t virtiofs fs-name /mnt/pvc"
    - test "$(lsblk /dev/vdb)" && mkfs.ext4 /dev/vdb
    - mkdir -p /mnt/vdb
    mounts:
    - [ "/dev/vdb", "/mnt/vdb", "ext4", "defaults,nofail", "0", "2" ]

在上述配置中：

1. 虚拟机绑定了两个 PVC：pvc-as-fs 和 pvc-as-disk，两者分别作为文件系统和磁盘。
2. 将 PVC 以文件系统的方式绑定到虚拟机时，需要使用 sudo mount -t virtiofs fs-name /mnt/pvc 命令将这个 PVC 绑定到 /mnt/pvc 路径下。
3. 将 PVC 以磁盘的方式绑定到虚拟机时，如果 PVC 没有进行过磁盘格式化，则需要执行 mkfs.ext4 /dev/vdb 命令格式化 PVC，同时执行 mount 命令将 PVC 绑定到 /mnt/vdb 路径下。

Job Manager

Job Manager 是一个用于管理 T9k Job（以下简称 Job）的控制台，是平台的原生应用。它提供了一个用户友好的界面，方便用户创建 Job、查看 Job 的详细信息，并监控计算资源的使用情况。

通过 Job Manager 的直观界面，用户可以不必在 JupyterLab 或 Terminal App 的终端中使用 kubectl 命令来创建或删除 Job，或查看 Job 及其创建的 Pod 的状态或日志，也无需手动编辑 YAML 配置文件。Job Manager 的界面展示了用户所关心的所有 Job 相关信息，并且引导用户填写创建 Job 所需的各个字段，从而简化了操作流程。

使用方法

待 App 就绪后，点击右侧的 进入控制台。

控制台的使用方法请参阅进行数据并行训练。

下一步

• 了解 T9k Job 的定义

Service Manager

Service Manager 是一个用于管理 T9k Service（以下简称 Service）的控制台，是平台的原生应用。它提供了一个用户友好的界面，方便用户创建 Service（和 Runtime）、查看 Service 的详细信息，并监控计算资源的使用情况。

通过 Service Manager 的直观界面，用户可以不必在 JupyterLab 或 Terminal App 的终端中使用 kubectl 命令来创建或删除 Service（和 Runtime），或查看 Service 及其创建的 Pod 的状态或日志，也无需手动编辑 YAML 配置文件。Service Manager 的界面展示了用户所关心的所有 Service 相关信息，并且引导用户填写创建 Service 所需的各个字段，从而简化了操作流程。

使用方法

待 App 就绪后，点击右侧的 进入控制台。

控制台的使用方法请参阅部署 PyTorch 模型。

下一步

• 了解 T9k Service 的定义

Workflow

Workflow 是一个用于管理工作流的控制台，是平台的原生应用。它提供了一个用户友好的界面，方便用户创建工作流、查看工作流的详细信息。

通过 Workflow 的直观界面，用户可以不必在 JupyterLab 或 Terminal App 的终端中使用 kubectl 命令来创建或删除工作流、查看工作流状态或日志，也无需手动编辑 YAML 配置文件。Workflow 的界面展示了用户所关心的所有工作流相关信息，并且引导用户填写创建工作流所需的各个字段，从而简化了操作流程。

使用方法

待 App 就绪后，点击右侧的 进入控制台。

下一步

• 了解工作流的定义

AutoTune

AutoTune 是一个自动化机器学习（AutoML）工具，是平台的原生应用。它提供了一个用户友好的界面，方便用户创建自动化机器学习实验、查看实验的详细信息。

使用方法

待 App 就绪后，点击右侧的 进入控制台。

用户可以在控制台创建 AutoTuneExperiment 以进行自动化机器学习。

下一步

• 了解 AutoTuneExperiment

Argo Workflows

Argo Workflows 是一个广泛应用的开源工作流编排引擎，具有直观的可视化界面，便于用户创建和运行工作流，并查看状态和日志，而无需手动编辑 YAML 配置文件。其界面展示了所有与工作流相关的信息，并引导用户填写所需的字段，从而大大简化了操作流程。

使用方法

待 App 就绪后，点击右侧的 进入控制台。

Argo Workflows 的使用方法请参阅官方文档和官方示例。

控制台的基本使用方法，包括如何创建 Workflow、如何创建 Workflow Template，可以参阅下面的教程。

创建完整的 Workflow

点击 SUBMIT NEW WORKFLOW 来创建一个 Workflow：

在 Argo Worklfows 中，你可以直接在 Workflow 中填写全部运行所需信息，或者先创建一个 WorkflowTemplate 作为模板、然后创建一个 Workflow 引用该模板并填写必要的参数。

首先，点击 Edit using full workflow options，直接在 Workflow 中填写全部运行所需信息：

将下面的 Workflow YAML 示例复制到编辑框中，并点击 CREATE 创建：

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: hello-world-
  labels:
    workflows.argoproj.io/archive-strategy: "false"
  annotations:
    workflows.argoproj.io/description: |
      This is a simple hello world example.
spec:
  entrypoint: hello-world
  templates:
  - name: hello-world
    container:
      image: busybox
      command: [echo]
      args: ["hello world"]

上述 Workflow 示例会打印一行 hello world。

创建成功后自动跳转至 Workflow 详情页面，你可以在此查看 Workflow 的运行状态、日志等信息：

创建 WorkflowTemplate 和 Workflow

接下来演示如何先创建一个 Workflowtemplate，然后再创建一个 Workflow 引用它。

点击左侧导航栏中的第二个图标进入 WorkflowTemplate 列表页面，然后点击 CREATE NEW WORKFLOWTEMPLATE 创建一个 WorkflowTemplate：

将下面的 WorkflowTemplate YAML 复制到编辑框中，并点击 CREATE 创建：

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: workflow-template-print-message
spec:
  entrypoint: print-message
  templates:
  - name: print-message
    inputs:
      parameters:
      - name: message
    container:
      image: busybox
      command: [echo]
      args: ["{{inputs.parameters.message}}"]

上述 WorkflowTemplate 示例要求传入一个名为 message 的参数，并将参数的值打印出来。

然后，以上一节相同的方式创建下面的 Workflow：

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: workflow-template-hello-world-
spec:
  entrypoint: hello-world-from-templateRef
  templates:
  - name: hello-world-from-templateRef
    steps:
      - - name: call-print-message
          templateRef:
            name: workflow-template-print-message
            template: print-message
          arguments:
            parameters:
            - name: message
              value: "hello world"

上述 Workflow 示例引用了之前的 WorkflowTemplate，并设置了参数 message 的值为 hello world。因此，该 Workflow 的运行结果与上一节相同。

APIs

概念

应用程序接口（API）是一组规则和协议，允许不同的软件组件之间相互通信。在 TensorStack AI 平台中，API 采用 Kubernetes 的 API 扩展机制 实现。

API 是平台的核心组成部分，扮演着几个关键角色：

1. 请求系统服务：集群的系统功能，如创建工作负载，申请存储空间，设置网络配置等，都是通过 API 实现。
2. API 对象管理： API 允许用户管理各种 Kubernetes API 对象，如 Pod、Service、Deployment，及其它 CRD 类型。这种管理包括根据需要创建、更新和删除资源。
3. 通信： API 支持不同组件之间的通信，确保它们能够有效地协同工作。
4. 可扩展性： 通过 CRD 和其他机制，API 使用户能够扩展平台的功能，允许创建满足特定要求的自定义解决方案。
5. 自动化： API 使自动化工具和脚本能够与平台交互,从而实现应用程序的简化部署和管理。

系统中的 API

系统提供的 API 由管理员安装，普通用户可以查看系统中的 API 安装情况。

例如，查看系统中的 TensorStack 提供的 APIs:

$ kubectl api-resources |grep tensorstack
instances                                       app.tensorstack.dev/v1beta1       true      Instance
beamjobs                             bj         batch.tensorstack.dev/v1beta1     true      BeamJob
colossalaijobs                       caij       batch.tensorstack.dev/v1beta1     true      ColossalAIJob
cronworkflowruns                     cwr        batch.tensorstack.dev/v1beta1     true      CronWorkflowRun
deepspeedjobs                        dj         batch.tensorstack.dev/v1beta1     true      DeepSpeedJob
genericjobs                          gj         batch.tensorstack.dev/v1beta1     true      GenericJob
mpijobs                              mj         batch.tensorstack.dev/v1beta1     true      MPIJob
pytorchtrainingjobs                  pj         batch.tensorstack.dev/v1beta1     true      PyTorchTrainingJob
tensorflowtrainingjobs               tj         batch.tensorstack.dev/v1beta1     true      TensorFlowTrainingJob
...

API 详情

如希望了解一个具体的 API 详情，可方便通过命令行获得。

以 DeepSpeedJob API 为例，查看 API 基本情况：

$ kubectl explain deepspeedjobs
KIND:     DeepSpeedJob
VERSION:  batch.tensorstack.dev/v1beta1

DESCRIPTION:
     DeepSpeedJob defines the schema for the DeepSpeedJob API.

FIELDS:
   apiVersion	<string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
...

可进一步指定子字段，查看其详情：

$ kubectl explain deepspeedjobs.spec
KIND:     DeepSpeedJob
VERSION:  batch.tensorstack.dev/v1beta1

RESOURCE: spec <Object>

DESCRIPTION:
     DeepSpeedJobSpec outlines the intended configuration and execution
     parameters for a DeepSpeedJob.

FIELDS:
   config	<Object>
     Key configurations for executing DeepSpeed training jobs.
...

下一步

• 阅读本 APIs 章节内容，全面了解平台提供的各种 APIs
• 了解 TensorStack AI 平台 计算任务（T9k Job）APIs
• 了解 Kubernetes 的 API 扩展机制

存储

存储系统负责为 Apps 提供数据持久化。它包括存储卷（PVC）和适配器（StorageShim）两种类型的资源，这些资源确保 Apps 能够可靠地存储和访问数据。存储卷支持 Apps 动态地申请新的数据存储空间，而适配器则帮助 Apps 连接和使用已有的外部存储系统（例如 S3）。

通过有效管理这些存储资源，用户能够灵活地处理大规模模型、数据集文件和其他 AI 开发过程中产生的数据，从而支持各种 AI 应用的高效运行和数据密集型任务的顺利进行。

架构

存储系统架构如下图所示：

Apps 的数据持久化保存在 PVC 中。PVC 的生命周期与 Apps 是相互独立的，PVC 不会因为 Apps 的删除而被删除。一个 PVC 可以被多个 Apps 同时使用，多个 Apps 对同一个 PVC 的修改是互相可见的。

用户既可以通过直接创建 PVC 来在 TensorStack AI 平台存储系统中动态申请一块新的存储空间，也可以通过创建 StorageShim 来连接一个第三方存储系统（例如 S3 的某个 bucket 下的某个路径，或 CephFS 的某个文件夹），StorageShim 负责根据用户提供的访问凭证（存储在 Secret 中）自动创建并配置好一个 PVC 以供 Apps 使用。

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 是通用的持久化存储资源，你在 JupyterLab、Code Server、File Browser、TensorBoard 等 App，以及 Notebook、T9k Job、T9k Service、Workflow 等 API 中都可以使用 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

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 必须为 Ceph Client 类型，该 CephFS 文件系统的相关信息存储在 ConfigMap ceph-cluster-config-demo 中。

下一步

• API 参考：StorageShim
• 学习如何创建 StorageShim

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 的概念

网络服务

网络服务负责为 Apps 提供平台内外的访问方式。它包括 Service、Ingress、Gateway API 等资源。Service 用于管理平台内部的网络通信，确保不同 Apps 之间能够相互访问和交互；Ingress 和 Gateway API 则负责管理从平台外部到内部 Apps 的访问路由，使得外部用户或系统能够安全地访问平台内的服务。

基于这些网络服务，用户能够灵活配置 Apps 的网络连接，无论是内部微服务之间的通信，还是对外暴露 API 接口，都能得到有效支持，从而满足 AI 开发和部署过程中复杂多样的网络需求。

Service

Service 是一种 Kubernetes 原生资源，用于访问一个或多个 Pod。它为一组 Pod 提供了一个稳定的 IP 地址和 DNS 名称，以便其他应用程序或用户可以访问它们。Service 允许 Pod 动态添加或删除，而不会影响服务的可用性。Service 还支持负载均衡，可以将请求分配给多个 Pod 以提高可扩展性和可靠性。

创建 Service

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

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

其中：

• spec.selector 字段表示该 Service 指向一组拥有标签 app: nignx 的 Pod
• spec.ports 字段表示该 Service 本身对外提供服务的端口（port）为 80，指向的 Pod 的端口（targetPort）也为 80

下面是该 Service 指向的一组 Pod 的示例，以 Deployment 的形式运行：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 3
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

在该例中，Deployment 一共会创建 3 个 Pod，每个 Pod 都拥有标签 app: nginx，且在 80 端口提供服务。因此，上述 Service 会将流量均匀分布到这 3 个 Pod 中。

使用 Service

创建 Service 后，其他应用程序可以从集群内部根据 Service 的名称和命名空间访问该 Service，访问地址为 http://<service-name>.<service-namespace>:<service-port>。

例如，上节中的 Service 示例可以在集群内部通过如下命令访问：

curl -G http://nginx-service.default:80

注：如果应用程序与 Service 处于同一命名空间，可以省略地址中的命名空间部分，形如 http://<service-name>:<service-port>。

Service 类型

Service 支持以下几种类型：

• ClusterIP：ClusterIP 是最常见的 Service 类型，也是默认类型。ClusterIP 类型的 Service 只能从集群内部访问，不允许从集群外部访问；
• NodePort：NodePort 允许在每个节点上公开一个端口，以便从集群外部根据节点的 IP 和端口访问 Service；
• LoadBalancer：LoadBalancer 使用外部负载均衡器将流量分配到 Service 上。它需要在云提供商上创建负载均衡器，然后将流量转发到Service。
• ExternalName：ExternalName 将 Service 映射到另一个服务的地址（例如 api.example.com）。它通常用于连接到外部服务。

下一步

• 了解 Service 的概念
• 了解 Service 的定义

Ingress

Ingress 是一种 Kubernetes 原生资源，用于提供从集群外部到集群内服务的 HTTP 和 HTTPS 路由。

创建 Ingress

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-example
spec:
  rules:
  - host: foo.example.com
    http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80
  tls:
  - hosts:
    - foo.example.com
    secretName: my-tls-secret

在该例中，当用户从集群外部访问地址 https://foo.example.com/testpath 时，Ingress 会将请求转发至名为 nginx-service 的 Service 的 80 端口。

为了支持 HTTPS 协议，该 Ingress 需要配置如下格式的 Secret：

apiVersion: v1
kind: Secret
metadata:
  name: my-tls-secret
data:
  tls.crt: <base64 encoded cert>
  tls.key: <base64 encoded key>
type: kubernetes.io/tls

使用 Ingress

创建 Ingress 后，还需要为 Ingress 定义中的域名配置 DNS 解析，才能支持用户正常访问。当 Ingress 控制器为 Ingress NGINX Controller 时，Ingress 定义中的域名需要解析到集群 ingress 节点的 IP 地址。

例如，可以通过以下命令得到集群 ingress 节点的 IP 地址为 100.1.2.3：

$ kubectl get node -l node-role.kubernetes.io/ingress -o wide
NAME                 STATUS   ROLES     AGE    VERSION    INTERNAL-IP
ingress-node-name    Ready    ingress   536d   v1.28.6    100.1.2.3

那么，对于上节中的 Ingress 示例，应当配置域名 foo.example.com 解析到地址 100.1.2.3。

下一步

• 了解 Ingress 的概念
• 了解 Ingress 的定义

Gateway API

Gateway API 是一组 Kubernetes 原生资源，包括 GatewayClass、Gateway、HTTPRoute 等，提供从集群外部到集群内服务的动态路由功能。Gateway API 是 Ingress 的继任者，将替代 Ingress 成为下一代 Kubernetes 路由解决方案。

Gateway API 的设计模型如下：

其中：

• 基础设施提供商（TensorStack AI 平台）负责创建 GatewayClass 资源；
• 平台管理员（集群管理员）负责创建 Gateway 资源；
• 应用开发者（平台 App 开发者、普通用户）负责创建 HTTPRoute 资源。

上述资源的功能分别是：

• GatewayClass：与 IngressClass、StorageClass 类似，GatewayClass 定义了一组共享共同配置和行为的 Gateway，由实现该 GatewayClass 的控制器管理。
• Gateway：描述了如何将流量翻译到集群内的服务。
• HTTPRoute：定义了特定协议的规则，用于将流量从 Gateway 映射到 Kubernetes 服务。

查看 GatewayClass

TensorStack AI 平台默认使用 Cilium 作为控制器实现 Gateway API 功能，所创建的 GatewayClass 如下：

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cilium
spec:
  controllerName: io.cilium/gateway-controller

HTTP 示例

针对 Service 文档中创建的 nginx 服务，如果你想通过 HTTP 协议访问，可创建如下 Gateway 和 HTTPRoute：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: cilium
  listeners:
  - protocol: HTTP
    port: 80
    name: web-gw
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-route-nginx
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /test
    backendRefs:
    - name: nginx-service
      port: 80

其中 my-gateway 的 /test 路径将被转发到 nginx-service 这个 Service。

通过以下命令查看该 Gateway 的 IP 地址为 100.1.2.3：

$ kubectl get gateway my-gateway
NAME         CLASS    ADDRESS      PROGRAMMED   AGE
my-gateway   cilium   100.1.2.3    True         13d

因此，可以通过以下命令访问 nginx-service 服务：

curl -G http://100.1.2.3/test

HTTPS 示例

针对 Service 文档中创建的 nginx 服务，如果你想通过 HTTPS 协议访问，可创建如下 Gateway 和 HTTPRoute：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-gateway
spec:
  gatewayClassName: cilium
  listeners:
  - name: https-1
    protocol: HTTPS
    port: 443
    hostname: "example.com"
    tls:
      certificateRefs:
      - kind: Secret
        name: demo-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: https-route-nginx
spec:
  parentRefs:
  - name: tls-gateway
  hostnames:
  - "example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /test
    backendRefs:
    - name: nginx-service
      port: 80

其中：

• tls-gateway 设置了域名为 example.com，存储证书的 Secret 为 demo-cert，你需要在该 Secret 中存储 example.com 的 TLS 证书；
• tls-gateway 的 /test 路径将被转发到 nginx-service 这个 Service。

通过以下命令查看该 Gateway 的 IP 地址为 100.1.2.3：

$ kubectl get gateway tls-gateway
NAME          CLASS    ADDRESS      PROGRAMMED   AGE
tls-gateway   cilium   100.1.2.3    True         13d

你需要配置 DNS 解析，将域名 example.com 解析到 IP 地址 100.1.2.3。然后可以通过以下命令访问 nginx-service 服务：

curl -G https://example.com/test

下一步

• 查看 Gateway API 官方文档
• 了解 Gateway API 相关资源定义
• 了解 如何从 Ingress 迁移至 Gateway API

辅助

辅助性资源负责为 Apps 提供其他支持，或者为用户提供实用功能。下表总结了所有辅助性资源：

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 类型

Secret 有多种类型，分别适用于存储不同类型的敏感数据，并通过 label tensorstack.dev/resource 进行标识，具体类型如下表所示：

例如：

• SSH Public Key 类型的 Secret 可用于部分 App 的 SSH 访问
• Docker 类型的 Secret 可用于 ImageBuilder 构建并上传镜像
• S3-cfg 类型的 Secret 可用于创建 S3 类型的 StorageShim
• Ceph Client 类型的 Secret 可用于创建 CephFS 类型的 StorageShim

下一步

• 了解 Secret 的概念
• 了解 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 的定义
• 学习如何管理 ConfigMap

ServiceAccountToken

平台提供 CRD ServiceAccountToken，用于生成一个 kubeconfig，以便用户从本地通过 kubectl 访问集群。

创建 ServiceAccountToken

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

apiVersion: tensorstack.dev/v1beta1
kind: ServiceAccountToken
metadata:
  name: sat-sample
spec:
  duration: 1h

在该例中，创建一个有效期为 1h（由 spec.duration 字段指定）的 ServiceAccountToken。系统将会生成一个 JSON 网络令牌（JSON Web Token）和一个 kubeconfig，你可以使用它们作为凭证来访问集群。

有效期设置

spec.duration 字段定义 ServiceAccountToken 的有效期：

• 类型是 string，并且需要匹配正则表达式 ^(0|(([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?)$。
• 支持的时间单位：y, w（周）, d, h, m, s。
• 示例：“3w”，“2h45m”。

状态

Secret 名称

ServiceAccountToken 创建后，系统同步创建的 token 和 kubeconfig 存储在一个 Secret 中，并将 Secret 名称记录在 status.secretRef.name 中：

status:
  secretRef:
    name: sat-sample-fced8

Secret sat-sample-fced8 存储以下两个键值对：

• token：表示一个 ServiceAccount token，你可以在 HTTP 请求头中以 Authorization: Bearer <token> 的形式使用。
• kubeconfig：表示一个 kubeconfig 文件内容，你可以将该内容保存到本地路径下，并在 kubectl 命令中通过 --kubeconfig 参数指定文件路径使用。

通过如下命令将 kubeconfig 保存到本地并使用：

kubectl get secret sat-sample-fced8 -o jsonpath='{.data.kubeconfig}' | base64 -d > mykubeconfig
kubectl --kubeconfig mykubeconfig get pod

过期时间

ServiceAccountToken 创建后，token 的实际过期时间记录在 status.expirationTime 中：

status:
  expirationTime: "2024-05-10T04:11:41Z"

在该例中，ServiceAccountToken 将在 2024-05-10T04:11:41Z（即北京时间 2024-05-10 12:11:41）过期。

ServiceAccountToken 状态

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

• Ready：ServiceAccountToken 准备就绪，处于可用状态。

下面是一个状态信息的示例：

status:
  conditions:
  - lastTransitionTime: "2024-05-10T02:51:41Z"
    message: All subresources are ready
    reason: SubresourcesReady
    status: "True"
    type: Ready

在该例中，所有子资源均就绪，ServiceAccountToken 是可用的。

参考

• API 参考：ServiceAccountToken

T9k Job

TensorStack AI 平台定义了一系列 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 资源，支持各种并行计算场景。
  • GenericJob 十分灵活，用户可以使用 GenericJob 实现 MPIJob、PyTorchTrainingJob 等特定功能的 T9k Job；但其自动化程度低，需要手工设置很多参数。
  • GenericJob 的目的是提供一个总是可行的 “通用” 机制，以支持一些其他特定功能 T9k Job 还未支持的新的计算场景。

运行模式

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

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

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

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

GenericJob

GenericJob 是最基本的 T9k Job 资源。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.replicaSpecs[*].template 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.replicaSpecs[*].template.spec.containers[*].resources 字段指定。

GenericJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，GenericJob 中每个 worker 副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: GenericJob
metadata:
  name: generic-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - resources:
              limits:
                cpu: 4
                memory: 4Gi
              requests:
                cpu: 2
                memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 GenericJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: GenericJob
metadata:
  name: generic-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - ...
            volumeMounts:
              - mountPath: /dev/shm
                name: dshm
          volumes:
          - name: dshm
            emptyDir:
              medium: Memory
              sizeLimit: "1Gi"

在该例中：

• 在 spec.replicaSpecs[*].template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.replicaSpecs[*].template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.replicaSpecs[*].template.spec.containers[*].env 字段指定。GenericJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，GenericJob 给 worker 副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: GenericJob
metadata:
  name: generic-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
            - env:
              - name: ENV_DIRECT
                value: env-value
              - name: ENV_REFERENCED
                valueFrom:
                  secretKeyRef:
                    name: secret-name
                    key: key-in-secret

变量替换

在副本的配置信息中有时需要传入副本自身或其他副本的信息，包括序号、类型和副本的服务地址等。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 的成功和失败条件是通过 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 成功或失败后，控制器清理所创建的 Kubernetes 资源，使 GenericJob 不再浪费集群资源（内存、CPU 等）。GenericJob 提供三种策略，通过 spec.cleanUpPolicy 字段指定：

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

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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: "2024-09-09T09:56:52Z"
    message: The job has been initialized successfully.
    reason: '-'
    status: "True"
    type: Initialized
  - lastTransitionTime: "2024-09-09T09:57:23Z"
    message: 'The job is failed with rule: {"worker":["0"]}'
    reason: Failed
    status: "False"
    type: Running
  - lastTransitionTime: "2024-09-09T09:57:23Z"
    message: 'The job is failed with rule: {"worker":["0"]}'
    reason: Failed
    status: "True"
    type: Failed
  - lastTransitionTime: "2024-09-09T09:57:23Z"
    message: 'The job is failed with rule: {"worker":["0"]}'
    reason: Failed
    status: "True"
    type: Completed
  - lastTransitionTime: "2024-09-09T09:57:21Z"
    message: Pod[job-sample-8961e-worker-0] exited with error code 127
    reason: ErrorInPod
    status: "True"
    type: ReplicaFailure
  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 字段指定）。

副本设置

PyTorchTrainingJob 副本运行环境和命令可以通过 spec.replicaSpecs[*].template 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.replicaSpecs[*].template.spec.containers[*].resources 字段指定。

PyTorchTrainingJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，PyTorchTrainingJob 中每个 worker 副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: pytorch-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - resources:
              limits:
                cpu: 4
                memory: 4Gi
              requests:
                cpu: 2
                memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 PyTorchTrainingJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: pytorch-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - ...
            volumeMounts:
              - mountPath: /dev/shm
                name: dshm
          volumes:
          - name: dshm
            emptyDir:
              medium: Memory
              sizeLimit: "1Gi"

在该例中：

• 在 spec.replicaSpecs[*].template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.replicaSpecs[*].template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.replicaSpecs[*].template.spec.containers[*].env 字段指定。PyTorchTrainingJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，PyTorchTrainingJob 给 worker 副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: PyTorchTrainingJob
metadata:
  name: pytorch-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
            - env:
              - name: ENV_DIRECT
                value: env-value
              - name: ENV_REFERENCED
                valueFrom:
                  secretKeyRef:
                    name: secret-name
                    key: key-in-secret

重启机制

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）来设置副本的最大重启次数。重启次数为所有副本共享，即所有副本重启次数累计达到此数值后，副本将不能再次重启。

使用 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）并不代表实际训练规模，当集群资源数量不足时，控制器可能无法创建足够的副本。

在训练启动后，用户可以在 [4,10] 之间调整期望训练规模。

最佳实践

...
spec:
  torchrunConfig:
    enabled: false
    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 提供清除策略，在训练结束后删除这些副本。

PyTorchTrainingJob 提供以下三种策略：

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

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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

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[*].template 字段指定，此处的填写方式参考 PodTemplate）。
• 当副本失败后，会自动重启（由 spec.replicaSpecs[*].restartPolicy 字段指定）。

副本的类型

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

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

副本设置

TensorFlowTrainingJob 副本运行环境和命令可以通过 spec.replicaSpecs[*].template 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.replicaSpecs[*].template.spec.containers[*].resources 字段指定。

TensorFlowTrainingJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，TensorFlowTrainingJob 中每个 worker 副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: TensorFlowTrainingJob
metadata:
  name: tensorflow-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - resources:
              limits:
                cpu: 4
                memory: 4Gi
              requests:
                cpu: 2
                memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 TensorFlowTrainingJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: TensorFlowTrainingJob
metadata:
  name: tensorflow-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - ...
            volumeMounts:
              - mountPath: /dev/shm
                name: dshm
          volumes:
          - name: dshm
            emptyDir:
              medium: Memory
              sizeLimit: "1Gi"

在该例中：

• 在 spec.replicaSpecs[*].template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.replicaSpecs[*].template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.replicaSpecs[*].template.spec.containers[*].env 字段指定。TensorFlowTrainingJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，TensorFlowTrainingJob 给 worker 副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: TensorFlowTrainingJob
metadata:
  name: tensorflow-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
            - env:
              - name: ENV_DIRECT
                value: env-value
              - name: ENV_REFERENCED
                valueFrom:
                  secretKeyRef:
                    name: secret-name
                    key: key-in-secret

重启机制

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

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

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

清除策略

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

TensorFlowTrainingJob 提供以下三种策略：

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

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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

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.worker.template 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.worker.template.spec.containers[*].resources 字段指定。

DeepSpeedJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，DeepSpeedJob 中每个副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: DeepSpeedJob
metadata:
  name: deepspeed-example
spec:
  worker:
    replicas: 4
    template:
      spec:
        containers:
        - resources:
            limits:
              cpu: 4
              memory: 4Gi
            requests:
              cpu: 2
              memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 DeepSpeedJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: DeepSpeedJob
metadata:
  name: deepspeed-example
spec:
  worker:
    replicas: 4
    template:
      spec:
        containers:
        - ...
          volumeMounts:
            - mountPath: /dev/shm
              name: dshm
        volumes:
        - name: dshm
          emptyDir:
            medium: Memory
            sizeLimit: "1Gi"

在该例中：

• 在 spec.worker.template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.worker.template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.worker.template.spec.containers[*].env 字段指定。DeepSpeedJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，DeepSpeedJob 给副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: DeepSpeedJob
metadata:
  name: deepspeed-example
spec:
  worker:
    replicas: 4
    template:
      spec:
        containers:
          - env:
            - name: ENV_DIRECT
              value: env-value
            - name: ENV_REFERENCED
              valueFrom:
                secretKeyRef:
                  name: secret-name
                  key: key-in-secret

训练配置

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：只删除未结束的副本。

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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: "2023-11-20T08:25:09Z"
    message: The job has been initialized successfully.
    reason: '-'
    status: "True"
    type: Initialized
  - lastTransitionTime: "2023-11-22T03:14:05Z"
    message: 'DeepSpeedJob baichuan2-sft has failed: baichuan2-sft-worker-0 failed
      with exit code 137'
    reason: Failed
    status: "False"
    type: Running
  - lastTransitionTime: "2023-11-22T03:14:05Z"
    message: 'DeepSpeedJob baichuan2-sft has failed: baichuan2-sft-worker-0 failed
      with exit code 137'
    reason: Failed
    status: "True"
    type: Failed
  - lastTransitionTime: "2023-11-22T03:14:05Z"
    message: 'DeepSpeedJob baichuan2-sft has failed: baichuan2-sft-worker-0 failed
      with exit code 137'
    reason: Failed
    status: "True"
    type: Completed
  - lastTransitionTime: "2023-11-22T03:14:05Z"
    message: 'DeepSpeedJob baichuan2-sft has failed: baichuan2-sft-worker-0 failed
      with exit code 137'
    reason: Failed
    status: "True"
    type: ReplicaFailure
  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
  torchConfig:
    procPerWorker: 1
    script:
      - train.py
      - arg1
  replicaSpecs:
  - type: launcher
    template:
      spec:
        containers:
        - name: launcher
          image: hpcaitech/colossalai:0.3.0
          workingDir: /workspace
          resources: 
            limits:
              cpu: 1
              memory: 2Gi
            requests:
              cpu: 500m
              memory: 1Gi
  - type: worker
    replicas: 2
    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.replicaSpecs 数组中 type 为 launcher 的部分指定）。
• 创建 2 个执行副本，每个执行副本上启动 1 个训练进程，训练脚本和参数为 train.py arg1，执行副本的其他配置参考 PodTemplate，这里不再赘述（Pod Template 配置和副本数量由 spec.replicaSpecs 数组中 type 为 worker 的部分指定，其他训练配置由 spec.torchConfig 字段指定）。
• 执行副本需要执行 sshd 程序，等待启动副本发来训练指令。sshd 的路径为 /user/sbin/sshd（由 spec.ssh.sshdPath 字段指定，使用该字段的原因是 sshd 程序必须使用绝对路径调用，所以需要其具体路径）。

副本设置

ColossalAIJob 副本运行环境和命令可以通过添加 worker 类型的 spec.replicaSpecs 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.replicaSpecs[worker].template.spec.containers[*].resources 字段指定。

ColossalAIJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，ColossalAIJob 中每个副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: ColossalAIJob
metadata:
  name: colossalai-example
spec:
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
        - resources:
            limits:
              cpu: 4
              memory: 4Gi
            requests:
              cpu: 2
              memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 ColossalAIJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: ColossalAIJob
metadata:
  name: colossalai-example
spec:
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
        - ...
          volumeMounts:
            - mountPath: /dev/shm
              name: dshm
        volumes:
        - name: dshm
          emptyDir:
            medium: Memory
            sizeLimit: "1Gi"

在该例中：

• 在 spec.replicaSpecs[worker].template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.replicaSpecs[worker].template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.replicaSpecs[worker].template.spec.containers[*].env 字段指定。ColossalAIJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，ColossalAIJob 给副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: ColossalAIJob
metadata:
  name: colossalai-example
spec:
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
          - env:
            - name: ENV_DIRECT
              value: env-value
            - name: ENV_REFERENCED
              valueFrom:
                secretKeyRef:
                  name: secret-name
                  key: key-in-secret

重启机制

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

成功和失败

在 ColossalAIJob 分布式训练框架中：

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

清除策略

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

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

...
spec:
  runPolicy:
    cleanUpWorkers: true

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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。

...
status:
  conditions:
  - lastTransitionTime: "2024-09-10T02:01:36Z"
    message: The job has been initialized successfully.
    reason: '-'
    status: "True"
    type: Initialized
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully.
    reason: Succeeded
    status: "False"
    type: Running
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully.
    reason: Succeeded
    status: "False"
    type: Failed
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully.
    reason: Succeeded
    status: "True"
    type: Completed
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully
    reason: Finished
    status: "False"
    type: ReplicaFailure
  phase: Succeeded

副本的状态

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[*].template 字段指定，此处的填写方式参考 PodTemplate）。
• 当副本失败后，会自动重启（由 spec.replicaSpecs[*].restartPolicy 字段指定）。

副本设置

XGBoostTrainingJob 副本运行环境和命令可以通过 spec.replicaSpecs[*].template 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.replicaSpecs[*].template.spec.containers[*].resources 字段指定。

XGBoostTrainingJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，XGBoostTrainingJob 中每个 worker 副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: XGBoostTrainingJob
metadata:
  name: xgboost-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - resources:
              limits:
                cpu: 4
                memory: 4Gi
              requests:
                cpu: 2
                memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 XGBoostTrainingJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: XGBoostTrainingJob
metadata:
  name: xgboost-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
          - ...
            volumeMounts:
              - mountPath: /dev/shm
                name: dshm
          volumes:
          - name: dshm
            emptyDir:
              medium: Memory
              sizeLimit: "1Gi"

在该例中：

• 在 spec.replicaSpecs[*].template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.replicaSpecs[*].template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.replicaSpecs[*].template.spec.containers[*].env 字段指定。XGBoostTrainingJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，XGBoostTrainingJob 给 worker 副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: XGBoostTrainingJob
metadata:
  name: xgboost-example
spec:
  replicaSpecs:
    - type: worker
      replicas: 4
      template:
        spec:
          containers:
            - env:
              - name: ENV_DIRECT
                value: env-value
              - name: ENV_REFERENCED
                valueFrom:
                  secretKeyRef:
                    name: secret-name
                    key: key-in-secret

重启机制

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 字段来设置副本的最大重启次数。重启次数为所有副本共享，即所有副本重启次数累计达到此数值后，副本将不能再次重启。

成功和失败

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

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

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

清除策略

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

XGBoostTrainingJob 提供以下三种策略：

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

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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:
  mpiConfig:
    home: /usr/local
    mca:
      btl: ^openib
    extraArgs:
      - -N
      - "3"
      - --enable-recovery
      - --max-restarts
      - "100"
      - --allow-run-as-root
      - -bind-to
      - none
    script:
      - ./random_walk
      - "20"
      - "40"
      - "2"
  ssh:
    sshdPath: /usr/sbin/sshd
  runPolicy:
    cleanUpWorkers: true
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
          - name: worker
            image: t9kpublic/mpi-tutorial:2021022-2
            resources:
              limits:
                cpu: 100m
              requests:
                cpu: 50m
            workingDir: /usr/local/code
  - type: launcher
    replicas: 1
    template: {}

在该例中：

• 创建 5 个执行副本（由 spec.replicaSpecs 数组中 type 为 worker 的部分指定）。
• spec.replicaSpecs[*].template 字段沿用 PodTemplate 的规约，配置执行副本和启动副本的环境。
• 在执行副本准备完毕后，启动副本向执行副本发送启动命令，令执行副本创建 3 个 MPI 进程，这些进程分别执行 ./random_walk 20 40 2（由 spec.mpiConfig.script 字段指定）命令。
• 在训练过程中不使用 Infiniband 进行通信（由 spec.mpiconfig.mca.btl 字段指定）。
• 在训练结束后自动清除副本（由 spec.runPolicy.cleanUpWorkers 字段指定）来释放集群资源。
• sshd 的路径为 /user/sbin/sshd（由 spec.ssh.sshdPath 字段指定，使用该字段的原因是 sshd 程序必须使用绝对路径调用，所以需要其具体路径）。
• MPI 安装在 /usr/local 处（由 spec.mpiConfig.home 字段指定，使用该字段的原因是 mpirun 的有些功能需要知道 MPI 的根目录地址才能正确运行）。

运行 Horovod 训练脚本

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

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

1. 在 spec.replicaSpecs[worker].template.spec.containers[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
  replicaSpecs:
  - type: worker
    template:
      spec:
        containers:
          - name: worker
            env: 
            - name: "NCCL_DEBUG"
              value: "INFO"
...

副本设置

MPIJob 副本运行环境和命令可以通过 spec.replicaSpecs[worker].template 进行配置，可配置内容包括镜像、运行命令、资源配置、环境变量等。

资源配置

副本资源配置通过 spec.replicaSpecs[worker].template.spec.containers[*].resources 字段指定。

MPIJob 的资源配置包括两部分：

• 资源请求量（requests）：创建该副本时，节点上至少应具有这些数量的资源。如果集群中所有节点都不满足副本的资源请求量，则副本的创建可能会被阻塞；或者如果副本的优先级较高，则有可能驱逐节点上其他工作负载来为副本空出可用的资源。
• 资源上限（limits）：该副本在运行期间，最多可以使用的资源数量。比如：如果副本在运行时申请分配超过上限的内存，则有可能出现 OOMKILLED 错误。（注：资源上限不能小于资源请求量）

在下面的示例中，MPIJob 中每个副本设置了以下资源配置：

• 资源请求量：2 个 cpu 核心、2Gi 内存；
• 资源上限：4 个 cpu 核心、4Gi 内存。

apiVersion: batch.tensorstack.dev/v1beta1
kind: MPIJob
metadata:
  name: mpi-example
spec:
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
        - resources:
            limits:
              cpu: 4
              memory: 4Gi
            requests:
              cpu: 2
              memory: 2Gi

共享内存

在进行多节点任务时，可以按照如下方式修改 MPIJob 来使用共享内存：

apiVersion: batch.tensorstack.dev/v1beta1
kind: MPIJob
metadata:
  name: mpi-example
spec:
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
        - ...
          volumeMounts:
            - mountPath: /dev/shm
              name: dshm
        volumes:
        - name: dshm
          emptyDir:
            medium: Memory
            sizeLimit: "1Gi"

在该例中：

• 在 spec.replicaSpecs[worker].template.spec.volumes 中增加一项，名称为 dshm，其中限制共享内存最大为 1Gi；
• 在 spec.replicaSpecs[worker].template.spec.containers[*].volumeMounts 中增加一项，将上述 dshm 绑定到 /dev/shm 路径。

环境变量

副本环境变量通过 spec.replicaSpecs[worker].template.spec.containers[*].env 字段指定。MPIJob 支持直接设置环境变量内容和引用其他资源字段作为环境变量两种方式。

在下面的示例中，MPIJob 给副本设置了两个环境变量：ENV_DIRECT 和 ENV_REFERENCED。其中 ENV_DIRECT 环境变量被直接设置为 env-value，ENV_REFERENCED 环境变量引用了 secret-name Secret 的 key-in-secret 字段的内容。

apiVersion: batch.tensorstack.dev/v1beta1
kind: MPIJob
metadata:
  name: mpi-example
spec:
  replicaSpecs:
  - type: worker
    replicas: 4
    template:
      spec:
        containers:
          - env:
            - name: ENV_DIRECT
              value: env-value
            - name: ENV_REFERENCED
              valueFrom:
                secretKeyRef:
                  name: secret-name
                  key: key-in-secret

调试模式

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[*].template 中的命令。
  • 如果不填写 spec.runMode.pause.resumeSpecs 字段，则表示所有副本都使用默认设置。

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

在下面的示例中：

• 示例一：开启了暂停模式，并配置 worker 跳过 InitContainer，并执行 /usr/bin/sshd。
• 示例二：开启了暂停模式，副本使用默认恢复设置，即不跳过 InitContainer，并执行 spec.replicaSpecs[*].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。

...
status:
  conditions:
  - lastTransitionTime: "2024-09-10T02:01:36Z"
    message: The job has been initialized successfully.
    reason: '-'
    status: "True"
    type: Initialized
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully.
    reason: Succeeded
    status: "False"
    type: Running
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully.
    reason: Succeeded
    status: "False"
    type: Failed
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully.
    reason: Succeeded
    status: "True"
    type: Completed
  - lastTransitionTime: "2024-09-10T02:01:51Z"
    message: The job has finished successfully
    reason: Finished
    status: "False"
    type: ReplicaFailure
  phase: Succeeded

副本的状态

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
...

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
...

T9k Service

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:
      secretRef:
        name: s3-secret
      uri: s3://models/mnist/
      mountPath: /var/lib/t9k/model
  tensorflow:
    image: t9kpublic/tensorflow-serving:2.6.0
    resources: 
      requests:
        cpu: 1
        memory: 1Gi

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

• replicas: 定义运行推理服务的副本数量是 1。
• storage.s3: 设定使用 S3 存储模型，子字段的释义如下：
  • secretRef.name: Secret s3-secret 中存储 S3 配置信息，其详情参见：创建 S3 Secret。
  • uri: 模型在 S3 中的存储标识是 s3://models/mnist/。
  • mountPath: 模型被加载后，在容器中存储模型的文件系统路径是 /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:
      secretRef:
        name: s3-secret
      uri: s3://models/mnist/
      mountPath: /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.replicas 设置为 0 时，可以在不删除 SimpleMLService 的情况下暂停服务。

暴露服务

通过设置 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。

模型存储

通过 spec.storage 字段可以设置 SimpleMLService 的模型存储信息，详情请见模型存储。

服务状态

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：定义前处理（pre-processing）和后处理（post-processing）计算。

MLService 的主要特性包括：

• 支持定义多个版本（release）的推理服务，每个 release 定义了下列内容：
  • 名称：推理服务的版本名称
  • 模型存储（storage）
  • 模型规约（model），包括 parameters，runtime（引用 MLServiceRuntime 定义运行推理服务 Pod 的模板）
  • 计算资源（containersResources）
  • 其他部署参数（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
        storage:
          pvc:
            name: tutorial
            subPath: tutorial-examples/deployment/pvc/mlservice-torch/
        containersResources:
        - name: user-container
          resources:
            limits:
              cpu: "500m"
              memory: 1Gi

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
      storage:
        pvc:
          name: <pvc-name>
          subPath: <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
      storage:
        pvc:
          name: <pvc-name>
          subPath: <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
      storage:
        pvc:
          name: <pvc-name>
          subPath: <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 等其余设置都会被保留。

计算资源

MLServiceRuntime 定义了 Pod 模板，但对于容器的资源要求，不同场景之间存在差异。因此， MLServiceRuntime 中定义的容器资源要求只是一个缺省时的默认值。

用户可以直接在 MLService predictor 中的 containersResources 定义容器的资源要求，例如：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: demo
spec:
  default: version1
  releases:
  - name: version1
    predictor:
      model:
        modelFormat:
          name: pytorch
      storage:
        pvc:
          name: <pvc-name>
          subPath: <model-path>
      containersResources:
      - name: user-container
        resources:
          limits:
            cpu: "500m"
            memory: 1Gi

模型存储

你可以为 release 和 transformer 定义模型存储：

1. 通过 spec.releases[*].predictor.storage 可以设置当前 release 的模型存储信息。
2. 通过 spec.transformer.storage 可以设置 transformer 的模型存储信息。

详情请见模型存储。

Transformer

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

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

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

下文是一个设置了 transformer 的 MLService 示例：

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: pic-mnist
spec:
  default: origin
  transformer:
    minReplicas: 1
    template:
      spec:
        containers:
        - name: user-container
          image: t9kpublic/transformer-example:0.1.0
          resources:
            limits:
              cpu: "500m"
              memory: 500Mi
  releases:
    - name: origin
      predictor:
        minReplicas: 1
        model:
          runtime: t9k-tensorflow-serving
        containersResources:
        - name: user-container
          resources:
            limits:
              cpu: "500m"
              memory: 500Mi
        storage:
          pvc:
            name: tutorial
            subPath: tutorial-examples/deployment/mlservice/transformer/model

全局路由配置

MLService 提供了一个全局的 URL，用户可以通过这个 URL 来访问 MLService 部署的推理服务(详情见访问推理服务)。当用户向这个 URL 发送请求时，MLService 会根据全局路由配置将用户请求转发到对应版本的推理服务。

全局路由配置最多可以设置两个版本（release）的推理服务来处理用户请求，其中一个推理服务版本作为默认版本，另一个推理服务版本作为金丝雀版本：

1. 默认版本：必需。将 spec.default 字段设置为 release 名称来表明将哪个 release 设置为路由的默认版本。
2. [可选]金丝雀版本：将 spec.canary 字段设置为 release 名称来表明将哪个 release 设置为路由的金丝雀版本。设置金丝雀版本的同时，你必须设置 spec.canaryTrafficPercent 字段，来配置金丝雀版本的路由权重。

下面是一个 MLService 示例，在这个示例中：

1. 部署了 3 个版本的推理服务，版本名称分别是：nov-02，nov-05，nov-11。
2. 全局路由配置：nov-02 设置为路由的默认版本，路由权重是 80%；nov-11 设置为路由的金丝雀版本，路由权重是 20%。

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

更多配置

发布策略

多版本支持

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

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

apiVersion: tensorstack.dev/v1beta1
kind: MLService
metadata:
  name: multi-releases
spec:
  default: nov-02
  releases:
  - name: nov-02
    predictor:
      model:
        runtime: torchserve
      storage:
        pvc:
          name: tutorial
          subPath: model-11-02
  - name: nov-05
    predictor:
      model:
        runtime: torchserve
      storage:
        pvc:
          name: tutorial
          subPath: model-11-05
  - name: nov-11
    predictor:
      model:
        runtime: torchserve
      storage:
        pvc:
          name: tutorial
          subPath: 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 支持对预测请求进行日志收集，详情见日志收集

容量伸缩

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
      predictor:
        minReplicas: 1
        maxReplicas: 3
        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 的状态字段可以获取如下信息：

• 推理服务的全局状态及服务地址：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 中也会有相关的错误信息。

访问推理服务

有两种访问推理服务的方式：

1. 通过全局 URL 访问全局路由配置中设置的推理服务。
2. 通过某个版本的推理服务对应的 URL 来访问这个版本的推理服务。

全局 URL

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

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

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

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

$ curl http://torch-mnist.<project>.<domain>/ping
{
  "status": "Healthy"
}

并调用推理服务：

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

单版本 URL

MLService 部署成功后，通过状态字段 status.releases 可以查看每个版本的推理服务对应的 Base URL。

下面的是 status.releases 示例，这个 MLService 中部署了 3 个版本的推理服务，版本名称分别是：v1、v2、v3。

status:
  releases:
  - name: v1
    ready: true
    readyReplicas: 1
    totalReplicas: 1
    trafficPercent: 50
    url: http://torch-mnist-s3-predict-v1.<project>.<domain>
  - name: v2
    ready: true
    readyReplicas: 1
    totalReplicas: 1
    trafficPercent: 50
    url: http://torch-mnist-s3-predict-v2.<project>.<domain>
  - name: v3
    ready: true
    readyReplicas: 1
    totalReplicas: 1
    trafficPercent: 0
    url: http://torch-mnist-s3-predict-v3.<project>.<domain>

运行下列命令可以查看 v1 版本的推理服务的运行状态：

$ curl http://torch-mnist-s3-predict-v1.<project>.<domain>/ping
{
  "status": "Healthy"
}

参考

• 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
       containersResources:
       - name: user-container
         resources:
           limits:
             cpu: "500m"
             memory: 1Gi
        storage:
          pvc:
            name: tutorial
            subPath: tutorial-examples/deployment/mlservice/torch-pvc

然后按照 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 源码

模型存储

AI 模型可以存储在集群的文件系统里，或者 S3 对象存储服务中。

SimpleMLService 和 MLService 采用相同的方式指定模型的存储细节，用户可以明确、方便地指定模型在集群文件系统或者 S3 对象存储服务中的位置，并设置模型在容器中的挂载路径。

文件系统

通过配置 storage.pvc 字段可以通过 PVC 使用集群文件系统中的模型。storage.pvc 字段包含下列子字段：

• name: 存储模型数据的 PVC 的名称。
• subPath: 模型在 PVC 中的路径，不可以是绝对路径（即开头不能是 /）。
• mountPath: 模型在容器中的挂载路径，必须是绝对路径。未设置时，默认值是 /var/lib/t9k/model。

示例如下：

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

在上述示例中：

• PVC 名称是 demo。
• 模型在 PVC 中的路径是 path/mnist。
• 模型会被挂载到容器的路径 /var/lib/custom 下。

S3

当使用 S3 服务存储的模型数据时：

• SimpleMLService/MLService 需要先通过 initContainer 下载模型数据到容器本地，然后才能供给推理服务使用。如果下载失败，则推理服务无法启动。
• 当 SimpleMLService/MLService 设置了多个副本时，每个副本都需要单独下载模型数据，副本间无法共享模型数据。

如果用户想使用存储在 S3 服务中的模型数据，需要：

1. 创建存储 S3 服务信息的 Secret
2. 设置 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: aG9zdF9iYXNlID0gczMuYXAtZWFzdC0xLmFtYXpvbmF3cy5jb20KaG9zdF9idWNrZXQgPSBleGFtcGxlLnMzLmFwLWVhc3QtMS5hbWF6b25hd3MuY29tCmJ1Y2tldF9sb2NhdGlvbiA9IGFwLWVhc3QtMQp1c2VfaHR0cHMgPSBGYWxzZQphY2Nlc3Nfa2V5ID0gdXNlcgpzZWNyZXRfa2V5ID0gcGFzc3dvcmQKc2lnbmF0dXJlX3YyID0gRmFsc2U=

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

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

设置 storage.s3

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

• secretRef: 记录存储 S3 配置信息的 Secret。该字段有下列子字段：
  • name：Secret 名称。
• uri: 模型在 S3 中的存储标识。
• mountPath: 模型在容器中的挂载路径，必须是绝对路径。未设置时，默认值是 /var/lib/t9k/model。

示例如下：

storage:
  s3:
    secretRef:
      name: s3-secret
    uri: s3://models/mnist/
    mountPath: /var/lib/custom

在上述示例中：

• Secret s3-secret 存储着 S3 配置信息。
• 模型在 S3 中的存储标识是 s3://models/mnist/。
• 模型会被挂载到容器的路径 /var/lib/custom 下。

存储类型比较

使用 PVC 存储模型数据：

• 优点：
  • 挂载速度快
  • 多副本可以共享 PVC 数据
• 缺点：
  • 需要提前创建 PVC，并在 PVC 中准备好模型数据

使用 S3 存储模型数据：

• 优点：
  • 只需简单设置，就能 S3 服务存储的模型数据
  • 跨项目共享使用模型很方便
• 缺点：
  • S3 中的模型需要先被下载才能使用，启动时间一般较长
  • 多副本间无法共享模型数据，每个副本都需要从 S3 下载模型数据

参考

• S3
• s3cmd
• PVC
• API 参考：Storage in MLService
• API 参考：Storage in SimpleMLService

工作流

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 Job 之一，系统将自动帮助填写 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 Job WorkflowTemplate

T9k Workflow 系统对 T9k Job 提供更进一步的原生支持，添加以下 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

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 pod -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。

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 支持对多种训练框架进行超参数的调优，包括 TensorFlow、PyTorch 和 XGBoost。

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

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

搜索空间

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
metadata:
  name: experiment-sample
spec:
  ...
  searchSpace: |-
    {
      "batch_size": {"_type": "choice", "_value": [512, 1024, 2048, 4096, 8092]},
      "learning_rate": {"_type": "choice", "_value": [0.0001, 0.001, 0.01, 0.1]}
    }
  ...

在上述示例中，实验要选择 batch_size 和 learning_rate 两个超参数，二者的搜索范围分别是 [512, 1024, 2048, 4096, 8092] 和 [0.0001, 0.001, 0.01, 0.1]。

格式

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

在上述结构中：

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

搜索方法

超参数调优算法

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

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  tuner:
    builtinTunerName: "Anneal"
    classArgs: |-
      {
        "optimize_mode": "minimize", 
        "constant_liar_type": "min"
      }
  assessor:
    builtinAssessorName: "Medianstop"
    classArgs: |-
      {
        "optimize_mode": "maximize",
        "start_step": 0
      }

在上述示例中，实验使用 Anneal 算法选择超参数，使用 Medianstop 算法来判断是否中止试验。

Tuner 算法

HyperOpt 类算法

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

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  tuner:
    builtinTunerName: "Anneal"
    classArgs: |-
      {
        "optimize_mode": "minimize", 
        "constant_liar_type": "min"
      }

Evolution

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  tuner:
    builtinTunerName: "Evolution"
    classArgs: |-
      {
        "optimize_mode": "minimize", 
        "population_size": 32
      }

Batch

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  searchSpace: |-
    {
      "learning_rate": {"_type": "choice", "_value": [0.0001, 0.001, 0.01, 0.1]}
    }
  tuner:
    builtinTunerName: "Batch"
    classArgs: |-
      {
        "optimize_mode": "minimize", 
        "population_size": 32
      }

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

GridSearch

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

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  tuner:
    builtinTunerName: "GridSearch"

MetisTuner

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

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  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 是一种能够极大减少超参数优化步骤的贝叶斯优化算法。算法的详细介绍请参阅 GPTuner 文档。

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  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 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  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 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  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 字段包含当前算法所有参数，有些参数在实际使用中可以选择不指定）：

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  assessor:
    builtinAssessorName: "Medianstop"
    classArgs: |-
      {
        "optimize_mode": "maximize",
        "start_step": 0
      }

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

Curvefitting

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

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

apiVersion: tensorstack.dev/v1beta1
kind: AutoTuneExperiment
spec:
  assessor:
    builtinAssessorName: "Curvefitting"
    classArgs: |-
      {
        "optimize_mode": "minimize",
        "epoch_num": 20,
        "start_step": 6,
        "threshold": 0.95,
        "gap": 1
      }

实验状态

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

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

ImageBuilder

平台提供 CRD ImageBuilder，用于在集群中构建容器镜像。

创建 ImageBuilder

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

# imagebuilder-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 的详细参考

DataCube

平台提供 CRD DataCube，用于 PVC 和数据存储服务之间的数据传输：

• 下载数据到 PVC。
• 上传数据到 Git、Hugging Face 和 S3 等数据存储服务。

创建 DataCube

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

apiVersion: tensorstack.dev/v1beta1
kind: DataCube
metadata:
  name: git-download
spec:
  source:
    type: git
    options:
    - name: url
      value: https://github.com/owner/repo.git
  sink: 
    type: pvc
    pvc:
      name: datacube-pvc

在该例中，下载（克隆）Git 仓库（repository）https://github.com/user/repo.git（由 spec.source.options 字段指定）到 PVC datacube-pvc（由 spec.sink.pvc.name 字段指定）。

下载数据

设置 PVC

下载数据到 PVC 时，支持自动创建 PVC 和指定 PVC 子目录：

spec:
  sink: 
    type: pvc
    pvc:
      template:
        spec:
          accessModes:
          - ReadWriteMany
          resources:
            requests:
              storage: 100Gi
      name: datacube-pvc
      subPath: dev/git

在该例中，声明创建一个存储容量为 100Gi（由 spec.sink.pvc.template.spec.resources 字段指定）、可多处读写（由 spec.sink.pvc.template.spec.accessModes 字段指定）的 PVC datacube-pvc，并将数据下载到该 PVC 的 dev/git（由 spec.sink.pvc.subPath 字段指定）子目录下。

设置源存储服务

Git

下载（克隆）一个 Git 仓库到 PVC：

spec:
  source:
    type: git
    options:
    - name: token
      valueFrom:
        secretKeyRef:
          name: github-token
          key: token
    - name: url
      value: https://$(TOKEN)@github.com/user/repo.git
    - name: ref
      value: main

在该例中，通过 spec.source.type 字段指定源存储服务类型为 Git，通过 spec.source.options 字段指定源存储服务选项：

• token：个人访问令牌（personal access token），使用 Secret github-token 的键 token 的值，该字段是可选的。
• url：Git 仓库路径，以 $(TOKEN) 引用的形式嵌入 token。
• ref：分支、标签或 commit，下载完成后切换到该 ref。该字段是可选的，默认为 master。

Hugging Face

下载一个 Hugging Face 仓库（repository）或其中的部分文件到 PVC：

spec:
  source:
    type: huggingface
    options:
    - name: token
      valueFrom:
        secretKeyRef:
          name: hf-token
          key: token
    - name: repo
      value: openai/whisper-large-v3
    - name: files
      value: README.md,tokenizer.json,tokenizer_config.json

在该例中，通过 spec.source.type 字段指定源存储服务类型为 Hugging Face，通过 spec.source.options 字段指定源存储服务选项：

• token：Hugging Face token，引用 Secret hf-token 的键 token 的值，该字段是可选的。
• repo：Hugging Face 仓库名称。
• files：下载的文件列表。该字段是可选的，默认下载仓库的所有文件。

S3

下载 S3 的文件或目录到 PVC：

spec:
  source:
    type: s3
    options:
    - name: s3-endpoint
      valueFrom:
        secretKeyRef:
          name: s3-config
          key: endpoint
    - name: s3-access-key-id
      valueFrom:
        secretKeyRef:
          name: s3-config
          key: accessKeyID
    - name: s3-secret-access-key
      valueFrom:
        secretKeyRef:
          name: s3-config
          key: secretAccessKey
    - name: s3-uri
      value: s3://bucket/path/subpath

在该例中，通过 spec.source.type 字段指定源存储服务类型为 S3，通过 spec.source.options 字段指定源存储服务选项：

• s3-endpoint：S3 端点，引用 Secret s3-config 的键 endpoint 的值。
• s3-access-key-id：S3 服务的 AccessKeyID 凭证，引用 Secret s3-config 的键 accessKeyID 的值。
• s3-secret-access-key：S3 服务的 SecretAccessKey 凭证，引用 Secret s3-config 的键 secretAccessKey 的值。
• s3-uri：S3 文件或目录的路径。

上传数据

设置 PVC

上传 PVC 数据：

spec:
  source:
    type: pvc
    pvc:
      name: datacube-pvc
      subPath: dev/hf/whisper-large-v3

在该例中，上传 PVC datacube-pvc 的子路径 dev/hf/whisper-large-v3 到目标存储服务。

设置目标存储服务

Git

上传 PVC 的一个 Git 仓库到目标数据存储服务：

spec:
  source: 
    type: pvc
    pvc:
      name: datacube-pvc
      subPath: dev/git/
  sink:
    type: git
    options:
    - name: token
      valueFrom:
        secretKeyRef:
          name: github-token
          key: token
    - name: url
      value: https://$(TOKEN)@github.com/user/repo.git

在该例中，上传 PVC datacube-pvc 的 dev/git/ 路径下的 repo 目录（由 spec.sink.options 字段指定，其中 url 指向的仓库名称即为目录名称），通过 spec.sink.type 字段指定目标存储服务类型为 Git，通过 spec.sink.options 字段指定目标存储选项：

• token：个人访问令牌（personal access token），引用 Secret github-token 的键 token 的值，该字段是可选的。
• url：Git 仓库路径，以 $(TOKEN) 引用的形式嵌入 token。

Hugging Face

上传 PVC 的文件或目录到 Hugging Face 仓库：

spec:
  sink: 
    type: huggingface
    options:
    - name: token
      valueFrom:
        secretKeyRef:
          name: hf-token
          key: token
    - name: repo
      value: user/repo
    - name: path-in-repo
      value: pvc/demo
    - name: commit-message
      value: Upload files from PVC

在该例中，通过 spec.sink.type 字段指定目标存储服务类型为 Hugging Face，通过 spec.sink.options 字段指定目标存储选项：

• token：Hugging Face token，引用 Secret hf-token 的键 token 的值，该字段是可选的。
• repo：Hugging Face 仓库名称。
• path-in-repo：仓库中的路径，数据将被上传到这里。
• commit-message：提交信息，该字段是可选的。

S3

上传 PVC 的文件或目录到 S3：

spec:
  sink: 
    type: s3
    options:
    - name: s3-endpoint
      valueFrom:
        secretKeyRef:
          name: s3-config
          key: endpoint
    - name: s3-access-key-id
      valueFrom:
        secretKeyRef:
          name: s3-config
          key: accessKeyID
    - name: s3-secret-access-key
      valueFrom:
        secretKeyRef:
          name: s3-config
          key: secretAccessKey
    - name: s3-uri
      value: s3://bucket/path/subpath
    - name: s3-no-check-bucket
      value: "true"

在该例中，通过 spec.sink.type 字段指定目标存储服务类型为 S3，通过 spec.sink.options 字段指定目标存储选项：

• s3-endpoint：S3 端点，引用 Secret s3-config 的键 endpoint 的值。
• s3-access-key-id：S3 服务的 AccessKeyID 凭证，引用 Secret s3-config 的键 accessKeyID 的值。
• s3-secret-access-key：S3 服务的 SecretAccessKey 凭证，引用 Secret s3-config 的键 secretAccessKey 的值。
• s3-uri：S3 路径，上传数据到该路径下。
• s3-no-check-bucket：不检查 bucket 是否存在，当上述凭证不具备检查 bucket 的权限时需要设置，该字段是可选的。

数据传输设置

执行策略

DataCube 支持限制数据传输的失败重试次数，以及每次数据传输的最大执行时间：

spec:
  executor:
    options:
      backoffLimit: 2
      activeDeadlineSeconds: 3600

在该例中：

• 设置最多失败重试 2 次（由 spec.executor.options.backoffLimit 字段指定），重试达到限制次数时，标记该 DataCube 失败；默认为 0，即不执行失败重试。
• 设置每次数据传输最多执行 3600 秒（由 spec.executor.options.activeDeadlineSeconds 字段指定），当本次数据传输达到限制时长时，标记本次数据传输失败，将会进行重试；默认为空，即不限制执行时间。

额外参数

指定数据传输时额外的参数：

spec:
  executor:
    options:
      extraArgs:
      - --cache-dir
      - /tmp/cache/hf

在该例中，通过 spec.executor.options.extraArgs 指定缓存目录 --cache-dir 为 /tmp/cache/hf，适用于下载 Hugging Face 文件。

环境变量

设置数据传输时的环境变量：

spec:
  executor:
    env:
    - name: HTTPS_PROXY
      value: <host>:<port>

在该例中，通过 spec.executor.env 定义了数据传输时的网络代理，表示使用该网络代理进行数据下载或上传。

S3 同步

在下载 S3 数据到 PVC 时，可以设置使用同步模式：

spec:
  executor:
    options:
      sync: true

在该例中，通过 spec.executor.options.sync 定义了使用同步模式，表示完全同步 S3 数据内容到 PVC，会删除 PVC 子目录中多余的文件。

状态

Pod 状态

执行数据传输的 Pod 状态信息记录在 status.pod 中：

status:
  pod:
    phase: Succeeded
    reference:
      name: s3-upload-file-batchjob-h4fsn
      uid: 8789c49a-ce14-4daa-b2d3-46a32a1decec
    status: Completed

DataCube 状态

DataCube 的状态信息记录在 status.conditions 中，包括 3 种类型：

• Initialized：DataCube 已经成功创建 Pod 并正常启动，执行数据传输任务。
• Complete：DataCube 数据传输完成。
• Failed：DataCube 数据传输失败。

下面是一个状态信息的示例：

status:
  conditions:
  - lastProbeTime: "2024-04-25T06:28:45Z"
    lastTransitionTime: "2024-04-25T06:28:45Z"
    message: The DataCube is initialized
    status: "True"
    type: Initialized
  - lastProbeTime: "2024-04-25T06:28:45Z"
    lastTransitionTime: "2024-04-25T06:28:45Z"
    message: The DataCube is complete
    status: "True"
    type: Complete
  - lastProbeTime: "2024-04-25T06:28:45Z"
    lastTransitionTime: "2024-04-25T06:28:38Z"
    status: "False"
    type: Failed

参考

• API 参考：DataCube

计算资源

运行集群中的工作负载需要计算资源。TensorStack AI 平台提供了完善的计算资源分配和管理机制，支持使用 GPU、高速网卡等扩展设备资源，并提供资源使用监控、统计功能帮助用户随时获得工作负载的资源使用情况。

资源请求和限制

资源请求（requests）和限制（limits）是一种管理资源的重要机制，用于确保集群中的工作负载可以按照预期方式使用计算资源。资源请求（由 spec.containers[].resources.requests 字段）定义了工作负载的一个容器所需的最小资源量，资源限制（由 spec.containers[].resources.limits 字段）则定义了该容器所允许使用的最大资源量。集群的调度器根据这些参数进行资源分配，确保各个容器在共享主机资源时不会相互干扰或过度使用资源。

容器会被分配请求的资源量；如果容器所在的节点有足够的可用资源，容器可以使用超出请求的资源量，但不可使用超出限制的资源量。例如，当容器中的进程尝试使用超出限制的内存资源量时，系统会将尝试申请内存的进程终止，并触发内存不足（OOM）错误。

资源类型

资源类型包括 CPU、内存（memory）和扩展资源（extended resources）：

• CPU 的请求和限制以 Kubernetes CPU 为单位，1 个 Kubernetes CPU 等于 1 个物理 CPU 核心或 1 个虚拟核心，取决于节点是一台物理主机还是运行在某物理主机上的虚拟机。可以指定小数，例如 0.1 或 100m（1m = 1/1000），来使用核心的部分处理能力。

• 内存的请求和限制以字节为单位。可以使用科学计数法、定点后缀（k、M、G、T、P 和 E）和 2 的幂后缀（Ki、Mi、Gi、Ti、Pi 和 Ei），例如以下表达式代表大致相同的值：

  128974848, 129e6, 129M, 128974848000m, 123Mi

• 除了 CPU 和内存之外，Kubernetes 还支持扩展资源。扩展资源由管理员颁布（advertise），然后用户可以像使用 CPU 和内存一样使用扩展资源。GPU 是最重要的扩展资源类型之一，请参阅 GPU 使用。

资源配额

资源配额（resource quota）是对于资源使用量的限制，旨在确保集群中有限的计算资源被公平、有效地分配和利用，以提高集群的整体效率。平台引入了以下两种资源配额：

1. 项目配额：一个项目中的工作负载可以使用的资源总量。
2. 队列配额：一个队列中的工作负载可以使用的资源总量。

当用户创建工作负载时，系统会检查项目和队列的资源使用量是否将超过各自的资源配额。如果超过配额，系统将拒绝该工作负载的创建。

请参阅项目资源配额和队列资源配额（TODO）。

调度

调度（scheduling）是指将 Pod 分配给集群中的节点的过程。当用户创建一个工作负载时，由调度器决定将工作负载的 Pod 放置在哪些节点上运行。调度器会根据一系列的策略和条件来选择最合适的节点，并确保集群中的工作负载被有效地分配和管理。

节点上的每种资源类型都有特定的容量，调度器会确保对于每种资源类型，所有调度到某个节点上的 Pod 的资源请求量之和都小于该节点的可用容量。只有当所有资源请求（包括 CPU、内存和任何扩展资源）都被某个节点满足时，Pod 才能被调度到这个节点上。当资源请求无法被任何节点满足时，Pod 将保持 PENDING 状态。

除了资源需求，调度器还会根据自身的调度策略（TODO），以及节点的约束、亲和性、健康状态等来选择节点。

关于调度的更多细节，请参阅调度器。

参考

• 为 Pod 和容器管理资源
• 资源配额

下一步

• 进一步了解调度器
• 了解如何使用 GPU
• 了解如何监控工作负载的资源使用情况

调度器

调度器负责将工作负载的 Pod 放置在合适的节点上运行。平台支持 Kubernetes 的默认调度器 kube-scheduler。

kube-scheduler

kube-scheduler 是 Kubernetes 集群的默认调度器，也是平台的默认调度器。

下面将介绍 kube-scheduler 的一些常见的特性。如果想要更全面地了解 kube-scheduler，请参阅官方文档 调度、抢占和驱逐。

指定调度偏好

在创建 Pod 时，用户可以主动设置一些调度偏好，从而影响调度行为，约束 Pod 只能运行在指定的节点上。下面是一些可以设置的调度偏好。

NodeSelector

nodeSelector 用于约束 Pod 只能运行在指定的节点上，用户通过设置 nodeSelector 来表明用户希望目标节点所具有的节点标签。Pod 只会被调度到拥有用户所指定的每个标签的节点上。

设置方式：通过 Pod 的 spec.nodeSelector 字段来设置 nodeSelector。字段类型是 map，定义了节点标签。

示例：当 Pod YAML 设置了下列 nodeSelector 时，节点需要同时有标签 kubernetes.io/os: linux 和 kubernetes.io/arch: amd64

spec:
 nodeSelector:
   kubernetes.io/os: linux
   kubernetes.io/arch: amd64

亲和性

亲和性（affinity）用于影响 Pod 可以被调度到哪些节点上，亲和性分为两种类型：

• 节点亲和性：功能类似于 nodeSelector，但它的表达能力更强，并且允许用户指定软规则。
• Pod 间亲和性与反亲和性：使用户可以基于已经在节点上运行的 Pod 的标签来约束 Pod 可以调度到的节点，而不是基于节点上的标签。

节点亲和性

节点亲和性使用户可以基于节点标签来约束 Pod 可以调度到的节点。节点亲和性有两种类型：

• requiredDuringSchedulingIgnoredDuringExecution： 调度器只有在规则被满足的时候才能执行调度。此功能类似于 nodeSelector， 但其语法表达能力更强。
• preferredDuringSchedulingIgnoredDuringExecution： 调度器会尝试寻找满足对应规则的节点。如果找不到匹配的节点，调度器仍然会调度该 Pod。

设置方式：

• 通过 Pod 的 spec.affinity.nodeAffinity 字段来设置节点亲和性（API 参考）

示例：

spec:
 affinity:
   nodeAffinity:
     requiredDuringSchedulingIgnoredDuringExecution:
       nodeSelectorTerms:
       - matchExpressions:
         - key: topology.kubernetes.io/zone
           operator: In
           values:
           - antarctica-east1
           - antarctica-west1
     preferredDuringSchedulingIgnoredDuringExecution:
     - weight: 1
       preference:
         matchExpressions:
         - key: node-role.kubernetes.io/compute
           operator: Exists

Pod 设置的上述 affinity 表明：

1. 可调度的节点上必须有标签 topology.kubernetes.io/zone:antarctica-east1 或 topology.kubernetes.io/zone:antarctica-west1
2. 倾向于将 Pod 调度到含有标签键 node-role.kubernetes.io/compute 的节点上

Pod 间亲和性与反亲和性

Pod 间亲和性与反亲和性使用户可以基于已经在节点上运行的 Pod 的标签来约束 Pod 可以调度到的节点，而不是基于节点上的标签。与节点亲和性类似，Pod 间亲和性与反亲和性也分为 requiredDuringSchedulingIgnoredDuringExecution 和 preferredDuringSchedulingIgnoredDuringExecution 两种类型。

Pod 间亲和性与反亲和性的规则格式为“如果 X 上已经运行了一个或多个满足规则 Y 的 Pod， 则这个 Pod 应该（或者在反亲和性的情况下不应该）运行在 X 上”。 这里的 X 可以是节点、机架、云提供商可用区或地理区域或类似的拓扑域，Y 则是 Kubernetes 尝试满足的规则。

• 拓扑域（X）：用户会通过 topologyKey 来表达拓扑域（X）的概念，其值是系统用来标示域的节点标签键。以 topologyKey topology.kubernetes.io/zone 为例，标签键 topology.kubernetes.io/zone 对应的值相同的节点会被认为是同一拓扑域。
• 规则（Y）：通过 Pod affinity 字段定义的标签筛选规则。

设置方式：

• 通过 spec.affinity.podAffinity 字段来设置 Pod 间亲和性，通过 spec.affinity.podAntiAffinity 字段来设置 Pod 间反亲和性（API 参考）
• 必须设置 topologyKey 字段，以表达拓扑域（X）

示例：

apiVersion: apps/v1
kind: Deployment
metadata:
 name: application-server
...
spec:
 template:
   metadata:
     labels:
       app: database
   spec:
     affinity:
       podAntiAffinity:
         requiredDuringSchedulingIgnoredDuringExecution:
         - labelSelector:
             matchExpressions:
             - key: app
               operator: In
               values:
               - database
           topologyKey: topology.kubernetes.io/zone

上述 Deployment 为他的 Pod 设置了:

• Pod 标签： app: database
• Pod 间亲和性：保证所有 Pod 可以运行在相同拓扑域（标签键是 topology.kubernetes.io/zone）的节点上。

nodeName

Pod 含有 spec.nodeName 字段，用于表明 Pod 运行在哪个节点上。在创建 Pod 时：

• 未设置 nodeName 字段：调度器会根据调度规则自动为 Pod 设置 nodeName。
• 设置了 nodeName 字段：Pod 会绕过调度器的调度规则，直接被分配到指定的节点上运行。

下面是设置 nodeName 的 Pod 示例：

apiVersion: v1
kind: Pod
metadata:
 name: nginx
spec:
 containers:
 - name: nginx
   image: nginx
 nodeName: kube-01

上面的 Pod 只能运行在节点 kube-01 上。

污点与容忍度

污点（taint）是节点的一种属性，它可被用来使得某些类型的 Pod 不能被调度到该节点上（除非 Pod 明确说明其容忍该污点）。例如，当节点存在出现软硬件故障、网络不可用、磁盘空间不足等问题时，系统会自动为该节点添加一个污点。此外，当管理员发现节点存在问题或正在测试节点时，也可能为该节点添加污点。

容忍度（tolerations）是添加在一个 Pod 上的，如果 Pod 的容忍度与节点污点匹配，那么 Pod 可以被分配到含有污点的节点上。

节点污点示例

如果用户有查看节点的权限，用户可以使用 kubectl get node <nodeName> -o yaml 查看节点的污点。否则用户需要向管理员咨询节点的污点信息。

下面是一个示例，节点的 spec.taints 字段定义了污点信息：

spec:
  taints:
  - effect: NoSchedule
    key: key1
    value: value1

容忍度

创建 Pod 时，通过 spec.tolerations (API 参考) 字段来设置容忍度。

下面的容忍度设置可以忍受上述节点污点，从而 Pod 可以被调度到上述节点上：

tolerations:
- key: "key1"
  operator: "Equal"
  value: "value1"
  effect: "NoSchedule"

Pod 拓扑分布约束

拓扑分布约束（topology spread constraints）用于控制 Pod 在集群内的拓扑分布，通过 Pod 的 spec.topologySpreadConstraints 字段进行设置。详情请见 Kubernetes 文档。

下面是一个帮助用户理解拓扑分布约束的基本示例：

集群状态如下：

• 集群内有四个节点，通过节点标签 zone: <区域名> 划分为两个区域 zoneA 和 zoneB。
• 含有标签 foo: bar 的 3 个 Pod 分别运行在 node1、node2、node3 中。

用户若想创建一个新的 Pod，并且希望新来的 Pod 均匀分布在现有的可用区域，则可以按如下设置其清单：

kind: Pod
apiVersion: v1
metadata:
 name: mypod
 labels:
   foo: bar
spec:
 topologySpreadConstraints:
 - maxSkew: 1
   topologyKey: zone
   whenUnsatisfiable: DoNotSchedule
   labelSelector:
     matchLabels:
       foo: bar
 containers:
 - name: pause
   image: registry.k8s.io/pause:3.1

spec.topologySpreadConstraints 下的子字段说明：

• maxSkew：值是 1，表明不同节点区域之间 Pod 数量的最大差值为 1。
• topologyKey：用于划分节点区域的节点标签的键值。
• whenUnsatisfiable：值是 DoNotSchedule，表明调度器无法找到满足拓扑约束的方式时，将 Pod 保持在 pending 状态。
• labelSelector：表明含有标签 foo: bar 的 Pod 会被统计，以确定相应拓扑域中 Pod 的数量。

综上，zoneA 上有 2 个 Pod，zoneB 上有 1 个 Pod，如果 mypod 被分配到 zoneA 上会导致 skew 为 2，违背 maxSkew=1，所以 mypod 会被调度器分配到 zoneB 中的 Node3 或 Node4 上。

优先级和抢占

kube-scheduler 的优先级和抢占机制请参阅 Pod 优先级和抢占。

参考

• Kubernetes 调度器
• 将 Pod 指派给节点
• 污点和容忍度
• Pod 拓扑分布约束

GPU 使用

许多执行深度学习相关任务的工作负载都需要使用 GPU 进行计算，这些任务包括数据集的预处理、模型训练以及模型推理等等。平台支持目前所有主流的 GPU 设备，并且可以轻松扩展以支持更多设备类型。

使用模式

独占模式

独占模式指的是在特定时间段内，GPU 仅供单一工作负载使用。

适用场景：GPU 被满负荷使用，并且计算需要尽快完成。例如训练 AI 模型。

共享模式

共享模式指的是单个物理 GPU 被多个工作负载同时使用。

适用场景：对于有些计算任务，例如交互式的 Notebook，小规模或者低使用量的模型推理服务，经常只需要使用 GPU 的部分计算能力。在这些情况下，让多个计算任务共享使用 GPU，将能极大地提升 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 的 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
         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。同时又设置了 replica 的数量为 4，因此该 PyTorchTrainingJob 总共会占用 16 个 NVIDIA GPU。

共享 GPU

下面是一个以共享方式使用 GPU 的 Notebook 示例：

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 字段设置为指定型号 GPU 对应的节点标签，并且为工作负载设置了代表 GPU 的扩展资源，那么工作负载就可以使用指定型号的 GPU。

常见的节点标签

如果用户想要知道所使用的集群有哪些表明 GPU 型号的节点标签，请咨询管理员。下面是一些表明 GPU 型号的节点标签示例：

常见工作负载的 nodeSelector 字段

下面列举了常见的工作负载，以及工作负载用于设置 nodeSelector 的字段：

示例

下面是一个设置了 nodeSelector 字段的 SimpleMLService 示例：

apiVersion: tensorstack.dev/v1beta1
kind: SimpleMLService
metadata:
  name: llama3-1-8b
spec:
  replicas: 1
  storage:
    pvc:
      name: vllm
      subPath: Meta-Llama-3.1-8B-Instruct
  service:
    type: ClusterIP
    ports:
    - name: http
      port: 8000
      targetPort: 8000
      protocol: TCP
  custom:
    spec:
      containers:
      - name: server
        image: vllm/vllm-openai:v0.5.4
        args:
          - --model=/var/lib/t9k/model
          - --served-model-name=llama3-1-8b
          - --trust-remote-code
          - --enforce-eager
        ports:
        - name: http
          containerPort: 8000
          protocol: TCP
        resources:
          limits:
            cpu: 4
            memory: 64Gi
            nvidia.com/gpu: 1
      nodeSelector:
        nvidia.com/gpu.product: NVIDIA-A100-PCIE-40GB

在该例中：

• SimpleMLService 的资源量设置了 nvidia.com/gpu: 1，表示 SimpleMLService 使用 1 个 GPU。
• SimpleMLService 的 nodeSelector 被设置为 nvidia.com/gpu.product: NVIDIA-A100-PCIE-40GB，因此 SimpleMLService 的 Pod 会被分配到带有标签 nvidia.com/gpu.product: NVIDIA-A100-PCIE-40GB 的节点上运行，从而该 Pod 会被分配一个 NVIDIA A100 40GB。

参考

• K8s Extended resources
• Consuming extended resources
• Schedule GPUs | Kubernetes
• Device Plugins
• Assigning Pods to Nodes
• Improving GPU Utilization in Kubernetes
• MIG：NVIDIA Multi-Instance GPU User Guide

资源使用监控

在平台创建工作负载后，用户可以通过控制台或命令行工具查看工作负载的资源使用情况（除了计算资源，还包括网络带宽和存储资源）。

控制台

用户可以在下列控制台的工作负载的详情页面查看资源监测图表：

• Job Manager
• Service Manager

当用户定义工作负载时可以选择性地为每个容器设定所需要的资源数量，最常见的可设定资源是 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（读+写）：所有容器在节点的物理磁盘上，进行读写的操作次数之和。
• 吞吐量（读+写）：所有容器在节点的物理磁盘上，读写数据的吞吐量。

命令行工具

用户可以在 JupyterLab、Terminal 等 App 的终端中，使用 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 

下一步

• 监控 Job 的资源使用
• 监控 MLService 的资源使用
• 了解使用资源后产生的账单

账户和安全

TensorStack AI 平台提供全面、系统性的安全支持，以保障平台本身、平台提供的各种工具（例如模型构建控制台）和用户的各种工作负载（例如训练任务）的安全。

组织

如上图所示，TensorStack 平台支持客户以个人用户身份或组织形式使用服务。

组织之间、组织与个人用户之间存在隔离，即：

1. 组织用户仅可以加入同组织的用户组、个人用户也仅可以加入个人用户组；
2. 组织用户仅可以使用同组织的项目、个人用户也仅可以使用个人项目。

组织内权限

组织中的用户具有三种身份：组织所有者、组织管理者和普通用户。三者分别具有以下权限：

1. 普通用户可以使用其所加入或管理的项目。
2. 组织管理者除具有普通用户的权限以外，还具有管理用户、用户组和项目的权限（管理指创建、删除和修改）。
3. 组织所有者除具有组织管理者的权限以外，还具有修改用户身份的权限。
   • 组织中最多只能有一个组织所有者，所以如果设置其他用户为组织所有者，原组织所有者会变为组织管理员。

组织管理员和组织所有者可以查看组织账单，而普通用户在经过授权后也可以查看账单：

组织资源配额

平台管理员可以为组织设置组织资源配额，组织资源配额指一个组织所能使用最大的资源数量。

如果组织中尝试创建 K8s 对象以使用超出配额的资源，则准入控制器会阻止对应 K8s 对象的创建。

账户

账户是 TensorStack AI 平台为客户设立的用于记录和反映经济业务活动或其他特定事务的一种工具。

平台客户分为组织和个人用户两种，所以账户也可以分为组织账户和个人账户。

平台在创建组织或个人用户时，会自动为组织和个人用户创建账户。

账单

账单指一个账户在指定时间内所产生的费用。

组织账户的账单覆盖了所有组织项目中 Apps 和 APIs 使用每种资源产生的费用；个人账户的账单覆盖了其所管理的项目中 Apps 和 APIs 使用每种资源产生的费用，即使 Apps 是由其他项目成员创建的。

收费的资源种类包括：

示例

某用户拥有一个项目，该项目中只有一个 App。在 2024/09/01 10:00:00 ~ 13:00:00 时段，计费系统将生成 3 笔账单，分别是：

• 2024/09/01 10:00:00 ~ 11:00:00
• 2024/09/01 11:00:00 ~ 12:00:00
• 2024/09/01 12:00:00 ~ 13:00:00

假设该 App 请求了 2核 CPU、2GiB 内存，但是实际使用量存在一定波动：

• 在 2024/09/01 10:00:00 ~ 11:30:00 时段，实际使用了 0.5核 CPU、0.5GiB 内存
• 在 2024/09/01 11:30:00 ~ 12:00:00 时段，实际使用了 4核 CPU、4GiB 内存

假设 CPU 的价格为 0.003元/核/小时，内存的价格为 0.003元/GiB/小时，那么上述 3 笔账单的费用分别为：

• 2024/09/01 10:00:00 ~ 11:00:00：请求量与实际使用量的较大值为 1核 CPU、1GiB 内存，费用 = 0.003元/核/小时 * 2核 * 1小时 + 0.003元/GiB/小时 * 2GiB * 1小时 = 0.012元，抹零后实际扣除费用为 0.01元；
• 2024/09/01 11:00:00 ~ 12:00:00：请求量与实际使用量的较大值前半小时为 1核 CPU、1GiB 内存，后半小时为 4核 CPU、4GiB 内存，平均为 2.5核 CPU、2.5GiB 内存，因此费用 = 0.003元/核/小时 * 2.5核 * 1小时 + 0.003元/GiB/小时 * 2.5GiB * 1小时 = 0.015元，抹零后实际扣除费用为 0.01元；
• 2024/09/01 12:00:00 ~ 13:00:00：请求量与实际使用量的较大值为 4核 CPU、4GiB 内存，费用 = 0.003元/核/小时 * 4核 * 1小时 + 0.003元/GiB/小时 * 4GiB * 1小时 = 0.024元，抹零后实际扣除费用为 0.02元。

下一步

• 查看账单

项目

项目（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）查看自己所在和所管理的项目以及项目的成员。

项目管理员可以通过安全控制台编辑项目成员。

项目成员管理

项目管理员可以在安全控制台设置项目成员：

• 项目成员可以是用户或用户组，一个用户组被设置为项目成员表示该组中的所有用户都可以使用该项目。
• 设置项目成员时，可以对每一个成员单独设置项目的使用范围，对成员设置的项目使用范围应为项目所有使用范围的子集。

告警通知

当项目中出现异常情况时（例如余额不足、任务失败、App 长时间未就绪等），项目成员可以通过告警通知来订阅、查看告警信息，以了解异常情况。

告警信息

告警通知通过告警信息向用户传递异常情况，下面是一条告警信息的示例：

开始时间
2024-09-14T01:06:48Z
状态
firing
标签
alertname = KubePodNotReady
namespace = demo
pod = torch-mnist-trainingjob
severity = warning
注释
2024-09-14T01:06:48Z
description = Pod demo/torch-mnist-trainingjob has been in a non-ready state for longer than 15 minutes.
runbook_url = https://runbooks.prometheus-operator.dev/runbooks/kubernetes/kubepodnotready
summary = Pod has been in a non-ready state for more than 15 minutes.

以上述告警信息为例，一条告警信息主要包含下列内容：

1. 开始时间：当异常情况持续存在时，系统并不会持续产生告警信息，而是会周期性地（例如每 6 个小时）产生一条对应的告警信息。开始时间是系统最近一次产生这条告警信息的时间，并非异常情况出现的时间。
2. 状态：表明这条告警信息的状态，可能的值有：
   • pending：表明系统已经达到该告警信息对应的条件，但尚未超过规定时长。处于 pending 状态的告警信息无法通过订阅来查看。
   • firing：表明系统已经达到该告警信息对应的条件，并且已经超过规定时长。
3. 标签：记录了这条告警信息的所有内容，包括告警名称、相关对象等等，具有相同标签的告警信息会被认为是同一条告警信息。
   • 告警名称：标签键 alertname 对应的值是告警名称，上述告警信息的告警名称是 KubePodNotReady。告警名称代表告警信息的类型，同一类告警信息会有相同的告警名称，例如：当多个 Pod 处于 NotReady 状态时，系统会产生多个告警信息，这些告警信息的告警名称都是 KubePodNotReady。
4. 注释：注释中会存放总结信息，通常情况下，你只需要看注释就知道这条告警信息对应的异常情况是什么。

订阅告警信息

项目成员可以在 User Console 中订阅告警信息，不同项目的订阅设置是互相独立的。订阅告警信息时，项目成员需要进行下列操作：

1. 选择项目名称，下面的订阅设置只作用于这个项目
2. 填写接收通知的邮箱地址
3. 设置需要订阅的告警名称

默认情况下，项目成员只能订阅下列告警信息：

• KubePodCrashLooping：Pod 容器处于 CrashLooping 状态
• KubeImagePullError：Pod 容器无法拉取镜像（错误原因是 ImagePullError 或 ErrImagePull）
• KubeContainerOOM：容器的内存溢出，原因可能是超出容器的资源限制或节点的内存上限
• KubeQuotaAlmostFull：资源配额几乎耗尽了，需要减少资源使用或增加资源配额
• KubeQuotaFullyUsed：资源配额几乎耗尽了，需要减少资源使用或增加资源配额
• KubeQuotaExceeded：资源请求总量超过了资源配额
• KubePersistentVolumeFillingUp：存储卷容量已使用 97%
• T9kAccountBalanceLow：账户余额不足
• T9kServiceNotReady：未处于暂停状态的 T9kService 超过 15 分钟还未就绪
• T9kJobFailed：T9k Job 运行失败
• T9kAppNotReady：T9k App 超过 10 分钟还未就绪
• T9kAppNotInstalled：T9k App 超过 10 分钟还未被成功安装

查看告警信息

项目成员可以在 User Console 中直接查看项目的所有告警信息：

• 告警信息通过告警名称进行分类
• 告警信息状态：红色代表处于 firing 状态的告警信息，黄色代表处于 pending 状态的告警信息

下一步

• 查看告警通知

API Key

在使用浏览器场景下（例如使用 User Console），用户能够直接、同步地参与到身份认证和授权流程。用户可以方便地通过交互式的方式提供安全凭证（用户名 + 密码）来完成认证和授权，并随后通过 Cookie + Access Token 建立安全的交互过程。

但是，还有其他环境或者场景不适合采用前述方式。例如，用户通过命令行或者在自动化脚本中向服务器发送请求，此时要求 “用户同步进行交互” 来获得访问令牌是非常不便捷的；或者，在此过程中需要通过客户程序输入密码，可能造成密码泄漏。同时，有些场景下，我们希望能够只授予客户端部分权限，但直接使用前述 access token 或者 Cookie 并不能更进一步缩小权限。

API Key 是 TensorStack AI 平台应对上述问题的解决方案。它是一种可撤销的、异步的、持久的安全授权方式，具有以下特点：

• 可以长期持有（适合在脚本中使用）
• 不会泄漏账户信息（无需使用用户名和密码）
• 可以选择性地包含账户的部分权限
• 方便在脚本程序、命令行工具等“非交互场景”进行集成使用
• 可以随时方便地取消该授权

下一步

• 学习如何为账户 管理 API Key

操作指南

User Console 首页

首页是 User Console 的起始界面，为用户提供功能快速入口，以及账户的基本统计信息。

User Console 首页包含以下元素：

1. 顶部导航栏（包括白色和蓝色两个导航栏）
2. 左侧导航菜单
3. 中间的各项功能和账户统计

顶部白色导航栏的右侧有一些快捷按键，分别提供了以下功能：

1. ：使用 YAML 创建 K8s 资源
2. ：切换语言
3. ：打开用户文档
4. ：显示当前账户订阅的告警信息
5. ：显示当前用户信息，可用于退出登录

蓝色面包屑导航栏的左侧可以显示/隐藏左侧导航菜单，右侧是手动刷新按键和自动刷新的开关。

左侧导航菜单和中间区域对应的各项功能在后面介绍。

管理 App

这一部分演示如何安装、卸载 App 以及查看 App 的详细信息。

安装 App

本教程演示安装一个 App。

查看可安装的 App

在左侧导航菜单点击应用进入 App 管理页面，这里展示了所有已安装的 App。点击右上角的安装进入应用目录：

应用目录展示了所有可安装的 App 和它们的简介，你可以点击左侧的过滤选项过滤显示的 App，或在上方的搜索栏输入名称以快速查找：

选择并了解 App

如果你想要进一步了解某个 App 的功能和使用方法是否满足需求，点击以查看它的 README 文档。这里以最常用的交互式开发环境（IDE）App JupyterLab (CPU) 为例，点击 JupyterLab (CPU) 卡片进入 README 文档页面：

App 的 README 主要包含三个方面的信息：

1. 对于 App 的简短介绍：介绍 App 是什么，用来做什么，有什么特性。

   • 介绍的第一个链接是指向原项目的，你可以点击前往了解原项目的详情。

2. App 的使用方法：指导如何进行具体操作。

   • 使用方法可能会链接到官方文档。
   • 对于操作简单的网页 UI，可能不提供具体的使用方法。
   • 有时会附上一些网页 UI 的截图拱参考。

3. App 的配置方法：如果你确认 App 满足你的需求并着手安装时，接下来就需要参考此部分学习如何配置 App，根据配置示例和字段说明，确定符合需求的配置。

   • 可能提供额外的配置说明。
   • 对于有多个可选镜像的 App，还会提供镜像列表。

点击右上角的立刻安装进入配置页面：

配置和安装 App

在配置页面，填写配置可以通过表单或者 YAML 编辑器。前者提供了一个详细的字段设置界面，可以直接编辑各个字段；后者则需要编辑 YAML 文件，适合熟悉 YAML 格式的用户。

假定为 JupyterLab (CPU) App 选用 PyTorch 环境，申请 16 个 CPU（核心）、32 GiB 内存资源，挂载存储卷 demo。通过表单配置：

通过 YAML 编辑器配置：

不论以哪种方式，填写配置完成后，点击右上角的安装。

等待 App 就绪

安装完成后，等待 App 就绪。等待时间可能受以下因素影响：

1. 是否需要拉取镜像，以及镜像的大小和下载速度；
2. 应用的复杂程度（例如 K8s 和 T9k 资源的数量和依赖关系）；
3. 应用启动后是否需要初始化（例如下载数据集、加载模型文件等）

开始使用 App

待 App 就绪后，按照 README 提供的 App 的使用方法开始使用。对于 JupyterLab (CPU) App，即点击右侧的 进入网页 UI，参阅 JupyterLab Documentation 或它的中文版本进行操作。

克隆 App

如要安装一个与某个已安装的 App 配置相同或相似的 App，可以选择克隆该已安装的 App，而无需重复上面的操作。

假定再安装一个 JupyterLab (CPU) App，挂载存储卷 tutorial，其他配置不变。点击运行中的 JupyterLab (CPU) App 右侧的 > 克隆，进入配置页面，此时配置已经按照该 App 填写，因此修改 pvc 字段的值为 tutorial 即可。然后为了便于辨识，修改其名称为 tutorial。最后点击右上角的安装：

卸载 App

本教程演示卸载一个 App。

在左侧导航菜单点击应用进入 App 管理页面，这里展示了所有已安装的 App。点击 App 右侧的 > 卸载，确认以卸载相应的 App：

也可以点击 App 的名称进入其详情页面，点击右上角的卸载，确认以卸载相应的 App：

查看 App 详情

本教程演示查看一个 App 的详细信息。

App 管理页面已经展示了 App 的部分信息，包括状态、图标、名称、分类、创建时间和版本。点击 App 的名称进入其详情页面：

App 的详情页面展示了 App 的基本信息、网络配置、安装清单和 Pod 信息，下面将展开介绍：

基本信息

基本信息包含 App 的名称、App 的图标和原始名称、当前状态、资源请求和限制、创建时间等。点击配置右侧的 ，可以查看 App 安装时的配置：

点击信息右侧的 ，可以查看 App（可能）提供的信息：

对于部分 App，信息包含了访问网页 UI、获取服务端点或进行功能测试的方法。

如果 App 处于 NotReady 状态，可以点击状态右侧的诊断查看诊断结果以尝试定位原因：

对于上图中的示例，诊断结果显示 Pod 的 spec.volumes[0].persistentVolumeClaim.claimName 字段的值是必需的却没有提供，这提示着没有为 JupyterLab (CPU) App 绑定一个 PVC。

网络配置

网络配置提供了分别从集群内部和外部访问 App 服务的地址。外部地址对应 App 管理页面的链接，没有外部地址的 App 也就没有链接。

安装清单

安装清单列出了 App 创建的所有 API 资源。

Pod 信息

Pods 部分列出了 App（间接）创建的所有 Pod。点击 Pod 右侧的 可以进行更多操作，例如查看 Pod 的日志，在 Pod 的容器终端中执行命令以进行调试等：

管理存储、网络服务和辅助资源

管理 PVC

本教程演示创建、扩容和删除 PVC。

准备工作

• 了解 PVC 的概念和 Kubernetes API。

创建 PVC

在左侧导航菜单点击存储 > 存储卷进入 PVC 管理页面，这里展示了所有存在的 PVC。点击右上角的创建 PVC进入创建页面：

在 PVC 创建页面，填写名称和存储卷大小，选择存储卷访问模式和存储类，然后点击创建。

使用 PVC

PVC 的使用方式是作为存储卷挂载到 Pod 的容器中。例如在配置 JupyterLab App 时，你必须为其挂载一个 PVC 作为工作空间：

最终 PVC 被挂载到运行 JupyterLab 服务的容器的 /t9k/mnt 路径下。

下列文档提供了一些使用 PVC 的具体案例，供用户参考：

• 进行数据并行训练
• 部署 PyTorch 服务
• 上传和下载文件

扩容 PVC

在 PVC 管理页面，点击 PVC 右侧的 > 扩容：

填写新的存储大小（必须大于原大小），点击确定以扩容 PVC：

删除 PVC

在 PVC 管理页面，点击 PVC 右侧的 > 删除，确认以删除 PVC：

在终端操作

你也可以在 JupyterLab、Terminal 等 App 的终端使用 kubectl 命令完成上述操作，例如查看当前项目下的所有 PVC：

[/ root@app-terminal-a0cf62-73-57b676fcc4-bh8zc]
# kubectl get pvc
NAME    STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
demo    Bound    pvc-805d660d-f03a-4893-910c-7c8b06922de8   1Gi        RWX            cephfs-hdd     18m
mnist   Bound    pvc-0a272431-97b0-4b9d-9a91-2fa49859d219   1Gi        RWX            cephfs-hdd     3d6h

查看一个 PVC 的详细信息：

[/ root@app-terminal-a0cf62-73-57b676fcc4-bh8zc]
# kubectl get mnist
Name:          mnist
Namespace:     demo
StorageClass:  cephfs-hdd
Status:        Bound
Volume:        pvc-0a272431-97b0-4b9d-9a91-2fa49859d219
Labels:        <none>
Annotations:   pv.kubernetes.io/bind-completed: yes
               pv.kubernetes.io/bound-by-controller: yes
               volume.beta.kubernetes.io/storage-provisioner: cephfs-hdd.csi.ceph.com
               volume.kubernetes.io/storage-provisioner: cephfs-hdd.csi.ceph.com
Finalizers:    [kubernetes.io/pvc-protection]
Capacity:      1Gi
Access Modes:  RWX
VolumeMode:    Filesystem
Used By:       managed-simplemlservice-mnist-7fdfd-765d94c499-5kcfk
               mnist-84350-node-0
Events:        <none>

删除一个 PVC：

[/ root@app-terminal-a0cf62-73-57b676fcc4-bh8zc]
# kubectl delete pvc demo
persistentvolumeclaim "demo" deleted

创建 StorageShim

StorageShim 用于将已有的存储系统以 PVC 的形式提供给用户使用，例如将分布式文件系统的某个子目录作为一个 PVC 使用。

CephFS 类型

本章演示创建 CephFS 类型的 StorageShim，将 CephFS 的一个子目录作为一个 PVC 使用。创建 CephFS 类型的 StorageShim 需要用到一个包含 Ceph 服务器信息的 ConfigMap 和一个保存了 Ceph 客户端信息的 Secret。

点击辅助 > ConfigMap，然后点击右上角的创建，进入创建页面。填写 ConfigMap 名称、标签和数据，点击右上角的创建，完成 ConfigMap 的创建：

点击辅助 > Secret，然后点击右上角的创建，进入创建页面，并选择模板为 Ceph Client：

填写名称、userID 和 userKey，点击创建完成 Secret 的创建：

点击菜单存储 > 适配器，打开适配器的列表页面。然后点击右上角创建 StorageShim，进入创建页面：

选择类型为 CephFS，并选择提前准备好的 Ceph 服务器 ConfigMap 和 Ceph 客户端 Secret：

然后填写名称和 CephFS 路径。如果不知道可用的 CephFS 路径信息，可以询问管理员。最后点击右上角的创建：

创建成功后，等待 StorageShim 就绪即可：

S3 类型

本章演示创建 CephFS 类型的 StorageShim，将 S3 的一个 bucket 或者 bucket 中的目录作为一个 PVC 使用。创建 S3 类型的 StorageShim 需要用到一个 S3-cfg 类型的 Secret。

获取 S3 服务的信息，点击辅助 > Secret，创建一个S3-cfg 类型的 Secret：

进入 StorageShim 创建页面，并选择类型为 S3：

填写名称、“S3 URI” 并选择 “S3 Secret”，将鼠标放在字段右侧的 上可以看到详细的说明：

点击右上角的创建即可完成 StorageShim 的创建。

查看 Service

Service 是将运行在一个或一组 Pod 上的网络 Apps 公开为网络服务的方法。大部分 Apps 在安装时会自动创建相应的 Service，以方便集群中的其他服务进行访问。

点击网络服务 > Service，查看已有的 Service：

例如，安装 PostgreSQL App 时，会自动创建以下 Service：

查看 Ingress

Ingress 提供从集群外部到集群内服务的 HTTP 和 HTTPS 路由。 流量路由由 Ingress 资源所定义的规则来控制。

点击网络服务 > Ingress，查看已有的 Ingress：

管理 Secret

本教程演示创建、查看、修改和删除 Secret。

准备工作

• 了解 Secret 的概念和 Kubernetes API。

创建 Secret

在左侧导航菜单点击辅助 > Secret 进入 Secret 管理页面，这里展示了所有存在的 Secret。点击右上角的创建进入创建页面：

在 Secret 创建页面，填写名称和要存储的数据，然后点击创建：

使用 Secret

Secret 通过两种方式在 Pod 中使用：文件系统挂载和环境变量注入。具体来说，Secret 可以作为卷挂载到容器的指定路径。例如在 Job 创建页面，你可以添加存储卷并选择 Secret 类型：

这样配置的效果是，Secret 作为卷挂载到指定目录，Secret 的每个数据条目都会作为该目录下的一个文本文件，键为文件名，值为文件内容。

Secret 数据也可以直接配置为容器的环境变量。例如对于 DataCube 的 YAML 配置，设置源存储服务和目标存储服务都是通过引用 Secret 的数据条目来提供凭据（以 Hugging Face 类型为例）：

spec:
  source:
    type: huggingface
    options:
    - name: token
      valueFrom:
        secretKeyRef:
          name: hf
          key: token

这样的 DataCube 所创建的 Pod 就会将该数据条目赋值给环境变量 TOKEN：

spec:
  containers:
    env:
    - name: TOKEN
      valueFrom:
        secretKeyRef:
          name: hf
          key: token

对于 App（如 Tensorboard）和部分 API（如 StorageShim），你只需要参照配置或 YAML 配置的说明，在指定字段提供满足要求的 Secret 的名称即可，App 或 API 会处理好内部的配置。

下列文档提供了一些使用 Secret 的具体场景：

• SSH 场景
• S3 场景

查看和编辑 Secret

在 Secret 管理页面，点击 Secret 右侧的 > 编辑进入编辑页面：

在 Secret 编辑页面可以查看和修改数据（但是不能重命名 Secret），修改完成后点击编辑以保存：

删除 Secret

在 Secret 管理页面，点击 Secret 右侧的 > 删除，确认以删除 Secret：

SSH 场景

当用户需要在本地通过 SSH 远程连接 App 时，可以创建 SSH Public Key 类型的 Secret 存储本地系统的 SSH 公钥，并将其提供给启用 SSH 服务的 App（如 JupyterLab 和 RStudio），从而实现在本地远程连接和操作这些 App。

创建 Secret

在 Secret 创建页面，填写名称，选择模板 SSH Public Key，填写公钥文本，然后点击创建：

使用 Secret

下列文档提供了一些使用此类型的 Secret 配置 App 并远程连接的具体案例，供用户参考：

• 如何通过 SSH 远程连接

S3 场景

当 App 或 API 需要连接 S3 存储服务时，可以创建 S3-cfg 或 S3-env 类型的 Secret 存储访问凭证，并将其提供给这些 App 或 API。S3-cfg 类型以 .s3cfg 文件的形式存储和提供，而 S3-env 类型则以环境变量的形式存储和提供，这两种类型的 Secret 都能让 App 或 API 安全地访问和操作 S3 存储服务。

创建 Secret

S3-cfg 类型

在 Secret 创建页面，填写名称，选择模板 S3-cfg，填写 .s3cfg 文件的内容（可以在模板内容的基础上进行修改），然后点击创建：

S3-env 类型

在 Secret 创建页面，填写名称，选择模板 S3-env，填写或修改各个数据的值，然后点击创建：

使用 Secret

下列文档提供了一些使用这些类型的 Secret 配置 App 或 API 的具体案例，供用户参考：

• 创建 S3 类型的 StorageShim
• 使用 DataCube 在云存储与 PVC 之间复制或同步文件
• TensorBoard App 使用 S3 服务作为数据源

管理 ConfigMap

本教程演示创建、查看、修改和删除 ConfigMap。

准备工作

• 了解 ConfigMap 的概念和 Kubernetes API。

创建 ConfigMap

在左侧导航菜单点击辅助 > ConfigMap 进入 ConfigMap 管理页面，这里展示了所有存在的 ConfigMap。点击右上角的创建进入创建页面：

在 ConfigMap 创建页面，填写名称和要存储的数据，然后点击创建：

使用 ConfigMap

ConfigMap 的使用方式与 Secret 类似，这里不再赘述。

查看和编辑 ConfigMap

在 ConfigMap 管理页面，点击 ConfigMap 右侧的 > 编辑进入编辑页面：

在 ConfigMap 编辑页面可以查看和修改数据（但是不能重命名 ConfigMap），修改完成后点击编辑以保存：

删除 ConfigMap

在 ConfigMap 管理页面，点击 ConfigMap 右侧的 > 删除，确认以删除 ConfigMap：

设置账户

账户信息

点击左侧的账户设置 > 账户信息，展示了用户的信息：

项目管理

点击左侧的账户设置 > 项目管理，展示了当前用户有权限访问的项目：

在我的项目部分，展示的都是当前用户作为项目管理员的项目。这些项目产生的所有费用，都将结算到当前用户的账单中。而在分享给我的项目部分展示的项目中，当前用户是项目的普通成员，不需要承担项目的费用。

点击项目名称，可以查看项目的管理员和成员。如果当前用户是项目管理员，还可以点击成员右侧的编辑按键调整项目成员：

点击成员右侧的加号，添加用户或者用户组为项目成员；点击已有成员右侧的减号，可以将该用户或者用户组移除项目成员：

安全设置

点击左侧的账户设置 > 安全设置，进入安全设置页面：

安全设置页面提供了两个功能：修改密码和管理 API Key。

修改密码

管理 API Key

初次使用时，需要点击管理 API Key 的启用，输入密码来开启 API Key 功能。然后，点击生成 APIKey 进入创建页面：

在创建页面，输入 APIKey 的名称，并勾选该 API Key 的权限。点击下面的生成 APIKey完成创建：

创建完成后，可以复制 API Key 的值：

查看账单

点击左侧的账户设置 > 账单，可以查看账单页面：

通过最上方的日期选择框和项目选择框，你可以查看你所拥有的所有项目每天的费用。这些费用来源于你拥有的项目中使用的各种资源，包括计算资源（例如 CPU、GPU、内存）、存储资源（例如 PVC）和网络资源（例如流量）等。

点击明细，可以查看充值记录和费用记录：

对于某一条费用记录，点击查看详情，可以查看该条记录的详细情况：

点击计价标准，可以查看每种资源的单价：

告警通知

点击左侧的账户设置 > 告警通知，可以查看告警信息。你也可以通过点击上方白色导航栏的右侧的跳转到这个页面：

展开告警信息，可以看到更详细的说明。包括告警信息的开始时间、状态、标签、注释：

点击上方的通知标签页，填写接收通知的邮箱地址，然后可以设置告警信息的订阅状态：

订阅你关心的告警信息。被订阅的告警信息触发后，TensorStack AI 平台会发送邮件到指定的邮箱地址：

参考

• 告警信息

训练模型

这一部分的任务围绕深度学习模型的训练展开。通过这些任务，你将能够体验平台在模型训练领域的强大功能，具体包括：

1. 使用平台提供的 Job API，在多种深度学习框架或分布式训练框架下进行并行训练
2. 执行少数几行命令即可简单快速地启动训练任务
3. 通过可视化界面查看训练信息，实时监控训练进程和指标
4. 运用各种并行策略，高效分配计算资源，并且容易扩大规模
5. 使用 Job 的重启机制显著提升训练的故障容错能力
6. 分析性能以识别训练代码中的性能瓶颈和优化机会

进行数据并行训练

本教程演示使用 PyTorchTrainingJob 对 PyTorch 模型进行多工作器同步训练（使用 torch.nn.parallel.DistributedDataParallel 分布式数据并行模块）。本教程对应示例使用 PyTorchTrainingJob 进行数据并行训练。

本教程的 Apps 架构如下图所示：

准备工作

创建一个名为 tutorial、大小 1 Gi 的 PVC，然后安装一个同样名为 tutorial 的 JupyterLab App 挂载该 PVC，镜像和资源不限。

进入 JupyterLab，启动一个终端，执行以下命令以克隆 t9k/tutorial-examples 仓库：

cd ~
git clone https://github.com/t9k/tutorial-examples.git

启动训练（创建 PyTorchTrainingJob）

安装一个 Job Manager App（如有 Job Manager 则直接复用），进入 Job Manager 的网页 UI（控制台）。在左侧导航菜单点击 Job 进入 Job 管理页面，这里展示了所有已创建的 Job。点击右上角的创建，然后点击 PyTorch 进入 PyTorchTrainingJob 创建页面：

在 PyTorchTrainingJob 创建页面，填写配置如下：

• 基本信息部分：
  • 名称填写 torch-mnist-trainingjob
  • 打开使用 TorchRun，最大重启次数填写 3，单节点最大进程数填写 4
• worker 部分：
  • 镜像填写 t9kpublic/pytorch-1.13.0:sdk-0.5.2
  • 参数填写 torch_mnist_trainingjob.py "--save_path=model_state_dict.pt" "--log_dir=log" "--backend=nccl"
  • CPU 上限和内存上限分别填写 8 和 16Gi，CPU 请求值和内存请求值分别填写 4 和 8Gi
  • GPU 选择 nvidia.com/gpu，GPU Value 填写 4
  • 工作目录填写 /t9k/mnt/tutorial-examples/job/pytorchtrainingjob/ddp
  • 添加一个存储卷，PersistentVolumeClaim 选择 tutorial，绑定名称填写 data，绑定路径填写 /t9k/mnt

然后点击创建：

查看训练信息（查看 PyTorchTrainingJob 详情）

回到 Job 管理页面，可以看到名为 torch-mnist-trainingjob 的 PyTorchTrainingJob 正在运行，点击其名称进入详情页面：

可以看到刚才创建的 PyTorchTrainingJob 的基本信息，以及状况和事件信息：

点击上方的副本标签页，查看 PyTorchTrainingJob 的 Pod 信息；点击副本右侧的  > 日志以查看训练脚本执行过程中的日志输出：

点击上方的资源监测标签页，查看 PyTorchTrainingJob 运行过程中使用集群计算资源、网络资源和存储资源的情况：

一段时间之后，PyTorchTrainingJob 的状态变为 Succeeded，表示训练成功完成。

若 PyTorchTrainingJob 在运行过程中出错，其状态会变为 Error，并在事件信息和 Pod 信息部分显示错误信息，此时需要根据给出的错误信息进行问题排查。

查看训练指标

训练产生的 tfevents 文件保存在 PVC 中。回到 JupyterLab，创建一个 TensorBoard 实例。点击 TensorBoard 图标：

直接点击 Create TensorBoard：