# Parameter Optimizer: Bayesian Parameter Tuning

> Learn how to use the Parameter Optimizer to find optimal LLM call parameters (temperature, top_p, etc.) using Bayesian optimization without changing your prompt.

The `ParameterOptimizer` uses Bayesian optimization to tune LLM call parameters such as temperature, top\_p, frequency\_penalty, and other sampling parameters. Unlike other optimizers that modify the prompt itself, this optimizer keeps your prompt unchanged and focuses solely on finding the best parameter configuration for your specific task.

<Note>
  **When to Use:** Optimize LLM parameters (temperature, top\_p) without changing your prompt. Best when you have a good prompt but need to tune model behavior.

  **Key Trade-offs:** Requires defining parameter search space; doesn't modify prompt text; uses two-phase Bayesian search.
</Note>

<Info>
  Have questions about `ParameterOptimizer`? Our [Optimizer & SDK FAQ](/agent_optimization/faq)
  answers common questions, including when to use this optimizer, how parameters like `default_n_trials` and `local_search_ratio`
  work, and how to define custom parameter search spaces.
</Info>

## How It Works

This optimizer uses [Optuna](https://optuna.org/), a hyperparameter optimization framework, to search for the best LLM parameters:

1. **Baseline Evaluation**: First evaluates your prompt with its current parameters (or default parameters) to establish a baseline score.

2. **Parameter Space Definition**: You define which parameters to optimize and their valid ranges using a `ParameterSearchSpace`. For example:
   * `temperature`: float between 0.0 and 2.0
   * `top_p`: float between 0.0 and 1.0
   * `frequency_penalty`: float between -2.0 and 2.0

3. **Global Search Phase**:
   * Optuna explores the full parameter space using Bayesian optimization (TPESampler by default).
   * Tries various parameter combinations to find promising regions.
   * Evaluates each combination against your dataset using the specified metric.

4. **Local Search Phase** (optional):
   * After global search, focuses on the best parameter region found.
   * Performs fine-grained optimization around the best parameters.
   * Controlled by `local_search_ratio` and `local_search_scale`.

5. **Parameter Importance Analysis**:
   * Calculates which parameters had the most impact on performance.
   * Uses FANOVA importance (requires scikit-learn) or falls back to correlation-based sensitivity analysis.

6. **Result**: Returns the best parameter configuration found, along with detailed optimization history and parameter importance rankings.

The optimizer intelligently balances exploration (trying diverse parameters) with exploitation (refining promising configurations) to efficiently find optimal settings.

<Tip>
  The core of this optimizer relies on robust evaluation where each parameter configuration is assessed using your `metric` against the `dataset`. Understanding Opik's evaluation platform is key to effective use:

  * [Evaluation Overview](/evaluation/overview)
  * [Evaluate Prompts](/evaluation/evaluate_prompt)
  * [Metrics Overview](/evaluation/metrics/overview)
</Tip>

## Configuration Options

### Basic Configuration

```python
from opik_optimizer import ParameterOptimizer
from opik_optimizer.algorithms.parameter_optimizer.parameter_search_space import (
    ParameterSearchSpace,
)

optimizer = ParameterOptimizer(
    model="openai/gpt-4",
    default_n_trials=20,    # Number of optimization trials
    n_threads=4,            # Parallel evaluation threads
    seed=42
)
```

### Advanced Configuration

```python
optimizer = ParameterOptimizer(
    model="openai/gpt-4",
    default_n_trials=50,        # More trials for thorough optimization
    n_threads=8,                # More parallel threads
    local_search_ratio=0.3,     # 30% of trials for local refinement
    local_search_scale=0.2,     # Scale of local search range
    seed=42,
    verbose=1                   # Verbosity level (0=off, 1=info, 2=debug)
)
```

The key parameters are:

* `model`: The LLM used for evaluation with different parameter configurations.
* `default_n_trials`: Default number of optimization trials (can be overridden in `optimize_parameter`).
* `n_threads`: Number of parallel threads for evaluation (balance with API rate limits).
* `local_search_ratio`: Ratio of trials dedicated to local search around best parameters (0.0-1.0).
* `local_search_scale`: Scale factor for local search range (0.0 = no local search, higher = wider range).
* `seed`: Random seed for reproducibility.
* `verbose`: Logging level (0=warnings only, 1=info, 2=debug).

## Example Usage

### Basic Example

```python
from opik_optimizer import ParameterOptimizer, ChatPrompt
from opik_optimizer.algorithms.parameter_optimizer.parameter_search_space import (
    ParameterSearchSpace,
)
from opik.evaluation.metrics import LevenshteinRatio
from opik_optimizer import datasets