ForgeActor#

The actors module contains the core components for model training and inference in TorchForge. These pre-built actors provide essential functionality for reinforcement learning workflows and can be used as building blocks for complex distributed training systems.

class forge.controller.actor.ForgeActor(*args, **kwargs)[source]#

Bases: Actor

Base class for Forge actors with configurable resource attributes.

The initialization sets up logging configuration with rank/size information and initializes the actor’s process mesh reference. The rank and size are automatically determined from the current execution context.

Parameters:

*args – Variable length argument list passed to the parent Actor class.
**kwargs – Arbitrary keyword arguments passed to the parent Actor class.

async classmethod as_actor(*args, **actor_kwargs)[source]#

Spawns a single actor using the configuration stored in .options(), or defaults.

The configuration values stored in the subclass returned by .options() (like procs) are used to construct a ProcessConfig instance. If no configuration was stored, defaults to a single process with no GPU.

Return type:: TypeVar(T, bound= ForgeActor)

hosts = None#: Number of hosts to distribute the actor across. If None, uses as many hosts as needed to accommodate the requested processes. Defaults to None.

async classmethod launch(*args, **kwargs)[source]#

Provisions and deploys a new actor.

This method is used by Service to provision a new replica.

We implement it this way because special actors like inference servers may be composed of multiple actors spawned across multiple processes. This allows you to specify how your actor gets launched together.

This implementation is basic, assuming that we’re spawning a homogeneous set of actors on a single proc mesh.

Return type:: ActorMesh

mesh_name = None#: Optional name for the process mesh used by this actor. If None, a default name will be generated. Defaults to None.

num_replicas = 1#: Number of replicas to create when spawning as a service. Only applies when using as_service(). Defaults to 1.

classmethod options(*, procs=1, hosts=None, with_gpus=False, num_replicas=1, mesh_name=None, **kwargs)[source]#

Returns a version of ForgeActor with configured resource attributes.

This method allows you to pre-configure an actor class before spawning it with .as_actor() or .as_service(). Each call creates a separate subclass, so multiple different configurations can coexist without interfering with each other.

Examples: :rtype: Type[TypeVar(T, bound= ForgeActor)]

Pre-configure a service with multiple replicas:

service = await MyForgeActor.options(num_replicas=2, procs=2).as_service(...)
await service.shutdown()

Default usage without calling options:

service = await MyForgeActor.as_service(...)
await service.shutdown()

Pre-configure a single actor

actor = await MyForgeActor.options(procs=1, hosts=1).as_actor(...)
await actor.shutdown()

Default usage without calling options

actor = await MyForgeActor.as_actor(...)
await MyForgeActor.shutdown(actor)

procs = 1#: Number of processes to use for this actor. Defaults to 1.

async classmethod shutdown(actor)[source]#: Shuts down an actor. This method is used by Service to teardown a replica.

with_gpus = False#: Whether to allocate GPU resources for this actor. Defaults to False.