• 人工智能
• 大模型
• AI Agent
• 代码智能体
• 自主智能体

OpenEvolve 是一个开源的 AlphaEvolve 实现，它把 LLM 变成自主代码优化器：通过"进化"的方式反复改进程序。本篇文章以仓库configs/目录下的配置体系为核心，系统讲解如何从default_config.yaml全量模板出发，理解每一个配置参数的含义与默认值，掌握岛屿模型（Island-Based Evolution）三个核心参数（num_islands、migration_interval、migration_rate）的调优逻辑，并基于island_examples.yaml的五大典型场景与early_stopping_example.yaml的早期停止示例，写出可直接运行的实战配置。读完本文，你将具备从零搭建 OpenEvolve 进化任务配置、按问题复杂度选择合适的岛屿策略、并通过命令行或 Python API 一键启动的能力。

configs 目录：OpenEvolve 配置文件的完整图谱

configs/目录是 OpenEvolve 的配置中心，共包含 4 个 YAML 文件与一份导读文档（configs/README.md），它们分工明确：

其中default_config.yaml是灵魂文件：它既是一份"参数字典"，也是 OpenEvolve 各核心模块（LLM、Prompt、Database、Evaluator、EvolutionTrace）配置入口的真实写照，与 openevolve/config.py 中的Config及其子 dataclass（LLMConfig、PromptConfig、DatabaseConfig、EvaluatorConfig、EvolutionTraceConfig）一一对应。下面我们先逐模块拆解这份全量模板。

default_config.yaml：全量配置模板逐模块拆解

通用设置（General Settings）

max_iterations: 100 # Maximum number of evolution iterations checkpoint_interval: 10 # Save checkpoints every N iterations log_level: "INFO" # Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) log_dir: null # Custom directory for logs (default: output_dir/logs) random_seed: 42 # Random seed for reproducibility (null = random, 42 = default)

• max_iterations：进化总迭代数上限。注意：这是 YAML 模板中的示例值，代码层Config的默认值为 10000（见 openevolve/config.py），CLI 也可通过--iterations覆盖；
• checkpoint_interval：每隔 N 次迭代保存一次检查点，配合 CLI 的--checkpoint参数可实现断点续跑；
• random_seed：设置后控制器会同步 seed 全局random、numpy，并对不同组件派生哈希种子，保证可复现；设为null则随机。

进化设置（Evolution Settings）

diff_based_evolution: true # Use diff-based evolution (true) or full rewrites (false) max_code_length: 10000 # Maximum allowed code length in characters enforce_evolve_blocks: false # Revert LLM edits outside EVOLVE-BLOCK-START/END markers

• diff_based_evolution：true采用基于 SEARCH/REPLACE diff 的增量进化，false则使用全量重写。Config中还维护diff_pattern正则（默认<<<<<<< SEARCH\n(.*?)=======\n(.*?)>>>>>>> REPLACE）用于解析 LLM 返回的 diff；
• enforce_evolve_blocks：开启后，LLM 在EVOLVE-BLOCK-START/EVOLVE-BLOCK-END标记之外的编辑会被回滚（实现位于 openevolve/utils/code_utils.py 的enforce_evolve_blocks）。

早期停止设置（Early Stopping）

early_stopping_patience: null # Stop after N iterations without improvement (null = disabled) convergence_threshold: 0.001 # Minimum improvement required to reset patience counter early_stopping_metric: "combined_score" # Metric to track for early stopping

详见本文"早期停止（Early Stopping）配置"一节。

LLM 配置（llm）

llm: models: # List of available models with their weights - name: "gemini-2.0-flash-lite" weight: 0.8 - name: "gemini-2.0-flash" weight: 0.2 evaluator_models: # Models for LLM feedback - name: "gemini-2.0-flash-lite" weight: 0.8 - name: "gemini-2.0-flash" weight: 0.2 api_base: "https://generativelanguage.googleapis.com/v1beta/openai/" # Base URL for API api_key: null # API key (defaults to OPENAI_API_KEY env variable) # api_key: ${GEMINI_API_KEY} # Reads API key from $GEMINI_API_KEY temperature: 0.7 # Higher = more creative top_p: 0.95 # Top-p sampling parameter max_tokens: 4096 # Maximum tokens to generate timeout: 60 # Timeout for API requests in seconds retries: 3 # Number of retries for failed requests retry_delay: 5 # Delay between retries in seconds

