企业官网建设流程全解析

deepagents-evals trials 如何重复运行同一模型并合并报告判断稳定性？

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

当你改完 prompt、工具描述或 SDK 之后，想知道模型分数变化是真实信号还是单次运行的波动时，libs/evals里的deepagents-evals trials就是对应的操作路径：用同一模型和同一配置重复运行 eval 套件 N 次，自动合并各次报告，再根据trials_summary.json里的标准差判断波动大小。文档明确区分了两种工作流：比较多个模型用evals.yml（trials=1、models 多个），而判断单个模型在同一配置下是否稳定用 trials（trials=N、models 恰好一个）。适用前提是你能从libs/evals目录调用deepagents-evals控制台脚本，并已配置 LangSmith 追踪和对应模型提供商的 API key。

准备条件

在libs/evals/下同步依赖并设置环境变量。该包要求 Python>=3.12,<3.14（见 pyproject.toml）：

cd libs/evals uv sync --all-groups export LANGSMITH_TRACING=true export LANGSMITH_API_KEY=... export ANTHROPIC_API_KEY=... # 或与你 --model 匹配的提供商 key

eval 套件的conftest.py在缺少 LangSmith 追踪或未提供--model时会在收集阶段前直接中止，所以这两项不是可选项。提供商 key 必须与--model的提供商一致（如openai:模型配OPENAI_API_KEY）。

运行前可以先用list子命令确认可用的模型、类别和 eval，无需翻源码：

deepagents-evals list categories deepagents-evals list tiers deepagents-evals list models --group set0 deepagents-evals list evals --category memory

类别清单定义在 categories.json，tier 固定为baseline（回归门槛）和hillclimb（进度跟踪）。

重复运行同一模型

最短主路径，以openai:gpt-5.5为例，在memory类别上跑 3 次 trial：

deepagents-evals trials --model openai:gpt-5.5 --trials 3 \ --eval-category memory --out-dir trial_runs/memory

行为要点（来自 run_trials.py 与 cli.py）：

• --trials取值 1–50（本地上限 50；GitHub Actions 的evals_trials.yml工作流上限是 20）。
• 同一次 CLI 调用内 trial顺序执行：LangSmith 实验的进程内并发创建和提供商限流使并行不安全。每个 trial 是独立的pytest tests/evals子进程，并在 LangSmith 中创建各自的 experiment。
• 常用可选参数：--eval-category（可重复）、--eval-tier（可重复，baseline | hillclimb）、--openai-reasoning-effort（仅openai:模型）、--openrouter-provider（需openrouter:模型，默认严格不允许 fallback，--openrouter-allow-fallbacks显式放宽）、--repl quickjs。
• --model缺省时回退到环境变量DEEPAGENTS_EVALS_MODEL；显式 flag 优先。
• 报告默认写入trial_runs/，可用--out-dir或--summary-out指定位置。
• 大多数子命令支持--dry-run（只打印将要执行的命令）和--json（机器可读 stdout），适合自动化前预览。

如果某次 trial 的 pytest 退出码非零，脚本会打 warning 并把该报告标记后继续聚合；如果某个 trial 完全没产出报告文件，该 trial 从聚合中剔除并 warning。

等价 Makefile 路径

make evals-trials是 CI 在用的等价形式，MODEL和TRIALS两个变量缺一即报错退出，额外 flag 通过TRIAL_ARGS透传（见 Makefile）：

make evals-trials MODEL=openai:gpt-5.5 TRIALS=3 \ TRIAL_ARGS="--eval-category memory"

CI 并行分支（可选）

本地跑不完时，CI 的做法是把每个 trial 拆成独立的 GHA job（各自 6 小时预算），各 job 上传自己的报告 artifact，最后用aggregate-trialsjob 以--aggregate-only模式合并。合并逻辑与下面的aggregate子命令相同。

合并已分离的报告

一次trials调用结束时会自动写出聚合摘要，无需手动合并。当你需要把来自不同 CI job / 不同 artifact 的报告合并成一个摘要时，用aggregate子命令（内部即run_trials.py --aggregate-only，递归扫描目录下所有evals_report.json和evals_report_trial_*.json）：

deepagents-evals aggregate trial_runs/memory # 摘要写到自定义路径 deepagents-evals aggregate ./downloaded-artifacts --summary-out summary.json

合并时的检查规则（对判断稳定性有直接影响）：

• 各报告的model不一致会 warning，摘要取第一个报告的值；sdk_version不一致同理。文档明确提示：混合模型或 SDK 版本的结果不应用于回归结论。
• 某 metric 为null（例如没有测试通过时的solve_rate）会静默从该 metric 的统计中剔除，n反映实际贡献的 trial 数而非总 trial 数。
• 非null但非数值的值会带 warning 剔除，用于暴露上游 reporter 结构变化。

