File size: 41,238 Bytes
1556404 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 | # Evaluation Agent 设计方案
## 📋 可行性分析
**结论：完全可行！** 将evaluation脚本改造成agent不仅技术上可行，而且可以显著增强系统的适应性和智能化程度。
---
## 🏗️ 当前架构分析
### 当前Evaluation工作流
```
┌─────────────────────────────────────────────────────┐
│ EvolutionRunner (控制器) │
│ ├─ 生成新代码 (gen_N/main.py) │
│ ├─ 提交job到JobScheduler │
│ └─ 等待结果 │
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ JobScheduler 执行命令: │
│ python evaluate_with_auxiliary.py \ │
│ --program_path gen_N/main.py \ │
│ --results_dir gen_N/results │
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Evaluation Script (独立进程) │
│ ├─ 加载程序 │
│ ├─ 运行实验 (run_packing) │
│ ├─ 验证结果 (validate_packing) │
│ ├─ 计算metrics (固定的7个auxiliary metrics) │
│ ├─ 生成文本反馈 │
│ └─ 保存结果到文件: │
│ • metrics.json │
│ • correct.json │
│ • extra.npz │
│ • auxiliary_analysis.json │
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ EvolutionRunner 读取结果 │
│ ├─ 解析 metrics.json │
│ ├─ 提取 combined_score, public_metrics │
│ ├─ 写入数据库 (ProgramDatabase) │
│ └─ 用于选择下一代父程序 │
└─────────────────────────────────────────────────────┘
```
### 关键接口契约
**输入接口** (命令行参数):
```python
--program_path: str # 要评估的程序路径
--results_dir: str # 结果保存目录
--aux_config: str # (可选) 辅助评估配置
```
**输出接口** (文件系统):
```json
# metrics.json
{
"combined_score": 2.635, # 主评分 (必须)
"public": { # 公开指标 (LLM可见)
"centers_str": "...",
"num_circles": 26,
"aux_packing_efficiency": 0.842,
"aux_gap_analysis": 0.756,
...
},
"private": { # 私有指标 (仅记录)
"reported_sum_of_radii": 2.635
},
"text_feedback": "..." # (可选) 文本反馈
}
# correct.json
{
"correct": true,
"error": null
}
```
**数据库Schema** (Program表):
```python
@dataclass
class Program:
# 身份标识
id: str
code: str
generation: int
parent_id: Optional[str]
# 评估结果 (由evaluation写入)
combined_score: float
public_metrics: Dict[str, Any]
private_metrics: Dict[str, Any]
text_feedback: str
correct: bool
# 辅助数据
embedding: List[float]
metadata: Dict[str, Any]
# 进化关系
archive_inspiration_ids: List[str]
top_k_inspiration_ids: List[str]
children_count: int
```
---
## 🤖 Agent化改造方案
### 核心设计理念
**Agent ≠ 脚本的区别:**
1. **自主决策**: Agent能根据context决定分析策略
2. **动态工具使用**: Agent能调用不同工具、生成新代码
3. **历史感知**: Agent能访问数据库了解进化历史
4. **元学习**: Agent能改进自己的评估策略
### Agent架构设计
```
┌─────────────────────────────────────────────────────────────┐
│ EvaluationAgent (主控制器) │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Core Components: │ │
│ │ • LLM (decision maker) │ │
│ │ • Tool Registry (可调用的工具集) │ │
│ │ • Database Access (读写历史数据) │ │
│ │ • Code Executor (安全执行生成的代码) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Workflow: │ │
│ │ 1. 接收评估请求 (program_path, results_dir) │ │
│ │ 2. 查询数据库获取context │ │
│ │ 3. LLM规划评估策略 │ │
│ │ 4. 执行评估步骤 (调用工具/生成代码) │ │
│ │ 5. 聚合结果并生成反馈 │ │
│ │ 6. (可选) 更新数据库元信息 │ │
│ │ 7. 保存标准输出文件 │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Agent可用的工具 (Tools):
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Ground Truth │ │ Auxiliary │ │ Dynamic Metric │
│ Evaluation │ │ Metrics │ │ Generator │
│ • 运行程序 │ │ • 预定义指标 │ │ • LLM生成代码 │
│ • 验证约束 │ │ • 注册系统 │ │ • 编译并执行 │
│ • 计算主分数 │ │ │ │ • 安全沙箱 │
└──────────────────┘ └──────────────────┘ └──────────────────┘
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Database Query │ │ Visualization │ │ Meta Analysis │
│ • 查询历史 │ │ • 生成图表 │ │ • 趋势分析 │
│ • 统计分析 │ │ • 保存可视化 │ │ • 策略推荐 │
│ • 对比程序 │ │ │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘
数据库访问权限:
┌──────────────────────────────────────────────────────────┐
│ Database Interface (ProgramDatabase) │
│ ┌────────────────────────────────────────────────────┐ │
│ │ READ Operations (Agent可用): │ │
│ │ • get_all_programs() │ │
│ │ • get_programs_by_generation(gen) │ │
│ │ • get_top_programs(n, metric) │ │
│ │ • get_best_program(metric) │ │
│ │ • get_program(id) │ │
│ │ • 自定义SQL查询 (受限) │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ WRITE Operations (谨慎使用): │ │
│ │ • 只能写入metadata字段 │ │
│ │ • 不能修改 combined_score, correct 等核心字段 │ │
│ │ • 可以添加额外的分析结果到metadata │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
---
## 🔌 Agent对外接口设计
### 1. 命令行接口 (保持兼容)
```bash
# 基本接口 (与当前完全兼容)
python evaluation_agent.py \
--program_path gen_42/main.py \
--results_dir gen_42/results
# 扩展接口 (新增功能)
python evaluation_agent.py \
--program_path gen_42/main.py \
--results_dir gen_42/results \
--db_path path/to/evolution.sqlite \ # Agent可访问数据库
--agent_mode adaptive \ # 评估模式: static|adaptive|exploratory
--enable_dynamic_metrics \ # 允许生成新metrics
--feedback_style detailed # 反馈风格: minimal|normal|detailed
```
### 2. Python API接口
```python
from shinka.evaluation import EvaluationAgent, AgentConfig
# 配置Agent
agent_config = AgentConfig(
# LLM配置
llm_model="native-gemini-2.5-pro",
llm_temperature=0.7,
# 评估模式
mode="adaptive", # static | adaptive | exploratory
# 工具访问权限
enable_ground_truth=True, # 必须
enable_auxiliary_metrics=True, # 预定义辅助指标
enable_dynamic_metrics=True, # LLM生成新指标
enable_database_read=True, # 读取历史数据
enable_database_write_metadata=False, # 写入元数据
# 安全配置
code_execution_timeout=30, # 生成代码执行超时
max_tool_calls=20, # 最大工具调用次数
sandboxed_execution=True, # 沙箱执行
# 输出配置
generate_text_feedback=True,
save_detailed_analysis=True,
visualization=True,
)
# 创建Agent
agent = EvaluationAgent(
config=agent_config,
db_path="path/to/evolution.sqlite" # 可选
)
# 执行评估
metrics, correct, error = agent.evaluate(
program_path="gen_42/main.py",
results_dir="gen_42/results"
)
# Agent会自动保存标准输出文件
# - metrics.json
# - correct.json
# - auxiliary_analysis.json
# - (可选) agent_reasoning.json # Agent的决策过程
```
### 3. EvolutionRunner集成接口
```python
from shinka.core import EvolutionRunner, EvolutionConfig
from shinka.database import DatabaseConfig
from shinka.launch import LocalJobConfig
from shinka.evaluation import EvaluationAgentConfig # 新增
# 配置job使用Agent评估器
job_config = LocalJobConfig(
eval_program_path="shinka/evaluation/agent_main.py", # Agent入口
extra_cmd_args={
"agent_mode": "adaptive",
"enable_dynamic_metrics": True,
"db_path": "auto", # 自动传递数据库路径
}
)
# 数据库配置
db_config = DatabaseConfig(
db_path="evolution_db.sqlite",
# ... 其他配置
)
# 进化配置
evo_config = EvolutionConfig(
# ... 其他配置
use_text_feedback=True, # 接收Agent生成的反馈
)
# 运行时，Agent会自动获得:
# 1. 当前generation的程序路径
# 2. 数据库访问权限 (通过--db_path参数)
# 3. 历史程序信息
runner = EvolutionRunner(
job_config=job_config,
db_config=db_config,
evo_config=evo_config,
)
runner.run()
```
---
## 🛠️ Agent工具系统设计
### 工具接口规范
```python
from typing import Any, Dict, Optional
from dataclasses import dataclass
@dataclass
class ToolResult:
"""工具执行结果"""
success: bool
data: Any
error: Optional[str] = None
cost: float = 0.0 # API成本
class Tool:
"""工具基类"""
name: str
description: str
parameters: Dict[str, Any] # JSON Schema
def execute(self, **kwargs) -> ToolResult:
"""执行工具逻辑"""
raise NotImplementedError
```
### 核心工具清单
```python
# ============================================================================
# 1. GROUND TRUTH EVALUATION (必需工具)
# ============================================================================
class RunProgramTool(Tool):
"""运行被评估程序并获取原始结果"""
name = "run_program"
description = "Execute the program and get raw results (centers, radii, score)"
def execute(self, program_path: str, num_runs: int = 1) -> ToolResult:
# 调用 run_shinka_eval 的底层逻辑
# 返回: centers, radii, reported_score
pass
class ValidateResultsTool(Tool):
"""验证程序输出是否满足约束"""
name = "validate_results"
description = "Validate if results satisfy all constraints"
def execute(self, centers, radii) -> ToolResult:
# 调用 adapted_validate_packing
# 返回: is_valid, error_message
pass
# ============================================================================
# 2. AUXILIARY METRICS (预定义分析工具)
# ============================================================================
class ComputeMetricTool(Tool):
"""计算预定义的辅助指标"""
name = "compute_metric"
description = "Compute a predefined auxiliary metric"
parameters = {
"metric_name": {
"type": "string",
"enum": ["packing_efficiency", "gap_analysis", "edge_utilization", ...]
}
}
def execute(self, metric_name: str, centers, radii) -> ToolResult:
# 调用 METRIC_REGISTRY.get(metric_name)
pass
class ListMetricsTool(Tool):
"""列出所有可用的预定义指标"""
name = "list_metrics"
def execute(self) -> ToolResult:
return ToolResult(
success=True,
data=METRIC_REGISTRY.list_metrics()
)
# ============================================================================
# 3. DATABASE ACCESS (历史数据工具)
# ============================================================================
class QueryDatabaseTool(Tool):
"""查询数据库获取历史程序信息"""
name = "query_database"
description = "Query historical programs from database"
parameters = {
"query_type": {
"type": "string",
"enum": ["top_programs", "by_generation", "best_program", "all"]
},
"filters": {
"type": "object",
"properties": {
"metric": {"type": "string"},
"n": {"type": "integer"},
"generation": {"type": "integer"}
}
}
}
def execute(self, query_type: str, filters: Dict) -> ToolResult:
if query_type == "top_programs":
programs = self.db.get_top_programs(
n=filters.get("n", 10),
metric=filters.get("metric", "combined_score")
)
elif query_type == "by_generation":
programs = self.db.get_programs_by_generation(filters["generation"])
# ...
return ToolResult(
success=True,
data=[p.to_dict() for p in programs]
)
class CompareWithHistoryTool(Tool):
"""对比当前程序与历史程序"""
name = "compare_with_history"
def execute(self, current_metrics: Dict, comparison_type: str) -> ToolResult:
# comparison_type: "best" | "parent" | "generation_average"
# 返回对比分析结果
pass
# ============================================================================
# 4. DYNAMIC METRIC GENERATION (LLM生成新指标)
# ============================================================================
class GenerateMetricCodeTool(Tool):
"""让LLM生成新的评估指标代码"""
name = "generate_metric_code"
description = "Generate Python code for a new evaluation metric"
parameters = {
"metric_purpose": {"type": "string"},
"inspiration_from": {"type": "string"} # 参考已有指标
}
def execute(self, metric_purpose: str, inspiration_from: str = None) -> ToolResult:
# 调用LLM生成新metric代码
# 使用 LLMGeneratedMetric 框架
prompt = f"""
Generate a Python function to compute a new auxiliary metric for circle packing.
Purpose: {metric_purpose}
Requirements:
1. Function signature: def metric_name(centers: np.ndarray, radii: np.ndarray) -> MetricResult
2. Return MetricResult with name, value, interpretation, description, details
3. Use numpy for computations
4. Handle edge cases gracefully
Example structure:
```python
def my_metric(centers, radii):
# Your analysis logic here
score = ...
return MetricResult(
name="my_metric",
value=float(score),
interpretation="higher_better",
description="What this metric measures",
details={{"key": "value"}}
)
```
"""
llm_response = self.llm.query(prompt)
code = extract_code_from_response(llm_response)
return ToolResult(
success=True,
data={"code": code, "cost": llm_response.cost}
)
class CompileAndTestMetricTool(Tool):
"""编译并测试LLM生成的指标代码"""
name = "compile_and_test_metric"
def execute(self, code: str, test_data: Dict) -> ToolResult:
metric = LLMGeneratedMetric(
name="llm_metric",
code=code,
description="LLM generated metric",
interpretation="higher_better"
)
if not metric.compile():
return ToolResult(success=False, error="Compilation failed")
# 测试执行
try:
result = metric.evaluate(
centers=test_data["centers"],
radii=test_data["radii"]
)
return ToolResult(success=True, data=result)
except Exception as e:
return ToolResult(success=False, error=str(e))
# ============================================================================
# 5. VISUALIZATION & ANALYSIS (分析工具)
# ============================================================================
class VisualizeTool(Tool):
"""生成可视化"""
name = "visualize"
def execute(self, vis_type: str, data: Dict, output_path: str) -> ToolResult:
# vis_type: "packing" | "metrics_trend" | "comparison"
pass
class StatisticalAnalysisTool(Tool):
"""统计分析工具"""
name = "statistical_analysis"
def execute(self, data: List[float], analysis_type: str) -> ToolResult:
# analysis_type: "trend" | "distribution" | "correlation"
pass
# ============================================================================
# 6. META OPERATIONS (元操作)
# ============================================================================
class UpdateMetadataTool(Tool):
"""更新程序的metadata字段"""
name = "update_metadata"
description = "Add analysis results to program metadata (write to DB)"
def execute(self, program_id: str, metadata: Dict) -> ToolResult:
# 仅允许写入metadata字段，不能修改核心评估字段
program = self.db.get_program(program_id)
if program:
program.metadata.update(metadata)
# 写回数据库
# 注意：需要扩展ProgramDatabase添加update_metadata方法
pass
```
---
## 🧠 Agent决策流程
### Mode 1: Static Mode (兼容模式)
```python
def static_evaluation(agent, program_path, results_dir):
"""
完全兼容现有evaluation脚本的行为
"""
# 1. 运行程序
result = agent.tools["run_program"].execute(program_path)
centers, radii, score = result.data
# 2. 验证结果
validation = agent.tools["validate_results"].execute(centers, radii)
correct = validation.data["is_valid"]
# 3. 计算预定义auxiliary metrics
auxiliary_results = {}
for metric_name in agent.config.enabled_metrics:
metric_result = agent.tools["compute_metric"].execute(
metric_name, centers, radii
)
auxiliary_results[metric_name] = metric_result.data.value
# 4. 生成标准反馈
feedback = generate_standard_feedback(auxiliary_results, score)
# 5. 保存结果
metrics = {
"combined_score": score,
"public": {
"centers_str": format_centers_string(centers),
"num_circles": len(centers),
**{f"aux_{k}": v for k, v in auxiliary_results.items()}
},
"private": {"reported_sum_of_radii": score},
"text_feedback": feedback
}
save_metrics(results_dir, metrics, correct)
return metrics, correct
```
### Mode 2: Adaptive Mode (智能模式)
```python
def adaptive_evaluation(agent, program_path, results_dir, db_path):
"""
Agent根据context智能决策评估策略
"""
# 1. 获取context
context = agent.gather_context(program_path, db_path)
# 2. LLM规划评估策略
plan = agent.llm.plan_evaluation(context)
# 示例plan:
# {
# "steps": [
# {"action": "run_program", "params": {...}},
# {"action": "query_database", "params": {"query_type": "best_program"}},
# {"action": "compute_metric", "params": {"metric_name": "packing_efficiency"}},
# {"action": "compare_with_history", "params": {"comparison_type": "best"}},
# {"action": "generate_feedback", "params": {...}}
# ]
# }
# 3. 执行plan
execution_log = []
for step in plan["steps"]:
tool = agent.tools[step["action"]]
result = tool.execute(**step["params"])
execution_log.append(result)
# 如果某步失败，LLM可以调整策略
if not result.success:
plan = agent.llm.replan(plan, execution_log, result.error)
# 4. LLM聚合结果并生成反馈
final_metrics, feedback = agent.llm.aggregate_results(execution_log, context)
# 5. 保存结果 (保证接口兼容性)
save_metrics(results_dir, final_metrics, correct)
# 6. (可选) 保存Agent推理过程
save_agent_reasoning(results_dir, plan, execution_log)
return final_metrics, correct
```
### Mode 3: Exploratory Mode (探索模式)
```python
def exploratory_evaluation(agent, program_path, results_dir, db_path):
"""
Agent主动探索新的评估方法
"""
# 1. 标准评估
base_metrics, correct = adaptive_evaluation(agent, program_path, results_dir, db_path)
# 2. 分析历史趋势
trend_analysis = agent.tools["statistical_analysis"].execute(
data=get_historical_scores(agent.db),
analysis_type="trend"
)
# 3. 如果发现评估盲点，生成新metric
if agent.detect_evaluation_gap(trend_analysis):
# LLM生成新metric代码
new_metric_code = agent.tools["generate_metric_code"].execute(
metric_purpose="Identify patterns missed by existing metrics"
)
# 编译并测试
test_result = agent.tools["compile_and_test_metric"].execute(
code=new_metric_code.data["code"],
test_data={"centers": centers, "radii": radii}
)
if test_result.success:
# 注册新metric到全局registry
register_new_metric(new_metric_code.data["code"])
# 重新评估包含新metric
extended_metrics = compute_with_new_metric(centers, radii)
base_metrics["public"].update(extended_metrics)
# 4. 保存扩展结果
save_metrics(results_dir, base_metrics, correct)
return base_metrics, correct
```
---
## 🔒 安全性设计
### 代码执行沙箱
```python
class SafeCodeExecutor:
"""安全的代码执行环境"""
def __init__(self, timeout=30):
self.timeout = timeout
self.allowed_imports = {
'numpy', 'scipy', 'math', 'statistics'
}
self.forbidden_operations = {
'__import__', 'eval', 'exec', 'compile',
'open', 'file', 'input', 'raw_input'
}
def execute(self, code: str, inputs: Dict) -> Any:
"""在受限环境中执行代码"""
# 1. 静态分析检查
if self.has_forbidden_operations(code):
raise SecurityError("Forbidden operations detected")
# 2. 创建受限namespace
namespace = {
'np': numpy,
'MetricResult': MetricResult,
# ... 只提供必要的模块
}
namespace.update(inputs)
# 3. 超时执行
with timeout(self.timeout):
exec(code, namespace)
return namespace
```
### 数据库访问权限控制
```python
class RestrictedDatabaseAccess:
"""受限的数据库访问接口"""
def __init__(self, db: ProgramDatabase):
self.db = db
self.read_only_methods = [
'get_all_programs', 'get_programs_by_generation',
'get_top_programs', 'get_best_program', 'get_program'
]
self.write_allowed_fields = ['metadata'] # 只能写metadata
def __getattr__(self, name):
if name in self.read_only_methods:
return getattr(self.db, name)
else:
raise PermissionError(f"Method {name} not allowed for agent")
def update_metadata(self, program_id: str, metadata: Dict):
"""唯一允许的写入操作"""
program = self.db.get_program(program_id)
if program:
program.metadata.update(metadata)
# 需要在ProgramDatabase中添加此方法
self.db.update_program_metadata(program_id, program.metadata)
```
---
## 📊 Agent与外界的数据流
```
┌─────────────────────────────────────────────────────────────┐
│ EvolutionRunner (主系统) │
│ │
│ [每一代进化] │
│ ├─ 生成新代码: gen_N/main.py │
│ ├─ 调用Agent评估 ──────────────────────────┐ │
│ │ ▼ │
│ │ ┌──────────────────────────┐ │
│ │ │ EvaluationAgent │ │
│ │ │ (独立进程) │ │
│ │ │ │ │
│ │ │ 输入: │ │
│ │ │ • program_path │ │
│ │ │ • results_dir │ │
│ │ │ • db_path (可选) │ │
│ │ │ │ │
│ │ │ Agent内部流程: │ │
│ │ │ 1. 加载程序 │ │
│ │ │ 2. 运行评估 │ │
│ │ 读取数据库 ◄───────────┼ 3. 查询DB历史 ──┐ │ │
│ │ │ 4. LLM规划 │ │ │
│ │ │ 5. 工具调用 │ │ │
│ │ │ 6. 聚合结果 │ │ │
│ │ (可选)写metadata ◄─────┼ 7. 保存输出 │ │ │
│ │ │ │ │ │
│ │ │ 输出文件: │ │ │
│ │ │ • metrics.json │ │ │
│ │ │ • correct.json │ │ │
│ │ │ • agent_log.json│ │ │
│ │ └──────────────────┼───────┘ │
│ │ │ │
│ ├─ 读取评估结果 ◄────────────────────────────────┘ │
│ │ • combined_score │
│ │ • public_metrics (含aux metrics) │
│ │ • text_feedback │
│ │ │
│ ├─ 写入数据库 (ProgramDatabase) │
│ │ • 创建新Program记录 │
│ │ • 保存所有metrics │
│ │ • 更新archive │
│ │ │
│ └─ 选择父代 → 下一代 ────────────────────────► │
└─────────────────────────────────────────────────────────────┘
数据库 Schema (共享状态):
┌──────────────────────────────────────────────────────────┐
│ SQLite: evolution_db.sqlite │
│ ┌────────────────────────────────────────────────────┐ │
│ │ programs 表 │ │
│ │ ├─ id (gen_N) │ │
│ │ ├─ code │ │
│ │ ├─ generation (N) │ │
│ │ ├─ combined_score ◄── EvolutionRunner写入 │ │
│ │ ├─ public_metrics ◄── EvolutionRunner写入 │ │
│ │ ├─ text_feedback ◄── EvolutionRunner写入 │ │
│ │ ├─ correct ◄── EvolutionRunner写入 │ │
│ │ │ │ │
│ │ └─ metadata ◄── Agent可写入 (可选) │ │
│ │ { │ │
│ │ "agent_analysis": {...}, │ │
│ │ "custom_metrics": {...}, │ │
│ │ "evaluation_reasoning": "..." │ │
│ │ } │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ Agent可读取全部历史数据，但只能写入metadata字段 │
└──────────────────────────────────────────────────────────┘
```
---
## 🎯 Agent对外接口总结
### 必需接口 (保持兼容)
```python
# 1. 命令行参数接口
--program_path: str # 必需
--results_dir: str # 必需
# 2. 输出文件接口 (标准契约)
metrics.json: {
"combined_score": float, # 必需
"public": dict, # 必需
"private": dict, # 可选
"text_feedback": str # 可选 (use_text_feedback=True时)
}
correct.json: {
"correct": bool, # 必需
"error": str | null # 必需
}
```
### 扩展接口 (Agent特性)
```python
# 1. 数据库访问接口
--db_path: str # 可选，提供后Agent可访问历史数据
# 2. Agent模式配置
--agent_mode: str # static | adaptive | exploratory
--enable_dynamic_metrics: bool
--max_tool_calls: int
# 3. 额外输出文件
agent_reasoning.json: { # Agent的决策过程 (用于调试和分析)
"plan": [...],
"execution_log": [...],
"tool_costs": {...},
"total_cost": float
}
auxiliary_analysis.json # 详细的辅助分析 (已有)
visualizations/ # 可视化文件 (可选)
├─ packing_viz.png
├─ metrics_trend.png
└─ comparison.png
```
### Python API接口
```python
# 1. Agent类接口
class EvaluationAgent:
def __init__(
self,
config: AgentConfig,
db_path: Optional[str] = None
):
pass
def evaluate(
self,
program_path: str,
results_dir: str
) -> Tuple[Dict, bool, Optional[str]]:
"""
返回: (metrics, correct, error)
与 run_shinka_eval 完全兼容
"""
pass
# 2. 工具接口 (供Agent内部使用)
class Tool:
def execute(self, **kwargs) -> ToolResult:
pass
# 3. 数据库接口扩展
class ProgramDatabase:
# 新增方法供Agent使用
def update_program_metadata(
self,
program_id: str,
metadata: Dict
) -> bool:
pass
```
---
## 🚀 实现路线图
### Phase 1: 基础Agent框架 (2-3天)
```
✓ 1. 创建 EvaluationAgent 类骨架
✓ 2. 实现 Tool 基类和工具注册系统
✓ 3. 重构现有evaluation代码为工具
- RunProgramTool
- ValidateResultsTool
- ComputeMetricTool
✓ 4. 实现 static_mode (完全兼容现有行为)
✓ 5. 单元测试
```
### Phase 2: 数据库集成 (1-2天)
```
✓ 1. 创建 RestrictedDatabaseAccess 接口
✓ 2. 实现数据库查询工具
- QueryDatabaseTool
- CompareWithHistoryTool
✓ 3. 扩展 ProgramDatabase.update_program_metadata()
✓ 4. 集成测试
```
### Phase 3: Adaptive Mode (3-4天)
```
✓ 1. 实现 LLM planning 逻辑
✓ 2. Context gathering (历史数据分析)
✓ 3. 动态工具调用
✓ 4. 结果聚合和反馈生成
✓ 5. 端到端测试
```
### Phase 4: Dynamic Metrics (2-3天)
```
✓ 1. 实现 GenerateMetricCodeTool
✓ 2. SafeCodeExecutor 沙箱
✓ 3. 动态metric注册和验证
✓ 4. Exploratory mode 实现
✓ 5. 安全性测试
```
### Phase 5: 可视化和分析 (1-2天)
```
✓ 1. VisualizeTool
✓ 2. StatisticalAnalysisTool
✓ 3. Agent推理过程可视化
```
### Phase 6: 生产就绪 (2-3天)
```
✓ 1. 性能优化
✓ 2. 错误处理和恢复
✓ 3. 日志和监控
✓ 4. 文档完善
✓ 5. 集成到EvolutionRunner
```
**总计: 11-17天开发时间**
---
## 📝 使用示例
### 示例1: 静态模式 (完全兼容)
```python
from shinka.evaluation import EvaluationAgent, AgentConfig
config = AgentConfig(mode="static")
agent = EvaluationAgent(config)
metrics, correct, error = agent.evaluate(
program_path="gen_42/main.py",
results_dir="gen_42/results"
)
# 输出与现有evaluate_with_auxiliary.py完全相同
```
### 示例2: 自适应模式 (智能评估)
```python
config = AgentConfig(
mode="adaptive",
enable_database_read=True,
llm_model="native-gemini-2.5-pro"
)
agent = EvaluationAgent(
config=config,
db_path="evolution_db.sqlite"
)
metrics, correct, error = agent.evaluate(
program_path="gen_100/main.py",
results_dir="gen_100/results"
)
# Agent会:
# 1. 查询前99代的最佳程序
# 2. 分析当前程序相对历史的改进
# 3. 智能选择最相关的auxiliary metrics
# 4. 生成个性化的反馈
```
### 示例3: 探索模式 (自动发现新指标)
```python
config = AgentConfig(
mode="exploratory",
enable_dynamic_metrics=True,
enable_database_read=True
)
agent = EvaluationAgent(config, db_path="evolution_db.sqlite")
metrics, correct, error = agent.evaluate(
program_path="gen_150/main.py",
results_dir="gen_150/results"
)
# Agent可能会:
# 1. 发现现有metrics都在plateau
# 2. 生成新的metric来检测"corner circle size pattern"
# 3. 验证新metric与主分数的相关性
# 4. 如果有效，注册到全局registry供后续使用
```
---
## 💡 优势和影响
### 对进化系统的改进
1. **更智能的评估**: Agent可以根据进化阶段调整评估策略
2. **自适应反馈**: 针对当前代的具体问题提供针对性建议
3. **自动发现**: 探索新的评估维度，突破人工设计的局限
4. **可解释性**: Agent的推理过程可追溯，方便调试
### 保持兼容性
1. **接口兼容**: 完全遵守现有的输入输出契约
2. **渐进式采用**: 可以从static模式开始，逐步启用高级功能
3. **性能可控**: 可以配置Agent的计算预算
4. **无破坏性**: 不影响现有实验的可复现性
---
## 🎓 总结
### Agent的核心对外接口
```
输入接口:
├─ 必需: program_path, results_dir
└─ 可选: db_path, agent_config
输出接口:
├─ 必需: metrics.json, correct.json
└─ 可选: agent_reasoning.json, visualizations/
数据库接口:
├─ READ: 可读取所有历史程序数据
└─ WRITE: 仅可写入program.metadata字段
工具接口:
├─ Ground Truth: 运行和验证程序
├─ Auxiliary Metrics: 预定义分析指标
├─ Database: 查询历史数据
├─ Dynamic: 生成新指标
└─ Visualization: 分析和可视化
```
### 关键设计原则
1. **接口兼容优先**: Agent必须能完全替代现有evaluation脚本
2. **安全性**: 代码执行沙箱、数据库权限控制
3. **可扩展性**: 工具系统支持持续添加新能力
4. **可观测性**: Agent的决策过程可追溯和调试
5. **性能可控**: 通过配置平衡智能程度和计算成本
### 实现可行性
✅ **技术可行**: 所有组件都有成熟的实现方案
✅ **架构友好**: 与现有系统无缝集成
✅ **渐进式**: 可以分阶段实现和部署
✅ **向后兼容**: 不破坏现有实验
---
**这个Agent将evaluation从固定流程提升为智能决策过程，同时保持与现有系统的完美兼容！** 🚀
|