PyTorch-TCN库使用指南与笔记汇总

提供以下功能

TCN类

Conv1d 和 ConvTranspose1d 层的实现，并带有因果/非因果切换功能

流式推理（Streaming Inference）选项，可用于实时应用

兼容 ONNX（Open Neural Network Exchange）格式，可在非Python环境（如C++）中使用已训练的TCN模型

1 TCN类

from pytorch_tcn import TCN

model = TCN(
    num_inputs: int,
    num_channels: ArrayLike,
    kernel_size: int = 4,
    dilations: Optional[ ArrayLike ] = None,
    dilation_reset: Optional[ int ] = None,
    dropout: float = 0.1,
    causal: bool = True,
    use_norm: str = 'weight_norm',
    activation: str = 'relu',
    kernel_initializer: str = 'xavier_uniform',
    use_skip_connections: bool = False,
    input_shape: str = 'NCL',
    embedding_shapes: Optional[ ArrayLike ] = None,
    embedding_mode: str = 'add',
    use_gate: bool = False,
    lookahead: int = 0,
    output_projection: Optional[ int ] = None,
    output_activation: Optional[ str ] = None,
)

1.1 输入&输出形状

(N, Cin, L)

N：批量大小

Cin：输入/出通道数（特征维度）

L：序列长度

1.2 参数详解

num_inputs	输入数据的特征维度
num_channels	一个list，指定每个残差块的通道数（这个TCN多少层也是通过这个来确定的）
kernel_size	卷积核大小
dilations	膨胀率若为 `None`，则自动计算为 2^(0…n)（标准做法）。也可手动传入特定膨胀率列表，如 `[1, 2, 4, 8]`。
dilation_reset	膨胀率重置若不重置，膨胀率会指数级增长，导致内存溢出。如果设置了重置，那么超过之后会从最小的dilation开始再来一轮。例如，`dilation_reset=16` 使膨胀率超过16后重置，如 `[1, 2, 4, 8, 16, 1, 2, 4, ...]`
dropout
causal	是否使用因果卷积 `True`：忽略未来信息，适用于实时预测。 `False`：考虑未来信息，可用于非实时预测
use_norm	归一化方式可选：`weight_norm`（默认）/`batch_norm`/`layer_norm`/`None`。 `weight_norm` 在原论文中使用，其他方式需根据具体任务测试。
activation	激活函数：默认 `relu`
kernel_initializer	权重初始化可选：`uniform` / `normal` / `kaiming_uniform` / `kaiming_normal` / `xavier_uniform` / `xavier_normal`。默认 `xavier_uniform`，相比 `normal` 初始化更稳定。
use_skip_connections	跳跃连接 `True`：每个残差块的输出都会传递到最终输出（类似 WaveNet）。 `False`（默认）：不使用跳跃连接（原始 TCN 结构）
input_shape	输入形状格式） `NCL`（默认）：批量大小、通道数、序列长度（PyTorch 格式）。 `NLC`：批量大小、序列长度、通道数（时序数据常见格式）。
output_projection	输出投影：若非 `None`，则通过 1×1 卷积将输出投影到指定维度。适用于输入和输出维度不同的情况
output_activation	输出激活函数：可选 `softmax` 等，用于分类任务。 `None`（默认）：不使用激活函数。

2因果卷积

pytorch-TCN 提供了一个 因果卷积层，它继承自 PyTorch 的 Conv1d，可以直接替换标准的 Conv1d 层

2.1 参数说明

2.1.1 `TemporalConv1d`（因果卷积层）

in_channels	输入通道数
out_channels	输出通道数
kernel_size	卷积核大小
stride	步长，默认 `1`
padding	默认 `0`，自动计算，若手动设置可能会报错
dilation	膨胀率，默认 `1`
groups	组卷积数，默认 `1`
bias	是否使用偏置，默认 `True`
padding_mode	填充模式，默认 `zeros`
device	运行设备，默认 `None`（自动选择）
dtype	数据类型，默认 `None`
causal	是否使用因果卷积，默认 `True`

2.1.2 `TemporalConvTranspose1d`（转置卷积层）

in_channels	输入通道数
out_channels	输出通道数
kernel_size	卷积核大小
stride	步长，默认 `1`
padding	默认 `0`，自动计算，若手动设置可能会报错
dilation	膨胀率，默认 `1`
groups	组卷积数，默认 `1`
bias	是否使用偏置，默认 `True`
padding_mode	填充模式，默认 `zeros`
device	运行设备，默认 `None`（自动选择）
dtype	数据类型，默认 `None`
causal	是否使用因果卷积，默认 `True`

2.2 基本使用举例

from pytorch_tcn import TemporalConv1d, TemporalConvTranspose1d
import torch


# 因果卷积层
conv = TemporalConv1d(
    in_channels=32,     # 输入通道数
    out_channels=32,    # 输出通道数
    kernel_size=3,      # 卷积核大小
    causal=True         # 是否使用因果卷积
)

# 反卷积层（转置卷积）
conv_t = TemporalConvTranspose1d(
    in_channels=32,
    out_channels=32,
    kernel_size=4,
    stride=2
)

# 前向传播
x = torch.randn(10, 32, 100)  # (batch_size=10, in_channels=32, seq_len=100)

y = conv(x, inference=False, in_buffer=None)    
# 进行卷积运算
y_t = conv_t(x, inference=False, in_buffer=None)  
# 进行转置卷积


y.shape,y_t.shape
#(torch.Size([10, 32, 100]), torch.Size([10, 32, 200]))

3 流式推理

模型能够逐块（blockwise）处理数据，而无需加载完整的序列。

这一功能对于实时应用至关重要。

3.1 流式推理的挑战

在 TCN 结构中，若 kernel_size > 1，为了保证输出的时间步与输入相同，TCN 始终会使用零填充（zero padding）。

然而，在块状处理（blockwise processing）时，零填充可能会导致感受野断裂，从而影响模型的推理效果

假设输入序列为[ X1, X2, X3, X4 ]

使用 kernel_size=3，dilation=1 的因果网络时，第一层的填充长度为 2

期望的输入格式：[ 0, 0, X1, X2, X3, X4 ]

但若按块状输入 [X1, X2] 和 [X3, X4]，则会导致：[ 0, 0, X1, X2 ] + [ 0, 0, X3, X4 ]

——>不同块的填充断裂，使得推理结果与整体序列处理时不同，影响模型的表现。

——>TCN 采用内部缓冲区（buffer），用于存储网络的输入历史，并在下一次推理时将其作为填充

因此，无论数据是否是整块输入还是逐块输入，最终输出都是一致的。

注意：流式推理时，批量大小 batch_size 必须为 1

`3.2 如何使用流式推理`

from pytorch_tcn import TCN

# 初始化 TCN 模型
tcn = TCN(
    num_inputs=10,      # 输入特征数
    num_channels=[32, 64, 128],
    causal=True,         # 流式推理只适用于因果网络
)

# 处理新序列前 **必须** 重置缓冲区
tcn.reset_buffers()
#作用是，清空存储的历史输入，确保每次推理不会受到上一次序列的影响。


# 流式推理的输入数据按块分割
for block in blocks:  # 每个 block 形状：(1, num_inputs, block_size)
    out = tcn(block, inference=True)  
    # 启用流式推理，使 TCN 在推理时利用缓冲区填充，确保逐块处理时的输出与完整序列处理时一致。

作者：UQI-LIUWJ

物联沃分享整理
物联沃-IOTWORD物联网 » PyTorch-TCN库使用指南与笔记汇总