---

TensorFlow I/O

TensorFlow I/O 是一组文件系统和文件格式的集合，这些内容在 TensorFlow 的内置支持中并不提供。TensorFlow I/O 支持的完整文件系统和文件格式列表可以在这里找到：https://www.tensorflow.org/io/api_docs/python/tfio。

使用 tensorflow-io 配合 Keras 非常简单。以下是一个基于 TensorFlow 入门教程 的示例，其中数据处理部分由 tensorflow-io 替代：

import tensorflow as tf
import tensorflow_io as tfio

# 将 MNIST 数据读入 IODataset。
dataset_url = "https://storage.googleapis.com/cvdf-datasets/mnist/"
d_train = tfio.IODataset.from_mnist(
    dataset_url + "train-images-idx3-ubyte.gz",
    dataset_url + "train-labels-idx1-ubyte.gz",
)

# 打乱数据集中的元素。
d_train = d_train.shuffle(buffer_size=1024)

# 默认情况下，图像数据是 uint8 类型，因此使用 map() 转换为 float32。
d_train = d_train.map(lambda x, y: (tf.image.convert_image_dtype(x, tf.float32), y))

# 像处理任何其他 tf.data.Dataset 一样准备批次数据。
d_train = d_train.batch(32)

# 构建模型。
model = tf.keras.models.Sequential(
    [
        tf.keras.layers.Flatten(input_shape=(28, 28)),
        tf.keras.layers.Dense(512, activation=tf.nn.relu),
        tf.keras.layers.Dropout(0.2),
        tf.keras.layers.Dense(10, activation=tf.nn.softmax),
    ]
)

# 编译模型。
model.compile(
    optimizer="adam", loss="sparse_categorical_crossentropy", metrics=["accuracy"]
)

# 训练模型。
model.fit(d_train, epochs=5, steps_per_epoch=200)

在上述 MNIST 示例中，用于访问数据集文件的 URL 直接传递给了 tfio.IODataset.from_mnist API 调用。这是因为 tensorflow-io 内置支持 HTTP/HTTPS 文件系统，从而无需将数据集下载并保存到本地目录。

注意：由于 tensorflow-io 能够自动检测并解压缩 MNIST 数据集（如果需要），我们可以直接将压缩文件（gzip 格式）的 URL 传递给 API 调用。

请查阅官方 文档，以获取更多关于该包的详细且有趣的用法。

安装

Python 包

可以通过 pip 直接安装 tensorflow-io Python 包：

$ pip install tensorflow-io

对于更喜欢尝试新事物的用户，也可以使用我们的夜间构建版本：

$ pip install tensorflow-io-nightly

为了确保您使用的 TensorFlow 版本与 TensorFlow-IO 兼容，您可以在安装时指定 tensorflow 附加依赖项：

pip install tensorflow-io[tensorflow]

类似的附加依赖项也适用于 tensorflow-gpu、tensorflow-cpu 和 tensorflow-rocm 等包。

Docker 镜像

除了 pip 包之外，还可以使用 Docker 镜像快速开始使用。

对于稳定版：

$ docker pull tfsigio/tfio:latest
$ docker run -it --rm --name tfio-latest tfsigio/tfio:latest

对于夜间版：

$ docker pull tfsigio/tfio:nightly
$ docker run -it --rm --name tfio-nightly tfsigio/tfio:nightly

R 包

成功安装 tensorflow-io Python 包后，您可以从 GitHub 安装 R 包的开发版本，方法如下：

if (!require("remotes")) install.packages("remotes")
remotes::install_github("tensorflow/io", subdir = "R-package")

TensorFlow 版本兼容性

为确保与 TensorFlow 的兼容性，建议根据下表安装相应版本的 TensorFlow I/O。发布列表可以在 这里 查看。

TensorFlow I/O 版本	TensorFlow 兼容性	发布日期
0.37.1	2.16.x	2024年7月1日
0.37.0	2.16.x	2024年4月25日
0.36.0	2.15.x	2024年2月2日
0.35.0	2.14.x	2023年12月18日
0.34.0	2.13.x	2023年9月8日
0.33.0	2.13.x	2023年8月1日
0.32.0	2.12.x	2023年3月28日
0.31.0	2.11.x	2023年2月25日
0.30.0	2.11.x	2023年1月20日
0.29.0	2.11.x	2022年12月18日
0.28.0	2.11.x	2022年11月21日
0.27.0	2.10.x	2022年9月8日
0.26.0	2.9.x	2022年5月17日
0.25.0	2.8.x	2022年4月19日
0.24.0	2.8.x	2022年2月4日
0.23.1	2.7.x	2021年12月15日
0.23.0	2.7.x	2021年12月14日
0.22.0	2.7.x	2021年11月10日
0.21.0	2.6.x	2021年9月12日
0.20.0	2.6.x	2021年8月11日
0.19.1	2.5.x	2021年7月25日
0.19.0	2.5.x	2021年6月25日
0.18.0	2.5.x	2021年5月13日
0.17.1	2.4.x	2021年4月16日
0.17.0	2.4.x	2020年12月14日
0.16.0	2.3.x	2020年10月23日
0.15.0	2.3.x	2020年8月3日
0.14.0	2.2.x	2020年7月8日
0.13.0	2.2.x	2020年5月10日
0.12.0	2.1.x	2020年2月28日
0.11.0	2.1.x	2020年1月10日
0.10.0	2.0.x	2019年12月5日
0.9.1	2.0.x	2019年11月15日
0.9.0	2.0.x	2019年10月18日
0.8.1	1.15.x	2019年11月15日
0.8.0	1.15.x	2019年10月17日
0.7.2	1.14.x	2019年11月15日
0.7.1	1.14.x	2019年10月18日
0.7.0	1.14.x	2019年7月14日
0.6.0	1.13.x	2019年5月29日
0.5.0	1.13.x	2019年4月12日
0.4.0	1.13.x	2019年3月1日
0.3.0	1.12.0	2019年2月15日
0.2.0	1.12.0	2019年1月29日
0.1.0	1.12.0	2018年12月16日

