AntOmniEvo进阶扩展:对接云端存储与自定义Coding Agent后端完全指南

原创2026-10-16 20:45:111,650 阅读

AntOmniEvo进阶扩展:对接云端存储与自定义Coding Agent后端完全指南

AntOmniEvo 是一个让 AI 自动进化的开源框架——你可以把它理解为一支 7×24 小时在线的"算法工程师团队",它把系统里可调的文件(Skill、提示词、工作流配置)当作基因,自动跑"选择→改写→评估→反思"的进化循环。本文带你完成两项进阶扩展:对接云端存储(自定义 CandidateStore)与自定义 Coding Agent 后端(自定义 Proposer),全程只需改动很小的代码量。

AntOmniEvo 自动进化框架的候选体种群界面

一、为什么要扩展:先认识 AntOmniEvo 的 7 个可插拔组件

AntOmniEvo 的设计哲学是"通用引擎 + 任务插件":主循环、调度、预算控制、断点续跑全部由框架负责,你的任务只需插入 7 个可插拔组件。官方扩展文档 docs/extensibility.md 把它们分成三个角色:

角色 组件 职责 常见默认实现
目标端 System 用候选的可调文件运行系统 Text2SQLSystem、TerminalBenchSystem
目标端 Evaluator 给运行结果打分,其评分标准就是优化目标 TextSQLEvaluator 等
目标端 DataInst + loader 一条评测实例及其加载方式 各场景 loader
优化端 Optimizer 进化主循环 基类 + 场景子类
优化端 Proposer 读失败轨迹、改写文件的 Coding Agent PiCodingAgentProposer、ClaudeCodeProposer
优化端 EvolutionAlgorithm 决定谁被选育、谁被淘汰 ParetoFrontierEvolutionAlgorithm
持久化 CandidateStore 持久化全部进化状态 LocalCandidateStore(文件系统)

在这 7 个组件里,绝大多数用户只需要替换前 3 个目标端组件。而本文讲的两条扩展轴,正好对应另外两个位置:

  • 换 Coding Agent 后端:继承 BaseProposer,实现一个方法即可;
  • 接云端存储:继承 CandidateStore 抽象基类,实现"本地 + 透明同步"子类。

两条轴都不需要修改主循环一行代码。

AntOmniEvo 可视化器统计页展示迭代分数曲线

二、扩展轴一:对接云端存储(自定义 CandidateStore)

2.1 存储里到底存了什么

一次优化运行 = 一个 Optimizer 进程 + 一个本地存储。所有候选体(candidate)的"基因"与进化记忆都落在 workspace/ 目录下,默认实现 LocalCandidateStore 的目录结构长这样:

workspace/
└── candidates/
    └── {candidate_id}/
        ├── artifact/          # 该候选的可调文件(技能、提示词、配置…)
        └── data/
            ├── meta.json      # 候选元信息
            ├── changelog.jsonl
            ├── summary.json   # 分数汇总
            ├── system_run/    # 训练集运行记录
            └── proposer_run/ # 分析/变异轨迹

这就是为什么 AntOmniEvo 天然可中断、可续跑:状态全在磁盘上,重启后自动恢复。

2.2 官方推荐的云存储方案:本地 + 透明同步

很多团队的第一反应是"把存储整体搬到对象存储/数据库",但官方文档在 docs/extensibility.zh-CN.md 中给出了一个更稳妥的结论:请实现一个"本地 + 透明同步"的 CandidateStore 子类,而不是"多 worker 共享一个远端 store"。原因是:

  • 候选的 artifact_dir 会被直接当作工作目录(cwd)交给 Coding Agent 子进程就地改文件,也作为 --artifact-dir 传给系统子进程——它必须是真实可写的本地目录,远端 URI 无法胜任;
  • 存储接口依赖文件修改时间(mtime)来判断"哪些运行记录还没被分析",远端后端必须提供等价的时间戳语义;
  • changelog.jsonl 等文件由外部 CLI 子进程并发追加写入,远端需支持安全的追加语义。

