Upload modeling_attn_mask_utils.py with huggingface_hub
Browse files- modeling_attn_mask_utils.py +334 -0
modeling_attn_mask_utils.py
ADDED
@@ -0,0 +1,334 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1 |
+
# Copyright 2023 The HuggingFace Team. All rights reserved.
|
2 |
+
#
|
3 |
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
4 |
+
# you may not use this file except in compliance with the License.
|
5 |
+
# You may obtain a copy of the License at
|
6 |
+
#
|
7 |
+
# http://www.apache.org/licenses/LICENSE-2.0
|
8 |
+
#
|
9 |
+
# Unless required by applicable law or agreed to in writing, software
|
10 |
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
11 |
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
12 |
+
# See the License for the specific language governing permissions and
|
13 |
+
# limitations under the License.
|
14 |
+
from typing import List, Optional, Tuple, Union
|
15 |
+
|
16 |
+
import torch
|
17 |
+
|
18 |
+
|
19 |
+
class AttentionMaskConverter:
|
20 |
+
"""
|
21 |
+
A utility attention mask class that allows one to:
|
22 |
+
- Create a causal 4d mask
|
23 |
+
- Create a causal 4d mask with slided window
|
24 |
+
- Convert a 2d attention mask (batch_size, query_length) to a 4d attention mask (batch_size, 1, query_length,
|
25 |
+
key_value_length) that can be multiplied with attention scores
|
26 |
+
|
27 |
+
Parameters:
|
28 |
+
is_causal (`bool`):
|
29 |
+
Whether the attention mask should be a uni-directional (causal) or bi-directional mask.
|
30 |
+
|
31 |
+
sliding_window (`int`, *optional*):
|
32 |
+
Optionally, the sliding window masks can be created if `sliding_window` is defined to a positive integer.
|
33 |
+
"""
|
34 |
+
|
35 |
+
def __init__(self, is_causal: bool, sliding_window: Optional[int] = None):
|
36 |
+
self.is_causal = is_causal
|
37 |
+
self.sliding_window = sliding_window
|
38 |
+
|
39 |
+
if self.sliding_window is not None and self.sliding_window <= 0:
|
40 |
+
raise ValueError(
|
41 |
+
f"Make sure that when passing `sliding_window` that its value is a strictly positive integer, not `{self.sliding_window}`"
|
42 |
+
)
|
43 |
+
|
44 |
+
def to_causal_4d(
|
45 |
+
self,
|
46 |
+
batch_size: int,
|
47 |
+
query_length: int,
|
48 |
+
key_value_length: int,
|
49 |
+
dtype: torch.dtype = torch.float32,
|
50 |
+
device: Union[torch.device, "str"] = "cpu",
|
51 |
+
) -> torch.Tensor:
|
52 |
+
"""
|
53 |
+
Creates a causal 4D mask of (bsz, head_dim=1, query_length, key_value_length) shape and adds large negative
|
54 |
+
bias to upper right hand triangular matrix (causal mask).
|
55 |
+
"""
|
56 |
+
if not self.is_causal:
|
57 |
+
raise ValueError(f"Please use `to_causal_4d` only if {self.__class__} has `is_causal` set to True.")
|
58 |
+
|
59 |
+
# If shape is not cached, create a new causal mask and cache it
|
60 |
+
input_shape = (batch_size, query_length)
|
61 |
+
past_key_values_length = key_value_length - query_length
|
62 |
+
|
63 |
+
# create causal mask
|
64 |
+
# [bsz, seq_len] -> [bsz, 1, tgt_seq_len, src_seq_len]
|
65 |
+
causal_4d_mask = None
|
66 |
+
if input_shape[-1] > 1 or self.sliding_window is not None:
|
67 |
+
causal_4d_mask = self._make_causal_mask(
|
68 |
+
input_shape,
|
69 |
+
dtype,
|
70 |
+
device=device,
|
71 |
+
past_key_values_length=past_key_values_length,
|
72 |
+
sliding_window=self.sliding_window,
|
73 |
+
)
|
74 |
+
|
75 |
+
return causal_4d_mask
|
76 |
+
|
77 |
+
def to_4d(
|
78 |
+
self,
|
79 |
+
attention_mask_2d: torch.Tensor,
|
80 |
+
query_length: int,
|
81 |
+
key_value_length: Optional[int] = None,
|
82 |
+
dtype: torch.dtype = torch.float32,
|
83 |
+
) -> torch.Tensor:
|
84 |
+
"""
|
85 |
+
Converts 2D attention mask to 4D attention mask by expanding mask to (bsz, head_dim=1, query_length,
|
86 |
+
key_value_length) shape and by adding a large negative bias to not-attended positions. If attention_mask is
|
87 |
+
causal, a causal mask will be added.
|
88 |
+
"""
|
89 |
+
input_shape = (attention_mask_2d.shape[0], query_length)
|
90 |
+
|
91 |
+
# create causal mask
|
92 |
+
# [bsz, seq_len] -> [bsz, 1, tgt_seq_len, src_seq_len]
|
93 |
+
causal_4d_mask = None
|
94 |
+
if (input_shape[-1] > 1 or self.sliding_window is not None) and self.is_causal:
|
95 |
+
if key_value_length is None:
|
96 |
+
raise ValueError(
|
97 |
+
"This attention mask converter is causal. Make sure to pass `key_value_length` to correctly create a causal mask."
|
98 |
+
)
|
99 |
+
|
100 |
+
past_key_values_length = key_value_length - query_length
|
101 |
+
causal_4d_mask = self._make_causal_mask(
|
102 |
+
input_shape,
|
103 |
+
dtype,
|
104 |
+
device=attention_mask_2d.device,
|
105 |
+
past_key_values_length=past_key_values_length,
|
106 |
+
sliding_window=self.sliding_window,
|
107 |
+
)
|
108 |
+
elif self.sliding_window is not None:
|
109 |
+
raise NotImplementedError("Sliding window is currently only implemented for causal masking")
|
110 |
+
|
111 |
+
# [bsz, seq_len] -> [bsz, 1, tgt_seq_len, src_seq_len]
|
112 |
+
expanded_attn_mask = self._expand_mask(attention_mask_2d, dtype, tgt_len=input_shape[-1]).to(
|
113 |
+
attention_mask_2d.device
|
114 |
+
)
|
115 |
+
expanded_4d_mask = expanded_attn_mask if causal_4d_mask is None else expanded_attn_mask + causal_4d_mask
|
116 |
+
|
117 |
+
return expanded_4d_mask
|
118 |
+
|
119 |
+
@staticmethod
|
120 |
+
def _make_causal_mask(
|
121 |
+
input_ids_shape: torch.Size,
|
122 |
+
dtype: torch.dtype,
|
123 |
+
device: torch.device,
|
124 |
+
past_key_values_length: int = 0,
|
125 |
+
sliding_window: Optional[int] = None,
|
126 |
+
):
|
127 |
+
"""
|
128 |
+
Make causal mask used for bi-directional self-attention.
|
129 |
+
"""
|
130 |
+
bsz, tgt_len = input_ids_shape
|
131 |
+
mask = torch.full((tgt_len, tgt_len), torch.finfo(dtype).min, device=device)
|
132 |
+
mask_cond = torch.arange(mask.size(-1), device=device)
|
133 |
+
mask.masked_fill_(mask_cond < (mask_cond + 1).view(mask.size(-1), 1), 0)
|
134 |
+
|
135 |
+
mask = mask.to(dtype)
|
136 |
+
|
137 |
+
if past_key_values_length > 0:
|
138 |
+
mask = torch.cat([torch.zeros(tgt_len, past_key_values_length, dtype=dtype, device=device), mask], dim=-1)
|
139 |
+
|
140 |
+
# add lower triangular sliding window mask if necessary
|
141 |
+
if sliding_window is not None:
|
142 |
+
diagonal = past_key_values_length - sliding_window + 1
|
143 |
+
|
144 |
+
context_mask = 1 - torch.triu(torch.ones_like(mask, dtype=torch.int), diagonal=diagonal)
|
145 |
+
mask.masked_fill_(context_mask.bool(), torch.finfo(dtype).min)
|
146 |
+
|
147 |
+
return mask[None, None, :, :].expand(bsz, 1, tgt_len, tgt_len + past_key_values_length)
|
148 |
+
|
149 |
+
@staticmethod
|
150 |
+
def _expand_mask(mask: torch.Tensor, dtype: torch.dtype, tgt_len: Optional[int] = None):
|
151 |
+
"""
|
152 |
+
Expands attention_mask from `[bsz, seq_len]` to `[bsz, 1, tgt_seq_len, src_seq_len]`.
|
153 |
+
"""
|
154 |
+
bsz, src_len = mask.size()
|
155 |
+
tgt_len = tgt_len if tgt_len is not None else src_len
|
156 |
+
|
157 |
+
expanded_mask = mask[:, None, None, :].expand(bsz, 1, tgt_len, src_len).to(dtype)
|
158 |
+
|
159 |
+
inverted_mask = 1.0 - expanded_mask
|
160 |
+
|
161 |
+
return inverted_mask.masked_fill(inverted_mask.to(torch.bool), torch.finfo(dtype).min)
|
162 |
+
|
163 |
+
|
164 |
+
def _prepare_4d_causal_attention_mask(
|
165 |
+
attention_mask: Optional[torch.Tensor],
|
166 |
+
input_shape: Union[torch.Size, Tuple, List],
|
167 |
+
inputs_embeds: torch.Tensor,
|
168 |
+
past_key_values_length: int,
|
169 |
+
sliding_window: Optional[int] = None,
|
170 |
+
):
|
171 |
+
"""
|
172 |
+
Creates a causal 4D mask of shape `(batch_size, 1, query_length, key_value_length)` from a 2D mask of shape
|
173 |
+
`(batch_size, key_value_length)`
|
174 |
+
|
175 |
+
Args:
|
176 |
+
attention_mask (`torch.Tensor` or `None`):
|
177 |
+
A 2D attention mask of shape `(batch_size, key_value_length)`
|
178 |
+
input_shape (`tuple(int)` or `list(int)` or `torch.Size`):
|
179 |
+
The input shape should be a tuple that defines `(batch_size, query_length)`.
|
180 |
+
inputs_embeds (`torch.Tensor`):
|
181 |
+
The embedded inputs as a torch Tensor.
|
182 |
+
past_key_values_length (`int`):
|
183 |
+
The length of the key value cache.
|
184 |
+
sliding_window (`int`, *optional*):
|
185 |
+
If the model uses windowed attention, a sliding window should be passed.
|
186 |
+
"""
|
187 |
+
attn_mask_converter = AttentionMaskConverter(is_causal=True, sliding_window=sliding_window)
|
188 |
+
|
189 |
+
key_value_length = input_shape[-1] + past_key_values_length
|
190 |
+
|
191 |
+
# 4d mask is passed through the layers
|
192 |
+
if attention_mask is not None:
|
193 |
+
attention_mask = attn_mask_converter.to_4d(
|
194 |
+
attention_mask, input_shape[-1], key_value_length, dtype=inputs_embeds.dtype
|
195 |
+
)
|
196 |
+
else:
|
197 |
+
attention_mask = attn_mask_converter.to_causal_4d(
|
198 |
+
input_shape[0], input_shape[-1], key_value_length, dtype=inputs_embeds.dtype, device=inputs_embeds.device
|
199 |
+
)
|
200 |
+
|
201 |
+
return attention_mask
|
202 |
+
|
203 |
+
|
204 |
+
def _prepare_4d_attention_mask(mask: torch.Tensor, dtype: torch.dtype, tgt_len: Optional[int] = None):
|
205 |
+
"""
|
206 |
+
Creates a non-causal 4D mask of shape `(batch_size, 1, query_length, key_value_length)` from a 2D mask of shape
|
207 |
+
`(batch_size, key_value_length)`
|
208 |
+
|
209 |
+
Args:
|
210 |
+
mask (`torch.Tensor` or `None`):
|
211 |
+
A 2D attention mask of shape `(batch_size, key_value_length)`
|
212 |
+
dtype (`torch.dtype`):
|
213 |
+
The torch dtype the created mask shall have.
|
214 |
+
tgt_len (`int`):
|
215 |
+
The target length or query length the created mask shall have.
|
216 |
+
"""
|
217 |
+
return AttentionMaskConverter._expand_mask(mask=mask, dtype=dtype, tgt_len=tgt_len)
|
218 |
+
|
219 |
+
|
220 |
+
def _create_4d_causal_attention_mask(
|
221 |
+
input_shape: Union[torch.Size, Tuple, List],
|
222 |
+
dtype: torch.dtype,
|
223 |
+
device: torch.device,
|
224 |
+
past_key_values_length: int = 0,
|
225 |
+
sliding_window: Optional[int] = None,
|
226 |
+
):
|
227 |
+
"""
|
228 |
+
Creates a causal 4D mask of shape `(batch_size, 1, query_length, key_value_length)`
|
229 |
+
|
230 |
+
Args:
|
231 |
+
input_shape (`tuple(int)` or `list(int)` or `torch.Size`):
|
232 |
+
The input shape should be a tuple that defines `(batch_size, query_length)`.
|
233 |
+
dtype (`torch.dtype`):
|
234 |
+
The torch dtype the created mask shall have.
|
235 |
+
device (`int`):
|
236 |
+
The torch device the created mask shall have.
|
237 |
+
sliding_window (`int`, *optional*):
|
238 |
+
If the model uses windowed attention, a sliding window should be passed.
|
239 |
+
"""
|
240 |
+
attn_mask_converter = AttentionMaskConverter(is_causal=True, sliding_window=sliding_window)
|
241 |
+
|
242 |
+
key_value_length = past_key_values_length + input_shape[-1]
|
243 |
+
attention_mask = attn_mask_converter.to_causal_4d(
|
244 |
+
input_shape[0], input_shape[-1], key_value_length, dtype=dtype, device=device
|
245 |
+
)
|
246 |
+
|
247 |
+
return attention_mask
|
248 |
+
|
249 |
+
|
250 |
+
# Adapted from _prepare_4d_causal_attention_mask
|
251 |
+
def _prepare_4d_causal_attention_mask_for_sdpa(
|
252 |
+
attention_mask: Optional[torch.Tensor],
|
253 |
+
input_shape: Union[torch.Size, Tuple, List],
|
254 |
+
inputs_embeds: torch.Tensor,
|
255 |
+
past_key_values_length: int,
|
256 |
+
sliding_window: Optional[int] = None,
|
257 |
+
):
|
258 |
+
"""
|
259 |
+
Prepares the correct `attn_mask` argument to be used by `torch.nn.functional.scaled_dot_product_attention`.
|
260 |
+
|
261 |
+
In case no token is masked in the `attention_mask` argument, we simply set it to `None` for the cases `query_length == 1` and
|
262 |
+
`key_value_length == query_length`, and rely instead on SDPA `is_causal` argument to use causal/non-causal masks,
|
263 |
+
allowing to dispatch to the flash attention kernel (that can otherwise not be used if a custom `attn_mask` is passed).
|
264 |
+
"""
|
265 |
+
attn_mask_converter = AttentionMaskConverter(is_causal=True, sliding_window=sliding_window)
|
266 |
+
|
267 |
+
key_value_length = input_shape[-1] + past_key_values_length
|
268 |
+
batch_size, query_length = input_shape
|
269 |
+
|
270 |
+
# torch.jit.trace and torchdynamo with fullgraph=True are unable to capture the controlflow `is_causal=attention_mask is None and q_len > 1`
|
271 |
+
# used as an SDPA argument. We keep compatibility with these tracing tools by always using SDPA's `attn_mask` argument in case we are tracing.
|
272 |
+
# TODO: Fix this as well when using torchdynamo with fullgraph=True.
|
273 |
+
is_tracing = torch.jit.is_tracing()
|
274 |
+
|
275 |
+
if attention_mask is not None:
|
276 |
+
# 4d mask is passed through
|
277 |
+
if len(attention_mask.shape) == 4:
|
278 |
+
expected_shape = (input_shape[0], 1, input_shape[1], key_value_length)
|
279 |
+
if tuple(attention_mask.shape) != expected_shape:
|
280 |
+
raise ValueError(
|
281 |
+
f"Incorrect 4D attention_mask shape: {tuple(attention_mask.shape)}; expected: {expected_shape}."
|
282 |
+
)
|
283 |
+
else:
|
284 |
+
# if the 4D mask has correct shape - invert it and fill with negative infinity
|
285 |
+
inverted_mask = 1.0 - attention_mask.to(inputs_embeds.dtype)
|
286 |
+
attention_mask = inverted_mask.masked_fill(
|
287 |
+
inverted_mask.to(torch.bool), torch.finfo(inputs_embeds.dtype).min
|
288 |
+
)
|
289 |
+
return attention_mask
|
290 |
+
|
291 |
+
elif torch.all(attention_mask == 1):
|
292 |
+
if is_tracing:
|
293 |
+
pass
|
294 |
+
elif query_length == 1:
|
295 |
+
# For query_length == 1, causal attention and bi-directional attention are the same.
|
296 |
+
attention_mask = None
|
297 |
+
elif key_value_length == query_length:
|
298 |
+
attention_mask = None
|
299 |
+
else:
|
300 |
+
# Unfortunately, for query_length > 1 and key_value_length != query_length, we cannot generally ignore the attention mask, as SDPA causal mask generation
|
301 |
+
# may be wrong. We will set `is_causal=False` in SDPA and rely on Transformers attention_mask instead, hence not setting it to None here.
|
302 |
+
# Reference: https://github.com/pytorch/pytorch/issues/108108
|
303 |
+
pass
|
304 |
+
elif query_length > 1 and key_value_length != query_length:
|
305 |
+
# See the comment above (https://github.com/pytorch/pytorch/issues/108108).
|
306 |
+
# Ugly: we set it to True here to dispatch in the following controlflow to `to_causal_4d`.
|
307 |
+
attention_mask = True
|
308 |
+
elif is_tracing:
|
309 |
+
raise ValueError(
|
310 |
+
'Attention using SDPA can not be traced with torch.jit.trace when no attention_mask is provided. To solve this issue, please either load your model with the argument `attn_implementation="eager"` or pass an attention_mask input when tracing the model.'
|
311 |
+
)
|
312 |
+
|
313 |
+
if attention_mask is None:
|
314 |
+
expanded_4d_mask = None
|
315 |
+
elif attention_mask is True:
|
316 |
+
expanded_4d_mask = attn_mask_converter.to_causal_4d(
|
317 |
+
input_shape[0], input_shape[-1], key_value_length, dtype=inputs_embeds.dtype, device=inputs_embeds.device
|
318 |
+
)
|
319 |
+
else:
|
320 |
+
expanded_4d_mask = attn_mask_converter.to_4d(
|
321 |
+
attention_mask,
|
322 |
+
input_shape[-1],
|
323 |
+
dtype=inputs_embeds.dtype,
|
324 |
+
key_value_length=key_value_length,
|
325 |
+
)
|
326 |
+
|
327 |
+
# From PyTorch 2.1 onwards, F.scaled_dot_product_attention with the memory-efficient attention backend
|
328 |
+
# produces nans if sequences are completely unattended in the attention mask. Details: https://github.com/pytorch/pytorch/issues/110213
|
329 |
+
if query_length > 1:
|
330 |
+
expanded_4d_mask = AttentionMaskConverter._unmask_unattended(
|
331 |
+
expanded_4d_mask, attention_mask, unmasked_value=0.0
|
332 |
+
)
|
333 |
+
|
334 |
+
return expanded_4d_mask
|