# Callbacks

## RichProgressCallback[[trl.RichProgressCallback]]

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

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

[Nguồn](https://github.com/huggingface/trl/blob/main/trl/trainer/callbacks.py#L157)

Một [TrainerCallback](https://huggingface.co/docs/transformers/main/en/main_classes/callback#transformers.TrainerCallback) hiển thị tiến trình của quá trình huấn luyện hoặc đánh giá bằng Rich.

## 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)
```

[Nguồn](https://github.com/huggingface/trl/blob/main/trl/trainer/callbacks.py#L268)

**Tham số:**

trainer (`Trainer`) : Trainer mà callback sẽ được gắn vào. Tập dữ liệu đánh giá của trainer phải bao gồm một cột `"prompt"` chứa các prompt để tạo ra các câu trả lời hoàn chỉnh.

generation_config ([GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig), *optional*) : Cấu hình sinh cần dùng để tạo các phần hoàn thành.

num_prompts (`int`, *optional*) : Số lượng prompt để tạo các câu hoàn thành. Nếu không được cung cấp, mặc định sẽ là số lượng ví dụ trong bộ dữ liệu đánh giá.

freq (`int`, *tuỳ chọn*) : Tần suất ghi log các kết quả hoàn thành. Nếu không được cung cấp, mặc định là `eval_steps` của trainer.

Một [TrainerCallback](https://huggingface.co/docs/transformers/main/en/main_classes/callback#transformers.TrainerCallback) ghi log các kết quả hoàn thành vào Weights & Biases và/hoặc Comet.

Cách sử dụng:
```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')
```

[Nguồn](https://github.com/huggingface/trl/blob/main/trl/trainer/callbacks.py#L590)

**Tham số:**

update_freq (`int`, *optional*, mặc định là `400`) : Cập nhật trọng số BEMA mỗi X bước. Kí hiệu này là  \\( \phi \\) trong bài báo.

ema_power (`float`, *optional*, mặc định là `0.5`) : Lũy thừa cho hệ số suy giảm EMA. Được ký hiệu là \\( \kappa \\) trong bài báo. Để tắt EMA, hãy đặt giá trị này thành `0.0`.

bias_power (`float`, *optional*, mặc định là `0.2`) : Lũy thừa cho hệ số tỷ lệ BEMA. Được ký hiệu là \\( \eta \\) trong bài báo. Một giá trị lớn (ví dụ `8.0`) khiến \\( \alpha_t \\) suy giảm về `0`, xấp xỉ việc vô hiệu hóa hiệu chỉnh sai lệch; `0.0` thay vào đó giữ \\( \alpha_t \\) ở mức `1` cho mọi bước (hiệu chỉnh tối đa, không suy giảm).

lag (`int`, *tuỳ chọn*, mặc định là `10`) : Độ lệch ban đầu trong lịch trình suy giảm trọng số, kiểm soát độ mượt ở giai đoạn đầu bằng cách đóng vai trò là tuổi bắt đầu ảo cho các bản cập nhật. Được ký hiệu là \\( \rho \\) trong bài báo.

update_after (`int`, *optional*, mặc định là `0`) : Thời gian chạy thử trước khi bắt đầu cập nhật trọng số BEMA. Được ký hiệu là \\( \tau \\) trong bài báo.

multiplier (`float`, *tuỳ chọn*, mặc định là `1.0`) : Giá trị ban đầu cho hệ số suy giảm EMA. Được ký hiệu là \\( \gamma \\) trong bài báo.

min_ema_multiplier (`float`, *tùy chọn*, mặc định là `0.0`) : Giá trị tối thiểu cho hệ số suy giảm EMA.

device (`str`, *tùy chọn*, mặc định là `"cpu"`) : Thiết bị để sử dụng cho các bộ đệm BEMA, ví dụ `"cpu"` hoặc `"cuda"`. Lưu ý rằng trong hầu hết các trường hợp, thiết bị này PHẢI KHÁC với thiết bị được sử dụng cho huấn luyện để tránh OOM.

Một [TrainerCallback](https://huggingface.co/docs/transformers/main/en/main_classes/callback#transformers.TrainerCallback) triển khai [BEMA](https://huggingface.co/papers/2508.00180) (Bias-Corrected Exponential Moving Average) do [Adam Block](https://huggingface.co/abblock) và [Cyril Zhang](https://huggingface.co/cyrilzhang) phát triển. Mã nguồn từ https://github.com/abblock/bema theo giấy phép MIT.

BEMA tính toán trọng số mô hình có tỷ lệ như sau:

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

trong đó \\( \theta_t \\) là trọng số mô hình hiện tại, \\( \theta_0 \\) là bản sao của trọng số mô hình tại bước `update_after` đầu tiên, \\( \text{EMA}_t  \\) là trung bình trượt mũ của trọng số mô hình, và \\( \alpha_t \\) là hệ số tỷ lệ giảm dần theo số bước \\( t \\) như

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

EMA được tính như sau:

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

trong đó \\( \beta_t \\) là hệ số suy giảm, giảm dần theo số bước \\( t \\) như

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

Ví dụ:

```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)
```

[Nguồn](https://github.com/huggingface/trl/blob/main/trl/trainer/callbacks.py#L361)

**Tham số:**

trainer (`Trainer`) : Trainer mà callback sẽ được gắn vào. Tập dữ liệu đánh giá của trainer phải bao gồm một cột `"prompt"` chứa các prompt để tạo ra các câu trả lời hoàn chỉnh.

project_name (`str`, *tùy chọn*) : Tên của dự án Weave nơi dữ liệu sẽ được ghi log. Nếu không được cung cấp, sẽ cố gắng sử dụng weave client hiện có hoặc quay lại tên dự án của wandb run đang hoạt động. Ném lỗi nếu không có bất kỳ lựa chọn nào trong số này khả dụng.

scorers (`dict[str, Callable]`, *tùy chọn*) : Từ điển ánh xạ tên bộ chấm điểm đến các hàm chấm điểm. Nếu là `None`, hoạt động ở chế độ theo dõi (chỉ dự đoán). Nếu được cung cấp, hoạt động ở chế độ đánh giá (dự đoán + điểm + tóm tắt). Các hàm chấm điểm nên có chữ ký: `scorer(prompt: str, completion: str) -> float | int`

generation_config ([GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig), *optional*) : Cấu hình sinh để sử dụng khi tạo các phần hoàn thành.

num_prompts (`int`, *optional*) : Số lượng prompt để tạo các câu hoàn thành. Nếu không được cung cấp, mặc định sẽ là số lượng ví dụ trong bộ dữ liệu đánh giá.

dataset_name (`str`, *tùy chọn*, mặc định là `"eval_dataset"`) : Tên cho metadata của dataset trong Weave.

model_name (`str`, *tùy chọn*) : Tên cho metadata của model trong Weave. Nếu không được cung cấp, sẽ cố gắng trích xuất từ config của model.

Một [TrainerCallback](https://huggingface.co/docs/transformers/main/en/main_classes/callback#transformers.TrainerCallback) ghi lại các trace và đánh giá vào W&B Weave. Callback này sử dụng https://weave-docs.wandb.ai/guides/evaluation/evaluation_logger/ để ghi lại các trace và đánh giá ở mỗi bước đánh giá.

Hỗ trợ hai chế độ dựa trên tham số `scorers`:
- **Chế độ Tracing** (khi scorers=None): Ghi lại các dự đoán để khám phá và phân tích dữ liệu
- **Chế độ đánh giá** (khi có bộ chấm điểm): Ghi log các dự đoán kèm theo điểm số và các chỉ số tóm tắt

Cả hai chế độ đều sử dụng EvaluationLogger của Weave để ghi log dữ liệu có cấu trúc và nhất quán.

Callback ghi log dữ liệu trong các giai đoạn đánh giá (`on_evaluate`) thay vì các bước huấn luyện, giúp hiệu quả hơn và đúng về mặt ngữ nghĩa. Nó xử lý một cách mềm mại việc thiếu cài đặt weave bằng cách ghi log cảnh báo và bỏ qua các chức năng đặc thù của weave. Nó cũng kiểm tra các weave client hiện có trước khi khởi tạo những client mới.

Cách sử dụng:
```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)
```

[Nguồn](https://github.com/huggingface/trl/blob/main/trl/trainer/callbacks.py#L491)

Khởi tạo Weave khi quá trình huấn luyện bắt đầu.

