flat_quant

产品支持情况

  • Ascend 950PR&950DT系列产品:支持
  • Atlas A3系列产品:支持
  • Atlas A2系列产品:支持
  • Atlas 200I/500 A2推理产品:不支持
  • Atlas推理系列产品:不支持
  • Atlas训练系列产品:不支持

功能说明

  • 接口功能:

    为矩阵x依次进行两次克罗内克积小矩阵乘法,然后针对矩阵乘的结果进行量化处理。底层封装aclnnFlatQuantV3。

  • 计算公式:

    intermediate=x⋅kronecker_p2\text{intermediate} = x \cdot \text{kronecker\_p2}

    result=kronecker_p1⋅intermediate\text{result} = \text{kronecker\_p1} \cdot \text{intermediate}

    scale=compute_quant_scale(result,clip_ratio,dst_type_max)\text{scale} = \text{compute\_quant\_scale}(\text{result}, \text{clip\_ratio}, \text{dst\_type\_max})

    out=quantize(result,scale)\text{out} = \text{quantize}(\text{result}, \text{scale})

函数原型

cann_ops_nn.flat_quant(x, kronecker_p1, kronecker_p2, clip_ratio=1.0, dst_dtype=torch.quint4x2, dst_type_max=0.0, group_list=None, group_list_type=0)
    -> (Tensor out, Tensor quant_scale)

参数说明

参数名 参数类型 可选/必选 描述 数据类型 维度(shape)
x Tensor 必选 输入矩阵,进行克罗内克积乘法和量化处理的数据张量。N2必须是8的整数倍(dst_dtype = torch.quint4x2时)或偶数(dst_dtype = torch_npu.float4_e2m1fn_x2时)。 float16、bfloat16 (M, N1, N2)
kronecker_p1 Tensor 必选 第一个克罗内克积矩阵,N1维与x中N1维一致。 float16、bfloat16 (N1, N1)
kronecker_p2 Tensor 必选 第二个克罗内克积矩阵,N2维与x中N2维一致。 float16、bfloat16 (N2, N2)
clip_ratio float 可选 量化裁剪比例,用于控制量化的裁剪幅度,范围(0, 1]。默认值:1.0。 - -
dst_dtype int 可选 指定输出数据类型。支持torch.quint4x2(默认)、torch_npu.float4_e2m1fn_x2。 - -
dst_type_max float 可选 目标数据类型的最大值,输入值只能是0或[6, 12]范围内的数。默认值:0.0。 - -
group_list Tensor 可选 分组列表,用于分组量化。支持1D或2D输入。默认值:None。 int64 (G,) 或 (G, 2)
group_list_type int 可选 group_list输入的分组方式,取值范围0-2。默认值:0。 - -

返回值说明

输出名 输出类型 可选/必选 描述 数据类型 维度(shape)
out Tensor 必选 量化输出。dst_dtype = torch.quint4x2时数据类型为int32,shape为(M, N1, N2//8),dst_dtype = torch_npu.float4_e2m1fn_x2时数据类型为uint8,shape为(M, N1 * N2//2)。 int32、uint8 (M, N1, N2//8) 或 (M, N1 * N2//2)
quant_scale Tensor 必选 量化缩放因子。dst_dtype = torch.quint4x2时数据类型为float32,shape为(M,),dst_dtype = torch_npu.float4_e2m1fn_x2时数据类型为uint8,shape为(M, ceildiv(N1*N2,64), 2)。 float32、uint8 (M,) 或 (M, ceildiv(N1*N2,64), 2)

约束说明

  • 该接口支持训练、推理场景下使用。
  • 该接口支持单算子模式和TorchAir图模式调用。
  • 输入x的N2维度必须满足以下条件:
    • dst_dtype = torch.quint4x2时,N2必须是8的整数倍。
    • dst_dtype = torch_npu.float4_e2m1fn_x2时,N2必须是偶数。
  • 输入kronecker_p1和kronecker_p2的数据类型必须与x一致。
  • dst_dtype支持torch.quint4x2(默认)、torch_npu.float4_e2m1fn_x2,输出说明如下:
    • 如果dtype为torch.quint4x2时,输出out类型为int32,由8个int4拼接,查看具体值需自行解包,输出quant_scale类型为float32。
    • 如果dtype为torch_npu.float4_e2m1fn_x2时,输出out类型为uint8,由2个float4_e2m1fn_x2拼接,查看具体值需自行解包,输出quant_scale类型为uint8,查看实际值需自行转换成float8_e8m0fnu。
  • group_list_type取值范围为0-2,当group_list_type为0或1时,group_list的shape为(G,),当group_list_type为2时,group_list的shape为(G, 2),G表示分组数,G需要小于等于1024。
  • group_list需要满足以下条件:
    • Ascend 950PR&950DT系列产品:group_list仅支持None输入。
    • Atlas A3系列产品、Atlas A2系列产品:
      • group_list不为None时,group_list输入的数值需要满足以下条件,否则无法保证输出是否符合预期:
        • 当group_list_type为0时,group_list必须为非负单调非递减数列,表示分组后每组大小的cumsum结果(累计和),最后一个值应小于等于x中tensor的第一维。
        • 当group_list_type为1时,group_list必须为非负数列,表示分组后每组大小,数值的总和应小于等于x中tensor的第一维。
        • 当group_list_type为2时,group_list必须为非负数列,数据排布为[[groupIdx0, groupSize0], [groupIdx1, groupSize1]……],其中groupSize为分组后每组大小,第二列数值的总和应小于等于x中tensor的第一维。

确定性计算

默认支持确定性计算。

调用说明

  • 单算子模式调用(eager)

    import torch
    import torch_npu
    import cann_ops_nn
    
    M, N1, N2 = 128, 16, 16
    x = torch.randn(M, N1, N2, dtype=torch.float16).npu()
    kronecker_p1 = torch.randn(N1, N1, dtype=torch.float16).npu()
    kronecker_p2 = torch.randn(N2, N2, dtype=torch.float16).npu()
    
    # int32 输出(默认)
    out, quant_scale = cann_ops_nn.flat_quant(x, kronecker_p1, kronecker_p2)
    print("out: ", out)
    print("quant_scale: ", quant_scale)
    

    带可选输入:

    group_list = torch.tensor([0, 16, 32, 48, 64], dtype=torch.int64).npu()
    out, quant_scale = cann_ops_nn.flat_quant(
        x, kronecker_p1, kronecker_p2,
        group_list=group_list,
        clip_ratio=0.95,
        group_list_type=0
    )
    
  • 图模式(TorchAir)调用

    import torch, torch_npu, cann_ops_nn
    
    @torch.compile(backend="npu")
    def func(x, p1, p2):
        return cann_ops_nn.flat_quant(x, p1, p2)
    
    M, N1, N2 = 128, 16, 16
    x = torch.randn(M, N1, N2, dtype=torch.float16).npu()
    kronecker_p1 = torch.randn(N1, N1, dtype=torch.float16).npu()
    kronecker_p2 = torch.randn(N2, N2, dtype=torch.float16).npu()
    out, quant_scale = func(x, kronecker_p1, kronecker_p2)
    print("out: ", out)
    print("quant_scale: ", quant_scale)