如何使用 Trial 模板

本指南介绍如何配置 Trial 模板参数以及如何在 Katib Trials 中使用自定义的 Kubernetes CRD。您将学习如何修改 Trial 模板规范，如何使用 Kubernetes ConfigMaps 存储模板，以及如何修改 Katib 控制器以在 Katib Experiments 中支持您的 Kubernetes CRD。

Katib 动态支持将任何类型的 Kubernetes CRD 用作 Trial 的 Worker。在 Katib 示例中，您可以找到 Trial 的 Worker 的以下示例：

• Kubernetes Job

• Kubeflow TFJob

• Kubeflow PyTorchJob

• Kubeflow XGBoostJob

• Kubeflow MPIJob

• Tekton Pipelines

• Argo Workflows

要使用您自己的 Kubernetes 资源，请按照以下步骤操作。

如何使用 Trial 模板

要运行 Katib 实验，您需要为您的 Worker Job 指定 Trial 模板，模型训练实际在该 Worker Job 中运行。

配置 Trial 模板规范

Trial 模板规范位于您的 Experiment 的 .spec.trialTemplate 下。要定义 Trial，您应在 .spec.trialTemplate 中指定以下参数：

• trialParameters - Experiment 执行期间在 Trial 模板中使用的参数列表。

  注意：您的 Trial 模板必须包含 trialParameters 中的每个参数。您可以在模板的任何字段中设置这些参数，但 .metadata.name 和 .metadata.namespace 除外。例如，您的训练容器可以接收超参数作为命令行参数或环境变量。

  您的 Experiment 的 Suggestion 在运行 Trial 之前会生成 trialParameters。每个 trialParameter 具有以下结构：

  • name - 在模板中被替换的参数名称。

  • description (可选) - 参数的描述。

  • reference - Experiment 的 Suggestion 返回的参数名称。通常，对于超参数调优，参数引用等于 Experiment 搜索空间。例如，在网格示例中，搜索空间有 三个参数 (lr, momentum)，并且 trialParameters 在 reference 中包含所有这些参数。

• 您必须在 trialSpec 或 configMap 来源中的一个定义您的 Trial 模板。

  注意：您的模板必须省略 .metadata.name 和 .metadata.namespace。

  要设置 trialParameters 中的参数，您需要在模板中使用以下表达式：${trialParameters.<parameter-name>}。Katib 会自动将其替换为 Suggestion 中的相应值。

  例如，--lr=${trialParameters.learningRate} 就是 learningRate 参数。

  • trialSpec - 非结构化格式的 Trial 模板。模板应为有效的 YAML。

  • configMap - Trial 模板所在的 Kubernetes ConfigMap 规范。此 ConfigMap 必须具有标签 katib.kubeflow.org/component: trial-templates，并包含键值对，其中 key: <模板名称>, value: <模板 YAML>。请查看包含 Trial 模板的 ConfigMap 示例。

    configMap 规范应包含：

    1. configMapName - 包含 Trial 模板的 ConfigMap 名称。

    2. configMapNamespace - 包含 Trial 模板的 ConfigMap 命名空间。

    3. templatePath - ConfigMap 数据中指向模板的路径。

以下 .spec.trialTemplate 参数用于控制 Trial 行为。如果参数具有默认值，则可以在 Experiment YAML 中省略。

• retain - 指示 Trial 完成后是否清理其资源。请查看带 retain: true 参数的示例。

  默认值为 false

• primaryPodLabels - Trial Worker 的 Pod 或多个 Pod 的标签。这些 Pod 会被 Katib 指标收集器注入。

  注意：如果省略 primaryPodLabels，Katib 指标收集器会包裹所有 Worker Pod。请查看带 primaryPodLabels 的示例。

  Kubeflow TFJob、PyTorchJob、MXJob 和 XGBoostJob 的默认值为 job-role: master

  primaryPodLabels 的默认值仅在您在 .spec.trialTemplate.trialSpec 中指定模板时才有效。对于 configMap 模板源，您必须手动设置 primaryPodLabels。

• primaryContainerName - 实际模型训练运行所在的训练容器名称。Katib 指标收集器会包裹此容器以收集单个 Experiment 优化步骤所需的指标。

