# Công cụ cho Trainer

Trang này liệt kê tất cả các hàm tiện ích được sử dụng bởi [Trainer](/docs/transformers/main/vi/main_classes/trainer#transformers.Trainer).

Hầu hết những điều đó chỉ hữu ích nếu bạn đang nghiên cứu mã nguồn của Trainer trong thư viện.

## Công cụ tiện ích[[transformers.EvalPrediction]]

#### transformers.EvalPrediction[[transformers.EvalPrediction]]

```python
transformers.EvalPrediction(predictions: numpy.ndarray | tuple[numpy.ndarray], label_ids: numpy.ndarray | tuple[numpy.ndarray], inputs: numpy.ndarray | tuple[numpy.ndarray] | None = None, losses: numpy.ndarray | tuple[numpy.ndarray] | None = None)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L210)

**Tham số:**

predictions (`np.ndarray`) : Dự đoán của mô hình.

label_ids (`np.ndarray`) : Các mục tiêu cần khớp.

inputs (`np.ndarray`, *tùy chọn*) : Dữ liệu đầu vào được truyền vào mô hình.

losses (`np.ndarray`, *tùy chọn*) : Các giá trị loss được tính trong quá trình đánh giá.

Đầu ra đánh giá (luôn chứa nhãn), dùng để tính toán các chỉ số.

#### transformers.IntervalStrategy[[transformers.IntervalStrategy]]

```python
transformers.IntervalStrategy(value, names = None, module = None, qualname = None, type = None, start = 1, boundary = None)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L389)

#### transformers.enable_full_determinism[[transformers.enable_full_determinism]]

```python
transformers.enable_full_determinism(seed: int, warn_only: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L154)

Hàm phụ trợ cho hành vi có thể tái lập trong huấn luyện phân tán. Xem https://pytorch.org/docs/stable/notes/randomness.html cho pytorch

#### transformers.set_seed[[transformers.set_seed]]

```python
transformers.set_seed(seed: int, deterministic: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L180)

**Tham số:**

seed (`int`) : Hạt giống cần thiết lập.

deterministic (`bool`, *tùy chọn*, mặc định là `False`) : Có sử dụng các thuật toán tất định khi có sẵn hay không. Có thể làm chậm quá trình huấn luyện.

Hàm phụ trợ cho hành vi có thể tái lập để đặt hạt giống trong `random`, `numpy`, `torch` (nếu đã cài đặt).

#### transformers.torch_distributed_zero_first[[transformers.torch_distributed_zero_first]]

```python
transformers.torch_distributed_zero_first(local_rank: int)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_pt_utils.py#L309)

**Tham số:**

local_rank (`int`) : Bậc của tiến trình cục bộ.

Decorator để tất cả các tiến trình trong huấn luyện phân tán chờ từng local_master thực hiện một thao tác.

## Bên trong Callbacks[[transformers.trainer_callback.CallbackHandler]]

#### transformers.trainer_callback.CallbackHandler[[transformers.trainer_callback.CallbackHandler]]

```python
transformers.trainer_callback.CallbackHandler(callbacks, model, processing_class, optimizer, lr_scheduler)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L429)

Lớp nội bộ chỉ gọi danh sách các callback theo thứ tự.

## Trình phân tích đối số của Trainer[[transformers.HfArgumentParser]]

#### transformers.HfArgumentParser[[transformers.HfArgumentParser]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L111)

**Tham số:**

dataclass_types (`DataClassType` hoặc `Iterable[DataClassType]`, *tùy chọn*) : Kiểu dataclass, hoặc danh sách các kiểu dataclass mà chúng ta sẽ "điền" các instance bằng các args đã được phân tích.

kwargs (`dict[str, Any]`, *tùy chọn*) : Được truyền vào `argparse.ArgumentParser()` theo cách thông thường.

Lớp con này của `argparse.ArgumentParser` sử dụng type hints trên dataclasses để tạo ra các đối số.

Lớp này được thiết kế để tương tác tốt với argparse bản địa. Cụ thể, bạn có thể thêm các đối số (không dựa trên dataclass) vào parser sau khi khởi tạo và sẽ nhận được kết quả sau khi phân tích dưới dạng một namespace bổ sung. Tùy chọn: Để tạo các nhóm đối số con, hãy sử dụng thuộc tính `_argument_group_name` trong dataclass.

#### parse_args_into_dataclasses[[transformers.HfArgumentParser.parse_args_into_dataclasses]]

