---

提供以下功能

• 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，则通过 1x1 卷积将输出投影到指定维度。 适用于输入和输出维度不同的情况
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 在推理时利用缓冲区填充，确保逐块处理时的输出与完整序列处理时一致。