Hugging Face 的徽标

Bitsandbytes 文档

概述

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

概述

bitsandbytes.functional API 为库的功能提供了低级构建块。

何时使用 bitsandbytes.functional

  • 当您需要直接控制量化操作及其参数时。
  • 构建利用低位算术的自定义层或操作。
  • 与其他生态系统工具集成。
  • 出于实验或研究目的，需要非标准量化或性能优化。

LLM.int8()

bitsandbytes.functional.int8_double_quant

< >

( A: 张量 col_stats: typing.Optional[torch.Tensor] = None row_stats: typing.Optional[torch.Tensor] = None out_col: typing.Optional[torch.Tensor] = None out_row: typing.Optional[torch.Tensor] = None threshold = 0.0 ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Optional[torch.Tensor]]

参数

  • A (torch.Tensor，数据类型为 torch.float16) — 输入矩阵。
  • col_stats (torch.Tensor，可选) — 用于保存列式量化比例的预分配张量。
  • row_stats (torch.Tensor，可选) — 用于保存行式量化比例的预分配张量。
  • out_col (torch.Tensor，可选) — 用于保存列式量化数据的预分配张量。
  • out_row (torch.Tensor，可选) — 用于保存行式量化数据的预分配张量。
  • threshold (float，可选) — 异常值特征的稀疏分解的可选阈值。

    当为 0.0 时，不保留任何异常值。默认为 0.0。

返回值

Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Optional[torch.Tensor]]

一个元组，包含量化张量和相关统计信息。

  • torch.Tensor，数据类型为 torch.int8：行式量化数据。
  • torch.Tensor，数据类型为 torch.int8：列式量化数据。
  • torch.Tensor，数据类型为 torch.float32：行式量化比例。
  • torch.Tensor，数据类型为 torch.float32：列式量化比例。
  • torch.Tensor，数据类型为 torch.int32，可选：包含异常值特征的列索引列表。

根据 LLM.int8() 算法确定输入矩阵 A 的量化统计信息。

统计信息是按行和按列（转置）确定的。

有关更多信息，请参阅 LLM.int8() 论文。

此函数对于训练很有用，但对于推理，建议改用 `int8_vectorwise_quant`。此实现执行额外的列式转置计算，这些计算未进行优化。

bitsandbytes.functional.int8_linear_matmul

< >

( A: 张量 B: 张量 out: typing.Optional[torch.Tensor] = None dtype = torch.int32 ) → torch.Tensor

参数

  • A (torch.Tensor) — 第一个矩阵操作数，数据类型为 torch.int8。
  • B (torch.Tensor) — 第二个矩阵操作数，数据类型为 torch.int8。
  • out (torch.Tensor，可选) — 用于存储结果的预分配张量。
  • dtype (torch.dtype，可选) — 输出的预期数据类型。默认为 torch.int32。

返回值

torch.Tensor

操作结果。

引发

NotImplementedError 或 RuntimeError

  • NotImplementedError — 当前环境不支持该操作。
  • RuntimeError — 当由于任何其他原因无法完成操作时引发。

执行 8 位整数矩阵乘法。

应用线性变换，使得 out = A @ B.T。如果可能，将使用整数张量核心硬件来加速操作。

bitsandbytes.functional.int8_mm_dequant

< >

( A: 张量 row_stats: 张量 col_stats: 张量 out: typing.Optional[torch.Tensor] = None bias: typing.Optional[torch.Tensor] = None ) → torch.Tensor

参数

  • A (torch.Tensor，数据类型为 torch.int32) — 量化 int8 矩阵乘法的结果。
  • row_stats (torch.Tensor) — 矩阵乘法左侧操作数的行式量化统计信息。
  • col_stats (torch.Tensor) — 矩阵乘法右侧操作数的列式量化统计信息。
  • out (torch.Tensor, optional) — 用于存储操作输出的预分配张量。
  • bias (torch.Tensor, optional) — 可选的偏置向量，添加到结果中。

返回值

torch.Tensor

反量化结果，带有可选的偏置，数据类型为 torch.float16。

对量化 int8 矩阵乘法的结果执行反量化。

bitsandbytes.functional.int8_vectorwise_dequant

< >

( A: Tensor stats: Tensor ) → torch.Tensor with dtype torch.float32

参数

  • A (torch.Tensor with dtype torch.int8) — 量化的 int8 张量。
  • stats (torch.Tensor with dtype torch.float32) — 行向量化统计信息。

返回值

torch.Tensor with dtype torch.float32

反量化张量。

