tfboys——tensorflow模块学习（三）

2024年5月3日 132次阅读来源: tensorflow

tf.estimator模块

定义在：tensorflow/python/estimator/estimator_lib.py

估算器（Estimator）：用于处理模型的高级工具。

主要模块

export 模块：用于导出估算器的实用方法。

inputs 模块：用于创建简单的 input_fns 的实用方法。

类

class DNNClassifier：TensorFlow DNN 模型的分类器。

class DNNLinearCombinedClassifier：TensorFlow Linear 和 DNN 连接的分类模型的估计器。

class DNNLinearCombinedRegressor：TensorFlow Linear 和 DNN 连接的回归模型的估计器。

class DNNRegressor：TensorFlow DNN 模型的回归器。

class Estimator：用于训练和评估 TensorFlow 模型的估计器类。

class EstimatorSpec：从 model_fn 返回的操作和对象，并传递给 Estimator。

class LinearClassifier：线性分类器模型。

class LinearRegressor：TensorFlow 线性回归问题的估计器。

class ModeKeys：模型模式的标准名称。

class RunConfig：此类指定 Estimator 运行的配置。

函数

classifier_parse_example_spec(…)：为 tf.parse_example 生成用于分类器的解析规范。

regressor_parse_example_spec(…)：为 tf.parse_example 生成用于回归的解析规范。

tf.estimator.classifier_parse_example_spec 生成解析规范

classifier_parse_example_spec(
    feature_columns,
    label_key,
    label_dtype=tf.int64,
    label_default=None,
    weight_column=None
)
定义在：tensorflow/python/estimator/canned/parsing_utils.py。
生成用于分类器的 tf.parse_example 的解析规范。
如果用户将数据保存在 tf.Example 格式中，则需要使用适当的函数参数调用 tf. parse_example。此实用程序有两个主要的帮助:
用户需要将函数的解析规范与标签和权重（如果有的话）相结合，因为它们都是从相同的 tf.Example 实例中解析出来的。该实用程序组合了这些规范。
通过分类器（如 DNNClassifie）将预期标签映射到相应的 tf.parse_example 规范是很困难的。该实用程序通过用户（key，dtype）获取相关信息对其进行编码。
解析规范示例输出：
# Define features and transformations
feature_b = tf.feature_column.numeric_column(...)
feature_c_bucketized = tf.feature_column.bucketized_column(
  tf.feature_column.numeric_column("feature_c"), ...)
feature_a_x_feature_c = tf.feature_column.crossed_column(
    columns=["feature_a", feature_c_bucketized], ...)

feature_columns = [feature_b, feature_c_bucketized, feature_a_x_feature_c]
parsing_spec = tf.estimator.classifier_parse_example_spec(
    feature_columns, label_key='my-label', label_dtype=tf.string)

# For the above example, classifier_parse_example_spec would return the dict:
assert parsing_spec == {
  "feature_a": parsing_ops.VarLenFeature(tf.string),
  "feature_b": parsing_ops.FixedLenFeature([1], dtype=tf.float32),
  "feature_c": parsing_ops.FixedLenFeature([1], dtype=tf.float32)
  "my-label" : parsing_ops.FixedLenFeature([1], dtype=tf.string)
}
分类器使用示例：
feature_columns = # define features via tf.feature_column
estimator = DNNClassifier(
    n_classes=1000,
    feature_columns=feature_columns,
    weight_column='example-weight',
    label_vocabulary=['photos', 'keep', ...],
    hidden_units=[256, 64, 16])
# This label configuration tells the classifier the following:
# * weights are retrieved with key 'example-weight'
# * label is string and can be one of the following ['photos', 'keep', ...]
# * integer id for label 'photos' is 0, 'keep' is 1, ...

# Input builders
def input_fn_train():  # Returns a tuple of features and labels.
  features = tf.contrib.learn.read_keyed_batch_features(
      file_pattern=train_files,
      batch_size=batch_size,
      # creates parsing configuration for tf.parse_example
      features=tf.estimator.classifier_parse_example_spec(
          feature_columns,
          label_key='my-label',
          label_dtype=tf.string,
          weight_column='example-weight'),
      reader=tf.RecordIOReader)
   labels = features.pop('my-label')
   return features, labels

estimator.train(input_fn=input_fn_train)
ARGS：
feature_columns：一个包含所有特征列的 iterable。所有项目都应该是从 _FeatureColumn 派生的类的实例。
label_key：标识标签的字符串。这意味着 tf.Example 使用这个键存储标签。
label_dtype：一个 tf.dtype 标识标签的类型。默认情况下是 tf.int64。如果用户定义了一个 label_vocabulary，则应将其设置为 tf.string。tf.float32 标签仅支持二进制分类。
label_default：如果在给定的 tf.Example 中不存在 label_key，则用作标签。一个示例用法：假设 label_key 是 “clicked”，并且 tf.Example 仅包含以下 key 格式的正示例的点击数据：clicked, value:1。这意味着如果没有键 “clicked” 的数据，应该通过设置 label_deafault=0 来计算为负的示例。该值的类型应与 label_dtype 兼容。
weight_column：通过 tf.feature_column.numeric_column 创建的一个字符串或者 _NumericColumn，用来定义表示权重的特征列。在训练过程中，它用于降低权重或增加实例。它将乘以示例的损失。如果它是一个字符串，它被用作 key 并从特征中获取权重张量。如果是 _NumericColumn，则通过键weight_column.key 获取原始张量，然后在其上应用 weight_column.normalizer_fn 以获得权重张量。
返回：
返回一个字典将每个特征键映射到 FixedLenFeature 或 VarLenFeature 值。
注意：
ValueError：如果标签中使用 feature_columns。
ValueError：如果在 feature_columns 中使用 weight_column 。
ValueError：如果给定的 feature_columns 不是一个 _FeatureColumn 实例。
ValueError：如果 weight_column 不是一个 _NumericColumn 实例。
ValueError：如果 label_key 为 None。

`tf.estimator.DNNClassifier` 使用DNN模型分类器

