# Tầng và tiện ích tùy chỉnh

Trang này liệt kê tất cả các lớp tùy chỉnh được thư viện sử dụng, cũng như các hàm tiện ích và lớp mà nó cung cấp cho việc mô hình hóa.

Phần lớn những điều đó chỉ hữu ích nếu bạn đang nghiên cứu mã nguồn của các mô hình trong thư viện.

## WeightRenaming[[transformers.GroupWeightRename]]

#### transformers.GroupWeightRename[[transformers.GroupWeightRename]]

```python
transformers.GroupWeightRename(source_patterns: list[str], target_patterns: list[str])
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L1087)

Áp dụng một danh sách các biến đổi WeightRenaming được ghép cặp, được kích hoạt một cách lười biếng bởi mẫu nguồn đầu tiên ("guard"). Sử dụng biến thể này khi hai phép đổi tên chia sẻ một tên trung gian (ví dụ: `norm0→norm1` và `norm1→norm2`) để đảm bảo việc tải một checkpoint đã được chuyển đổi (chứa `norm1` và `norm2` nhưng không có `norm0`) không áp dụng lại các phép đổi tên một cách sai lệch.

NOTE: sắp xếp `source_patterns` sao cho pattern vắng mặt trong checkpoint đã được chuyển đổi đứng đầu. State dict được lặp lại theo thứ tự key đã sắp xếp, do đó guard pattern phải nhỏ hơn về mặt từ điển so với các pattern phụ thuộc. Nếu không, các phần phụ thuộc sẽ bị bỏ qua ở lượt đầu tiên và không bao giờ được thử lại.

## WeightConverter[[transformers.WeightConverter]]

#### transformers.WeightConverter[[transformers.WeightConverter]]

```python
transformers.WeightConverter(source_patterns: str | list[str], target_patterns: str | list[str], operations: list[ConversionOps], force_cpu: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L1231)

### Các thao tác chuyển đổi[[transformers.ConversionOps]]

#### transformers.ConversionOps[[transformers.ConversionOps]]

```python
transformers.ConversionOps()
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L81)

Lớp cơ sở cho các thao tác chuyển đổi trọng số.

#### transformers.Chunk[[transformers.Chunk]]

```python
transformers.Chunk(dim: int = 0, num_shards_attribute: str | None = None)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L116)

Tách một tensor dọc theo `dim` thành các khối có kích thước bằng nhau. Ngoài ra, `num_shards_attribute` là một trường cấu hình để đọc nhằm biết cần tách thành bao nhiêu tensor. Hữu ích khi nối một số lượng tensor tùy ý.

#### transformers.Concatenate[[transformers.Concatenate]]

```python
transformers.Concatenate(dim: int = 0, num_shards_attribute: str | None = None)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L187)

Nối các tensor dọc theo `dim`. Ngoài ra, nếu nối một số lượng tensor tùy ý, `num_shards_attribute` là một trường cấu hình để đọc nhằm biết số lượng tensor cần tạo lại khi sử dụng các Ops ngược lại.

#### transformers.MergeModulelist[[transformers.MergeModulelist]]

```python
transformers.MergeModulelist(dim: int = 0)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L259)

Gộp một danh sách tensor thành một tensor duy nhất dọc theo chiều đầu tiên. Chúng ta định nghĩa rõ ràng điều này vì với EP hoặc TP, bạn cần chắc chắn rằng mình biết mình đang làm gì!

#### transformers.SplitModulelist[[transformers.SplitModulelist]]

```python
transformers.SplitModulelist(dim: int = 0)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L310)

Ngược của `MergeModulelist` sử dụng kích thước tách rõ ràng cho từng nhóm.

#### transformers.PermuteForRope[[transformers.PermuteForRope]]

```python
transformers.PermuteForRope(subconfig_key: str | None = None, permute_layer_names: list[str] | None = None, inverse: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L465)

Áp dụng hoán vị cần thiết để chuyển đổi trọng số RoPE phức tạp sang định dạng sin/cos tách riêng.

