GEPA Workbench 使用指南：为 optimize_anything 优化运行提供可观测性与实时操控

• AI Agent
• 提示工程
• 模型优化

GEPA Workbench 是 GEPA 项目为optimize_anything运行提供的交互式可观测平台，让你在浏览器中实时观察、检查并引导整个优化过程。本文以 docs/docs/workbench.md 为主线，结合仓库源码（状态持久化、评测服务、launcher）详解其三大能力：观察运行（候选、评测、反思的完整视图）、诊断与对话（内置 GEPA Agent 实时诊断并建议修复）、反馈操控（直接编辑候选或给出反馈并注入优化池）。读完本文，你将掌握如何通过submit_job提交可观察的优化任务、如何上传gepa_state.bin复现历史运行、如何读懂面板上的每一类指标，以及如何用反馈介入搜索过程。

GEPA Workbench 是什么

optimize_anything是 GEPA 提供的通用优化入口（见 src/gepa/optimize_anything.py），其底层循环由「提出候选 → 评测 → 反思 → 接受/拒绝」构成。传统跑批方式下，整个过程是一个黑盒：你只能等到结束再拿到最终结果。GEPA Workbench 的目标正是把这个黑盒打开，提供两类核心能力：

• 可观测性（Observability）：实时检查被提出的候选（candidates）、每次评测（evaluations）以及反思模型产出的反思（reflections），包括整体进度、训练与评测结果、逐任务明细。
• 可操控性（Steerability）：在任意时间点介入搜索——用反馈引导优化方向，或让内置的GEPA Agent诊断潜在问题并直接提议、应用修复。

换句话说，Workbench 不只是一个监控面板，还是一条「人在回路（human-in-the-loop）」通道，让搜索过程既透明又可被引导。

启动一次可观察的优化运行

Workbench 提供了三种进入优化运行的途径，覆盖了「新任务、浏览器配置、历史复盘」三种场景：

用 submit_job 提交任务

Workbench 文档给出的代码入口是：

from gepa.dashboard import submit_job

通过该调用提交的运行会在 Workbench 中实时可见，面板顶部会显示运行状态徽标（如 "In progress"）以及实时统计。对于希望在代码内启动并同时获得 Web 可观测性的场景，这是最直接的方式。

上传 gepa_state.bin 复盘历史运行

gepa_state.bin是 GEPA 优化运行的状态文件，由核心引擎在每个迭代周期持久化。在 src/gepa/core/state.py 的GEPAState.save中可以看到完整的落盘机制：

• 状态以pickle序列化，先写入<run_dir>/gepa_state.bin.tmp，再通过os.replace原子替换为目标文件，避免写坏中断导致的半成品状态；
• 同步导出可读的run_log.json（完整运行轨迹）与candidates.json（候选池快照）；
• 当write_agent_state=True时，额外写出iterations/<id>/与pareto/目录树，每个迭代（含被拒绝的提案）都有独立的meta.json、components/、trace.json，接受的候选还会附带val_scores.json、outputs/、trajectories/——这正是「Agent 可读」的状态视图。

更重要的是gepa_state.bin同时是续跑的种子：根据 src/gepa/api.py 的run_dir说明，如果目录中已存在gepa_state.bin，GEPA 会从该状态恢复（已保存的 seed 不会在 valset 上重新评测）。Workbench 的 "Upload a run" 正是复用了这一机制——把任意run_dir下生成的gepa_state.bin上传，即可按原样回放整个搜索历程，包括每个候选的得分、反思与决策轨迹。

观察你的优化运行

Workbench 的主界面围绕一个运行实例（文档中的示例是circle-packing-multi）组织，顶部栏与左侧候选列表、中央三个页签共同构成完整的运行视图。

顶部状态栏：聚合分数、预算与行动

Agg score 0.87 (+0.14) Calls 418 / 600 ETA ~4m [Pause] [Stop] [Branch]

• Agg score：当前聚合得分（文档示例为 0.87，相对 seed 提升 +0.14）；
• Calls：已消耗/总预算的评测调用数（418 / 600），对应底层BudgetTracker的用量；
• ETA：预计剩余时间；
• Pause / Stop / Branch：暂停、停止或从当前状态分支出新的运行——分支是在不污染原运行的前提下尝试不同方向的操控手段。

候选列表与谱系视图

左侧 Explorer 以List（列表）或Lineage（谱系）两种视图呈现候选池。每个候选带三类标记：

• sc（score）：该候选的得分，如 Candidate 0 = 0.73；
• par（◆）：该候选位于 Pareto 前沿；
• star（★）：当前最优候选。

文档示例中 Candidate 7 以 ★ 标记为当前最优（0.87），而 Candidate 4、6 已加入 Pareto 前沿。这一视图直接对应 src/gepa/oa/eval_server.py 中EvalServer维护的候选注册表与best_candidate/best_score追踪。

