.. image:: https://img.shields.io/coveralls/mila-udem/fuel.svg :target: https://coveralls.io/r/mila-udem/fuel

.. image:: https://travis-ci.org/mila-udem/fuel.svg?branch=master :target: https://travis-ci.org/mila-udem/fuel

.. image:: https://readthedocs.org/projects/fuel/badge/?version=latest :target: https://fuel.readthedocs.org/

.. image:: https://img.shields.io/scrutinizer/g/mila-udem/fuel.svg :target: https://scrutinizer-ci.com/g/mila-udem/fuel/

.. image:: https://requires.io/github/mila-udem/fuel/requirements.svg?branch=master :target: https://requires.io/github/mila-udem/fuel/requirements/?branch=master

.. image:: https://img.shields.io/badge/license-MIT-blue.svg :target: https://github.com/mila-udem/fuel/blob/master/LICENSE

Fuel

Fuel 为您的机器学习模型提供学习所需的数据。

• 提供与常见数据集的接口，如 MNIST、CIFAR-10（图像数据集）、Google 的 One Billion Words（文本）等众多数据集。
• 支持以多种方式遍历数据，例如按小批量处理，并可选择打乱或按顺序排列样本。
• 内置预处理流水线，允许您在数据流中实时修改数据，比如添加噪声、从句子中提取 n-gram、从图像中提取补丁等。
• 确保整个流水线可以通过 pickle 序列化；这是实现长时间运行实验的检查点和恢复功能所必需的。为此，我们大量依赖 picklable_itertools_ 库。

Fuel 主要面向 Blocks_ 开发，Blocks 是一个基于 Theano 的工具包，用于帮助训练神经网络。

如果您有任何问题，请随时发送邮件至 邮件列表_。

引用 Fuel 如果您在工作中使用了 Blocks 或 Fuel，我们非常希望您能引用以下论文：

Bart van Merriënboer、Dzmitry Bahdanau、Vincent Dumoulin、Dmitriy Serdyuk、David Warde-Farley、Jan Chorowski 和 Yoshua Bengio，《Blocks 和 Fuel：深度学习框架_》，arXiv 预印本 arXiv:1506.00619 [cs.LG]，2015 年。

文档 更多信息请参阅文档_。

.. _picklable_itertools: http://github.com/dwf/picklable_itertools .. _Blocks: http://github.com/mila-udem/blocks .. _mailing list: https://groups.google.com/d/forum/fuel-users .. _documentation: http://fuel.readthedocs.org/en/latest/ .. _Blocks 和 Fuel：深度学习框架: http://arxiv.org/abs/1506.00619

Fuel 快速上手指南

Fuel 是一个专为机器学习模型（特别是配合 Blocks 和 Theano 使用）提供数据支持的框架。它支持常见数据集（如 MNIST、CIFAR-10、One Billion Words），提供灵活的数据迭代方式（小批量、乱序/顺序），并支持构建可序列化的实时预处理管道。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux 或 macOS（Windows 支持有限，建议在 WSL 或虚拟机中运行）。
• Python 版本：Python 3.6+（具体版本取决于您安装的 Theano 和 Blocks 版本兼容性）。
• 核心依赖：
  • Theano：Fuel 主要设计用于配合 Theano 使用。
  • Blocks：Fuel 的主要协作框架。
  • picklable_itertools：用于确保数据管道可序列化。
  • HDF5 和 h5py：用于高效存储和读取大型数据集。
  • NumPy, SciPy, Pillow 等科学计算库。

提示：由于 Fuel 项目较早期，建议先安装兼容版本的 Theano 和 Blocks。国内用户可使用清华源或阿里源加速 Python 包安装。

安装步骤

1. 安装系统级依赖

在使用 pip 安装前，请先安装必要的系统库（以 Ubuntu/Debian 为例）：

sudo apt-get update
sudo apt-get install libhdf5-dev libsnappy-dev libbz2-dev liblz4-dev

2. 安装 Python 依赖

推荐使用国内镜像源加速安装。首先安装基础依赖和 Theano/Blocks：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy scipy pillow h5py picklable_itertools
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple theano blocks

3. 安装 Fuel

从 GitHub 源码安装最新稳定版：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple git+https://github.com/mila-udem/fuel.git

4. 下载数据集（可选但推荐）

Fuel 提供了命令行工具来下载和管理数据集。例如，下载 MNIST 数据集：

fuel-download mnist

注：下载速度取决于网络状况，如遇超时请尝试配置代理或使用离线数据包。

基本使用

Fuel 的核心概念是 Data Streams（数据流）。以下是最简单的使用示例，展示如何加载 MNIST 数据集并以小批量（minibatch）形式迭代。

示例：加载并迭代 MNIST 数据

from fuel.datasets import MNIST
from fuel.streams import DataStream
from fuel.schemes import SequentialScheme

# 1. 定义数据集
# train 表示加载训练集，which_sets=('train',) 指定只使用训练部分
dataset = MNIST(which_sets=('train',))

# 2. 创建数据流
# 使用 SequentialScheme 按顺序生成索引，batch_size 设为 32
stream = DataStream(dataset, scheme=SequentialScheme(examples=dataset.num_examples, batch_size=32))

# 3. 迭代数据
for batch in stream.get_epoch_iterator():
    # batch 通常是一个元组，包含 (features, targets)
    features, targets = batch
    
    # 在此处进行模型训练或数据处理
    print(f"Batch shape: {features.shape}")
    
    # 仅演示前两个批次后退出
    if stream.epoch == 0 and stream.batch_iterator_context.iter_index >= 2:
        break

进阶：添加预处理管道

Fuel 的强大之处在于其可组合的预处理转换（Transforms）。以下示例展示如何在数据流中加入一个简单的预处理步骤（例如将图像展平）：

from fuel.transformers import Flatten

# 在原有的 stream 基础上添加 Flatten 转换器
# sources=('features',) 指定要处理的数据源名称
flattened_stream = Flatten(stream, which_sources=('features',))

for batch in flattened_stream.get_epoch_iterator():
    features, targets = batch
    # 此时 features 已被展平为一维向量
    print(f"Flattened batch shape: {features.shape}")
    break

通过以上步骤，您已成功配置并使用 Fuel 为机器学习模型提供数据支持。更多高级功能（如自定义数据集、复杂预处理链、多进程加载）请参考官方文档。