将数据类型为 torch.int8 的张量反量化为 torch.float32。

bitsandbytes.functional.int8_vectorwise_quant

< >

( A: Tensor threshold = 0.0 ) → Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor]]

参数

  • A (torch.Tensor with dtype torch.float16) — 输入张量。
  • threshold (float, optional) — 用于离群特征稀疏分解的可选阈值。

    当为 0.0 时，不保留离群值。默认为 0.0。

返回值

Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor]]

一个元组，包含量化张量和相关统计信息。

  • torch.Tensor with dtype torch.int8: 量化数据。
  • torch.Tensor with dtype torch.float32: 量化尺度。
  • torch.Tensor，数据类型为 torch.int32，可选：包含异常值特征的列索引列表。

根据 LLM.int8() 算法将数据类型为 torch.float16 的张量量化为 torch.int8。

有关更多信息，请参阅 LLM.int8() 论文。

4 位

bitsandbytes.functional.dequantize_4bit

< >

( A: Tensor quant_state: typing.Optional[bitsandbytes.functional.QuantState] = None absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize: int = 64 quant_type = 'fp4' ) → torch.Tensor

参数

  • A (torch.Tensor) — 量化的输入张量。
  • quant_state (QuantState, optional) — 由 quantize_4bit 返回的量化状态。如果未提供 absmax，则为必需项。
  • absmax (torch.Tensor, optional) — 包含缩放值的张量。如果未提供 quant_state，则为必需项，否则将被忽略。
  • out (torch.Tensor, optional) — 用于存储结果的张量。
  • blocksize (int, optional) — 块的大小。默认为 64。有效值为 64、128、256、512、1024、2048 和 4096。
  • quant_type (str, optional) — 要使用的数据类型：nf4 或 fp4。默认为 fp4。

返回值

torch.Tensor

反量化张量。

引发

ValueError

  • ValueError — 当输入数据类型或块大小不受支持时引发。

反量化打包的 4 位量化张量。

输入张量通过将其划分为大小为 blocksize 的块进行反量化。这些块内的绝对最大值用于缩放非线性反量化。

bitsandbytes.functional.dequantize_fp4

< >

( A: Tensor quant_state: typing.Optional[bitsandbytes.functional.QuantState] = None absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize: int = 64 )

bitsandbytes.functional.dequantize_nf4

< >

( A: Tensor quant_state: typing.Optional[bitsandbytes.functional.QuantState] = None absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize: int = 64 )

bitsandbytes.functional.gemv_4bit

 < >

( A: Tensor B: Tensor out: typing.Optional[torch.Tensor] = None transposed_A = False transposed_B = False state = None )

bitsandbytes.functional.quantize_4bit

 < >

( A: Tensor absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize = 64 compress_statistics = False quant_type = 'fp4' quant_storage = torch.uint8 ) → Tuple[torch.Tensor, QuantState]

参数

  • A (torch.Tensor) — 输入张量。支持 float16、bfloat16 或 float32 数据类型。
  • absmax (torch.Tensor, optional) — 用于存储 absmax 值的张量。
  • out (torch.Tensor, optional) — 用于存储结果的张量。
  • blocksize (int, optional) — 块的大小。默认为 64。有效值包括 64、128、256、512、1024、2048 和 4096。
  • compress_statistics (bool, optional) — 是否额外量化 absmax 值。默认为 False。
  • quant_type (str, optional) — 要使用的数据类型：nf4 或 fp4。默认为 fp4。
  • quant_storage (torch.dtype, optional) — 用于存储结果的张量的数据类型。默认为 torch.uint8。

返回值

Tuple[torch.Tensor, QuantState]

包含量化结果的元组。

  • torch.Tensor: 包含打包的 4 位值的量化张量。
  • QuantState: 用于撤销量化的状态对象。

引发

ValueError

  • ValueError — 当输入数据类型不受支持时引发。

以 4 位值块量化张量 A。

通过将张量 A 分成独立量化的块来量化张量 A。

bitsandbytes.functional.quantize_fp4

< >

( A: Tensor absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize = 64 compress_statistics = False quant_storage = torch.uint8 )

bitsandbytes.functional.quantize_nf4

< >

( A: Tensor absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize = 64 compress_statistics = False quant_storage = torch.uint8 )

class bitsandbytes.functional.QuantState

< >

( absmax shape = None code = None blocksize = None quant_type = None dtype = None offset = None state2 = None )

用于与 Params4bit 和类似类一起使用的量化状态组件的容器

as_dict

 < >

( packed = False )

