interfaces.py 7.67 KB
Newer Older
1
from abc import ABC, abstractmethod
2
from typing import Dict, FrozenSet, List, Optional, Protocol, Tuple
3
4
5

from vllm.utils import Device

6
7
BlockId = int

8
9
10
11
12
13
14

class Block(ABC):

    @abstractmethod
    def append_token_ids(self, token_ids: List[int]) -> None:
        pass

15
16
    @property
    @abstractmethod
17
18
19
    def block_id(self) -> Optional[int]:
        pass

20
21
22
23
24
25
    @block_id.setter
    @abstractmethod
    def block_id(self, value: Optional[int]) -> None:
        """NOTE: Do not use this API outside Block."""
        self._block_id = value

26
27
    @property
    @abstractmethod
28
29
30
    def token_ids(self) -> List[int]:
        pass

31
32
33
34
35
36
37
    @property
    @abstractmethod
    def num_tokens_total(self) -> int:
        """The number of tokens till the current block (inclusive)
        """
        pass

38
39
    @property
    @abstractmethod
40
41
42
    def num_empty_slots(self) -> int:
        pass

43
44
    @property
    @abstractmethod
45
46
47
    def is_full(self) -> bool:
        pass

48
49
    @property
    @abstractmethod
50
51
52
    def prev_block(self) -> Optional["Block"]:
        pass

53
54
55
56
57
    @property
    @abstractmethod
    def extra_hash(self) -> Optional[int]:
        return None

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
    @property
    @abstractmethod
    def computed(self) -> bool:
        raise NotImplementedError

    @computed.setter
    @abstractmethod
    def computed(self, value) -> bool:
        """Should be only used by PrefixCacingAllocator"""
        raise NotImplementedError

    @property
    @abstractmethod
    def last_accessed(self) -> float:
        raise NotImplementedError

    @last_accessed.setter
    @abstractmethod
    def last_accessed(self, last_accessed_ts: float):
        raise NotImplementedError

79
80
81
82
83
84
85
86
87
88
    class Factory(Protocol):

        @abstractmethod
        def __call__(
            self,
            prev_block: Optional["Block"],
            token_ids: List[int],
            block_size: int,
            allocator: "BlockAllocator",
            block_id: Optional[int] = None,
89
90
            computed: bool = False,
            extra_hash: Optional[int] = None,
91
92
93
        ) -> "Block":
            pass

94
95
96
97
98
99
100
101
102
103
104
    @property
    @abstractmethod
    def content_hash(self) -> Optional[int]:
        """Return the content-based hash of the current block, or None if it is
        not yet defined or not supported.

        For the content-based hash to be defined, the current block must be
        full.
        """
        return None

105
106
107
108

class BlockAllocator(ABC):

    @abstractmethod
109
110
    def allocate_mutable_block(self, prev_block: Optional[Block],
                               extra_hash: Optional[int]) -> Block:
111
112
113
        pass

    @abstractmethod
114
    def allocate_immutable_block(self, prev_block: Optional[Block],
115
116
                                 token_ids: List[int],
                                 extra_hash: Optional[int]) -> Block:
117
118
119
        pass

    @abstractmethod
120
121
122
    def allocate_immutable_blocks(self, prev_block: Optional[Block],
                                  block_token_ids: List[List[int]],
                                  extra_hash: Optional[int]) -> List[Block]:
123
124
125
126
127
128
129
130
131
132
        pass

    @abstractmethod
    def free(self, block: Block) -> None:
        pass

    @abstractmethod
    def fork(self, last_block: Block) -> List[Block]:
        pass

133
134
135
136
    @abstractmethod
    def get_num_total_blocks(self) -> int:
        pass

137
    @abstractmethod
138
    def get_num_free_blocks(self) -> int:
139
140
        pass

141
142
143
144
145
146
147
148
149
150
151
152
    @abstractmethod
    def get_physical_block_id(self, absolute_id: int) -> int:
        pass

    @abstractmethod
    def swap_out(self, blocks: List[Block]) -> None:
        pass

    @abstractmethod
    def swap_in(self, blocks: List[Block]) -> None:
        pass

153
154
155
    @property
    @abstractmethod
    def all_block_ids(self) -> FrozenSet[int]:
156
157
158
        pass

    @abstractmethod
159
    def clear_copy_on_writes(self) -> List[Tuple[int, int]]:
160
161
        pass

162
    @abstractmethod
