Transformers 文件
回撥
並獲得增強的文件體驗
開始使用
回撥函式
回撥函式是能夠自定義 PyTorch Trainer 中訓練迴圈行為的物件（此功能尚未在 TensorFlow 中實現），它可以檢查訓練迴圈狀態（用於進度報告、在 TensorBoard 或其他 ML 平臺上記錄日誌……）並做出決策（如提前停止）。
回撥函式是“只讀”的程式碼片段，除了它們返回的 TrainerControl 物件外，它們不能改變訓練迴圈中的任何內容。對於需要改變訓練迴圈的自定義，您應該子類化 Trainer 並覆蓋您需要的方法（參閱 訓練器 以獲取示例）。
預設情況下，`TrainingArguments.report_to` 設定為 `"all"`，因此 Trainer 將使用以下回調函式。
- DefaultFlowCallback，它處理日誌記錄、儲存和評估的預設行為。
- PrinterCallback 或 ProgressCallback 用於顯示進度並列印日誌（如果您透過 TrainingArguments 停用 tqdm，則使用第一個，否則使用第二個）。
- 如果 TensorBoard 可訪問（透過 PyTorch >= 1.4 或 tensorboardX），則使用 TensorBoardCallback。
- 如果安裝了 wandb，則使用 WandbCallback。
- 如果安裝了 comet_ml，則使用 CometCallback。
- 如果安裝了 mlflow，則使用 MLflowCallback。
- 如果安裝了 neptune，則使用 NeptuneCallback。
- 如果安裝了 azureml-sdk，則使用 AzureMLCallback。
- 如果安裝了 codecarbon，則使用 CodeCarbonCallback。
- 如果安裝了 clearml，則使用 ClearMLCallback。
- 如果安裝了 dagshub，則使用 DagsHubCallback。
- 如果安裝了 flyte，則使用 FlyteCallback。
- 如果安裝了 dvclive，則使用 DVCLiveCallback。
- 如果安裝了 swanlab，則使用 SwanLabCallback。
如果已安裝某個包，但您不想使用隨附的整合，您可以將 `TrainingArguments.report_to` 更改為僅包含您要使用的整合的列表（例如，`["azure_ml", "wandb"]`）。
實現回撥函式的主要類是 TrainerCallback。它獲取用於例項化 Trainer 的 TrainingArguments，可以透過 TrainerState 訪問該 Trainer 的內部狀態，並且可以透過 TrainerControl 對訓練迴圈執行一些操作。
可用回撥函式
以下是庫中可用的 TrainerCallback 列表
一個將日誌傳送到 Comet ML 的 TrainerCallback。
設定可選的 Comet 整合。
環境
- COMET_MODE (
str, 可選，預設為get_or_create)：控制是建立並記錄到新的 Comet 實驗還是附加到現有實驗。它接受以下值get_or_create：根據是否設定了 `COMET_EXPERIMENT_KEY` 以及該鍵的實驗是否存在自動決定。create：始終建立一個新的 Comet 實驗。get：始終嘗試附加到現有 Comet 實驗。需要設定 `COMET_EXPERIMENT_KEY`。ONLINE：**已棄用**，用於建立線上實驗。請改用 `COMET_START_ONLINE=1`。OFFLINE：**已棄用**，用於建立離線實驗。請改用 `COMET_START_ONLINE=0`。DISABLED：**已棄用**，用於停用 Comet 日誌記錄。請改用 `--report_to` 標誌來控制用於記錄結果的整合。
- COMET_PROJECT_NAME (
str, 可選)：Comet 實驗的專案名稱。 - COMET_LOG_ASSETS (
str, 可選，預設為TRUE)：是否將訓練資產（tf 事件日誌、檢查點等）記錄到 Comet。可以是TRUE或FALSE。
有關環境中可配置項的數量，請參閱此處。
一個 TrainerCallback，用於處理日誌、評估和檢查點的預設訓練迴圈流。
一個只打印日誌的 TrainerCallback。
一個 TrainerCallback，顯示訓練或評估的進度。您可以修改 `max_str_len` 來控制日誌記錄時字串截斷的長度。
class transformers.EarlyStoppingCallback
< 源 >( early_stopping_patience: int = 1 early_stopping_threshold: typing.Optional[float] = 0.0 )
一個處理提前停止的 TrainerCallback。
此回撥函式依賴於 TrainingArguments 引數 *load_best_model_at_end* 功能，用於設定 TrainerState 中的 best_metric。請注意，如果 TrainingArguments 引數 *save_steps* 與 *eval_steps* 不同，則提前停止不會發生，直到下一個儲存步驟。
class transformers.integrations.TensorBoardCallback
< 源 >( tb_writer = None )
一個將日誌傳送到 TensorBoard 的 TrainerCallback。
一個將指標、媒體、模型檢查點記錄到 Weight and Biases 的 TrainerCallback。
設定可選的 Weights & Biases (wandb) 整合。
可以子類化並重寫此方法以根據需要自定義設定。欲瞭解更多資訊，請參閱此處。您還可以覆蓋以下環境變數
環境
WANDB_LOG_MODEL (
str, 可選, 預設為"false")：是否在訓練期間記錄模型和檢查點。可以是"end","checkpoint"或"false"。如果設定為"end"，模型將在訓練結束時上傳。如果設定為"checkpoint"，檢查點將每args.save_steps上傳一次。如果設定為"false"，模型將不會上傳。與load_best_model_at_end()一起使用以上傳最佳模型。5.0 版本中已棄用
在 🤗 Transformers 的 5.0 版本中，將
WANDB_LOG_MODEL設定為bool將被棄用。WANDB_WATCH (
str, 可選，預設為"false")：可以是"gradients","all","parameters"或"false"。設定為"all"以記錄梯度和引數。WANDB_PROJECT (
str, 可選，預設為"huggingface")：將其設定為自定義字串以將結果儲存在不同的專案中。WANDB_DISABLED (
bool, 可選，預設為False)：是否完全停用 wandb。設定為 `WANDB_DISABLED=true` 以停用。
一個將日誌傳送到 MLflow 的 TrainerCallback。可以透過設定環境變數 `DISABLE_MLFLOW_INTEGRATION = TRUE` 來停用。
設定可選的 MLflow 整合。
環境
- HF_MLFLOW_LOG_ARTIFACTS (
str, 可選)：是否使用 MLflow `log_artifact()` 功能記錄工件。這僅在記錄到遠端伺服器（例如 s3 或 GCS）時才有意義。如果設定為 `True` 或 *1*，則在 TrainingArguments 的 `output_dir` 中每次儲存時將每個儲存的檢查點複製到本地或遠端工件儲存。在沒有遠端儲存的情況下使用它只會將檔案複製到您的工件位置。 - MLFLOW_TRACKING_URI (
str, 可選)：是否將執行儲存在特定路徑或遠端伺服器。預設情況下未設定，這將完全跳過設定跟蹤 URI。 - MLFLOW_EXPERIMENT_NAME (
str, 可選, 預設為None)：是否使用 MLflow 實驗名稱來啟動執行。預設為None，這將指向 MLflow 中的 `Default` 實驗。否則，它是要啟用的實驗的區分大小寫名稱。如果不存在具有此名稱的實驗，則會建立一個具有此名稱的新實驗。 - MLFLOW_TAGS (
str, 可選)：鍵/值對字典的字串轉儲，將作為標籤新增到 MLflow 執行中。示例：`os.environ['MLFLOW_TAGS']='{"release.candidate": "RC1", "release.version": "2.2.0"}'`。 - MLFLOW_NESTED_RUN (
str, 可選)：是否使用 MLflow 巢狀執行。如果設定為True或 *1*，將在當前執行中建立一個巢狀執行。 - MLFLOW_RUN_ID (
str, 可選)：允許重新連線到現有執行，這在從檢查點恢復訓練時很有用。當設定了 `MLFLOW_RUN_ID` 環境變數時，`start_run` 嘗試恢復具有指定執行 ID 的執行，其他引數將被忽略。 - MLFLOW_FLATTEN_PARAMS (
str, 可選，預設為False)：是否在記錄之前展平引數字典。 - MLFLOW_MAX_LOG_PARAMS (
int, 可選)：設定在執行中記錄的最大引數數量。
一個將日誌傳送到 AzureML 的 TrainerCallback。
一個追蹤訓練過程中二氧化碳排放量的 TrainerCallback。
class transformers.integrations.NeptuneCallback
< 源 >( api_token: typing.Optional[str] = None project: typing.Optional[str] = None name: typing.Optional[str] = None base_namespace: str = 'finetuning' run = None log_parameters: bool = True log_checkpoints: typing.Optional[str] = None **neptune_run_kwargs )
引數
- api_token (
str, 可選) — 註冊時獲取的 Neptune API 令牌。如果您已將令牌儲存到 `NEPTUNE_API_TOKEN` 環境變數中（強烈推薦），則可以省略此引數。請參閱文件中的完整設定說明。 - project (
str, 可選) — 現有 Neptune 專案的名稱，格式為“workspace-name/project-name”。您可以在 Neptune 的專案設定 -> 屬性中找到並複製該名稱。如果為 None（預設），則使用 `NEPTUNE_PROJECT` 環境變數的值。 - name (
str, 可選) — 執行的自定義名稱。 - base_namespace (
str, 可選, 預設為“finetuning”) — 在 Neptune 執行中，將包含回撥函式記錄的所有元資料的根名稱空間。 - log_parameters (
bool, 可選, 預設為True) — 如果為 True，則記錄 Trainer 提供的所有 Trainer 引數和模型引數。 - log_checkpoints (
str, 可選) — 如果為“same”，則在 Trainer 儲存檢查點時上傳檢查點。如果為“last”，則僅上傳最近儲存的檢查點。如果為“best”，則上傳最佳檢查點（Trainer 儲存的檢查點中）。如果為 `None`，則不上傳檢查點。 - run (
Run, 可選) — 如果您想繼續記錄到現有執行，請傳入一個 Neptune 執行物件。有關恢復執行的更多資訊，請參閱文件。 - **neptune_run_kwargs (可選) — 在建立新執行時直接傳遞給
neptune.init_run()函式的其他關鍵字引數。
將日誌傳送到 Neptune 的 TrainerCallback。
有關說明和示例，請參閱 Neptune 文件中的Transformers 整合指南。
一個將日誌傳送到 ClearML 的 TrainerCallback。
環境
- CLEARML_PROJECT (
str, 可選，預設為HuggingFace Transformers)：ClearML 專案名稱。 - CLEARML_TASK (
str, 可選，預設為Trainer)：ClearML 任務名稱。 - CLEARML_LOG_MODEL (
bool, 可選，預設為False)：是否在訓練期間將模型記錄為工件。
一個將日誌記錄到 DagsHub 的 TrainerCallback。繼承自 `MLflowCallback`
設定 DagsHub 的日誌整合。
環境
- HF_DAGSHUB_LOG_ARTIFACTS (
str, 可選)：是否儲存實驗的資料和模型工件。預設為 `False`。
class transformers.integrations.FlyteCallback
< 源 >( save_log_history: bool = True sync_checkpoints: bool = True )
一個將日誌傳送到 Flyte 的 TrainerCallback。注意：此回撥函式僅在 Flyte 任務中有效。
class transformers.integrations.DVCLiveCallback
< 源 >( live: typing.Optional[typing.Any] = None log_model: typing.Union[typing.Literal['all'], bool, NoneType] = None **kwargs )
引數
- live (
dvclive.Live, 可選, 預設為None) — 可選的 Live 例項。如果為 None，將使用 **kwargs 建立一個新例項。 - log_model (Union[Literal[“all”], bool], 可選, 預設為
None) — 是否使用dvclive.Live.log_artifact()記錄由 Trainer 建立的檢查點。如果設定為True，最終檢查點將在訓練結束時記錄。如果設定為"all"，整個 TrainingArguments 的 `output_dir` 將在每個檢查點記錄。
一個將日誌傳送到 DVCLive 的 TrainerCallback。
在 `setup` 中使用以下環境變數配置整合。要在此環境變數之外自定義此回撥函式，請參閱此處。
設定可選的 DVCLive 整合。要在此環境變數之外自定義此回撥函式，請參閱此處。
環境
- HF_DVCLIVE_LOG_MODEL (
str, 可選)：是否使用 `dvclive.Live.log_artifact()` 記錄由 Trainer 建立的檢查點。如果設定為 `True` 或 *1*，最終檢查點將在訓練結束時記錄。如果設定為 `all`，整個 TrainingArguments 的 `output_dir` 將在每個檢查點記錄。
一個將指標、媒體、模型檢查點記錄到 SwanLab 的 TrainerCallback。
設定可選的 SwanLab (swanlab) 整合。
如有需要，可以子類化並覆蓋此方法以自定義設定。更多資訊請參閱此處。
您還可以覆蓋以下環境變數。更多關於環境變數的資訊請參閱此處
環境
SWANLAB_API_KEY (
str, 可選, 預設為None): 雲API金鑰。登入時，首先檢查此環境變數。如果不存在，系統會檢查使用者是否已登入。如果未登入，則啟動登入過程。- 如果將字串傳遞給登入介面，則忽略此環境變數。
- 如果使用者已登入，此環境變數優先於本地儲存的登入資訊。
SWANLAB_PROJECT (
str, 可選, 預設為None): 將此設定為自定義字串，以便將結果儲存在不同的專案中。如果未指定，則使用當前執行目錄的名稱。SWANLAB_LOG_DIR (
str, 可選, 預設為swanlog): 此環境變數指定在本地模式下執行時的日誌檔案儲存路徑。預設情況下，日誌儲存在工作目錄下名為 swanlog 的資料夾中。SWANLAB_MODE (
Literal["local", "cloud", "disabled"], 可選, 預設為cloud): SwanLab 的解析模式，涉及操作員註冊的回撥。目前有三種模式：本地、雲和停用。注意：區分大小寫。更多資訊請參閱此處SWANLAB_LOG_MODEL (
str, 可選, 預設為None): SwanLab 目前不支援儲存模式功能。此功能將在未來版本中提供。SWANLAB_WEB_HOST (
str, 可選, 預設為None): 私有版本 SwanLab 雲環境的 Web 地址（免費）SWANLAB_API_HOST (
str, 可選, 預設為None): 私有版本 SwanLab 雲環境的 API 地址（免費）
TrainerCallback
class transformers.TrainerCallback
< source >( )
引數
- args (TrainingArguments) — 用於例項化 Trainer 的訓練引數。
- state (TrainerState) — Trainer 的當前狀態。
- control (TrainerControl) — 返回給 Trainer 的物件，可用於做出某些決策。
- model (PreTrainedModel 或
torch.nn.Module) — 正在訓練的模型。 - tokenizer (PreTrainedTokenizer) — 用於資料編碼的分詞器。此引數已被棄用，建議使用
processing_class。 - processing_class ([
PreTrainedTokenizer或BaseImageProcessor或ProcessorMixin或FeatureExtractionMixin]) — 用於資料編碼的處理類。可以是分詞器、處理器、影像處理器或特徵提取器。 - optimizer (
torch.optim.Optimizer) — 用於訓練步驟的最佳化器。 - lr_scheduler (
torch.optim.lr_scheduler.LambdaLR) — 用於設定學習率的排程器。 - train_dataloader (
torch.utils.data.DataLoader, 可選) — 當前用於訓練的資料載入器。 - eval_dataloader (
torch.utils.data.DataLoader, 可選) — 當前用於評估的資料載入器。 - metrics (
dict[str, float]) — 上一評估階段計算的指標。這些僅在
on_evaluate事件中可訪問。 - logs (
dict[str, float]) — 要記錄的值。這些僅在
on_log事件中可訪問。
一個類，用於在某些事件中檢查訓練迴圈狀態並做出決策的物件。在每個這些事件中，以下引數可用：
control 物件是唯一可以被回撥更改的物件，在這種情況下，更改它的事件應返回修改後的版本。
引數 args、state 和 control 是所有事件的位置引數，所有其他引數都分組在 kwargs 中。您可以使用它們的簽名解包您需要的引數。例如，請參見簡單 PrinterCallback 的程式碼。
示例
class PrinterCallback(TrainerCallback):
def on_log(self, args, state, control, logs=None, **kwargs):
_ = logs.pop("total_flos", None)
if state.is_local_process_zero:
print(logs)on_epoch_begin
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
一個 epoch 開始時呼叫的事件。
on_epoch_end
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
一個 epoch 結束時呼叫的事件。
on_evaluate
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
評估階段結束後呼叫的事件。
on_init_end
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
Trainer 初始化結束時呼叫的事件。
記錄最新日誌後呼叫的事件。
on_optimizer_step
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
最佳化器步驟之後但在梯度歸零之前呼叫的事件。用於監控梯度很有用。
on_pre_optimizer_step
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
最佳化器步驟之前但在梯度裁剪之後呼叫的事件。用於監控梯度很有用。
on_predict
< source >( args: TrainingArguments state: TrainerState control: TrainerControl metrics **kwargs )
成功預測後呼叫的事件。
on_prediction_step
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
預測步驟後呼叫的事件。
檢查點儲存後呼叫的事件。
on_step_begin
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
訓練步驟開始時呼叫的事件。如果使用梯度累積，一個訓練步驟可能需要多個輸入。
on_step_end
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
訓練步驟結束時呼叫的事件。如果使用梯度累積，一個訓練步驟可能需要多個輸入。
on_substep_end
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
梯度累積期間一個子步驟結束時呼叫的事件。
on_train_begin
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
訓練開始時呼叫的事件。
on_train_end
< source >( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )
訓練結束時呼叫的事件。
以下是如何向 PyTorch Trainer 註冊自定義回撥的示例
class MyCallback(TrainerCallback):
"A callback that prints a message at the beginning of training"
def on_train_begin(self, args, state, control, **kwargs):
print("Starting training")
trainer = Trainer(
model,
args,
train_dataset=train_dataset,
eval_dataset=eval_dataset,
callbacks=[MyCallback], # We can either pass the callback class this way or an instance of it (MyCallback())
)另一種註冊回撥的方法是呼叫 trainer.add_callback()，如下所示
trainer = Trainer(...)
trainer.add_callback(MyCallback)
# Alternatively, we can pass an instance of the callback class
trainer.add_callback(MyCallback())TrainerState
class transformers.TrainerState
< source >( epoch: typing.Optional[float] = None global_step: int = 0 max_steps: int = 0 logging_steps: int = 500 eval_steps: int = 500 save_steps: int = 500 train_batch_size: typing.Optional[int] = None num_train_epochs: int = 0 num_input_tokens_seen: int = 0 total_flos: float = 0 log_history: list = None best_metric: typing.Optional[float] = None best_global_step: typing.Optional[int] = None best_model_checkpoint: typing.Optional[str] = None is_local_process_zero: bool = True is_world_process_zero: bool = True is_hyper_param_search: bool = False trial_name: typing.Optional[str] = None trial_params: dict = None stateful_callbacks: list = None )
引數
- epoch (
float, 可選) — 僅在訓練期間設定，表示訓練所在的 epoch（小數部分表示當前 epoch 完成的百分比）。 - global_step (
int, 可選, 預設為 0) — 訓練期間，表示已完成的更新步驟數。 - max_steps (
int, 可選, 預設為 0) — 當前訓練期間要執行的更新步驟數。 - logging_steps (
int, 可選, 預設為 500) — 每 X 更新步驟記錄一次日誌。 - eval_steps (
int, 可選) — 每 X 步驟執行一次評估。 - save_steps (
int, 可選, 預設為 500) — 每 X 更新步驟儲存一次檢查點。 - train_batch_size (
int, 可選) — 訓練資料載入器的批大小。僅在使用了auto_find_batch_size時需要。 - num_input_tokens_seen (
int, 可選, 預設為 0) — 當跟蹤輸入 token 時，訓練期間已看到的 token 數量（輸入 token 的數量，而非預測 token 的數量）。 - total_flos (
float, 可選, 預設為 0) — 模型自訓練開始以來完成的浮點運算總數（儲存為浮點數以避免溢位）。 - log_history (
list[dict[str, float]], 可選) — 自訓練開始以來的日誌列表。 - best_metric (
float, 可選) — 當跟蹤最佳模型時，迄今為止遇到的最佳指標值。 - best_global_step (
int, 可選) — 當跟蹤最佳模型時，遇到最佳指標時的步驟。用於設定best_model_checkpoint。 - best_model_checkpoint (
str, 可選) — 當跟蹤最佳模型時，迄今為止遇到的最佳模型的檢查點名稱。 - is_local_process_zero (
bool, 可選, 預設為True) — 此程序是否為本地（例如，如果以分散式方式在多臺機器上訓練）主程序。 - is_world_process_zero (
bool, 可選, 預設為True) — 此程序是否為全域性主程序（當以分散式方式在多臺機器上訓練時，此引數僅對一個程序為True）。 - is_hyper_param_search (
bool, 可選, 預設為False) — 是否正在使用 Trainer.hyperparameter_search 進行超引數搜尋。這將影響資料在 TensorBoard 中的記錄方式。 - stateful_callbacks (
list[StatefulTrainerCallback], 可選) — 附加到Trainer的回撥，其狀態應被儲存或恢復。相關回調應實現state和from_state函式。
一個包含 Trainer 內部狀態的類，該狀態將在檢查點時與模型和最佳化器一起儲存，並傳遞給 TrainerCallback。
在本類中，一步被理解為一次更新步。當使用梯度累積時，一次更新步可能需要多次正向和反向傳播：如果您使用 gradient_accumulation_steps=n，那麼一次更新步需要經過 *n* 個批次。
根據是否為比例來計算並存儲用於日誌記錄、評估和儲存步驟的絕對值。
儲存 self 中所需的初始訓練引用
從 json_path 的內容建立例項。
以 JSON 格式將此例項的內容儲存在 json_path 中。
TrainerControl
類 transformers.TrainerControl
< 源 >( should_training_stop: bool = False should_epoch_stop: bool = False should_save: bool = False should_evaluate: bool = False should_log: bool = False )
引數
- should_training_stop (
bool, 可選, 預設為False) — 訓練是否應該中斷。如果為
True，此變數將不會被重置為False。訓練將直接停止。 - should_epoch_stop (
bool, 可選, 預設為False) — 當前 epoch 是否應該中斷。如果為
True，此變數將在下一個 epoch 開始時被重置為False。 - should_save (
bool, 可選, 預設為False) — 模型是否應該在此步儲存。如果為
True，此變數將在下一步開始時被重置為False。 - should_evaluate (
bool, 可選, 預設為False) — 模型是否應該在此步評估。如果為
True，此變數將在下一步開始時被重置為False。 - should_log (
bool, 可選, 預設為False) — 日誌是否應該在此步報告。如果為
True，此變數將在下一步開始時被重置為False。
一個處理 Trainer 控制流的類。此類由 TrainerCallback 使用，以啟用訓練迴圈中的某些開關。