跳到主要内容

Darwinian Evolver

借助 Imbue 的进化循环来进化 prompt、regex、SQL 或代码。

Skill 元数据​

来源Optional(可选)— 使用 kopi skills install official/research/darwinian-evolver 安装
路径optional-skills/research/darwinian-evolver
版本0.1.0
作者Bihruze (Asahi0x), KOPI AI AGENT
许可证MIT
平台linux, macos
标签evolution, optimization, prompt-engineering, research
相关 skillarxiv, jupyter-live-kernel

参考:完整的 SKILL.md​

信息

以下是当该 skill 被触发时 Kopi Agent 加载的完整 skill 定义。这就是 skill 处于激活状态时 agent 所看到的指令。

Darwinian Evolver

运行 Imbue 的 darwinian_evolver —— 一个由 LLM 驱动的进化搜索循环 —— 针对某个 fitness function(适应度函数)来优化 prompt、regex、SQL 查询或一小段代码。

状态:这是对上游工具的轻量封装(thin wrapper)。该 skill 负责安装它,引导 agent 编写一个 Problem 定义(organism(有机体)+ evaluator(评估器)+ mutator(变异器)),并通过上游 CLI 或一个小型自定义 Python driver 来驱动该循环。

许可证: 上游工具采用 AGPL-3.0。该 skill 只会通过上游 CLI 或一次 subprocess/uv run 调用来使用它(仅属聚合)。请不要将上游的类导入到 Kopi Agent 本身中。

何时使用​

  • 用户说"优化这个 prompt"、"为 X 进化一个 regex"、"自动改进这段代码/SQL"、"搜索更好的指令"。
  • 你已经有一个 scorer(打分器)(精确匹配、regex 通过率、单元测试、LLM-judge、运行时指标)并且有一个起始候选(organism)。如果你还没有 scorer,请停下来先定义一个 —— 那才是最困难的部分。
  • 成本可以接受:一次典型运行会调用 50–500 次 LLM。在 gpt-4o-mini 上这只需几美分;在 Claude Sonnet 上可能需要几美元。

不要在以下情况使用:

  • 优化目标是可微的(请使用梯度下降 / DSPy)。
  • 你只需要尝试 2–3 个变体 —— 直接手写即可。
  • fitness 信号完全是主观的,没有任何可衡量的标准。

前置条件​

  • Python ≥3.11
  • git、uv(或 pip)
  • OPENROUTER_API_KEY、ANTHROPIC_API_KEY 或 OPENAI_API_KEY 之一

该 skill 附带一个小型的 parrot_openrouter.py driver,它通过 OpenAI SDK 使用 OPENROUTER_API_KEY,因此 OpenRouter 上的任何 model 都可以使用。上游 CLI 本身硬编码了 Anthropic,需要 ANTHROPIC_API_KEY。

安装(一次性)​

通过 terminal 工具运行:

mkdir -p ~/.kopi/cache/darwinian-evolver && cd ~/.kopi/cache/darwinian-evolver
[ -d darwinian_evolver ] || git clone --depth 1 https://github.com/imbue-ai/darwinian_evolver.git
cd darwinian_evolver && uv sync

验证:

cd ~/.kopi/cache/darwinian-evolver/darwinian_evolver \
&& uv run darwinian_evolver --help | head -5

快速上手 —— 内置的 Parrot 示例​

一个很小的冒烟测试(需要 ANTHROPIC_API_KEY):

cd ~/.kopi/cache/darwinian-evolver/darwinian_evolver
uv run darwinian_evolver parrot \
--num_iterations 2 \
--num_parents_per_iteration 2 \
--mutator_concurrency 2 --evaluator_concurrency 2 \
--output_dir /tmp/parrot_demo

输出:

  • /tmp/parrot_demo/snapshots/iteration_N.pkl —— 每次迭代的 pickle 化 population(种群)
  • /tmp/parrot_demo/<jsonl> —— 每次迭代的 JSON 日志(路径会在最后打印出来)

在浏览器中打开 ~/.kopi/cache/darwinian-evolver/darwinian_evolver/darwinian_evolver/lineage_visualizer.html,并加载该 JSON 日志即可查看进化树。

快速上手 —— OpenRouter Driver(无需 Anthropic Key)​

该 skill 附带了 scripts/parrot_openrouter.py —— 同样的 parrot 问题,但 LLM 调用会通过 OpenRouter,因此任何 provider(服务提供商)都可以使用。

# From wherever the skill is installed:
SKILL_DIR=~/.kopi/skills/research/darwinian-evolver
DE_DIR=~/.kopi/cache/darwinian-evolver/darwinian_evolver

cd "$DE_DIR" && \
EVOLVER_MODEL='openai/gpt-4o-mini' \
uv run --with openai python "$SKILL_DIR/scripts/parrot_openrouter.py" \
--num_iterations 3 --num_parents_per_iteration 2 \
--output_dir /tmp/parrot_or

