黑盒优化示例¶

黑盒优化指目标函数无法解析表达，只能通过外部函数评估的问题。OptAgent 通过 external_call 将黑盒函数集成到 DAG IR 中。

TSP — 禁忌搜索¶

使用禁忌搜索求解 4 城市旅行商问题，距离矩阵通过黑盒函数评估。

from optagent import HeuristicStrategy, ModelBuilder, Orchestrator, OrchestratorConfig, OrchestratorSolver, PhaseConfig

DIST = [
    [0, 4, 7, 3],
    [4, 0, 2, 6],
    [7, 2, 0, 5],
    [3, 6, 5, 0],
]

def route_cost(order: list[int]) -> int:
    tour = order + [order[0]]
    return sum(DIST[tour[index]][tour[index + 1]] for index in range(len(order)))

builder = ModelBuilder(metadata={"case": "tsp_blackbox_small"})
route = builder.sequence_var(size=4, default=[3, 2, 1, 0], name="route")
builder.minimize(builder.external_call(route_cost, route, name="route_cost"), name="tour_length")
program = builder.freeze()

result = Orchestrator().run(
    program,
    config=OrchestratorConfig(
        total_budget_iterations=60,
        phases=[
            PhaseConfig(
                name="heuristic_tsp_blackbox",
                solver=OrchestratorSolver.HEURISTIC,
                budget_iterations=60,
                strategy=HeuristicStrategy.TABU,
            )
        ],
    ),
)

运行方式：

PYTHONPATH=src python examples/blackbox/tsp_blackbox_small.py

TSP — 进化算法¶

使用进化算法求解同样的 TSP 问题，对比不同策略的效果。

from optagent import (
    EvolutionaryConfig, HeuristicOrchestrationConfig,
    ModelBuilder, Orchestrator, OrchestratorConfig, OrchestratorSolver, PhaseConfig,
)

DIST = [
    [0, 4, 7, 3],
    [4, 0, 2, 6],
    [7, 2, 0, 5],
    [3, 6, 5, 0],
]

def route_cost(order: list[int]) -> int:
    tour = order + [order[0]]
    return sum(DIST[tour[index]][tour[index + 1]] for index in range(len(order)))

builder = ModelBuilder(metadata={"case": "tsp_evolutionary_small"})
route = builder.sequence_var(size=4, default=[3, 2, 1, 0], name="route")
builder.minimize(builder.external_call(route_cost, route, name="route_cost"), name="tour_length")
program = builder.freeze()

result = Orchestrator().run(
    program,
    config=OrchestratorConfig(
        total_budget_iterations=24,
        phases=[
            PhaseConfig(
                name="evolutionary_tsp_blackbox",
                solver=OrchestratorSolver.HEURISTIC,
                heuristic_plan=HeuristicOrchestrationConfig(
                    phases=[],
                    evolutionary_plan=EvolutionaryConfig(
                        population_size=6,
                        elite_size=2,
                        generation_limit=4,
                    ),
                ),
            )
        ],
    ),
)

运行方式：

PYTHONPATH=src python examples/blackbox/tsp_evolutionary_small.py

路由优化 — 启发式¶

使用字典定义距离的路由优化问题。

from optagent import HeuristicStrategy, ModelBuilder, Orchestrator, OrchestratorConfig, OrchestratorSolver, PhaseConfig

def route_cost(order: list[int]) -> int:
    distances = {
        (0, 1): 4, (0, 2): 7, (0, 3): 3,
        (1, 0): 4, (1, 2): 2, (1, 3): 6,
        (2, 0): 7, (2, 1): 2, (2, 3): 5,
        (3, 0): 3, (3, 1): 6, (3, 2): 5,
    }
    return sum(distances[(order[index - 1], order[index])] for index in range(1, len(order)))

builder = ModelBuilder(metadata={"case": "blackbox_route_heuristic"})
route = builder.sequence_var(size=4, default=[3, 2, 1, 0], name="route")
builder.minimize(builder.external_call(route_cost, route, name="route_cost"), name="route_obj")
program = builder.freeze()

result = Orchestrator().run(
    program,
    config=OrchestratorConfig(
        total_budget_iterations=40,
        phases=[
            PhaseConfig(
                name="heuristic_blackbox",
                solver=OrchestratorSolver.HEURISTIC,
                budget_iterations=40,
                strategy=HeuristicStrategy.TABU,
            )
        ],
    ),
)

运行方式：

PYTHONPATH=src python examples/blackbox/routing_heuristic.py

使用预设求解黑盒问题¶

from optagent import BuiltInStrategyPreset, ModelBuilder, Orchestrator

builder = ModelBuilder(metadata={"case": "routing_blackbox_preset"})
route = builder.sequence_var(size=4, default=[3, 2, 1, 0], name="route")
builder.minimize(builder.external_call(route_cost, route, name="route_cost"), name="tour_length")
program = builder.freeze()

# 使用进化预设
result = Orchestrator().run(program, preset=BuiltInStrategyPreset.ROUTING_EVOLUTIONARY)

# 或自动选择预设
result = Orchestrator().run(program)

运行方式：

PYTHONPATH=src python examples/presets/routing_blackbox_preset.py
PYTHONPATH=src python examples/presets/routing_blackbox_auto_preset.py

黑盒优化要点

external_call：将任意 Python 函数注册为 DAG IR 中的评估节点
sequence_var：定义排列型决策变量（如路径顺序）
黑盒问题只能使用启发式求解器，无法使用精确求解器
进化算法适合多峰、噪声大的黑盒函数