Trainer 的工具

本頁列出了 Trainer 使用的所有實用函式。

其中大部分僅在您研究庫中 Trainer 的程式碼時才有用。

工具

class transformers.EvalPrediction

( predictions: typing.Union[numpy.ndarray, tuple[numpy.ndarray]] label_ids: typing.Union[numpy.ndarray, tuple[numpy.ndarray]] inputs: typing.Union[numpy.ndarray, tuple[numpy.ndarray], NoneType] = None losses: typing.Union[numpy.ndarray, tuple[numpy.ndarray], NoneType] = None )

引數

predictions (np.ndarray) — 模型的預測。
label_ids (np.ndarray) — 要匹配的目標。
inputs (np.ndarray, 可選) — 傳遞給模型的輸入資料。
losses (np.ndarray, 可選) — 評估期間計算的損失值。

評估輸出（始終包含標籤），用於計算指標。

class transformers.IntervalStrategy

< 來源 >

( value names = None module = None qualname = None type = None start = 1 )

一個列舉。

transformers.enable_full_determinism

< 來源 >

( seed: int warn_only: bool = False )

分散式訓練期間可重現行為的輔助函式。請參閱

https://pytorch.org/docs/stable/notes/randomness.html (pytorch)
https://www.tensorflow.org/api_docs/python/tf/config/experimental/enable_op_determinism (tensorflow)

transformers.set_seed

< 來源 >

( seed: int deterministic: bool = False )

引數

seed (int) — 要設定的種子。
deterministic (bool, 可選, 預設為 False) — 是否在可用時使用確定性演算法。可能會減慢訓練速度。

用於在 random、numpy、torch 和/或 tf（如果已安裝）中設定種子的可重現行為的輔助函式。

transformers.torch_distributed_zero_first

< 來源 >

( local_rank: int )

引數

local_rank (int) — 本地程序的等級。

分散式訓練中，使所有程序等待每個本地主程序執行某些操作的裝飾器。

回撥內部

class transformers.trainer_callback.CallbackHandler

< 來源 >

( callbacks model processing_class optimizer lr_scheduler )

僅按順序呼叫回撥列表的內部類。

分散式評估

class transformers.trainer_pt_utils.DistributedTensorGatherer

< 來源 >

( world_size num_samples make_multiple_of = None padding_index = -100 )

引數

world_size (int) — 分散式訓練中使用的程序數。
num_samples (int) — 資料集中的樣本數量。
make_multiple_of (int, 可選) — 如果傳遞此引數，則假定傳遞給每個程序的資料集是此引數的倍數（透過新增樣本）。
padding_index (int, 可選, 預設為 -100) — 如果陣列的序列長度不一致，則使用的填充索引。

一個負責透過分塊在 CPU 上正確收集張量（或張量的巢狀列表/元組）的類。

如果我們的資料集有 16 個樣本，在 3 個程序上批次大小為 2，並且我們每一步都收集然後傳輸到 CPU，我們的取樣器將生成以下索引

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 0, 1]

以獲得大小為 3 的倍數（以便每個程序獲得相同的資料集長度）。然後程序 0、1 和 2 將負責對以下樣本進行預測

P0: [0, 1, 2, 3, 4, 5]
P1: [6, 7, 8, 9, 10, 11]
P2: [12, 13, 14, 15, 0, 1]

每個程序處理的第一個批次將是

P0: [0, 1]
P1: [6, 7]
P2: [12, 13]

因此，如果我們在第一個批次結束時進行收集，我們將得到一個對應於以下索引的張量（張量的巢狀列表/元組）

[0, 1, 6, 7, 12, 13]

如果我們在不採取任何預防措施的情況下直接連線我們的結果，使用者將在預測迴圈結束時以這種順序獲得這些索引的預測

[0, 1, 6, 7, 12, 13, 2, 3, 8, 9, 14, 15, 4, 5, 10, 11, 0, 1]

出於某種原因，這並不能滿足他們的需求。這個類就是為了解決這個問題。

add_arrays

< 來源 >

( arrays )

將 arrays 新增到內部儲存中。將在第一次傳遞陣列時將儲存初始化為完整大小，以便如果註定要發生 OOM，則會在開始時發生。

finalize

< 來源 >

( )