几个值得注意的源码级细节：

1. 多模型加权集成：models列表支持配置多个模型并赋予权重，运行时由LLMEnsemble按权重采样（见 openevolve/llm/ensemble.py）。evaluator_models若未显式配置，会复用models列表（openevolve/config.py）；
2. ${VAR}环境变量语法：api_key支持api_key: ${GEMINI_API_KEY}形式，配置加载时会通过_resolve_env_var完整匹配并展开；若引用的环境变量未设置会抛出ValueError（openevolve/config.py）；
3. 向后兼容语法：除了models数组，还兼容primary_model/primary_model_weight与secondary_model/secondary_model_weight的旧写法，LLMConfig.__post_init__会自动把它们转换为models列表条目（openevolve/config.py），island_config_example.yaml与 examples/circle_packing/config_phase_1.yaml 均使用了这种写法；
4. provider 扩展：LLMModelConfig还支持provider字段（"openai"默认、"claude_code"、"copilot_cli"），以及reasoning_effort、max_budget_usd（Claude Code）、max_ai_credits（Copilot CLI）、manual_mode（人机协同）等进阶选项。

Prompt 配置（prompt）

prompt: template_dir: null # Custom directory for prompt templates system_message: "You are an expert coder helping to improve programs through evolution." island_system_messages: [] # Optional literal text or template names by island index evaluator_system_message: "You are an expert code reviewer." num_top_programs: 3 # Number of top-performing programs to include num_diverse_programs: 2 # Number of diverse programs to include use_template_stochasticity: true # Use random variations in templates for diversity template_variations: # Different phrasings for parts of the template improvement_suggestion: - "Here's how we could improve this code:" - "I suggest the following improvements:" - "We can enhance this code by:" include_artifacts: true # Include execution outputs/errors in prompt max_artifact_bytes: 20480 # Maximum artifact size in bytes (20KB default) artifact_security_filter: true # Apply security filtering to artifacts suggest_simplification_after_chars: 500 include_changes_under_chars: 100 concise_implementation_max_lines: 10 comprehensive_implementation_min_lines: 50 diff_summary_max_line_len: 100 diff_summary_max_lines: 30

• template_dir：自定义提示词模板目录。加载时若为相对路径，会相对配置文件所在目录解析（openevolve/config.py）；仓库默认模板见 openevolve/prompts/defaults/；
• island_system_messages：按岛屿下标为不同岛屿指定专属系统消息（字面量或模板名），null/缺失则回退到system_message。它必须与database.num_islands配合，条目数不能超过岛屿数，否则Config.from_dict会抛出ValueError（openevolve/config.py）；
• 阈值类参数（suggest_simplification_after_chars等）用于特征提取与程序标签（"简洁实现"/"全面实现"），diff_summary_*控制 "Previous Attempts" 段落中 SEARCH/REPLACE 块的展示长度。

Database 配置（database）

database: db_path: null # Path to persist database (null = in-memory only) in_memory: true log_prompts: true population_size: 1000 # Maximum number of programs to keep in memory archive_size: 100 # Size of elite archive num_islands: 5 # Number of islands (separate populations) migration_interval: 50 # Migrate between islands every N generations migration_rate: 0.1 # Fraction of top programs to migrate (0.1 = 10%) elite_selection_ratio: 0.1 # Ratio of elite programs to select exploration_ratio: 0.2 # Ratio of exploration vs exploitation exploitation_ratio: 0.7 # Ratio of exploitation vs random selection feature_dimensions: # MAP-Elites feature map dimensions - "complexity" # Code length (built-in) - "diversity" # Code diversity (built-in) feature_bins: 10 # Number of bins per dimension diversity_reference_size: 20 # Size of reference set for diversity calculation

• db_path：持久化路径；null时数据库仅在内存中运行；
• MAP-Elites 特征图：feature_dimensions默认["complexity", "diversity"]，两者均为内置特征（代码长度与结构多样性）；也可混入评估器返回的自定义指标（如performance、correctness）。注意：自定义维度必须由评估器返回连续的原始数值，OpenEvolve 内部完成缩放与分箱，评估器不应返回预先算好的 bin 索引；
• feature_bins：每个维度的分箱数，可以是整数（所有维度一致）或按维度指定的字典，例如feature_bins: {complexity: 10, diversity: 15}；
• 从源码看，diversity_metric目前固定为"edit_distance"（feature_based 未实现），选择比例默认elite_selection_ratio=0.1、exploration_ratio=0.2、exploitation_ratio=0.7。

