[Docs][RL] Rewrite weight-transfer docs; standardize examples (#51729)

Signed-off-by: haoaaron <ahao@anyscale.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Aaron Hao
2026-08-11 18:53:15 -07:00
committed by GitHub
co-authored by Claude Opus 5
parent 9b3382685e
commit 793ca6998a
16 changed files with 1211 additions and 1142 deletions
+9 -27
View File
@@ -77,7 +77,15 @@ class WeightSource(ABC):
@abstractmethod
def metadata(self) -> list[ParamMeta]:
"""Declare what iteration will yield, without transferring anything."""
"""Declare what iteration will yield, without transferring anything.
Must agree with iteration element for element: the same parameters, in
the same order, with the same dtypes and shapes. Backends may read both
channels and trust that they match (dense NCCL sizes the worker's receive
buffers and its packed chunk boundaries from this, then sends the bytes
from iteration), so a source that disagrees between the two splits the
stream differently on each side.
"""
raise NotImplementedError
@abstractmethod
@@ -342,32 +350,6 @@ class WeightTransferEngine(ABC, Generic[TInitInfo, TUpdateInfo]):
"""
raise NotImplementedError
@staticmethod
@abstractmethod
def trainer_send_weights(
iterator: Iterator[Any],
trainer_args: dict[str, Any] | Any,
) -> None:
"""
Send weights from trainer to inference workers.
This is a static method that can be called from the trainer process
to send weights to all inference workers.
Args:
iterator: Iterator of backend-specific items to send.
trainer_args: Dictionary containing backend-specific arguments needed
to send weights. The structure depends on the backend:
- NCCL: Contains 'group', 'src', 'packed', etc.
- IPC: Contains 'mode' ('http' or 'ray'),
'llm_handle' (for Ray), 'url' (for HTTP), etc.
Example:
>>> param_iter = ((n, p) for n, p in model.named_parameters())
>>> engine.trainer_send_weights(param_iter, trainer_args)
"""
raise NotImplementedError
@runtime_checkable
class VLLMWeightSyncClient(Protocol):
@@ -249,21 +249,6 @@ class IPCWeightTransferEngine(
def shutdown(self) -> None:
self._packed_importer.close()
@staticmethod
def trainer_send_weights(*args: Any, **kwargs: Any) -> None:
"""Removed. Use the stateful `IPCTrainerWeightTransferEngine` instead.
Transitional stub kept only to satisfy the (still abstract)
`WeightTransferEngine.trainer_send_weights`; that member is dropped from
the worker ABC once every backend has migrated to the trainer engine.
"""
raise NotImplementedError(
"The static IPC trainer path has been replaced by "
"IPCTrainerWeightTransferEngine. Build it via "
"WeightTransferTrainerFactory.trainer_init(IPCTrainerInitInfo(...), "
"client=..., source=...) and drive it with send_weights()."
)
class IPCTrainerWeightTransferEngine(TrainerWeightTransferEngine[IPCTrainerInitInfo]):
"""Trainer-side CUDA IPC weight transfer engine.
@@ -5,7 +5,7 @@
from collections.abc import Iterator
from concurrent.futures import ThreadPoolExecutor
from dataclasses import asdict, dataclass
from typing import TYPE_CHECKING, Any, ClassVar
from typing import TYPE_CHECKING, ClassVar
import torch
from typing_extensions import Self
@@ -226,21 +226,6 @@ class NCCLWeightTransferEngine(
# Clean up the communicator by removing the reference
self.model_update_group = None
@staticmethod
def trainer_send_weights(*args: Any, **kwargs: Any) -> None:
"""Removed. Use the stateful `NCCLTrainerWeightTransferEngine` instead.
Transitional stub kept only to satisfy the (still abstract)
`WeightTransferEngine.trainer_send_weights`; that member is dropped from
the worker ABC once every backend has migrated to the trainer engine.
"""
raise NotImplementedError(
"The static NCCL trainer path has been replaced by "
"NCCLTrainerWeightTransferEngine. Build it via "
"WeightTransferTrainerFactory.trainer_init(NCCLTrainerInitInfo(...), "
"client=..., source=...) and drive it with send_weights()."
)
class NCCLTrainerWeightTransferEngine(TrainerWeightTransferEngine[NCCLTrainerInitInfo]):
"""Trainer-side NCCL weight transfer engine.
@@ -17,7 +17,7 @@ MVP limitations:
from collections.abc import Iterable
from concurrent.futures import ThreadPoolExecutor
from dataclasses import asdict, dataclass
from typing import TYPE_CHECKING, Any, ClassVar
from typing import TYPE_CHECKING, ClassVar
import torch
from typing_extensions import Self
@@ -227,22 +227,6 @@ class SparseNCCLWeightTransferEngine(
if self.model_update_group is not None:
self.model_update_group = None
@staticmethod
def trainer_send_weights(*args: Any, **kwargs: Any) -> None:
"""Removed. Use the stateful `SparseNCCLTrainerWeightTransferEngine`.
Transitional stub kept only to satisfy the (still abstract)
`WeightTransferEngine.trainer_send_weights`; that member is dropped from
the worker ABC once every backend has migrated to the trainer engine.
"""
raise NotImplementedError(
"The static sparse NCCL trainer path has been replaced by "
"SparseNCCLTrainerWeightTransferEngine. Build it via "
"WeightTransferTrainerFactory.trainer_init("
"SparseNCCLTrainerInitInfo(...), client=..., source=...) and drive "
"it with send_weights()."
)
class SparseNCCLTrainerWeightTransferEngine(
TrainerWeightTransferEngine[SparseNCCLTrainerInitInfo]