api.md

Protocol Documentation

Table of Contents

• api.proto

  • CreateStudyReply

  • CreateStudyRequest

  • CreateTrialReply

  • CreateTrialRequest

  • DataSetInfo

  • DeleteStudyReply

  • DeleteStudyRequest

  • EarlyStoppingParameter

  • EarlyStoppingParameterSet

  • FeasibleSpace

  • GetEarlyStoppingParameterListReply

  • GetEarlyStoppingParameterListRequest

  • GetEarlyStoppingParametersReply

  • GetEarlyStoppingParametersRequest

  • GetMetricsReply

  • GetMetricsRequest

  • GetSavedModelReply

  • GetSavedModelRequest

  • GetSavedModelsReply

  • GetSavedModelsRequest

  • GetSavedStudiesReply

  • GetSavedStudiesRequest

  • GetShouldStopWorkersReply

  • GetShouldStopWorkersRequest

  • GetStudyListReply

  • GetStudyListRequest

  • GetStudyReply

  • GetStudyRequest

  • GetSuggestionParameterListReply

  • GetSuggestionParameterListRequest

  • GetSuggestionParametersReply

  • GetSuggestionParametersRequest

  • GetSuggestionsReply

  • GetSuggestionsRequest

  • GetTrialReply

  • GetTrialRequest

  • GetTrialsReply

  • GetTrialsRequest

  • GetWorkerFullInfoReply

  • GetWorkerFullInfoRequest

  • GetWorkersReply

  • GetWorkersRequest

  • GraphConfig

  • Metrics

  • MetricsLog

  • MetricsLogSet

  • MetricsValueTime

  • ModelInfo

  • NasConfig

  • NasConfig.Operations

  • Operation

  • Operation.ParameterConfigs

  • Parameter

  • ParameterConfig

  • RegisterWorkerReply

  • RegisterWorkerRequest

  • ReportMetricsLogsReply

  • ReportMetricsLogsRequest

  • SaveModelReply

  • SaveModelRequest

  • SaveStudyReply

  • SaveStudyRequest

  • SetEarlyStoppingParametersReply

  • SetEarlyStoppingParametersRequest

  • SetSuggestionParametersReply

  • SetSuggestionParametersRequest

  • StopSuggestionReply

  • StopSuggestionRequest

  • StopWorkersReply

  • StopWorkersRequest

  • StudyConfig

  • StudyConfig.ParameterConfigs

  • StudyOverview

  • SuggestionParameter

  • SuggestionParameterSet

  • Tag

  • Trial

  • UpdateWorkerStateReply

  • UpdateWorkerStateRequest

  • ValidateSuggestionParametersReply

  • ValidateSuggestionParametersRequest

  • Worker

  • WorkerFullInfo

  • OptimizationType

  • ParameterType

  • State

  • EarlyStopping

  • Manager

  • Suggestion

• Scalar Value Types

Top

api.proto

Katib API

CreateStudyReply

Return generated StudyID.

Field	Type	Label	Description
study_id	string

CreateStudyRequest

Create a Study from Study Config. Generate an unique ID and store the Study to DB.

Field	Type	Label	Description
study_config	StudyConfig

CreateTrialReply

Return generated TrialID.

Field	Type	Label	Description
trial_id	string

CreateTrialRequest

Create a Trial from Trial Config. Generate an unique ID and store the Trial to DB.

Field	Type	Label	Description
trial	Trial

DataSetInfo

Field	Type	Label	Description
name	string
path	string

DeleteStudyReply

Return deleted Study ID.

Field	Type	Label	Description
study_id	string

DeleteStudyRequest

Delete a Study from DB by Study ID.

Field	Type	Label	Description
study_id	string

EarlyStoppingParameter

Parameter for EarlyStopping service. Key-value format.

Field	Type	Label	Description
name	string		Name of Parameter.
value	string		Value of Parameter.

EarlyStoppingParameterSet

Field	Type	Label	Description
param_id	string
early_stopping_algorithm	string
early_stopping_parameters	EarlyStoppingParameter	repeated

FeasibleSpace

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

Field	Type	Label	Description
max	string		Max Value
min	string		Minimum Value
list	string	repeated	List of Values.
step	string		Step for double or int parameter

GetEarlyStoppingParameterListReply

Field	Type	Label	Description
early_stopping_parameter_sets	EarlyStoppingParameterSet	repeated

GetEarlyStoppingParameterListRequest

Field	Type	Label	Description
study_id	string

GetEarlyStoppingParametersReply

Field	Type	Label	Description
early_stopping_parameters	EarlyStoppingParameter	repeated

GetEarlyStoppingParametersRequest

Field	Type	Label	Description
param_id	string

GetMetricsReply

Field	Type	Label	Description
metrics_log_sets	MetricsLogSet	repeated

GetMetricsRequest

