用途
ag2-eval-comparison 用于比较 AG2 智能体、模型或提示词，帮助判断哪一个更好。它覆盖两类评估：一是把 N 个模型、提示词或配置放到排行榜上排名（run_variants）；二是对两个候选做一对一比较（run_pairwise），由 LLM 评判或由人评判。若只需运行和评分单个智能体（评分器、CI、持久化），应使用 ag2-evaluation。
安装
pip install "ag2[openai,tracing]"
这是必需步骤，应在交付代码前运行。若无法运行命令，需给出确切的 pip install 命令。
主要能力
排行榜：run_variants
Variants 是一个冻结的 dataclass，保存命名 Agent 实例的映射，以及一个 axis 标签，用来命名被变化的对象。构建每个 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"）。分数相同则共享同一排名；三方并列通常说明评估区分度不足，应加大难度，或用评判器给质量打分。
一对一（LLM）：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 配对两个已有 trace 来源）：
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）；小样本 n 会跨越 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（不要设置 swap=False），以获得无偏判定。
深入阅读
- website/docs/user-guide/evaluation/ —— variants（Variants 映射 + axis）、pairwise（比较器、胜率、盲测标注）
- ag2-evaluation —— 单智能体运行/评分、评分器、CI、持久化