Nexent 统一 Benchmark Runner:run_benchmark.py 全参数指南与源码级原理解析

原创2026-10-12 12:02:581,434 阅读
文章标签:AI AgentAI 应用后端前端大模型RAG

Nexent 统一 Benchmark Runner:run_benchmark.py 全参数指南与源码级原理解析

导读

本文是 Nexent 开源仓库中 sdk/benchmark/generic 目录下统一 Benchmark 运行器 run_benchmark.py 的完整使用与原理指南。它以 Langfuse 数据集为输入,驱动真实 Nexent SDK Agent 执行推理、评分与重新评分,覆盖 Agent 配置加载、CLI 覆盖、上下文预算控制、Web 检索观测、Exa 缓存回放、GAIA 最终答案诊断等完整实验流程。读完本文,你将能够:从 YAML 或纯 CLI 参数发起不可变 Benchmark 实验,正确选择评分器与上下文处理策略,复用已有 trace 进行秒级重新评分,并通过 manifest 与完整性检查确保实验可归因、可复现。

该文档原位于 sdk/benchmark/generic/RUN_BENCHMARK.zh-CN.md,其对应的源码实现为 run_benchmark.py,本文以文档为主体,结合源码逐项展开。

一、工具定位:为什么要统一 Benchmark 入口

run_benchmark.py 是 Nexent 通用 Benchmark 框架的统一运行器,替代了此前的 run_experiment.py 与 re_evaluate.py 两个脚本。它解决的核心问题是:Agent 版本迭代时,实验者需要在"运行新实验(调用 LLM)"与"重新评分已有结果(不调用 LLM)"之间反复切换,且不同脚本对 YAML 配置的支持、数据集上传能力各不相同。

从源码 run_benchmark.py 的模块 docstring 可以看到,它支持的能力包括:

  • 从 YAML 配置文件加载 Agent 参数(配置文件由 export_agent_config.py 从数据库导出);
  • CLI 参数覆盖 YAML 配置;
  • 运行新实验(调用 LLM);
  • 重新评分已有结果(不调用 LLM);
  • 上传数据集 + 运行一体化;
  • 记录 Web Search → Fetch 证据与工具成本统计;
  • Exa 结果 record/replay;
  • 只对已有 run 的失败题做小范围重复实验。

整个框架的执行链路不依赖 Nexent 后端与前端,只依赖 Langfuse(保存数据集、trace、评分与 dataset run)与本地产物目录(保存 manifest、evidence 和对比报告),具体架构说明见 sdk/benchmark/generic/README.zh-CN.md。

二、命令行参数全表

run_benchmark.py 的完整参数定义见 run_benchmark.py 的 main() 函数,下面按文档分类逐一说明。

2.1 Agent 配置

参数 必填 说明
--agent-config 否 Agent YAML 配置文件路径(由 export_agent_config.py 生成)

加载时调用 load_agent_config()(源码),使用 yaml.safe_load 读取后,会经过 resolve_env_references() 解析严格的 {"$env": "NAME"} 环境引用——即 YAML 中敏感字段(如 API key)可以写成环境变量引用,导出工具负责在导出时把敏感值外部化,详见 common/secret_refs.py。

2.2 数据集

参数 必填 说明
--dataset ✅ Langfuse 数据集名称
--upload 否 JSONL 文件路径(上传后运行)
--input-key 否 JSONL 中问题字段的 key(默认 question)
--output-key 否 JSONL 中答案字段的 key(默认 answer)

--upload 对应的 upload_jsonl()(源码)逐行解析 JSONL,把 input_key 之外的字段原样并入 input 字典,expected_output 只在存在 output_key 时写入;遇到非法 JSON 行会打印 WARNING 并跳过,不中断整体上传。

2.3 评分器

参数 必填 说明
--evaluators 否 评分器名称列表(默认 exact_match)
--list-evaluators 否 列出所有可用评分器并退出

评分器通过 evaluators/init.py 的 EVALUATOR_REGISTRY 注册表按名称解析,resolve_evaluators() 遇到未知名称会抛出包含可用列表的 ValueError。

