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

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

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

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

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

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

Blocks

Blocks 是一个基于 Theano 构建神经网络模型的框架。目前它支持并提供以下功能：

• 构建参数化的 Theano 操作，称为“积木”（bricks）
• 使用模式匹配在大型模型中选择变量和积木
• 用于优化模型的算法
• 训练的保存与恢复
• 在训练过程中监控和分析数值（包括训练集和测试集）
• 应用图变换，例如 Dropout

未来我们还希望支持：

• 维度、类型和轴的检查

参见：

• Fuel_，主要为 Blocks 开发的数据处理引擎。
• Blocks-examples_，包含维护良好的 Blocks 使用示例脚本。
• Blocks-extras_，包含半维护的额外 Blocks 组件。

引用 Blocks 如果您在工作中使用了 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 年。

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

贡献 如果您想做出贡献，请务必阅读 开发者指南_。

.. _documentation: http://blocks.readthedocs.org .. _developer guidelines: http://blocks.readthedocs.org/en/latest/development/index.html .. _Blocks and Fuel: Frameworks for deep learning: http://arxiv.org/abs/1506.00619 .. _Blocks-examples: https://github.com/mila-udem/blocks-examples .. _Blocks-extras: https://github.com/mila-udem/blocks-extras .. _Fuel: https://github.com/mila-udem/fuel

Blocks 快速上手指南

Blocks 是一个基于 Theano 的深度学习框架，旨在帮助用户更轻松地构建神经网络模型。它提供了模块化的构建块（Bricks）、灵活的算法配置、训练监控及断点续训等功能。

注意：Blocks 依赖于 Theano，而 Theano 目前已停止维护。本指南适用于需要维护旧项目或研究历史代码的场景。新项目建议考虑迁移至 PyTorch 或 TensorFlow。

环境准备

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

• 操作系统：Linux 或 macOS（Windows 支持较差，建议使用 WSL 或虚拟机）。
• Python 版本：推荐 Python 2.7 或 Python 3.4/3.5（取决于 Theano 版本兼容性）。
• 前置依赖：
  • Theano：Blocks 的核心后端。
  • NumPy & SciPy：科学计算基础库。
  • PyYAML：用于配置文件解析。
  • Fuel：Blocks 官方推荐的数据处理引擎（可选但强烈推荐）。

建议先安装好 Theano 并配置好 .theanorc 文件以启用 GPU 加速（如适用）。

安装步骤

您可以选择通过 pip 直接安装稳定版，或从源码安装最新开发版。

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

pip install blocks

如果您需要同时安装数据处理工具 Fuel：

pip install fuel

方法二：从源码安装（获取最新功能）

git clone https://github.com/mila-udem/blocks.git
cd blocks
pip install -e .

国内加速提示：如果下载速度较慢，可以使用国内镜像源进行安装：

pip install blocks -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Blocks 的核心概念是 "Bricks"（构建块），它们是参数化的 Theano 操作。以下是一个最简单的线性回归模型构建与训练示例。

1. 定义模型与数据

首先导入必要的模块，定义输入变量，并使用 Linear Brick 构建模型。

import numpy
from theano import tensor

from blocks.bricks import Linear, Bias
from blocks.bricks.lookup import LookupTable
from blocks.algorithms import GradientDescent, Scale
from blocks.main_loop import MainLoop
from blocks.model import Model
from blocks.graph import ComputationGraph
from blocks.extensions import FinishAfter, Printing
from blocks.extensions.monitoring import TrainingDataMonitoring
from blocks.filter import VariableFilter
from blocks.roles import WEIGHT

# 定义输入变量 (例如：10 维特征)
x = tensor.matrix('features')
y = tensor.matrix('targets')

# 构建模型：Linear -> Bias
linear = Linear(input_dim=10, output_dim=1, name='linear')
bias = Bias(name='bias')
prediction = bias.apply(linear.apply(x))

# 定义代价函数 (均方误差)
cost = ((prediction - y) ** 2).mean()
cost.name = 'MSE'

2. 初始化算法与主循环

配置优化算法（如带动量的 SGD）并设置主循环，包含监控扩展。

# 获取模型参数
cg = ComputationGraph(cost)
weights = VariableFilter(roles=[WEIGHT])(cg.variables)

# 定义优化算法
algorithm = GradientDescent(
    cost=cost, 
    parameters=weights,
    step_rule=Scale(learning_rate=0.01)
)

# 创建主循环
main_loop = MainLoop(
    model=Model(cost),
    data_stream=None, # 实际使用时需传入 Fuel 生成的 data_stream
    algorithm=algorithm,
    extensions=[
        TrainingDataMonitoring(variables=cg.variables),
        Printing(),
        FinishAfter(after_n_epochs=10)
    ]
)

# 运行训练
# main_loop.run() 

3. 数据流说明

在实际生产中，Blocks 通常配合 Fuel 使用来生成 data_stream。一个简单的随机数据流示例如下：

from fuel.streams import DataStream
from fuel.datasets import IterableDataset

# 构造虚拟数据
dataset = IterableDataset([{'features': numpy.random.rand(100, 10), 
                            'targets': numpy.random.rand(100, 1)}])
stream = DataStream(dataset)

# 将 stream 赋值给 main_loop.data_stream 即可开始训练
main_loop.data_stream = stream

更多复杂模型（如 RNN、CNN）及高级用法，请参考 Blocks 官方文档 或查看 blocks-examples 仓库中的脚本。