因此正确姿势是:优化过程仍在本地 workspace/ 跑,每次写入时顺带把产物同步到对象存储/数据库;运行前从云端拉取初始可调文件作为种子,运行后把最终产物推给下游消费。主循环及其并发(进程内的 num_proposals 槽位)完全不用动。

AntOmniEvo 进化谱系树展示候选体父子关系与得分变化

2.3 三步落地:自定义 CandidateStore 子类

第 1 步:继承抽象基类。 在 antomnievo/interface/candidate_store.py 中,CandidateStore 是一个 ABC(抽象基类),__init__ 是具体实现(只需保存 workspace_dir 和 cleanup_unavailable 两个跨实现配置项):

class CloudSyncStore(CandidateStore):
    def __init__(self, workspace_dir, bucket, cleanup_unavailable=True):
        super().__init__(workspace_dir, cleanup_unavailable)  # 必须先调 super
        self._local = LocalCandidateStore(workspace_dir, cleanup_unavailable)
        self._bucket = bucket  # 你的对象存储/数据库句柄

第 2 步:委托本地 + 写入时同步。 把所有读方法直接委托给 LocalCandidateStore(它已带内存缓存),再在写路径(save_meta、save_run_record、append_changelog、update_analysis、轨迹保存等)之后,把对应文件/目录增量同步到云端。

第 3 步:处理两个"物化"时机。

  • create_root 时:从云端拉取初始可调文件目录,在本地 artifact/ 物化,再交给子进程;
  • 运行结束(或每个候选被接受时):把 artifact/ 树推送到云端,供下游(部署、报表)消费。