Evaluator 配置（evaluator）

evaluator: timeout: 300 # Maximum evaluation time in seconds max_retries: 3 # Maximum number of retries for evaluation cascade_evaluation: true # Use cascade evaluation to filter bad solutions early cascade_thresholds: # Thresholds for advancing to next evaluation stage - 0.5 - 0.75 - 0.9 parallel_evaluations: 4 # Number of parallel evaluations use_llm_feedback: false # Use LLM to evaluate code quality (experimental) llm_feedback_weight: 0.1 # Weight for LLM feedback in final score

• 适应度计算：优先使用评估器返回的combined_score；否则对所有指标取平均，但会排除database.feature_dimensions中列出的特征维度；
• 级联评估（cascade）：先跑廉价的第一阶段，达到阈值（0.5）才进入下一阶段，用于尽早过滤劣质解（对应 openevolve/evaluator.py 中的_cascade_evaluate与run_stage1/2/3）；
• 资源限制（memory_limit_mb、cpu_limit）与分布式评估（distributed）在注释中明确标注"not yet implemented"，配置时不要依赖。

Evolution Trace 配置（evolution_trace）

evolution_trace: enabled: false # Enable evolution trace logging format: 'jsonl' # Output format: 'jsonl', 'json', or 'hdf5' include_code: false # Include full program code in traces include_prompts: true # Include prompts and LLM responses output_path: null # Defaults to output_dir/evolution_trace.{format} buffer_size: 10 # Number of traces to buffer before writing compress: false # Compress output file (jsonl only)

该模块为强化学习训练与进化分析记录细粒度的进化轨迹，支持 jsonl/json/hdf5 三种格式与可选压缩，底层实现在 openevolve/evolution_trace.py。

岛屿模型：OpenEvolve 保持进化多样性的核心机制

configs/README.md明确指出：default_config.yaml的价值不仅在于参数齐全，还在于内置了岛屿式进化参数（Island-Based Evolution Parameters）——这是 OpenEvolve 维持进化多样性的关键设计。

岛屿模型的思想是：不维护一个全局种群，而是把种群拆成多个独立进化的子种群（岛屿），每个岛屿在自己的搜索区域深耕；每隔若干代，把各岛屿上的优秀程序迁移到相邻岛屿，实现知识共享。这样既避免了单一种群过早收敛到局部最优，又通过周期性交流保留了全局进步的动力。

三个核心参数

database: num_islands: 5 # Number of separate populations migration_interval: 50 # Migrate every N generations migration_rate: 0.1 # Fraction of top programs to migrate

• num_islands：岛屿数量。岛屿越多，独立搜索方向越多、多样性越强，但收敛变慢；推荐大多数问题取 3–10；
• migration_interval：每隔多少代迁移一次。值越大，各岛屿越独立；推荐 25–100 代；
• migration_rate：每次迁移时，从每个岛屿顶部程序（按适应度降序）中迁出的比例，推荐 0.05–0.2（5%–20%）。比例越高，知识传播越快。

源码级的迁移实现细节

在 openevolve/database.py 中可以看到岛屿机制的真实实现：

• 轮转调度：next_island()以 round-robin 方式切换当前进化岛屿，increment_island_generation()维护每个岛屿的代数计数器（openevolve/database.py）；
• 迁移判定：should_migrate()比较"最大岛屿代数"与"上次迁移代数"的差值是否达到migration_interval（openevolve/database.py）；
• 迁移数量：migrate_programs()将每个岛屿的程序按get_fitness_score（优先combined_score，否则对非特征维度指标取平均）降序排列，取max(1, int(len(island_programs) * migration_rate))个作为迁出对象（openevolve/database.py）；
• 环状拓扑：默认把迁出程序复制到相邻岛屿(i+1) % n与(i-1) % n（openevolve/database.py），即"邻居共享"而非全局广播；
• 去重保护：_migrate_one()会跳过目标岛屿已存在相同代码的程序，并为迁移副本生成新 UUID、打上migrant: true标记（openevolve/database.py）；
• 最少岛屿限制：岛屿数小于 2 时直接跳过迁移（openevolve/database.py）。