Field	Type	Label	Description
study_id	string
worker_ids	string	repeated
metrics_names	string	repeated

GetSavedModelReply

Field	Type	Label	Description
model	ModelInfo

GetSavedModelRequest

Field	Type	Label	Description
study_name	string
worker_id	string

GetSavedModelsReply

Field	Type	Label	Description
models	ModelInfo	repeated

GetSavedModelsRequest

Field	Type	Label	Description
study_name	string

GetSavedStudiesReply

Field	Type	Label	Description
studies	StudyOverview	repeated

GetSavedStudiesRequest

GetShouldStopWorkersReply

Field	Type	Label	Description
should_stop_worker_ids	string	repeated

GetShouldStopWorkersRequest

Field	Type	Label	Description
study_id	string
early_stopping_algorithm	string
param_id	string

GetStudyListReply

Return a overview list of Studies.

Field	Type	Label	Description
study_overviews	StudyOverview	repeated

GetStudyListRequest

Get all Study Configs from DB.

GetStudyReply

Return a config of specified Study.

Field	Type	Label	Description
study_config	StudyConfig

GetStudyRequest

Get a Study Config from DB by ID of Study.

Field	Type	Label	Description
study_id	string

GetSuggestionParameterListReply

Field	Type	Label	Description
suggestion_parameter_sets	SuggestionParameterSet	repeated

GetSuggestionParameterListRequest

Field	Type	Label	Description
study_id	string

GetSuggestionParametersReply

Field	Type	Label	Description
suggestion_parameters	SuggestionParameter	repeated

GetSuggestionParametersRequest

Field	Type	Label	Description
param_id	string

GetSuggestionsReply

Field	Type	Label	Description
trials	Trial	repeated

GetSuggestionsRequest

Field	Type	Label	Description
study_id	string
suggestion_algorithm	string
request_number	int32
log_worker_ids	string	repeated
param_id	string

GetTrialReply

Return a trial configuration by specified trial ID

Field	Type	Label	Description
trial	Trial

GetTrialRequest

Get a trial configuration from DB by trial ID

Field	Type	Label	Description
trial_id	string

GetTrialsReply

Return a trial list in specified Study.

Field	Type	Label	Description
trials	Trial	repeated

GetTrialsRequest

Get a Trial Configs from DB by ID of Study.

Field	Type	Label	Description
study_id	string

GetWorkerFullInfoReply

Field	Type	Label	Description
worker_full_infos	WorkerFullInfo	repeated

GetWorkerFullInfoRequest

Get a full information related to specified Workers. It includes Worker Config, HyperParameters and Metrics Logs.

Field	Type	Label	Description
study_id	string
trial_id	string
worker_id	string
only_latest_log	bool

GetWorkersReply

Return a Worker list by specified condition.

Field	Type	Label	Description
workers	Worker	repeated

GetWorkersRequest

Get a configs and status of a Worker from DB by ID of Study, Trial or Worker.

Field	Type	Label	Description
study_id	string
trial_id	string
worker_id	string

GraphConfig

GraphConfig contains a config of DAG

Field	Type	Label	Description
num_layers	int32		Number of layers
input_size	int32	repeated	Dimenstions of input size
output_size	int32	repeated	Dimensions of output size

Metrics

Metrics of a worker

Field	Type	Label	Description
name	string		Name of metrics.
value	string		Value of metrics. Double float.

MetricsLog

Metrics logs of a worker

Field	Type	Label	Description
name	string		Name of metrics.
values	MetricsValueTime	repeated	Log of metrics. Ordered by time series.

MetricsLogSet

Logs of metrics for a worker.

Field	Type	Label	Description
worker_id	string		ID of the corresponding worker.
metrics_logs	MetricsLog	repeated	Logs of metrics.
worker_status	State		Status of the corresponding worker.

MetricsValueTime

Metrics of a worker with timestamp

Field	Type	Label	Description
time	string		Timestamp RFC3339 format.
value	string		Value of metrics. Double float.

ModelInfo

Field	Type	Label	Description
study_name	string
worker_id	string
parameters	Parameter	repeated
metrics	Metrics	repeated
model_path	string

NasConfig

NasConfig contains a config of NAS job

Field	Type	Label	Description
graph_config	GraphConfig		Config of DAG
operations	NasConfig.Operations		List of Operation

NasConfig.Operations

Field	Type	Label	Description
operation	Operation	repeated

Operation

Config for operations in DAG

Field	Type	Label	Description
operationType	string		Type of operation in DAG
parameter_configs	Operation.ParameterConfigs		List of ParameterConfig

Operation.ParameterConfigs

List of ParameterConfig

Field	Type	Label	Description
configs	ParameterConfig	repeated

Parameter

Value of a Hyper parameter. This will be created from a correcponding Config.

