Skip to content

vllm.v1.kv_offload.tiering.example.manager

ExampleSecondaryTierManager: A simple in-memory secondary tier.

This implementation provides a minimal secondary tier that stores chunks in memory (using a dictionary) with immediate completion. It serves as a reference for writing new tiers and is useful for testing the TieringOffloadingManager without requiring actual storage or network backends.

Classes:

ExampleSecondaryTierManager

Bases: SecondaryTierManager

A simple in-memory secondary tier.

This implementation: - Stores chunks in a dictionary (key -> True) - Completes transfers immediately (synchronous)

Methods:

  • __init__ –

    Initialize the example secondary tier.

  • drain_jobs –

    Synchronous tier — submit_*() returns only after the operation

  • get_finished_jobs –

    Poll for finished jobs.

  • get_num_chunks –

    Get the number of chunks currently stored in this tier.

  • lookup –

    Check whether a chunk exists in this secondary tier.

  • submit_load –

    Submit a job to load chunks from this tier to primary tier.

  • submit_store –

    Submit a job to store chunks from primary tier to this tier.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
class ExampleSecondaryTierManager(SecondaryTierManager):
    """A simple in-memory secondary tier.

    This implementation:
    - Stores chunks in a dictionary (key -> True)
    - Completes transfers immediately (synchronous)
    """

    medium: ClassVar[Medium] = Medium.CPU

    def __init__(
        self,
        offloading_spec: "OffloadingSpec",
        primary_kv_view: memoryview,
        tier_type: str,
        custom_param: int = 0,
        backpressure_detector: "BackpressureDetector | None" = None,
    ):
        """Initialize the example secondary tier.

        Args:
            offloading_spec: The offloading spec this tier belongs to.
            primary_kv_view: Memoryview over the primary tier's KV buffer.
            tier_type: Name identifying this tier type.
            custom_param: Dummy parameter demonstrating custom args.
            backpressure_detector: Optional backpressure detector.

        """
        super().__init__(
            offloading_spec=offloading_spec,
            primary_kv_view=primary_kv_view,
            tier_type=tier_type,
            backpressure_detector=backpressure_detector,
        )

        self._config_info = ExampleTierInfo(example_info=custom_param)

        logger.info(
            "ExampleSecondaryTierManager initialized with custom_param=%d", custom_param
        )

        # key -> True (only care about presence)
        self.chunks: dict[OffloadKey, bool] = {}

        # Completed jobs waiting to be retrieved by get_finished_jobs()
        self.completed_jobs: list[JobResult] = []
        assert primary_kv_view.strides is not None
        self._chunk_size = primary_kv_view.strides[0]

    @classmethod
    @override
    def config_info_keys(cls, tier_config: dict[str, Any]) -> tuple[str, ...]:
        return ExampleTierInfo.config_info_keys()

    @override
    def config_info(self) -> ConfigInfoMapping:
        return self._config_info.as_config_info()

    @override
    def lookup(self, key: OffloadKey, req_context: ReqContext) -> LookupResult:
        """Check whether a chunk exists in this secondary tier.

        Args:
            key: Offload key to look up.
            req_context: Per-request context.

        Returns:
            HIT if the chunk is present, MISS if not found.

        """
        return LookupResult.HIT if key in self.chunks else LookupResult.MISS

    @override
    def submit_store(self, job_metadata: TransferJob) -> None:
        """Submit a job to store chunks from primary tier to this tier.

        Args:
            job_metadata: Job metadata including job_id, keys, and
                          spec for reading chunks from the primary tier.

        """
        keys = job_metadata.keys
        chunk_ids = job_metadata.chunk_ids

        assert len(keys) == len(chunk_ids), (
            f"Length mismatch: {len(keys)} keys but {len(chunk_ids)} chunk_ids"
        )

        for key in keys:
            self.chunks[key] = True
        self.completed_jobs.append(
            JobResult(
                job_id=job_metadata.job_id,
                success=True,
                transfer_time=0.0,
            )
        )

    @override
    def submit_load(self, job_metadata: TransferJob) -> None:
        """Submit a job to load chunks from this tier to primary tier.

        Args:
            job_metadata: Job metadata including job_id, keys, and
                          spec for writing chunks into the primary tier.

        """
        keys = job_metadata.keys
        chunk_ids = job_metadata.chunk_ids

        assert len(keys) == len(chunk_ids), (
            f"Length mismatch: {len(keys)} keys but {len(chunk_ids)} chunk_ids"
        )

        for key in keys:
            if key not in self.chunks:
                self.completed_jobs.append(
                    JobResult(job_id=job_metadata.job_id, success=False)
                )
                return

        self.completed_jobs.append(
            JobResult(
                job_id=job_metadata.job_id,
                success=True,
                transfer_time=0.0,
            )
        )

    @override
    def get_finished_jobs(self) -> Iterable[JobResult]:
        """Poll for finished jobs.

        Returns:
            Iterable of JobResult objects for all jobs that have
            finished since the last call.

        """
        result = self.completed_jobs
        self.completed_jobs = []
        return result

    @override
    def on_new_request(self, req_context: ReqContext) -> RequestOffloadingContext:
        return RequestOffloadingContext()

    @override
    def drain_jobs(self) -> None:
        """Synchronous tier — submit_*() returns only after the operation
        completes, so there is nothing to wait for."""
        return

    def get_num_chunks(self) -> int:
        """Get the number of chunks currently stored in this tier."""
        return len(self.chunks)

__init__(offloading_spec, primary_kv_view, tier_type, custom_param=0, backpressure_detector=None)

Initialize the example secondary tier.