• successCondition - Trial Worker 对象成功完成 Trial 作业的状态。此条件必须采用 GJSON 格式。请查看带 successCondition 的示例。

  Kubernetes Job 的默认值为

  status.conditions.#(type=="Complete")#|#(status=="True")#
  

  Kubeflow TFJob、PyTorchJob、MXJob 和 XGBoostJob 的默认值为

  status.conditions.#(type=="Succeeded")#|#(status=="True")#
  

  successCondition 的默认值仅在您在 .spec.trialTemplate.trialSpec 中指定模板时才有效。对于 configMap 模板源，您必须手动设置 successCondition。

• failureCondition - Trial Worker 对象失败完成 Trial 作业的状态。此条件必须采用 GJSON 格式。请查看带 failureCondition 的示例。

  Kubernetes Job 和 Kubeflow TFJob、PyTorchJob、MXJob 和 XGBoostJob 的默认值为

  status.conditions.#(type=="Failed")#|#(status=="True")#
  

  failureCondition 的默认值仅在您在 .spec.trialTemplate.trialSpec 中指定模板时才有效。对于 configMap 模板源，您必须手动设置 failureCondition。

在 Trial 模板中使用元数据

您不能在 Trial 模板中指定 .metadata.name 和 .metadata.namespace，但可以在 Experiment 运行时获取此数据。例如，如果您想将 Trial 的名称附加到模型存储中。

为此，将 .trialParameters[x].reference 指向相应的元数据参数，并在您的 Trial 模板中使用 .trialParameters[x].name。

下表显示了 .trialParameters[x].reference 值与 Trial 元数据之间的连接。

请查看使用 Trial 元数据的示例。

在 Trial 模板中使用 CRD

无需修改 Katib 控制器源代码和构建新镜像，就可以使用您自己的 Kubernetes CRD 或其他 Kubernetes 资源（例如 Kubernetes CronJob）作为 Trial Worker。只要您的 CRD 创建 Kubernetes Pod，允许在这些 Pod 上注入sidecar 容器，并且具有成功和失败状态，您就可以在 Katib 中使用它。

为此，您需要在将 Katib 组件安装到您的 Kubernetes 集群之前对其进行修改。因此，您需要了解您的 CRD API 组和版本，以及 CRD 对象的类型 (kind)。此外，您还需要了解您的自定义对象创建了哪些资源。请查看 Kubernetes 指南以了解更多关于 CRD 的信息。

按照以下两个简单步骤将您的自定义 CRD 集成到 Katib 中

1. 修改 Katib 控制器的ClusterRole 规则，添加新规则以赋予 Katib 访问 Trial 创建的所有资源的权限。要了解更多关于 ClusterRole 的信息，请查看 Kubernetes 指南。

   对于 Tekton Pipelines，Trials 创建 Tekton PipelineRun，然后 Tekton PipelineRun 创建 Tekton TaskRun。因此，Katib 控制器的 ClusterRole 应具有访问 pipelineruns 和 taskruns 的权限。

   - apiGroups:
       - tekton.dev
     resources:
       - pipelineruns
       - taskruns
     verbs:
       - "get"
       - "list"
       - "watch"
       - "create"
       - "delete"
   

2. 修改 Katib Config 的控制器参数，添加新实体。

   trialResources:
    - <object-kind>.<object-API-version>.<object-API-group>
   

   例如，要支持 Tekton Pipelines

   trialResources:
     - PipelineRun.v1beta1.tekton.dev
   

完成这些更改后，按照安装指南中的说明部署 Katib，并等待 katib-controller Pod 创建完成。您可以查看 Katib 控制器的日志以验证您的资源集成情况。

$ kubectl logs $(kubectl get pods -n kubeflow -o name | grep katib-controller) -n kubeflow | grep '"CRD Kind":"PipelineRun"'

{"level":"info","ts":1628032648.6285546,"logger":"trial-controller","msg":"Job watch added successfully","CRD Group":"tekton.dev","CRD Version":"v1beta1","CRD Kind":"PipelineRun"}

如果您成功执行了以上步骤，您应该能够在 Experiment 的 Trial 模板源规范中使用您的自定义对象 YAML。

我们非常感谢您关于在 Katib 中使用各种 CRD 的反馈。如果您能告知我们您的 Experiment 情况，那将非常棒。开发者指南是了解如何为项目做贡献的良好起点。

下一步

• 了解Katib 指标收集器功能。

• 了解Katib 配置。