PyTorch 中的 torch.full 全面指南

在深度学习中，有时需要创建一个所有元素都相同的张量，例如作为常数初始值或掩码。PyTorch 提供了 torch.full 接口，功能灵活且参数丰富。下面我们按模块逐一展开。

一、接口定义

torch.full(*sizes,
           fill_value,
           out=None,
           dtype=None,
           layout=torch.strided,
           device=None,
           requires_grad=False) → Tensor

• 返回值：形状由 *sizes 决定，所有位置都填 fill_value 的张量。

• 等价签名：

  torch.full(size: Tuple[int, ...],
             fill_value: Number,
             out: Tensor = None,
             dtype: torch.dtype = None,
             layout: torch.layout = torch.strided,
             device: torch.device = None,
             requires_grad: bool = False) → Tensor
  

二、参数详解

注意：

• out、dtype、layout、device、requires_grad 均为 关键字参数，必须以 key=value 形式传入，否则会被误认为是形状（sizes）的一部分。

三、常见使用场景

1. 创建常数张量
   作为偏置、掩码或特殊标志值：

   bias = torch.full((batch_size, num_features), 0.1)
   mask = torch.full((H, W), True, dtype=torch.bool)
   

2. 初始化权重
   固定常数初始化：

   self.weight = torch.full((out_channels, in_channels), fill_value=0.01, requires_grad=True)
   

3. 占位符
   在复杂流程中预分配内存：

   out = torch.empty(3, 3)
   const = torch.full((3,3), 5, out=out)  # 直接写入 out
   

4. 与其他 API 配合

   # full_like：沿用现有张量形状
   ref = torch.zeros(2,4)
   filled = torch.full_like(ref, 3.14)  # 结果 shape=(2,4), dtype=float32
   

四、具体示例与输出

以下示例固定随机种子（对 full 无影响，仅为演示一致性），并展示每步输出。

import torch
torch.manual_seed(0)

# 示例 1：最基础的 (2,3) 常数张量
a = torch.full(2, 7)  
# 等价于 torch.full((2,), 7)
print("a:", a)  
# 输出：
# a: tensor([7, 7])

# 示例 2：二维常数（位置参数 vs tuple）
b = torch.full(2, 3, fill_value=-1)  # shape=(2,), fill_value=-1
print("\nb:", b)
# b: tensor([-1, -1])

c = torch.full((2,3), 5)
print("\nc:", c)
# c:
# tensor([[5, 5, 5],
#         [5, 5, 5]])

d = torch.full(2, 3, fill_value=9)  # 填充 9
print("\nd:", d)
# d: tensor([9, 9])

# 示例 3：指定 dtype 和 device
e = torch.full((2,2), 3.14, dtype=torch.float64)
print("\ne:", e, "\ne.dtype =", e.dtype)
# e:
# tensor([[3.1400, 3.1400],
#         [3.1400, 3.1400]], dtype=torch.float64)

# （假设有 GPU 环境）
# f = torch.full((1,3), 0, device='cuda:0')
# print("\nf.device =", f.device)

# 示例 4：使用 out 关键字
out = torch.empty(2,2)
torch.full((2,2), 42, out=out)
print("\nout(after full):", out)
# out:
# tensor([[42, 42],
#         [42, 42]])

# 示例 5：requires_grad=True
g = torch.full((3,), 1.0, requires_grad=True)
print("\ng:", g, "; requires_grad =", g.requires_grad)
# g: tensor([1., 1., 1.], requires_grad=True)

五、关键字参数设计原理

在 Python 里，当函数签名中出现 *sizes 时，所有位置参数都会被收集到 sizes 这个元组里，作为张量的形状。如果把 out、dtype 等也当位置参数传入，就会被当作形状维度导致类型错误或逻辑混乱。因此，PyTorch 将它们设计成 keyword-only arguments，只允许 out=…、dtype=…、device=… 等形式出现，保证了接口的清晰与安全。

总结

• 接口灵活：torch.full(2,3, fill_value=val) 或 torch.full((2,3), val) 都可；
• 关键字参数：out、dtype、layout、device、requires_grad 强制使用 key=value 形式；
• 常见场景：常数张量、权重初始化、占位符分配等；
• 示例丰富：提供了形状、数据类型、设备、in-place 输出、梯度追踪等全方位示例。