如何配置指标收集器

本指南描述了Katib指标收集器的工作原理。

前提条件

在使用Python SDK运行超参数调优的Katib实验之前，确保命名空间标签 katib.kubeflow.org/metrics-collector-injection: enabled 存在。这个标签允许侧车容器注入，以便基于拉取的指标收集器在实验期间收集指标。

您可以通过添加以下标签 katib.kubeflow.org/metrics-collector-injection: enabled 来配置命名空间，如示例代码所示：

apiVersion: v1
kind: Namespace
metadata:
  name: <your-namespace>
  labels:
    katib.kubeflow.org/metrics-collector-injection: enabled

或者您可以使用以下命令将标签添加到现有的命名空间：

kubectl label namespace <your-namespace> katib.kubeflow.org/metrics-collector-injection=enabled

概述

收集指标有两种方法：

1. 拉取式：通过使用一个sidecar容器收集指标。sidecar 是一个实用容器，支持 Kubernetes Pod 中的主容器。

2. 基于推送：用户在训练脚本中将指标直接推送到Katib数据库。

在 Experiment YAML 配置文件的 metricsCollectorSpec 部分，您可以定义 Katib 应如何从每个试验中收集指标，例如准确性和损失指标。

基于拉取的指标收集器

您的训练代码可以将指标记录到 StdOut 或任意输出文件中。

要为您的实验定义基于拉取的指标收集器：

1. 在.collector.kind字段中指定收集器类型。
   Katib的指标收集器支持以下收集器类型：

   • StdOut: Katib 从操作系统的默认输出位置收集指标（标准输出）。这是默认的指标收集器。

   • File：Katib 从您在 .source.fileSystemPath.path 字段中指定的任意文件收集指标。训练容器应该以 TEXT 或 JSON 格式记录这些指标到该文件。如果您选择 JSON 格式，指标必须按 epoch 或 step 逐行分隔，如下所示，时间戳的键必须是 timestamp：

     {"epoch": 0, "foo": "bar", "fizz": "buzz", "timestamp": "2021-12-02T14:27:51"}
     {"epoch": 1, "foo": "bar", "fizz": "buzz", "timestamp": "2021-12-02T14:27:52"}
     {"epoch": 2, "foo": "bar", "fizz": "buzz", "timestamp": "2021-12-02T14:27:53"}
     {"epoch": 3, "foo": "bar", "fizz": "buzz", "timestamp": "2021-12-02T14:27:54"}
     

     查看文件指标收集器示例以获取 TEXT 和 JSON 格式。此外，默认文件路径是 /var/log/katib/metrics.log，默认文件格式是 TEXT。

   • TensorFlowEvent：Katib 从包含 tf.Event 的目录路径收集指标。 这些通常由 tensorflow.summary 写入。 从 Katib 0.18 开始，torch.utils.tensorboard 或 tensorboardX 也可以用于写入指标。 你应该在 .source.fileSystemPath.path 字段中指定路径。查看 TFJob 示例。 默认目录路径为 /var/log/katib/tfevent/。

   • Custom: 如果您需要使用自定义方式收集指标，请指定此值。您必须在 .collector.customCollector 字段中定义您的自定义指标收集器容器。查看 custom metrics collector example。

2. 在您的训练容器中编写代码以按照.source.filter.metricsFormat字段中指定的格式打印或保存度量指标。默认的度量格式值为：

   ([\w|-]+)\s*=\s*([+-]?\d*(\.\d+)?([Ee][+-]?\d+)?)
   

   每个元素都是一个正则表达式，并包含两个子表达式。第一个匹配的表达式被视为度量名称。第二个匹配的表达式被视为度量值。

   例如，使用默认的度量格式和StdOut度量收集器， 如果您的目标度量名称是loss，并且附加度量是recall和precision，则您的训练代码应打印以下输出：

   epoch 1:
   loss=3.0e-02
   recall=0.5
   precision=.4
   
   epoch 2:
   loss=1.3e-02
   recall=0.55
   precision=.5
   

基于推送的指标收集器

您的训练代码需要在Python SDK中调用report_metrics()函数来记录指标。 report_metrics()函数通过解析metrics字段中的指标生成一个gRPC请求，自动为用户添加当前时间戳，并将请求发送到Katib DB Manager。

但在此之前，应该在您的训练容器中安装 kubeflow-katib 包。

要为您的实验定义基于推送的指标收集器，您有两个选项：

• YAML 文件

  1. 在.collector.kind字段中指定收集器类型Push。

  2. 在您的训练容器中编写代码以调用 report_metrics() 来报告指标。

• tune function

  Use tune function and specify the metrics_collector_config field. You can reference to the following example:

  import kubeflow.katib as katib
  
  def objective(parameters):
    import time
    import kubeflow.katib as katib
    time.sleep(5)
    result = 4 * int(parameters["a"])
    # Push metrics to Katib DB.
    katib.report_metrics({"result": result})
  
  katib.KatibClient(namespace="kubeflow").tune(
    name="push-metrics-exp",
    objective=objective,
    parameters= {"a": katib.search.int(min=10, max=20)}
    objective_metric_name="result",
    max_trial_count=2,
    metrics_collector_config={"kind": "Push"},
    # When SDK is released, replace it with packages_to_install=["kubeflow-katib==0.18.0"].
    # Currently, the training container should have `git` package to install this SDK.
    packages_to_install=["git+https://github.com/kubeflow/katib.git@master#subdirectory=sdk/python/v1beta1"],
  )