ShinkaEvolve: 朝着开放-ended且样本高效的程序进化 🧬

shinka 是一个将大型语言模型（LLMs）与进化算法相结合的框架，用于推动科学发现。通过利用 LLM 的创造性能力和进化搜索的优化能力，shinka 能够实现科学代码的自动化探索与改进。该系统受到 AI Scientist、AlphaEvolve 和 达尔文哥德尔机 的启发：它维护一个由多代演化而来的程序种群，并由一组 LLM 作为智能突变算子，提出代码改进建议。

2026年3月更新：重构了 API，并统一了运行器 ShinkaEvolveRunner（取代了 EvolutionRunner 和 AsyncEvolutionRunner）。现在可以通过 PyPI 和 uv 安装 shinka：pip install shinka-evolve。

2026年2月更新：新增了 agent 技能，用于在编码代理（Claude Code、Codex 等）中使用 shinka 进行新任务生成（shinka-setup）、仓库转换（shinka-convert）、进化（shinka-run）以及结果检查（shinka-inspect）。可通过 npx 安装这些技能：

npx skills add SakanaAI/ShinkaEvolve --skill '*' -a claude-code -a codex -y

2026年1月更新：ShinkaEvolve 已被 ICLR 2026 接受，我们还发布了包含新功能的 更新日志。

2025年11月更新：Rob 就我们的 ShinkaEvolve 项目进行了多次公开演讲（官方、AutoML 研讨会)。

2025年10月更新：ShinkaEvolve 支持 Team Unagi 赢得了 ICFP 2025 编程竞赛。

该框架支持在本地或 Slurm 集群上对候选方案进行 并行评估。它维护着一个成功解决方案的档案，从而实现不同进化岛屿之间的知识转移。shinka 特别适用于那些存在验证器、旨在优化性能指标同时保持代码正确性和可读性的科学任务。

文档 📝

安装与快速入门 🚀

# 从 PyPI 安装
pip install shinka-evolve

# 或者使用 uv
uv pip install shinka-evolve

# 运行你的第一个进化实验
shinka_launch variant=circle_packing_example

发行包名称为 shinka-evolve；Python 导入语句仍为 import shinka。

shinka_launch 仍然支持原有的简写组覆盖方式：

shinka_launch variant=circle_packing_example
shinka_launch task=novelty_generator database=island_small

软件包内自带 Hydra 预设，位于 shinka/configs/ 目录下。若要从 PyPI 安装中添加自定义预设而不克隆仓库，可以将其放置在自己的配置目录中，并通过 --config-dir 参数指定：

mkdir -p ~/my-shinka-configs/variant
$EDITOR ~/my-shinka-configs/variant/my_variant.yaml
shinka_launch --config-dir ~/my-shinka-configs variant=my_variant

对于从源码进行开发安装的情况：

git clone https://github.com/SakanaAI/ShinkaEvolve
cd ShinkaEvolve
uv venv --python 3.11
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv pip install -e .

有关详细的安装说明和使用示例，请参阅 入门指南。

示例 📖

使用 Python API 运行 shinka 🐍

对于使用默认设置的最简单配置，您只需指定评估程序即可：

from shinka.core import ShinkaEvolveRunner, EvolutionConfig
from shinka.database import DatabaseConfig
from shinka.launch import LocalJobConfig, SlurmCondaJobConfig, SlurmDockerJobConfig

# 最简配置 - 只需指定必要内容
job_conf = LocalJobConfig(eval_program_path="evaluate.py")
# 或为每个作业单独加载 uv/venv 环境：
# job_conf = LocalJobConfig(
#     eval_program_path="evaluate.py",
#     activate_script=".venv/bin/activate",
# )
# 或在 SLURM 上运行评估：
# job_conf = SlurmCondaJobConfig(
#     eval_program_path="evaluate.py",
#     partition="gpu",
#     time="01:00:00",
#     cpus=1,
#     gpus=1,
#     mem="8G",
#     conda_env="shinka",
# )
# 或在 SLURM 上的 Docker 容器中运行评估：
# job_conf = SlurmDockerJobConfig(
#     eval_program_path="evaluate.py",
#     image="ubuntu:latest",
#     partition="gpu",
#     time="01:00:00",
#     cpus=1,
#     gpus=1,
#     mem="8G",
# )
db_conf = DatabaseConfig()
evo_conf = EvolutionConfig(init_program_path="initial.py")