可用评分器:

评分器 说明 适用场景
numeric_answer 提取数字并比较 数学题、计算题
exact_match SQuAD 标准化后精确匹配 短答案 QA
em exact_match 的别名 同上
f1 Token 级 F1 分数 开放式 QA
keyword_match 关键词命中率 需要包含特定关键词的回答
gaia_exact_match GAIA 标准化最终答案精确匹配 GAIA 正式准确率
gaia_final_answer 最终答案格式、候选与提交损失诊断 放在 gaia_exact_match 之后

各评分器的判定逻辑可以从源码进一步印证:

  • numeric_answer(numeric_answer.py)优先匹配 GSM8K 风格的 #### <number> 模式,其次匹配 "the answer is / answer: / so" 等模式,最后回退到取全文最后一个数字;比较时去掉千位分隔逗号,容差 1e-6;
  • exact_match(exact_match.py)执行 SQuAD 风格标准化:小写、去标点、去冠词(a/an/the)、折叠空白;
  • em / f1(em_f1.py)在 SQuAD 标准化基础上额外做复数归一化,F1 为 Token 级 precision/recall 调和平均;
  • keyword_match(keyword_match.py)返回命中关键词占全部关键词的比例(0~1 之间的小数);
  • gaia_exact_match(gaia_exact_match.py)是三策略比较器:优先数字(剥离货币符号、单位、千位逗号,支持分数与 1e-9 相对容差),其次逗号分隔列表(逐元素、保序),最后是归一化字符串比较。它比通用 SQuAD 匹配更适合 GAIA,因为 SQuAD 去标点会破坏 "89706.00" 这类数字答案;
  • gaia_final_answer(gaia_final_answer.py)是纯诊断评分器,不参与正式准确率,输出四个 0/1 诊断分数(见下文 3.7 节)。

2.4 Agent 执行参数(覆盖 YAML)

参数 说明
--max-steps 最大执行步数
--temperature LLM 温度;标准导出 YAML 不含该字段,不传时通常使用 0.1
--language 提示语言(en / zh)
--duty-prompt 角色描述 prompt
--constraint-prompt 约束条件 prompt
--few-shots-prompt Few-shot 示例 prompt
--system-prompt-file 自定义系统 prompt 文件(跳过模板引擎)
--tenant-id builtin skill tools 的运行范围;默认依次取 CLI、YAML agent_info.tenant_id、tenant_id
--skills-path builtin skill tools 使用的本地 Skill 根目录;未传时读取 SKILLS_PATH

从 run_benchmark.py 的合并逻辑可以看到优先级链:CLI 参数 → YAML → 默认值。例如 max_steps 取 args.max_steps or agent_cfg.get("max_steps", 10),temperature 取 CLI 值,否则取 YAML 的 temperature,否则 0.1。

--language 会选择和生产相同的公共 Prompt 模板与 ContextItem 装配路径。Benchmark 与生产使用相同的 Nexent 固定身份描述:

zh -> Nexent 是一个开源智能体平台,基于 MCP 工具生态系统,提供灵活的多模态问答、检索、数据分析、处理等能力。
en -> Nexent is an open-source agent platform built on the MCP tool ecosystem, providing flexible multimodal Q&A, retrieval, data analysis, and processing capabilities.

注意:--language 不会翻译 YAML 中的 duty_prompt、constraint_prompt 或 few_shots_prompt;这些 Agent 自定义字段必须来自待测生产版本。切换语言后应重新生成对应 snapshot,不能把 en snapshot 用于 zh run。

2.5 上下文管理

PR #3475 之后,ContextManager/ContextItems assembly 始终启用。配置控制的是 processing_mode,而不是选择 Legacy/Managed runtime。

YAML 配置示例:

agent_config:
  enable_context_manager: true  # 或 false

CLI 参数:

参数 说明
--context-processing-mode passthrough 同一 ContextItems assembly,不执行 adaptive compaction
--context-processing-mode adaptive_compact 启用 adaptive compaction
--enable-context-manager 兼容别名,映射为 adaptive_compact
--disable-context-manager 兼容别名,映射为 passthrough
--token-threshold 压缩阈值;Benchmark 默认 32,768
--soft-input-budget 显式 soft input budget;默认跟随 threshold,即 32,768
--hard-input-budget 显式 hard input budget;默认是 threshold 的 1.1 倍,即 36,044
--budget-profile 预算来源/实验意图分类,只写入 manifest,不改变预算计算
--context-window-tokens 记录到 ContextManager 的 context-window 值;默认 32,768,当前不会执行完整生产容量解析

这三个默认值与源码常量一一对应(run_benchmark.py):

DEFAULT_CONTEXT_WINDOW_TOKENS = 32_768
DEFAULT_TOKEN_THRESHOLD = DEFAULT_CONTEXT_WINDOW_TOKENS
DEFAULT_SOFT_INPUT_BUDGET_TOKENS = DEFAULT_TOKEN_THRESHOLD
DEFAULT_HARD_INPUT_BUDGET_TOKENS = int(DEFAULT_TOKEN_THRESHOLD * 1.1)

预算解析规则(对应 resolve_context_budget_defaults()):

  • 显式传入 --soft-input-budget / --hard-input-budget 时,ContextManager 直接使用这两个值;
  • 未显式传入时,Benchmark 使用 Nexent 的 32K legacy fallback:threshold/soft 为 32,768,hard 为 int(32768 * 1.1),即 36,044;显式修改 threshold 时,soft/hard 继续按 threshold 和 threshold * 1.1 派生;
  • --context-window-tokens 当前不会根据模型的 max_input_tokens、输出预留和 uncertainty reserve 自动推导 soft/hard,因此已经显式传入预算时通常不需要再传它;
  • 默认 hard 是 legacy threshold guard,并不是根据 provider 容量计算的安全输入上限;正式实验仍应根据模型容量显式传入 soft/hard;
  • P(passthrough)仍执行 hard-budget 防护;超过 hard 后会报错,而不是无限制调用模型;
  • C(adaptive_compact)压缩后仍超过 hard 时会报 Context input remains over the model hard budget after compaction。

此外,run_benchmark.py 会对非法组合做启动前校验:--soft-input-budget 超过 --hard-input-budget 直接报错;--item-limit 与 --item-id 互斥;--keep-recent-pairs、--max-observation-length 已被统一 ContextItems runtime 移除,传入会报错。--keep-recent-steps 则保留(SDK 默认保留 4 个最近 action step)。

run_benchmark.py 可记录以下 profile:

profile 含义
legacy_threshold 仅使用旧 token_threshold 及其 1.1 倍 hard 派生
production_like 调用方已按生产容量规则计算并显式传入预算
synthetic_trigger 人为降低 soft 以提高压缩触发率,同时把 hard 保持在可安全运行的容量内
synthetic_stress 人为收紧 soft/hard,用于观察压缩极限和 hard-budget 失败,不作为正常准确率对照

profile 是归因标签,不是容量解析器。若直接调用 run_benchmark.py 且显式预算但不传 profile,manifest 会记录 explicit_unclassified(该默认逻辑见 run_benchmark.py)。

逻辑流程:

  1. 从 YAML 读取旧 enable_context_manager,映射为 policy;
  2. --context-processing-mode 优先覆盖 YAML;
  3. 创建带 PolicyLayers 的 ContextManagerConfig(run_benchmark.py);
  4. P/C 始终使用 context_runtime=context_items。

2.6 执行控制

参数 说明
--max-concurrency 最大并行数(默认 1)
--item-id 精确选择一个 DatasetItem ID;可重复传入
--item-limit 只运行数据集前 N 项(确定性 smoke test 用)
--exa-cache-mode off、record 或严格 replay
--exa-cache-path record/replay 使用的 JSON 文件
--run-name 自定义运行名称
--dry-run 仅上传数据集,不运行实验

