From e63ce91e0072cd1d933ff4db55dc68f36f51bac3 Mon Sep 17 00:00:00 2001 From: sun1638650145 <1638650145@qq.com> Date: Tue, 2 Feb 2021 14:16:38 +0800 Subject: [PATCH 1/8] Fix typo&update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7336430ca24..1e5368dba99 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ An archive containing Python packages and an installation script can be download - To quickly try this out, copy and paste the following into Terminal: - ``` + ```shell /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" ``` @@ -52,14 +52,14 @@ Please submit feature requests or report issues via [GitHub Issues](https://gith It is not necessary to make any changes to your existing TensorFlow scripts to use ML Compute as a backend for TensorFlow and TensorFlow Addons. -There is an optional `mlcompute.set_mlc_device(device_name=’any')` API for ML Compute device selection. The default value for `device_name` is `'any’`, which means ML Compute will select the best available device on your system, including multiple GPUs on multi-GPU configurations. Other available options are `‘cpu’` and `‘gpu’`. Please note that in eager mode, ML Compute will use the CPU. For example, to choose the CPU device, you may do the following: +There is an optional `mlcompute.set_mlc_device(device_name='any')` API for ML Compute device selection. The default value for `device_name` is `'any'`, which means ML Compute will select the best available device on your system, including multiple GPUs on multi-GPU configurations. Other available options are `'cpu'` and `'gpu'`. Please note that in eager mode, ML Compute will use the CPU. For example, to choose the CPU device, you may do the following: - ``` + ```python # Import mlcompute module to use the optional set_mlc_device API for device selection with ML Compute. from tensorflow.python.compiler.mlcompute import mlcompute # Select CPU device. - mlcompute.set_mlc_device(device_name=‘cpu’) # Available options are 'cpu', 'gpu', and ‘any'. + mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and 'any'. ``` From ba078a5437c55832054e12e8280d89777d2f4447 Mon Sep 17 00:00:00 2001 From: sun1638650145 <1638650145@qq.com> Date: Fri, 5 Feb 2021 11:37:23 +0800 Subject: [PATCH 2/8] Add README_zh.md --- README_zh.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 README_zh.md diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 00000000000..a688abfd73c --- /dev/null +++ b/README_zh.md @@ -0,0 +1,99 @@ +## Mac-optimized TensorFlow and TensorFlow Addons + + +### INTRODUCTION + +This pre-release delivers hardware-accelerated TensorFlow and TensorFlow Addons for macOS 11.0+. Native hardware acceleration is supported on Macs with M1 and Intel-based Macs through Apple’s [ML Compute](https://developer.apple.com/documentation/mlcompute) framework. + +### CURRENT RELEASE + +- 0.1-alpha2 + +### SUPPORTED VERSIONS + +- TensorFlow r2.4rc0 +- TensorFlow Addons 0.11.2 + +### REQUIREMENTS + +- macOS 11.0+ +- Python 3.8, available from the [Xcode Command Line Tools](https://developer.apple.com/download/more/?=command%20line%20tools). + +### INSTALLATION + +An archive containing Python packages and an installation script can be downloaded from the [releases](https://github.com/apple/tensorflow_macos/releases). + +#### Details + +- To quickly try this out, copy and paste the following into Terminal: + + ```shell + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" + ``` + + This will verify your system, ask you for confirmation, then create a virtual environment (https://docs.python.org/3.8/tutorial/venv.html) with TensorFlow for macOS installed. + +- Alternatively, download the archive file from the [releases](https://github.com/apple/tensorflow_macos/releases). The archive contains an installation script, accelerated versions of TensorFlow, TensorFlow Addons, and needed dependencies. + +#### Notes + +For Macs with M1, the following packages are currently unavailable: + +- SciPy and dependent packages +- Server/Client TensorBoard packages + +### ISSUES AND FEEDBACK + +Please submit feature requests or report issues via [GitHub Issues](https://github.com/apple/tensorflow_macos/issues). + +### ADDITIONAL INFORMATION + +#### Device Selection (Optional) + +It is not necessary to make any changes to your existing TensorFlow scripts to use ML Compute as a backend for TensorFlow and TensorFlow Addons. + +There is an optional `mlcompute.set_mlc_device(device_name='any')` API for ML Compute device selection. The default value for `device_name` is `'any'`, which means ML Compute will select the best available device on your system, including multiple GPUs on multi-GPU configurations. Other available options are `'cpu'` and `'gpu'`. Please note that in eager mode, ML Compute will use the CPU. For example, to choose the CPU device, you may do the following: + + ```python +# Import mlcompute module to use the optional set_mlc_device API for device selection with ML Compute. +from tensorflow.python.compiler.mlcompute import mlcompute + +# Select CPU device. +mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and 'any'. + ``` + + +#### Logs and Debugging + +##### Graph mode + +Logging provides more information about what happens when a TensorFlow model is optimized by ML Compute. Turn logging on by setting the environment variable `TF_MLC_LOGGING=1` when executing the model script. The following is the list of information that is logged in graph mode: + +- Device used by ML Compute. +- Original TensorFlow graph without ML Compute. +- TensorFlow graph after TensorFlow operations have been replaced with ML Compute. + - Look for MLCSubgraphOp nodes in this graph. Each of these nodes replaces a TensorFlow subgraph from the original graph, encapsulating all the operations in the subgraph. This, for example, can be used to determine which operations are being optimized by ML Compute. +- Number of subgraphs using ML Compute and how many operations are included in each of these subgraphs. + - Having larger subgraphs that encapsulate big portions of the original graph usually results in better performance from ML Compute. Note that for training, there will usually be at least two MLCSubgraphOp nodes (representing forward and backward/gradient subgraphs). +- TensorFlow subgraphs that correspond to each of the ML Compute graphs. + +##### Eager mode + +不同于静态图模式，eager模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制。如下是eager模式记录的日志信息列表： + +- 缓冲区指针和输入/输出张量的形状. +- 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值。该键值被用来复现计算图，运行反向传播或者是更新优化器的参数. +- 格式化的权重张量. +- 保存统计日志，例如插入和删除的信息. + +##### Debug提示 + +- 在GPU上训练较大的模型可能会超出可分配的内存，导致内存分页. 如果发生了这样的情况，您可以尝试减小batch大小或者是模型的层数. +- TensorFlow is multi-threaded, which means that different TensorFlow operations, such as` MLCSubgraphOp`, can execute concurrently. As a result, there may be overlapping logging information. To avoid this during the debugging process, set TensorFlow to execute operators sequentially by setting the number of threads to 1 (see [`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)). + +##### Additional tips for debugging in eager mode: + +- To find information about a specific tensor in the log, search for its buffer pointer in the log. If the tensor is defined by an operation that ML Compute does not support, you will need to cast it to `size_t` and search for it in log entries with the pattern `MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`. You may also need to modify the `OpKernelContext::input()` to print out the input pointer so that you can see the entire use-def chain in the log. +- You may disable the conversion of any eager operation to ML Compute by using `TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`. The gradient op may also need to be disabled by modifying the file `$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py` (this avoids TensorFlow recompilation). +- To initialize allocated memory with a specific value, use `TF_MLC_ALLOCATOR_INIT_VALUE=`. + From 12e222156850901796a7ce1ece66e8ba9604252e Mon Sep 17 00:00:00 2001 From: sun1638650145 <1638650145@qq.com> Date: Sat, 6 Feb 2021 16:59:15 +0800 Subject: [PATCH 3/8] Update README_zh.md --- README_zh.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README_zh.md b/README_zh.md index a688abfd73c..c27981834da 100644 --- a/README_zh.md +++ b/README_zh.md @@ -77,23 +77,23 @@ Logging provides more information about what happens when a TensorFlow model is - Having larger subgraphs that encapsulate big portions of the original graph usually results in better performance from ML Compute. Note that for training, there will usually be at least two MLCSubgraphOp nodes (representing forward and backward/gradient subgraphs). - TensorFlow subgraphs that correspond to each of the ML Compute graphs. -##### Eager mode +##### Eager模式 -不同于静态图模式，eager模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制。如下是eager模式记录的日志信息列表： +不同于静态图模式, eager模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制. 如下是eager模式记录的日志信息列表: - 缓冲区指针和输入/输出张量的形状. -- 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值。该键值被用来复现计算图，运行反向传播或者是更新优化器的参数. +- 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值. 该键值用于复现计算图, 以及运行反向传播或者是更新优化器的参数. - 格式化的权重张量. -- 保存统计日志，例如插入和删除的信息. +- 保存统计日志, 例如插入和删除的信息. -##### Debug提示 +##### 调试建议 -- 在GPU上训练较大的模型可能会超出可分配的内存，导致内存分页. 如果发生了这样的情况，您可以尝试减小batch大小或者是模型的层数. -- TensorFlow is multi-threaded, which means that different TensorFlow operations, such as` MLCSubgraphOp`, can execute concurrently. As a result, there may be overlapping logging information. To avoid this during the debugging process, set TensorFlow to execute operators sequentially by setting the number of threads to 1 (see [`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)). +- 在GPU上训练较大的模型可能会超出可分配的内存, 导致内存分页. 如果发生了这样的情况, 您可以尝试减小批次大小或者是模型的层数. +- TensorFlow支持多线程, 这意味着不同的TensorFlow操作可以并行执行, 比如` MLCSubgraphOp`. 但这可能会导致输出重复的日志信息, 如果您不希望在调试中出现这种情况, 您可以设置线程数为1让TensorFlow顺序执行操作(请参阅[`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)). -##### Additional tips for debugging in eager mode: +##### 在eager模式下调试的其他建议: -- To find information about a specific tensor in the log, search for its buffer pointer in the log. If the tensor is defined by an operation that ML Compute does not support, you will need to cast it to `size_t` and search for it in log entries with the pattern `MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`. You may also need to modify the `OpKernelContext::input()` to print out the input pointer so that you can see the entire use-def chain in the log. -- You may disable the conversion of any eager operation to ML Compute by using `TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`. The gradient op may also need to be disabled by modifying the file `$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py` (this avoids TensorFlow recompilation). -- To initialize allocated memory with a specific value, use `TF_MLC_ALLOCATOR_INIT_VALUE=`. +- 在日志中寻找指定张量的信息, 请您在日志中搜索张量缓冲区的指针. 如果定义了ML Compute不支持的操作, 您需要强制转换为`size_t` 类型然后在日志中搜索有`MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`的指针. 如果您想在日志中看到整个LLVM的use-def链, 您有可能需要修改函数`OpKernelContext::input()`. +- 您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止任何eager模式下的操作转换成ML Compute.您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来来禁止计算梯度的操作(这样可以避免TensorFlow重新编译). +- 为特定变量分配初始化的内存, 请使用 `TF_MLC_ALLOCATOR_INIT_VALUE=`. From 88bb6a17d2930e8302cd66d283d115a57c92c6d0 Mon Sep 17 00:00:00 2001 From: sun1638650145 <1638650145@qq.com> Date: Sun, 7 Feb 2021 19:45:17 +0800 Subject: [PATCH 4/8] Update README_zh.md --- README_zh.md | 102 ++++++++++++++++++++++++++------------------------- 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/README_zh.md b/README_zh.md index c27981834da..37e40b849c4 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,99 +1,101 @@ -## Mac-optimized TensorFlow and TensorFlow Addons +## 针对 Mac 优化的 TensorFlow 和 TensorFlow Addons +### 简介 -### INTRODUCTION +这个预览版为 macOS 11.0+ 提供了硬件加速的 TensorFlow 和 TensorFlow Addons。通过 Apple 的 [ML Compute](https://developer.apple.com/documentation/mlcompute) 框架，搭载 Apple M1和 Intel 芯片的 Mac 都支持了原生硬件加速。 -This pre-release delivers hardware-accelerated TensorFlow and TensorFlow Addons for macOS 11.0+. Native hardware acceleration is supported on Macs with M1 and Intel-based Macs through Apple’s [ML Compute](https://developer.apple.com/documentation/mlcompute) framework. - -### CURRENT RELEASE +### 当前版本 - 0.1-alpha2 -### SUPPORTED VERSIONS +### 支持版本 - TensorFlow r2.4rc0 - TensorFlow Addons 0.11.2 -### REQUIREMENTS +### 依赖 - macOS 11.0+ -- Python 3.8, available from the [Xcode Command Line Tools](https://developer.apple.com/download/more/?=command%20line%20tools). +- Python 3.8，可从[Xcode命令行工具](https://developer.apple.com/download/more/?=command%20line%20tools)下载。 -### INSTALLATION +### 安装 -An archive containing Python packages and an installation script can be downloaded from the [releases](https://github.com/apple/tensorflow_macos/releases). +包含 Python 安装包和安装脚本的压缩文件可以从[releases](https://github.com/apple/tensorflow_macos/releases)下载。 -#### Details +#### 详细信息 -- To quickly try this out, copy and paste the following into Terminal: +- 您想快速体验这个版本的 TensorFlow，复制并粘贴以下内容到终端： ```shell /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" ``` - This will verify your system, ask you for confirmation, then create a virtual environment (https://docs.python.org/3.8/tutorial/venv.html) with TensorFlow for macOS installed. + 这将验证您的系统并要求您进行确认，然后创建一个安装了 TensorFlow macOS 的虚拟环境(https://docs.python.org/3.8/tutorial/venv.html)。 + +- 或者，从[release](https://github.com/apple/tensorflow_macos/releases)下载压缩文件。压缩文件中包含一个安装脚本，其中包括加速版本的 TensorFlow ， TensorFlow Addons ，以及其他所需的依赖项。 -- Alternatively, download the archive file from the [releases](https://github.com/apple/tensorflow_macos/releases). The archive contains an installation script, accelerated versions of TensorFlow, TensorFlow Addons, and needed dependencies. +#### 在Conda上安装 -#### Notes +TensorFlow 预览版支持使用 Xcode 命令行工具中的 Python 安装和测试.。更多在 Conda 环境中安装的信息，请您参阅[#153](https://github.com/apple/tensorflow_macos/issues/153)。 -For Macs with M1, the following packages are currently unavailable: +#### 注意 -- SciPy and dependent packages -- Server/Client TensorBoard packages +对于搭载 Apple M1 芯片的 Mac ，以下依赖包目前不可用： -### ISSUES AND FEEDBACK +- SciPy 和依赖包 +- 服务器/客户端的 TensorBoard -Please submit feature requests or report issues via [GitHub Issues](https://github.com/apple/tensorflow_macos/issues). +### 问题和反馈 -### ADDITIONAL INFORMATION +请通过[GitHub Issues](https://github.com/apple/tensorflow_macos/issues)提交新功能请求和报告问题。 -#### Device Selection (Optional) +### 更多信息 -It is not necessary to make any changes to your existing TensorFlow scripts to use ML Compute as a backend for TensorFlow and TensorFlow Addons. +#### 指定硬件设备(可选) -There is an optional `mlcompute.set_mlc_device(device_name='any')` API for ML Compute device selection. The default value for `device_name` is `'any'`, which means ML Compute will select the best available device on your system, including multiple GPUs on multi-GPU configurations. Other available options are `'cpu'` and `'gpu'`. Please note that in eager mode, ML Compute will use the CPU. For example, to choose the CPU device, you may do the following: +首先，使用 ML Compute 作为 TensorFlow 和 TensorFlow Addons 的后端，是不需要对现有的 TensorFlow 脚本做任何更改。 + +有一个可选的 ML Compute 硬件设备选择API `mlcompute.set_mlc_device(device_name='any')`。其中，`device_name`的默认值是`'any'`，这意味着 ML Compute 将在您的系统上选择最佳可用硬件设备，包括在多 GPU 上配置多 GPU 训练。其他可用参数有`'cpu'` 和`'gpu'` 。需要您注意，在 eager 模式下， ML Compute 将使用CPU。 如果您想选择 CPU ，你可以这样做： ```python -# Import mlcompute module to use the optional set_mlc_device API for device selection with ML Compute. +# 导入mlcompute模块, 使用可选的set_mlc_device API来使用ML Compute进行硬件设备选择. from tensorflow.python.compiler.mlcompute import mlcompute -# Select CPU device. -mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and 'any'. +# 选择CPU. +mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'any'. ``` +#### 日志和调试 -#### Logs and Debugging - -##### Graph mode +##### 静态图模式 -Logging provides more information about what happens when a TensorFlow model is optimized by ML Compute. Turn logging on by setting the environment variable `TF_MLC_LOGGING=1` when executing the model script. The following is the list of information that is logged in graph mode: +日志记录了许多关于 ML Compute 优化 TensorFlow 模型时产生的信息。在执行模型脚本时，通过设置环境变量`TF_MLC_LOGGING=1` 来显示日志。如下是静态图模式记录的日志信息列表： -- Device used by ML Compute. -- Original TensorFlow graph without ML Compute. -- TensorFlow graph after TensorFlow operations have been replaced with ML Compute. - - Look for MLCSubgraphOp nodes in this graph. Each of these nodes replaces a TensorFlow subgraph from the original graph, encapsulating all the operations in the subgraph. This, for example, can be used to determine which operations are being optimized by ML Compute. -- Number of subgraphs using ML Compute and how many operations are included in each of these subgraphs. - - Having larger subgraphs that encapsulate big portions of the original graph usually results in better performance from ML Compute. Note that for training, there will usually be at least two MLCSubgraphOp nodes (representing forward and backward/gradient subgraphs). -- TensorFlow subgraphs that correspond to each of the ML Compute graphs. +- ML Compute 使用的硬件设备。 +- 不使用 ML Compute 的原始 TensorFlow 计算图。 +- 将 TensorFlow 操作替换为 ML Compute 后的 TensorFlow 计算图。 + - 在计算图中查找 MLCSubgraphOp 节点。这些节点中的每一个结点都替换了原计算图中的一个 TensorFlow 子图，并封装了子图中的所有操作。这些可以用来确定 ML Compute 正在优化哪些操作。 +- 使用 ML Compute 的子图的数量以及每个子图中包含的操作的数量。 + - 如果使用 ML Compute，用更大的子图来封装大部分的原始计算图，性能将会提高。注意，对于训练过程，通常至少有两个 MLCSubgraphOp 节点（表示前向传播以及反向传播/计算梯度子图）。 +- ML Compute 计算图相对应的 TensorFlow 子图。 -##### Eager模式 +##### Eager 模式 -不同于静态图模式, eager模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制. 如下是eager模式记录的日志信息列表: +不同于静态图模式，Eager 模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制。如下是 Eager 模式记录的日志信息列表： -- 缓冲区指针和输入/输出张量的形状. -- 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值. 该键值用于复现计算图, 以及运行反向传播或者是更新优化器的参数. -- 格式化的权重张量. -- 保存统计日志, 例如插入和删除的信息. +- 缓冲区指针和输入/输出张量的形状。 +- 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值。该键值用于复现计算图，以及运行反向传播或者是更新优化器的参数。 +- 格式化的权重张量。 +- 保存统计日志，例如插入和删除的信息。 ##### 调试建议 -- 在GPU上训练较大的模型可能会超出可分配的内存, 导致内存分页. 如果发生了这样的情况, 您可以尝试减小批次大小或者是模型的层数. -- TensorFlow支持多线程, 这意味着不同的TensorFlow操作可以并行执行, 比如` MLCSubgraphOp`. 但这可能会导致输出重复的日志信息, 如果您不希望在调试中出现这种情况, 您可以设置线程数为1让TensorFlow顺序执行操作(请参阅[`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)). +- 在 GPU 上训练较大的模型可能会超出可分配的显存，导致内存分页。如果发生了这样的情况，您可以尝试减小批次大小或者是模型的层数。 +- TensorFlow 支持多线程，这意味着不同的 TensorFlow 操作可以并行执行，比如` MLCSubgraphOp`。但这可能会导致输出重复的日志信息，如果您不希望在调试中出现这种情况，您可以设置线程数为1让 TensorFlow 顺序执行操作（详细信息，请参阅[`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)）。 -##### 在eager模式下调试的其他建议: +##### 在 Eager 模式下调试的其他建议： -- 在日志中寻找指定张量的信息, 请您在日志中搜索张量缓冲区的指针. 如果定义了ML Compute不支持的操作, 您需要强制转换为`size_t` 类型然后在日志中搜索有`MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`的指针. 如果您想在日志中看到整个LLVM的use-def链, 您有可能需要修改函数`OpKernelContext::input()`. -- 您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止任何eager模式下的操作转换成ML Compute.您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来来禁止计算梯度的操作(这样可以避免TensorFlow重新编译). -- 为特定变量分配初始化的内存, 请使用 `TF_MLC_ALLOCATOR_INIT_VALUE=`. +- 在日志中寻找指定张量的信息，请您在日志中搜索张量缓冲区的指针。如果定义了 ML Compute 不支持的操作，您需要强制转换为`size_t`类型，然后在日志中搜索有`MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`的指针。如果您想在日志中看到整个 LLVM 的 use-def 链，您有可能需要修改函数`OpKernelContext::input()`。 +- 您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止 Eager 模式下的任何操作转换成 ML Compute。您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来禁止计算梯度的操作（这样可以避免 TensorFlow 重新编译）。 +- 为特定变量分配初始化的内存，请使用 `TF_MLC_ALLOCATOR_INIT_VALUE=`。 From 6e413981592a56229e97a6977d96a31a9d858055 Mon Sep 17 00:00:00 2001 From: sun1638650145 <1638650145@qq.com> Date: Sun, 7 Feb 2021 20:48:33 +0800 Subject: [PATCH 5/8] Update README_zh.md --- README_zh.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/README_zh.md b/README_zh.md index 37e40b849c4..4ace93ba188 100644 --- a/README_zh.md +++ b/README_zh.md @@ -2,7 +2,7 @@ ### 简介 -这个预览版为 macOS 11.0+ 提供了硬件加速的 TensorFlow 和 TensorFlow Addons。通过 Apple 的 [ML Compute](https://developer.apple.com/documentation/mlcompute) 框架，搭载 Apple M1和 Intel 芯片的 Mac 都支持了原生硬件加速。 +这个预览版为 macOS 11.0+ 提供了硬件加速的 TensorFlow 和 TensorFlow Addons。通过 Apple 的 [ML Compute](https://developer.apple.com/documentation/mlcompute) 框架，搭载 Apple M1 和 Intel 芯片的 Mac 都支持了原生硬件加速。 ### 当前版本 @@ -20,7 +20,7 @@ ### 安装 -包含 Python 安装包和安装脚本的压缩文件可以从[releases](https://github.com/apple/tensorflow_macos/releases)下载。 +包含 Python 安装包和安装脚本的压缩文件可以从 [releases](https://github.com/apple/tensorflow_macos/releases) 下载。 #### 详细信息 @@ -32,7 +32,7 @@ 这将验证您的系统并要求您进行确认，然后创建一个安装了 TensorFlow macOS 的虚拟环境(https://docs.python.org/3.8/tutorial/venv.html)。 -- 或者，从[release](https://github.com/apple/tensorflow_macos/releases)下载压缩文件。压缩文件中包含一个安装脚本，其中包括加速版本的 TensorFlow ， TensorFlow Addons ，以及其他所需的依赖项。 +- 或者，从 [release](https://github.com/apple/tensorflow_macos/releases) 下载压缩文件。压缩文件中包含一个安装脚本，其中包括加速版本的 TensorFlow ，TensorFlow Addons ，以及其他所需的依赖项。 #### 在Conda上安装 @@ -47,7 +47,7 @@ TensorFlow 预览版支持使用 Xcode 命令行工具中的 Python 安装和测 ### 问题和反馈 -请通过[GitHub Issues](https://github.com/apple/tensorflow_macos/issues)提交新功能请求和报告问题。 +请通过 [GitHub Issues](https://github.com/apple/tensorflow_macos/issues) 提交新功能请求和报告问题。 ### 更多信息 @@ -55,7 +55,7 @@ TensorFlow 预览版支持使用 Xcode 命令行工具中的 Python 安装和测 首先，使用 ML Compute 作为 TensorFlow 和 TensorFlow Addons 的后端，是不需要对现有的 TensorFlow 脚本做任何更改。 -有一个可选的 ML Compute 硬件设备选择API `mlcompute.set_mlc_device(device_name='any')`。其中，`device_name`的默认值是`'any'`，这意味着 ML Compute 将在您的系统上选择最佳可用硬件设备，包括在多 GPU 上配置多 GPU 训练。其他可用参数有`'cpu'` 和`'gpu'` 。需要您注意，在 eager 模式下， ML Compute 将使用CPU。 如果您想选择 CPU ，你可以这样做： +有一个可选的 ML Compute 硬件设备选择API `mlcompute.set_mlc_device(device_name='any')`。其中，`device_name`的默认值是`'any'`，这意味着 ML Compute 将在您的系统上选择最佳可用硬件设备，包括在多 GPU 上配置多 GPU 训练。其他可用参数有`'cpu'` 和`'gpu'` 。需要您注意，在即时执行模式下， ML Compute 将使用CPU。 如果您想选择 CPU ，你可以这样做： ```python # 导入mlcompute模块, 使用可选的set_mlc_device API来使用ML Compute进行硬件设备选择. @@ -67,9 +67,9 @@ mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'an #### 日志和调试 -##### 静态图模式 +##### 图执行模式 -日志记录了许多关于 ML Compute 优化 TensorFlow 模型时产生的信息。在执行模型脚本时，通过设置环境变量`TF_MLC_LOGGING=1` 来显示日志。如下是静态图模式记录的日志信息列表： +日志记录了许多关于 ML Compute 优化 TensorFlow 模型时产生的信息。在执行模型脚本时，通过设置环境变量`TF_MLC_LOGGING=1` 来显示日志。如下是图执行模式记录的日志信息列表： - ML Compute 使用的硬件设备。 - 不使用 ML Compute 的原始 TensorFlow 计算图。 @@ -79,9 +79,9 @@ mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'an - 如果使用 ML Compute，用更大的子图来封装大部分的原始计算图，性能将会提高。注意，对于训练过程，通常至少有两个 MLCSubgraphOp 节点（表示前向传播以及反向传播/计算梯度子图）。 - ML Compute 计算图相对应的 TensorFlow 子图。 -##### Eager 模式 +##### 即时执行模式 -不同于静态图模式，Eager 模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制。如下是 Eager 模式记录的日志信息列表： +不同于图执行模式，即时执行模式的日志显示由`TF_CPP_MIN_VLOG_LEVEL`控制。如下是即时执行模式记录的日志信息列表： - 缓冲区指针和输入/输出张量的形状。 - 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值。该键值用于复现计算图，以及运行反向传播或者是更新优化器的参数。 @@ -90,12 +90,16 @@ mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'an ##### 调试建议 -- 在 GPU 上训练较大的模型可能会超出可分配的显存，导致内存分页。如果发生了这样的情况，您可以尝试减小批次大小或者是模型的层数。 +- 在 GPU 上训练较大的模型可能会超出可分配的显存（搭载 Apple M1 芯片的 Mac 使用的是 UMA 内存），导致显存分页。如果发生了这样的情况，您可以尝试减小批次大小或者是模型的层数。 - TensorFlow 支持多线程，这意味着不同的 TensorFlow 操作可以并行执行，比如` MLCSubgraphOp`。但这可能会导致输出重复的日志信息，如果您不希望在调试中出现这种情况，您可以设置线程数为1让 TensorFlow 顺序执行操作（详细信息，请参阅[`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)）。 -##### 在 Eager 模式下调试的其他建议： +##### 在即时执行模式下调试的其他建议： - 在日志中寻找指定张量的信息，请您在日志中搜索张量缓冲区的指针。如果定义了 ML Compute 不支持的操作，您需要强制转换为`size_t`类型，然后在日志中搜索有`MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`的指针。如果您想在日志中看到整个 LLVM 的 use-def 链，您有可能需要修改函数`OpKernelContext::input()`。 -- 您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止 Eager 模式下的任何操作转换成 ML Compute。您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来禁止计算梯度的操作（这样可以避免 TensorFlow 重新编译）。 +- 您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止即时执行模式下的任何操作转换成 ML Compute。您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来禁止计算梯度的操作（这样可以避免 TensorFlow 重新编译）。 - 为特定变量分配初始化的内存，请使用 `TF_MLC_ALLOCATOR_INIT_VALUE=`。 +### 翻译人员 + +译者才疏学浅，学识简陋，自明译文不及原著，纵使多次勘误和推敲，但仍难表达原著精微之处。前有孺子尝甘苦，诚邀诸君续春秋。@[Lu Han](https://github.com/luhan1024) 参与翻译了前半部分 @[Steve R. Sun](https://github.com/sun1638650145) 参与翻译了后半部分，您可以通过QQ 1040256093/1638650145 或邮箱 luhan_1024@outlook.com/s16386510145@gmail.com 联系我们并提出改进意见。 + From 4260692e7317edfb068a1223a649537d4f5abcf9 Mon Sep 17 00:00:00 2001 From: luhan1024 <66825721+luhan1024@users.noreply.github.com> Date: Sun, 7 Feb 2021 21:33:36 +0800 Subject: [PATCH 6/8] Update README_zh.md --- README_zh.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README_zh.md b/README_zh.md index 4ace93ba188..11d1d7d9284 100644 --- a/README_zh.md +++ b/README_zh.md @@ -87,6 +87,9 @@ mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'an - 构建`MLCTraining` 或者`MLCInference`计算图的张量缓冲区的键值。该键值用于复现计算图，以及运行反向传播或者是更新优化器的参数。 - 格式化的权重张量。 - 保存统计日志，例如插入和删除的信息。 + +### 翻译说明：即时执行模式，翻译自 eager mode。该模型下不需要先构造图，然后再使用Session.run()，而是可以得到即时的反馈。这样在研究和开发时会更加符合直觉。 + ##### 调试建议 From c75652d33ccad4586a4df9881fbf1d717297d18b Mon Sep 17 00:00:00 2001 From: "Steve R. Sun" <47380395+sun1638650145@users.noreply.github.com> Date: Sun, 7 Feb 2021 21:51:22 +0800 Subject: [PATCH 7/8] Update README_zh.md --- README_zh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_zh.md b/README_zh.md index 11d1d7d9284..7d89e4373f0 100644 --- a/README_zh.md +++ b/README_zh.md @@ -88,7 +88,7 @@ mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'an - 格式化的权重张量。 - 保存统计日志，例如插入和删除的信息。 -### 翻译说明：即时执行模式，翻译自 eager mode。该模型下不需要先构造图，然后再使用Session.run()，而是可以得到即时的反馈。这样在研究和开发时会更加符合直觉。 +###### 翻译说明：即时执行模式，翻译自 Eager mode。该模式下不需要先构造静态计算图，而是即时执行代码，这样在研究和开发时会更加符合直觉。 ##### 调试建议 From a165a27a1db3baf055f0c5bd4eb8b982f3562dfe Mon Sep 17 00:00:00 2001 From: sun1638650145 <1638650145@qq.com> Date: Sun, 7 Mar 2021 20:53:13 +0800 Subject: [PATCH 8/8] Update translation --- README.md | 24 ++++++++++++------------ README_zh.md | 45 ++++++++++++++++++++++++++++++--------------- 2 files changed, 42 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index d41e41a9183..031d114ef27 100644 --- a/README.md +++ b/README.md @@ -26,18 +26,18 @@ An archive containing Python packages and an installation script can be download - To quickly try this out, copy and paste the following into Terminal: ```shell - % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" ``` This will verify your system, ask you for confirmation, then create a [virtual environment](https://docs.python.org/3.8/tutorial/venv.html) with TensorFlow for macOS installed. - Alternatively, download the archive file from the [releases](https://github.com/apple/tensorflow_macos/releases). The archive contains an installation script, accelerated versions of TensorFlow, TensorFlow Addons, and needed dependencies. - ``` - % curl -fLO https://github.com/apple/tensorflow_macos/releases/download/v0.1alpha2/tensorflow_macos-${VERSION}.tar.gz - % tar xvzf tensorflow_macos-${VERSION}.tar - % cd tensorflow_macos - % ./install_venv.sh --prompt + ```shell + curl -fLO https://github.com/apple/tensorflow_macos/releases/download/v0.1alpha2/tensorflow_macos-${VERSION}.tar.gz + tar xvzf tensorflow_macos-${VERSION}.tar + cd tensorflow_macos + ./install_venv.sh --prompt ``` #### Installation on Conda @@ -53,8 +53,8 @@ For M1 Macs, the following packages are currently unavailable: When installing pip packages in a virtual environment, you may need to specify `--target` as follows: -``` -% pip install --upgrade -t "${VIRTUAL_ENV}/lib/python3.8/site-packages/" PACKAGE_NAME +```shell +pip install --upgrade -t "${VIRTUAL_ENV}/lib/python3.8/site-packages/" PACKAGE_NAME ``` ### ISSUES AND FEEDBACK @@ -70,11 +70,11 @@ It is not necessary to make any changes to your existing TensorFlow scripts to u There is an optional `mlcompute.set_mlc_device(device_name='any')` API for ML Compute device selection. The default value for `device_name` is `'any'`, which means ML Compute will select the best available device on your system, including multiple GPUs on multi-GPU configurations. Other available options are `'cpu'` and `'gpu'`. Please note that in eager mode, ML Compute will use the CPU. For example, to choose the CPU device, you may do the following: ```python - # Import mlcompute module to use the optional set_mlc_device API for device selection with ML Compute. - from tensorflow.python.compiler.mlcompute import mlcompute +# Import mlcompute module to use the optional set_mlc_device API for device selection with ML Compute. +from tensorflow.python.compiler.mlcompute import mlcompute - # Select CPU device. - mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and 'any'. +# Select CPU device. +mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and 'any'. ``` #### Unsupported TensorFlow Features diff --git a/README_zh.md b/README_zh.md index 7d89e4373f0..28bd88ebcf2 100644 --- a/README_zh.md +++ b/README_zh.md @@ -2,11 +2,11 @@ ### 简介 -这个预览版为 macOS 11.0+ 提供了硬件加速的 TensorFlow 和 TensorFlow Addons。通过 Apple 的 [ML Compute](https://developer.apple.com/documentation/mlcompute) 框架，搭载 Apple M1 和 Intel 芯片的 Mac 都支持了原生硬件加速。 +这个预览版为 macOS 11.0+ 提供了硬件加速的 TensorFlow 和 TensorFlow Addons。通过 Apple 的 [ML Compute](https://developer.apple.com/documentation/mlcompute) 框架，M1 Mac 和 Intel 芯片的 Mac 都支持了原生硬件加速。 ### 当前版本 -- 0.1-alpha2 +- 0.1-alpha3 ### 支持版本 @@ -16,35 +16,46 @@ ### 依赖 - macOS 11.0+ -- Python 3.8，可从[Xcode命令行工具](https://developer.apple.com/download/more/?=command%20line%20tools)下载。 +- Python 3.8（搭载 M1 Mac 芯片的 Mac 需要从[Xcode命令行工具](https://developer.apple.com/download/more/?=command%20line%20tools)下载）。 ### 安装 包含 Python 安装包和安装脚本的压缩文件可以从 [releases](https://github.com/apple/tensorflow_macos/releases) 下载。 -#### 详细信息 - - 您想快速体验这个版本的 TensorFlow，复制并粘贴以下内容到终端： ```shell - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" + % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)" ``` - 这将验证您的系统并要求您进行确认，然后创建一个安装了 TensorFlow macOS 的虚拟环境(https://docs.python.org/3.8/tutorial/venv.html)。 + 这将验证您的系统并要求您进行确认，然后创建一个安装了 TensorFlow macOS 的[虚拟环境](https://docs.python.org/3.8/tutorial/venv.html)。 - 或者，从 [release](https://github.com/apple/tensorflow_macos/releases) 下载压缩文件。压缩文件中包含一个安装脚本，其中包括加速版本的 TensorFlow ，TensorFlow Addons ，以及其他所需的依赖项。 + ```shell + % curl -fLO https://github.com/apple/tensorflow_macos/releases/download/v0.1alpha2/tensorflow_macos-${VERSION}.tar.gz + % tar xvzf tensorflow_macos-${VERSION}.tar + % cd tensorflow_macos + % ./install_venv.sh --prompt + ``` + #### 在Conda上安装 TensorFlow 预览版支持使用 Xcode 命令行工具中的 Python 安装和测试.。更多在 Conda 环境中安装的信息，请您参阅[#153](https://github.com/apple/tensorflow_macos/issues/153)。 #### 注意 -对于搭载 Apple M1 芯片的 Mac ，以下依赖包目前不可用： +对于搭载 M1 Mac ，以下依赖包目前不可用： - SciPy 和依赖包 - 服务器/客户端的 TensorBoard +在虚拟环境中安装 pip 软件包，您可能需要指定`--target`，如下所示： + +```shell +% pip install --upgrade -t "${VIRTUAL_ENV}/lib/python3.8/site-packages/" PACKAGE_NAME +``` + ### 问题和反馈 请通过 [GitHub Issues](https://github.com/apple/tensorflow_macos/issues) 提交新功能请求和报告问题。 @@ -65,6 +76,14 @@ from tensorflow.python.compiler.mlcompute import mlcompute mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'any'. ``` +#### 不支持的 TensorFlow 特性 + +以下 TensorFlow 特性目前在这个复刻暂不支持： + +- [tf.vectorized_map(向量化映射)](https://www.tensorflow.org/api_docs/python/tf/vectorized_map) +- [高阶梯度](https://www.tensorflow.org/guide/advanced_autodiff#higher-order_gradients) +- 雅可比矢量积 （又名 [前向传播](https://www.tensorflow.org/api_docs/python/tf/autodiff/ForwardAccumulator)） + #### 日志和调试 ##### 图执行模式 @@ -90,19 +109,15 @@ mlcompute.set_mlc_device(device_name='cpu') # 可用选项为'cpu', 'gpu'和'an ###### 翻译说明：即时执行模式，翻译自 Eager mode。该模式下不需要先构造静态计算图，而是即时执行代码，这样在研究和开发时会更加符合直觉。 - ##### 调试建议 - 在 GPU 上训练较大的模型可能会超出可分配的显存（搭载 Apple M1 芯片的 Mac 使用的是 UMA 内存），导致显存分页。如果发生了这样的情况，您可以尝试减小批次大小或者是模型的层数。 - TensorFlow 支持多线程，这意味着不同的 TensorFlow 操作可以并行执行，比如` MLCSubgraphOp`。但这可能会导致输出重复的日志信息，如果您不希望在调试中出现这种情况，您可以设置线程数为1让 TensorFlow 顺序执行操作（详细信息，请参阅[`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)）。 - -##### 在即时执行模式下调试的其他建议： - -- 在日志中寻找指定张量的信息，请您在日志中搜索张量缓冲区的指针。如果定义了 ML Compute 不支持的操作，您需要强制转换为`size_t`类型，然后在日志中搜索有`MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`的指针。如果您想在日志中看到整个 LLVM 的 use-def 链，您有可能需要修改函数`OpKernelContext::input()`。 -- 您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止即时执行模式下的任何操作转换成 ML Compute。您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来禁止计算梯度的操作（这样可以避免 TensorFlow 重新编译）。 +- 在即时执行模式下，您可以通过使用`TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`禁止即时执行模式下的任何操作转换成 ML Compute。您可以通过修改`$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py`文件来禁止计算梯度的操作（这样可以避免 TensorFlow 重新编译）。 - 为特定变量分配初始化的内存，请使用 `TF_MLC_ALLOCATOR_INIT_VALUE=`。 +- 设置环境变量`TF_DISABLE_MLC=1`来禁止 ML Compute 加速（例如，用于调试或验证结果）。 ### 翻译人员 -译者才疏学浅，学识简陋，自明译文不及原著，纵使多次勘误和推敲，但仍难表达原著精微之处。前有孺子尝甘苦，诚邀诸君续春秋。@[Lu Han](https://github.com/luhan1024) 参与翻译了前半部分 @[Steve R. Sun](https://github.com/sun1638650145) 参与翻译了后半部分，您可以通过QQ 1040256093/1638650145 或邮箱 luhan_1024@outlook.com/s16386510145@gmail.com 联系我们并提出改进意见。 +译者才疏学浅，学识简陋，自明译文不及原著，纵使多次勘误和推敲，但仍难表达原著精微之处。前有孺子尝甘苦，诚邀诸君续春秋。@[Lu Han](https://github.com/luhan1024) 参与翻译了前半部分 @[Steve R. Sun](https://github.com/sun1638650145) 参与翻译了后半部分，您可以通过QQ:1040256093 / 1638650145 或邮箱 luhan_1024@outlook.com / s16386510145@gmail.com 联系我们并提出改进意见。