返回张量和字符串的字典，用于通过 _save_to_state_dict() 进行序列化 param: packed — 返回 dict[str, torch.Tensor]，用于适合 safetensors 保存的 state_dict

from_dict

< >

( qs_dict: typing.Dict[str, typing.Any] device: device )

将 state_dict 的组件解包到 QuantState 中，并在必要时转换为字符串、torch.dtype、整数等。

qs_dict：基于 state_dict，仅包含相关键，去除前缀。

键为 quant_state.bitsandbytes__[nf4/fp4] 的项可能包含次要的和非张量的量化状态项。

动态 8 位量化

8 位优化器量化中使用的原语。

有关更多详细信息，请参阅 深度学习并行性的 8 位近似

bitsandbytes.functional.dequantize_blockwise

< >

( A: Tensor quant_state: typing.Optional[bitsandbytes.functional.QuantState] = None absmax: typing.Optional[torch.Tensor] = None code: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize: int = 4096 nested = False ) → torch.Tensor

参数

  • A (torch.Tensor) — 量化的输入张量。
  • quant_state (QuantState, optional) — 由 quantize_blockwise 返回的量化状态。如果未提供 absmax，则为必需项。
  • absmax (torch.Tensor, optional) — 包含缩放值的张量。如果未提供 quant_state，则为必需项，否则将被忽略。
  • code (torch.Tensor, optional) — 描述低比特数据类型的映射。默认为带符号的 8 位动态类型。有关更多详细信息，请参阅（深度学习并行性的 8 位近似）[https://arxiv.org/abs/1511.04561]。当提供 quant_state 时将被忽略。
  • out (torch.Tensor, optional) — 用于存储结果的张量。
  • blocksize (int, optional) — 块的大小。默认为 4096。有效值包括 64、128、256、512、1024、2048 和 4096。当提供 quant_state 时将被忽略。

返回值

torch.Tensor

解量化的张量。数据类型由 quant_state.dtype 指示，默认为 torch.float32。

引发

ValueError

  • ValueError — 当输入数据类型不受支持时引发。

解量化值块中的张量。

输入张量通过将其划分为大小为 blocksize 的块进行反量化。这些块内的绝对最大值用于缩放非线性反量化。

bitsandbytes.functional.quantize_blockwise

< >

( A: Tensor code: typing.Optional[torch.Tensor] = None absmax: typing.Optional[torch.Tensor] = None out: typing.Optional[torch.Tensor] = None blocksize = 4096 nested = False ) → Tuple[torch.Tensor, QuantState]

参数

  • A (torch.Tensor) — 输入张量。支持 float16、bfloat16 或 float32 数据类型。
  • code (torch.Tensor, optional) — 描述低比特数据类型的映射。默认为带符号的 8 位动态类型。有关更多详细信息，请参阅（深度学习并行性的 8 位近似）[https://arxiv.org/abs/1511.04561]。
  • absmax (torch.Tensor, optional) — 用于存储 absmax 值的张量。
  • out (torch.Tensor, optional) — 用于存储结果的张量。
  • blocksize (int, optional) — 块的大小。默认为 4096。有效值包括 64、128、256、512、1024、2048 和 4096。
  • nested (bool, optional) — 是否额外量化 absmax 值。默认为 False。

返回值

Tuple[torch.Tensor, QuantState]

包含量化结果的元组。

  • torch.Tensor: 量化的张量。
  • QuantState: 用于撤销量化的状态对象。

引发

ValueError

  • ValueError — 当输入数据类型不受支持时引发。

量化值块中的张量。

输入张量通过将其划分为 blocksize 值的块进行量化。计算这些块内的绝对最大值，以缩放非线性量化。

实用工具

bitsandbytes.functional.get_ptr

< >

( A: typing.Optional[torch.Tensor] ) → Optional[ct.c_void_p]

参数

  • A (Optional[Tensor]) — 一个 PyTorch 张量。

返回值

Optional[ct.c_void_p]

指向底层张量数据的指针。

获取张量第一个元素的内存地址

bitsandbytes.functional.is_on_gpu

< >

( tensors: typing.Iterable[typing.Optional[torch.Tensor]] )

参数

  • tensors (Iterable[Optional[torch.Tensor]]) — 要验证的张量列表。

引发

RuntimeError

  • RuntimeError — 当验证失败时引发。

验证输入张量是否都在同一设备上。

输入张量也可以标记为 paged，在这种情况下，设备放置将被忽略。

< > 在 GitHub 上更新

←论文、资源和如何引用 概览→