--item-id 的解析逻辑见 select_dataset_items():拒绝重复 ID、拒绝与 --item-limit 组合,请求的 ID 未找到时报错列出缺失项。Exa 缓存相关参数还有启动前约束:--exa-cache-mode 非 off 时 --exa-cache-path 必填,反之 --exa-cache-path 必须在 record/replay 下使用(run_benchmark.py)。

Web evidence、Exa replay、失败题重复与 GAIA 最终答案诊断的完整使用方法见 sdk/benchmark/generic/integrations/langfuse/WEB_BENCHMARK_OPTIMIZATIONS.zh-CN.md。

2.7 重新评分模式

参数 说明
--rescore 启用重新评分模式(不调用 LLM)
--existing-run 要重新评分的已有运行名称

重新评分的实现见 rescore_experiment():从已有 dataset run 的 dataset_run_items 中取每个 item 对应的 trace,读取其 output 原样复用,再对新评分器逐条打分并链接到新的 run。新的 run name 默认是 {existing_run}-rescore-{evaluator列表}。由于完全不调用 LLM,整个过程是秒级完成的。注意 --rescore 模式下,--existing-run 是必填参数,缺失时 parser.error() 直接退出。

三、使用示例:八大实战场景

以下命令均假定已激活环境:

source backend/.venv/bin/activate

场景 1:使用 Agent 配置运行实验

python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --evaluators numeric_answer \
  --run-name gsm8k-math-assistant-zh

configs/agent_7.yaml 这类配置由 export_agent_config.py 从数据库导出,仓库自带示例见 configs/gsm8k_solver_assistant.yaml(数学解答助手,Agent ID 7)与 configs/gaia_solver.yaml(GAIA 解题助手,Agent ID 8)。配置文件的顶层结构为:agent_info(展示名、描述、问候语、示例问题)、agent_config(max_steps、enable_context_manager、prompt_template_id、version_no、verification_config)、prompts(duty/constraint/few_shots)、tools、sub_agents、skills。

场景 2:CLI 参数覆盖 YAML 配置

python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --max-steps 20 \
  --temperature 0.2 \
  --language zh \
  --evaluators numeric_answer em f1

场景 3:不用 YAML,纯 CLI 参数

python run_benchmark.py \
  --dataset gsm8k-n10 \
  --evaluators numeric_answer \
  --duty-prompt "你是一个专业的数学解题助手,仅输出最终数字答案。" \
  --max-steps 15 \
  --run-name gsm8k-custom-prompt

场景 4:重新评分已有结果(秒级,不调 LLM)

python run_benchmark.py \
  --rescore \
  --dataset gsm8k-n10 \
  --existing-run gsm8k-math-assistant \
  --evaluators em f1 exact_match

场景 5:上传新数据集并运行

# 先只上传,确认无误
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset my-new-benchmark \
  --upload data/test.jsonl \
  --evaluators numeric_answer \
  --dry-run

# 确认后运行实验
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset my-new-benchmark \
  --evaluators numeric_answer

JSONL 每行约定的默认 schema 形如:

{"question": "What is 2 + 2?", "answer": "4"}

其他字段 schema 可通过 --input-key / --output-key 指定。若没有现成数据,也可以直接用 datasets/gsm8k_loader.py 从 HuggingFace 下载 GSM8K 并抽样上传(例如 --sample 10 生成 gsm8k-n10)。

场景 6:对比不同 Agent 配置

# Agent A
python run_benchmark.py \
  --agent-config configs/agent_5.yaml \
  --dataset gsm8k-n10 \
  --evaluators numeric_answer \
  --run-name gsm8k-agent5

# Agent B
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --evaluators numeric_answer \
  --run-name gsm8k-agent7

# 在 Langfuse UI 中对比两个 run 的结果

场景 7:使用自定义系统 prompt

# 创建自定义 prompt 文件
cat > my_prompt.txt << 'EOF'
你是一个专业的数学解题助手。
请仔细阅读题目,逐步推导,最后只输出数字答案。
不要输出解题过程。
EOF