DNNClassifier 类
继承自： Estimator
定义在：tensorflow/python/estimator/canned/dnn.py。
TensorFlow DNN 模型的分类器。
例：
sparse_feature_a = sparse_column_with_hash_bucket(...)
sparse_feature_b = sparse_column_with_hash_bucket(...)

sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a,
                                        ...)
sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b,
                                        ...)

estimator = DNNClassifier(
    feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb],
    hidden_units=[1024, 512, 256])

# Or estimator using the ProximalAdagradOptimizer optimizer with
# regularization.
estimator = DNNClassifier(
    feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb],
    hidden_units=[1024, 512, 256],
    optimizer=tf.train.ProximalAdagradOptimizer(
      learning_rate=0.1,
      l1_regularization_strength=0.001
    ))

# Input builders
def input_fn_train: # returns x, y
  pass
estimator.train(input_fn=input_fn_train, steps=100)

def input_fn_eval: # returns x, y
  pass
metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10)
def input_fn_predict: # returns x, None
  pass
predictions = estimator.predict(input_fn=input_fn_predict)
输入的 train 和 evaluate 应具有以下特点，否则将会产生 KeyError：
如果 weight_column 不是 None，则有特性：key=weight_column，其值为张量。
对于 feature_columns 中的每一列：
如果列是 _CategoricalColumn，则有特性：key=column.name，其值是一个 SparseTensor。
如果列是一个 _WeightedCategoricalColumn，则有两个特性：第一个是带有 key 的 id 列名称，第二个是带有 key 的权重列名称。这两个特性的值必须是SparseTensor。
如果列是 _DenseColumn，则有一个特性：key=column.name，其值是一个 Tensor。
损失是通过使用 softmax 交叉熵计算的。
属性
config
model_dir
params
方法
__init__
__init__(
    hidden_units,
    feature_columns,
    model_dir=None,
    n_classes=2,
    weight_column=None,
    label_vocabulary=None,
    optimizer='Adagrad',
    activation_fn=tf.nn.relu,
    dropout=None,
    input_layer_partitioner=None,
    config=None
)
初始化一个 DNNClassifier 实例。
ARGS：
hidden_units：每层隐藏单元的 Iterable 数。所有层都完全连接。注意：[64, 32]意味着第一层有64个节点，第二层有32个节点。
feature_columns：包含模型使用的所有特征列的 iterable。集合中的所有项目都应该是从 _FeatureColumn 派生的类的实例。
model_dir：用来保存模型参数，图形等的目录。这也可用于将检查点从目录加载到 estimator 中，以继续训练以前保存的模型。
n_classes：标签类的数量。默认为 2，即二进制分类，必须大于1。
weight_column：通过 tf.feature_column.numeric_column 创建的一个字符串或者 _NumericColumn，用来定义表示权重的特征列。在训练过程中，它用于降低权重或增加实例。它将乘以示例的损失。如果它是一个字符串，则被用作从特征中中获取权重张量的 key；如果是 _NumericColumn，则通过键 weight_column.key 获取原始张量，然后在其上应用 weight_column.normalizer_fn 以获得权重张量。
label_vocabulary：字符串列表，表示可能的标签值。如果给定，标签必须是字符串类型，并且 label_vocabulary 具有任何值。如果没有给出，这意味着标签已经被编码为整数或者在[0，1]内浮动， n_classes=2 ；并且被编码为{0，1，…，n_classes-1}中的整数值，n_classes> 2。如果没有提供词汇表并且标签是字符串，也会出现错误。
optimizer：tf.Optimizer 用于训练模型的实例。默认为 Adagrad 优化器。
activation_fn：激活函数应用于每个层。如果为 None，将使用 tf.nn.relu。
dropout：当不是 None 时，我们将放弃给定坐标的概率。
input_layer_partitioner：（可选）输入层分区。默认为 min_max_variable_partitioner 与 min_slice_size64 << 20。
config：RunConfig 对象配置运行时设置。
evaluate
evaluate(
    input_fn,
    steps=None,
    hooks=None,
    checkpoint_path=None,
    name=None
)
评估给定的评估数据 input_fn 的模型。
对于每个步骤，调用 input_fn，它返回一组数据。评估结束条件：达到 – steps 批处理，或 – input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor或带标签的张量字典。
steps：评估模型的步骤数。如果为 None，直到 input_fn 引发 end-of-input 异常时，评估结束。
hooks：SessionRunHook 子类实例的列表，用于评估调用中的回调。
checkpoint_path：要评估的特定检查点的路径。如果为 None，则使用 model_dir 中的最新检查点。
name：如果用户需要在不同数据集上运行多个评估，例如培训数据与测试数据，则设置评估的名称。不同评估的度量值保存在单独的文件夹中，并在 tensorboard 中单独显示。
返回：
包含 model_fn 按名称键入指定的评估度量的 dict ，以及一个条目 global_step，它包含执行此评估的全局步骤值。
注意：
ValueError：如果 steps <= 0。
ValueError：如果没有训练模型，即 model_dir，或者给定的 checkpoint_path 是空的。
export_savedmodel
export_savedmodel(
    export_dir_base,
    serving_input_receiver_fn,
    assets_extra=None,
    as_text=False,
    checkpoint_path=None
)
将推理图作为 SavedModel 导出到给定的目录中。
此方法首先调用 serve_input_receiver_fn 来获取特征 Tensors，然后调用此 Estimator 的 model_fn 以生成基于这些特征的模型图，从而构建新的图。它在新的会话中将给定的检查点（或缺少最新的检查点）还原到此图中。最后，它在给定的 export_dir_base 下面创建一个时间戳的导出目录，并将 SavedModel 写入其中，其中包含从此会话保存的单个 MetaGraphDef。
导出的 MetaGraphDef 将为从 model_fn 返回的 export_outputs 字典的每个元素提供一个 SignatureDef，使用相同的键命名。这些密钥之一始终是signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY，指示当一个服务请求没有指定时将提供哪个签名。对于每个签名，输出由相应的ExportOutputs 提供，并且输入始终是由 serve_input_receiver_fn 提供的输入接收器。
额外的资产可以通过 extra_assets 参数写入 SavedModel。这应该是一个 dict，其中每个键都给出了相对于 assets.extra 目录的目标路径（包括文件名）。相应的值给出要复制的源文件的完整路径。例如，复制单个文件而不重命名的简单情况被指定为：{‘my_asset_file.txt’: ‘/path/to/my_asset_file.txt’}。
ARGS：
export_dir_base：一个包含一个目录的字符串，用于创建包含导出的 SavedModels 的时间戳子目录。
serving_input_receiver_fn：一个不带参数并返回 ServingInputReceiver 的函数。
assets_extra：指定如何在导出的 SavedModel 中填充 asset.extra 目录的 dict，如果为 None，则不需要额外的资源。
as_text：是否以文本格式写入 SavedModel 原型。
checkpoint_path：要导出的检查点路径。如果为 None（默认值），则选择在模型目录中找到的最新检查点。
返回：
导出目录的字符串路径。
注意：
ValueError：如果没有提供 serve_input_receiver_fn，则不提供 export_outputs，或者没有找到任何检查点。
predict
predict(
    input_fn,
    predict_keys=None,
    hooks=None,
    checkpoint_path=None
)
返回给定功能的预测。
ARGS：
input_fn：输入函数返回的特征，是字符串特征名称字典的 Tensor 或 SparseTensor。如果它返回一个元组，则第一个项目被提取为特征。预测继续，直到input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
predict_keys：str 列表，要预测的键的名称。如果 EstimatorSpec.predictions 是 dict，则使用它。如果使用 predict_keys，那么其余的预测将从字典中过滤掉。如果为 None，则返回所有。
hooks：SessionRunHook 子类实例列表。用于预测调用内的回调。
checkpoint_path：对具体检查点的路径进行预测。如果为 None，则使用 model_dir 中的最新检查点。
获取：
计算预测张量的值。
注意：
ValueError：在 model_dir 中找不到训练有素的模型。
ValueError：如果批量长度的预测不一致。
ValueError：如果 predict_keys 和 predictions 之间存在冲突。例如，如果 predict_keys 不是 None，但 EstimatorSpec.predictions 不是 dict。
train
train(
    input_fn,
    hooks=None,
    steps=None,
    max_steps=None
)
训练一个给定训练数据 input_fn 的模型。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor 或带标签的张量字典。
hooks：SessionRunHook 子类实例列表。用于训练循环内的回调。
steps：用于训练模型的步骤数。如果为 None，永远训练或训练直到 input_fn 生成 OutOfRange 或 StopIteration 错误。“steps”是逐步进行的。如果你调用两次 train（steps = 10），那么 train 总共有20步。如果 OutOfRange 或 StopIteration 在中间出现差错，train将在前20步之前停止。如果您不想增加行为，请设置 max_steps 代替。如果设置，max_steps 必须为 None。
max_steps：用于 train 模型的总步骤数。如果为 None，永远训练或训练，直到 input_fn 生成 OutOfRange 或 StopIteration 错误。如果设置，steps 必须为None。如果 OutOfRange 或者 StopIteration 在中间出现差错，训练之前应停止 max_steps 步骤。两次调用 train (steps=100) 意味着 200次 train 迭代。另一方面，两个调用 train(max_steps=100)意味着第二次调用将不会执行任何迭代，因为第一次调用完成了所有的100个步骤。
返回：
返回 self，用于链接。
注意：
ValueError：如果两个 steps 和 max_steps 都不是 None。
ValueError：如果任一 steps 或是 max_steps <= 0。

tf.estimator.DNNLinearCombinedClassifier

DNNLinearCombinedClassifier 类
继承自： Estimator
定义在：tensorflow/python/estimator/canned/dnn_linear_combined.py。
TensorFlow Linear 和 DNN 的估算器（estimator）加入了分类模型。
注意：此估算器（estimator）也称为 wide-n-deep。
例：
numeric_feature = numeric_column(...)
sparse_column_a = categorical_column_with_hash_bucket(...)
sparse_column_b = categorical_column_with_hash_bucket(...)

sparse_feature_a_x_sparse_feature_b = crossed_column(...)
sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a,
                                        ...)
sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b,
                                        ...)

estimator = DNNLinearCombinedClassifier(
    # wide settings
    linear_feature_columns=[sparse_feature_a_x_sparse_feature_b],
    linear_optimizer=tf.train.FtrlOptimizer(...),
    # deep settings
    dnn_feature_columns=[
        sparse_feature_a_emb, sparse_feature_b_emb, numeric_feature],
    dnn_hidden_units=[1000, 500, 100],
    dnn_optimizer=tf.train.ProximalAdagradOptimizer(...))

# To apply L1 and L2 regularization, you can set optimizers as follows:
tf.train.ProximalAdagradOptimizer(
    learning_rate=0.1,
    l1_regularization_strength=0.001,
    l2_regularization_strength=0.001)
# It is same for FtrlOptimizer.

# Input builders
def input_fn_train: # returns x, y
  pass
estimator.train(input_fn=input_fn_train, steps=100)

def input_fn_eval: # returns x, y
  pass
metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10)
def input_fn_predict: # returns x, None
  pass
predictions = estimator.predict(input_fn=input_fn_predict)
输入的 train 和 evaluate 应具有以下特点，否则将会产生 KeyError：
对于 dnn_feature_columns+ linear_feature_columns 中的每一列：
如果列是 _CategoricalColumn，则具有 key=column.name 并且其值是一个 SparseTensor 的特点。
如果列是一个 _WeightedCategoricalColumn，则具有两个特点：第一个是带有键的 ID 列名称，第二个是具有键权重列名称。这两个特点的值必须是SparseTensor。
如果列是 _DenseColumn，则有特点：key = column.name 并且其值是一个 Tensor。
利用 softmax 交叉熵计算损失。
属性
config
model_dir
params
方法
__init__
__init__(
    model_dir=None,
    linear_feature_columns=None,
    linear_optimizer='Ftrl',
    dnn_feature_columns=None,
    dnn_optimizer='Adagrad',
    dnn_hidden_units=None,
    dnn_activation_fn=tf.nn.relu,
    dnn_dropout=None,
    n_classes=2,
    weight_column=None,
    label_vocabulary=None,
    input_layer_partitioner=None,
    config=None
)
初始化 DNNLinearCombinedClassifier 实例。
ARGS：
model_dir：保存模型参数、图形等的目录。这也可用于将检查点从目录加载到估算器中，以继续训练以前保存的模型。
linear_feature_columns：包含模型线性部分使用的所有特征列的 iterable（迭代）。集合中的所有项目都必须是从 FeatureColumn 派生的类的实例。
linear_optimizer：tf.Optimizer 用于将渐变应用于模型的线性部分的实例。默认为 FTRL 优化器。
dnn_feature_columns：包含模型深层部分所使用的所有特征列的 iterable。集合中的所有项目都必须是从 FeatureColumn 派生的类的实例。
dnn_optimizer：tf.Optimizer 用于将渐变应用于模型的深层部分的实例。默认为 Adagrad 优化器。
dnn_hidden_units：每层隐藏单位的列表。所有层都完全连接。
dnn_activation_fn：激活函数应用于每个层。如果无，将使用 tf.nn.relu。
dnn_dropout：当不是 None 时，我们将放弃一个给定的坐标的概率。
n_classes：标签类的数量。默认为 2，即二进制分类，必须大于1。
weight_column：通过 tf.feature_column.numeric_column 创建的一个字符串或者 _NumericColumn 用来定义表示权重的特征列。在 train 过程中，它用于降低权重或增加实例。它将乘以例子的损失。如果它是一个字符串，它是用来作为一个键从特征提取权重张量；如果是 _NumericColumn，则通过键获取原始张量weight_column.key，然后在其上应用 weight_column.normalizer_fn 以获得权重张量。
label_vocabulary：字符串列表表示可能的标签值。如果给定，标签必须是字符串类型，并且在 label_vocabulary 中具有任何值。如果没有给出，这意味着标签已经被编码为整数或者在[0，1]内浮动， n_classes=2 ；并且被编码为{0，1，…，n_classes-1}中的整数值，n_classes> 2。如果没有提供词汇表并且标签是字符串，也会出现错误。
input_layer_partitioner：输入层分区。默认为 min_max_variable_partitioner 与 min_slice_size64 << 20。
config：RunConfig 对象配置运行时设置。
注意：
ValueError：如果 linear_feature_columns 和 dnn_features_columns 都同时为空。
evaluate
evaluate(
    input_fn,
    steps=None,
    hooks=None,
    checkpoint_path=None,
    name=None
)
评估给定的评估数据 input_fn 的模型。
对于每个步骤，调用 input_fn，它返回一组数据。评估结束条件：达到 – steps 批处理，或 – input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor或带标签的张量字典（dict）。
steps：评估模型的步骤数。如果为 None，直到 input_fn 引发 end-of-input 异常时，评估结束。
hooks：SessionRunHook 子类实例的列表，用于评估调用中的回调。
checkpoint_path：要评估的特定检查点的路径。如果为 None，则使用 model_dir 中的最新检查点。
name：如果用户需要在不同数据集上运行多个评估，例如培训数据与测试数据，则设置评估的名称。不同评估的度量值保存在单独的文件夹中，并在 tensorboard 中单独显示。
返回：
包含 model_fn 按名称键入指定的评估度量的 dict ，以及一个条目 global_step，它包含执行此评估的全局步骤值。
注意：
ValueError：如果 steps <= 0。
ValueError：如果没有 train 模型，即 model_dir，或者给定的 checkpoint_path 是空的。
export_savedmodel
export_savedmodel(
    export_dir_base,
    serving_input_receiver_fn,
    assets_extra=None,
    as_text=False,
    checkpoint_path=None
)
将推理图作为 SavedModel 导出到给定的目录中。
此方法首先调用 serve_input_receiver_fn 来获取特征 Tensors，然后调用此 Estimator 的 model_fn 以生成基于这些特征的模型图，从而构建新的图。它在新的会话中将给定的检查点（或缺少最新的检查点）还原到此图中。最后，它在给定的 export_dir_base 下面创建一个时间戳的导出目录，并将 SavedModel 写入其中，其中包含从此会话保存的单个 MetaGraphDef。
导出的 MetaGraphDef 将为从 model_fn 返回的 export_outputs 字典的每个元素提供一个 SignatureDef，使用相同的键命名。这些密钥之一始终是signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY，指示当一个服务请求没有指定时将提供哪个签名。对于每个签名，输出由相应的ExportOutputs 提供，并且输入始终是由 serve_input_receiver_fn 提供的输入接收器。
额外的资产可以通过 extra_assets 参数写入 SavedModel。这应该是一个 dict，其中每个键都给出了相对于 assets.extra 目录的目标路径（包括文件名）。相应的值给出要复制的源文件的完整路径。例如，复制单个文件而不重命名的简单情况被指定为：{‘my_asset_file.txt’: ‘/path/to/my_asset_file.txt’}。
ARGS：
export_dir_base：一个包含一个目录的字符串，用于创建包含导出的 SavedModels 的时间戳子目录。
serving_input_receiver_fn：一个不带参数并返回 ServingInputReceiver 的函数。
assets_extra：指定如何在导出的 SavedModel 中填充 asset.extra 目录的 dict，如果为 None，则不需要额外的资源。
as_text：是否以文本格式写入 SavedModel 原型。
checkpoint_path：要导出的检查点路径。如果为 None（默认值），则选择在模型目录中找到的最新检查点。
返回：
导出目录的字符串路径。
注意：
ValueError：如果没有提供 serve_input_receiver_fn，则不提供 export_outputs，或者没有找到任何检查点。
predict
predict(
    input_fn,
    predict_keys=None,
    hooks=None,
    checkpoint_path=None
)
返回给定功能的预测。
ARGS：
input_fn：输入函数返回的特征，是字符串特征名称字典的 Tensor 或 SparseTensor。如果它返回一个元组，则第一个项目被提取为特征。预测继续，直到input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
predict_keys：str 列表，要预测的键的名称。如果 EstimatorSpec.predictions 是 dict，则使用它。如果使用 predict_keys，那么其余的预测将从字典中过滤掉。如果为 None，则返回所有。
hooks：SessionRunHook 子类实例列表。用于预测调用内的回调。
checkpoint_path：对具体检查点的路径进行预测。如果为 None，则使用 model_dir 中的最新检查点。
得到：
计算预测张量的值。
注意：
ValueError：在 model_dir 中找不到训练有素的模型。
ValueError：如果批量长度的预测不一致。
ValueError：如果 predict_keys 和 predictions 之间存在冲突。例如，如果 predict_keys 不是 None，但 EstimatorSpec.predictions 不是 dict。
train
train(
    input_fn,
    hooks=None,
    steps=None,
    max_steps=None
)
训练一个给定训练数据 input_fn 的模型。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor 或带标签的张量字典。
hooks：SessionRunHook 子类实例列表。用于训练循环内的回调。
steps：用于训练模型的步骤数。如果为 None，永远训练或训练直到 input_fn 生成 OutOfRange 或 StopIteration 错误。“steps”是逐步进行的。如果你调用两次 train（steps = 10），那么 train 总共有20步。如果 OutOfRange 或 StopIteration 在中间出现差错，train将在前20步之前停止。如果您不想增加行为，请设置 max_steps 代替。如果设置，max_steps 必须为 None。
max_steps：用于 train 模型的总步骤数。如果为 None，永远训练或训练，直到 input_fn 生成 OutOfRange 或 StopIteration 错误。如果设置，steps 必须为None。如果 OutOfRange 或者 StopIteration 在中间出现差错，训练之前应停止 max_steps 步骤。两次调用 train (steps=100) 意味着 200次 train 迭代。另一方面，两个调用 train(max_steps=100)意味着第二次调用将不会执行任何迭代，因为第一次调用完成了所有的100个步骤。
返回：
返回 self，用于链接。
注意：
ValueError：如果两个 steps 和 max_steps 都不是 None。
ValueError：如果任一 steps 或是 max_steps <= 0。