读取 trials_summary.json 并判断稳定性

输出是--out-dir（或 aggregate 目录）下的trials_summary.json，文档示例的结构如下（数值为文档示例，不是固定预期）：

{ "n_trials": 3, "model": "openai:gpt-5.5", "sdk_version": "0.5.7", "metrics": { "correctness": {"n": 3, "mean": 0.84, "median": 0.85, "stdev": 0.02, "min": 0.82, "max": 0.86}, "solve_rate": {"n": 3, "mean": 0.71, "median": 0.70, "stdev": 0.03, "min": 0.68, "max": 0.74}, "step_ratio": {"n": 3, "mean": 1.10, "median": 1.10, "stdev": 0.01, "min": 1.09, "max": 1.11}, "tool_call_ratio": {"n": 3, "mean": 1.05, "median": 1.05, "stdev": 0.01, "min": 1.04, "max": 1.06}, "median_duration_s": {"n": 3, "mean": 4.30, "median": 4.31, "stdev": 0.05, "min": 4.25, "max": 4.34} }, "counts": { "passed": {"n": 3, "mean": 17.0, "median": 17, "stdev": 0.0, "min": 17, "max": 17}, "failed": {"n": 3, "mean": 3.0, "median": 3, "stdev": 0.0, "min": 3, "max": 3}, "skipped": {"n": 3, "mean": 0.0, "median": 0, "stdev": 0.0, "min": 0, "max": 0}, "total": {"n": 3, "mean": 20.0, "median": 20, "stdev": 0.0, "min": 20, "max": 20} }, "category_scores": { "memory": {"n": 3, "mean": 0.83, "median": 0.83, "stdev": 0.0, "min": 0.83, "max": 0.83} }, "trials": [ { "trial_index": 1, "passed": 17, "failed": 3, "skipped": 0, "total": 20, "correctness": 0.85, "category_scores": {"memory": 0.83}, "experiment_urls": ["https://smith.langchain.com/..."], "pytest_returncode": 0 } ] }

判断稳定性时看各 metric 的stdev：

• stdev ≪ 候选变化量→ 变化是信号，可以下结论。
• stdev ≈ 候选变化量→ 增加 trial 次数，或把该结果当噪声。
• 文档给出的量级参考（示例数值）：170 个测试的套件中 2 个任务通过数的摆动对应 Δcorrectness ≈ 0.012，与单次 trial 的典型 stdev 相当——这个量级的单次运行差异不应在没有 trial 佐证的情况下报告为模型差异。
• stdev在 n < 2 时为null（样本标准差至少需要 2 个样本），所以只跑 1 次 trial 拿不到波动信息。

失败判定不要用 pytest_returncode

reporter 会把 pytest 的 session 退出状态重写为0（即使有测试失败），因此每个 trial 的pytest_returncode不是可靠的失败信号。trials/aggregate的退出码来自摘要中的counts.failed.mean：大于 0 时进程退出码为 1。完整退出码表（见 AGENTS.md）：

自动化的判定入口应读trials_summary.json的counts.failed.mean，而不是解析人类可读输出或依赖pytest_returncode。

可选：只重试失败用例

一轮 trial 结束后，可以只针对上一轮失败的测试节点再跑一次，用于甄别偶发失败（flake）：

deepagents-evals trials --model openai:gpt-5.5 --trials 1 \ --retry-failed trial_runs/memory/trials_summary.json

--retry-failed接受trials_summary.json文件路径或包含逐 trial 报告的目录；它读取各报告中的failures[].test_name，跨 trial 去重后把节点 ID 作为 pytest 参数转发，每个失败用例最多重试一次。找不到可重试节点时退出码为 3。

边界与限制

• 本地单次调用最多 50 个 trial，CI 工作流最多 20 个；5 trial 顺序跑在慢模型上可能超过单 job 预算，所以 CI 才需要拆 job + aggregate。
• 重复运行必须保持模型、SDK 版本和配置完全一致，摘要对 model/sdk_version不一致只会 warning 而不阻止聚合——合并前确认来源属于同一轮对比。
• 单个 rollout 只是诊断，不是稳定对比；在拿到多 trial 摘要之前，不要把单次correctness变化当作模型差异报告出去。

参考路径

• AGENTS.md：deepagents-evals子命令、退出码、trials_summary.jsonschema 与字段说明
• CONTRIBUTING.md：Multi-trial runs 一节（本地/CI 跑法、spread 解读）
• scripts/run_trials.py：trial 循环、聚合与--aggregate-only实现
• deepagents_evals/cli.py：trials/aggregate/--retry-failed的 CLI 参数与退出码映射

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents