TensorFlow风格指南

此页面包含TensorFlow的开发人员和用户应遵循的风格决策，以增加其代码的可读性，减少错误数量并提高一致性。

Python风格

一般遵循 PEP8 Python风格指南，除了使用2个空格。

Python 2和3兼容

• 所有代码都需要与Python 2和3兼容。

• 所有Python文件中都应存在下一行：

  from  __future__  import  absolute_import from  __future__  import  division from  __future__  import  print_functio

• 使用six写兼容代码（例如six.moves.range）。

 

Bazel BUILD规则

TensorFlow使用Bazel构建系统并执行下一个要求：

• 每个BUILD文件应包含下一个标题：

  # Description: # <...>   package(      default_visibility  =  [ "//visibility:private" ],      features  =  [ "-parse_headers" ], )   licenses([ "notice" ])   # Apache 2.0   exports_files([ "LICENSE" ])

• 在每个BUILD文件的末尾，应包含：

  filegroup(      name  =  "all_files" ,      srcs  =  glob(          [ "**/*" ],          exclude  =  [              "**/METADATA" ,              "**/OWNERS" ,          ],      ),      visibility  =  [ "//third_party/tensorflow:__subpackages__" ], )

• 添加新的BUILD文件时，将此行添加tensorflow/BUILD到all_opensource_files目标文件中。

  "//third_party/tensorflow/<directory>:all_files" ,

• 对于所有Python BUILD目标（库和测试）添加下一行：

  srcs_version  =  "PY2AND3" ,

 

张量

• 处理批次的操作可以假设Tensor的第一个维度是批量维度。

 

Python操作

甲的Python操作是一个函数，给定输入张量和参数，创建图的一部分，并返回输出张量。

• 第一个参数应该是张量，其次是基本的python参数。最后一个参数name的默认值为None。如果操作需要将一些Tensors 保存到Graph集合，则将参数与集合名称一起放在name参数之前。

• 张量参数应该是单张量或迭代张量。例如“张量或张量表”太广泛了。见assert_proper_iterable。

•  convert_to_tensor 如果使用C ++操作，将张量作为参数的操作应调用将非张量输入转换为张量。请注意，参数仍被描述为文档中Tensor特定dtype的对象。

• 每个Python操作应该有op_scope如下所示。传递输入张量列表，name并将op的默认名称作为参数。

• 操作应该包含一个广泛的Python注释与Args和Returns声明，解释每个值的类型和含义。应在说明中指定可能的形状，型式或等级。 请参阅文档详细信息

• 为了提高可用性，包括使用示例部分中op操作的输入/输出示例。

例：

def  my_op(tensor_in, other_tensor_in, my_param, other_param = 0.5 ,            output_collections = (), name = None ): """My operation that adds two tensors with given coefficients.   Args:    tensor_in: `Tensor`, input tensor.    other_tensor_in: `Tensor`, same shape as `tensor_in`, other input tensor.    my_param: `float`, coefficient for `tensor_in`.    other_param: `float`, coefficient for `other_tensor_in`.    output_collections: `tuple` of `string`s, name of the collection to                        collect result of this op.    name: `string`, name of the operation.   Returns:    `Tensor` of same shape as `tensor_in`, sum of input values with coefficients.   Example:    >>> my_op([1., 2.], [3., 4.], my_param=0.5, other_param=0.6,              output_collections=['MY_OPS'], name='add_t1t2')    [2.3, 3.4] """ with tf.name_scope(name,  "my_op" , [tensor_in, other_tensor_in]):    tensor_in  =  tf.convert_to_tensor(tensor_in)    other_tensor_in  =  tf.convert_to_tensor(other_tensor_in)    result  =  my_param  *  tensor_in  +  other_param  *  other_tensor_in    tf.add_to_collections(output_collections, result)    return  result

用法：

output  =  my_op(t1, t2, my_param = 0.5 , other_param = 0.6 ,                 output_collections = [ 'MY_OPS' ], name = 'add_t1t2' )

图层

阿层是结合可变创建和/或一个或多个其他图形操作一个Python操作。遵循与常规Python操作相同的要求。

• 如果一个层创建一个或多个变量，层函数也应该遵循下列参数：
• initializers：可选地允许指定变量的初始值。
• regularizers：可选地允许为变量指定正则化程序。
• trainable：哪个控制他们的变量是否可训练。
• scope：VariableScope该变量将被放在下面的对象。

• reuse：bool指示变量如果存在于范围内，应重新使用。

• 训练过程中行为不同的层应具有：

• is_training：bool指示是否建立训练图。

例：

def  conv2d(inputs,             num_filters_out,             kernel_size,             stride = 1 ,             padding = 'SAME' ,             activation_fn = tf.nn.relu,             normalization_fn = add_bias,             normalization_params = None ,             initializers = None ,             regularizers = None ,             trainable = True ,             scope = None ,             reuse = None ):    ... see implementation at tensorflow / contrib / layers / python / layers / layers.py ...