Parameters:

  • offloading_spec

    (OffloadingSpec) –

    The offloading spec this tier belongs to.

  • primary_kv_view

    (memoryview) –

    Memoryview over the primary tier's KV buffer.

  • tier_type

    (str) –

    Name identifying this tier type.

  • custom_param

    (int, default: 0 ) –

    Dummy parameter demonstrating custom args.

  • backpressure_detector

    (BackpressureDetector | None, default: None ) –

    Optional backpressure detector.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def __init__(
    self,
    offloading_spec: "OffloadingSpec",
    primary_kv_view: memoryview,
    tier_type: str,
    custom_param: int = 0,
    backpressure_detector: "BackpressureDetector | None" = None,
):
    """Initialize the example secondary tier.

    Args:
        offloading_spec: The offloading spec this tier belongs to.
        primary_kv_view: Memoryview over the primary tier's KV buffer.
        tier_type: Name identifying this tier type.
        custom_param: Dummy parameter demonstrating custom args.
        backpressure_detector: Optional backpressure detector.

    """
    super().__init__(
        offloading_spec=offloading_spec,
        primary_kv_view=primary_kv_view,
        tier_type=tier_type,
        backpressure_detector=backpressure_detector,
    )

    self._config_info = ExampleTierInfo(example_info=custom_param)

    logger.info(
        "ExampleSecondaryTierManager initialized with custom_param=%d", custom_param
    )

    # key -> True (only care about presence)
    self.chunks: dict[OffloadKey, bool] = {}

    # Completed jobs waiting to be retrieved by get_finished_jobs()
    self.completed_jobs: list[JobResult] = []
    assert primary_kv_view.strides is not None
    self._chunk_size = primary_kv_view.strides[0]

drain_jobs()

Synchronous tier — submit_*() returns only after the operation completes, so there is nothing to wait for.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
197
198
199
200
201
@override
def drain_jobs(self) -> None:
    """Synchronous tier — submit_*() returns only after the operation
    completes, so there is nothing to wait for."""
    return

get_finished_jobs()

Poll for finished jobs.

Returns:

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
180
181
182
183
184
185
186
187
188
189
190
191
@override
def get_finished_jobs(self) -> Iterable[JobResult]:
    """Poll for finished jobs.

    Returns:
        Iterable of JobResult objects for all jobs that have
        finished since the last call.

    """
    result = self.completed_jobs
    self.completed_jobs = []
    return result

get_num_chunks()

Get the number of chunks currently stored in this tier.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
203
204
205
def get_num_chunks(self) -> int:
    """Get the number of chunks currently stored in this tier."""
    return len(self.chunks)

lookup(key, req_context)

Check whether a chunk exists in this secondary tier.

Parameters:

  • key

    (OffloadKey) –

    Offload key to look up.

  • req_context

    (ReqContext) –

    Per-request context.

Returns:

  • LookupResult –

    HIT if the chunk is present, MISS if not found.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
@override
def lookup(self, key: OffloadKey, req_context: ReqContext) -> LookupResult:
    """Check whether a chunk exists in this secondary tier.

    Args:
        key: Offload key to look up.
        req_context: Per-request context.

    Returns:
        HIT if the chunk is present, MISS if not found.

    """
    return LookupResult.HIT if key in self.chunks else LookupResult.MISS

submit_load(job_metadata)

Submit a job to load chunks from this tier to primary tier.

Parameters:

  • job_metadata

    (TransferJob) –

    Job metadata including job_id, keys, and spec for writing chunks into the primary tier.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
@override
def submit_load(self, job_metadata: TransferJob) -> None:
    """Submit a job to load chunks from this tier to primary tier.

    Args:
        job_metadata: Job metadata including job_id, keys, and
                      spec for writing chunks into the primary tier.

    """
    keys = job_metadata.keys
    chunk_ids = job_metadata.chunk_ids

    assert len(keys) == len(chunk_ids), (
        f"Length mismatch: {len(keys)} keys but {len(chunk_ids)} chunk_ids"
    )

    for key in keys:
        if key not in self.chunks:
            self.completed_jobs.append(
                JobResult(job_id=job_metadata.job_id, success=False)
            )
            return

    self.completed_jobs.append(
        JobResult(
            job_id=job_metadata.job_id,
            success=True,
            transfer_time=0.0,
        )
    )

submit_store(job_metadata)

Submit a job to store chunks from primary tier to this tier.

Parameters:

  • job_metadata

    (TransferJob) –

    Job metadata including job_id, keys, and spec for reading chunks from the primary tier.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
@override
def submit_store(self, job_metadata: TransferJob) -> None:
    """Submit a job to store chunks from primary tier to this tier.

    Args:
        job_metadata: Job metadata including job_id, keys, and
                      spec for reading chunks from the primary tier.

    """
    keys = job_metadata.keys
    chunk_ids = job_metadata.chunk_ids

    assert len(keys) == len(chunk_ids), (
        f"Length mismatch: {len(keys)} keys but {len(chunk_ids)} chunk_ids"
    )

    for key in keys:
        self.chunks[key] = True
    self.completed_jobs.append(
        JobResult(
            job_id=job_metadata.job_id,
            success=True,
            transfer_time=0.0,
        )
    )

ExampleTierInfo dataclass

Bases: ConfigInfo

Config facts of one ExampleSecondaryTierManager.

A field name is the label name. A secondary tier needs no name of its own for the tier, because the tier label tells the series of the tiers apart.

Source code in vllm/v1/kv_offload/tiering/example/manager.py 
40
41
42
43
44
45
46
47
48
@dataclass(frozen=True)
class ExampleTierInfo(ConfigInfo):
    """Config facts of one ExampleSecondaryTierManager.

    A field name is the label name. A secondary tier needs no name of its own
    for the tier, because the tier label tells the series of the tiers apart.
    """

    example_info: int