Configuration Reference

Overview

Configure the Arctic RL client with backend, communication protocol, model, and GPU resource settings through the ArcticRLClientConfig model. This page documents all available configuration options for initializing and tuning the platform.

Configuration Reference

ArcticRLClientConfig

The ArcticRLClientConfig class defines all configuration options for the Arctic RL client. Use this model to customize backend selection, communication protocol, GPU allocation, training parameters, and timeout behavior.

Backend & Communication

Field	Type	Default	Description
`backend`	`"local"` \| `"dss-platform"`	`"local"`	Backend platform for job execution.
`comm_protocol`	`"http"` \| `"ray"`	`"http"`	Communication protocol between client and server.
`host`	`Optional[str]`	`None`	Server hostname. Auto-derived from `comm_protocol` unless explicitly set. For `http`, defaults to the primary network IP. For `ray`, remains `None`.
`port`	`Optional[int]`	`None`	Server port. Auto-derived from `comm_protocol` unless explicitly set. For `http`, defaults to `7000`. For `ray`, remains `None`.

Model & Checkpoint

Field	Type	Default	Description
`model_name`	`str`	(required)	Model name or HuggingFace ID to load on all engines.
`checkpoint_path`	`Optional[str]`	`None`	Path to model checkpoint for resuming training.

Engine Configuration

Field	Type	Default	Description
`ds_config`	`dict`	`{}`	DeepSpeed configuration for the training engine.
`training_config`	`Optional[dict]`	`None`	Training worker config (optimizer settings, dtype, gradient checkpointing, attention implementation, max tokens per microbatch, etc.). Standard fields include `optimizer` (lr, weight_decay, beta1, beta2, eps, lr_scheduler_type, gradient_clipping, warmup_steps_proportion/warmup_ratio), `dtype`, `gradient_checkpointing`, `attn_impl`, and `mb_spec`. Extra fields are ignored by the server.
`vllm_config`	`Optional[dict]`	`None`	vLLM / ModelConfig overrides for sampling and log-prob engines.
`log_prob_ds_config`	`Optional[dict]`	`None`	Log-prob DeepSpeed worker configuration (batch size, dtype, etc.).
`ds_worker_config`	`Optional[dict]`	`None`	DeepSpeed worker configuration (optimizer, dtype, etc.).
`arctic_inference_config`	`Optional[dict]`	`None`	Arctic inference configuration (use_fca, spec_model, etc.).

GPU Resources

Field	Type	Default	Description
`training_gpus`	`int`	`0`	Number of GPUs allocated to the DeepSpeed training engine.
`sampling_gpus`	`int`	`0`	Number of GPUs allocated to the vLLM sampling engine.
`log_prob_gpus`	`int`	`0`	Number of GPUs allocated to the log-prob engine.
`log_prob_engine`	`"vllm"` \| `"deepspeed"`	`"vllm"`	Engine backend for the log-prob job.
`colocate`	`bool`	`False`	If `True`, colocate training, sampling, and log-prob workers on the same GPUs using fractional Ray resources.

Training & Determinism

Field	Type	Default	Description
`full_determinism`	`bool`	`False`	If `True`, the DeepSpeed worker calls `enable_full_determinism()` for reproducible training.
`seed`	`int`	`42`	Seed used by `enable_full_determinism()` when `full_determinism=True`.

Ray Cluster & Startup

Field	Type	Default	Description
`ray_auto_attach`	`bool`	`True`	If `True`, the local server attempts to attach to a pre-existing Ray cluster (only honored when that cluster has GPU resources). Set to `False` to always start a fresh Ray cluster—useful when an unrelated CPU-only Ray cluster is running.
`server_logs`	`bool`	`True`	If `True`, display server subprocess stdout/stderr.
`startup_timeout`	`float`	`300.0`	Seconds to wait for the local server to become healthy during initialization.
`health_check_interval`	`float`	`2.0`	Seconds between health-check polls during server startup.
`job_ready_timeout`	`float`	`600.0`	Seconds to wait for each job (training, sampling, log-prob) to reach RUNNING state after `/initialize`.

Reconnection

Field	Type	Default	Description
`training_job_id`	`Optional[int]`	`None`	Job ID for reconnecting to an existing training job. Populated by `ArcticRLClient.reconnect_config()` and consumed in `ArcticRLClient.__init__()`. Not forwarded to `/initialize`.
`sampling_job_id`	`Optional[int]`	`None`	Job ID for reconnecting to an existing sampling job. Not forwarded to `/initialize`.
`log_prob_job_id`	`Optional[int]`	`None`	Job ID for reconnecting to an existing log-prob job. Not forwarded to `/initialize`.

Validation Rules

The configuration enforces the following rules:

Local Backend GPU Requirement: When using backend="local" and not in reconnect mode (training_job_id=None), at least one of training_gpus, sampling_gpus, or log_prob_gpus must be greater than 0.
Host/Port Auto-Derivation: When not explicitly set, host and port are automatically derived from comm_protocol:
- For "http": host is set to the primary routable IP of the current node, and port is set to 7000.
- For "ray": both host and port remain None.

WeightSyncConfig

The WeightSyncConfig class configures NCCL weight-transfer topology between training GPUs and inference replicas. This is used by WeightSyncCoordinator (a standalone utility, not part of the HTTP client).

Field	Type	Default	Description
`training_sharding`	`str`	`"dp"`	Training parallelism strategy: `"dp"` (data parallel) or `"fsdp"` (fully sharded data parallel).
`training_gpus`	`int`	`1`	Number of training GPUs.
`inference_replicas`	`int`	`1`	Number of inference replicas.
`inference_tp`	`int`	`1`	Tensor parallelism degree for inference replicas.
`base_port`	`int`	`29500`	Base port for NCCL communication.
`bucket_size`	`int`	`268435456` (256 MB)	Bucket size for weight synchronization in bytes.

Example Usage

from arctic_platform.rl.config import ArcticRLClientConfig

# Basic configuration with required fields
config = ArcticRLClientConfig(
    model_name="meta-llama/Llama-2-7b",
    training_gpus=4,
    sampling_gpus=2
)

# Advanced configuration with training customization
config = ArcticRLClientConfig(
    model_name="meta-llama/Llama-2-7b",
    backend="local",
    comm_protocol="http",
    training_gpus=4,
    sampling_gpus=2,
    log_prob_gpus=1,
    full_determinism=True,
    seed=123,
    training_config={
        "optimizer": {
            "lr": 1e-5,
            "weight_decay": 0.01,
            "lr_scheduler_type": "cosine"
        },
        "dtype": "bfloat16",
        "gradient_checkpointing": True
    },
    startup_timeout=600.0,
    job_ready_timeout=900.0
)

# Reconnecting to existing jobs
config = ArcticRLClientConfig(
    model_name="meta-llama/Llama-2-7b",
    training_job_id=42,
    sampling_job_id=43,
    log_prob_job_id=44,
    host="192.168.1.100",
    port=7000
)