Add pydocstyle to the ruff rules (#52136)
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com> Signed-off-by: Harry Mellor <hej.mellor@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
804e5377aa
commit
8c1557a79c
+32
-39
@@ -1,8 +1,6 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
|
||||
"""
|
||||
Core abstractions for KV cache offloading in vLLM v1.
|
||||
"""
|
||||
"""Core abstractions for KV cache offloading in vLLM v1."""
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
from collections.abc import Collection, Iterable, Sequence
|
||||
@@ -149,8 +147,7 @@ class ScheduleEndContext(NamedTuple):
|
||||
|
||||
|
||||
class LoadStoreSpec:
|
||||
"""
|
||||
Metadata that encapsulates information allowing a worker
|
||||
"""Metadata that encapsulates information allowing a worker
|
||||
to load, and optionally also to store, blocks of KV data.
|
||||
"""
|
||||
|
||||
@@ -235,8 +232,7 @@ class OffloadingKVEventsConfig:
|
||||
class OffloadingManager(ABC):
|
||||
@abstractmethod
|
||||
def lookup(self, key: OffloadKey, req_context: ReqContext) -> LookupResult:
|
||||
"""
|
||||
Checks whether a single block is offloaded and ready to be read.
|
||||
"""Checks whether a single block is offloaded and ready to be read.
|
||||
|
||||
Args:
|
||||
key: the key identifying the block to lookup.
|
||||
@@ -246,6 +242,7 @@ class OffloadingManager(ABC):
|
||||
HIT if the block is offloaded and ready, MISS if not found,
|
||||
HIT_PENDING if found but not yet readable, or RETRY if the
|
||||
lookup should be retried later.
|
||||
|
||||
"""
|
||||
pass
|
||||
|
||||
@@ -255,8 +252,7 @@ class OffloadingManager(ABC):
|
||||
keys: Collection[OffloadKey],
|
||||
req_context: ReqContext,
|
||||
) -> LoadStoreSpec:
|
||||
"""
|
||||
Prepare the given blocks to be read.
|
||||
"""Prepare the given blocks to be read.
|
||||
The given blocks will be protected from eviction until
|
||||
complete_load is called.
|
||||
It assumes all given blocks are offloaded.
|
||||
@@ -268,27 +264,28 @@ class OffloadingManager(ABC):
|
||||
Returns:
|
||||
A LoadStoreSpec that can be used by a worker to locate and load
|
||||
the actual offloaded KV data.
|
||||
|
||||
"""
|
||||
pass
|
||||
|
||||
def touch(self, keys: Collection[OffloadKey], req_context: ReqContext):
|
||||
"""
|
||||
Mark the given blocks as recently used.
|
||||
"""Mark the given blocks as recently used.
|
||||
This could in practice mean moving them to the end of an LRU list.
|
||||
|
||||
Args:
|
||||
keys: the keys identifying the blocks.
|
||||
req_context: per-request context (e.g. kv_transfer_params).
|
||||
|
||||
"""
|
||||
return
|
||||
|
||||
def complete_load(self, keys: Collection[OffloadKey], req_context: ReqContext):
|
||||
"""
|
||||
Marks previous blocks that were prepared to load as done loading.
|
||||
"""Marks previous blocks that were prepared to load as done loading.
|
||||
|
||||
Args:
|
||||
keys: the keys identifying the blocks.
|
||||
req_context: per-request context (e.g. kv_transfer_params).
|
||||
|
||||
"""
|
||||
return
|
||||
|
||||
@@ -298,8 +295,7 @@ class OffloadingManager(ABC):
|
||||
keys: Collection[OffloadKey],
|
||||
req_context: ReqContext,
|
||||
) -> PrepareStoreOutput | None:
|
||||
"""
|
||||
Prepare the given blocks to be offloaded.
|
||||
"""Prepare the given blocks to be offloaded.
|
||||
The given blocks will be protected from eviction until
|
||||
complete_store is called.
|
||||
|
||||
@@ -312,6 +308,7 @@ class OffloadingManager(ABC):
|
||||
where to store them (LoadStoreSpec), and list of blocks that
|
||||
were evicted as a result.
|
||||
None is returned if the blocks cannot be stored.
|
||||
|
||||
"""
|
||||
pass
|
||||
|
||||
@@ -321,8 +318,7 @@ class OffloadingManager(ABC):
|
||||
req_context: ReqContext,
|
||||
success: bool = True,
|
||||
):
|
||||
"""
|
||||
Marks blocks which were previously prepared to be stored, as stored.
|
||||
"""Marks blocks which were previously prepared to be stored, as stored.
|
||||
Following this call, the blocks become loadable.
|
||||
If success is False, blocks that were not marked as stored will be
|
||||
removed.
|
||||
@@ -331,25 +327,25 @@ class OffloadingManager(ABC):
|
||||
keys: the keys identifying the blocks.
|
||||
req_context: per-request context (e.g. kv_transfer_params).
|
||||
success: whether the blocks were stored successfully.
|
||||
|
||||
"""
|
||||
return
|
||||
|
||||
@abstractmethod
|
||||
def on_new_request(self, req_context: ReqContext) -> RequestOffloadingContext:
|
||||
"""
|
||||
Called when a new request is first seen by the scheduler.
|
||||
"""Called when a new request is first seen by the scheduler.
|
||||
|
||||
Returns a RequestOffloadingContext indicating how this request's
|
||||
blocks should be offloaded.
|
||||
|
||||
Args:
|
||||
req_context: per-request context.
|
||||
|
||||
"""
|
||||
pass
|
||||
|
||||
def on_request_finished(self, req_context: ReqContext) -> None:
|
||||
"""
|
||||
Called when a request has finished.
|
||||
"""Called when a request has finished.
|
||||
|
||||
By the time this is called, the scheduler will issue no more
|
||||
submit-side calls for this request, such as prepare_store() and
|
||||
@@ -364,12 +360,12 @@ class OffloadingManager(ABC):
|
||||
|
||||
Args:
|
||||
req_context: per-request context.
|
||||
|
||||
"""
|
||||
return
|
||||
|
||||
def take_events(self) -> Iterable[OffloadingEvent]:
|
||||
"""
|
||||
Take the offloading events from the manager.
|
||||
"""Take the offloading events from the manager.
|
||||
|
||||
A tier manager emits only events for storage state it owns. A
|
||||
composing manager may aggregate child event streams, but should not
|
||||
@@ -377,6 +373,7 @@ class OffloadingManager(ABC):
|
||||
|
||||
Yields:
|
||||
New OffloadingEvents collected since the last call.
|
||||
|
||||
"""
|
||||
return ()
|
||||
|
||||
@@ -410,8 +407,7 @@ class OffloadingManager(ABC):
|
||||
|
||||
|
||||
class BlockIDsLoadStoreSpec(LoadStoreSpec, ABC):
|
||||
"""
|
||||
Spec for loading/storing KV blocks from given block numbers.
|
||||
"""Spec for loading/storing KV blocks from given block numbers.
|
||||
|
||||
Subclass semantics differ: GPULoadStoreSpec.block_ids are GPU block
|
||||
indices; CPULoadStoreSpec.block_ids are CPU cache chunk indices.
|
||||
@@ -425,8 +421,7 @@ class BlockIDsLoadStoreSpec(LoadStoreSpec, ABC):
|
||||
|
||||
|
||||
class GPULoadStoreSpec(BlockIDsLoadStoreSpec):
|
||||
"""
|
||||
Spec for loading/storing a KV block to GPU memory.
|
||||
"""Spec for loading/storing a KV block to GPU memory.
|
||||
|
||||
If there are multiple KV groups, the blocks are expected to be
|
||||
ordered by the group index.
|
||||
@@ -460,8 +455,7 @@ class GPULoadStoreSpec(BlockIDsLoadStoreSpec):
|
||||
|
||||
@dataclass
|
||||
class CanonicalKVCacheTensor:
|
||||
"""
|
||||
A canonicalized KV cache tensor whose first dimension is num_blocks.
|
||||
"""A canonicalized KV cache tensor whose first dimension is num_blocks.
|
||||
|
||||
With standardized layouts (RFC #42082) num_blocks is always the leading
|
||||
logical dimension.
|
||||
@@ -478,7 +472,8 @@ class CopyRun:
|
||||
"""A strided byte correspondence between this worker's physical page and
|
||||
a canonical page: for i in range(num_fragments), fragment i spans
|
||||
[local_offset + i * local_stride, +fragment_size) in the worker's page and
|
||||
[canonical_offset + i * canonical_stride, +fragment_size) canonically."""
|
||||
[canonical_offset + i * canonical_stride, +fragment_size) canonically.
|
||||
"""
|
||||
|
||||
local_offset: int
|
||||
canonical_offset: int
|
||||
@@ -517,8 +512,7 @@ class CanonicalPageMapping:
|
||||
|
||||
@dataclass
|
||||
class CanonicalKVCacheRef:
|
||||
"""
|
||||
Per-layer (or group of layers) reference to a specific (by index)
|
||||
"""Per-layer (or group of layers) reference to a specific (by index)
|
||||
CanonicalKVCacheTensor and records the un-padded page size used by that layer.
|
||||
"""
|
||||
|
||||
@@ -532,8 +526,7 @@ class CanonicalKVCacheRef:
|
||||
|
||||
@dataclass
|
||||
class CanonicalKVCaches:
|
||||
"""
|
||||
Canonicalized block-level representation of the KV caches.
|
||||
"""Canonicalized block-level representation of the KV caches.
|
||||
|
||||
Composed of:
|
||||
- Unique list of KV cache data tensors,
|
||||
@@ -561,7 +554,8 @@ class TransferResult:
|
||||
class OffloadingWorker(ABC):
|
||||
"""Runs in the worker process. Performs async KV transfers for ONE
|
||||
offloaded medium (e.g. CPU). Direction is explicit via submit_store /
|
||||
submit_load, so there is no (src_medium, dst_medium) routing."""
|
||||
submit_load, so there is no (src_medium, dst_medium) routing.
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
def submit_store(
|
||||
@@ -620,8 +614,7 @@ class OffloadingSpec(ABC):
|
||||
|
||||
@abstractmethod
|
||||
def get_manager(self) -> OffloadingManager:
|
||||
"""
|
||||
Get an OffloadingManager that will be used
|
||||
"""Get an OffloadingManager that will be used
|
||||
by the scheduler-side offloading connector to track
|
||||
offloaded blocks and manage evictions.
|
||||
"""
|
||||
@@ -629,13 +622,13 @@ class OffloadingSpec(ABC):
|
||||
|
||||
@abstractmethod
|
||||
def get_worker(self, kv_caches: CanonicalKVCaches) -> OffloadingWorker:
|
||||
"""
|
||||
Get an OffloadingWorker that handles async KV transfers for this spec.
|
||||
"""Get an OffloadingWorker that handles async KV transfers for this spec.
|
||||
|
||||
Args:
|
||||
kv_caches: Canonicalized KV caches.
|
||||
|
||||
Returns:
|
||||
An OffloadingWorker instance for this medium.
|
||||
|
||||
"""
|
||||
pass
|
||||
|
||||
Reference in New Issue
Block a user