# البحث عن المعلمات الفائقة

تؤثر المعلمات الفائقة مثل معدل التعلم وحجم الدفعة وعدد الفترات بشكل كبير على نتائج التدريب. يجد [Trainer.hyperparameter_search()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.hyperparameter_search) أفضل تركيبة من خلال تشغيل تجارب متعددة، كل منها بمجموعة مختلفة من القيم، وإرجاع الأفضل منها.

يُهيّئ كل تجربة نموذجًا جديدًا باستخدام `model_init`، ويستخرج معاملات خوارزمية جديدة، وينفّذ حلقة تدريب كاملة، ثم يُبلّغ الخلفية البحثية بقيمة الهدف. وتستخدم الخلفية البحثية كل قيمة هدف لتوجيه التجربة التالية. وبعد اكتمال جميع التجارب، تُعاد أفضل المعاملات الخوارزمية في `~trainer.utils.BestRun`.

## تهيئة نموذج

ابدأ كل تجربة بنموذج جديد لتجنّب حالة التشغيلات السابقة. يُستدعى `model_init` في بداية كل تجربة ويعيد نسخة جديدة من النموذج، لذا تبدأ كل تجربة من نفس الأوزان الأولية.

```py
from transformers import AutoModelForCausalLM

def model_init(trial):
    return AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")

trainer = Trainer(
    model_init=model_init,
    args=args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)
```

لا تقم بتمرير `model=` و`model_init=` معًا، وإلا سيُطلق [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) خطأً.

## تعريف مساحة البحث

أنشئ دالة تُعرّف مساحة البحث. يعتمد التنسيق على الخلفية (backend). إذا لم تُعرّف دالة `hp_space`، فإن البحث الافتراضي يغطي `learning_rate` و`num_train_epochs` و`per_device_train_batch_size`.

```bash
# install one of these hyperparam search backends
pip install optuna
pip install wandb
pip install ray[tune]
```

[Optuna](https://optuna.readthedocs.io/en/stable/index.html) هو إطار عمل خفيف لتحسين المعلمات الفائقة.

```py
def hp_space(trial):
    return {
        "learning_rate": trial.suggest_float("learning_rate", 1e-6, 1e-4, log=True),
        "per_device_train_batch_size": trial.suggest_categorical("per_device_train_batch_size", [16, 32, 64, 128]),
    }
```

[Ray Tune](https://docs.ray.io/en/latest/tune/index.html) هو مكتبة قابلة للتوسع لضبط المعلمات الفائقة، كما يمكنها توزيع التجارب عبر عدة أجهزة.

```py
from ray import tune

def hp_space(trial):
    return {
        "learning_rate": tune.loguniform(1e-6, 1e-4),
        "per_device_train_batch_size": tune.choice([16, 32, 64, 128]),
    }
```

[Weights & Biases](https://docs.wandb.ai/) هو منصة لتتبع التجارب تتضمن بحثًا مدمجًا في المعلمات الفائقة. يدعم استراتيجيات البحث البايزي والعشوائي والشبكي.

```py
def hp_space(trial):
    return {
        "method": "random",
        "metric": {"name": "objective", "goal": "minimize"},
        "parameters": {
            "learning_rate": {"distribution": "uniform", "min": 1e-6, "max": 1e-4},
            "per_device_train_batch_size": {"values": [16, 32, 64, 128]},
        },
    }
```

## Run the search

قدّم دالة `compute_objective` اختيارية لتعريف هدف التحسين. يكون الافتراضي `eval_loss` إذا كانت موجودة، وإلا فيكون مجموع جميع قيم المقاييس. مرّر دالة صريحة لتجنب الاعتماد على هذا الخيار الاحتياطي. يحسّن `backend` البحث الهدف على مدى `n_trials` تشغيلات في `direction` محددة.

```py
def compute_objective(metrics):
    return metrics["eval_loss"]

best_run = trainer.hyperparameter_search(
    hp_space=hp_space,
    compute_objective=compute_objective,
    n_trials=30,               # how many trials to run
    direction="minimize",      # or "maximize" for metrics like accuracy/F1
    backend="optuna",          # "optuna", "ray", or "wandb"
)
```

يعيد [hyperparameter_search()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.hyperparameter_search) كائنًا من نوع `~trainer.utils.BestRun` يحتوي على قيمة الدالة الهدف وأفضل تركيبة للمعاملات الفائقة.

```py
best_run = trainer.hyperparameter_search(...)

best_run.objective        # 0.38  (best eval loss)
best_run.hyperparameters  # {"learning_rate": 5e-5, "num_train_epochs": 4, ...}
```

طبّق أفضل المعاملات الفائقة على [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) وأعد التدريب على مجموعة البيانات الكاملة.