返回正確收集的陣列，並截斷為樣本數量（因為取樣器添加了一些額外的樣本以使每個程序的資料集長度相同）。

Trainer 引數解析器

class transformers.HfArgumentParser

< 來源 >

( dataclass_types: typing.Union[transformers.hf_argparser.DataClassType, collections.abc.Iterable[transformers.hf_argparser.DataClassType], NoneType] = None **kwargs )

引數

dataclass_types (DataClassType 或 Iterable[DataClassType], 可選) — 資料類型別，或資料類型別列表，我們將用解析的引數“填充”例項。
kwargs (dict[str, Any], 可選) — 以常規方式傳遞給 argparse.ArgumentParser()。

argparse.ArgumentParser 的這個子類使用資料類上的型別提示來生成引數。

該類旨在與本機 argparse 良好配合。特別是，您可以在初始化後向解析器新增更多（非資料類支援的）引數，並且在解析後您將以附加名稱空間的形式獲得輸出。可選：要建立子引數組，請在資料類中使用 _argument_group_name 屬性。

parse_args_into_dataclasses

< 來源 >

( args = None return_remaining_strings = False look_for_args_file = True args_filename = None args_file_flag = None ) → 包含以下內容的元組：

引數

args — 要解析的字串列表。預設值取自 sys.argv。（與 argparse.ArgumentParser 相同）
return_remaining_strings — 如果為 true，還返回剩餘引數字串的列表。
look_for_args_file — 如果為 true，將查詢與此程序的入口點指令碼同名的“.args”檔案，並將其潛在內容附加到命令列引數。
args_filename — 如果不是 None，將使用此檔案而不是前一個引數中指定的“.args”檔案。
args_file_flag — 如果不是 None，將在命令列引數中查詢用此標誌指定的檔案。該標誌可以指定多次，優先順序由順序決定（最後一個獲勝）。

包含以下內容的元組：

資料類例項，順序與傳遞給初始化器時的順序相同。
如果適用，一個額外的名稱空間，用於在初始化後新增到解析器的更多（非資料類支援的）引數。
剩餘引數字串的潛在列表。（與 argparse.ArgumentParser.parse_known_args 相同）

將命令列引數解析為指定資料類型別的例項。

這依賴於 argparse 的 ArgumentParser.parse_known_args。請參閱文件：docs.python.org/3.7/library/argparse.html#argparse.ArgumentParser.parse_args

parse_dict

< 來源 >

( args: dict allow_extra_keys: bool = False ) → 包含以下內容的元組：

引數

args (dict) — 包含配置值的字典
allow_extra_keys (bool, 可選, 預設為 False) — 預設為 False。如果為 False，則如果字典包含未解析的鍵，將引發異常。

包含以下內容的元組：

資料類例項，順序與傳遞給初始化器時的順序相同。

不使用 argparse 的替代輔助方法，而是使用字典填充資料類型別。

parse_json_file

< 來源 >

( json_file: typing.Union[str, os.PathLike] allow_extra_keys: bool = False ) → 包含以下內容的元組：

引數

json_file (str 或 os.PathLike) — 要解析的 json 檔名
allow_extra_keys (bool, 可選, 預設為 False) — 預設為 False。如果為 False，則如果 json 檔案包含未解析的鍵，將引發異常。

包含以下內容的元組：

資料類例項，順序與傳遞給初始化器時的順序相同。

不使用 argparse 的替代輔助方法，而是載入 json 檔案並填充資料類型別。

parse_yaml_file

< 來源 >

( yaml_file: typing.Union[str, os.PathLike] allow_extra_keys: bool = False ) → 包含以下內容的元組：

引數

yaml_file (str 或 os.PathLike) — 要解析的 yaml 檔名
allow_extra_keys (bool, 可選, 預設為 False) — 預設為 False。如果為 False，則如果 json 檔案包含未解析的鍵，將引發異常。

包含以下內容的元組：

資料類例項，順序與傳遞給初始化器時的順序相同。

不使用 argparse 的替代輔助方法，而是載入 yaml 檔案並填充資料類型別。

除錯工具

class transformers.debug_utils.DebugUnderflowOverflow

< 來源 >

( model max_frames_to_save = 21 trace_batch_nums = [] abort_after_batch_num = None )

引數