Field	Type	Label	Description
name	string		Name of the parameter.
parameter_type	ParameterType		Type of the parameter.
value	string		Value of the parameter.

ParameterConfig

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

Field	Type	Label	Description
name	string		Name of the parameter.
parameter_type	ParameterType		Type of the parameter.
feasible	FeasibleSpace		FeasibleSpace for the parameter.

RegisterWorkerReply

Return generated WorkerID.

Field	Type	Label	Description
worker_id	string

RegisterWorkerRequest

Create a Worker from Worker Config. Generate an unique ID and store the Worker to DB.

Field	Type	Label	Description
worker	Worker

ReportMetricsLogsReply

ReportMetricsLogsRequest

Field	Type	Label	Description
study_id	string
metrics_log_sets	MetricsLogSet	repeated

SaveModelReply

SaveModelRequest

Field	Type	Label	Description
model	ModelInfo
data_set	DataSetInfo
tensor_board	bool

SaveStudyReply

SaveStudyRequest

Field	Type	Label	Description
study_name	string
owner	string
description	string

SetEarlyStoppingParametersReply

Field	Type	Label	Description
param_id	string

SetEarlyStoppingParametersRequest

Field	Type	Label	Description
study_id	string
early_stopping_algorithm	string
param_id	string
early_stopping_parameters	EarlyStoppingParameter	repeated

SetSuggestionParametersReply

Field	Type	Label	Description
param_id	string

SetSuggestionParametersRequest

Field	Type	Label	Description
study_id	string
suggestion_algorithm	string
param_id	string
suggestion_parameters	SuggestionParameter	repeated

StopSuggestionReply

StopSuggestionRequest

Field	Type	Label	Description
study_id	string

StopWorkersReply

StopWorkersRequest

Field	Type	Label	Description
study_id	string
worker_ids	string	repeated
is_complete	bool

StudyConfig

Config of a Study. Study represents a single optimization run over a feasible space. Each Study 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 Study.

Field	Type	Label	Description
name	string		Name of Study.
owner	string		Owner of Study.
optimization_type	OptimizationType		Optimization type.
optimization_goal	double		Goal of optimization value.
parameter_configs	StudyConfig.ParameterConfigs		List of ParameterConfig
access_permissions	string	repeated	Access Permission
tags	Tag	repeated	Tag for Study
objective_value_name	string		Name of objective value.
metrics	string	repeated	List of metrics name.
jobId	string		ID of studyjob that is created from this config.
nas_config	NasConfig		Config for NAS job
job_type	string		Type of the job, NAS or HP

StudyConfig.ParameterConfigs

List of ParameterConfig

Field	Type	Label	Description
configs	ParameterConfig	repeated

StudyOverview

Overview of a study. For UI.

Field	Type	Label	Description
name	string		Name of Study.
owner	string		Owner of Study.
id	string		Study ID.
description	string		Discretption of Study.

SuggestionParameter

Parameter for Suggestion service. Key-value format.

Field	Type	Label	Description
name	string		Name of Parameter.
value	string		Value of Parameter.

SuggestionParameterSet

Field	Type	Label	Description
param_id	string
suggestion_algorithm	string
suggestion_parameters	SuggestionParameter	repeated

Tag

Tag for each resource.

Field	Type	Label	Description
name	string		Name of tag.
value	string		Value of tag.

Trial

A set of Hyperparameter. In a study, multiple trials are evaluated by workers. Suggestion service will generate next trials. Create time will be filled in the server automatically side even user set the value

Field	Type	Label	Description
trial_id	string		Trial ID.
study_id	string		Study ID.
parameter_set	Parameter	repeated	Hyperparameter set
objective_value	string		Objective Value
tags	Tag	repeated	Tags of Trial.
create_time	string		Trial create timestamp RFC3339 format.

UpdateWorkerStateReply

UpdateWorkerStateRequest

Update a Status of Worker.

Field	Type	Label	Description
worker_id	string
status	State

ValidateSuggestionParametersReply

Return 1 if Suggestion Parameters is Valid, 0 if not

ValidateSuggestionParametersRequest

Field	Type	Label	Description
study_config	StudyConfig
suggestion_algorithm	string
suggestion_parameters	SuggestionParameter	repeated

Worker

A process of evaluation for a trial. Types of worker supported by Katib are k8s Job, TF-Job, and Pytorch-Job.

Field	Type	Label	Description
worker_id	string		Worker ID.
study_id	string		Study ID.
trial_id	string		Trial ID.
Type	string		Type of Worker
status	State		Status of Worker.
TemplatePath	string		Path for the manufest template of Worker.
tags	Tag	repeated	Tags of Worker.

WorkerFullInfo

Field	Type	Label	Description
Worker	Worker
parameter_set	Parameter	repeated
metrics_logs	MetricsLog	repeated

OptimizationType

