# ShinkaEvolve: results_dir 传递流程详解 ## 🎯 问题 当运行 ShinkaEvolve 时，评估脚本（evaluate.py）是如何知道要把结果保存到指定的 `results_dir` 的？ ## 📊 完整数据流程 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 1 步: 用户配置 (run_circle_packing_*.py) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ evo_config = EvolutionConfig( │ │ results_dir="examples/circle_packing/results/results_exp_20260129", │ │ ... │ │ ) │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 2 步: EvolutionRunner 初始化 (shinka/core/runner.py:90-108) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ class EvolutionRunner: │ │ def __init__(self, evo_config, ...): │ │ if evo_config.results_dir is None: │ │ timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") │ │ self.results_dir = f"results_{timestamp}" │ │ else: │ │ self.results_dir = Path(evo_config.results_dir) ← 使用配置 │ │ │ │ # 创建目录 │ │ Path(self.results_dir).mkdir(parents=True, exist_ok=True) │ │ │ │ 结果: self.results_dir = "examples/.../results_exp_20260129" │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 3 步: 运行每一代 (shinka/core/runner.py:461-496) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ def _run_generation_0(self): │ │ # 构建当前代的目录路径 │ │ initial_dir = f"{self.results_dir}/{FOLDER_PREFIX}_0" │ │ # 即: "examples/.../results_exp_20260129/gen_0" │ │ │ │ Path(initial_dir).mkdir(parents=True, exist_ok=True) │ │ exec_fname = f"{initial_dir}/main.py" │ │ │ │ # 构建结果子目录 │ │ results_dir = f"{self.results_dir}/{FOLDER_PREFIX}_0/results" │ │ # 即: "examples/.../results_exp_20260129/gen_0/results" │ │ │ │ Path(results_dir).mkdir(parents=True, exist_ok=True) │ │ │ │ # 运行评估，传递 results_dir │ │ results, rtime = self.scheduler.run(exec_fname, results_dir) ←关键 │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 4 步: JobScheduler 构建命令 (shinka/launch/scheduler.py:98-148) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ def _build_command(self, exec_fname_t, results_dir_t): │ │ cmd = [ │ │ "python", │ │ f"{self.config.eval_program_path}", ← 评估脚本路径 │ │ "--program_path", │ │ f"{exec_fname_t}", ← 被评估的程序 │ │ "--results_dir", │ │ results_dir_t, ← 结果目录！ │ │ ] │ │ │ │ 实际命令: │ │ python examples/circle_packing/evaluate_with_auxiliary.py \ │ │ --program_path examples/.../gen_0/main.py \ │ │ --results_dir examples/.../gen_0/results │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 5 步: 评估脚本接收参数 (evaluate_with_auxiliary.py:260-295) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ if __name__ == "__main__": │ │ parser = argparse.ArgumentParser(...) │ │ parser.add_argument( │ │ "--program_path", │ │ type=str, │ │ default="initial.py", │ │ ) │ │ parser.add_argument( │ │ "--results_dir", ← 接收命令行参数 │ │ type=str, │ │ default="results", │ │ ) │ │ │ │ args = parser.parse_args() │ │ │ │ main( │ │ program_path=args.program_path, │ │ results_dir=args.results_dir, ← 传递给 main 函数 │ │ ) │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 6 步: 评估执行和结果保存 (evaluate_with_auxiliary.py:161-256) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ def main(program_path, results_dir, ...): │ │ # 确保目录存在 │ │ os.makedirs(results_dir, exist_ok=True) │ │ │ │ # 运行评估 │ │ metrics, correct, error = run_shinka_eval( │ │ program_path=program_path, │ │ results_dir=results_dir, ← 传递给核心评估函数 │ │ ... │ │ ) │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 第 7 步: 核心评估函数保存结果 (shinka/core/wrap_eval.py:54-193) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ def run_shinka_eval(program_path, results_dir, ...): │ │ # ... 运行实验 ... │ │ │ │ # 保存额外数据 │ │ if "extra_data" in metrics: │ │ os.makedirs(results_dir, exist_ok=True) │ │ extra_file = os.path.join(results_dir, "extra.pkl") │ │ with open(extra_file, "wb") as f: │ │ pickle.dump(extra_data, f) │ │ │ │ # 保存主要结果 │ │ save_json_results(results_dir, metrics, correct, error) │ │ │ │ def save_json_results(results_dir, metrics, correct, error): │ │ os.makedirs(results_dir, exist_ok=True) │ │ metrics_file = os.path.join(results_dir, "metrics.json") │ │ correct_file = os.path.join(results_dir, "correct.json") │ │ │ │ # 保存文件 │ │ with open(metrics_file, "w") as f: │ │ json.dump(metrics, f, indent=4) │ │ with open(correct_file, "w") as f: │ │ json.dump({"correct": correct, "error": error}, f, indent=4) │ │ │ │ 结果文件: │ │ - examples/.../gen_0/results/metrics.json │ │ - examples/.../gen_0/results/correct.json │ │ - examples/.../gen_0/results/extra.pkl (如果有) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## 🔍 关键代码位置 ### 1. EvolutionConfig 定义 (shinka/core/runner.py:38-64) ```python @dataclass class EvolutionConfig: # ... 其他配置 ... results_dir: Optional[str] = None # 第59行：results_dir 配置项 # ... 其他配置 ... ``` ### 2. EvolutionRunner 使用配置 (shinka/core/runner.py:104-108) ```python if evo_config.results_dir is None: timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") self.results_dir = f"results_{timestamp}" else: self.results_dir = Path(evo_config.results_dir) # 使用用户配置 ``` ### 3. 构建每一代的路径 (shinka/core/runner.py:461-496) ```python def _run_generation_0(self): initial_dir = f"{self.results_dir}/{FOLDER_PREFIX}_0" # ... results_dir = f"{self.results_dir}/{FOLDER_PREFIX}_0/results" Path(results_dir).mkdir(parents=True, exist_ok=True) # 运行评估 results, rtime = self.scheduler.run(exec_fname, results_dir) ``` ### 4. JobScheduler 构建命令 (shinka/launch/scheduler.py:98-148) ```python def _build_command(self, exec_fname_t: str, results_dir_t: str) -> List[str]: cmd = [ "python", f"{self.config.eval_program_path}", "--program_path", f"{exec_fname_t}", "--results_dir", results_dir_t, # ← results_dir 作为命令行参数 ] return cmd ``` ### 5. 评估脚本接收参数 (evaluate_with_auxiliary.py:260-295) ```python if __name__ == "__main__": parser = argparse.ArgumentParser(...) parser.add_argument( "--program_path", type=str, default="initial.py", ) parser.add_argument( "--results_dir", # ← 接收命令行参数 type=str, default="results", ) args = parser.parse_args() main( program_path=args.program_path, results_dir=args.results_dir, # ← 传递给 main ) ``` ### 6. 保存结果 (shinka/core/wrap_eval.py:33-51) ```python def save_json_results( results_dir: str, # ← 接收 results_dir metrics: Dict[str, Any], correct: bool, error: Optional[str] = None, ) -> None: os.makedirs(results_dir, exist_ok=True) metrics_file = os.path.join(results_dir, "metrics.json") correct_file = os.path.join(results_dir, "correct.json") with open(metrics_file, "w", encoding="utf-8") as f: json.dump(metrics, f, indent=4) with open(correct_file, "w", encoding="utf-8") as f: json.dump({"correct": correct, "error": error}, f, indent=4) ``` ## 📁 实际目录结构示例 ``` examples/circle_packing/results/results_exp_20260129_150530/ │ ├── evolution_db_exp_20260129_150530.sqlite ← 数据库 ├── evolution_run.log ← 日志 ├── experiment_config.yaml ← 配置 │ ├── gen_0/ ← 第 0 代 │ ├── main.py ← 被评估的程序 │ └── results/ ← 评估结果目录 │ ├── metrics.json ← 性能指标 │ ├── correct.json ← 正确性标志 │ ├── extra.npz ← 额外数据 │ ├── packing_viz.png ← 可视化 │ └── auxiliary_analysis.json ← 辅助分析 │ ├── gen_1/ │ ├── main.py │ └── results/ │ ├── metrics.json │ └── ... │ ├── gen_2/ │ └── ... │ └── best/ ← 最佳结果（符号链接） └── results/ ├── metrics.json └── ... ``` ## 🔧 关键设计特点 ### 1. 层次化的目录结构 ``` {results_dir}/ ├── gen_0/results/ ← EvolutionRunner 创建 ├── gen_1/results/ ← EvolutionRunner 创建 └── gen_2/results/ ← EvolutionRunner 创建 └── metrics.json ← 评估脚本保存 ``` ### 2. 参数传递链 ``` 用户配置 → EvolutionConfig.results_dir → EvolutionRunner.results_dir → JobScheduler.run(results_dir) → 命令行参数 --results_dir → argparse 解析 → main(results_dir) → save_json_results(results_dir) → 文件保存 ``` ### 3. 职责分离 | 组件 | 职责 | |-----|------| | **EvolutionRunner** | 创建顶层目录和每代的子目录 | | **JobScheduler** | 构建命令并传递 results_dir 参数 | | **评估脚本** | 接收参数并执行评估 | | **run_shinka_eval** | 保存评估结果到指定目录 | ## 💡 为什么这样设计？ ### 优点 1. **解耦**: 评估脚本不需要知道 ShinkaEvolve 的目录结构 2. **灵活**: 可以独立运行评估脚本进行测试 3. **标准化**: 所有评估脚本使用相同的参数接口 4. **可追溯**: 每一代都有独立的结果目录 ### 示例：独立运行评估脚本 ```bash # 可以完全独立于 ShinkaEvolve 运行评估 python examples/circle_packing/evaluate_with_auxiliary.py \ --program_path my_solution.py \ --results_dir my_custom_results/ # 结果会保存在 my_custom_results/ 而不是 ShinkaEvolve 的目录结构中 ``` ## 🎯 总结 **评估脚本通过命令行参数 `--results_dir` 知道保存位置！** 整个流程是： 1. 用户在 `EvolutionConfig` 中设置 `results_dir` 2. `EvolutionRunner` 读取配置并创建目录结构 3. 对于每一代，构建 `{results_dir}/gen_X/results` 路径 4. `JobScheduler` 将这个路径作为 `--results_dir` 参数传递给评估脚本 5. 评估脚本通过 `argparse` 解析参数 6. `run_shinka_eval` 和 `save_json_results` 使用这个路径保存结果 这是一个**标准的命令行参数传递机制**，而不是硬编码或环境变量。 --- **创建时间**: 2026-01-29 **相关文件**: - `shinka/core/runner.py` - EvolutionRunner 和 EvolutionConfig - `shinka/launch/scheduler.py` - JobScheduler 命令构建 - `shinka/core/wrap_eval.py` - run_shinka_eval 和结果保存 - `examples/circle_packing/evaluate_with_auxiliary.py` - 评估脚本示例