Overview 页签：进度、最优候选与得分曲线

Overview 页签包含三张核心卡片：

1. 状态横幅：如 "Improving — Best score improved to 0.87 at iteration 12, +0.14 over the seed"，并带 "Analyze" 一键触发诊断；
2. 当前最优卡片：展示最优候选得分（0.75 / 0.80 / 0.87 的演进，+19.2%）、程序长度（如program · 212 tok）与程序预览，支持 Copy / Open；
3. Score over time 图表：横轴为 Metric calls（0～600），纵轴为得分（0.65～0.85），同时绘制三条参考线——seed 0.73、best 0.87、pareto 0.91，并用轨迹点标注每次被接受候选的落点。

Evaluation 页签：逐任务字段与得分

Evaluation 页签以任务为行、以 ASI（Agent-Side Information）字段为列展示矩阵，并支持三种显示模式：Fields & Scores / Fields Only / Scores Only。文档示例中circle-packing-multi展示的 ASI 字段为：

• scores.sum_radii（聚合指标）
• n_circles（任务参数）
• circles（候选输出，带缩略可视化）
• stdout、error、validation_details（运行与环境信息）

这些字段与真实示例 examples/circle_packing/main.py 完全对应：main返回的 dict 中scores.sum_radii取自validation_details["sum_radii"]，而[examples/circle_packing/utils.py](https://link.gitcode.com/i/31c4ef8455ce9fe0b2e010817a72826f) 强制要求返回值必须包含all_scores键，否则判为失败——这就是面板上validation_details` 字段的来源。逐任务查看能让你迅速定位「哪个任务拖累了聚合分数」，例如 N 较大任务超时得 0 分的情形。

Reflections 页签：反思链的完整回放

Reflections 页签按时间顺序列出反思事件，每个事件呈现「父候选 → 子候选」关系、接受/拒绝状态、得分差与 token 消耗：

Candidate 5 → Candidate 7 accepted +0.03 2.4k tokens Reflection output: The grid layout wastes corner space once n grows past 6. Keep the greedy placement, then anneal positions and grow radii until first contact... proposal: replace shrink_radii with anneal + grow_radii ...

同时该页签还展示Refiner prompt与ASI fields配置（如scores.sum_radii、n_circles、circles、stdout、error、validation_details共 6 个字段）。被拒绝的提案同样保留（如 Candidate 2 → Candidate r1，rejected，−0.02），使整个「提出 → 反思 → 决策」链条完全可审计。

底部 Dock：日志流

底部 Dock 提供实时日志流，每条日志带时间戳、迭代号与事件级别（pareto/accept/info），例如：

14:02:03 iter 11 pareto Candidate 6 joined the Pareto front (0.84) 14:02:11 iter 12 accept Candidate 7 accepted — agg score 0.87 (+0.03) 14:02:14 iter 13 info minibatch eval started (5 tasks)

这份日志流与 src/gepa/oa/eval_server.py 中的log_progress机制一致：每次评测都会向progress_log.jsonl追加事件条目，当output_dir被设置时，每个评测还会持久化为<dir>/evals/<i>.json，并提供滚动的summary.json与candidates.jsonl——这些文件正是 Workbench 前端数据源在磁盘层的落点。

与 GEPA Agent 对话与诊断

GEPA Agent 内置于 Workbench，提供 Chat 与 Diagnostics 两个页签。

Chat：向 Agent 提问你的运行

你可以用自然语言对运行提问，并用@指定上下文（如@ run:circle-packing-multi）。文档示例展示了一个典型问答：

问：Why was candidate r1 rejected? 答：Candidate r1scored0.69on its reflection minibatch, while its parentCandidate 2scored0.71on the same tasks. Acceptance requires beating the parent, so the proposal was not added to the pool. Its main change, a denser initial grid, slowed the search on N ≥ 7.

这个回答精确引用了接受判据（子候选需在反思 minibatch 上超过父候选）与具体证据（0.69 vs 0.71、N≥7 变慢）——回答必须是证据可溯源的，而非凭空猜测。Agent 还能对配置做修改，这意味着对话不限于查询，还延伸到「编辑运行配置」的操作层。

Diagnostics：每次提案后的自动诊断

GEPA Agent 在每次提案之后都会对运行做一次诊断；当发现异常时，会以诊断卡片的形式呈现：

• 问题标题：如 "Timeouts on the largest tasks"（带 ⚠ 警示）；
• 证据：如 "N=9 and N=10 hit the 60s subprocess limit in 3 of the last 5 candidates, so their scores fall to 0 and drag the aggregate down"；
• 建议修复：如 "Cap the local search iterations by n_circles so every task finishes inside the budget"；
• 行动按钮：Apply as feedback（作为反馈应用到运行）或Dismiss（忽略）。

诊断活动会被完整记录（"Agent activity"），例如「比较各候选的逐任务得分」「检查近期评测的 stderr 与超时」，让用户能看到 Agent 的推理过程。这一设计把「发现问题 → 定位证据 → 给出修复 → 一键落地」闭环直接放进了优化流程。

用反馈改进一个候选

Workbench 的操控能力最终落地为「改进候选」工作流：对任一候选，你可以直接编辑其程序，或仅用自然语言描述期望的改进，由反思模型据此产出改进版候选。

✦ Improve Candidate 7 program: def main(n, timeout, best): pts = grid_layout(n) r = shrink_radii(pts) return circles(pts, r) Feedback for improvement: [Add a local search pass after placement.] [Cap iterations by n to avoid timeouts.] [✦ Improve with feedback] [Evaluate candidate] Diff between candidates: def main(n, timeout, best): pts = grid_layout(n) - r = shrink_radii(pts) + pts, r = anneal(pts, steps_for(n)) + r = grow_radii(pts, r) return circles(pts, r) Evaluation: Base 0.87 Improved 0.91 Δ +0.04

关键机制与术语如下：

• 两种改进输入：直接编辑program，或填写「Feedback for improvement」——后者会作为反馈喂给反思模型，由其生成改进候选；
• 即时评测对比：改进前后可立即评测，并以Base / Improved / Δ形式展示收益（示例中 0.87 → 0.91，Δ +0.04）；
• Add candidate 注入优化池：点击 "Add candidate" 后，改进候选以新候选（如 Candidate 8）身份加入候选池，后续所有提案都会以它为父候选继续迭代（"future proposals build from it"）。

这一机制与核心引擎的候选池语义完全对齐：被加入的候选会获得一次完整的 valset 评测，之后进入正常的「提出 → 反思 → 接受/拒绝」循环。换言之，你的每一次人工反馈都会被转化为搜索空间中的一次受控扰动，而非推倒重来。

底层支撑：评测服务与状态持久化

Workbench 并非独立的魔法面板，它复用了optimize_anything已有的基础设施：

• EvalServer（单一事实来源）：src/gepa/oa/eval_server.py 中EvalServer同时服务进程内引擎（直接调用evaluate）与外部引擎（HTTP POST 到url），两者共用同一套预算计数器与候选注册表；每次评测都会计入progress_log.jsonl，并在设置output_dir时持久化evals/、candidates.jsonl与summary.json。Workbench 的 Calls 统计、逐任务得分、Pareto 前沿追踪全部来源于此。
• 带服务器的启动入口：仓库提供optimize_anything_with_server以及optimize_sequential_with_server、optimize_adaptive_sequential_with_server、optimize_parallel_with_server、optimize_best_of_with_server、optimize_vote_with_server等变体（见 src/gepa/optimize_anything.py），它们负责「启动一个带评测服务的运行」这一工作流。
• 状态即续跑：gepa_state.bin既是 Workbench 上传复盘的对象，也是进程重启后断点续跑的凭据——EngineConfig.run_dir一旦设置，核心引擎在每次迭代后都会写盘（见 src/gepa/core/engine.py 的恢复检查逻辑）。

实战建议与适用前提

• 何时使用提交式 vs 浏览器式：已有optimize_anything代码的团队用submit_job最省事；临时起意的探索用浏览器 "New run"；需要审计或向他人展示历史结论时上传gepa_state.bin。
• 保证可回放：运行务必设置run_dir（EngineConfig.run_dir），否则不产生gepa_state.bin，也就无法上传复盘或续跑。
• 预算意识：面板上的 Calls 数字直接对应BudgetTracker（如 600 次评测预算），EvalServer 的max_concurrency（默认 8）与budget共同决定了并行度与开销边界；超预算后评测会被拒绝，这正是文档示例中「Pareto 0.91 高于当前 best 0.87」这类差分信息背后的预算语义。
• 诊断依赖磁盘落盘：如需 Agent 深度诊断（逐任务得分对比、stderr 与超时分析），建议同时开启 EvalServer 的output_dir，让evals/与progress_log.jsonl成为可回溯的证据源。

需要说明的是，GEPA Workbench 在仓库中目前以「产品文档 + 前端样式原型」形态呈现（页面结构与样式见 docs/docs/assets/workbench-styles.css，页面模板见 docs/overrides/workbench.html），本文所述交互细节均以 docs/docs/workbench.md 描述为准；而支撑其数据流的评测、预算与状态机制，则已在 EvalServer 与 状态持久化 等核心模块中落地。对于想进一步深入的用户，建议从 examples/circle_packing/main.py 出发，跑通一个真实的多任务优化案例，再对照本指南逐项验证面板语义。

• AI Agent
• 提示工程
• 模型优化