runner = ShinkaEvolveRunner(
    evo_config=evo_conf,
    job_config=job_conf,
    db_config=db_conf,
    max_evaluation_jobs=2,
    max_proposal_jobs=3,  # 当提案生成速度慢于评估时，适度超量提交任务
    max_db_workers=4,
)
runner.run()

评估设置与初始解决方案 🏃

要使用 ShinkaEvolveRunner, 你需要两个关键文件：evaluate.py 脚本定义了如何测试和评分你的程序——它会运行多次评估、验证结果，并将这些结果汇总成指标，以指导 shinka 的进化循环。initial.py 文件包含你的初始解决方案，其中包含了核心算法，该算法将在多代迭代中由 LLM 不断改进。

from shinka.core import run_shinka_eval

def main(program_path: str,
         results_dir: str):
    metrics, correct, err = run_shinka_eval(
        program_path=program_path,
        results_dir=results_dir,
        experiment_fn_name="run_experiment",
        num_runs=3, # 多次评估以进行汇总
        run_workers=1,  # >1 => 每次运行并行
        get_experiment_kwargs=get_kwargs,
        aggregate_metrics_fn=aggregate_fn,
        validate_fn=validate_fn,  # 可选
    )

def get_kwargs(run_idx: int) -> dict:
    return {"param1": "value", "param2": 42}

def aggregate_fn(results: list) -> dict:
    score = results[0]
    text = results[1]
    return {
        "combined_score": float(score),
        "public": {...},  # shinka可见
        "private": {...},  # shinka不可见
        "extra_data": {...},  # 存储为 pkl
        "text_feedback": text,  # str反馈
    }

if __name__ == "__main__":
    # argparse程序路径&目录
    main(program_path, results_dir)

# EVOLVE-BLOCK-START
def advanced_algo():
    # 这部分将被进化
    return solution
# EVOLVE-BLOCK-END

def run_experiment(**kwargs):
    """主函数，由评估者调用"""
    result = solve_problem(kwargs)
    return result

def solve_problem(params):
    solution = advanced_algo()
    return solution

带有 Hydra 的 shinka 启动器 🚀

shinka 启动器利用 Hydra 轻松配置并启动进化实验。它支持通过 Hydra 强大的覆盖语法进行简洁的配置，从而便于管理和迭代科学探索。

# 使用共享的默认基准运行
shinka_launch

# 使用自定义参数运行
shinka_launch \
    task=circle_packing \
    database=island_large \
    evolution=small_budget \
    cluster=local \
    evo_config.num_generations=20

有关全面的配置选项和高级用法，请参阅配置指南。

shinka_run 代理 CLI 🤖

shinka_run 是一个用于异步进化的任务目录启动器。它专为代理工作流设计，无需 Hydra 配置文件。

# 查看完整界面（详细帮助）
shinka_run --help

# 最小化运行
shinka_run \
    --task-dir examples/circle_packing \
    --results_dir results/circle_agent_run \
    --num_generations 20

# 使用关键字覆盖运行
shinka_run \
    --task-dir examples/circle_packing \
    --results_dir results/circle_agent_custom \
    --num_generations 50 \
    --max-evaluation-jobs 6 \
    --set db.num_islands=2 \
    --set job.time=00:10:00 \
    --set job.activate_script=.venv/bin/activate \
    --set evo.llm_models='["gpt-5-mini","gemini-3-flash-preview"]'

# 加载可选 YAML 配置文件（相对于 --task-dir），然后通过 --set 覆盖
shinka_run \
    --task-dir examples/circle_packing \
    --config-fname shinka_small.yaml \
    --results_dir results/circle_agent_from_yaml \
    --num_generations 50 \
    --set db.num_islands=2

--task-dir 必须包含 evaluate.py 和 initial.<ext>。
--config-fname 可以定义 evo/db/job（或 evo_config/db_config/job_config）以及 max_evaluation_jobs/max_proposal_jobs/max_db_workers 和 verbose/debug。
优先级：配置 YAML < --set < 权威性标志。
--results_dir 和 --num_generations 具有权威性，始终会覆盖配置/--set 中的 evo.results_dir 和 evo.num_generations 值。

交互式 WebUI 🎨

使用 Shinka 的交互式 Web 界面实时监控您的进化实验！WebUI 提供进化过程、谱系树和性能指标的实时可视化。

在启动进化实验的同时启动 WebUI：

# 开始您的进化实验
shinka_launch

# 在另一个终端中启动 WebUI
shinka_visualize --port 8888 --open

有关详细的 WebUI 文档，请参阅WebUI 指南。

贡献 👥