性能基准测试

我们使用 github-pages 来记录 API 性能基准测试的结果。每次提交到 master 分支时都会触发基准测试作业，从而便于跟踪性能随提交的变化情况。

贡献

TensorFlow I/O 是一个由社区主导的开源项目。因此，该项目依赖于公众的贡献、错误修复和文档编写。请参阅：

• 贡献指南，了解如何参与贡献。
• 开发文档，了解开发环境的设置方法。
• 教程，查看教程笔记本列表及如何编写教程的说明。

构建状态与持续集成

构建	状态
Linux CPU Python 2
Linux CPU Python 3
Linux GPU Python 2
Linux GPU Python 3

由于 manylinux2010 的要求，TensorFlow I/O 在 Linux 上使用 Ubuntu:16.04 + Developer Toolset 7 (GCC 7.3) 进行构建。在 Ubuntu 16.04 上配置 Developer Toolset 7 并不十分简单。如果系统已安装 Docker，则可以使用以下命令自动构建 manylinux2010 兼容的 whl 包：

#!/usr/bin/env bash

ls dist/*
for f in dist/*.whl; do
  docker run -i --rm -v $PWD:/v -w /v --net=host quay.io/pypa/manylinux2010_x86_64 bash -x -e /v/tools/build/auditwheel repair --plat manylinux2010_x86_64 $f
done
sudo chown -R $(id -nu):$(id -ng) .
ls wheelhouse/*

构建过程需要一些时间，但完成后，wheelhouse 目录中将提供适用于 Python 3.5、3.6 和 3.7 的 whl 包。

在 macOS 上，也可以使用相同的命令。不过，该脚本会依赖于 shell 中的 python 命令，并且只会生成与当前 shell 中 python 版本匹配的 whl 包。如果希望为特定版本的 Python 构建 whl 包，就需要将该版本的 Python 别名设置为 shell 中的 python。具体操作方法请参阅 .github/workflows/build.yml 文件中的 Auditwheel 步骤。

需要注意的是，上述命令也是我们在发布 Linux 和 macOS 版本时所使用的命令。

TensorFlow I/O 同时使用 GitHub Workflows 和 Google CI（Kokoro）进行持续集成。GitHub Workflows 负责 macOS 的构建和测试，而 Kokoro 则负责 Linux 的构建和测试。同样由于 manylinux2010 的要求，在 Linux 上，whl 包始终是在 Ubuntu 16.04 + Developer Toolset 7 的环境下构建的。测试则在多种不同系统的不同 Python 3 版本上进行，以确保良好的覆盖范围：

Python	Ubuntu 18.04	Ubuntu 20.04	macOS + osx9	Windows-2019
2.7	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	N/A
3.7	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
3.8	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:

TensorFlow I/O 与许多系统和云服务提供商实现了集成，例如 Prometheus、Apache Kafka、Apache Ignite、Google Cloud PubSub、AWS Kinesis、Microsoft Azure Storage、Alibaba Cloud OSS 等。

我们尽最大努力在持续集成过程中尽可能地对这些系统进行测试。其中，Prometheus、Kafka 和 Ignite 等测试是通过实际运行的系统完成的，即在测试开始前，我们会先在 CI 机器上安装 Prometheus/Kafka/Ignite。而 Kinesis、PubSub 和 Azure Storage 等测试则是通过官方或非官方的模拟器来完成的。此外，只要条件允许，我们也会进行离线测试，尽管通过离线测试覆盖的系统可能无法达到与实际系统或模拟器相同的覆盖程度。

	实际系统	模拟器	CI 集成	离线
Apache Kafka	:heavy_check_mark:		:heavy_check_mark:
Apache Ignite	:heavy_check_mark:		:heavy_check_mark:
Prometheus	:heavy_check_mark:		:heavy_check_mark:
Google PubSub		:heavy_check_mark:	:heavy_check_mark:
Azure Storage		:heavy_check_mark:	:heavy_check_mark:
AWS Kinesis		:heavy_check_mark:	:heavy_check_mark:
Alibaba Cloud OSS				:heavy_check_mark:
Google BigTable/BigQuery		待添加
Elasticsearch (实验性)	:heavy_check_mark:		:heavy_check_mark:
MongoDB (实验性)	:heavy_check_mark:		:heavy_check_mark:

模拟器参考：

• Google Cloud 提供的官方 PubSub 模拟器。
• Azure 提供的官方 Azurite 模拟器。
• LocalStack 提供的非官方 LocalStack 模拟器用于 AWS Kinesis。

社区

• SIG IO Google Group 和邮件列表：io@tensorflow.org
• SIG IO 每月会议记录
• Gitter 讨论室：tensorflow/sig-io

补充信息

• 利用分层存储且无需数据湖的流式机器学习 - Kai Waehner
• TensorFlow 与 Apache Arrow 数据集 - Bryan Cutler
• 如何为 TensorFlow 构建自定义数据集 - Ivelin Ivanov
• TensorFlow 与 Apache Ignite - Anton Dmitriev

许可证

Apache License 2.0

TensorFlow I/O 快速上手指南

TensorFlow I/O 是一个扩展库，提供了 TensorFlow 原生不支持的文件系统和文件格式（如 Kafka、Prometheus、各类云存储等）。它允许你直接从 URL 或特定协议读取数据，无需手动下载解压。

环境准备

• 操作系统: Linux (Ubuntu 16.04+), macOS, Windows
• Python 版本: 推荐 Python 3.7 - 3.11
• 前置依赖: 需预先安装与 TensorFlow I/O 版本匹配的 TensorFlow。

版本兼容性参考（部分）：

TensorFlow I/O 版本	兼容 TensorFlow 版本
0.37.x	2.16.x
0.36.x	2.15.x
0.35.x	2.14.x
0.34.x	2.13.x

提示：建议先确定你项目中使用的 TensorFlow 版本，再安装对应的 tensorflow-io 版本，以避免兼容性问题。

安装步骤

方法一：使用 pip 安装（推荐）

你可以直接通过 pip 安装稳定版。如果未安装 TensorFlow，可以使用 [tensorflow] 额外依赖自动安装兼容版本。

# 仅安装 tensorflow-io (需确保已安装兼容的 tensorflow)
pip install tensorflow-io

# 或者，同时安装兼容版本的 tensorflow
pip install tensorflow-io[tensorflow]

国内加速方案： 在中国大陆地区，建议使用清华或阿里镜像源以加快下载速度：

pip install tensorflow-io -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或
pip install tensorflow-io[tensorflow] -i https://mirrors.aliyun.com/pypi/simple/

如需尝试最新开发版（nightly build）：

pip install tensorflow-io-nightly

方法二：使用 Docker

如果你希望快速体验且避免环境配置问题，可以直接拉取官方 Docker 镜像。

# 拉取稳定版镜像
docker pull tfsigio/tfio:latest

# 运行容器
docker run -it --rm --name tfio-latest tfsigio/tfio:latest

基本使用

TensorFlow I/O 的核心优势在于可以直接从网络地址（HTTP/HTTPS）或其他文件系统读取数据并转换为 tf.data.Dataset。以下是一个直接从 URL 加载 MNIST 数据集并训练模型的完整示例。

特点：

• 无需手动下载 .gz 文件。
• 自动处理解压逻辑。
• 无缝集成 Keras model.fit。

import tensorflow as tf
import tensorflow_io as tfio

# 1. 定义数据源 URL
dataset_url = "https://storage.googleapis.com/cvdf-datasets/mnist/"

# 2. 直接使用 IODataset 从 URL 读取数据
# tensorflow-io 会自动检测并解压 gzip 文件
d_train = tfio.IODataset.from_mnist(
    dataset_url + "train-images-idx3-ubyte.gz",
    dataset_url + "train-labels-idx1-ubyte.gz",
)

# 3. 数据预处理
# 打乱数据
d_train = d_train.shuffle(buffer_size=1024)

# 将 uint8 图像数据转换为 float32
d_train = d_train.map(lambda x, y: (tf.image.convert_image_dtype(x, tf.float32), y))

# 构建 Batch
d_train = d_train.batch(32)

# 4. 构建 Keras 模型
model = tf.keras.models.Sequential(
    [
        tf.keras.layers.Flatten(input_shape=(28, 28)),
        tf.keras.layers.Dense(512, activation=tf.nn.relu),
        tf.keras.layers.Dropout(0.2),
        tf.keras.layers.Dense(10, activation=tf.nn.softmax),
    ]
)

# 5. 编译并训练
model.compile(
    optimizer="adam", loss="sparse_categorical_crossentropy", metrics=["accuracy"]
)

# 直接传入 IODataset 进行训练
model.fit(d_train, epochs=5, steps_per_epoch=200)

除了 MNIST，tensorflow-io 还支持直接读取 AVI 视频、PCAP 网络包、Apache Kafka 消息流等多种格式，具体 API 请参考 官方文档。