eval_agent/design_draft/EVAL_SERVICE_INTEGRATION.md

Eval Service 集成到 ShinkaEvolve

✅ 集成完成

Eval Service 已成功集成到 ShinkaEvolve，支持异步评估模式。

🎯 修改内容（最小化）

1. 数据结构扩展

# EvolutionConfig - 新增 3 个字段
class EvolutionConfig:
    eval_service_url: Optional[str] = None  # 已存在
    use_eval_service: bool = False  # 新增：是否使用 eval service 做评估
    evaluator_module: Optional[str] = None  # 新增：evaluator 模块路径
    evaluator_function: str = "main"  # 新增：evaluator 函数名

# RunningJob - 新增 1 个字段
class RunningJob:
    use_eval_service: bool = False  # 新增：标记是否使用 eval service

2. 核心方法修改

_submit_new_job() - 选择提交方式：

if self.eval_service_url and self.evo_config.use_eval_service:
    job_id = self._submit_to_eval_service(exec_fname, results_dir, current_gen)
else:
    job_id = self.scheduler.submit_async(exec_fname, results_dir)

_check_completed_jobs() - 选择检查方式：

if job.use_eval_service:
    is_complete = self._check_eval_service_status(job.job_id)
else:
    is_running = self.scheduler.check_job_status(job)

_process_completed_job() - 选择结果获取方式：

if job.use_eval_service:
    results = self._get_eval_service_results(job.job_id, job.results_dir)
else:
    results = self.scheduler.get_job_results(job.job_id, job.results_dir)

3. 新增辅助方法（3个）

• _submit_to_eval_service() - 提交评估到 eval service
• _check_eval_service_status() - 检查 eval service 任务状态
• _get_eval_service_results() - 获取 eval service 结果

总计: ~60 行新增代码

📊 使用方式

方式 1：传统模式（默认）

evo_config = EvolutionConfig(
    # ... 其他配置 ...
    eval_service_url=None,  # 或者不设置
)

行为：

• 使用 scheduler 执行评估（旧方式）
• 完全不受影响

方式 2：通知模式（已有）

evo_config = EvolutionConfig(
    # ... 其他配置 ...
    eval_service_url="http://localhost:8765",
    use_eval_service=False,  # 默认值
)

行为：

• 使用 scheduler 执行评估
• 完成后通知 eval service（触发 Agent）

方式 3：评估模式（新）

evo_config = EvolutionConfig(
    # ... 其他配置 ...
    eval_service_url="http://localhost:8765",
    use_eval_service=True,  # 启用 eval service 评估
    evaluator_module="examples.circle_packing.evaluate_ori",
    evaluator_function="main",
)

行为：

• 提交到 eval service 执行评估（异步）
• Eval service 运行 primary + auxiliary evaluators
• 自动集成所有 metrics
• 可能触发 Agent 分析

🚀 快速开始

1. 启动 Eval Service

python eval_agent/ev2_service_standalone.py \
    --results-dir /path/to/experiment \
    --primary-evaluator examples/circle_packing/evaluate_ori.py \
    --port 8765

2. 运行 ShinkaEvolve

python examples/circle_packing/run_with_eval_service.py

或者修改现有脚本：

from shinka.core import EvolutionRunner, EvolutionConfig

evo_config = EvolutionConfig(
    # ... 基础配置 ...
    
    # 启用 eval service 评估
    eval_service_url="http://localhost:8765",
    use_eval_service=True,
    evaluator_module="examples.circle_packing.evaluate_ori",
    evaluator_function="main",
)

runner = EvolutionRunner(evo_config, job_config, db_config)
runner.run()

📊 数据流

ShinkaEvolve:
  1. 生成代码 → gen_1/main.py
  2. POST /api/v1/notify/generation_complete
     (立即返回 job_id)
  3. 继续生成 gen_2（不等待 gen_1 完成）
  4. 轮询 gen_1 状态...
  5. gen_1 完成 → 获取 metrics → 添加到 DB
  6. 继续进化...

Eval Service（后台）:
  1. 接收请求，启动后台任务
  2. 运行 primary evaluator
  3. 运行 auxiliary evaluators
  4. 保存 metrics.json
  5. 决定是否触发 Agent

✅ 优势

1. 最小修改：只修改了 ~60 行核心代码
2. 完全兼容：旧代码不受任何影响
3. 渐进式：可以逐步迁移到新模式
4. 并发优化：利用现有的并发机制
5. 自动集成：primary + auxiliary metrics 自动整合

🧪 测试

# 1. 启动 eval service
python eval_agent/ev2_service_standalone.py \
    --results-dir /tmp/test \
    --primary-evaluator examples/circle_packing/evaluate_ori.py

# 2. 运行测试
python test_eval_service_unified.py

# 3. 运行集成示例
python examples/circle_packing/run_with_eval_service.py

📝 配置选项

选项	类型	默认值	说明
eval_service_url	str	None	Eval Service URL
use_eval_service	bool	False	是否使用 eval service 做评估
evaluator_module	str	None	Evaluator 模块路径
evaluator_function	str	"main"	Evaluator 函数名

🔧 代码统计

• 修改文件: shinka/core/runner.py
• 新增配置: 3 个字段
• 新增方法: 3 个辅助方法
• 修改方法: 3 个核心方法
• 新增代码: ~60 行
• linter 错误: 0

🎯 下一步

现在可以：

1. ✅ 使用传统模式（不受影响）
2. ✅ 使用通知模式（触发 Agent）
3. ✅ 使用评估模式（完整集成）

选择最适合你的模式，逐步迁移！

---

实施日期: 2026-02-03
修改者: AI Assistant
状态: ✅ 完成并测试