Optuna 怎样用 enqueue_trial 先尝试指定参数组合

如果你已经有一组经验参数，又不想完全放弃 Optuna 的自动搜索，可以先调用 Study.enqueue_trial()，把指定的参数字典排进试验队列，再调用 study.optimize()。这样 objective 仍然使用 trial.suggest_* 读取参数，但前几次试验会优先评估人工指定的组合；队列消费完后，后续试验再由 sampler 选择。

最小做法是：先创建 Study，连续调用 enqueue_trial({参数名: 参数值})，最后用足够大的 n_trials 执行优化。需要防止同一组合重复入队时，传入 skip_if_exists=True。

官方参考地址：https://optuna.readthedocs.io/en/stable/reference/generated/optuna.study.Study.html

先把人工组合放进试验队列

enqueue_trial() 接收一个参数字典，键名必须和 objective 中的 suggest_* 名称对应。下面用两个浮点参数表示学习率和树深度；示例只表达调用关系，不把静态图当作实际运行截图。

import optuna


def objective(trial):
    # 参数名要与 enqueue_trial 传入的字典键保持一致
    learning_rate = trial.suggest_float("learning_rate", 0.001, 0.2, log=True)
    depth = trial.suggest_int("depth", 2, 8)
    # 这里替换成真实模型训练后的验证集损失
    return (learning_rate - 0.03) ** 2 + (depth - 5) ** 2 * 0.01


study = optuna.create_study(direction="minimize")
study.enqueue_trial({"learning_rate": 0.01, "depth": 4})
study.enqueue_trial({"learning_rate": 0.03, "depth": 5})

# 前两个试验优先消费队列，后续试验再由 sampler 选择
study.optimize(objective, n_trials=6)

关键点是 enqueue_trial() 只负责安排参数，不会直接调用 objective，也不会返回一个已经完成的 Trial。真正的评估发生在 optimize() 中。若设置了 n_trials=6，上面的两个排队组合会占用其中两个试验名额。

为什么仍然要在 objective 中 suggest 参数

入队参数不是另一套配置系统。它们最终仍要经过 objective 的参数声明，Optuna 才能把字典值放到对应的 Trial 中，并依据 suggest 方法的分布范围管理试验。不要把参数直接写死在 objective 里，否则后续 sampler 就无法继续探索。

def objective(trial):
    # suggest_float 声明取值范围，队列值也必须落在这个范围内
    dropout = trial.suggest_float("dropout", 0.0, 0.5)
    width = trial.suggest_categorical("width", [128, 256, 512])

    try:
        score = train_and_evaluate(dropout=dropout, width=width)
    except RuntimeError as exc:
        # 训练失败交给 Optuna 标记当前试验，生产代码应记录必要上下文
        raise optuna.TrialPruned(f"训练不可用：{exc}") from exc
    return score

如果队列中给出的值不符合对应分布，例如分类参数不在候选列表中，试验会在参数分布校验处失败。实际项目应先统一参数名称、类型和允许范围，再生成入队字典。

用 skip_if_exists 控制重复组合

同一进程里反复执行初始化代码时，默认行为可能把相同参数再次加入队列。可以让 Optuna 在已有相同参数时跳过入队：

candidates = [
    {"learning_rate": 0.01, "depth": 4},
    {"learning_rate": 0.03, "depth": 5},
]

for params in candidates:
    # 已存在相同参数时跳过，避免重复消耗试验名额
    study.enqueue_trial(params, skip_if_exists=True)

study.optimize(objective, n_trials=len(candidates) + 4)

skip_if_exists 比较的是试验参数，不是你业务上的实验名称。分布式进程同时以相同参数入队时，仍可能出现重复，所以并发任务需要依赖共享 storage 的事务语义，并把“可能重复”纳入结果处理；不要仅凭本地列表做去重。

几个容易混淆的边界

• 入队不等于固定全部试验：只固定队列中的组合，队列为空后仍可由 sampler 生成新参数。
• 参数名必须一致：enqueue_trial({"depth": 4}) 只对 objective 中名为 depth 的建议有效。
• 组合必须在分布内：浮点范围、整数范围和 categorical 候选都要覆盖人工值。
• 控制预算：n_trials 是总试验数，应该大于等于计划中的人工组合数。
• 多进程要谨慎：共享数据库可以支持并发优化，但同时入队同一参数时仍要接受重复试验的可能。

常见问题

enqueue_trial 会跳过 objective 吗？

不会。它只把参数安排到队列，后续仍由 study.optimize() 调用 objective 完成评估。

队列参数评估后还会继续自动搜索吗？

会。队列中的试验完成后，剩余试验仍由 Study 配置的 sampler 选择。

skip_if_exists 能完全保证分布式不重复吗？

不能完全保证。多个进程在相近时间提交相同参数时，仍可能出现重复试验，结果处理应具备幂等性。