# 回调

## RichProgressCallback[[trl.RichProgressCallback]]

#### trl.RichProgressCallback[[trl.RichProgressCallback]]

```python
trl.RichProgressCallback()
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/callbacks.py#L157)

一个使用 Rich 显示训练或评估进度的 [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback)。

## LogCompletionsCallback[[trl.LogCompletionsCallback]]

#### trl.LogCompletionsCallback[[trl.LogCompletionsCallback]]

```python
trl.LogCompletionsCallback(trainer: Trainer, generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, num_prompts: int | None = None, freq: int | None = None)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/callbacks.py#L268)

**参数：**

trainer (`Trainer`)：回调将附加到的 `Trainer`。该 `Trainer` 的评估数据集必须包含一个 `"prompt"` 列，其中包含用于生成补全的提示。

generation_config ([GenerationConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/text_generation#transformers.GenerationConfig)，*可选*)：用于生成补全的生成配置。

num_prompts (`int`, *可选*) : 需要生成补全的提示数量。如果未提供，则默认为评估数据集中的示例数量。

freq (`int`, *可选*) : 记录补全的频率。如果未提供，则默认为训练器的 `eval_steps`。

一个用于将补全记录到 Weights & Biases 和/或 Comet 的 [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback)。

用法：
```python
>>> trainer = DPOTrainer(...)
>>> completions_callback = LogCompletionsCallback(trainer=trainer)
>>> trainer.add_callback(completions_callback)
```

## BEMACallback[[trl.BEMACallback]]

#### trl.BEMACallback[[trl.BEMACallback]]

```python
trl.BEMACallback(update_freq: int = 400, ema_power: float = 0.5, bias_power: float = 0.2, lag: int = 10, update_after: int = 0, multiplier: float = 1.0, min_ema_multiplier: float = 0.0, device: str = 'cpu')
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/callbacks.py#L590)

**参数：**

update_freq (`int`, *可选*, 默认为 `400`) : 每隔 X 步更新一次 BEMA 权重。在论文中将其表示为 \\( \phi \\)。

ema_power (`float`, *可选*，默认为 `0.5`)：EMA 衰减因子的幂。在论文中记为 \\( \kappa \\)。要禁用 EMA，请将其设置为 `0.0`。

bias_power (`float`, *可选*，默认为 `0.2`) : BEMA 缩放因子的幂次。在论文中记为 \\( \eta \\)。较大的值（例如 `8.0`）会使 \\( \alpha_t \\) 衰减至 `0`，从而近似于禁用偏差校正；而 `0.0` 则会在每一步将 \\( \alpha_t \\) 固定为 `1`（即最大且未衰减的校正）。

lag (`int`, *可选*, 默认为 `10`) : 权重衰减调度中的初始偏移量，通过充当更新的虚拟起始年龄来控制早期阶段的平滑度。在论文中记为 \\( \rho \\)。

update_after (`int`, *可选*, 默认为 `0`) : 开始更新 BEMA 权重之前的预热时间。在论文中记为 \\( \tau \\)。

multiplier (`float`, *可选*, 默认为 `1.0`) : EMA 衰减因子的初始值。在论文中记为 \\( \gamma \\)。

min_ema_multiplier (`float`, *可选*, 默认为 `0.0`) : EMA 衰减因子的最小值。

device (`str`，*可选*，默认为 `"cpu"`)：用于 BEMA 缓冲区的设备，例如 `"cpu"` 或 `"cuda"`。请注意，在大多数情况下，该设备应与训练所用的设备不同，以避免 OOM。

一个实现了 [BEMA](https://huggingface.co/papers/2508.00180)（偏差校正指数移动平均）的 [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback)，由 [Adam Block](https://huggingface.co/abblock) 和 [Cyril Zhang](https://huggingface.co/cyrilzhang) 开发。代码来自 https://github.com/abblock/bema，采用 MIT 许可证。

BEMA 计算按以下方式缩放的模型权重：

$$ \theta_t' = \alpha_t \cdot (\theta_t - \theta_0) + \text{EMA}_t $$

其中 \\( \theta_t \\) 是当前模型权重，\\( \theta_0 \\) 是第一个 `update_after` 步时模型权重的快照，\\( \text{EMA}_t  \\) 是模型权重的指数移动平均，\\( \alpha_t \\) 是一个随步数 \\( t \\) 衰减的缩放因子，其形式为

$$ \alpha_t = (\rho + \gamma \cdot t)^{-\eta}. $$

EMA 的计算方式如下：

$$ \text{EMA}_t = (1 - \beta_t) \cdot \text{EMA}_{t-1} + \beta_t \cdot \theta_t $$

其中 \\( \beta_t \\) 是一个衰减因子，它随着步数 \\( t \\) 的增大而衰减，具体为

$$ \beta_t = (\rho + \gamma \cdot t)^{-\kappa}. $$

示例：

```python
>>> from trl import BEMACallback

>>> trainer = Trainer(..., callbacks=[BEMACallback()])
```

## WeaveCallback[[trl.WeaveCallback]]

#### trl.WeaveCallback[[trl.WeaveCallback]]

```python
trl.WeaveCallback(trainer: Trainer, project_name: str | None = None, scorers: dict[str, callable] | None = None, generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, num_prompts: int | None = None, dataset_name: str = 'eval_dataset', model_name: str | None = None)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/callbacks.py#L361)

**参数：**

trainer (`Trainer`)：回调将附加到的 `Trainer`。该 `Trainer` 的评估数据集必须包含一个 `"prompt"` 列，其中包含用于生成补全的提示。

project_name (`str`, *可选*) : 用于记录数据的 Weave 项目名称。如果未提供，将尝试使用现有的 weave 客户端，或回退到当前活跃的 wandb 运行的项目名称。如果这些均不可用，则会引发错误。

scorers (`dict[str, Callable]`, *可选*) : 将评分器名称映射到评分器函数的字典。如果为 `None`，则以追踪模式运行（仅预测）。如果提供，则以评估模式运行（预测 + 分数 + 摘要）。评分器函数的签名应为：`scorer(prompt: str, completion: str) -> float | int`

generation_config ([GenerationConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/text_generation#transformers.GenerationConfig)，*可选*)：用于生成补全的生成配置。

num_prompts (`int`, *可选*) : 需要生成补全的提示数量。如果未提供，则默认为评估数据集中的示例数量。

dataset_name (`str`，*可选*，默认为 `"eval_dataset"`)：Weave 中数据集元数据的名称。

model_name (`str`, *可选*) : 模型元数据在 Weave 中的名称。如果未提供，则尝试从模型配置中提取。

一个用于将跟踪和评估记录到 W&B Weave 的 [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback)。该回调使用 https://weave-docs.wandb.ai/guides/evaluation/evaluation_logger/ 在每个评估步骤记录跟踪和评估。

支持基于 `scorers` 参数的两种模式：
- **追踪模式**（当 scorers=None 时）：记录预测结果，用于数据探索和分析
- **评估模式**（提供评分器时）：记录带有评分和汇总指标的预测结果

两种模式均使用 Weave 的 EvaluationLogger 进行结构化且一致的数据记录。

该回调在评估阶段（`on_evaluate`）而非训练步骤中记录数据，因此更高效且语义上更正确。它会优雅地处理 weave 未安装的情况，通过记录警告并跳过 weave 特定功能来实现。此外，在初始化新的 weave 客户端之前，它还会检查是否已存在 weave 客户端。

用法：
```python
# Tracing mode (just log predictions)
trainer = DPOTrainer(...)
weave_callback = WeaveTraceCallback(trainer=trainer)  # project_name optional
trainer.add_callback(weave_callback)

# Or specify a project name
weave_callback = WeaveTraceCallback(trainer=trainer, project_name="my-llm-training")
trainer.add_callback(weave_callback)

# Evaluation mode (log predictions + scores + summary)
def accuracy_scorer(prompt: str, completion: str) -> float:
    # Your scoring logic here (metadata available via eval_attributes)
    return score

weave_callback = WeaveTraceCallback(
    trainer=trainer,
    project_name="my-llm-training",  # optional and needed only if weave client is not initialized
    scorers={"accuracy": accuracy_scorer},
)
trainer.add_callback(weave_callback)
```

#### on_train_begin[[trl.WeaveCallback.on_train_begin]]

```python
on_train_begin(args, state, control, **kwargs)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/callbacks.py#L491)

在训练开始时初始化 Weave。

