ag2-eval-comparison

评估 — 比较构建版本（变体与成对比较）

适用场景

• 在排行榜上为 N 个模型 / 提示词 / 配置排名 → run_variants
• 比较两个选项，判断哪个更好 → 使用 pairwise_judge（大模型）或 human_pairwise（人工）搭配 run_pairwise

如需运行并评估单个 Agent（评分器、CI、持久化），请使用 ag2-evaluation。

安装

pip install "ag2[openai,tracing]"

必需。在交付代码前运行此安装命令。如果无法运行命令，请注明准确的 pip install 命令。

排行榜 — run_variants

Variants 是一个冻结的数据类，包含命名的 Agent 实例映射，以及用于说明变化维度的 axis 标签。构建每个 Agent 时，只改变一项（配置、提示词、工具、中间件等），其余保持不变，然后为每个 Agent 评分并排名：

from ag2 import Agent
from ag2.config import OpenAIConfig, GeminiConfig
from ag2.eval import Variants, run_variants
from ag2.eval.scorers import agent_judge

board = await run_variants(
    suite,
    variants=Variants(
        {
            "gpt-4o": Agent("a", prompt="Answer helpfully.", config=OpenAIConfig("gpt-4o")),
            "flash":  Agent("a", prompt="Answer helpfully.", config=GeminiConfig("gemini-3-flash-preview")),
        },
        axis="config",                  # label for what was varied (used in summary)
    ),
    scorers=[agent_judge(OpenAIConfig("gpt-4o"), criterion="Helpful and accurate.", key="quality")],
    store_dir="runs",
    repeats=5,                          # optional: N runs per variant for stability
)
print(board.summary("quality"))         # ranked leaderboard
board.best("quality")                   # winning variant name (None if tied)
board.leaderboard("quality")            # list[LeaderboardRow] — variant, score, n, rank
board.results["gpt-4o"]                 # each variant's full RunResult

你可以随意改变各 Agent 的内容，只需设置 axis 为相应标签（例如，"config"、"prompt"、"tools"）。同分者排名相同；三方并列通常意味着评估的区分度不足——可以提高难度，或使用评审器为质量评分。

正面对比（大模型）— run_pairwise + pairwise_judge

比较器会针对每项任务选出胜者。pairwise_judge 会以两种顺序展示这对选项，并且只有结果一致时才计为胜出，否则判为平局（抵消顺序偏差）：

from ag2.eval import run_pairwise
from ag2.eval.scorers import pairwise_judge

result = await run_pairwise(
    suite, variant_a=agent_v1, variant_b=agent_v2,
    comparators=[pairwise_judge(OpenAIConfig("gpt-4o"), criterion="more helpful answer", key="quality")],
    store_dir="runs",
)
wr = result.win_rate("quality")         # B's win-rate
print(wr.rate, wr.ci, wr.wins, wr.losses, wr.ties)   # ties count 0.5; ci is a Wilson 95% interval
print(result.flips("quality"))          # int — count of cases where the two orders disagreed

variant_a / variant_b 是 Agent 实例；comparators= 接受复数形式的可迭代对象。result.agreement("quality", "human") 会返回两个比较器键之间的 Agreement（.rate、.cohen_kappa 等）。评审模型应与变体使用的模型不同。

正面对比（人工）— human_pairwise

单位相同，由人工做出判断。选项会隐藏身份并随机排列顺序；默认行为是将其打印出来，并读取 1 / 2 / tie。传入自定义的异步 ask(task, response_1, response_2)，即可从 UI 收集投票（返回 "1"、"2" 或 "tie"）：

from ag2.eval.scorers import human_pairwise

async def ask(task, response_1, response_2) -> str:
    return await my_ui.compare(task.inputs["input"], response_1, response_2)   # "1" / "2" / "tie"

result = await run_pairwise(suite, variant_a=agent_v1, variant_b=agent_v2,
                            comparators=[human_pairwise(key="quality", ask=ask)], store_dir="runs")

大规模评估时，可以导出隐藏身份的清单，在任意工具中标注，再导入。evaluate_pairwise 是 run_pairwise 的仅评分版本（根据 task_id 配对两个现有的追踪来源）：

from ag2.eval import evaluate_pairwise, DirectoryTraceSource
from ag2.eval.scorers import export_pairwise_cases, human_labels

a, b = DirectoryTraceSource("runs/champion"), DirectoryTraceSource("runs/challenger")
await export_pairwise_cases(a, b, criteria=["more helpful"], out="labels.jsonl", suite=suite)   # blinded JSONL
# a person adds  "preferred": "1" | "2" | "tie"  per line, then:
result = await evaluate_pairwise(a, b, suite=suite, store_dir="runs",
                                 comparators=[human_labels("labels.jsonl", criterion="more helpful", key="helpful")])

清单会隐藏各模型的身份；其 first_variant 字段会在 human_labels 中显示身份。

常见问题

• 评审器 == 某个变体使用的模型 — 会产生自我偏好偏差；请使用不同的评审模型。
• 基于少量配对计算未经调整的胜率 — 应报告 wr.ci（Wilson 置信区间）；样本量较小时，置信区间可能横跨 50%。
• 传入工厂函数而非 Agent — run_variants（variants=Variants({name: Agent(...)})）和 run_pairwise（variant_a= / variant_b=）接受的是 Agent 实例，而不是构建函数。使用 model_config=（dict[task_id, ModelConfig]）为每项任务更换模型，而不是重新构建 Agent。保留 pairwise_judge 的默认交换设置（不要设置 swap=False），以确保判定不受偏差影响。

深入了解

• website/docs/user-guide/evaluation/ — variants（Variants 映射与 axis）、pairwise（比较器、胜率、隐藏身份标注）
• ag2-evaluation — 单个 Agent 的运行 / 评分、评分器、CI、持久化