Bitsandbytes 文档

概览

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

概述

bitsandbytes.functional API 提供了该库功能的底层构建块。

何时使用 bitsandbytes.functional

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

LLM.int8()

bitsandbytes.functional.int8_linear_matmul

< >

( A: Tensor B: Tensor 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

操作的结果。

引发

NotImplementedErrorRuntimeError

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

执行 8 位整数矩阵乘法。

应用线性变换,使得 `out = A @ B.T`。在可能的情况下,利用整数张量核心硬件来加速操作。

bitsandbytes.functional.int8_mm_dequant

< >

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

参数

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

返回

torch.Tensor

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

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

bitsandbytes.functional.int8_vectorwise_dequant

< >

( A: Tensor stats: Tensor ) 数据类型为 torch.float32torch.Tensor

参数

  • A (数据类型为 torch.int8torch.Tensor) — 量化的 int8 张量。
  • stats (数据类型为 torch.float32torch.Tensor) — 行向量量化统计信息。

返回

数据类型为 torch.float32torch.Tensor

反量化后的张量。

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

bitsandbytes.functional.int8_vectorwise_quant

< >

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

参数

  • A (数据类型为 torch.float16torch.Tensor) — 输入张量。
  • threshold (float, 可选) — 用于离群特征稀疏分解的可选阈值。

    当为 0.0 时,不保留任何离群值。默认为 0.0。

返回

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

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

  • 数据类型为 torch.int8torch.Tensor: 量化后的数据。
  • 数据类型为 torch.float32torch.Tensor: 量化尺度。
  • 数据类型为 torch.int32torch.Tensor, 可选: 包含离群特征的列索引列表。

根据 `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, 可选) — 由 `quantize_4bit` 返回的量化状态。如果未提供 `absmax`,则此项为必需。
  • absmax (torch.Tensor, 可选) — 包含缩放值的张量。如果未提供 `quant_state`,则此项为必需,否则将被忽略。
  • out (torch.Tensor, 可选) — 用于存储结果的张量。
  • blocksize (int, 可选) — 块的大小。默认为 64。有效值为 64、128、256、512、1024、2048 和 4096。
  • quant_type (str, 可选) — 要使用的数据类型:`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, 可选) — 用于存储绝对最大值的张量。
  • out (torch.Tensor, 可选) — 用于存储结果的张量。
  • blocksize (int, 可选) — 块的大小。默认为 64。有效值为 64、128、256、512、1024、2048 和 4096。
  • compress_statistics (bool, 可选) — 是否额外量化绝对最大值。默认为 False。
  • quant_type (str, 可选) — 要使用的数据类型:`nf4` 或 `fp4`。默认为 `fp4`。
  • quant_storage (torch.dtype, 可选) — 用于存储结果的张量的数据类型。默认为 `torch.uint8`。

返回

Tuple[torch.Tensor, QuantState]

包含量化结果的元组。

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

引发

ValueError

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

将张量 A 量化为 4 位值的块。

通过将张量 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() 进行序列化。参数:packed — 返回适用于 safetensors 保存的 state_dict 的 dict[str, torch.Tensor]

from_dict

< >

( qs_dict: dict 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, 可选) — 由 quantize_blockwise 返回的量化状态。如果未提供 absmax,则为必需。
  • absmax (torch.Tensor, 可选) — 包含缩放值的张量。如果未提供 quant_state,则为必需,否则将被忽略。
  • code (torch.Tensor, 可选) — 描述低位数据类型的映射。默认为有符号 8 位动态类型。更多细节,请参见《深度学习中并行计算的 8 位近似》[https://arxiv.org/abs/1511.04561]。当提供 quant_state 时,此参数将被忽略。
  • out (torch.Tensor, 可选) — 用于存储结果的张量。
  • blocksize (int, 可选) — 块的大小。默认为 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) — 输入张量。支持 float16bfloat16float32 数据类型。
  • code (torch.Tensor, 可选) — 描述低位数据类型的映射。默认为有符号 8 位动态类型。更多细节,请参见《深度学习中并行计算的 8 位近似》[https://arxiv.org/abs/1511.04561]。
  • absmax (torch.Tensor, 可选) — 用于存储 absmax 值的张量。
  • out (torch.Tensor, 可选) — 用于存储结果的张量。
  • blocksize (int, 可选) — 块的大小。默认为 4096。有效值为 64、128、256、512、1024、2048 和 4096。
  • nested (bool, 可选) — 是否对 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]

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

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

< > 在 GitHub 上更新