Direction of optimization. Minimize or Maximize.

Name	Number	Description
UNKNOWN_OPTIMIZATION	0	Undefined type and not used.
MINIMIZE	1	Minimize
MAXIMIZE	2	Maximize

ParameterType

Types of value for HyperParameter.

Name	Number	Description
UNKNOWN_TYPE	0	Undefined type and not used.
DOUBLE	1	Double float type. Use "Max/Min".
INT	2	Int type. Use "Max/Min".
DISCRETE	3	Discrete number type. Use "List" as float.
CATEGORICAL	4	Categorical type. Use "List" as string.

State

Status code for worker. This value is stored as TINYINT in MySQL.

Name	Number	Description
PENDING	0	Pending. Created but not running.
RUNNING	1	Running.
COMPLETED	2	Completed.
KILLED	3	Killed. Not failed.
ERROR	120	Error.

EarlyStopping

Method Name	Request Type	Response Type	Description
GetShouldStopWorkers	GetShouldStopWorkersRequest	GetShouldStopWorkersReply

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 Name	Request Type	Response Type	Description
CreateStudy	CreateStudyRequest	CreateStudyReply	Create a Study from Study Config. Generate a unique ID and store the Study to DB.
GetStudy	GetStudyRequest	GetStudyReply	Get a Study Config from DB by ID of Study.
DeleteStudy	DeleteStudyRequest	DeleteStudyReply	Delete a Study from DB by Study ID.
GetStudyList	GetStudyListRequest	GetStudyListReply	Get all Study Configs from DB.
CreateTrial	CreateTrialRequest	CreateTrialReply	Create a Trial from Trial Config. Generate a unique ID and store the Trial to DB.
GetTrials	GetTrialsRequest	GetTrialsReply	Get a Trial Configs from DB by ID of Study.
GetTrial	GetTrialRequest	GetTrialReply	Get a Trial Configuration from DB by ID of Trial.
RegisterWorker	RegisterWorkerRequest	RegisterWorkerReply	Create a Worker from Worker Config. Generate a unique ID and store the Worker to DB.
GetWorkers	GetWorkersRequest	GetWorkersReply	Get a Worker Configs and Status from DB by ID of Study, Trial or Worker.
UpdateWorkerState	UpdateWorkerStateRequest	UpdateWorkerStateReply	Update a Status of Worker.
GetWorkerFullInfo	GetWorkerFullInfoRequest	GetWorkerFullInfoReply	Get full information related to specified Workers. It includes Worker Config, HyperParameters and Metrics Logs.
GetSuggestions	GetSuggestionsRequest	GetSuggestionsReply	Get Suggestions from a Suggestion service.
GetShouldStopWorkers	GetShouldStopWorkersRequest	GetShouldStopWorkersReply
GetMetrics	GetMetricsRequest	GetMetricsReply	Get metrics of workers. You can get all logs of metrics since start of the worker.
SetSuggestionParameters	SetSuggestionParametersRequest	SetSuggestionParametersReply	Create or Update parameter set for a suggestion service. If you specify an ID of parameter set, it will update the parameter set by your request. If you don't specify an ID, it will create a new parameter set for corresponding study and suggestion service. The parameters are key-value format.
GetSuggestionParameters	GetSuggestionParametersRequest	GetSuggestionParametersReply	Get suggestion parameter set from DB specified.
GetSuggestionParameterList	GetSuggestionParameterListRequest	GetSuggestionParameterListReply	Get all suggestion parameter sets from DB.
SetEarlyStoppingParameters	SetEarlyStoppingParametersRequest	SetEarlyStoppingParametersReply
GetEarlyStoppingParameters	GetEarlyStoppingParametersRequest	GetEarlyStoppingParametersReply
GetEarlyStoppingParameterList	GetEarlyStoppingParameterListRequest	GetEarlyStoppingParameterListReply
SaveStudy	SaveStudyRequest	SaveStudyReply
SaveModel	SaveModelRequest	SaveModelReply
ReportMetricsLogs	ReportMetricsLogsRequest	ReportMetricsLogsReply	Report a logs of metrics for workers. The logs for each worker must have timestamp and must be ordered in time series. When the log you reported are already reported before, it will be dismissed and get no error.
GetSavedStudies	GetSavedStudiesRequest	GetSavedStudiesReply
GetSavedModels	GetSavedModelsRequest	GetSavedModelsReply
ValidateSuggestionParameters	ValidateSuggestionParametersRequest	ValidateSuggestionParametersReply	Validate Suggestion Parameters from Study Job.

Suggestion

Method Name	Request Type	Response Type	Description
GetSuggestions	GetSuggestionsRequest	GetSuggestionsReply
ValidateSuggestionParameters	ValidateSuggestionParametersRequest	ValidateSuggestionParametersReply

Scalar Value Types

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str