#### transformers.VisionFuseAndPermuteForRope[[transformers.VisionFuseAndPermuteForRope]]

```python
transformers.VisionFuseAndPermuteForRope(dim: int = 0, permute_layer_names: list[str] | None = None, inverse: bool = True)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L537)

Áp dụng hoán vị cần thiết để chuyển trọng số RoPE phức sang định dạng sin/cos tách riêng trên QKV đã hợp nhất. Tương đương với việc gọi `PermuteForRope() + Concatenate()` nhưng cho phép gọi `Permute` chỉ trên một tập con của các tensor đã chia nhỏ.

LƯU Ý: quá trình chuyển đổi này chỉ áp dụng cho bộ xương thị giác trong các mô hình đa phương thức, vì nó kiểm tra `config.vision_config`

#### transformers.VisionUnfuseAndPermuteForRope[[transformers.VisionUnfuseAndPermuteForRope]]

```python
transformers.VisionUnfuseAndPermuteForRope(dim: int = 0, permute_layer_names: list[str] | None = None, inverse: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L591)

Áp dụng hoán vị cần thiết để chuyển trọng số RoPE phức sang định dạng sin/cos tách riêng trên QKV đã hợp nhất. Tương đương với việc gọi `Chunk() + PermuteForRope()` nhưng cho phép gọi `Permute` chỉ trên một tập con các tensor đã chia.

LƯU Ý: quá trình chuyển đổi này chỉ áp dụng cho bộ xương thị giác trong các mô hình đa phương thức, vì nó kiểm tra `config.vision_config`

## Các lớp[[transformers.GradientCheckpointingLayer]]

#### transformers.GradientCheckpointingLayer[[transformers.GradientCheckpointingLayer]]

```python
transformers.GradientCheckpointingLayer(*args, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/modeling_layers.py#L54)

Lớp cơ sở cho các lớp có kiểm tra điểm gradient.

Lớp này cho phép tính năng kiểm tra điểm gradient (gradient checkpointing) cho một lớp. Mặc định, gradient checkpointing bị tắt (`gradient_checkpointing = False`). Khi `model.set_gradient_checkpointing()` được gọi, gradient checkpointing sẽ được bật bằng cách đặt `gradient_checkpointing = True` và gán một hàm checkpointing cho `_gradient_checkpointing_func`.

Quan trọng:

Khi sử dụng gradient checkpointing với `use_reentrant=True`, các đầu vào cần tính gradient (ví dụ: hidden states) phải được truyền dưới dạng đối số vị trí (`*args`) thay vì đối số từ khóa để truyền gradient một cách chính xác.

Ví dụ:

```python
>>> # Correct - hidden_states passed as positional arg
>>> out = self.layer(hidden_states, attention_mask=attention_mask)

>>> # Incorrect - hidden_states passed as keyword arg
>>> out = self.layer(hidden_states=hidden_states, attention_mask=attention_mask)
```

## Các hàm chú ý[[transformers.AttentionInterface]]

#### transformers.AttentionInterface[[transformers.AttentionInterface]]

```python
transformers.AttentionInterface()
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/modeling_utils.py#L5234)

Đối tượng dạng Dict theo dõi các hàm attention được cho phép. Bạn có thể dễ dàng thêm một hàm attention mới bằng cách gọi `register()`. Nếu một model cần ghi đè cục bộ một hàm attention hiện có, chẳng hạn `sdpa`, nó cần khai báo một instance mới của lớp này bên trong `modeling_<model>.py`, và khai báo nó trên instance đó.

#### Đăng ký[[transformers.AttentionInterface.register]]

```python
register(key: str, value: Callable)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/utils/generic.py#L1143)

## Các hàm mặt nạ chú ý[[transformers.AttentionMaskInterface]]

#### transformers.AttentionMaskInterface[[transformers.AttentionMaskInterface]]

```python
transformers.AttentionMaskInterface()
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/masking_utils.py#L733)

#### Đăng ký[[transformers.AttentionMaskInterface.register]]

