Optim-Agent：用编程智能体革新超参调优

当调参变成"苦力活"：一个真实困境

一位算法工程师正在训练一个推荐模型，实验跑了三天三夜后宣告失败——学习率设错了。更让人沮丧的是，这已经是本月第三次"低级失误"导致的实验报废。手动调参不仅耗时，更容易因为人脑的认知偏差（锚定效应、确认偏误）错过最优配置。

Optim-Agent 正是为解决这类痛点而生：它让 AI 编程智能体（Claude Code、Codex、OpenCode）扮演"超参猎人"，通过阅读代码理解每个参数的语义含义，再结合历史试验数据，智能地提出下一组候选配置。整个过程由目标函数的实测结果驱动，而非智能体的主观直觉。

图：optim-agent 的核心调优循环——智能体读代码、提方案、跑实验、记录结果，周而复始直到预算耗尽。

项目背景：从"黑箱优化"到"语义感知"

超参优化（Hyperparameter Optimization，HPO）并非新问题。Optuna、Ray Tune、Hyperopt 等框架早已存在，它们用贝叶斯优化、随机搜索、TPE 等算法自动探索参数空间。然而，这些方法有一个共同缺陷：把每个参数当作匿名坐标处理，完全忽略参数本身的语义——"学习率 0.001"和"正则化强度 0.001"在数学上无区别，但人类工程师知道它们代表完全不同的意义。

Optim-Agent 的核心创新在于引入语义层：让编程智能体阅读目标代码，理解每个参数代表什么物理意义、历史试验揭示了什么规律，从而提出更有信息量的候选值。这在小预算（≤20 次试验）场景下优势尤为明显，因为经典贝叶斯代理在数据不足时表现平庸，而语义推理不依赖历史数据。

核心机制：ask/tell API + 智能体工作流

Optim-Agent 提供简洁的 Python API：

import optim_agent as oa

def objective(trial):
    threshold = trial.suggest_float(
        "threshold", 0.05, 0.95,
        context="决策阈值；值越高召回越低精确率越高",
    )
    budget = trial.suggest_int(
        "budget", 10, 200, log=True,
        context="计算预算；值越大质量可能越好",
    )
    return evaluate_system(threshold=threshold, budget=budget)

study = oa.create_study(
    direction="maximize",
    sampler=oa.AgentSampler(backend="claude"),  # 或 codex、opencode
)
study.optimize(objective, n_trials=20)

AgentSampler 是核心采样器，它调用底层智能体 CLI（Claude Code / Codex / OpenCode），让智能体读取项目代码、理解参数含义，再生成候选配置。所有试验数据（配置、结果、上下文）以 JSON/SQLite 格式存档，可供后续分析和可视化。

采样器家族

基准测试：有数据支撑的能力宣言

Optim-Agent 在三个基准上进行了严格对照实验：

• 硬函数优化：无上下文条件下的全局最优化（Rosenbrock、Styblinski-Tang 等经典函数），小预算（≤20 次试验）显著优于 Random 和 TPE。
• 信用卡违约预测：基于 UCI 数据集的表格学习任务，对比有无语义上下文的情况下，GPT-5.5 上下文方案的验证集对数损失优于无上下文方案。
• 强化学习控制：Acrobot-v1 和 LunarLander-v3 上的 RL 策略调优，上下文方案在两个环境均值上均获胜。

部署难度：几乎零门槛

Optim-Agent 是一个纯 Python CLI 工具，安装方式极为简单：

# 方式一：pip 一键安装（推荐）
python -m pip install optim-agent

# 方式二：Claude Code Plugin
claude plugin marketplace add Optim-Agent/optim-agent && claude plugin install optim-agent@optim-agent

# 方式三：Codex Skill
skill-installer install https://github.com/Optim-Agent/optim-agent

唯一前提是系统上装有 Python >= 3.9，以及一个已认证的智能体 CLI（claude / codex / opencode）。无 GPU 要求，无特殊依赖，pip 安装即用。

缺点：没有 Docker 支持，不适合追求环境隔离或已在容器化环境中运行的团队。

技术架构：小而专注

项目结构清晰，核心代码仅 8 个文件：

• agent.py：AgentSampler——调用外部智能体 CLI 的桥梁
• study.py：create_study() 工厂函数，管理试验存储
• samplers.py：内置采样器（Random、TPE、AgentSampler）
• pruners.py：提前终止策略（基于试验结果的动态剪枝）
• space.py：参数空间定义（支持 float、int、categorical、log）
• summarizer.py：试验历史摘要生成
• reporting.py：结果报告与可视化

代码质量方面，使用 ruff 进行 linting（目标版本 py39），有 pre-commit 配置，pytest 测试框架，但当前处于 alpha 阶段（版本 0.2.0），测试覆盖率尚未公开。

局限性：不回避的坦诚

• 智能体依赖：必须依赖 Claude Code / Codex / OpenCode 三者之一，调用 API 有成本。
• alpha 阶段：API 尚未稳定（版本 0.2.0），大规模生产使用需谨慎。
• 无持久化 Web-UI：纯 CLI 工具，没有图形化界面来查看试验曲线。
• 上下文窗口限制：极长参数描述或复杂搜索空间可能超出智能体的上下文容量。
• 中文文档虽全，但实战案例偏少：Quickstart 示例较为基础，实际调优案例（尤其是中文场景）有待丰富。

行业意义：重新定义 AutoML 的边界

传统的 AutoML 工具追求"完全自动化"——用户不需要懂机器学习也能获得不错的模型。但 Optim-Agent 走的是另一条路：自动化程度更低，但智能程度更高。它假设用户是懂代码的工程师，提供的是一个"智能协作者"而非"端到端解决方案"。

这一设计哲学与当下 AI Coding 浪潮高度吻合。当 Claude Code、Codex 等工具已经能读懂代码、理解业务逻辑时，让它们参与超参调优是自然延伸。更重要的是，随着底层模型能力提升（GPT-5.5 → GPT-5.6），optim-agent 的提案质量也会同步提升，无需修改一行代码——这在传统贝叶斯优化框架中是不可想象的。