tf.estimator.DNNLinearCombinedRegressor DNN回归模型

DNNLinearCombinedRegressor 类
继承自： Estimator
定义在：tensorflow/python/estimator/canned/dnn_linear_combined.py。
TensorFlow Linear 和 DNN 的估计器加入了回归模型。
注意：此估计器（estimator）也称为 wide-n-deep。
例如：
numeric_feature = numeric_column(...)
sparse_column_a = categorical_column_with_hash_bucket(...)
sparse_column_b = categorical_column_with_hash_bucket(...)

sparse_feature_a_x_sparse_feature_b = crossed_column(...)
sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a,
                                        ...)
sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b,
                                        ...)

estimator = DNNLinearCombinedRegressor(
    # wide settings
    linear_feature_columns=[sparse_feature_a_x_sparse_feature_b],
    linear_optimizer=tf.train.FtrlOptimizer(...),
    # deep settings
    dnn_feature_columns=[
        sparse_feature_a_emb, sparse_feature_b_emb, numeric_feature],
    dnn_hidden_units=[1000, 500, 100],
    dnn_optimizer=tf.train.ProximalAdagradOptimizer(...))

# To apply L1 and L2 regularization, you can set optimizers as follows:
tf.train.ProximalAdagradOptimizer(
    learning_rate=0.1,
    l1_regularization_strength=0.001,
    l2_regularization_strength=0.001)
# It is same for FtrlOptimizer.

# Input builders
def input_fn_train: # returns x, y
  pass
estimator.train(input_fn=input_fn_train, steps=100)

def input_fn_eval: # returns x, y
  pass
metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10)
def input_fn_predict: # returns x, None
  pass
predictions = estimator.predict(input_fn=input_fn_predict)
输入的 train 和 evaluate 应具有以下特点，否则将会产生 KeyError：
对于 dnn_feature_columns+ linear_feature_columns 中的每一列：
如果列是 _CategoricalColumn，则具有 key=column.name 并且其值是一个 SparseTensor 的特点。
如果列是一个 _WeightedCategoricalColumn，则具有两个特点：第一个是带有键的 ID 列名称，第二个是具有键权重列名称。这两个特点的值必须是SparseTensor。
如果列是 _DenseColumn，则有特点：key = column.name 并且其值是一个 Tensor。
损失通过使用均方误差计算。
属性

