// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
syntax = "proto2";
option optimize_for = LITE_RUNTIME;
package segmentation_platform.proto;
import "components/segmentation_platform/public/proto/aggregation.proto";
import "components/segmentation_platform/public/proto/output_config.proto";
import "components/segmentation_platform/public/proto/types.proto";
// The version is used to verify if the metadata provided by the server is
// supported in current version of the code. Update the version number for any
// new feature added to metadata proto, and add a log of the new changes in the
// current version in this file.
// Version 0 supports UMA features and aggregation in |features| field.
// Version 1 supports UMA features, custom inputs and sql features in
// |input_features| field.
// Version 2 supports training data output collection in |training_outputs|
// field.
// Version 3 supports trigger configurations for training data collection.
enum CurrentVersion {
METADATA_VERSION = 3;
}
// Version information for segmentation models.
message VersionInfo {
// Minimum model metadata version that is supported. Some newer
// features/fields might not be available before this version. This field is
// set on the server and read by the client to verify if model is valid.
optional int32 metadata_min_version = 1;
// Current model metadata version. This field is set by the client while
// sending a model download request to optimization guide server so that the
// server knows the capabilities of the client.
optional int32 metadata_cur_version = 2;
}
// Used to identify the source of the model whether it is a client side or
// server side model.
enum ModelSource {
UNKNOWN_MODEL_SOURCE = 0;
SERVER_MODEL_SOURCE = 1; // Represents server side model.
DEFAULT_MODEL_SOURCE = 2; // Represents client side model.
}
message UMAFeature {
// The type of signal this feature refers to.
// Note: SignalType::UKM_EVENT type is only used for SignalStorageConfig and
// should not be used as uma feature's signal type.
optional SignalType type = 1;
// The human readable name of the histogram or user action.
optional string name = 2;
// The hash of the histogram name or user action. Must match the result of
// base::HashMetricName.
optional fixed64 name_hash = 3;
// Number of buckets to include in the result. If set to 0, no data will be
// collected. This can be used to start storing data before it should be used.
// See documentation for Aggregation for details.
optional uint64 bucket_count = 4;
// The required length of the calculated result. See documentation for
// Aggregation for details.
optional uint64 tensor_length = 5;
// The type of aggregation to use for this particular feature.
optional Aggregation aggregation = 6;
// Only set if type == HISTOGRAM_ENUM.
// Matches are only valid when the enum ID matches any of these.
// Works like an OR condition, e.g.: [url, search, …] or just [url].
repeated int32 enum_ids = 7;
// Only set if aggregation == LATEST_OR_DEFAULT.
// Value used for model if latest value requested is not available in the
// database. The number of entries should be equal to the tensor_length.
repeated float default_values = 8;
}
message CustomInput {
// This parameter is required.
// 1. If the param is directly used as the input tensor field to the model,
// then this specifies the number of columns to fill in the tensor. In this
// case the value should be float.
// 2. If the param is used as a bind value for sql features, then this
// specifies the number of sql bindings to fill in the sql query.
optional int32 tensor_length = 1;
// Used to distinguish between different types of custom inputs.
enum FillPolicy {
// Custom functions provided by the engine that fills in the input feature
// to the model.
UNKNOWN_FILL_POLICY = 0;
// Output is the time at which model prediction is needed. Can be used to
// bind TIME type param to queries.
// Output type: Time
// Output length: 1
FILL_PREDICTION_TIME = 1;
// Output is two timestamps, the beginning and the end of last x days. Can
// be used to bind TIME type param to query within a time interval.
// Output type: Time
// Output length: 2
// Additional arg:
// `bucket_count`: Required. Number of buckets to include in the result.
TIME_RANGE_BEFORE_PREDICTION = 2;
// Used to determine whether a given page is a product details page and can
// be price tracked.
PRICE_TRACKING_HINTS = 3;
// This type of custom input is used directly to fill the input tensor to
// the model or to another query.
// Output type: ProcessedValue
// Output length: 1
// Additional arg:
// `name`: Optional. The name of the field to be looked up in input
// context. If missing then the |name| field is used.
FILL_FROM_INPUT_CONTEXT = 4;
// Output is a tensor of length 10 consisting of float values denoting
// various devices count by type with different form factor and os type.
// See `SyncDeviceInfoObserver` for description of each value.
// Output type: float
// Output length: 10
// Additional arg:
// `wait_for_device_info_in_seconds`: Number of seconds to wait for sync
// device info before timeout. If 0, then does not wait for sync and times
// out immediately if device info is not available.
// InputContext arg:
// `active_days_limit`: Number of days after which the device is
// considered not active after last sync. Must be INT.
FILL_SYNC_DEVICE_INFO = 5;
// Output is a tensor of length 1 consisting device RAM in MB.
// Output type: float
// Output length: 1
FILL_DEVICE_RAM_MB = 6;
// Output is a tensor of length 1 describing device OS level.
// Output type: float
// Output length: 1
FILL_DEVICE_OS_VERSION_NUMBER = 7;
// Output is a tensor of length 1 giving pixels per inch for the current
// device used by the user.
// Output type: float
// Output length: 1
FILL_DEVICE_PPI = 8;
// Fills metrics about a given tab. A `tab_id` and `session_tag` is expected
// from input_context.
// Output type: float
// Output length: `TabSessionSource::kNumInputs`
FILL_TAB_METRICS = 9;
// Fills a random number between [0, 1).
// Output type: float
// Output length: 1
FILL_RANDOM = 10;
// Fill various metrics from the shopping service. Currently only support
// shopping bookmark count.
// Output type: float
// Output length: 1
FILL_FROM_SHOPPING_SERVICE = 11;
}
// The fill type of the custom input.
optional FillPolicy fill_policy = 2;
// If the current chrome version does not support this fill type, use this
// value. If this is not specified and the function is unavailable, the model
// will not run due to missing input. The number of entries should be equal to
// the |tensor_length|.
repeated float default_value = 3;
// If the fill type need additional arguments, use this value.
map<string, string> additional_args = 4;
// The human readable name of the custom input.
optional string name = 5;
}
// Configuration for storing signals in the SQL database.
message SignalFilterConfig {
// Defines a single UKM event that should be stored.
message UkmEvent {
// Event hash of the UKM event.
optional uint64 event_hash = 1;
// List of metric hashes for the event, to store in the database. It is
// is required to provide list of necessary metrics.
// TODO: Support empty metric hash list, the database will store all the
// metrics for the UKM event.
repeated uint64 metric_hash_filter = 2;
}
// List of UKM events to store in the database.
repeated UkmEvent ukm_events = 1;
}
message SqlFeature {
// The query should select a single float column. The query can contain '?'
// which can be used to bind values using |bind_values| list.
// TODO(ssid): Consider expanding this to return multiple input tensor
// features.
optional string sql = 1;
// List of signals needed in the storage for the query.
optional SignalFilterConfig signal_filter = 2;
// Used to bind value for the SQL query.
message BindValue {
// The bind field numbers, in range of 0 to n-1, for n question marks in the
// SQL query.
repeated int32 bind_field_index = 1;
// Used to call Bind*() in sql::Statement.
enum ParamType {
UNKNOWN = 0;
NULL = 1;
BOOL = 2;
INT = 3;
INT64 = 4;
DOUBLE = 5;
STRING = 6;
TIME = 7;
}
optional ParamType param_type = 2;
// Value of the input to bind the query. The custom function should return
// the specified param type. The |tensor_length| should be 0 since these
// inputs can only be used for SQL bind values.
optional CustomInput value = 3;
}
repeated BindValue bind_values = 3;
// The human readable name of the ukm event and metric.
optional string name = 4;
}
// Contains a feature used as an input to the ML model.
message InputFeature {
oneof Feature {
// An UMAFeature type of input feature.
UMAFeature uma_feature = 1;
// A custom input type of input feature.
CustomInput custom_input = 2;
// Input feature computed using SQL query.
SqlFeature sql_feature = 3;
}
}
// Contains a list of training output generators. The ML model pipeline can
// iterate on different output candidates and select the final output generator.
message TrainingOutputs {
repeated TrainingOutput outputs = 1;
// Config for triggering the training outputs data collection for the current
// model.
message TriggerConfig {
// Describes how the training outputs are collected.
enum DecisionType {
// By default considered as PERIODIC type.
UNKNOWN = 0;
// The on demand scheduler will trigger training data collection when the
// client asks for a model execution with input context.
ONDEMAND = 1;
// The periodic scheduler will trigger training data collection everyday.
// Currently this period is fixed on the client to 1 day.
PERIODIC = 2;
}
optional DecisionType decision_type = 1;
message ObservationTrigger {
oneof trigger {
// The delay, in seconds, to collect output tensors after input tensors
// are collected. For example, output labels can be collected one week
// after input tensors are collected. Set to 0 if output tensors need to
// be collected in the same time period as input tensors.
uint64 delay_sec = 1;
// The user action or histogram to trigger a training data output
// collection. Note: Only the name and type should be used with
// bucket_duration = 0.
// TODO(crbug.com/40239034): Figure out how to include the trigger as
// one of the outputs automatically.
UMAOutput uma_trigger = 2;
}
}
// List of triggers, whichever is hit first is used to upload the training
// data.
repeated ObservationTrigger observation_trigger = 2;
// Only for PERIODIC trigger. The prediction and observation times can be
// exact or flexible. The exact prediction setting forces the prediction
// time to be the time at which the segment selection or classification
// result was changed. The input features will be collected till the
// prediction time. Flexible prediction time setting allows the collector to
// pick any point in the past as the prediction time, usually pick the
// current time. The training data collection is triggered once a day with a
// rolling window whenever Chrome is active. This setting uploads more
// training data samples. By default the prediction time is FLEXIBLE. The
// exact observation time setting will be used only in case of exact
// prediction case and the observation starts exactly after prediction time.
// Flexible observation can be used to get most recent user behavior by
// setting observation time to the time of upload, which could be later than
// end of the observation period. By default the observation time is EXACT.
optional bool use_exact_prediction_time = 3;
optional bool use_flexible_observation_time = 4;
}
optional TriggerConfig trigger_config = 2;
}
// Generic type to define how to generate the training data output.
// TODO(xingliu): Add more implementation details about how output training data
// is generated.
message TrainingOutput {
oneof output {
// Training data output is generated from UMA metrics.
UMAOutput uma_output = 1;
}
}
// Contains the information to generate the output for training data based on a
// particular UMA metric.
message UMAOutput {
// The UMA metric to generate the training data output.
optional UMAFeature uma_feature = 1;
// The duration to trigger a training data collection, unit in TimeUnit. If
// not specified or 0, the training data will be generated immediately after
// certain UMA is recorded.
optional uint64 duration = 2;
}
// Metadata about a segmentation model for a given segment. Contains information
// on how to use the model such as collecting signals, interpreting results etc.
// Next tag: 16
message SegmentationModelMetadata {
// Values for obsolete fields.
reserved 15;
// The version information needed to validate segmentation models.
optional VersionInfo version_info = 9;
// DEPRECATED: Use |input_features.uma_feature| instead. Only one of
// |features| or |input_features| can be used in the config, not both. An
// ordered list of required features.
repeated UMAFeature features = 1;
// An ordered list of required features and custom inputs. Only one of
// |features| or |input_features| can be used in the config, not both.
repeated InputFeature input_features = 10;
// A list of training data output definitions.
optional TrainingOutputs training_outputs = 11;
// The time unit to be used for the rest of this proto.
optional TimeUnit time_unit = 2;
// The size of each interval the data should be aggregated over.
optional uint64 bucket_duration = 3;
// For how long should data be stored for this model.
optional int64 signal_storage_length = 4;
// For how long do we have to have captured data for this model. If the
// relevant signals have been captured for a shorter amount of time than this,
// this model can never be selected.
optional int64 min_signal_collection_length = 5;
// Describes how long after a valid result has been calculated for this model
// it is OK to cache the result without recalculating with updated data.
optional int64 result_time_to_live = 6;
message DiscreteMapping {
// A mapping result from the raw continuous result to a discrete and
// comparable value based on |rank|.
message Entry {
// The minimum result of the model to be allowed to choose this mapping.
optional float min_result = 1;
// A feature specific rank.
optional int64 rank = 2;
}
// An ordered (based on their |min_result|) list of discrete mappings.
// To map a model evaluation result to a DiscreteMapping, choose the highest
// |min_value| that the evaluation result is at or above.
// E.g. for these mappings: [(0.0, 0), (0.4, 1), (0.7, 2), (0.9, 3)], a
// result of 0.7 would yield (0.7, 2), and 0.69 would yield (0.4, 1).
repeated Entry entries = 1;
}
map<string, DiscreteMapping> discrete_mappings = 7;
// The default key to use during the mapping process if no key has been
// provided.
optional string default_discrete_mapping = 8;
// The delay, in seconds, to collect output tensors after input tensors are
// collected. For example, output labels can be collected one week after input
// tensors are collected. If not specified, output tensors are collected in
// the same time period as input tensors.
// DEPRECATED: optional int64 output_collection_delay_sec = 12;
reserved 12;
// Whether the client should upload the input and output tensors through UKM.
optional bool upload_tensors = 13;
// Describes the return type of the model score. Used for recording
// histograms.
enum OutputDescription {
UNKNOWN_RETURN_TYPE = 0;
// Model returns either 0 or 1.
RETURN_TYPE_HEURISTIC = 1;
// Model returns an int corresponding to a specific subsegment. Assume
// between 0 and 100.
RETURN_TYPE_MULTISEGMENT = 2;
// Model returns a float between 0 and 1.
RETURN_TYPE_PROBABILITY = 3;
// Model returns any integer value.
RETURN_TYPE_INTEGER = 4;
}
// TODO(ritikagup@): Deprecate the field.
optional OutputDescription return_type = 14;
// Contains information about the model results. Supplied by the client. It
// gives a description of how should the results look like and how to
// interpret them.
optional OutputConfig output_config = 16;
}
Codebase Browser
chromium