# 使用自定义 prompt
python run_benchmark.py \
  --dataset gsm8k-n10 \
  --system-prompt-file my_prompt.txt \
  --evaluators numeric_answer \
  --run-name gsm8k-custom-system-prompt

--system-prompt-file 会跳过模板引擎,直接以文件内容作为 system:custom ContextItem 注入,对应源码中 build_agent_run_info_with_custom_prompt() 的分支。

场景 8:选择上下文处理策略

# 自适应压缩
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --context-processing-mode adaptive_compact \
  --token-threshold 10000 \
  --evaluators numeric_answer

# 同一 ContextItems assembly,不压缩
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --context-processing-mode passthrough \
  --evaluators numeric_answer

四、配置优先级

CLI 参数 > YAML 配置 > 默认值

--duty-prompt "..."           → 覆盖 YAML 中的 duty_prompt
--max-steps 20                → 覆盖 YAML 中的 max_steps
--context-processing-mode adaptive_compact → 覆盖 YAML policy
--temperature 0.5             → 覆盖默认值 0.1

实现上,main() 中通过 args.xxx or agent_cfg.get(...) 的取值顺序保证"显式 CLI 值优先、其次是 YAML、最后是默认值";--context-processing-mode 还额外优先于 --enable/--disable-context-manager 兼容别名(run_benchmark.py)。

五、完整工作流

# 1. 导出 Agent 配置
backend/.venv/bin/python sdk/benchmark/generic/tools/export_agent_config.py --agent-id 7 --output configs/agent_7.yaml

# 2. 运行实验
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --evaluators numeric_answer

# 3. 用不同评分器重新评分(不调用 LLM)
python run_benchmark.py \
  --rescore \
  --dataset gsm8k-n10 \
  --existing-run gsm8k-n10-1720432800 \
  --evaluators em f1 exact_match keyword_match

# 4. 在 Langfuse UI 查看结果
# http://localhost:3100 → Datasets → gsm8k-n10 → Runs

第 1 步的导出脚本 export_agent_config.py 连接 PostgreSQL(环境变量 NEXENT_DB_HOST/PORT/NAME/USER/PASSWORD,源码),从 ag_tenant_agent_t、ag_tool_instance_t、ag_tool_info_t 等表读取 Agent 主配置、工具实例、子 Agent 与 Skill 关联,并把工具参数中的敏感值外部化为 $env 引用。它支持 --agent-id、--name、--version(默认 current_version_no)、--output 四个参数。详细的导出规范见 sdk/benchmark/generic/tools/EXPORT_AGENT_CONFIG.zh-CN.md。

六、Context processing P/C 标准对照

使用 run_context_manager_comparison.py 一次执行两组同代码配对实验:

  • P:context_items + passthrough;
  • C:context_items + adaptive_compact。

完整参数和运行规范见 sdk/benchmark/generic/RUN_CONTEXT_MANAGER_COMPARISON.md(中文版:RUN_CONTEXT_MANAGER_COMPARISON.zh-CN.md)。

默认先对每组运行一个 item 的 smoke test,再执行正式实验:

python sdk/benchmark/generic/run_context_manager_comparison.py \
  --dataset gaia-level1-web-search \
  --run-prefix gaia-context-20260723 \
  --repeat 3 \
  --soft-input-budget 10000 \
  --hard-input-budget 891808 \
  --budget-profile synthetic_trigger \
  --required-url data-process=http://localhost:5010/health \
  --runner-args \
    --agent-config path/to/gaia-agent.yaml \
    --evaluators gaia_exact_match \
    --max-steps 20 \
    --temperature 0

关键行为:

  • 两组共享 dataset、item 顺序、模型、tools、prompts、budget 和 evaluator;
  • 每轮随机交错 P/C 执行顺序,并记录实际顺序;
  • system prompt 模板使用相同实验时间;
  • run name 自动包含 phase、repeat 和组别;
  • 本地或 Langfuse 已存在同名 run 时拒绝启动;
  • smoke 使用相同的前 N 个 item,正式运行可用 --formal-items 限制;
  • 每轮运行后校验 resolved manifest 的非目标字段一致;
  • 输出不可覆盖的 JSON 和 Markdown 配对报告。

