向量量化变分自编码器

这是一个基于 PyTorch 的向量量化变分自编码器实现（https://arxiv.org/abs/1711.00937）。

您可以在这里找到作者的 TensorFlow 原始实现，并附带一个可以在 Jupyter Notebook 中运行的 示例。

安装依赖

要安装依赖，请创建一个包含 Python 3 的 conda 或虚拟环境，然后运行 pip install -r requirements.txt。

运行 VQ-VAE

要运行 VQ-VAE，只需执行 python3 main.py。如果您想保存模型，请务必加上 -save 标志。您还可以在命令行中添加参数。默认值如下：

parser.add_argument("--batch_size", type=int, default=32)
parser.add_argument("--n_updates", type=int, default=5000)
parser.add_argument("--n_hiddens", type=int, default=128)
parser.add_argument("--n_residual_hiddens", type=int, default=32)
parser.add_argument("--n_residual_layers", type=int, default=2)
parser.add_argument("--embedding_dim", type=int, default=64)
parser.add_argument("--n_embeddings", type=int, default=512)
parser.add_argument("--beta", type=float, default=.25)
parser.add_argument("--learning_rate", type=float, default=3e-4)
parser.add_argument("--log_interval", type=int, default=50)

模型

VQ-VAE 包含以下基本模型组件：

1. Encoder 类，定义映射 x -> z_e。
2. VectorQuantizer 类，将编码器输出转换为离散的独热向量，该向量是与之最接近的嵌入向量的索引：z_e -> z_q。
3. Decoder 类，定义映射 z_q -> x_hat，用于重建原始图像。

编码器和解码器类都是卷积和反卷积堆栈，其架构中包含残差块 参见 ResNet 论文。残差模型由 ResidualLayer 和 ResidualStack 类定义。

这些组件按照以下文件夹结构组织：

models/
    - decoder.py -> Decoder
    - encoder.py -> Encoder
    - quantizer.py -> VectorQuantizer
    - residual.py -> ResidualLayer, ResidualStack
    - vqvae.py -> VQVAE

PixelCNN — 从 VQ-VAE 隐空间采样

要从隐空间采样，我们需要在隐层像素值 z_ij 上拟合一个 PixelCNN。这里的关键在于认识到 VQ-VAE 将图像映射到一个具有与单通道图像相同结构的隐空间。例如，如果您使用默认的 VQ-VAE 参数，它会将形状为 (32,32,3) 的 RGB 图像映射到形状为 (8,8,1) 的隐空间，这相当于一张 8×8 的灰度图像。因此，您可以使用 PixelCNN 来拟合 8×8 单通道隐空间“像素”值的分布。

要训练 PixelCNN 对隐表示进行建模，您需要先执行以下步骤：

1. 在您选择的数据集上训练 VQ-VAE。
2. 使用保存的 VQ-VAE 参数对您的数据集进行编码，并使用 np.save API 保存离散的隐空间表示。在 quantizer.py 中，这个变量是 min_encoding_indices。
3. 在 utils.load_latent_block 函数中指定您已保存的隐空间数据集路径。
4. 运行 PixelCNN 脚本。

要运行 PixelCNN，只需输入：

python pixelcnn/gated_pixelcnn.py

以及任何其他参数（请参阅 argparse 语句）。默认数据集是 LATENT_BLOCK，只有在您已经训练过 VQ-VAE 并保存了隐表示的情况下才能使用。

VQ-VAE 快速上手指南

本指南基于 PyTorch 实现的向量量化变分自编码器（Vector Quantized Variational Autoencoder），帮助开发者快速搭建并运行模型。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：Python 3.x
• 依赖管理：推荐使用 conda 或 virtualenv 创建独立虚拟环境
• 网络建议：若下载依赖较慢，可配置国内镜像源（如清华源、阿里源）加速 pip 安装

安装步骤

1. 创建并激活 Python 虚拟环境（以 conda 为例）：

   conda create -n vqvae python=3.8
   conda activate vqvae
   

2. 克隆项目代码并进入目录（假设已获取源码）：

   cd path/to/vqvae
   

3. 安装依赖包（推荐使用国内镜像加速）：

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

训练 VQ-VAE 模型

运行主脚本即可开始训练，默认参数适用于大多数实验场景：

python3 main.py

若需保存训练好的模型，请添加 -save 标志：

python3 main.py -save

可通过命令行自定义超参数，例如：

python3 main.py --batch_size 64 --n_updates 10000 --learning_rate 1e-4

常用参数说明：

• --batch_size: 批次大小（默认 32）
• --n_updates: 训练迭代次数（默认 5000）
• --embedding_dim: 嵌入维度（默认 64）
• --n_embeddings: 码本大小（默认 512）
• --beta: 承诺损失权重（默认 0.25）

模型结构概览

核心组件位于 models/ 目录：

• encoder.py: 编码器（$x \to z_e$）
• quantizer.py: 向量量化器（$z_e \to z_q$）
• decoder.py: 解码器（$z_q \to \hat{x}$）
• residual.py: 残差块与残差堆栈
• vqvae.py: 整体 VQ-VAE 模型封装

潜在空间采样（可选）

若需从潜在空间生成新样本，可结合 PixelCNN 进行建模：

1. 先训练并保存 VQ-VAE 模型；
2. 编码数据集并保存离散潜在表示（min_encoding_indices）；
3. 在 utils.load_latent_block 中指定保存路径；
4. 运行 PixelCNN 脚本：

python pixelcnn/gated_pixelcnn.py

注意：PixelCNN 训练依赖于已生成的潜在空间数据，默认数据集为 LATENT_BLOCK。