config
model_dir
params
方法
__init__
__init__(
    model_dir=None,
    linear_feature_columns=None,
    linear_optimizer='Ftrl',
    dnn_feature_columns=None,
    dnn_optimizer='Adagrad',
    dnn_hidden_units=None,
    dnn_activation_fn=tf.nn.relu,
    dnn_dropout=None,
    label_dimension=1,
    weight_column=None,
    input_layer_partitioner=None,
    config=None
)
初始化 DNNLinearCombinedRegressor 实例。
ARGS：
model_dir：保存模型参数、图形等的目录。这也可用于将检查点从目录加载到估算器中，以继续训练以前保存的模型。
linear_feature_columns：包含模型线性部分使用的所有特征列的 iterable（迭代）。集合中的所有项目都必须是从 FeatureColumn 派生的类的实例。
linear_optimizer：tf.Optimizer 用于将渐变应用于模型的线性部分的实例。默认为 FTRL 优化器。
dnn_feature_columns：包含模型深层部分所使用的所有特征列的 iterable。集合中的所有项目都必须是从 FeatureColumn 派生的类的实例。
dnn_optimizer：tf.Optimizer 用于将渐变应用于模型的深层部分的实例。默认为 Adagrad 优化器。
dnn_hidden_units：每层隐藏单位的列表。所有层都完全连接。
dnn_activation_fn：激活函数应用于每个层。如果无，将使用 tf.nn.relu。
dnn_dropout：当不是 None 时，我们将放弃一个给定的坐标的概率。
label_dimension：每个例子的回归目标数。这是标签和 logits Tensor 对象的最后一个维度的大小（通常它们具有形状 [batch_size, label_dimension]）。
weight_column：通过 tf.feature_column.numeric_column 创建的一个字符串或者 _NumericColumn 用来定义表示权重的特征列。在 train 过程中，它用于降低权重或增加实例。它将乘以例子的损失。如果它是一个字符串，它是用来作为一个键从特征提取权重张量；如果是 _NumericColumn，则通过键获取原始张量weight_column.key，然后在其上应用 weight_column.normalizer_fn 以获得权重张量。
input_layer_partitioner：输入层分区。默认为 min_max_variable_partitioner 与 min_slice_size64 << 20。
config：RunConfig 对象配置运行时设置。
注意：
ValueError：如果 linear_feature_columns 和 dnn_features_columns 都同时为空。
evaluate
evaluate(
    input_fn,
    steps=None,
    hooks=None,
    checkpoint_path=None,
    name=None

)
评估给定的评估数据 input_fn 的模型。
对于每个步骤，调用 input_fn，它返回一组数据。评估结束条件：达到 – steps 批处理，或 – input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor或带标签的张量字典（dict）。
steps：评估模型的步骤数。如果为 None，直到 input_fn 引发 end-of-input 异常时，评估结束。
hooks：SessionRunHook 子类实例的列表，用于评估调用中的回调。
checkpoint_path：要评估的特定检查点的路径。如果为 None，则使用 model_dir 中的最新检查点。
name：如果用户需要在不同数据集上运行多个评估，例如培训数据与测试数据，则设置评估的名称。不同评估的度量值保存在单独的文件夹中，并在 tensorboard 中单独显示。
返回：
包含 model_fn 按名称键入指定的评估度量的 dict ，以及一个条目 global_step，它包含执行此评估的全局步骤值。
注意：
ValueError：如果 steps <= 0。
ValueError：如果没有 train 模型，即 model_dir，或者给定的 checkpoint_path 是空的。
export_savedmodel
export_savedmodel(
    export_dir_base,
    serving_input_receiver_fn,
    assets_extra=None,
    as_text=False,
    checkpoint_path=None
)
将推理图作为 SavedModel 导出到给定的目录中。
此方法首先调用 serve_input_receiver_fn 来获取特征 Tensors，然后调用此 Estimator 的 model_fn 以生成基于这些特征的模型图，从而构建新的图。它在新的会话中将给定的检查点（或缺少最新的检查点）还原到此图中。最后，它在给定的 export_dir_base 下面创建一个时间戳的导出目录，并将 SavedModel 写入其中，其中包含从此会话保存的单个 MetaGraphDef。
导出的 MetaGraphDef 将为从 model_fn 返回的 export_outputs 字典的每个元素提供一个 SignatureDef，使用相同的键命名。这些密钥之一始终是signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY，指示当一个服务请求没有指定时将提供哪个签名。对于每个签名，输出由相应的ExportOutputs 提供，并且输入始终是由 serve_input_receiver_fn 提供的输入接收器。
额外的资产可以通过 extra_assets 参数写入 SavedModel。这应该是一个 dict，其中每个键都给出了相对于 assets.extra 目录的目标路径（包括文件名）。相应的值给出要复制的源文件的完整路径。例如，复制单个文件而不重命名的简单情况被指定为：{‘my_asset_file.txt’: ‘/path/to/my_asset_file.txt’}。
ARGS：
export_dir_base：一个包含一个目录的字符串，用于创建包含导出的 SavedModels 的时间戳子目录。
serving_input_receiver_fn：一个不带参数并返回 ServingInputReceiver 的函数。
assets_extra：指定如何在导出的 SavedModel 中填充 asset.extra 目录的 dict，如果为 None，则不需要额外的资源。
as_text：是否以文本格式写入 SavedModel 原型。
checkpoint_path：要导出的检查点路径。如果为 None（默认值），则选择在模型目录中找到的最新检查点。
返回：
导出目录的字符串路径。
注意：
ValueError：如果没有提供 serve_input_receiver_fn，则不提供 export_outputs，或者没有找到任何检查点。
predict
predict(
    input_fn,
    predict_keys=None,
    hooks=None,
    checkpoint_path=None
)
返回给定功能的预测。
ARGS：
input_fn：输入函数返回的特征，是字符串特征名称字典的 Tensor 或 SparseTensor。如果它返回一个元组，则第一个项目被提取为特征。预测继续，直到input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
predict_keys：str 列表，要预测的键的名称。如果 EstimatorSpec.predictions 是 dict，则使用它。如果使用 predict_keys，那么其余的预测将从字典中过滤掉。如果为 None，则返回所有。
hooks：SessionRunHook 子类实例列表。用于预测调用内的回调。
checkpoint_path：对具体检查点的路径进行预测。如果为 None，则使用 model_dir 中的最新检查点。
得到：
计算预测张量的值。
注意：
ValueError：在 model_dir 中找不到训练有素的模型。
ValueError：如果批量长度的预测不一致。
ValueError：如果 predict_keys 和 predictions 之间存在冲突。例如，如果 predict_keys 不是 None，但 EstimatorSpec.predictions 不是 dict。
train
train(
    input_fn,
    hooks=None,
    steps=None,
    max_steps=None
)
训练一个给定训练数据 input_fn 的模型。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor 或带标签的张量字典。
hooks：SessionRunHook 子类实例列表。用于训练循环内的回调。
steps：用于训练模型的步骤数。如果为 None，永远训练或训练直到 input_fn 生成 OutOfRange 或 StopIteration 错误。“steps”是逐步进行的。如果你调用两次 train（steps = 10），那么 train 总共有20步。如果 OutOfRange 或 StopIteration 在中间出现差错，train将在前20步之前停止。如果您不想增加行为，请设置 max_steps 代替。如果设置，max_steps 必须为 None。
max_steps：用于 train 模型的总步骤数。如果为 None，永远训练或训练，直到 input_fn 生成 OutOfRange 或 StopIteration 错误。如果设置，steps 必须为None。如果 OutOfRange 或者 StopIteration 在中间出现差错，训练之前应停止 max_steps 步骤。两次调用 train (steps=100) 意味着 200次 train 迭代。另一方面，两个调用 train(max_steps=100)意味着第二次调用将不会执行任何迭代，因为第一次调用完成了所有的100个步骤。
返回：
返回 self，用于链接。
注意：
ValueError：如果两个 steps 和 max_steps 都不是 None。
ValueError：如果任一 steps 或是 max_steps <= 0。

