TensorFlow 官方API 中文版(一)

7/18/2016 7:49:42 PM

　　在学习Tensorflow的API时，发现尙没有官方API的中文版。于是想在这里对照官方的API翻译成中文，一来督促自己学习，二来也想方便一些学习者解决一些语言上的障碍。所有内容均翻译自官方网站，若大家有疑问时可以参照原文链接如下：(貌似最近被墙了)
https://www.tensorflow.org/versions/r0.9/api_docs/index.html
注意：
　　1.对于出现的重要概念或较难理解的句子都在后面括号做了英文原文表示
　　2.对于一些基础概念如Operation,Tensor等用原文表示，便于理解。建议在学习完官方的入门教程后再来学习API 　　
　　3.在保证语义完整清晰前提下，翻译尽力保证忠实于原文，仅在表达方式上略作调整
　　4.欢迎转载，请注明出处

API文档

　　TensorFlow 拥有多种语言的API用于构建和执行TensorFlow图，Python API 是目前最完整和最容易使用的，但是C++ API可能在执行图方面提供一些性能优势，同时支持在小型设备上的部署（例如Android）。随着时间的推移，我们希望TensorFlow社区能够开发出像Go,Java,JavaScript,Lua,R（或其他）这样的前端语言。借助于SWIG，用你最喜欢的语言开发TensorFlow界面将变得非常容易。

Part I Building Graphs 图的构建

1.1 核心图的数据结构

1.1.1 class tf.Graph

这是一个TensorFlow计算（computation)，代表一个数据流图（dataflow graph).
一张图包含一系列的Opration对象，这些对象代表着计算单元，而Tensor对象代表着数据单元，这些数据单元在各个Opertation间流动。
一张 默认图（default Graph)已经注册，可以通过调用 tf.get_default_graph()来获取它。为了向默认图添加一个操作，可以简单地调用定义了一个新的 Opertation 的函数：

    c = tf.constant(4.0)      assert c.graph is tf.get_default_graph()

另外一个典型的用法包括 Graph.as_default() 这个上下文管理器(context manager)在上下文环境中覆盖了当前的默认图。

 g = tf.Graph()    with g.as_default():    # Define operations and tensors in `g`.      c = tf.constant(30.0)      assert c.graph is g

重要提示：这个类构建图是非线程安全的。所有的操作应该从单个线程中创建，否则必须提供外部同步。除非明确指明，所有方法都是非线程安全的。

tf.graph.__init__()

创建一个新的空的图。

tf.Graph.as_default()

返回一个使得当前图成为默认图的上下文管理器
这个方法应该在你想要在相同的过程中创建多图时被使用。为了方便，一个全局默认图已经被提供，如果你没有明确创建一个新的图，所有的操作将会被添加进这张图。当你使用这个方法时，请使用 with 关键字明确在接下来的代码块范围内创建的操作应该加进这张图。
默认图是当前线程的一个属性，如果你创建了一个新的线程，并且希望在这个线程里使用默认图，你必须在这个线程的函数里明确添加 with g.as_default():
下面的代码示例（相对于上述解释）是等价的：

    # 1. Using Graph.as_default():    g = tf.Graph()    with g.as_default():      c = tf.constant(5.0)      assert c.graph is g    # 2. Constructing and making default:    with tf.Graph().as_default() as g:      c = tf.constant(5.0)      assert c.graph is g

返回：
一个用于将当前图作为默认图的上下文管理器

tf.Graph.as_graph_def(from_version=None, add_shapes=False)

返回一个表示这个图的序列化的 GraphDef。

这个序列化的 GraphDef 可以被引入另一个图（使用 import_graph_def()）或者使用 C++ Session API。
这个方法是线程安全的。

参数：
from_version： 可选的，如果被设定，将返回一个 GraphDef，它包含仅从这张图的版本属性有了给定值后加入这张图的节点（nodes）。
add_shapes： 如果是真值，给每个带有输出推断图形的结点添加一个_output_shapes列表属性。（adds an “_output_shapes” list attr to each node with the inferred shapes of each of its outputs.)
返回：
一个 GraphDef协议缓冲区（protocol buffer）
引起的错误：
ValueError: 如果 graph_def 太大

tf.Graph.finalize()

结束这个图，使它只读
在调用g.finalize()后，不能向g添加任何新的操作。当这个图在多线程间共享时，为了保证没有操作添加到这个图，可以调用这个方法，例如当使用一个 QueueRunner时

tf.Graph.finalized

如果这个图已经结束，它为真

tf.Graph.control_dependencies(control_inputs)

返回一个明确控制依赖（control dependencies）的上下文管理器

使用 with 关键字明确所有在上下文内创建的操作应该在control_inputs上有控制依赖。例如：

    with g.control_dependencies([a, b, c]):  # `d` and `e` will only run after `a`, `b`, and `c` have executed.  d = ...  e = ...

control_dependencies()的多重调用可以嵌套，在这种情况下，基于所有活动的上下文中的 control_inputs 的联合，一个新的 Operation 将拥有控制依赖。

with g.control_dependencies([a, b]):  # Ops constructed here run after `a` and `b`.  with g.control_dependencies([c, d]):# Ops constructed here run after `a`, `b`, `c`, and `d`.

你可以通过None来清除控制依赖。

with g.control_dependencies([a, b]):  # Ops constructed here run after `a` and `b`.  with g.control_dependencies(None):# Ops constructed here run normally, not waiting for either `a` or `b`.with g.control_dependencies([c, d]):  # Ops constructed here run after `c` and `d`, also not waiting  # for either `a` or `b`.

注：控制依赖应用于那些在上下文内建立的操作。很少在上下文中使用使用一个 op 或者 tensor 时不添加一个控制依赖。下面的例子解释了这一点:

# WRONGdef my_func(pred, tensor):  t = tf.matmul(tensor, tensor)  with tf.control_dependencies([pred]):# The matmul op is created outside the context, so no control# dependency will be added.return t# RIGHTdef my_func(pred, tensor):  with tf.control_dependencies([pred]):# The matmul op is created in the context, so a control dependency# will be added.return tf.matmul(tensor, tensor)

参数:
control_inputs：一个 Operation 或者 Tensor 对象列表，它上下文内定义的操作被运行前被执行或者计算。也可以为None来清除控制依赖。
返回：
一个明确在上下文内所有操作的控制依赖的上下文管理器
引起的错误：
TypeError: 如果 control_inputs 不是一个 Operation 或者Tensor 对象的列表.