契约类接口(artifact_dir / data_dir / system_run_dir 等路径方法)全部照抄 LocalCandidateStore 的路径拼接即可,因为它们最终都指向本地目录。完整契约细节写在该接口类的 docstring 中(antomnievo/interface/candidate_store.py#L36-L68),实现前务必通读一遍。

2.4 接入入口:只改一行

组件装配通常写在 example/ 下的入口脚本中,比如 antomnievo/example/terminalbench/terminalbench.py#L95:

candidate_store = LocalCandidateStore(workspace_dir, cleanup_unavailable=False)

换成你的云端子类后,Optimizer、Proposer、EvolutionAlgorithm 都通过 candidate_store= 参数持有同一个对象,因此其余代码一行不动。这也是 AntOmniEvo"面向接口编程"的直接收益:optimizer / proposer / system 全部只依赖 CandidateStore 抽象。

AntOmniEvo 文件查看器可浏览每个候选的运行记录与产物文件

三、扩展轴二:自定义 Coding Agent 后端(自定义 Proposer)

3.1 核心思想:两阶段流水线已经替你写好了

Proposer 是 AntOmniEvo 里真正"干活"的 AI:它先做阶段 1 分析(读取未分析的失败运行记录,让 Agent 写出失败归因),再做阶段 2 变异(根据分析结果改写可调文件,产出新候选)。这套两阶段流水线、提示词模板、changelog 校验脚本全部固化在 BaseProposer 中。

所以自定义后端只需要回答一个问题:怎么调用你自己的 Coding Agent CLI/SDK,并把会话解析成轨迹。也就是实现这一个抽象方法(antomnievo/proposer/base_proposer.py#L94-L101):

async def invoke_agent(self, prompt: str, cwd: str) -> tuple[Trajectory, UsageStats]:
    """调用你的 Agent,返回 (轨迹, 用量统计)。"""
  • prompt:框架已组装好的完整提示词(含评分标准、可调文件 schema、失败分析内容等),你原样传给 Agent 即可;
  • cwd:本次会话的工作目录。阶段 1 是父候选的 data_dir,阶段 2 是新候选的 artifact_dir(框架通过 snapshot_files 前后对比目录来判断"文件是否真的被修改");
  • 返回值:Trajectory 是 span 树结构(见 antomnievo/model/trajectory.py#L38),UsageStats 记录 token 用量,用于预算统计。

3.2 一个最小自定义 Proposer 长什么样

假设你的团队内部有一个叫 myagent 的编码 CLI。参考现有实现 PiCodingAgentProposer(它同时展示了重试、并发信号量等生产级写法):

class MyAgentProposer(BaseProposer):
    def __init__(self, *, api_key: str, concurrency: int = 4, **kwargs):
        super().__init__(concurrency=concurrency, **kwargs)
        self._api_key = api_key

    async def invoke_agent(self, prompt: str, cwd: str) -> tuple[Trajectory, UsageStats]:
        async with self._sem:  # 复用父类的并发信号量
            raw = await invoke_my_agent_cli(prompt, cwd, self._api_key)
        return parse_my_agent_output(raw)  # 你的解析函数

就这么多。提示词模板(antomnievo/proposer/template/)、分析结果校验、changelog 追加、反思链路(Mara Chain)全部继承而来。

3.3 三个生产级要点(现有后端的经验)

阅读 pi_coding_agent_proposer.py 时你会发现几个值得抄的细节:

  1. 瞬时错误重试:对 429/5xx/过载等瞬时错误用 tenacity 做指数退避重试,且退避期间继续持有并发信号量——这是刻意的背压设计,避免限流期间又堆进新的并发请求;
  2. 并发上限:通过 concurrency 参数 + asyncio.Semaphore 控制同时在跑的 Agent 会话数,阶段 1 的多组 data_id 分析用 asyncio.gather 并发;
  3. 防"假成功":Agent 会话退出码为 0 不代表文件真的落地。框架会在阶段 1 校验分析结果文件是否在会话期间被写入、阶段 2 对比目录快照判断文件是否被修改,未修改则视为失败,避免把半成品候选推入种群。你的解析函数只需如实填好 Trajectory.errors,这些防御逻辑就自动生效。

AntOmniEvo 逐题覆盖网格对比各候选在每道评测题上的得分

四、验证你的扩展:跑起来并可视化

扩展完成后,用 example/ 下任意入口脚本把组件指向你的新实现即可启动进化。跑起来之后,强烈建议装一下可视化器(docs/visualizer.zh-CN.md)来验收效果:

pip install -e .
pip install -e ./visualizer
cd visualizer && npm install
antomnievo-visualizer-manage start --workspace /path/to/workspace/<run>

前端默认在 http://localhost:5173。候选种群被渲染成一座"龙虾健身房",按分数分层归入不同房间;点击候选可以看祖先链、元信息,并用内置文件查看器浏览 system_run / proposer_run 的全部产物——自定义存储同步是否正常、自定义 Agent 的轨迹解析是否正确,在这里一目了然。

AntOmniEvo 候选详情面板展示祖先链、元信息与产物文件浏览

五、避坑清单:新手常踩的 5 个坑 🐚

  1. 把 artifact_dir 返回成远端 URI —— 它会被当作 cwd 交给子进程,必须是本地可写目录;
  2. 忘记 super().__init__(workspace_dir, cleanup_unavailable) —— workspace_dir 和 cleanup_unavailable 会被 Optimizer 通过接口回读用于启动恢复与日志;
  3. 忽略 mtime 语义 —— find_unanalyzed_runs 靠"运行记录比分析结果更新"来判断待分析项,远端对象必须有可用的最后修改时间;
  4. 自定义 Proposer 里不填 Trajectory.errors —— 框架靠它触发失败落盘与重试分类,吞掉错误会导致半成品候选混入种群;
  5. 试图多机共享一个 store 做跨主机并发进化 —— 这是另一套模型,框架开箱不支持;"一次运行 = 一个本地 store + 透明同步"才是官方姿势。

六、延伸阅读

两条扩展轴加起来,一个熟练的 Python 用户半天内就能跑通:CandidateStore 子类负责"进化记忆上云",BaseProposer 子类负责"换上你自己的 AI 工程师"。剩下的,交给 AntOmniEvo 的自动进化循环。

登录后查看全文
AntOmniEvo