Inconsistent config key names in Tune results

RLlib
1

Hello, when running RLlib experiments through Ray Tune, the configuration stored in trial results sometimes uses different key names than the public RLlib API. For example, when setting:

config.training(
    lr=0.0001,
    gamma=0.999,
    train_batch_size_per_learner=4000,
)

the resulting Tune trial config contains:

{
    "lr": 0.0001,
    "gamma": 0.999,
    "_train_batch_size_per_learner": 4000,  # different name than input parameter
}

This seems to be due to internal storage using private attributes (e.g. _train_batch_size_per_learner) in AlgorithmConfig that are directly serialized.

In my case, I am running HPO experiments and retrieving hyperparameters from the Tune result dict using the input parameter names. This works for most parameters, but not for train_batch_size_per_learner for example because of the naming mismatch.

Of course this is not a big issue and I can find an easy workaround, but is this behavior intentional ? And would it make sense to align the config keys with the public API names for consistency ?

Thanks!

1. Severity of the issue: (select one)
None: I’m just curious or want clarification.
Low: Annoying but doesn’t hinder my work.
Medium: Significantly affects my productivity but can find a workaround.
High: Completely blocks me.

2. Environment:

  • Ray version: 2.53.0
  • Python version: 3.12.12
  • OS: macOS
  • Cloud/Infrastructure: Local
  • Other libs/tools (if relevant):

3. What happened vs. what you expected:

  • Expected: same keys as input parameters in Ray Tune result dict
  • Actual: different names
2

It seems likely that this behavior is intentional and results from how RLlib’s AlgorithmConfig serializes its internal state, sometimes using private attribute names (e.g., _train_batch_size_per_learner) rather than the public API parameter names. This can cause mismatches between the keys you set in your config and the keys stored in the Tune trial results, as you’ve observed. The underlying reason is that AlgorithmConfig may store and serialize both public and private attributes, and the serialization logic does not always map private/internal names back to their public API equivalents automatically. This is not explicitly documented as a bug, but rather appears to be a side effect of the current implementation and serialization approach in RLlib and Ray Tune configs, as discussed in the code and related issues (algorithm_config.py, algorithm_config.py 2.36.0).

My understanding is that, while this is not a major issue and workarounds exist (such as mapping your parameter names to the stored keys), it could be improved for consistency and user experience. There is no explicit statement in the data sources that this will be changed, but aligning the config keys with the public API names would likely make sense for clarity, especially for users doing HPO or programmatic analysis of results. If this is a significant pain point, you might consider opening a feature request or issue on the Ray GitHub to suggest this improvement.

Would you like more detail on how to programmatically map or handle these key mismatches in your workflow?

Sources:

Hint: Mention @RunLLM in the post for followups.