tf.estimator.DNNRegressor DNN模型的回归器

DNNRegressor 类
继承自： Estimator
定义在：tensorflow/python/estimator/canned/dnn.py。
TensorFlow DNN 模型的回归器。
例：
sparse_feature_a = sparse_column_with_hash_bucket(...)
sparse_feature_b = sparse_column_with_hash_bucket(...)

sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a,
                                        ...)
sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b,
                                        ...)

estimator = DNNRegressor(
    feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb],
    hidden_units=[1024, 512, 256])

# Or estimator using the ProximalAdagradOptimizer optimizer with
# regularization.
estimator = DNNRegressor(
    feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb],
    hidden_units=[1024, 512, 256],
    optimizer=tf.train.ProximalAdagradOptimizer(
      learning_rate=0.1,
      l1_regularization_strength=0.001
    ))

# Input builders
def input_fn_train: # returns x, y
  pass
estimator.train(input_fn=input_fn_train, steps=100)

def input_fn_eval: # returns x, y
  pass
metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10)
def input_fn_predict: # returns x, None
  pass
predictions = estimator.predict(input_fn=input_fn_predict)
输入的 train 和 evaluate 应具有以下特点，否则将会产生 KeyError：
如果 weight_column 不是 None，则具有 key = weight_column 的特征，其值为张量。
对于 feature_columns 中的每列：
如果列是 _CategoricalColumn，则具有 key=column.name 并且其值是一个 SparseTensor 的特点。
如果列是一个 _WeightedCategoricalColumn，则具有两个特点：第一个是带有键的 ID 列名称，第二个是具有键权重列名称。这两个特点的值必须是SparseTensor。
如果列是 _DenseColumn，则有特点：key = column.name 并且其值是一个 Tensor。
损失通过使用均方误差计算。
属性
config
model_dir
params
方法
__init__
__init__(
    hidden_units,
    feature_columns,
    model_dir=None,
    label_dimension=1,
    weight_column=None,
    optimizer='Adagrad',
    activation_fn=tf.nn.relu,
    dropout=None,
    input_layer_partitioner=None,
    config=None
)
初始化一个 DNNRegressor 实例。
ARGS：
hidden_units：每层数隐藏单位的 Iterable。所有层都已完全连接。前 [64, 32] 意味第一层数有 64 个节点和第二个层数有 32 个节点。
feature_columns：包含模型所使用的所有特征列的 iterable（迭代）。集合中的所有项目都必须是从 FeatureColumn 派生的类的实例。
model_dir：保存模型参数、图形等的目录。这也可用于将检查点从目录加载到估算器中，以继续训练以前保存的模型。
label_dimension：每个示例的回归目标数。这是标签和 logits 张量对象的最后一个维度的大小 (通常, 它们具有形状 [batch_size, label_dimension])。
weight_column：通过 tf.feature_column.numeric_column 创建的一个字符串或者 _NumericColumn 用来定义表示权重的特征列。在 train 过程中，它用于降低权重或增加实例。它将乘以例子的损失。如果它是一个字符串，它是用来作为一个键从特征提取权重张量；如果是 _NumericColumn，则通过键获取原始张量weight_column.key，然后在其上应用 weight_column.normalizer_fn 以获得权重张量。
optimizer：tf.Optimizer 用于训练模型的实例。默认为 Adagrad 优化器。
activation_fn：激活函数应用于每个层。如果为 None，将使用 tf.nn.relu。
dropout：当不是 None 时，我们将放弃一个给定的坐标的概率。
input_layer_partitioner：输入层分区。默认为 min_max_variable_partitioner 与 min_slice_size64 << 20。
config：RunConfig 对象配置运行时设置。
evaluate
evaluate(
    input_fn,
    steps=None,
    hooks=None,
    checkpoint_path=None,
    name=None
)
评估给定的评估数据 input_fn 的模型。
对于每个步骤，调用 input_fn，它返回一组数据。评估结束条件：达到 – steps 批处理，或 – input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor或带标签的张量字典（dict）。
steps：评估模型的步骤数。如果为 None，直到 input_fn 引发 end-of-input 异常时，评估结束。
hooks：SessionRunHook 子类实例的列表，用于评估调用中的回调。
checkpoint_path：要评估的特定检查点的路径。如果为 None，则使用 model_dir 中的最新检查点。
name：如果用户需要在不同数据集上运行多个评估，例如培训数据与测试数据，则设置评估的名称。不同评估的度量值保存在单独的文件夹中，并在 tensorboard 中单独显示。
返回：
包含 model_fn 按名称键入指定的评估度量的 dict ，以及一个条目 global_step，它包含执行此评估的全局步骤值。
注意：
ValueError：如果 steps <= 0。
ValueError：如果没有 train 模型，即 model_dir，或者给定的 checkpoint_path 是空的。
export_savedmodel
export_savedmodel(
    export_dir_base,
    serving_input_receiver_fn,
    assets_extra=None,
    as_text=False,
    checkpoint_path=None
)
将推理图作为 SavedModel 导出到给定的目录中。
此方法首先调用 serve_input_receiver_fn 来获取特征 Tensors，然后调用此 Estimator 的 model_fn 以生成基于这些特征的模型图，从而构建新的图。它在新的会话中将给定的检查点（或缺少最新的检查点）还原到此图中。最后，它在给定的 export_dir_base 下面创建一个时间戳的导出目录，并将 SavedModel 写入其中，其中包含从此会话保存的单个 MetaGraphDef。
导出的 MetaGraphDef 将为从 model_fn 返回的 export_outputs 字典的每个元素提供一个 SignatureDef，使用相同的键命名。这些密钥之一始终是signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY，指示当一个服务请求没有指定时将提供哪个签名。对于每个签名，输出由相应的ExportOutputs 提供，并且输入始终是由 serve_input_receiver_fn 提供的输入接收器。
额外的资产可以通过 extra_assets 参数写入 SavedModel。这应该是一个 dict，其中每个键都给出了相对于 assets.extra 目录的目标路径（包括文件名）。相应的值给出要复制的源文件的完整路径。例如，复制单个文件而不重命名的简单情况被指定为：{‘my_asset_file.txt’: ‘/path/to/my_asset_file.txt’}。
ARGS：
export_dir_base：一个包含一个目录的字符串，用于创建包含导出的 SavedModels 的时间戳子目录。
serving_input_receiver_fn：一个不带参数并返回 ServingInputReceiver 的函数。
assets_extra：指定如何在导出的 SavedModel 中填充 asset.extra 目录的 dict，如果为 None，则不需要额外的资源。
as_text：是否以文本格式写入 SavedModel 原型。
checkpoint_path：要导出的检查点路径。如果为 None（默认值），则选择在模型目录中找到的最新检查点。
返回：
导出目录的字符串路径。
注意：
ValueError：如果没有提供 serve_input_receiver_fn，则不提供 export_outputs，或者没有找到任何检查点。
predict
predict(
    input_fn,
    predict_keys=None,
    hooks=None,
    checkpoint_path=None
)
返回给定功能的预测。
ARGS：
input_fn：输入函数返回的特征，是字符串特征名称字典的 Tensor 或 SparseTensor。如果它返回一个元组，则第一个项目被提取为特征。预测继续，直到input_fn 引发 end-of-input 异常（OutOfRangeError 或 StopIteration）。
predict_keys：str 列表，要预测的键的名称。如果 EstimatorSpec.predictions 是 dict，则使用它。如果使用 predict_keys，那么其余的预测将从字典中过滤掉。如果为 None，则返回所有。
hooks：SessionRunHook 子类实例列表。用于预测调用内的回调。
checkpoint_path：对具体检查点的路径进行预测。如果为 None，则使用 model_dir 中的最新检查点。
得到：
计算预测张量的值。
注意：
ValueError：在 model_dir 中找不到训练有素的模型。
ValueError：如果批量长度的预测不一致。
ValueError：如果 predict_keys 和 predictions 之间存在冲突。例如，如果 predict_keys 不是 None，但 EstimatorSpec.predictions 不是 dict。
train
train(
    input_fn,
    hooks=None,
    steps=None,
    max_steps=None
)
训练一个给定训练数据 input_fn 的模型。
ARGS：
input_fn：输入函数返回一个元组：features – Dictionary 的字符串特征名到 Tensor 或 SparseTensor。labels – Tensor 或带标签的张量字典。
hooks：SessionRunHook 子类实例列表。用于训练循环内的回调。
steps：用于训练模型的步骤数。如果为 None，永远训练或训练直到 input_fn 生成 OutOfRange 或 StopIteration 错误。“steps”是逐步进行的。如果你调用两次 train（steps = 10），那么 train 总共有20步。如果 OutOfRange 或 StopIteration 在中间出现差错，train将在前20步之前停止。如果您不想增加行为，请设置 max_steps 代替。如果设置，max_steps 必须为 None。
max_steps：用于 train 模型的总步骤数。如果为 None，永远训练或训练，直到 input_fn 生成 OutOfRange 或 StopIteration 错误。如果设置，steps 必须为None。如果 OutOfRange 或者 StopIteration 在中间出现差错，训练之前应停止 max_steps 步骤。两次调用 train (steps=100) 意味着 200次 train 迭代。另一方面，两个调用 train(max_steps=100)意味着第二次调用将不会执行任何迭代，因为第一次调用完成了所有的100个步骤。
返回：
返回 self，用于链接。
注意：
ValueError：如果两个 steps 和 max_steps 都不是 None。
ValueError：如果任一 steps 或是 max_steps <= 0。

