Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/keras/src/estimator/__init__.py: 40%
20 statements
« prev ^ index » next coverage.py v7.4.0, created at 2024-01-03 07:57 +0000
1# Copyright 2018 The TensorFlow Authors. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14# ==============================================================================
15"""Keras estimator API."""
17import tensorflow.compat.v2 as tf
19# isort: off
20from tensorflow.python.util.tf_export import keras_export
22# Keras has undeclared dependency on tensorflow/estimator:estimator_py.
23# As long as you depend //third_party/py/tensorflow:tensorflow target
24# everything will work as normal.
26_model_to_estimator_usage_gauge = tf.__internal__.monitoring.BoolGauge(
27 "/tensorflow/api/keras/model_to_estimator",
28 "Whether tf.keras.estimator.model_to_estimator() is called.",
29 "version",
30)
33# LINT.IfChange
34@keras_export(v1=["keras.estimator.model_to_estimator"])
35def model_to_estimator(
36 keras_model=None,
37 keras_model_path=None,
38 custom_objects=None,
39 model_dir=None,
40 config=None,
41 checkpoint_format="saver",
42 metric_names_map=None,
43 export_outputs=None,
44):
45 """Constructs an `Estimator` instance from given keras model.
47 If you use infrastructure or other tooling that relies on Estimators, you
48 can still build a Keras model and use model_to_estimator to convert the
49 Keras model to an Estimator for use with downstream systems.
51 For usage example, please see:
52 [Creating estimators from Keras Models](
53 https://www.tensorflow.org/guide/estimator#create_an_estimator_from_a_keras_model).
55 Sample Weights:
56 Estimators returned by `model_to_estimator` are configured so that they can
57 handle sample weights (similar to `keras_model.fit(x, y, sample_weights)`).
59 To pass sample weights when training or evaluating the Estimator, the first
60 item returned by the input function should be a dictionary with keys
61 `features` and `sample_weights`. Example below:
63 ```python
64 keras_model = tf.keras.Model(...)
65 keras_model.compile(...)
67 estimator = tf.keras.estimator.model_to_estimator(keras_model)
69 def input_fn():
70 return dataset_ops.Dataset.from_tensors(
71 ({'features': features, 'sample_weights': sample_weights},
72 targets))
74 estimator.train(input_fn, steps=1)
75 ```
77 Example with customized export signature:
78 ```python
79 inputs = {'a': tf.keras.Input(..., name='a'),
80 'b': tf.keras.Input(..., name='b')}
81 outputs = {'c': tf.keras.layers.Dense(..., name='c')(inputs['a']),
82 'd': tf.keras.layers.Dense(..., name='d')(inputs['b'])}
83 keras_model = tf.keras.Model(inputs, outputs)
84 keras_model.compile(...)
85 export_outputs = {'c': tf.estimator.export.RegressionOutput,
86 'd': tf.estimator.export.ClassificationOutput}
88 estimator = tf.keras.estimator.model_to_estimator(
89 keras_model, export_outputs=export_outputs)
91 def input_fn():
92 return dataset_ops.Dataset.from_tensors(
93 ({'features': features, 'sample_weights': sample_weights},
94 targets))
96 estimator.train(input_fn, steps=1)
97 ```
99 Args:
100 keras_model: A compiled Keras model object. This argument is mutually
101 exclusive with `keras_model_path`. Estimator's `model_fn` uses the
102 structure of the model to clone the model. Defaults to `None`.
103 keras_model_path: Path to a compiled Keras model saved on disk, in HDF5
104 format, which can be generated with the `save()` method of a Keras
105 model. This argument is mutually exclusive with `keras_model`.
106 Defaults to `None`.
107 custom_objects: Dictionary for cloning customized objects. This is
108 used with classes that is not part of this pip package. For example, if
109 user maintains a `relu6` class that inherits from
110 `tf.keras.layers.Layer`, then pass `custom_objects={'relu6': relu6}`.
111 Defaults to `None`.
112 model_dir: Directory to save `Estimator` model parameters, graph, summary
113 files for TensorBoard, etc. If unset a directory will be created with
114 `tempfile.mkdtemp`
115 config: `RunConfig` to config `Estimator`. Allows setting up things in
116 `model_fn` based on configuration such as `num_ps_replicas`, or
117 `model_dir`. Defaults to `None`. If both `config.model_dir` and the
118 `model_dir` argument (above) are specified the `model_dir` **argument**
119 takes precedence.
120 checkpoint_format: Sets the format of the checkpoint saved by the
121 estimator when training. May be `saver` or `checkpoint`, depending on
122 whether to save checkpoints from `tf.train.Saver` or
123 `tf.train.Checkpoint`. This argument currently defaults to `saver`. When
124 2.0 is released, the default will be `checkpoint`. Estimators use
125 name-based `tf.train.Saver` checkpoints, while Keras models use
126 object-based checkpoints from `tf.train.Checkpoint`. Currently, saving
127 object-based checkpoints from `model_to_estimator` is only supported by
128 Functional and Sequential models. Defaults to 'saver'.
129 metric_names_map: Optional dictionary mapping Keras model output metric
130 names to custom names. This can be used to override the default Keras
131 model output metrics names in a multi IO model use case and provide
132 custom names for the `eval_metric_ops` in Estimator.
133 The Keras model metric names can be obtained using `model.metrics_names`
134 excluding any loss metrics such as total loss and output losses.
135 For example, if your Keras model has two outputs `out_1` and `out_2`,
136 with `mse` loss and `acc` metric, then `model.metrics_names` will be
137 `['loss', 'out_1_loss', 'out_2_loss', 'out_1_acc', 'out_2_acc']`.
138 The model metric names excluding the loss metrics will be
139 `['out_1_acc', 'out_2_acc']`.
140 export_outputs: Optional dictionary. This can be used to override the
141 default Keras model output exports in a multi IO model use case and
142 provide custom names for the `export_outputs` in
143 `tf.estimator.EstimatorSpec`. Default is None, which is equivalent to
144 {'serving_default': `tf.estimator.export.PredictOutput`}. If not None,
145 the keys must match the keys of `model.output_names`.
146 A dict `{name: output}` where:
147 * name: An arbitrary name for this output.
148 * output: an `ExportOutput` class such as `ClassificationOutput`,
149 `RegressionOutput`, or `PredictOutput`. Single-headed models only
150 need to specify one entry in this dictionary. Multi-headed models
151 should specify one entry for each head, one of which must be named
152 using
153 `tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY`
154 If no entry is provided, a default `PredictOutput` mapping to
155 `predictions` will be created.
157 Returns:
158 An Estimator from given keras model.
160 Raises:
161 ValueError: If neither keras_model nor keras_model_path was given.
162 ValueError: If both keras_model and keras_model_path was given.
163 ValueError: If the keras_model_path is a GCS URI.
164 ValueError: If keras_model has not been compiled.
165 ValueError: If an invalid checkpoint_format was given.
166 """
168 try:
169 # isort: off
170 from tensorflow_estimator.python.estimator import (
171 keras_lib,
172 )
173 except ImportError:
174 raise NotImplementedError(
175 "tf.keras.estimator.model_to_estimator function not available in "
176 "your installation."
177 )
178 _model_to_estimator_usage_gauge.get_cell("v1").set(True)
179 return keras_lib.model_to_estimator(
180 keras_model=keras_model,
181 keras_model_path=keras_model_path,
182 custom_objects=custom_objects,
183 model_dir=model_dir,
184 config=config,
185 checkpoint_format=checkpoint_format,
186 use_v2_estimator=False,
187 metric_names_map=metric_names_map,
188 export_outputs=export_outputs,
189 )
192@keras_export("keras.estimator.model_to_estimator", v1=[])
193def model_to_estimator_v2(
194 keras_model=None,
195 keras_model_path=None,
196 custom_objects=None,
197 model_dir=None,
198 config=None,
199 checkpoint_format="checkpoint",
200 metric_names_map=None,
201 export_outputs=None,
202):
203 """Constructs an `Estimator` instance from given keras model.
205 If you use infrastructure or other tooling that relies on Estimators, you
206 can still build a Keras model and use model_to_estimator to convert the
207 Keras model to an Estimator for use with downstream systems.
209 For usage example, please see:
210 [Creating estimators from Keras Models](
211 https://www.tensorflow.org/guide/estimators#creating_estimators_from_keras_models).
213 Sample Weights:
214 Estimators returned by `model_to_estimator` are configured so that they can
215 handle sample weights (similar to `keras_model.fit(x, y, sample_weights)`).
217 To pass sample weights when training or evaluating the Estimator, the first
218 item returned by the input function should be a dictionary with keys
219 `features` and `sample_weights`. Example below:
221 ```python
222 keras_model = tf.keras.Model(...)
223 keras_model.compile(...)
225 estimator = tf.keras.estimator.model_to_estimator(keras_model)
227 def input_fn():
228 return dataset_ops.Dataset.from_tensors(
229 ({'features': features, 'sample_weights': sample_weights},
230 targets))
232 estimator.train(input_fn, steps=1)
233 ```
235 Example with customized export signature:
236 ```python
237 inputs = {'a': tf.keras.Input(..., name='a'),
238 'b': tf.keras.Input(..., name='b')}
239 outputs = {'c': tf.keras.layers.Dense(..., name='c')(inputs['a']),
240 'd': tf.keras.layers.Dense(..., name='d')(inputs['b'])}
241 keras_model = tf.keras.Model(inputs, outputs)
242 keras_model.compile(...)
243 export_outputs = {'c': tf.estimator.export.RegressionOutput,
244 'd': tf.estimator.export.ClassificationOutput}
246 estimator = tf.keras.estimator.model_to_estimator(
247 keras_model, export_outputs=export_outputs)
249 def input_fn():
250 return dataset_ops.Dataset.from_tensors(
251 ({'features': features, 'sample_weights': sample_weights},
252 targets))
254 estimator.train(input_fn, steps=1)
255 ```
257 Note: We do not support creating weighted metrics in Keras and converting
258 them to weighted metrics in the Estimator API using `model_to_estimator`.
259 You will have to create these metrics directly on the estimator spec using
260 the `add_metrics` function.
262 To customize the estimator `eval_metric_ops` names, you can pass in the
263 `metric_names_map` dictionary mapping the keras model output metric names
264 to the custom names as follows:
266 ```python
267 input_a = tf.keras.layers.Input(shape=(16,), name='input_a')
268 input_b = tf.keras.layers.Input(shape=(16,), name='input_b')
269 dense = tf.keras.layers.Dense(8, name='dense_1')
270 interm_a = dense(input_a)
271 interm_b = dense(input_b)
272 merged = tf.keras.layers.concatenate([interm_a, interm_b], name='merge')
273 output_a = tf.keras.layers.Dense(3, activation='softmax', name='dense_2')(
274 merged)
275 output_b = tf.keras.layers.Dense(2, activation='softmax', name='dense_3')(
276 merged)
277 keras_model = tf.keras.models.Model(
278 inputs=[input_a, input_b], outputs=[output_a, output_b])
279 keras_model.compile(
280 loss='categorical_crossentropy',
281 optimizer='rmsprop',
282 metrics={
283 'dense_2': 'categorical_accuracy',
284 'dense_3': 'categorical_accuracy'
285 })
287 metric_names_map = {
288 'dense_2_categorical_accuracy': 'acc_1',
289 'dense_3_categorical_accuracy': 'acc_2',
290 }
291 keras_est = tf.keras.estimator.model_to_estimator(
292 keras_model=keras_model,
293 config=config,
294 metric_names_map=metric_names_map)
295 ```
297 Args:
298 keras_model: A compiled Keras model object. This argument is mutually
299 exclusive with `keras_model_path`. Estimator's `model_fn` uses the
300 structure of the model to clone the model. Defaults to `None`.
301 keras_model_path: Path to a compiled Keras model saved on disk, in HDF5
302 format, which can be generated with the `save()` method of a Keras
303 model. This argument is mutually exclusive with `keras_model`.
304 Defaults to `None`.
305 custom_objects: Dictionary for cloning customized objects. This is
306 used with classes that is not part of this pip package. For example, if
307 user maintains a `relu6` class that inherits from
308 `tf.keras.layers.Layer`, then pass `custom_objects={'relu6': relu6}`.
309 Defaults to `None`.
310 model_dir: Directory to save `Estimator` model parameters, graph, summary
311 files for TensorBoard, etc. If unset a directory will be created with
312 `tempfile.mkdtemp`
313 config: `RunConfig` to config `Estimator`. Allows setting up things in
314 `model_fn` based on configuration such as `num_ps_replicas`, or
315 `model_dir`. Defaults to `None`. If both `config.model_dir` and the
316 `model_dir` argument (above) are specified the `model_dir` **argument**
317 takes precedence.
318 checkpoint_format: Sets the format of the checkpoint saved by the
319 estimator when training. May be `saver` or `checkpoint`, depending on
320 whether to save checkpoints from `tf.compat.v1.train.Saver` or
321 `tf.train.Checkpoint`. The default is `checkpoint`. Estimators use
322 name-based `tf.train.Saver` checkpoints, while Keras models use
323 object-based checkpoints from `tf.train.Checkpoint`. Currently, saving
324 object-based checkpoints from `model_to_estimator` is only supported by
325 Functional and Sequential models. Defaults to 'checkpoint'.
326 metric_names_map: Optional dictionary mapping Keras model output metric
327 names to custom names. This can be used to override the default Keras
328 model output metrics names in a multi IO model use case and provide
329 custom names for the `eval_metric_ops` in Estimator.
330 The Keras model metric names can be obtained using `model.metrics_names`
331 excluding any loss metrics such as total loss and output losses.
332 For example, if your Keras model has two outputs `out_1` and `out_2`,
333 with `mse` loss and `acc` metric, then `model.metrics_names` will be
334 `['loss', 'out_1_loss', 'out_2_loss', 'out_1_acc', 'out_2_acc']`.
335 The model metric names excluding the loss metrics will be
336 `['out_1_acc', 'out_2_acc']`.
337 export_outputs: Optional dictionary. This can be used to override the
338 default Keras model output exports in a multi IO model use case and
339 provide custom names for the `export_outputs` in
340 `tf.estimator.EstimatorSpec`. Default is None, which is equivalent to
341 {'serving_default': `tf.estimator.export.PredictOutput`}. If not None,
342 the keys must match the keys of `model.output_names`.
343 A dict `{name: output}` where:
344 * name: An arbitrary name for this output.
345 * output: an `ExportOutput` class such as `ClassificationOutput`,
346 `RegressionOutput`, or `PredictOutput`. Single-headed models only
347 need to specify one entry in this dictionary. Multi-headed models
348 should specify one entry for each head, one of which must be named
349 using
350 `tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY`
351 If no entry is provided, a default `PredictOutput` mapping to
352 `predictions` will be created.
354 Returns:
355 An Estimator from given keras model.
357 Raises:
358 ValueError: If neither keras_model nor keras_model_path was given.
359 ValueError: If both keras_model and keras_model_path was given.
360 ValueError: If the keras_model_path is a GCS URI.
361 ValueError: If keras_model has not been compiled.
362 ValueError: If an invalid checkpoint_format was given.
363 """
365 try:
366 # isort: off
367 from tensorflow_estimator.python.estimator import (
368 keras_lib,
369 )
370 except ImportError:
371 raise NotImplementedError(
372 "tf.keras.estimator.model_to_estimator function not available in "
373 "your installation."
374 )
375 _model_to_estimator_usage_gauge.get_cell("v2").set(True)
376 return keras_lib.model_to_estimator(
377 keras_model=keras_model,
378 keras_model_path=keras_model_path,
379 custom_objects=custom_objects,
380 model_dir=model_dir,
381 config=config,
382 checkpoint_format=checkpoint_format,
383 use_v2_estimator=True,
384 metric_names_map=metric_names_map,
385 export_outputs=export_outputs,
386 )
389# LINT.ThenChange(//tensorflow_estimator/python/estimator/keras_lib.py)