用 scripts/show_snapshot.py 检查结果:

uv run --with openai python "$SKILL_DIR/scripts/show_snapshot.py" \
/tmp/parrot_or/snapshots/iteration_3.pkl

预期输出:7 个进化后的 prompt 模板按分数排序,其中最好的大约落在 0.6–0.8(种子 Say {{ phrase }} 得分为 0.000)。

定义自定义问题​

该 skill 附带了 templates/custom_problem_template.py —— 复制、编辑、运行。 有三件事你必须定义:

  1. Organism —— 一个 Pydantic BaseModel 子类,用于承载被进化的产物(prompt_template: str、regex_pattern: str、sql_query: str、code_block: str 等)。添加一个 run(*args) 方法来执行它。

  2. Evaluator —— .evaluate(organism) -> EvaluationResult(score=..., trainable_failure_cases=[...], holdout_failure_cases=[...], is_viable=True)。

    • score 位于 [0, 1] 中。数值越高越好。
    • trainable_failure_cases —— mutator 所能看到的内容。要包含足够的上下文(input(输入)、expected(期望)、actual(实际)),以便 LLM 进行诊断。
    • holdout_failure_cases —— 不让 mutator 看到。用它们来检测过拟合。
    • 除非 organism 完全坏掉(抛出异常、返回 None 等),否则 is_viable=True。一个得分为 0 但仍然可用的 organism 是完全可以的 —— 它只是在父代选择时会被降权。
  3. Mutator —— .mutate(organism, failure_cases, learning_log_entries) -> list[Organism]。 通常做法是:构建一个 LLM prompt,其中包含当前 organism + 一个失败用例 + 一个请求让其提出修复方案;解析 LLM 的响应;返回一个新的 Organism。解析失败时返回 [] —— 循环会处理这种情况。

然后编写一个 driver 脚本,把 Problem(initial_organism, evaluator, [mutators]) 接入 EvolveProblemLoop,并对 loop.run(num_iterations=N) 进行迭代 —— 附带的 scripts/parrot_openrouter.py 就是参考实现。

真正重要的超参数​

flag默认值何时调整
--num_iterations5当你信任 evaluator 后,提升到 10–20
--num_parents_per_iteration4为了低成本探索,降到 2
--mutator_concurrency10为避免速率限制,降到 2–4
--evaluator_concurrency10同上;evaluator 也会调用 LLM
--batch_size1当你的 mutator 能处理多个失败用例后,提升到 3–5
--verify_mutations关闭当 mutator 浪费较大时打开(据 Imbue 所述,后续运行可节省 >10 倍成本)
--midpoint_scorep75除非分数过于集中,否则保持不变
--sharpness10保持不变

注意事项​

  1. Initial organism must be viable —— 即使 seed 的得分为 0,也要在你的 EvaluationResult 中设置 is_viable=True。该循环会拒绝不可存活的 organism,因为这意味着循环没有可供演化的起点。
  2. Provider 内容过滤器会中断运行。 由 Azure 托管的 OpenRouter 模型 会拒绝诸如 "ignore previous instructions" 之类的措辞,并返回 HTTP 400。请将 LLM 调用包装在 try/except 中并返回 f"<LLM_ERROR: {e}>" —— evolver 只会给该 organism 打 0 分,然后继续处理。
  3. loop.run() 是一个生成器 —— 调用它不会执行任何操作,直到 你进行迭代。请使用 for snap in loop.run(num_iterations=N):。
  4. 快照是嵌套的 pickle。 iteration_N.pkl 包含一个 dict,其中 population_snapshot(更多 pickle 字节)。要反序列化,你必须让 Organism 类可以在与其序列化时相同的点分路径下被导入。
  5. 并发默认值偏激进。 10/10 在大多数 provider 上 都会触发速率限制。请从 2/2 开始。
  6. CLI 硬编码为 Anthropic。 uv run darwinian_evolver <problem> 会调用 ANTHROPIC_API_KEY 并使用 Claude Sonnet。要使用其他 provider,请编写类似 parrot_openrouter.py 的 driver。
  7. AGPL。 切勿在 Kopi Agent 核心中 from darwinian_evolver import ...。 ~/.kopi/skills/... 下的自定义 driver 脚本属于用户侧,是没问题的。
  8. 没有 PyPI 包。 pip install darwinian-evolver 会拉取错误的 内容。请始终从 GitHub 仓库安装。

验证​

安装并运行一次 parrot 后,以下命令退出码为 0 即可视为通过:

DE_DIR=~/.kopi/cache/darwinian-evolver/darwinian_evolver
ls "$DE_DIR/darwinian_evolver/lineage_visualizer.html" >/dev/null && \
cd "$DE_DIR" && uv run darwinian_evolver --help >/dev/null && \
echo "darwinian-evolver: OK"

参考资料​