model (nn.Module) — 要除錯的模型。
max_frames_to_save (int, 可選, 預設為21) — 記錄多少幀
trace_batch_nums(list[int], 可選, 預設為[]) — 要跟蹤的批次號（關閉檢測）
abort_after_batch_num (`int`, 可選) — 是否在某個批次號完成後中止

這個除錯類有助於檢測和理解模型何時開始變得非常大或非常小，更重要的是檢測nan或inf權重和啟用元素。

有兩種工作模式

下溢/上溢檢測（預設）
特定批次的絕對最小值/最大值跟蹤（不帶檢測）

模式1：下溢/上溢檢測

要啟用下溢/上溢檢測，請使用模型初始化物件

debug_overflow = DebugUnderflowOverflow(model)

然後像往常一樣執行訓練，如果至少一個權重、輸入或輸出元素中檢測到nan或inf，此模組將丟擲異常並列印導致此事件的max_frames_to_save幀，每幀報告：

執行forward的完全限定模組名加上類名
每個模組權重以及輸入和輸出的所有元素的絕對最小值和最大值

例如，這是在fp16中執行google/mt5-small混合精度時檢測報告的標題和最後幾幀

混合精度

Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata
[...]
                  encoder.block.2.layer.1.DenseReluDense.wi_0 Linear
2.17e-07 4.50e+00 weight
1.79e-06 4.65e+00 input[0]
2.68e-06 3.70e+01 output
                  encoder.block.2.layer.1.DenseReluDense.wi_1 Linear
8.08e-07 2.66e+01 weight
1.79e-06 4.65e+00 input[0]
1.27e-04 2.37e+02 output
                  encoder.block.2.layer.1.DenseReluDense.wo Linear
1.01e-06 6.44e+00 weight
0.00e+00 9.74e+03 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense
1.79e-06 4.65e+00 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.dropout Dropout
3.18e-04 6.27e+04 input[0]
0.00e+00      inf output

你可以在這裡看到，T5DenseGatedGeluDense.forward產生的輸出啟用的絕對最大值約為62.7K，這非常接近fp16的上限64K。在下一幀中，我們有Dropout，它在將一些元素歸零後重新規範化權重，這將絕對最大值推高到超過64K，從而導致溢位。

如你所見，當數字開始變得非常大（對於fp16數字）時，我們需要檢視之前的幀。

跟蹤是在前向鉤子中完成的，該鉤子在forward完成後立即呼叫。

預設情況下，列印最後21幀。你可以根據需要更改預設值。例如：

debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)

為了驗證你是否正確設定了此除錯功能，並且你打算在可能需要數小時才能完成的訓練中使用它，請首先在啟用正常跟蹤的情況下執行它，用於少量批次，如下一節所述。

模式2. 特定批次的絕對最小值/最大值跟蹤（不帶檢測）

第二種工作模式是每批次跟蹤，並關閉下溢/上溢檢測功能。

假設你想觀察每個forward呼叫的所有元素的絕對最小值和最大值，

並且只對批次1和3執行此操作。然後你可以將此類別例項化為：

debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3])

現在將使用與上面解釋的相同格式跟蹤批次1和3。批次是從0開始索引的。

如果已知程式在某個批次號之後開始出現異常，這會很有幫助，你可以直接快進到該區域。

提前停止

你還可以指定在哪個批次號之後停止訓練，使用：

debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3)

此功能主要在跟蹤模式下有用，但你可以在任何模式下使用它。

效能:

由於此模組在每次前向傳播時都會測量模型每個權重的絕對min/max，因此會減慢訓練速度。因此，一旦除錯需求得到滿足，請記住將其關閉。

< > 在 GitHub 上更新

Transformers

Trainer 的工具

工具

class transformers.EvalPrediction

class transformers.IntervalStrategy

transformers.enable_full_determinism

transformers.set_seed

transformers.torch_distributed_zero_first

回撥內部

class transformers.trainer_callback.CallbackHandler

分散式評估

class transformers.trainer_pt_utils.DistributedTensorGatherer

add_arrays

finalize

Trainer 引數解析器

class transformers.HfArgumentParser

parse_args_into_dataclasses

parse_dict

parse_json_file

parse_yaml_file

除錯工具

class transformers.debug_utils.DebugUnderflowOverflow