Katib

Reference documentation for Katib

This is the legacy gRPC API reference for Katib v1alpha3 version. Corresponding Katib documentation can be found in 1.0 Kubeflow documentation.

Table of Contents

Top

api.proto

Katib API v1alpha3

AlgorithmSetting

FieldTypeLabelDescription
namestring
valuestring

AlgorithmSpec

FieldTypeLabelDescription
algorithm_namestring
algorithm_settingAlgorithmSettingrepeated
early_stopping_specEarlyStoppingSpec

DeleteObservationLogReply

DeleteObservationLogRequest

FieldTypeLabelDescription
trial_namestring

EarlyStoppingSpec

TODO: This feature is not yet fully implemented.

Experiment

FieldTypeLabelDescription
namestringName of Experiment. This is unique in DB.
specExperimentSpec

ExperimentSpec

Spec of a Experiment. Experiment represents a single optimization run over a feasible space. Each Experiment contains a configuration describing the feasible space, as well as a set of Trials. It is assumed that objective function f(x) does not change in the course of a Experiment.

FieldTypeLabelDescription
parameter_specsExperimentSpec.ParameterSpecs
objectiveObjectiveSpec
algorithmAlgorithmSpec
trial_templatestring
metrics_collector_specstring
parallel_trial_countint32
max_trial_countint32
nas_configNasConfig

ExperimentSpec.ParameterSpecs

List of ParameterSpec

FieldTypeLabelDescription
parametersParameterSpecrepeated

FeasibleSpace

Feasible space for optimization. Int and Double type use Max/Min. Discrete and Categorical type use List.

FieldTypeLabelDescription
maxstringMax Value
minstringMinimum Value
liststringrepeatedList of Values.
stepstringStep for double or int parameter

GetObservationLogReply

FieldTypeLabelDescription
observation_logObservationLog

GetObservationLogRequest

FieldTypeLabelDescription
trial_namestring
metric_namestring
start_timestringThe start of the time range. RFC3339 format
end_timestringThe end of the time range. RFC3339 format

GetSuggestionsReply

FieldTypeLabelDescription
parameter_assignmentsGetSuggestionsReply.ParameterAssignmentsrepeated
algorithmAlgorithmSpec

GetSuggestionsReply.ParameterAssignments

FieldTypeLabelDescription
assignmentsParameterAssignmentrepeated

GetSuggestionsRequest

FieldTypeLabelDescription
experimentExperiment
trialsTrialrepeatedall completed trials owned by the experiment.
request_numberint32The number of Suggestion you request at one time. When you set 3 to request_number, you can get three Suggestions at one time.

GraphConfig

GraphConfig contains a config of DAG

FieldTypeLabelDescription
num_layersint32Number of layers
input_sizesint32repeatedDimensions of input size
output_sizesint32repeatedDimensions of output size

Metric

FieldTypeLabelDescription
namestring
valuestring

MetricLog

FieldTypeLabelDescription
time_stampstringRFC3339 format
metricMetric

NasConfig

NasConfig contains a config of NAS job

FieldTypeLabelDescription
graph_configGraphConfigConfig of DAG
operationsNasConfig.OperationsList of Operation

NasConfig.Operations

FieldTypeLabelDescription
operationOperationrepeated

ObjectiveSpec

FieldTypeLabelDescription
typeObjectiveType
goaldouble
objective_metric_namestring
additional_metric_namesstringrepeatedThis can be empty if we only care about the objective metric.

Observation

FieldTypeLabelDescription
metricsMetricrepeated

ObservationLog

FieldTypeLabelDescription
metric_logsMetricLogrepeated

Operation

Config for operations in DAG

FieldTypeLabelDescription
operation_typestringType of operation in DAG
parameter_specsOperation.ParameterSpecs

Operation.ParameterSpecs

List of ParameterSpec

FieldTypeLabelDescription
parametersParameterSpecrepeated

ParameterAssignment

FieldTypeLabelDescription
namestring
valuestring

ParameterSpec

Config for a Hyper parameter. Katib will create each Hyper parameter from this config.

FieldTypeLabelDescription
namestringName of the parameter.
parameter_typeParameterTypeType of the parameter.
feasible_spaceFeasibleSpaceFeasibleSpace for the parameter.

ReportObservationLogReply

ReportObservationLogRequest

FieldTypeLabelDescription
trial_namestring
observation_logObservationLog

Trial

FieldTypeLabelDescription
namestring
specTrialSpec
statusTrialStatus

TrialSpec

FieldTypeLabelDescription
experiment_namestring
objectiveObjectiveSpec
parameter_assignmentsTrialSpec.ParameterAssignments
run_specstring
metrics_collector_specstring

TrialSpec.ParameterAssignments

List of ParameterAssignment

FieldTypeLabelDescription
assignmentsParameterAssignmentrepeated

TrialStatus

FieldTypeLabelDescription
start_timestringRFC3339 format
completion_timestringRFC3339 format
conditionTrialStatus.TrialConditionType
observationObservationThe best observation in logs.

ValidateAlgorithmSettingsReply

Return INVALID_ARGUMENT Error if Algorithm Settings are not Valid

ValidateAlgorithmSettingsRequest

FieldTypeLabelDescription
experimentExperiment

ObjectiveType

Direction of optimization. Minimize or Maximize.

NameNumberDescription
UNKNOWN0Undefined type and not used.
MINIMIZE1Minimize
MAXIMIZE2Maximize

ParameterType

Types of value for HyperParameter.

NameNumberDescription
UNKNOWN_TYPE0Undefined type and not used.
DOUBLE1Double float type. Use “Max/Min”.
INT2Int type. Use “Max/Min”.
DISCRETE3Discrete number type. Use “List” as float.
CATEGORICAL4Categorical type. Use “List” as string.

TrialStatus.TrialConditionType

NameNumberDescription
CREATED0
RUNNING1
SUCCEEDED2
KILLED3
FAILED4
UNKNOWN5

EarlyStopping

TODO: This feature is not yet fully implemented.

Method NameRequest TypeResponse TypeDescription

Manager

Service for Main API for Katib For each RPC service, we define mapping to HTTP REST API method. The mapping includes the URL path, query parameters and request body. https://cloud.google.com/service-infrastructure/docs/service-management/reference/rpc/google.api#http

Method NameRequest TypeResponse TypeDescription
ReportObservationLogReportObservationLogRequestReportObservationLogReplyReport a log of Observations for a Trial. The log consists of timestamp and value of metric. Katib store every log of metrics. You can see accuracy curve or other metric logs on UI.
GetObservationLogGetObservationLogRequestGetObservationLogReplyGet all log of Observations for a Trial.
DeleteObservationLogDeleteObservationLogRequestDeleteObservationLogReplyDelete all log of Observations for a Trial.

Suggestion

Method NameRequest TypeResponse TypeDescription
GetSuggestionsGetSuggestionsRequestGetSuggestionsReply
ValidateAlgorithmSettingsValidateAlgorithmSettingsRequestValidateAlgorithmSettingsReply

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
doubledoubledoublefloat
floatfloatfloatfloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intint
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/long
uint32Uses variable-length encoding.uint32intint/long
uint64Uses variable-length encoding.uint64longint/long
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intint
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/long
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intint
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/long
sfixed32Always four bytes.int32intint
sfixed64Always eight bytes.int64longint/long
boolboolbooleanboolean
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicode
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr

Last modified 11.11.2020: Katib v1beta1 documentation update (#2312) (ba726043)