optim-agent
使用编程智能体进行智能体系统优化。
自动化算法工程师的迭代参数调优工作。
English |
简体中文 |
日本語 |
한국어 |
Français |
Deutsch |
Español |
Português |
Русский
optim-agent 允许 Claude Code / Codex / OpenCode 通过阅读你的代码、提出试验并记录测得的目标结果，来调整真实的系统参数。
当你的系统暴露出可配置的参数和可度量的目标时，即可使用它。
它会将每个参数的*含义*与试验历史*显示*的内容结合起来，
然后提出下一个要评估的配置。目标评估仍然具有权威性：optim-agent 提出参数值，根据声明的参数空间验证它们，
记录结果，并在智能体回复无效时回退到安全采样。
| 模型 | 系统 | 研究 |
|---|---|---|
| 训练、架构和 RL 实验 | 推理、延迟、成本、控制和决策规则 | 量化信号、模拟和科学工作流 |
## 为什么选择 optim-agent
- **语义化建议** - 编程智能体会对参数含义进行推理，研究
上下文和观察到的结果，而不是将每个维度视为
匿名坐标。
- **低预算杠杆** - 在评估成本高昂且经典
代理模型仍缺乏数据时非常有用。
- **智能体 CLI 的优势** - 建议质量可以随着底层编程
智能体的改进而提升，例如从 GPT-5.5 升级到 GPT-5.6，而无需更改你的
优化代码。
- **可审计的决策** - JSON/SQLite 研究记录会保留配置、
结果、状态、上下文和可选的智能体理由。
- **受限执行** - 智能体仅提出参数值；optim-agent 会
根据声明的参数空间验证它们，无效输出会
回退到安全采样。
## 安装
安装 Codex 技能：
```
$skill-installer install https://github.com/Optim-Agent/optim-agent
```
安装 Claude Code 插件：
```
claude plugin marketplace add Optim-Agent/optim-agent && claude plugin install optim-agent@optim-agent
```
安装 Python 包：
```
# 来自 PyPI 的稳定版本
python -m pip install optim-agent
# 来自 GitHub 的最新源码
python -m pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"
```
要求在 `PATH` 上有一个经过身份验证的智能体 CLI：
[claude](https://docs.anthropic.com/en/docs/claude-code)、
[codex](https://github.com/openai/codex) 或
[opencode](https://github.com/sst/opencode)。
## 快速开始
```
import optim_agent as oa
def objective(trial):
threshold = trial.suggest_float(
"threshold", 0.05, 0.95,
context="decision threshold; higher values trade recall for precision",
)
budget = trial.suggest_int(
"budget", 10, 200, log=True,
context="compute or operating budget; larger values may improve quality",
)
return evaluate_system(threshold=threshold, budget=budget) # domain code
study = oa.create_study(
direction="maximize",
sampler=oa.AgentSampler(
backend="claude", # or "codex" / "opencode"
effort="high",
context="maximize system quality under a strict operating-cost budget",
history=5,
explicit_reasoning=True,
qualitative_notes=True,
),
storage="study.json", # optional: persist and resume
)
study.optimize(objective, n_trials=20)
print(study.best_value, study.best_params)
```
可选的 `context` 为研究和参数提供领域含义。可以通过
在 `AgentSampler(context=...)` 上进行全局设置，在
`suggest_*(..., context=...)` 上为单个参数设置，或两者同时设置来提供。
## 适用场景
| 领域 | optim-agent 可调整的参数 | 示例目标 |
|---|---|---|
| **模型训练** | 学习率、架构、数据增强、正则化 | 验证质量、计算量、鲁棒性 |
| **推理与服务** | 量化、批处理、解码、缓存、路由 | 质量、延迟、吞吐量、成本 |
| **量化研究** | 信号窗口、阈值、再平衡规则、风险控制 | 滚动回报、回撤、换手率 |
| **强化学习与决策** | 目标权重、探索计划、环境设置、策略阈值 | 回报、安全性、样本效率 |
| **科学工作流** | 模拟输入、求解器设置、实验对照 | 拟合度、误差、运行时、资源使用 |
| **黑盒系统** | 任何有界的类别型、整数型或连续型配置 | 标量目标得分 |
对于强化学习，optim-agent 负责调整学习
循环周围的系统；它不会替代策略学习算法。
## 优化轨迹
此 seed-0 Branin 轨迹在相同的 10 次试验
预算下比较了 TPE 和 GPT-5.5，并显示了每次试验后的当前最佳目标值。这是一个轨迹
说明；汇总的基准测试结果和复现命令如下。
### 无上下文优化数学函数：Branin-2D 和 Ackley-5D
高难度函数智能体**未获得提供的任务上下文**：仅有通用的
`x1...x5` 参数名称、数值边界和试验历史。运行使用 5 个随机种子进行 10 次试验；Random 和 TPE 是保持不变的基准。
#### 顶级智能体
| 方法 | Branin 平均最佳值 ↓ | Ackley-5D 平均最佳值 ↓ |
| ------------- | -----------------: | --------------------: |
| Random | 5.008 | 19.639 |
| TPE | 11.395 | 18.843 |
| GPT-5.5 | 1.326 | 3.960 |
| **Opus-4.8** | **0.398** | **0.061** |
| Sonnet-5 | 3.850 | 0.143 |
| Kimi-K3 | 2.082 | 0.907 |
| Minimax-M3 | 0.970 | 0.574 |
| GLM-5.2 | 3.609 | 15.023 |
指定的模型版本为 `gpt-5.5`、`claude-opus-4-8`、`claude-sonnet-5`、
`kimi-k3`、`MiniMax-M3` 和 `glm-5.2`。
Opus-4.8 平均达到了 Branin 的最优值，并且拥有最强的 5 种子
Ackley 平均值。
#### OpenCode 智能体（免费）
| 方法 | Branin 平均最佳值 ↓ | Ackley-5D 平均最佳值 ↓ |
| --------------------- | -----------------: | --------------------: |
| Random | 5.008 | 19.639 |
| TPE | 11.395 | 18.843 |
| Big-pickle | 4.734 | 15.951 |
| **DeepSeek-V4-Flash** | 4.410 | **4.608** |
| Nemotron-3-Ultra | 16.051 | 18.459 |
| **MiMo-v2.5** | **3.682** | 15.597 |
OpenCode 托管的模型不需要付费的模型 API。免费池会轮换；此
刷新固定使用 `opencode/big-pickle`、`opencode/deepseek-v4-flash-free`、
`opencode/nemotron-3-ultra-free` 和 `opencode/mimo-v2.5-free`。DeepSeek V4
Flash 拥有最强的免费模型 Ackley 平均值，而 MiMo-v2.5 拥有
最强的免费模型 Branin 平均值。
### 调整基于 ResNet 的图像分类器：MNIST 和 CIFAR-10
分类基准测试在 5 个随机种子（`0..4`）和
10 次试验中，比较了 **Random**、Optuna **TPE**、
**GPT-5.5（有上下文）** 和 **GPT-5.5（无上下文）**。有上下文条件接收自然语言的研究和参数
描述；无上下文条件仅接收边界和试验历史。
对于分类任务，主要指标强调快速提升：
```
cumulative_best_so_far_error = sum(best_test_error_so_far_at_i for i in 1..10)
```
越低越好。
| 方法 | MNIST 累积误差 ↓ | MNIST 最终误差 ↓ | CIFAR-10 累积误差 ↓ | CIFAR-10 最终误差 ↓ |
| ---------------------- | -----------------------: | ------------------: | --------------------------: | ---------------------: |
| Random | 9.174 | 0.648% | 278.920 | 25.072% |
| TPE | 7.166 | 0.580% | 279.936 | 25.596% |
| **GPT-5.5（有上下文）** | **5.668** | **0.506%** | **220.994** | **21.322%** |
| GPT-5.5（无上下文） | 8.910 | 0.632% | 281.466 | 25.960% |
在 MNIST 上，带上下文的 GPT-5.5 相对于 TPE 将累积的历史最佳误差降低了 **20.9%**，在 CIFAR-10 上相对于 Random 降低了 **20.8%**。在没有上下文的情况下，
它在 MNIST 上比 TPE 差 24.3%，在 CIFAR-10 上比 Random 差 0.9%。
该差距既包含了语义参数信息的影响，也包含了更早获得
智能体引导的建议的影响。
[`examples/mnist.py`](examples/mnist.py) 和
[`examples/cifar10.py`](examples/cifar10.py) 都调整了学习率、批次大小、
权重衰减、标签平滑、三个阶段的宽度、三个阶段的深度和四个
dropout 控制参数。MNIST 增加了平移和旋转；CIFAR-10 使用了裁剪
填充和翻转概率。
### 调整 Q-learning 控制器：Acrobot-v1 和 LunarLander-v3
此纯 CPU Gymnasium 基准测试为
Acrobot-v1 和 LunarLander-v3 调整离散化的 Q-learning 控制器。每种方法在 5 个种子（`0..4`）上进行 20 次试验；
目标是平均评估回报，因此越高越好。
运行器通过 `--workers` 跨种子并在每个 HPO 研究内进行并行化。
GPT-5.5 分支使用高建模精力和最近 5 次试验的历史。获胜的上下文分支禁用了可选的显式推理和定性注释字段。
| 方法 | Acrobot-v1 回报 ↑ | LunarLander-v3 回报 ↑ |
| ---------------------- | ------------------: | ----------------------: |
| Random | -200.000 | -62.139 |
| TPE | -199.900 | -72.088 |
| **GPT-5.5（有上下文）** | **-199.700** | **-50.825** |
| GPT-5.5（无上下文） | -199.100 | -59.751 |
在 20 次试验和 5 次试验提示历史的情况下，带上下文的 GPT-5.5 在两个环境中都有
最强的平均回报：在 Acrobot-v1 上比 TPE 高 0.2，在
LunarLander-v3 上比 Random 高 11.3。请将此视为 CPU HPO 压力测试，而
不是通用排名。
在动画演示中，optim-agent 使用一个 HPO 种子调整了确定性
LunarLander 控制器的 7 个增益。每次试验都在相同的 20 个
rollout 种子上运行，优先考虑成功着陆的次数，其次是平均
回报。当 Gymnasium 终止且着陆器静止且
最终信号为 +100 时，即表示着陆成功。选定的试验在所有 20 次 rollout 中都成功着陆；
GIF 显示了其回报最高的 rollout。
### 调整梯度提升分类器：信用违约概率
此纯 CPU 基准测试调整
`HistGradientBoostingClassifier` 在 UCI 的
[Default of Credit Card Clients](https://archive.ics.uci.edu/dataset/350/default+of+credit+card+clients)
数据集上的 8 个训练：30,000 行、23 个特征和下个月的违约目标。官方
存档由 SHA-256 固定，采用 CC BY 4.0 许可，并一次性分割为 60% 的训练集、
20% 的验证集和 20% 的未触及测试数据。所有方法使用相同的分割、20
次试验和随机种子 `0..4`。两个 GPT-5.5 分支都使用高建模精力、20 次试验
提示历史、显式推理和定性注释。
| 方法 | 最终验证 log loss ↓ | 留出测试 log loss ↓ |
| ---------------------- | --------------------------: | -----------------------: |
| Random | 0.433 | 0.425 |
| TPE | 0.430 | 0.422 |
| GP-BO | 0.430 | 0.423 |
| **GPT-5.5（有上下文）** | **0.428** | **0.422** |
| GPT-5.5（无上下文） | 0.433 | 0.427 |
相对于匹配的无上下文对照组，上下文将最终验证 log loss 降低了 1.13%，测试 log loss 降低了 1.23%。
GPT-5.5 的平均验证和测试损失也低于 Random、TPE 和 GP-BO。因为保留的
配置是同时使用验证和测试损失来选择的，所以测试结果
是一个基准比较，而不是对泛化能力的未触及估计。
这是一个方法论基准，而不是生产级信贷决策系统。
部署将需要超越此实验的公平性、校准、漂移、治理和法律审查。
复现基准测试构件：
```
pip install -e ".[examples]"
# 分类
python scripts/verify_classification_cumulative_error.py run-no-context
python scripts/verify_classification_cumulative_error.py
# Hard functions
python examples/hard_functions.py distributed \
--agents Random TPE GPT-5.5 Opus-4.8 Sonnet-5 GLM-5.2 Big-pickle \
DeepSeek-V4-Flash Nemotron-3-Ultra MiMo-v2.5 \
--trials 10 --seeds 0 1 2 3 4
cp ~/.claude/settings-kimi.json ~/.claude/settings.json
python examples/hard_functions.py distributed --agents Kimi-K3 --trials 10 --seeds 0 1 2 3 4
cp ~/.claude/settings-minimax.json ~/.claude/settings.json
python examples/hard_functions.py distributed --agents Minimax-M3 --trials 10 --seeds 0 1 2 3 4
python examples/hard_functions.py plot
# Credit-card HGB
pip install -e ".[ml,examples]"
python examples/credit_card.py download
python examples/credit_card.py preflight
python examples/credit_card.py run
python examples/credit_card.py selfcheck
python examples/credit_card.py summary
python examples/credit_card.py plot
# RL control
pip install -e ".[rl,examples]"
python examples/rl_control.py preflight
python examples/rl_control.py run --seeds 0 1 2 3 4 --workers 10
python examples/rl_control.py selfcheck
python examples/rl_control.py summary
python examples/rl_control.py plot
python examples/rl_control.py gif
```
## 使用指南
### 采样器提示控制
`effort` 被转发到后端 CLI 的 reasoning-effort 标志。测试工具
提示是单独控制的：
```
oa.AgentSampler(
backend="codex",
effort="medium",
history=5,
explicit_reasoning=True,
qualitative_notes=True,
)
```
设置 `history=None` 以显示所有已完成/已剪枝的试验。使用
`explicit_reasoning=False` 或 `qualitative_notes=False` 可以获得更短的智能体
回复。
### 剪枝
```
study = oa.create_study(
sampler=oa.AgentSampler(backend="codex"),
pruner=oa.AgentPruner(
backend="codex", level="medium", effort="medium",
), # level: loose | medium | tight
)
def objective(trial):
lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True,
context="learning rate for training an image classifier")
for epoch in range(20):
loss = train_one_epoch(lr)
trial.report(loss, epoch)
if trial.should_prune():
raise oa.TrialPruned()
return loss
```
剪枝智能体将当前学习曲线与已完成的试验进行比较，
并决定剪枝/保留；`loose` 仅剪枝明显表现不佳的运行，
而 `tight` 会积极地剪枝。智能体出错永远不会剪枝试验。
### 并发与分布式研究
设置 `max_concurrency`（默认值为 `1`）以同时评估多个试验，并使用
SQLite `storage` 文件（`.db` / `.sqlite`）作为并发安全的共享
历史记录：
```
study = oa.create_study(
sampler=oa.AgentSampler(backend="claude"),
storage="study.db", # SQLite → safe for many workers; .json stays single-writer
max_concurrency=8, # up to 8 objectives run at once
)
study.optimize(objective, n_trials=100)
```
- **在单个进程内**，`max_concurrency` 在线程池中运行目标。智能体
采样查询会被**排队**（串行化），因此每个建议都能看到
进程内的历史记录；只有目标调用会并行运行。这最适合
I/O 或子进程密集型的评估，例如模型训练或 API 调用。
- **跨进程/机器**，将它们全部指向同一个 SQLite `storage`。
数据库*本身*就是通信渠道：WAL 模式让每个工作进程追加
结果并读取历史记录而不会产生写入冲突，并且试验编号保持
唯一。
限制：线程共享 GIL，因此纯 Python 的 CPU 密集型目标最好
在具有共享 SQLite 存储的独立进程中运行。并发的工作进程无法
看到彼此*进行中*的点，因此它们偶尔可能会探测到附近的
区域。
### 技能模式（智能体阅读项目代码）
pip 包将目标视为黑盒。
[optim-agent 技能](SKILL.md) 则更进一步：在编程智能体会话中加载后，
智能体首先*阅读项目*以了解每个
参数的作用，然后通过
`study.ask(params)` / `study.tell(trial, value)` 自行驱动相同的研究循环 — 研究使用的 JSON 文件会跨会话保留历史记录。
```
$skill-installer install https://github.com/Optim-Agent/optim-agent
```
Claude Code 插件：
```
claude plugin marketplace add Optim-Agent/optim-agent
claude plugin install optim-agent@optim-agent
```
Codex 插件：
```
codex plugin marketplace add Optim-Agent/optim-agent
codex plugin add optim-agent@optim-agent
```
```
trial = study.ask({"threshold": 0.72, "budget": 80})
study.tell(trial, evaluate_system(**trial.params))
```
### 离线测试
`AgentSampler(backend="mock")` 是一个无需 token 的替代品（围绕
最佳点进行爬山），用于在智能体调用之前测试集成。
## 故障排除
- **`claude` 在智能体会话中返回 401** — 嵌套会话会继承
`ANTHROPIC_API_KEY`；使用 `env -u ANTHROPIC_API_KEY` 运行或从干净的 shell 中运行。
- **后端调用超时或发出无效输出** — 采样器会发出警告并
针对该试验回退到随机点；研究会继续进行。
- **OpenCode 与分布式研究** — OpenCode 目前在 optim-agent 中不支持分布式计算；对于分布式运行，请使用单进程工作流或不同的后端。
## 致谢
- [Optuna](https://github.com/optuna/optuna) 普及了 Study/Trial
接口，提供了示例和基准测试中使用的 TPE 基准，
并为实用优化工具设定了高标准。
- [OpenCode](https://github.com/sst/opencode) 提供了对在
高难度函数基准测试中评估的免费模型的访问权限。
## 许可证
[MIT](LICENSE)