欢迎在代码、文档、代表性基准测试和错误报告等方面做出贡献。

请在提交问题或拉取请求之前阅读贡献指南。其中记录了预期的问题和 PR 结构、本地检查，以及对核心程序进化流程进行更改所需的额外证据。

如果您提议对核心进化流程进行更改，请附上在一个具有代表性的可运行任务上的结果，以突出新功能，并将其与基准进行比较。请勿仅为了证明 PR 的合理性而随意添加基准测试任务。

相关开源项目 🧑‍🔧

• OpenEvolve：AlphaEvolve 的开源实现
• LLM4AD：基于大型语言模型的算法设计平台

引用 ✍️

如果您在研究中使用 ShinkaEvolve，请按以下方式引用：

@article{lange2025shinka,
  title={ShinkaEvolve: Towards Open-Ended And Sample-Efficient Program Evolution},
  author={Lange, Robert Tjarko and Imajuku, Yuki and Cetin, Edoardo},
  journal={arXiv preprint arXiv:2509.19349},
  year={2025}
}

ShinkaEvolve 快速上手指南

ShinkaEvolve 是一个结合大语言模型（LLM）与进化算法的框架，旨在通过自动化探索和改进科学代码来驱动科学发现。它维护一个程序种群，利用 LLM 作为智能变异算子，在多代演化中不断优化代码性能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：>= 3.10 (推荐使用 Python 3.11)
• 包管理器：推荐使用 uv (高速安装) 或 pip
• API 密钥：需配置主流 LLM 提供商的 API Key (如 OpenAI, Google Gemini 等)，用于代码生成和评估。

提示：国内用户若访问 PyPI 较慢，可配置国内镜像源加速安装。

• uv 示例：uv pip install shinka-evolve --index-url https://pypi.tuna.tsinghua.edu.cn/simple
• pip 示例：pip install shinka-evolve -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

您可以选择通过 PyPI 直接安装稳定版，或从源码安装以进行开发。

方式一：使用 uv 安装（推荐，速度最快）

# 创建并激活虚拟环境（可选但推荐）
uv venv --python 3.11
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装 shinka-evolve
uv pip install shinka-evolve

方式二：使用 pip 安装

pip install shinka-evolve

方式三：从源码安装（开发者模式）

如果您需要修改框架源码或运行最新示例：

git clone https://github.com/SakanaAI/ShinkaEvolve
cd ShinkaEvolve
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .

基本使用

安装完成后，您可以通过命令行工具或 Python API 快速启动第一个演化实验。

方法 A：命令行快速启动 (CLI)

使用内置的预设配置运行一个简单的“圆堆积优化”示例：

shinka_launch variant=circle_packing_example

自定义配置运行： 您也可以通过组合不同的任务、数据库和变体来运行实验：

shinka_launch task=novelty_generator database=island_small

使用自定义配置文件： 如果您有自己的 Hydra 配置文件，可以指定配置目录运行：

mkdir -p ~/my-shinka-configs/variant
# 编辑您的配置文件 ...
shinka_launch --config-dir ~/my-shinka-configs variant=my_variant

方法 B：Python API 调用

对于更灵活的控制，您可以在 Python 脚本中直接定义运行逻辑。以下是最小化配置示例：

from shinka.core import ShinkaEvolveRunner, EvolutionConfig
from shinka.database import DatabaseConfig
from shinka.launch import LocalJobConfig

# 1. 配置作业执行环境 (本地运行)
# 只需指定评估脚本路径即可
job_conf = LocalJobConfig(eval_program_path="evaluate.py")

# 2. 配置数据库 (默认使用本地 SQLite)
db_conf = DatabaseConfig()

# 3. 配置演化参数
# 指定初始程序路径
evo_conf = EvolutionConfig(init_program_path="initial.py")

# 4. 初始化并运行
runner = ShinkaEvolveRunner(
    evo_config=evo_conf,
    job_config=job_conf,
    db_config=db_conf,
    max_evaluation_jobs=2,       # 最大并行评估任务数
    max_proposal_jobs=3,         # 最大并行提案生成数
    max_db_workers=4,            # 最大数据库工作线程数
)

runner.run()

运行说明：

1. 确保当前目录下存在 evaluate.py (评估脚本) 和 initial.py (初始代码)。
2. 设置好您的 LLM API 环境变量 (例如 OPENAI_API_KEY)。
3. 运行上述 Python 脚本即可开始演化过程。

更多高级用法（如 Slurm 集群支持、异步演化、WebUI 监控等），请参考官方文档中的详细教程。