```python
parse_args_into_dataclasses(args = None, return_remaining_strings = False, look_for_args_file = True, args_filename = None, args_file_flag = None)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L272)

**Tham số:**

args : Danh sách các chuỗi cần phân tích. Giá trị mặc định được lấy từ sys.argv. (giống như argparse.ArgumentParser)

return_remaining_strings : Nếu là true, cũng trả về một danh sách các chuỗi đối số còn lại.

look_for_args_file : Nếu là true, sẽ tìm tệp ".args" có tên cơ sở giống với tệp script điểm vào cho tiến trình này, và sẽ thêm nội dung tiềm năng của nó vào các đối số dòng lệnh.

args_filename : Nếu không phải None, sẽ sử dụng tệp này thay cho tệp ".args" được chỉ định trong đối số trước đó.

args_file_flag : Nếu không phải None, sẽ tìm kiếm một tệp trong các đối số dòng lệnh được chỉ định bằng cờ này. Cờ có thể được chỉ định nhiều lần và thứ tự ưu tiên được xác định theo thứ tự (cờ cuối cùng được ưu tiên).

**Trả về:** `Tuple consisting of`

- các instance của dataclass theo cùng thứ tự như khi chúng được truyền vào bộ khởi tạo.
- nếu có, một namespace bổ sung cho các đối số (không dựa trên dataclass) được thêm vào parser sau khi khởi tạo.
- Danh sách các chuỗi đối số còn lại có thể có. (giống như argparse.ArgumentParser.parse_known_args)

Phân tích các đối số dòng lệnh thành các thể loại của các kiểu dataclass được chỉ định.

Điều này dựa vào `ArgumentParser.parse_known_args` của argparse. Xem tài liệu tại: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

#### parse_dict[[transformers.HfArgumentParser.parse_dict]]

```python
parse_dict(args: dict, allow_extra_keys: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L358)

**Tham số:**

args (`dict`) : dict chứa các giá trị cấu hình

allow_extra_keys (`bool`, *tùy chọn*, mặc định là `False`) : Mặc định là False. Nếu là False, sẽ ném ngoại lệ nếu dict chứa các khóa không được phân tích.

**Trả về:** `Tuple consisting of`

- các instance của dataclass theo cùng thứ tự như khi chúng được truyền vào bộ khởi tạo.

Phương thức trợ giúp thay thế không sử dụng `argparse` mà thay vào đó dùng một dict và điền dữ liệu vào các kiểu dataclass.

#### parse_json_file[[transformers.HfArgumentParser.parse_json_file]]

```python
parse_json_file(json_file: str | os.PathLike, allow_extra_keys: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L386)

**Tham số:**

json_file (`str` hoặc `os.PathLike`) : Tên tệp của tệp json cần phân tích

allow_extra_keys (`bool`, *tùy chọn*, mặc định là `False`) : Mặc định là False. Nếu là False, sẽ ném ngoại lệ nếu tệp json chứa các khóa không được phân tích.

**Trả về:** `Tuple consisting of`

- các instance của dataclass theo cùng thứ tự như khi chúng được truyền vào bộ khởi tạo.

Phương thức trợ giúp thay thế không sử dụng `argparse` mà thay vào đó tải một tệp json và điền dữ liệu vào các kiểu dataclass.

#### parse_yaml_file[[transformers.HfArgumentParser.parse_yaml_file]]

```python
parse_yaml_file(yaml_file: str | os.PathLike, allow_extra_keys: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L408)

**Tham số:**

yaml_file (`str` hoặc `os.PathLike`) : Tên tệp của tệp yaml cần phân tích

allow_extra_keys (`bool`, *tùy chọn*, mặc định là `False`) : Mặc định là False. Nếu là False, sẽ ném ngoại lệ nếu tệp json chứa các khóa không được phân tích.

**Trả về:** `Tuple consisting of`

- các instance của dataclass theo cùng thứ tự như khi chúng được truyền vào bộ khởi tạo.

Phương thức trợ giúp thay thế không sử dụng `argparse` mà thay vào đó tải một tệp yaml và điền vào các kiểu dataclass.

## Công cụ gỡ lỗi[[transformers.debug_utils.DebugUnderflowOverflow]]

#### transformers.debug_utils.DebugUnderflowOverflow[[transformers.debug_utils.DebugUnderflowOverflow]]

```python
transformers.debug_utils.DebugUnderflowOverflow(model, max_frames_to_save = 21, trace_batch_nums = None, abort_after_batch_num = None)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/debug_utils.py#L27)

**Tham số:**

model (`nn.Module`) : Mô hình cần gỡ lỗi.

max_frames_to_save (`int`, *tuỳ chọn*, mặc định là 21) : Số khung hình quay ngược lại để ghi

trace_batch_nums(`list[int]`, *tuỳ chọn*, mặc định là `[]`) : Các số batch cần theo dõi (tắt phát hiện)

abort_after_batch_num  (`int``, *tuỳ chọn*) : Có nên hủy sau khi một số batch nhất định đã hoàn thành hay không