这些细节解释了为什么migration_rate是"比例"而非"数量"：迁移量随岛屿种群规模动态缩放，小种群也能保证至少迁移 1 个程序。

何时使用什么：参数选择速查

configs/README.md与 configs/island_examples.yaml 给出的经验法则：

island_config_example.yaml：一份可直接运行的岛屿配置

configs/island_config_example.yaml 是岛屿模型的"标准答案"，它同时示范了两套 LLM 配置语法与岛屿专属系统消息的用法：

max_iterations: 1000 checkpoint_interval: 100 log_level: "INFO" llm: primary_model: "gemini-2.0-flash-lite" primary_model_weight: 0.8 secondary_model: "gemini-2.0-flash" secondary_model_weight: 0.2 temperature: 0.7 top_p: 0.95 max_tokens: 4096 database: population_size: 500 archive_size: 100 num_islands: 5 # 5 个独立种群 migration_interval: 50 # 每 50 代迁移 migration_rate: 0.1 # 迁移顶部 10% 的程序 elite_selection_ratio: 0.1 exploration_ratio: 0.3 exploitation_ratio: 0.7 feature_bins: 10 prompt: system_message: "Improve the program through evolution." island_system_messages: - "Focus on simpler algorithms." - null - "Focus on runtime performance." num_top_programs: 3 num_diverse_programs: 2 use_template_stochasticity: true evaluator: timeout: 300 max_retries: 3 cascade_evaluation: true parallel_evaluations: 4 diff_based_evolution: true allow_full_rewrites: false max_code_length: 10000

亮点解读：

1. 岛屿专属提示词：island_system_messages允许给不同岛屿定制演化风格——岛屿 0 专注"更简单的算法"、岛屿 2 专注"运行时性能"，第二个条目为null表示该岛屿沿用system_message。这种"分工进化"正是岛屿模型多样性的延伸；
2. 兼容语法：primary_model+secondary_model的写法会在Config加载时被自动展开为models权重列表（主模型 0.8、次模型 0.2）；
3. feature_bins 支持字典形式：注释中展示了feature_bins: {performance: 20, correctness: 10}的按维度分箱写法。

island_examples.yaml：五大典型场景配置速查

configs/island_examples.yaml 把岛屿参数压缩成五个可直接套用的场景模板：

# 1. 最大多样性（适合复杂问题、长时运行、避免局部最优） max_diversity: database: num_islands: 10 migration_interval: 25 migration_rate: 0.2 population_size: 1000 archive_size: 200 # 2. 聚焦探索（适合结构清晰的问题、较短运行） focused_exploration: database: num_islands: 3 migration_interval: 100 migration_rate: 0.05 population_size: 500 archive_size: 50 # 3. 均衡方案（大多数问题的默认起点） balanced: database: num_islands: 5 migration_interval: 50 migration_rate: 0.1 population_size: 1000 archive_size: 100 # 4. 快速探索（小规模、原型验证） quick_exploration: database: num_islands: 3 migration_interval: 20 migration_rate: 0.15 population_size: 200 archive_size: 30 # 5. 大规模进化（复杂优化、超长进化运行） large_scale: database: num_islands: 15 migration_interval: 75 migration_rate: 0.08 population_size: 2000 archive_size: 300

从 5 个场景可以观察出清晰的权衡规律：max_diversity用 10 个岛屿 + 高频高比例迁移（25 代 / 20%）最大化搜索空间覆盖；focused_exploration用 3 个岛屿 + 低频低比例迁移（100 代 / 5%）让每个岛屿深入挖掘；large_scale则把岛屿数推到 15、种群扩到 2000，同时用保守的 8% 迁移率避免大规模种群被过早同化。参数选取的本质是在多样性（多岛、少迁）与收敛速度（少岛、多迁）之间找平衡点。

早期停止（Early Stopping）配置

configs/early_stopping_example.yaml 演示了如何在进化长跑中自动止损：

max_iterations: 1000 checkpoint_interval: 50 log_level: "INFO" # 连续 30 代无改进即停止 early_stopping_patience: 30 # Stop after 30 iterations without improvement convergence_threshold: 0.01 # Minimum improvement of 0.01 required to reset patience early_stopping_metric: "combined_score" # Track the combined_score metric llm: models: - name: "gpt-4o-mini" weight: 1.0 api_base: "https://api.openai.com/v1" temperature: 0.7 max_tokens: 4096 database: population_size: 50 num_islands: 3 migration_interval: 20 evaluator: timeout: 60 max_retries: 2 parallel_evaluations: 2 diff_based_evolution: true max_code_length: 8000