报告中的比较口径:

P vs C:同一 ContextItems runtime 下 adaptive compaction 的增量效果

历史 L 基线固定为 32152c3bf7d43c37ff36336080d120284a42046d,只在独立 worktree 中运行。L/P 比较是架构迁移效果,不能和 P/C 的策略归因混为一谈。三个环境(当前代码 P/C、Legacy worktree L)各自保存 code commit、依赖 lock、模型/provider/tool schema、dataset item ID 与 prompt/config hash,以保证跨版本可归因。

外部工具依赖通过重复传入 --required-url NAME=URL 纳入启动前检查。健康检查返回 5xx 或无法连接时,任何 Agent/LLM 调用开始前即终止。

七、输出示例与度量语义

7.1 运行输出

Loading agent config from: configs/agent_7.yaml
  Agent: 数学解答助手
  Description: 你是一个数学解答助手,擅长解答GSM8K等数学问题...

Evaluators: ['numeric_answer']
Langfuse connected: http://localhost:3100

Configuration:
  Max steps:    15
  Temperature:  0.1
  Language:     en
  Context mgr:  True
  Duty prompt:  你是一个专业的数学解题助手,负责解答各类数学计算问题...

  10 items loaded

============================================================
Running experiment: gsm8k-math-assistant
  Dataset:      gsm8k-n10 (10 items)
  Model:        deepseek-v4-flash
============================================================

[1/10] {"question": "Janet's ducks lay 16 eggs..."} ✓ numeric_answer=1.00
[2/10] {"question": "A robe takes 2 bolts..."} ✓ numeric_answer=1.00
...
[10/10] {"question": "Josh decides to try..."} ✗ numeric_answer=0.00

============================================================
Experiment complete: gsm8k-math-assistant
  Total:  10
  Passed: 9
  Failed: 1
  Avg numeric_answer: 0.9000

View in Langfuse: http://localhost:3100/dataset/xxx
============================================================

从 run_experiment() 可以看到,每个 item 的 trace 会写入 system_prompt、model_config、agent_config、compression、provider_cache、web_evidence、manifest_hash 等元数据;每个 step 分别以 model_step_N generation 与 final_answer span 形式落库,便于在 Langfuse UI 中逐题、逐步回放。

7.2 两类缓存的独立统计

每个 trace output 和 step metadata 分开记录两类缓存:

  • compression.summary_cache_hits / summary_cache_types:ContextManager 本地摘要复用;
  • provider_cache:provider 明确返回的 prompt/KV prefix cache usage。

summary_cache_hits 只统计 previous_cache_hit 和 current_cache_hit;未调用压缩模型的 stable_bypass 不等同于复用已有 summary,因而不计入(对应 agent_runner.py 对 cache type 的白名单过滤)。

provider_cache.status 的语义:

  • available:provider 返回了可信 cache token 字段,可计算 hit rate 和 cached input ratio;
  • unavailable:provider capability 已知,但本次响应没有 cache metrics;
  • unsupported:当前 provider capability 未声明支持。

只有 available 调用进入 provider_prefix_hit_rate 的分母。unavailable 和 unsupported 不会按 0% 命中处理,也不会通过 estimated/API token 差值推断。该语义在 task_adapter.py 的 _provider_cache_result() 中实现:先看是否有 available 调用,其次看状态集合中是否有 unavailable,否则归为 unsupported,绝不自行推断。

运行 DeepSeek 官方接口时应显式声明:

--model-factory deepseek

OpenAI 官方接口使用 --model-factory openai。未知 provider 默认是 unsupported;benchmark 不会仅凭 OpenAI-compatible URL 擅自启用。

7.3 重新评分输出示例

Evaluators: ['em', 'f1', 'exact_match']
Langfuse connected: http://localhost:3100