```python
register(key: str, value: Callable)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/utils/generic.py#L1143)

## Các hàm nhúng vị trí Xoay[[transformers.dynamic_rope_update]]

#### transformers.dynamic_rope_update[[transformers.dynamic_rope_update]]

```python
transformers.dynamic_rope_update(rope_forward)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/modeling_rope_utils.py#L34)

**Tham số:**

rope_forward (Callable) : Quá trình truyền thẳng của việc triển khai RoPE.

**Trả về:**

Quá trình truyền thẳng được trang trí.

Hàm decorator để cập nhật các tham số RoPE trong bước truyền thẳng, nếu mô hình đang sử dụng RoPE động (tức là một triển khai RoPE có thể tính lại tần số của nó trong bước truyền thẳng).

## Các module tùy chỉnh của Pytorch[[transformers.Conv1D]]

#### transformers.Conv1D[[transformers.Conv1D]]

```python
transformers.Conv1D(nf, nx)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/pytorch_utils.py#L95)

**Tham số:**

nf (`int`) : Số lượng đặc trưng đầu ra.

nx (`int`) : Số lượng đặc trưng đầu vào.

Lớp tích chập 1 chiều được định nghĩa bởi Radford et al. cho OpenAI GPT (và cũng được sử dụng trong GPT-2).

Về cơ bản hoạt động giống như một lớp tuyến tính nhưng các trọng số được chuyển vị.

## Hàm trợ giúp PyTorch[[transformers.apply_chunking_to_forward]]

#### transformers.apply_chunking_to_forward[[transformers.apply_chunking_to_forward]]

```python
transformers.apply_chunking_to_forward(forward_fn: Callable[..., torch.Tensor], chunk_size: int, chunk_dim: int, *input_tensors)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/pytorch_utils.py#L124)

**Tham số:**

forward_fn (`Callable[..., torch.Tensor]`) : Hàm forward của mô hình.

chunk_size (`int`) : Kích thước chunk của một tensor dạng chunk: `num_chunks = len(input_tensors[0]) / chunk_size`.

chunk_dim (`int`) : Chiều mà `input_tensors` nên được chia nhỏ.

input_tensors (`tuple[torch.Tensor]`) : Các tensor đầu vào của `forward_fn` sẽ được chia nhỏ

**Trả về:** `torch.Tensor`

Một tensor có cùng hình dạng với kết quả mà `forward_fn` sẽ trả về nếu được áp dụng`.

Hàm này chia `input_tensors` thành các phần tensor đầu vào nhỏ hơn có kích thước `chunk_size` trên chiều `chunk_dim`. Sau đó, nó áp dụng lớp `forward_fn` cho từng phần một cách độc lập để tiết kiệm bộ nhớ.

Nếu `forward_fn` độc lập theo `chunk_dim`, hàm này sẽ cho kết quả giống như việc áp dụng trực tiếp `forward_fn` lên `input_tensors`.

Ví dụ:

```python
# rename the usual forward() fn to forward_chunk()
def forward_chunk(self, hidden_states):
    hidden_states = self.decoder(hidden_states)
    return hidden_states

# implement a chunked forward function
def forward(self, hidden_states):
    return apply_chunking_to_forward(self.forward_chunk, self.chunk_size_lm_head, self.seq_len_dim, hidden_states)
```

#### transformers.pytorch_utils.prune_linear_layer[[transformers.pytorch_utils.prune_linear_layer]]

```python
transformers.pytorch_utils.prune_linear_layer(layer: nn.Linear, index: torch.LongTensor, dim: int = 0)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/pytorch_utils.py#L61)

**Tham số:**

layer (`torch.nn.Linear`) : Lớp cần cắt tỉa.

index (`torch.LongTensor`) : Các chỉ số cần giữ lại trong lớp.

dim (`int`, *tuỳ chọn*, mặc định là 0) : Chiều cần giữ lại các chỉ số.

**Trả về:** `torch.nn.Linear`

Lớp đã được cắt tỉa như một lớp mới với `requires_grad=True`.

Cắt tỉa một lớp tuyến tính để chỉ giữ lại các mục trong index.

Được sử dụng để loại bỏ các đầu.