三个早期停止参数的语义（见 openevolve/config.py）：

• early_stopping_patience：连续 N 次迭代无改进即停止；null表示禁用。该示例中30表示"30 代无改进就收工"，可显著节省 LLM API 调用成本；
• convergence_threshold：判定"有改进"的最小幅度。只有当early_stopping_metric的提升超过该阈值（示例为 0.01）才会重置耐心计数器；若只是小幅抖动则不重置；
• early_stopping_metric：跟踪的指标，默认combined_score，可改为评估器返回的其他指标名。

该文件同样是一个完整的可运行配置（gpt-4o-mini + OpenAI API），适合预算有限、想快速验证想法的场景。关于早期停止参数更细的行为与校验逻辑，可参考 tests/test_early_stopping_config.py。

使用方法：把配置跑起来

方式一：命令行启动（推荐快速上手）

先复制模板为自有配置：

cp configs/default_config.yaml my_config.yaml # Edit my_config.yaml for your specific needs

然后通过仓库入口脚本openevolve-run.py启动：

python openevolve-run.py initial_program.py evaluator.py --config my_config.yaml --output my_output

CLI 支持的主要参数（见 openevolve/cli.py）：

实际项目中这种用法非常常见，例如 examples/arc_benchmark/run_evolution.sh 中的启动命令：

python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --output $OUTPUT_DIR "$@"

方式二：Python API 启动（适合集成与脚本化）

configs/README.md给出的 API 用法如下：

from openevolve import OpenEvolve from openevolve.config import Config config = Config() config.from_yaml("my_config.yaml") evolve = OpenEvolve( initial_program_path="program.py", evaluation_file="evaluator.py", config=config )

此外，仓库还提供了更简洁的函数式 APIrun_evolution（openevolve/api.py），它接受"文件路径 / 代码字符串 / 代码行列表"三种形式的初始程序，以及"文件路径 / Callable"两种形式的评估器，config参数既可以是 YAML 路径也可以是Config对象：

from openevolve import run_evolution result = run_evolution( initial_program="program.py", evaluator="evaluator.py", config="my_config.yaml", iterations=200, ) print(result.best_score)

配置加载的底层行为（了解即可）

从 openevolve/config.py 的Config.from_yaml/from_dict实现可知：

• YAML 通过yaml.safe_load读取，再用dacite.from_dict转换为类型化的Configdataclass 结构，因此字段名必须与 dataclass 定义一致；
• llm.temperature/top_p为null时会被自动剔除，避免 dacite 类型错误；
• 顶层random_seed会自动下放到database.random_seed；
• 两处校验会直接抛出ValueError：prompt.island_system_messages条目数超过database.num_islands；prompt.programs_as_changes_description=true但diff_based_evolution=false；
• diff_pattern若提供，会先尝试编译正则，非法表达式会报错。

从示例到实战：参考仓库里的真实配置

如果想看"岛屿参数之外"的完整实战配置，仓库的 examples 目录提供了大量真实任务的配置文件，是绝佳的参考样本：

• examples/circle_packing/config_phase_1.yaml：圆填充问题（n=26），使用 4 个岛屿、cascade_thresholds: [0.5, 0.75]、diff_based_evolution: false（构造型程序用全量重写）以及含领域知识的长 system message；
• examples/arc_benchmark/config.yaml：ARC 基准任务的配置，配套post_evolution_eval.py做进化后评估；
• examples/algotune/：AlgoTune 基准下的多个算法优化任务（FFT、LU 分解、特征向量等），每个任务都包含config.yaml、evaluator.py与initial_program.py三件套。

综合来看，OpenEvolve 的配置哲学可以总结为三句话：用default_config.yaml保证参数覆盖完整，用岛屿三参数（num_islands/migration_interval/migration_rate）控制多样性与收敛的平衡，用早期停止参数控制成本与收益的平衡。从复制模板、调整岛屿参数、按需开启早期停止，到用 CLI 或 API 启动任务，这就是一条完整且可复现的 OpenEvolve 配置实战路径。

• 人工智能
• 大模型
• AI Agent
• 代码智能体
• 自主智能体