163
164
    def mark_blocks_as_accessed(self, block_ids: List[int],
                                now: float) -> None:
165
166
        pass

167
    @abstractmethod
168
    def mark_blocks_as_computed(self, block_ids: List[int]) -> None:
169
170
171
172
        pass

    @abstractmethod
    def get_common_computed_block_ids(
173
            self, computed_seq_block_ids: List[List[int]]) -> List[int]:
174
175
        pass

176
    @abstractmethod
177
    def cow_block_if_not_appendable(self, block: Block) -> BlockId:
178
179
180
181
182
183
184
185
        """NOTE: This should not be used besides Block"""
        pass

    @abstractmethod
    def promote_to_immutable_block(self, block: Block) -> BlockId:
        """NOTE: This should not be used besides Block"""
        pass

186
    @abstractmethod
187
    def get_num_full_blocks_touched(self, blocks: List[Block]) -> int:
188
189
        pass

190
191
192
193
194
    @abstractmethod
    def get_prefix_cache_hit_rate(self) -> float:
        """Prefix cache hit rate. -1 means not supported or disabled."""
        pass

195
196
197
    class NoFreeBlocksError(ValueError):
        pass

198
199
200
201
202
203
204
    @abstractmethod
    def find_cached_blocks_prefix(
        self,
        block_hashes: List[int],
    ) -> List[int]:
        pass

205

206
class DeviceAwareBlockAllocator(ABC):
207
208

    @abstractmethod
209
210
211
212
    def allocate_mutable_block(self,
                               prev_block: Optional[Block],
                               device: Device,
                               extra_hash: Optional[int] = None) -> Block:
213
214
215
        pass

    @abstractmethod
216
217
    def allocate_immutable_block(self,
                                 prev_block: Optional[Block],
218
                                 token_ids: List[int],
219
220
                                 device: Device,
                                 extra_hash: Optional[int] = None) -> Block:
221
222
223
        pass

    @abstractmethod
224
225
226
227
228
    def allocate_immutable_blocks(
        self,
        prev_block: Optional[Block],
        block_token_ids: List[List[int]],
        device: Device,
229
        extra_hash: Optional[int] = None,
230
    ) -> List[Block]:
231
232
233
        pass

    @abstractmethod
234
    def get_num_free_blocks(self, device: Device) -> int:
235
236
237
        pass

    @abstractmethod
238
    def get_num_total_blocks(self, device: Device) -> int:
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
        pass

    @abstractmethod
    def free(self, block: Block) -> None:
        pass

    @abstractmethod
    def fork(self, last_block: Block) -> List[Block]:
        pass

    @property
    @abstractmethod
    def all_block_ids(self) -> FrozenSet[int]:
        pass

    @abstractmethod
255
    def clear_copy_on_writes(self) -> List[Tuple[int, int]]:
256
257
258
259
260
261
262
263
264
265
266
267
268
        pass

    @abstractmethod
    def mark_blocks_as_accessed(self, block_ids: List[int],
                                now: float) -> None:
        pass

    @abstractmethod
    def mark_blocks_as_computed(self, block_ids: List[int]) -> None:
        pass

    @abstractmethod
    def get_common_computed_block_ids(
269
            self, computed_seq_block_ids: List[List[int]]) -> List[int]:
270
        pass
271

272
    @abstractmethod
273
274
    def get_num_full_blocks_touched(self, blocks: List[Block],
                                    device: Device) -> int:
275
276
277
        pass

    @abstractmethod
278
279
    def swap(self, blocks: List[Block], src_device: Device,
             dst_device: Device) -> Dict[int, int]:
280
281
282
283
284
285
        pass

    @abstractmethod
    def get_physical_block_id(self, device: Device, absolute_id: int) -> int:
        pass

286
287
288
289
290
291
292
293
    @abstractmethod
    def allocate_or_get_null_block(self) -> Block:
        """
        Null blocks are used as a placeholders for KV cache blocks that have
        been dropped due to sliding window.
        There is at most one null block per allocator.
        """
        pass
294
295
296
297
298

    @abstractmethod
    def get_prefix_cache_hit_rate(self, device: Device) -> float:
        """Prefix cache hit rate. -1 means not supported or disabled."""
        pass
299
300
301
302
303
304
305
306

    @abstractmethod
    def find_cached_blocks_prefix(
        self,
        block_hashes: List[int],
        device: Device = Device.GPU,
    ) -> List[int]:
        pass