Nexent 统一 Benchmark Runner:run_benchmark.py 全参数指南与源码级原理解析
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)。
逻辑流程:
- 从 YAML 读取旧
enable_context_manager,映射为 policy; --context-processing-mode优先覆盖 YAML;- 创建带
PolicyLayers的ContextManagerConfig(run_benchmark.py); - 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。