Transformers 文件
BitNet
並獲得增強的文件體驗
開始使用
BitNet
概述
該模型在 4 萬億個 token 的語料庫上進行訓練，證明了原生的 1-bit LLM 能夠達到與同等規模領先的開源全精度模型相當的效能，同時在計算效率（記憶體、能耗、延遲）方面具有顯著優勢。
➡️ 技術報告： BitNet b1.58 2B4T 技術報告
➡️ 官方推理程式碼： microsoft/BitNet (bitnet.cpp)
模型變體
Hugging Face 上提供了多個版本的模型權重
microsoft/bitnet-b1.58-2B-4T：包含為高效推理而最佳化的打包 1.58 位權重。請用於部署。microsoft/bitnet-b1.58-2B-4T-bf16：包含 BF16 格式的主權重。僅用於訓練或微調目的。microsoft/bitnet-b1.58-2B-4T-gguf：包含 GGUF 格式的模型權重，與用於 CPU 推理的bitnet.cpp庫相容。
模型詳情
- 架構： 基於 Transformer，使用
BitLinear層（BitNet 框架）進行了修改。- 使用旋轉位置嵌入 (RoPE)。
- 在 FFN 層中使用平方 ReLU (ReLU²) 啟用函式。
- 採用
subln歸一化。 - 線性層或歸一化層中沒有偏置項。
- 量化： 原生 1.58 位權重和 8 位啟用 (W1.58A8)。
- 在前向傳播過程中，使用 absmean 量化將權重 量化為三元值 {-1, 0, +1}。
- 使用 absmax 量化（逐個 token）將啟用量化為 8 位整數。
- 至關重要的是，該模型是使用此量化方案從頭開始訓練的，而不是訓練後量化。
- 引數： 約 20 億
- 訓練 Token 數： 4 萬億
- 上下文長度： 最大序列長度為 4096 個 token。
- 建議： 為了在需要很長上下文的任務（超出預訓練長度或用於專門的長推理任務）上獲得最佳效能，我們建議在最終微調階段之前進行中間的長序列適應/訓練。
- 訓練階段
- 預訓練： 使用兩階段學習率和權重衰減計劃，對公共文字/程式碼和合成數學資料進行大規模訓練。
- 監督微調 (SFT)： 使用總和損失聚合和特定的超引數調整，在指令遵循和對話資料上進行微調。
- 直接偏好最佳化 (DPO)： 使用偏好對與人類偏好對齊。
- 分詞器： LLaMA 3 分詞器（詞彙表大小：128,256）。
使用技巧
關於效率的非常重要的說明
在使用標準 `transformers` 庫執行此模型時，請不要期望獲得性能效率上的提升（在速度、延遲或能耗方面）。
`transformers` 內部當前的執行路徑不包含利用 BitNet 架構優勢所需的專門、高度最佳化的計算核心。透過 `transformers` 執行此模型可能會導致推理速度和能耗與此框架內的標準全精度模型相當，甚至可能更差，無論是在 CPU 還是 GPU 上。
雖然由於量化權重您可能會觀察到記憶體使用量減少，但主要的計算效率優勢無法透過這種標準的 `transformers` 使用路徑獲得。
要實現技術報告中展示的效率優勢，您必須使用專用的 C++ 實現：bitnet.cpp。
環境要求
pip install transformers
示例
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
model_id = "microsoft/bitnet-b1.58-2B-4T"
# Load tokenizer and model
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
model_id,
torch_dtype=torch.bfloat16
)
# Apply the chat template
messages = [
{"role": "system", "content": "You are a helpful AI assistant."},
{"role": "user", "content": "How are you?"},
]
chat_input = tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_tensors="pt").to(model.device)
# Generate response
chat_outputs = model.generate(chat_input, max_new_tokens=50)
response = tokenizer.decode(chat_outputs[0][chat_input.shape[-1]:], skip_special_tokens=True) # Decode only the response part
print("\nAssistant Response:", response)BitNetConfig
class transformers.BitNetConfig
< 來源 >( vocab_size = 128256 hidden_size = 2560 intermediate_size = 6912 num_hidden_layers = 30 num_attention_heads = 20 num_key_value_heads = 5 hidden_act = 'relu2' max_position_embeddings = 2048 initializer_range = 0.02 rms_norm_eps = 1e-05 use_cache = True pad_token_id = None bos_token_id = 128000 eos_token_id = 128001 tie_word_embeddings = False rope_theta = 500000.0 attention_bias = False attention_dropout = 0.0 **kwargs )
引數
- vocab_size (
int, 可選, 預設為 128256) — BitNet 模型的詞彙表大小。定義了呼叫 BitNetModel 時傳入的inputs_ids可以表示的不同 token 的數量。 - hidden_size (
int, 可選, 預設為 2560) — 隱藏表示的維度。 - intermediate_size (
int, 可選, 預設為 6912) — MLP 表示的維度。 - num_hidden_layers (
int, 可選, 預設為 30) — Transformer 解碼器中的隱藏層數量。 - num_attention_heads (
int, 可選, 預設為 20) — Transformer 解碼器中每個注意力層的注意力頭數量。 - num_key_value_heads (
int, 可選, 預設為 5) — 這是實現分組查詢注意力 (Grouped Query Attention) 時應使用的鍵值頭 (key_value heads) 的數量。如果num_key_value_heads=num_attention_heads，模型將使用多頭注意力 (MHA)；如果num_key_value_heads=1，模型將使用多查詢注意力 (MQA)；否則將使用 GQA。當將一個多頭檢查點轉換為 GQA 檢查點時，每個分組的鍵和值頭應透過對該組內所有原始頭進行均值池化來構建。更多詳情，請檢視[這篇論文](https://huggingface.co/papers/2305.13245)。如果未指定，將預設為num_attention_heads。 - hidden_act (
str或function, 可選, 預設為"relu2") — 解碼器中的非線性啟用函式（函式或字串）。 - max_position_embeddings (
int, 可選, 預設為 2048) — 該模型可能使用的最大序列長度。 - initializer_range (
float, 可選, 預設為 0.02) — 用於初始化所有權重矩陣的 truncated_normal_initializer 的標準差。 - rms_norm_eps (
float, 可選, 預設為 1e-05) — rms 歸一化層使用的 epsilon 值。 - use_cache (
bool, 可選, 預設為True) — 模型是否應返回最後一個鍵/值注意力（並非所有模型都使用）。僅當config.is_decoder=True時相關。 - pad_token_id (
int, 可選) — 填充 token 的 id。 - bos_token_id (
int, 可選, 預設為 128000) — 序列開始 token 的 id。 - eos_token_id (
int, 可選, 預設為 128001) — 序列結束 token 的 id。 - tie_word_embeddings (
bool, 可選, 預設為False) — 是否繫結詞嵌入權重 - rope_theta (
float, optional, 預設為 500000.0) — RoPE 嵌入的基礎週期。 - attention_bias (
bool, optional, 預設為False) — 是否在自注意力機制的查詢、鍵、值和輸出投影層中使用偏置。 - attention_dropout (
float, optional, 預設為 0.0) — 注意力機率的 dropout 比率。
這是一個用於儲存 BitNetModel 配置的配置類。它用於根據指定的引數例項化一個 BitNet 模型，定義模型架構。使用預設值例項化配置將產生與 BitNet b1.58 2B4T microsoft/bitnet-b1.58-2B-4T 相似的配置。
配置物件繼承自 PretrainedConfig，可用於控制模型輸出。有關更多資訊，請閱讀 PretrainedConfig 的文件。
>>> from transformers import BitNetModel, BitNetConfig
>>> # Initializing a BitNet style configuration
>>> configuration = BitNetConfig()
>>> # Initializing a model from the BitNet style configuration
>>> model = BitNetModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configBitNetModel
class transformers.BitNetModel
< source >( config: BitNetConfig )
引數
- config (BitNetConfig) — 包含模型所有引數的模型配置類。使用配置檔案初始化不會載入與模型相關的權重，只會載入配置。請檢視 from_pretrained() 方法來載入模型權重。
裸的 Bitnet 模型，輸出原始的隱藏狀態，頂部沒有任何特定的頭。
該模型繼承自 PreTrainedModel。請檢視超類的文件，瞭解該庫為其所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
該模型也是 PyTorch torch.nn.Module 的子類。可以像常規 PyTorch 模組一樣使用它，並參考 PyTorch 文件瞭解所有與通用用法和行為相關的事項。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Optional[transformers.cache_utils.Cache] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None cache_position: typing.Optional[torch.LongTensor] = None **flash_attn_kwargs: typing_extensions.Unpack[transformers.modeling_flash_attention_utils.FlashAttentionKwargs] ) → transformers.modeling_outputs.BaseModelOutputWithPast 或 tuple(torch.FloatTensor)
引數
- input_ids (
torch.LongTensor，形狀為(batch_size, sequence_length)，可選) — 詞彙表中輸入序列標記的索引。預設情況下將忽略填充。可以使用 AutoTokenizer 獲取索引。有關詳細資訊，請參閱 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.Tensor，形狀為(batch_size, sequence_length)，可選) — 用於避免對填充標記索引執行注意力的掩碼。掩碼值選自[0, 1]：- 1 表示未被遮蔽的標記，
- 0 表示被遮蔽的標記。
- position_ids (
torch.LongTensor，形狀為(batch_size, sequence_length)，可選) — 位置嵌入中每個輸入序列標記的位置索引。選自範圍[0, config.n_positions - 1]。 - past_key_values (
~cache_utils.Cache，可選) — 預先計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於加速順序解碼。這通常包括在解碼的先前階段由模型返回的past_key_values，當use_cache=True或config.use_cache=True時。允許兩種格式：
- 一個 Cache 例項，請參閱我們的 kv 快取指南；
- 長度為
config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含 2 個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量。這也稱為舊版快取格式。
模型將輸出與輸入相同的快取格式。如果未傳遞
past_key_values，將返回舊版快取格式。如果使用
past_key_values，使用者可以選擇只輸入最後一個input_ids（那些沒有為其提供過去鍵值狀態的 ID），形狀為(batch_size, 1)，而不是所有形狀為(batch_size, sequence_length)的input_ids。 - inputs_embeds (
torch.FloatTensor，形狀為(batch_size, sequence_length, hidden_size)，可選) — 可選地，您可以選擇直接傳遞嵌入表示，而不是傳遞input_ids。如果您想比模型內部的嵌入查詢矩陣更好地控制如何將input_ids索引轉換為關聯向量，這將非常有用。 - use_cache (
bool，可選) — 如果設定為True，將返回past_key_values鍵值狀態，並可用於加速解碼（請參閱past_key_values）。 - output_attentions (
bool，可選) — 是否返回所有注意力層的注意力張量。有關詳細資訊，請參閱返回張量下的attentions。 - output_hidden_states (
bool，可選) — 是否返回所有層的隱藏狀態。有關詳細資訊，請參閱返回張量下的hidden_states。 - cache_position (
torch.LongTensor，形狀為(sequence_length)，可選) — 描繪輸入序列標記在序列中位置的索引。與position_ids相反，此張量不受填充影響。它用於在正確的位置更新快取並推斷完整的序列長度。
返回
transformers.modeling_outputs.BaseModelOutputWithPast 或 tuple(torch.FloatTensor)
一個 transformers.modeling_outputs.BaseModelOutputWithPast 或一個 `torch.FloatTensor` 元組（如果傳遞了 `return_dict=False` 或當 `config.return_dict=False` 時），根據配置（BitNetConfig）和輸入，包含各種元素。
-
last_hidden_state (
torch.FloatTensor, 形狀為(batch_size, sequence_length, hidden_size)) — 模型最後一層輸出的隱藏狀態序列。如果使用了
past_key_values，則只輸出形狀為(batch_size, 1, hidden_size)的序列的最後一個隱藏狀態。 -
past_key_values (
Cache，可選，當傳遞use_cache=True或config.use_cache=True時返回) — 這是一個 Cache 例項。有關更多詳細資訊，請參閱我們的 kv 快取指南。包含預先計算的隱藏狀態（自注意力塊中的鍵和值，如果 `config.is_encoder_decoder=True`，則還包括交叉注意力塊中的鍵和值），可用於（請參閱 `past_key_values` 輸入）加速順序解碼。
-
hidden_states (
tuple(torch.FloatTensor)，可選，當傳遞 `output_hidden_states=True` 或 `config.output_hidden_states=True` 時返回) — `torch.FloatTensor` 的元組（如果模型有嵌入層，則一個是嵌入的輸出，另一個是每層的輸出），形狀為 `(batch_size, sequence_length, hidden_size)`。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple(torch.FloatTensor)，可選，當傳遞 `output_attentions=True` 或 `config.output_attentions=True` 時返回) — `torch.FloatTensor` 的元組（每層一個），形狀為 `(batch_size, num_heads, sequence_length, sequence_length)`。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
BitNetModel 的 forward 方法，覆蓋了 `__call__` 特殊方法。
雖然前向傳遞的配方需要在此函式內定義，但之後應呼叫 `Module` 例項而不是此函式，因為前者會處理執行前處理和後處理步驟，而後者會靜默地忽略它們。
BitNetForCausalLM
class transformers.BitNetForCausalLM
< source >( config )
引數
- config (BitNetForCausalLM) — 包含模型所有引數的模型配置類。使用配置檔案初始化不會載入與模型相關的權重，只會載入配置。請檢視 from_pretrained() 方法來載入模型權重。
用於因果語言建模的 Bitnet 模型。
該模型繼承自 PreTrainedModel。請檢視超類的文件，瞭解該庫為其所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
該模型也是 PyTorch torch.nn.Module 的子類。可以像常規 PyTorch 模組一樣使用它，並參考 PyTorch 文件瞭解所有與通用用法和行為相關的事項。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Optional[transformers.cache_utils.Cache] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None labels: typing.Optional[torch.LongTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None cache_position: typing.Optional[torch.LongTensor] = None logits_to_keep: typing.Union[int, torch.Tensor] = 0 **kwargs: typing_extensions.Unpack[transformers.models.bitnet.modeling_bitnet.KwargsForCausalLM] ) → transformers.modeling_outputs.CausalLMOutputWithPast 或 tuple(torch.FloatTensor)
引數
- input_ids (
torch.LongTensor，形狀為(batch_size, sequence_length)，可選) — 詞彙表中輸入序列標記的索引。預設情況下將忽略填充。可以使用 AutoTokenizer 獲取索引。有關詳細資訊，請參閱 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.Tensor，形狀為(batch_size, sequence_length)，可選) — 用於避免對填充標記索引執行注意力的掩碼。掩碼值選自[0, 1]：- 1 表示未被遮蔽的標記，
- 0 表示被遮蔽的標記。
- position_ids (
torch.LongTensor，形狀為(batch_size, sequence_length)，可選) — 位置嵌入中每個輸入序列標記的位置索引。選自範圍[0, config.n_positions - 1]。 - past_key_values (
~cache_utils.Cache，可選) — 預先計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於加速順序解碼。這通常包括在解碼的先前階段由模型返回的past_key_values，當use_cache=True或config.use_cache=True時。允許兩種格式：
- 一個 Cache 例項，請參閱我們的 kv 快取指南；
- 長度為
config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含 2 個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量。這也稱為舊版快取格式。
模型將輸出與輸入相同的快取格式。如果未傳遞
past_key_values，將返回舊版快取格式。如果使用
past_key_values，使用者可以選擇只輸入最後一個input_ids（那些沒有為其提供過去鍵值狀態的 ID），形狀為(batch_size, 1)，而不是所有形狀為(batch_size, sequence_length)的input_ids。 - inputs_embeds (
torch.FloatTensor，形狀為(batch_size, sequence_length, hidden_size)，可選) — 可選地，您可以選擇直接傳遞嵌入表示，而不是傳遞input_ids。如果您想比模型內部的嵌入查詢矩陣更好地控制如何將input_ids索引轉換為關聯向量，這將非常有用。 - labels (
torch.LongTensor，形狀為(batch_size, sequence_length)，可選) — 用於計算掩碼語言建模損失的標籤。索引應在[0, transformers., config.vocab_size]或 -100 之間（請參閱input_ids文件字串）。索引設定為-100的標記將被忽略（遮蔽），損失僅對標籤在[0, transformers., config.vocab_size]中的標記計算。 - use_cache (
bool，可選) — 如果設定為True，將返回past_key_values鍵值狀態，並可用於加速解碼（請參閱past_key_values）。 - output_attentions (
bool，可選) — 是否返回所有注意力層的注意力張量。有關詳細資訊，請參閱返回張量下的attentions。 - output_hidden_states (
bool，可選) — 是否返回所有層的隱藏狀態。有關詳細資訊，請參閱返回張量下的hidden_states。 - cache_position (
torch.LongTensor，形狀為(sequence_length)，可選) — 描繪輸入序列標記在序列中位置的索引。與position_ids相反，此張量不受填充影響。它用於在正確的位置更新快取並推斷完整的序列長度。 - logits_to_keep (
Union[int, torch.Tensor]，預設為0) — 如果是int，則為最後logits_to_keep個標記計算 logits。如果是0，則為所有input_ids計算 logits（特殊情況）。生成時只需要最後一個標記的 logits，僅為該標記計算可以節省記憶體，這對於長序列或大詞彙量來說非常重要。如果是torch.Tensor，則必須是一維的，對應於序列長度維度中要保留的索引。當使用打包張量格式（批處理和序列長度使用單一維度）時，這非常有用。
返回
transformers.modeling_outputs.CausalLMOutputWithPast 或 tuple(torch.FloatTensor)
一個 transformers.modeling_outputs.CausalLMOutputWithPast 或一個 `torch.FloatTensor` 元組（如果傳遞了 `return_dict=False` 或當 `config.return_dict=False` 時），根據配置（BitNetConfig）和輸入，包含各種元素。
-
loss (
torch.FloatTensor形狀為(1,)，可選，當提供labels時返回) — 語言建模損失（用於下一個 token 預測）。 -
logits (形狀為
(batch_size, sequence_length, config.vocab_size)的torch.FloatTensor) — 語言建模頭部的預測分數（SoftMax 之前的每個詞彙標記的分數）。 -
past_key_values (
Cache，可選，當傳遞use_cache=True或config.use_cache=True時返回) — 這是一個 Cache 例項。有關更多詳細資訊，請參閱我們的 kv 快取指南。包含預計算的隱藏狀態（自注意力塊中的鍵和值），可用於（參見
past_key_values輸入）加速順序解碼。 -
hidden_states (
tuple(torch.FloatTensor)，可選，當傳遞 `output_hidden_states=True` 或 `config.output_hidden_states=True` 時返回) — `torch.FloatTensor` 的元組（如果模型有嵌入層，則一個是嵌入的輸出，另一個是每層的輸出），形狀為 `(batch_size, sequence_length, hidden_size)`。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple(torch.FloatTensor)，可選，當傳遞 `output_attentions=True` 或 `config.output_attentions=True` 時返回) — `torch.FloatTensor` 的元組（每層一個），形狀為 `(batch_size, num_heads, sequence_length, sequence_length)`。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
BitNetForCausalLM 的 forward 方法，覆蓋了 `__call__` 特殊方法。
雖然前向傳遞的配方需要在此函式內定義，但之後應呼叫 `Module` 例項而不是此函式，因為前者會處理執行前處理和後處理步驟，而後者會靜默地忽略它們。
示例
>>> from transformers import AutoTokenizer, BitNetForCausalLM
>>> model = BitNetForCausalLM.from_pretrained("microsoft/bitnet-b1.58-2B-4T")
>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/bitnet-b1.58-2B-4T")
>>> prompt = f'<|begin_of_text|>User: Hey, are you conscious? Can you talk to me?<|eot_id|>Assistant: '
>>> inputs = tokenizer(prompt, return_tensors="pt")
>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=100)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"User: Hey, are you conscious? Can you talk to me?Assistant: No, I'm not conscious. I'm an artificial intelligence designed to assist with information and tasks. How can I help you today?"