Lớp gỡ lỗi này giúp phát hiện và hiểu được vị trí mà mô hình bắt đầu có giá trị rất lớn hoặc rất nhỏ, và quan trọng hơn là các phần tử trọng số và kích hoạt có giá trị `nan` hoặc `inf`.

Có 2 chế độ hoạt động:

1. Phát hiện tràn/dưới tràn (mặc định)
2. Theo dõi giá trị tuyệt đối min/max của batch cụ thể mà không có phát hiện

Chế độ 1: Phát hiện tràn dưới/tràn trên

Để kích hoạt phát hiện underflow/overflow, khởi tạo đối tượng với model:

```python
debug_overflow = DebugUnderflowOverflow(model)
```

sau đó chạy huấn luyện như bình thường và nếu `nan` hoặc `inf` được phát hiện trong ít nhất một phần tử của trọng số, đầu vào hoặc đầu ra, module này sẽ ném ngoại lệ và in ra `max_frames_to_save` khung hình dẫn đến sự kiện này, mỗi khung hình báo cáo

1. tên module đầy đủ kèm theo tên lớp mà `forward` của nó đã được thực thi
2. giá trị min và max tuyệt đối của tất cả các phần tử đối với trọng số của mỗi module, cũng như đầu vào và đầu ra

Ví dụ, đây là phần tiêu đề và vài khung cuối cùng trong báo cáo phát hiện cho `google/mt5-small` chạy ở fp16

độ chính xác hỗn hợp:

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

Như bạn có thể thấy ở đây, `T5DenseGatedGeluDense.forward` đã tạo ra các kích hoạt đầu ra có giá trị tuyệt đối tối đa khoảng 62.7K, rất gần giới hạn trên 64K của fp16. Trong khung tiếp theo, chúng ta có `Dropout`, thành phần này đã đặt một số phần tử về 0 và sau đó chuẩn hóa lại các trọng số, khiến giá trị tuyệt đối tối đa vượt quá 64K, dẫn đến tràn số.

Như bạn có thể thấy, đó là các khung hình trước đó mà chúng ta cần xem xét khi các con số bắt đầu trở nên rất lớn đối với các số fp16.

Việc theo dõi được thực hiện trong một forward hook, được gọi ngay sau khi `forward` hoàn tất.

Mặc định, 21 khung hình cuối cùng sẽ được in ra. Bạn có thể thay đổi mặc định này để phù hợp với nhu cầu của mình. Ví dụ:

```python
debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)
```

Để xác nhận rằng bạn đã thiết lập tính năng gỡ lỗi này đúng cách và bạn có ý định sử dụng nó trong một quá trình huấn luyện có thể mất hàng giờ để hoàn thành, trước tiên hãy chạy nó với chế độ theo dõi thông thường được bật cho một trong vài batch như đã giải thích trong phần tiếp theo.

Chế độ 2. Theo dõi giá trị tuyệt đối min/max cụ thể của batch mà không có phát hiện

Chế độ hoạt động thứ hai là theo dõi theo lô (per-batch) với tính năng phát hiện tràn dưới/tràn trên (underflow/overflow) được tắt.

Giả sử bạn muốn xem giá trị min và max tuyệt đối của tất cả các thành phần trong mỗi lần gọi `forward` của

cho batch đã cho, và chỉ thực hiện điều đó với batch 1 và 3. Sau đó bạn khởi tạo class này như sau:

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

Và bây giờ, các batch đầy đủ 1 và 3 sẽ được trace bằng cùng định dạng như đã giải thích ở trên. Các batch được đánh chỉ số bắt đầu từ 0.

Điều này hữu ích nếu bạn biết rằng chương trình bắt đầu hoạt động sai sau một số lô (batch) nhất định, để bạn có thể tua nhanh trực tiếp đến khu vực đó.

Dừng sớm:

Bạn cũng có thể chỉ định số lô (batch) sau đó sẽ dừng quá trình huấn luyện, bằng cách sử dụng :

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

Tính năng này chủ yếu hữu ích trong chế độ theo dõi (tracing), nhưng bạn có thể sử dụng nó cho bất kỳ chế độ nào.

**Hiệu năng**:

Vì module này đo `min`/``max` tuyệt đối của từng trọng số của mô hình ở mỗi bước forward, nó sẽ làm chậm quá trình huấn luyện. Do đó, hãy nhớ tắt nó đi khi đã đáp ứng đủ nhu cầu gỡ lỗi.