Rescore 'gsm8k-math-assistant-rescore': 10 traces from 'gsm8k-math-assistant'
  [1] scores={'em': 1.0, 'f1': 1.0, 'exact_match': 1.0}
  [2] scores={'em': 1.0, 'f1': 1.0, 'exact_match': 1.0}
  ...
  [10] scores={'em': 0.0, 'f1': 0.5, 'exact_match': 0.0}

Rescore 'gsm8k-math-assistant-rescore' DONE: 9/10 passed
  avg_em=0.9000
  avg_f1=0.9500
  avg_exact_match=0.9000

八、环境变量

必需

变量 说明
LLM_API_KEY LLM API 密钥
LLM_MODEL_NAME LLM 模型名称
LLM_API_URL LLM API 地址
LANGFUSE_HOST Langfuse 服务地址
LANGFUSE_PUBLIC_KEY Langfuse 公钥
LANGFUSE_SECRET_KEY Langfuse 私钥

可选

变量 说明 默认值
LANGFUSE_ENABLED 是否启用 Langfuse true

此外,按功能需要还可能用到:NEXENT_BENCHMARK_DATA_ROOT(本地数据/产物根目录,默认 <repo-parent>/nexent-data/benchmark/,见 README.zh-CN.md)、SKILLS_PATH(--skills-path 未传时的 Skill 根目录)、Agent YAML 中引用的工具凭据(如 EXA_API_KEY)。注意 .env 文件会被 load_dotenv() 加载(仓库根目录与 benchmark 目录两级),但密钥不应提交进仓库。

九、故障排除

Langfuse 连接失败

# 检查 Langfuse 容器状态
docker ps | grep langfuse

# 检查环境变量
echo $LANGFUSE_HOST
echo $LANGFUSE_PUBLIC_KEY
echo $LANGFUSE_SECRET_KEY

Langfuse 的本地部署方式(docker compose、初始化账号、健康检查)见 sdk/benchmark/infra/langfuse/README.md。连接失败时,run_benchmark.py 会打印 ERROR: Langfuse connection failed 并以退出码 1 终止(源码)。

LLM API 调用失败

# 检查 LLM 配置
echo $LLM_API_URL
echo $LLM_MODEL_NAME

# 测试 API 连接
curl -X POST $LLM_API_URL/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "'$LLM_MODEL_NAME'", "messages": [{"role": "user", "content": "test"}]}'

数据集不存在

# 先上传数据集
python run_benchmark.py \
  --dataset my-dataset \
  --upload data/test.jsonl \
  --dry-run

# 或检查 Langfuse UI 中是否存在该数据集

数据集为空时 run_experiment() 会打印 ERROR: Dataset is empty. 并直接返回(源码)。

评分器不存在

# 列出所有可用评分器
python run_benchmark.py --list-evaluators

十、性能优化

并行执行

# 增加并行数(注意 LLM API 限制)
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --max-concurrency 5 \
  --evaluators numeric_answer

--max-concurrency 默认 1,类型上限定为正整数(run_benchmark.py 的 positive_int)。

减少 LLM 调用

# 使用重新评分模式(不调用 LLM)
python run_benchmark.py \
  --rescore \
  --dataset gsm8k-n10 \
  --existing-run previous-run \
  --evaluators em f1

减少步数

# 限制最大步数(减少 token 消耗)
python run_benchmark.py \
  --agent-config configs/agent_7.yaml \
  --dataset gsm8k-n10 \
  --max-steps 5 \
  --evaluators numeric_answer

只跑失败题(小范围重复)

对已有 run 的失败题做定向重复实验,可使用 run_failed_item_repeats.py:它从基准 run 的主评分器分数筛选失败 item ID(不创建新数据集),每次重复创建独立 run,并把 pass/fail 与 pass rate 写入 artifacts/targeted_repeats/ 下的 JSON/Markdown 报告。基准 run 缺少主评分器分数时会报错,不把缺失观测当作失败。命令示例见 WEB_BENCHMARK_OPTIMIZATIONS.zh-CN.md。

十一、与旧脚本的对比

