# How to Configure Hyperparameters for TensorFlow Models in the `tensorflow/models` Repository

> Learn how to configure hyperparameters for TensorFlow models in the tensorflow models repository. Easily override defaults for optimal performance.

- Repository: [tensorflow/models](https://github.com/tensorflow/models)
- Tags: how-to-guide
- Published: 2026-02-28

---

**To configure hyperparameters in the tensorflow/models repository, use the `create_hparams()` factory function in [`research/object_detection/model_hparams.py`](https://github.com/tensorflow/models/blob/main/research/object_detection/model_hparams.py) to instantiate an `HParams` object with sensible defaults, then override specific values by passing a comma-separated string of `name=value` pairs to the `hparams_overrides` parameter.**

The `tensorflow/models` repository provides a standardized pattern for managing model configurations through the `tf.contrib.training.HParams` class (and its TensorFlow 2-compatible equivalents). This approach centralizes default values while allowing flexible runtime overrides without modifying source code.

## Core Hyperparameter Configuration Pattern

The repository follows a three-step convention for hyperparameter management that ensures consistency across object detection and other model pipelines.

### Defining Defaults in create_hparams()

All default hyperparameters originate in the `create_hparams()` function located in **[`research/object_detection/model_hparams.py`](https://github.com/tensorflow/models/blob/main/research/object_detection/model_hparams.py)**. This function constructs an `HParams` instance with sensible baseline values for the training pipeline.

```python

# research/object_detection/model_hparams.py

def create_hparams(hparams_overrides=None):
    hparams = contrib_training.HParams(
        # Default hyperparameters

        load_pretrained=True,
        learning_rate=0.0003
    )
    return hparams

```

The `HParams` object serves as the single source of truth for the object-detection pipeline's configuration, encapsulating fields such as `load_pretrained` and `learning_rate` that downstream training code will reference.

### Applying Overrides via String Parsing

Runtime customization occurs through the `hparams_overrides` parameter, which accepts a comma-separated string of `name=value` pairs. The `create_hparams()` function parses this string at lines 48-49 to update the default configuration:

```python
if hparams_overrides:
    hparams = hparams.parse(hparams_overrides)

```

For example, passing `'load_pretrained=false,learning_rate=0.001'` updates both fields while preserving other defaults. This string-parsing approach enables straightforward command-line integration without requiring complex configuration file edits.

### Consuming HParams in Training Code

Once instantiated and optionally modified, the `HParams` object propagates to the training routine. Code throughout the repository accesses specific configuration values through attribute notation (e.g., `hparams.load_pretrained`), ensuring type-safe access to hyperparameters during model initialization and training loops.

## Practical Implementation Examples

The test suite in **[`research/object_detection/model_lib_tf1_test.py`](https://github.com/tensorflow/models/blob/main/research/object_detection/model_lib_tf1_test.py)** demonstrates canonical usage patterns that you can replicate in custom training scripts.

### Basic Programmatic Usage

Import the module and instantiate hyperparameters with overrides directly in Python:

```python
from research.object_detection import model_hparams

# Override via string (e.g., from a CLI flag)

override_str = "load_pretrained=false,learning_rate=0.0005"
hparams = model_hparams.create_hparams(hparams_overrides=override_str)

# Access values

print(hparams.load_pretrained)  # False

print(hparams.learning_rate)    # 0.0005

# Pass to training routine

train_model(hparams)

```

### Command-Line Override Pattern

Training scripts typically expose a `--hparams_overrides` flag that forwards arguments to the factory function:

```bash
python train.py \
  --model_dir=/tmp/my_model \
  --pipeline_config_path=ssd_mobilenet_v2/pipeline.config \
  --hparams_overrides="load_pretrained=false,learning_rate=0.001"

```

The script receives the string and passes it to `create_hparams()`, allowing you to adjust training behavior without modifying the underlying `pipeline.config` file.

### Adding Custom Hyperparameters

To extend the configuration schema, modify the `HParams` constructor in [`model_hparams.py`](https://github.com/tensorflow/models/blob/main/model_hparams.py):

```python

# research/object_detection/model_hparams.py

def create_hparams(hparams_overrides=None):
    hparams = contrib_training.HParams(
        load_pretrained=True,
        learning_rate=0.0003,
        my_custom_flag=False)  # New custom field

    if hparams_overrides:
        hparams = hparams.parse(hparams_overrides)
    return hparams

```

You can now override your custom field via command line:

```bash
python train.py --hparams_overrides="my_custom_flag=true,learning_rate=0.0001"

```

## TensorFlow Version Compatibility

The repository handles version differences through a compatibility shim. At lines 25-29 in [`model_hparams.py`](https://github.com/tensorflow/models/blob/main/model_hparams.py), the code attempts to import `tf.contrib.training.HParams` (TensorFlow 1.x) and falls back to the TensorFlow 2 implementation when `tensorflow.contrib` is unavailable. This ensures that hyperparameter configuration works across both TF 1.x and TF 2.x environments without breaking existing override strings or configuration patterns.

## Summary

- **Centralized defaults** are defined in [`research/object_detection/model_hparams.py`](https://github.com/tensorflow/models/blob/main/research/object_detection/model_hparams.py) via the `create_hparams()` factory function.
- **Runtime overrides** use comma-separated `name=value` strings passed to the `hparams_overrides` parameter.
- **String parsing** occurs through the `HParams.parse()` method, enabling command-line and programmatic configuration.
- **Version compatibility** is handled automatically through try/except blocks supporting both TF 1.x and TF 2.x.
- **Extensibility** requires only adding new arguments to the `HParams` constructor and referencing them in downstream code.

## Frequently Asked Questions

### How do I override multiple hyperparameters at once?

Pass a single comma-separated string containing all desired modifications to the `hparams_overrides` parameter. For example: `'load_pretrained=false,learning_rate=0.001,batch_size=32'`. The `HParams.parse()` method processes each `name=value` pair sequentially, updating the defaults while leaving unspecified parameters unchanged.

### Where are hyperparameter defaults defined in tensorflow/models?

Default values are hardcoded in the `create_hparams()` function within **[`research/object_detection/model_hparams.py`](https://github.com/tensorflow/models/blob/main/research/object_detection/model_hparams.py)**. This file serves as the central registry for object detection pipeline configurations, though other model families (such as NASNet in `research/slim/nets/nasnet/`) may implement similar patterns in their respective utility files.

### How does the repository handle TensorFlow 2.x compatibility for HParams?

The implementation includes a compatibility layer at lines 25-29 that attempts to import `tf.contrib.training.HParams` for TensorFlow 1.x, then falls back to the native TensorFlow 2 `HParams` implementation if the contrib module is unavailable. This ensures that hyperparameter parsing and override functionality remains consistent across framework versions.

### Can I add custom hyperparameters to existing models?

Yes. Add new arguments to the `contrib_training.HParams()` constructor inside `create_hparams()`, then reference those fields in your training or model code. Once defined, you can override the new parameters using the same comma-separated string format as built-in options (e.g., `'my_custom_flag=true'`).