参考：

https://www.w3cschool.cn/tensorflow_python/tensorflow_python-61mk2e0b.html

    原文作者：tensorflow
    原文地址: https://www.cnblogs.com/yifdu25/p/8284196.html
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。

tf.estimator模块

主要模块

类

函数

tf.estimator.classifier_parse_example_spec 生成解析规范

ARGS：

返回：

注意：

tf.estimator.DNNClassifier 使用DNN模型分类器

DNNClassifier 类

属性

方法

__init__

ARGS：

evaluate

ARGS：

返回：

注意：

export_savedmodel

ARGS：

返回：

注意：

predict

ARGS：

获取：

注意：

train

ARGS：

返回：

注意：

tf.estimator.DNNLinearCombinedClassifier

属性

方法

__init__

ARGS：

注意：

evaluate

ARGS：

返回：

注意：

export_savedmodel

ARGS：

返回：

注意：

predict

ARGS：

得到：

注意：

train

ARGS：

返回：

注意：

tf.estimator.DNNLinearCombinedRegressor DNN回归模型

DNNLinearCombinedRegressor 类

属性

方法

__init__

ARGS：

注意：

evaluate

ARGS：

返回：

注意：

export_savedmodel

ARGS：

注意：

predict

ARGS：

得到：

注意：

train

ARGS：

返回：

注意：

tf.estimator.DNNRegressor DNN模型的回归器

DNNRegressor 类

属性

方法

__init__

ARGS：

`tf.estimator.DNNClassifier` 使用DNN模型分类器

init

init

init

init