功能 run_experiment.py re_evaluate.py run_benchmark.py
运行新实验 ✅ ❌ ✅
重新评分 ❌ ✅ ✅
从 YAML 加载配置 ❌ ❌ ✅
CLI 覆盖配置 部分 部分 ✅
上传数据集 ✅ ❌ ✅
统一入口 ❌ ❌ ✅

结论:run_benchmark.py 完全替代 run_experiment.py 和 re_evaluate.py。

十二、Prompt 与 Tool assembly:与生产的对齐边界

Benchmark 不经过 backend/agents/create_agent_info.py,因此在 benchmark assembly 中显式模拟生产的被动注入行为:

  • YAML tools: 只保存 Agent 显式配置的工具;
  • 运行时额外注入 parallel_executor;
  • 运行时额外注入 run_skill_script、read_skill_md、read_skill_config、write_skill_file;
  • builtin skill tools 使用 agent_id、tenant_id、version_no 和 skills path 标记运行范围,不要求用户把它们写入 YAML;
  • YAML skills: 当前尚未实现生产的 Skill 发现、可见性过滤和完整执行链路。非空 skills: 不应被描述成已经完全对齐生产。

上述注入逻辑对应 agent_runner.py 的 inject_production_managed_tools():它镜像生产环境的被动装配,把 ParallelExecutorTool 与四个 builtin skill 工具(RunSkillScriptTool、ReadSkillMdTool、ReadSkillConfigTool、WriteSkillFileTool)追加到显式工具列表之后,并用 _benchmark_assembly_origin 元数据标记来源;--tenant-id 与 --skills-path 正是通过该函数的 agent_id/tenant_id/version_no/local_skills_dir 参数生效(run_benchmark.py)。

trace output 的 system_prompt 使用生产 ContextItemRenderer 渲染压缩前静态上下文(task_adapter.py 的 render_precompact_system_prompt()),因此 ### Available Resources 会包含实际装配的工具名称、描述、输入 schema 和输出类型,而不再只是空的资源标题。

十三、运行完整性检查

run_integrity.py 是独立的只读事后检查器(run_integrity.py),用于检查 dataset item 覆盖、重复 item、评分器 score 覆盖、trace output 必需字段、trace errors,以及可选 manifest 一致性:

backend/.venv/bin/python sdk/benchmark/generic/run_integrity.py \
  --dataset gaia-level1-reasoning \
  --run-name YOUR_RUN_NAME \
  --evaluators gaia_exact_match \
  --manifest $NEXENT_BENCHMARK_DATA_ROOT/artifacts/manifests/YOUR_RUN_NAME.manifest.json

返回码 0 表示完整,1 表示检查发现缺失或不一致,2 表示连接、认证或输入问题。

完整性检查要求的 trace output 必需字段为 agent_config、compression、model_config、provider_cache、system_prompt(源码常量)。实验结束后,还应把每条 run 的 manifest、dataset item ID、评分器名称、源码版本与报告一并保留作为结论依据。manifest 由 provenance/experiment_manifest.py 生成,schema v3,包含代码 commit、source tree hash、模型配置、工具 schema hash、parity snapshot hash、budget profile 等归因信息;write_manifest_exclusive() 采用不可覆盖写入,同名 run 已有 manifest 时会拒绝启动,从而保护实验 provenance。

十四、小结

run_benchmark.py 是 Nexent Agent 评测的统一、不可变入口:一条命令即可完成"导出配置 → 上传数据集 → 运行实验 → 重新评分 → 完整性校验"的完整闭环。理解它的三层配置优先级(CLI > YAML > 默认值)、32K legacy fallback 预算解析规则、P/C 上下文策略对照口径,以及 summary_cache 与 provider_cache 两类缓存度量的语义边界,是正确设计并解释 Nexent Agent 实验的前提。更多进阶能力(Web evidence artifact、Exa record/replay、失败题定向复测、GAIA 最终答案诊断)请继续阅读 WEB_BENCHMARK_OPTIMIZATIONS.zh-CN.md,以及作为上层编排器的 RUN_CONTEXT_MANAGER_COMPARISON.zh-CN.md。

登录后查看全文
nexent