Nexent Generic Benchmark Runner 实战指南：基于 Langfuse 的智能体端到端评测与上下文处理对照实验-优快云博客

【免费下载链接】nexent

Nexent 是一个开源智能体SDK和平台，能够将描述流程的自然语言转化为完整的多模态服务 —— 无需编排，无需复杂拖拉拽。基于 MCP 工具生态系统构建，Nexent 提供灵活的模型集成、可扩展的数据处理和强大的知识库管理。我们的目标很简单：将数据、模型和工具整合到一个智能中心中，让任何人都能轻松地将 Nexent 集成到项目中，使日常工作流程更智能、更互联。

项目地址： https://gitcode.com/ModelEngine/nexent

点击查看免费下载

本篇技术指南完整讲解 Nexent SDK 自带的通用基准评测框架（Generic Benchmark Runner）——一个基于 Langfuse 的独立评测工具链，它可以直接执行真实 SDK Agent，无需启动 Nexent 后端与前端。读完本文，你将掌握：如何用 Docker 快速拉起本地 Langfuse 评测栈、如何导入 GSM8K/GAIA 数据集并完成单条 smoke 验证、如何运行单次评测（run_benchmark.py）、如何执行同版本内的 P/C 上下文处理对照实验（passthrough vs adaptive_compact）、如何跨 Git worktree 做 Legacy/P 回归对照，以及如何用完整性检查脚本守护实验结论的可信度。

一、框架定位与整体架构

sdk/benchmark/generic/ 是一个独立、自包含的基准测试 harness：它直接驱动真实 SDK Agent 跑数据集，评测数据（数据集、trace、评分、dataset run）统一沉淀在 Langfuse 中，而实验清单（manifest）、web 证据和对照报告则保留在本地磁盘。它的核心设计意图是：

不依赖平台服务：不需要启动 Nexent backend / frontend，只依赖 SDK 本身与 Langfuse；
实验可复现、可追溯：每一次运行都有不可变 run name、manifest、源码修订哈希与评估器版本；
聚焦上下文处理策略对比：专门支持 passthrough（透传）与 adaptive_compact（自适应压缩）两种上下文处理模式的配对实验。

入口脚本一览（均位于 sdk/benchmark/generic/）：

脚本	用途
run_benchmark.py	执行或重新评分一次不可变基准运行
run_context_manager_comparison.py	对比当前版本的 passthrough（P）与 adaptive-compaction（C）两种模式
run_legacy_p_comparison.py	对比固定 Legacy worktree（L）与当前 passthrough 模式（P）
run_failed_item_repeats.py	仅重跑一次已完整运行中的失败条目
run_integrity.py	校验数据集链接、评估器评分、trace 状态与 manifest 的一致性

操作类命令位于 tools/ 子目录，可选的 Langfuse webhook 服务位于 integrations/langfuse/；支撑包提供任务适配（runtime/task_adapter.py）、评估器注册（evaluators/）、实验清单（provenance/）、回放（runtime/exa_replay.py）与证据分析（tools/web_evidence.py、tools/context_evidence_diff.py）等能力。

二、仓库与数据布局

源码和标准示例配置随仓库提交；数据集、附件、日志、生成的配置和运行产物全部保留在仓库之外，避免污染代码库。

默认的外部数据根目录为仓库父级下的 nexent-data/benchmark/：

<repo-parent>/nexent-data/benchmark/
├── datasets/
└── artifacts/

这个默认路径由 common/benchmark_paths.py 定义：BENCHMARK_DATA_ROOT 优先读取环境变量 NEXENT_BENCHMARK_DATA_ROOT，未设置时回退到 <repo-parent>/nexent-data/benchmark/，随后派生 DATASET_ROOT（datasets/）与 ARTIFACT_ROOT（artifacts/）。从源码结构看，ensure_benchmark_data_directories() 会在需要写入时自动创建这两个目录。

切换数据位置只需导出环境变量：

export NEXENT_BENCHMARK_DATA_ROOT=/path/to/benchmark-data

仓库内提交的标准 Agent 配置示例包括（位于 sdk/benchmark/generic/configs/）：

gaia_solver.yaml：GAIA 基准解题助手（多模态工具 + exa 搜索 + 终端 + 文件读取）；
gsm8k_solver_assistant.yaml：GSM8K 数学解答助手；
agent_example.yaml：带 few-shot 的数学助手示例；
agent_7_test.yaml。

实验专属的配置变体与生成的结果文件保持本地、不入库。

三、端到端评测流水线

README 给出的完整流水线如下：

Prepare Python and credentials
  -> start Langfuse
  -> import or select a dataset
  -> run one-item smoke
  -> run a single, P/C, or L/P experiment
  -> inspect Langfuse and local reports
  -> validate run integrity

除个别步骤显式切换目录外，以下所有命令都从仓库根目录执行。

3.1 准备运行环境

需要满足以下前置条件：

Python 3.11 环境位于 backend/.venv，且 SDK 以开发模式安装；
Docker（含 Compose 插件），用于本地 Langfuse 栈；
真实模型调用凭据：LLM_API_KEY、LLM_MODEL_NAME、LLM_API_URL；
所选 Agent YAML 引用的工具凭据，例如启用 exa_search 工具时需要 EXA_API_KEY（见 gaia_solver.yaml 中 $env: EXA_API_KEY 的引用方式）。

可选：指定外部数据与产物根目录（见上文 NEXENT_BENCHMARK_DATA_ROOT）。严禁提交任何服务、模型或工具密钥。

3.2 启动并配置 Langfuse

首次启动时，先复制环境模板并替换所有 replace-me 占位值：

cd sdk/benchmark/infra/langfuse
cp .env.example .env
# Edit .env before continuing.
docker compose -p nexent-benchmark-langfuse up -d
docker compose -p nexent-benchmark-langfuse ps
curl -s http://localhost:3100/api/public/health
cd ../../../..

本地 Langfuse 栈由 sdk/benchmark/infra/langfuse/compose.yaml 编排，会同时拉起 Langfuse web/worker 服务以及 PostgreSQL、ClickHouse、Redis、MinIO 等依赖组件；Langfuse web 发布在宿主机 3100 端口。

随后导出基准进程所需的项目凭据：

set -a
source sdk/benchmark/infra/langfuse/.env
set +a
export LANGFUSE_HOST=http://localhost:3100
export LANGFUSE_PUBLIC_KEY="$LANGFUSE_INIT_PROJECT_PUBLIC_KEY"
export LANGFUSE_SECRET_KEY="$LANGFUSE_INIT_PROJECT_SECRET_KEY"

打开 http://localhost:3100，使用同一个 .env 文件中的初始化账号登录。生命周期与安全细节参见 sdk/benchmark/infra/langfuse/README.md：.env 已被 Git 忽略、严禁提交；compose.yaml 将 Langfuse web 发布在 3100 端口，机器若可从网络访问应限制宿主机访问，对外暴露前请使用可信反向代理与 TLS。generic 运行器直接连接 Langfuse，ctx_debugger 仅用于可选的深度上下文追踪。

3.3 导入或选择数据集

若数据集已存在于所选 Langfuse 项目中，保持其名称不变，直接进入 smoke 运行。对于新的 JSONL 数据集，每行应包含配置好的输入键与期望输出键，例如：

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

使用 --dry-run 只上传、不调用模型：

backend/.venv/bin/python sdk/benchmark/generic/run_benchmark.py \
  --dataset my-benchmark \
  --upload /path/to/dataset.jsonl \
  --evaluators exact_match \
  --dry-run

默认 JSONL 键为 question 与 answer；其他 schema 通过 --input-key、--output-key 指定。底层上传逻辑在 run_benchmark.py 的 upload_jsonl()：逐行解析 JSON，将输入键之外的字段并入 input，期望输出键存在时才写入 expected_output，并跳过非法 JSON 行。注意：向已存在的数据集重复上传可能产生重复条目，因此重复导入前务必在 Langfuse 中核对数据集。

此外：

GSM8K 可通过 datasets/gsm8k_loader.py 下载并上传（从 HuggingFace 加载 openai/gsm8k，用 #### <number> 规则抽取黄金数字答案，支持 --sample N 随机采样与 --save_jsonl 落盘）；
GAIA 基于文件的任务还要求附件存在于数据集中记录的 S3/MinIO 路径，可用 tools/gaia/upload_files.py 准备附件。

数据集专属的运行选项详见 sdk/benchmark/generic/RUN_BENCHMARK.md。

3.4 真实单条 smoke 运行

每次执行必须使用新的 run name：

backend/.venv/bin/python sdk/benchmark/generic/run_benchmark.py \
  --dataset gaia-level1-web-search \
  --run-name gaia-web-smoke-YYYYMMDD \
  --item-limit 1 \
  --agent-config sdk/benchmark/generic/configs/gaia_solver.yaml \
  --language en \
  --evaluators gaia_exact_match \
  --max-steps 15 \
  --temperature 0 \
  --model-factory openai \
  --context-processing-mode passthrough

在启动更大规模实验前，请确认控制台结果、Langfuse 评估器评分、dataset-run 条目与 trace 状态四者一致。运行器会拒绝本地或 Langfuse 侧的 run name 冲突，以保护实验溯源——这一点在 run_benchmark.py 中体现为：run 已有 manifest 或 web 证据文件时直接抛出 FileExistsError，P/C 比较器的 preflight() 也会同时检查本地与远端 run 名冲突（run_context_manager_comparison.py）。

3.5 选择实验类型

单次运行（Single run）

用 run_benchmark.py 评测一种配置或一种处理策略，它同时也是两个对照编排器（P/C、L/P）的底层执行器。全部选项、重评分、输出与完整性检查见 sdk/benchmark/generic/RUN_BENCHMARK.md。

当前版本内的 P/C 对照

P/C 对照保持代码修订、数据集条目、模型、提示词、工具、评估器、实验时间完全对齐，仅对比处理策略：

分支	处理模式
P	`passthrough`
C	`adaptive_compact`

只有当 manifest 对等校验（parity）通过时，对照结果才被解释为"仅处理策略差异"。单条配对验收运行：

backend/.venv/bin/python sdk/benchmark/generic/run_context_manager_comparison.py \
  --dataset gaia-level1-web-search \
  --run-prefix gaia-web-pc-smoke-YYYYMMDD \
  --skip-smoke \
  --formal-items 1 \
  --repeat 1 \
  --soft-input-budget 10000 \
  --hard-input-budget 900000 \
  --budget-profile synthetic_trigger \
  --runner-args \
    --agent-config sdk/benchmark/generic/configs/gaia_solver.yaml \
    --language en \
    --evaluators gaia_exact_match \
    --max-steps 15 \
    --temperature 0 \
    --model-factory openai \
    --context-window-tokens 1000000

P/C 运行器拥有数据集、run 名、处理模式、条目限制、实验时间与预算等变量，这些选项不得通过 --runner-args 透传（run_context_manager_comparison.py 定义了 CONTROLLED_RUNNER_ARGS 并逐一校验拒绝）。受控参数详见 sdk/benchmark/generic/RUN_CONTEXT_MANAGER_COMPARISON.md。

跨修订的 L/P 对照

L/P 将固定版本的 Legacy worktree 与当前 passthrough 候选进行端到端跨修订回归对比，除非已证明组装对等（assembly parity），否则不得将其描述为仅 ContextManager 差异。两个 worktree 都需要可用的 Python 环境，并继承同一套已导出的 Langfuse、模型与工具凭据：

export REPO_ROOT="$(pwd)"
export LEGACY_ROOT=/path/to/legacy-worktree

backend/.venv/bin/python sdk/benchmark/generic/run_legacy_p_comparison.py \
  --dataset gaia-level1-reasoning \
  --run-prefix gaia-reasoning-lp-smoke-YYYYMMDD \
  --legacy-root "$LEGACY_ROOT" \
  --smoke-only \
  --smoke-items 1 \
  --candidate-soft-input-budget 10000 \
  --candidate-hard-input-budget 900000 \
  --candidate-context-window-tokens 1000000 \
  --candidate-budget-profile synthetic_trigger \
  --runner-args \
    --agent-config "$REPO_ROOT/sdk/benchmark/generic/configs/gaia_solver.yaml" \
    --language en \
    --evaluators gaia_exact_match \
    --max-steps 15 \
    --temperature 0

worktree 准备、解释器核验、正式运行与因果范围规则见 sdk/benchmark/generic/RUN_LEGACY_P_COMPARISON.md。

3.6 检查与验证结果

在 Langfuse 数据集页面查看 run 条目、trace、输出与评分。本地对照报告写入：

$NEXENT_BENCHMARK_DATA_ROOT/artifacts/comparisons/          # P/C
$NEXENT_BENCHMARK_DATA_ROOT/artifacts/legacy_p_comparisons/ # L/P

对单次运行执行只读完整性检查（命令见下文第四节）。INCOMPLETE 状态必须视为验收失败，直到缺失评分、缺失链接、空输出或 trace 错误均得到解释。每次实验结果都要保留 run name、manifest、源码修订、数据集条目 ID、评估器名称与报告。

四、单次运行执行器 run_benchmark.py 深度解析

run_benchmark.py 同时是直接使用的单次执行器与两个对照编排器的底层引擎，取代了早期的 run_experiment.py 与 re_evaluate.py。

4.1 标准执行与重要选项

标准执行命令（与 3.4 节相同）。重要选项：

选项	含义
`--dataset`	Langfuse 数据集名称
`--run-name`	不可变的 dataset-run 名称
`--item-id` / `--item-limit`	限制所选条目（二者不可同时使用）
`--agent-config`	YAML Agent 快照
`--evaluators`	一个或多个已注册评估器
`--context-processing-mode`	`passthrough` 或 `adaptive_compact`
`--soft-input-budget`	自适应压缩触发预算；默认 32,768
`--hard-input-budget`	不可协商的输入上限；Legacy 默认 36,044
`--context-window-tokens`	Provider/模型上下文窗口；默认 32,768
`--budget-profile`	预算来源标签
`--experiment-time`	冻结的提示词时间，供对照分支共享
`--dry-run`	只校验配置，不运行数据集

Legacy 的 --enable-context-manager / --disable-context-manager 是兼容别名，新命令应使用 --context-processing-mode。

CLI 参数覆盖 YAML 值，缺失值回退到运行器默认值（run_benchmark.py 展示了合并逻辑）。默认阈值来自 SDK 的 32K legacy 回退：DEFAULT_CONTEXT_WINDOW_TOKENS = 32_768，软预算默认等于阈值 32,768，硬护栏为 int(32768 * 1.1) = 36,044（run_benchmark.py）。该硬护栏并非基于 Provider 容量计算，正式实验仍应显式传入与模型匹配的软/硬预算。

--budget-profile 的可选值包括 legacy_threshold、production_like、synthetic_trigger、synthetic_stress，用于在 manifest 中记录预算来源/分类；--model-factory 是用于缓存指标统计的显式 Provider 能力标识（如 openai），未知 Provider 保持 unsupported 状态。

上下文处理策略最终通过 ContextManagerConfig 与 PolicyLayers(platform={"processing_mode": ...}) 注入任务（run_benchmark.py），并支持 --keep-recent-steps 控制压缩时保留的最近动作步数（SDK 默认 4）。

4.2 重新评分（Rescoring）

重新评分复用已有 trace，不调用模型：

backend/.venv/bin/python sdk/benchmark/generic/run_benchmark.py \
  --rescore \
  --dataset gaia-level1-web-search \
  --existing-run EXISTING_RUN \
  --run-name EXISTING_RUN-rescore-v2 \
  --evaluators gaia_exact_match

底层 rescore_experiment()（run_benchmark.py）读取既有 dataset-run 的 trace 输出，按条目重新打分并生成新的 re-eval-* trace 与新 run 链接。

4.3 输出与清单

每次运行会产出：

Langfuse dataset run 与 trace 链接；
评估器评分；
manifest，位于 $NEXENT_BENCHMARK_DATA_ROOT/artifacts/manifests/；
web 证据（如适用），位于 $NEXENT_BENCHMARK_DATA_ROOT/artifacts/web_evidence/。

解读结果时必须保留：run name、manifest、源码修订、数据集条目集合、评估器名称、模型配置、提示词/工具哈希与预算设置。manifest 机制由 provenance/experiment_manifest.py 实现：MANIFEST_SCHEMA_VERSION = 3，通过 canonical_json + SHA-256 计算哈希，resolve_code_commit() 记录 Git commit，compute_source_tree_hash() 用临时 Git index 计算工作树内容哈希（不修改真实 index 与工作树）。

4.4 完整性检查

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

run_integrity.py 的 check_run_integrity() 会检查：链接 trace 数量与唯一条目数、缺失/重复条目 ID、每个 trace 上评估器评分覆盖度、trace 输出完整性（要求 agent_config、compression、model_config、provider_cache、system_prompt 等字段齐全）、trace 中的 errors，以及 manifest 与 run 的条目/评估器对等性；IntegrityReport.summary() 输出 COMPLETE / INCOMPLETE 状态，CLI 以退出码 0/1 表示成败。该函数也可作为库直接调用。

五、P/C 上下文处理对照实验详解

run_context_manager_comparison.py 在同一代码修订上，对相同的 ContextItems 组装运行配对对比。只有当 manifest 对等校验通过，才把差异归因于处理策略。

5.1 参数与执行语义

P/C 运行器自身拥有：--dataset、--run-prefix、--repeat、--smoke-items/--skip-smoke、--formal-items、--soft-input-budget/--hard-input-budget（必须成对给出，且要求 soft < hard）、--budget-profile、--seed、--required-url（格式 NAME=URL，HTTP >= 500 视为服务不健康）、--runner-args（原样转发给 run_benchmark.py 的参数）。

运行流程（run_context_manager_comparison.py）：

构造 P、C 两组（comparison_groups()），P 用 passthrough，C 用 adaptive_compact，预算参数两组一致；
生成不可变 run 名 {prefix}-{phase}-r{repeat:02d}-{group.key}-{group.label}，保证碰撞安全；
preflight() 校验 Langfuse 认证、数据集非空且条目 ID 无重复、必需 URL 健康、本地 manifest 与远端 run 名均无冲突；
按 phase（smoke + 每个 repeat 一次 formal）逐组调用子进程 run_benchmark.py，--experiment-time 由运行器统一冻结（两组共享同一时间）；
等待 dataset-run 链接与评估器评分落定（fetch_complete_dataset_run 最多重试 30 次、fetch_run_results 最多等待 10 次），缺失评分会显式超时，而不是被当作答错；
汇总 provider 前缀缓存、ContextManager summary 缓存、预算/溢出证据，执行 manifest 对等校验与完整性检查；
以排他模式（open("x")）写入不可变的 JSON 与 Markdown 报告，报告路径已存在则拒绝覆盖。

5.2 配对结果矩阵与报告解读

配对矩阵使用：

PP：P 与 C 均通过；
PF：P 通过、C 失败；
FP：P 失败、C 通过；
FF：两者均失败。

报告同时分离 Provider 前缀缓存指标与 ContextManager summary 缓存指标（分别来自 trace 输出中的 provider_cache 与 compression.summary_cache_*），并记录预算/压缩证据（over_soft_budget_count、over_hard_budget_count、compression_triggered_count、overflow_avoidance_rate、max/avg_peak_context_tokens）。

报告文件写入：

$NEXENT_BENCHMARK_DATA_ROOT/artifacts/comparisons/<run-prefix>.comparison.json
$NEXENT_BENCHMARK_DATA_ROOT/artifacts/comparisons/<run-prefix>.comparison.md

Markdown 报告按 phase/repeat 输出四张表：配对结果矩阵（PP/PF/FP/FF）、Provider 前缀缓存（status/available calls/hit calls/hit rate/cached tokens/cached input ratio）、ContextManager summary 缓存（hits/types）、预算与溢出（over soft/over hard/compression triggered/avoidance rate/max peak ctx）。

5.3 Manifest 对等校验

validate_manifest_parity()（run_context_manager_comparison.py）对比 P/C 两组 manifest 的 18 个不变字段（数据集名与版本、条目 ID、源码树哈希、生命周期模式、主模型/总结模型/端点/工厂、温度、步数、语言、并发、工具数与工具 schema 哈希、系统提示词哈希、预算 profile、评估器名与版本），并将 parity snapshot 中的 processing_mode 归一化后再比对；任一项不一致即抛错拒绝。此外校验 P/C 的处理模式必须分别为 passthrough / adaptive_compact、两组都使用统一 ContextItems runtime、manifest 含已解析的硬预算与上下文策略指纹。

六、L/P 跨修订回归对照详解

run_legacy_p_comparison.py 将重构前的 Legacy 运行时与当前 passthrough 策略放在独立的 Git worktree 与独立 Python 环境中对比，独立于 P/C 协议及其产物。

标准分支：

分支	来源	上下文配置
L	Legacy worktree	`--disable-context-manager`
P	候选 worktree	`--context-processing-mode passthrough`

这是跨修订回归对比。如果提示词或工具哈希不同，报告会标记 causal_scope=end_to_end_revision，此时结果不得被描述为仅 ContextManager 效应；需要这种漂移直接判失败时，使用 --require-assembly-parity。从源码看（run_legacy_p_comparison.py），EXECUTION_INVARIANT_FIELDS 与 ASSEMBLY_PARITY_FIELDS 将执行不变量与组装对等字段分开管理。

6.1 环境检查

定义可移植的 worktree 与产物根目录，并核验每个解释器导入的是自己 worktree 的包：

export REPO_ROOT=/path/to/nexent
export LEGACY_ROOT=/path/to/legacy-worktree
export NEXENT_BENCHMARK_DATA_ROOT=/path/to/benchmark-data

$LEGACY_ROOT/backend/.venv/bin/python \
  -c "import sys; sys.path.insert(0, '$LEGACY_ROOT/sdk/benchmark'); import paths, nexent; print(nexent.__file__)"

$REPO_ROOT/backend/.venv/bin/python \
  -c "import sys; sys.path.insert(0, '$REPO_ROOT/sdk/benchmark'); import paths, nexent; print(nexent.__file__)"

6.2 Smoke 与正式运行

候选预算选项是 P-only 的，因为 Legacy 运行器不支持新的预算 CLI：

backend/.venv/bin/python \
  sdk/benchmark/generic/run_legacy_p_comparison.py \
  --dataset gaia-level1-reasoning \
  --run-prefix gaia-reasoning-lp-smoke-YYYYMMDD \
  --legacy-root $LEGACY_ROOT \
  --smoke-only \
  --smoke-items 1 \
  --candidate-soft-input-budget 10000 \
  --candidate-hard-input-budget 900000 \
  --candidate-context-window-tokens 1000000 \
  --candidate-budget-profile synthetic_trigger \
  --runner-args \
    --agent-config $REPO_ROOT/sdk/benchmark/generic/configs/gaia_solver.yaml \
    --language zh \
    --evaluators gaia_exact_match \
    --max-steps 15 \
    --temperature 0

正式运行使用新的不可变前缀并选择重复次数：

backend/.venv/bin/python \
  sdk/benchmark/generic/run_legacy_p_comparison.py \
  --dataset gaia-level1-reasoning \
  --run-prefix gaia-reasoning-lp-formal-YYYYMMDD \
  --legacy-root $LEGACY_ROOT \
  --skip-smoke \
  --repeat 5 \
  --candidate-soft-input-budget 10000 \
  --candidate-hard-input-budget 900000 \
  --candidate-context-window-tokens 1000000 \
  --candidate-budget-profile synthetic_trigger \
  --runner-args \
    --agent-config $REPO_ROOT/sdk/benchmark/generic/configs/gaia_solver.yaml \
    --language zh \
    --evaluators gaia_exact_match \
    --max-steps 15 \
    --temperature 0

报告写入 $NEXENT_BENCHMARK_DATA_ROOT/artifacts/legacy_p_comparisons/，与既有 P/C 报告分离。配对矩阵同样使用：

PP：两分支均通过；
PF：Legacy 通过、P 失败；
FP：Legacy 失败、P 通过；
FF：两者均失败。

七、评估器注册表与 Agent 配置导出

7.1 评估器

评估器注册表位于 evaluators/init.py，通过名称解析函数，兼容 Langfuse 的 EvaluatorFunction 协议（def evaluator(*, input, output, expected_output, metadata, **kwargs) -> Evaluation）。可用评估器：

名称	模块	用途
`exact_match`	exact_match.py	精确字符串匹配
`gaia_exact_match`	gaia_exact_match.py	GAIA 精确答案匹配
`gaia_final_answer`	gaia_final_answer.py	GAIA 最终答案提取匹配
`em` / `f1`	em_f1.py	精确匹配率与 F1
`keyword_match`	keyword_match.py	关键词匹配
`numeric_answer`	numeric_answer.py	数值答案匹配

resolve_evaluators() 对未知名称抛出带可用列表的 ValueError；run_benchmark.py --list-evaluators 可列出全部评估器。

7.2 Agent 配置导出

tools/export_agent_config.py 从 PostgreSQL 读取 Agent 定义并写出 run_benchmark.py 可接受的 YAML 快照。数据库连接信息来自进程环境或仓库 .env：

变量	默认值
`NEXENT_DB_HOST`	`localhost`
`NEXENT_DB_PORT`	`5434`
`NEXENT_DB_NAME`	`nexent`
`NEXENT_DB_USER`	`root`
`NEXENT_DB_PASSWORD`	本地开发默认值

用法（详见 sdk/benchmark/generic/tools/EXPORT_AGENT_CONFIG.md）：

backend/.venv/bin/python sdk/benchmark/generic/tools/export_agent_config.py \
  --agent-id 7 \
  --output /tmp/agent_7.yaml

backend/.venv/bin/python sdk/benchmark/generic/tools/export_agent_config.py \
  --name "Math Assistant" \
  --version 1 \
  --output /tmp/math_assistant_v1.yaml

--agent-id 与 --name 必须二选一；省略 --version 时导出当前版本。敏感工具参数会导出为严格的 {"$env": "VARIABLE_NAME"} 引用（由 common/secret_refs.py 的 resolve_env_references() 在加载时解析）。使用导出文件前建议：复核 agent/工具/子代理/技能元数据、确认所有敏感值均为 $env 引用、运行 run_benchmark.py --dry-run --agent-config <path> 校验；生成文件默认不入库。

7.3 标准 Agent 配置的结构

以 gaia_solver.yaml 为例，配置分为：

agent_info：agent_id、name、display_name、description、greeting_message、example_questions；
agent_config：max_steps、enable_context_manager、provide_run_summary、prompt_template_id、version_no，以及 verification_config（pass_score、strictness、fail_policy、critical_events、max_final_rounds 等）；
prompts：duty_prompt、constraint_prompt、few_shots_prompt；
tools：工具列表，每个工具含 tool_name、tool_class、tool_source、tool_category、tool_description、tool_inputs（JSON Schema 风格）、tool_output_type、tool_params（含 $env 密钥引用）、enabled；
sub_agents 与 skills：子代理与技能列表。

GAIA 解题助手启用的工具包括多模态分析（analyze_audio/analyze_image/analyze_video/analyze_text_file）、exa_search 联网搜索、read_file 本地文件读取与 terminal 终端执行。任务执行链路由 runtime/task_adapter.py 的 make_nexent_task() 桥接：从 Langfuse DatasetItem 提取问题、经 agent_runner.py 构建 AgentRunInfo、执行 Agent 并返回结构化结果（含 agent_config、compression、model_config、provider_cache、system_prompt、parity_snapshot 等必需字段）。

八、失败条目重跑与 Web 证据

8.1 失败条目重跑

run_failed_item_repeats.py 从已完成基准运行的失败条目中构建一次隔离运行：baseline_failed_item_ids() 按数据集顺序收集主评估器得分 < 1.0 的条目，若基线缺失评分则直接报错，随后用 --item-id 逐个指定失败条目调用 run_benchmark.py，形成只含失败条目的新 run。

8.2 Web 证据与 Langfuse Webhook

Web 证据聚合与写入由 tools/web_evidence.py 负责，产物位于 $NEXENT_BENCHMARK_DATA_ROOT/artifacts/web_evidence/；run_benchmark.py 控制台会汇总 Exa search / Tavily extract / Terminal fetch 调用次数与 URL 发现统计；
--exa-cache-mode（off/record/replay）配合 --exa-cache-path 可实现基准专用的 Exa 调用录制与回放（runtime/exa_replay.py）：record 复用命中并记录未命中，replay 遇未命中且无在线回退时直接失败；
可选 Langfuse webhook 服务器见 integrations/langfuse/README.md，部署方式见 integrations/langfuse/DEPLOY.md，web 证据与失败条目重跑优化见 integrations/langfuse/WEB_BENCHMARK_OPTIMIZATIONS.md。

九、进一步阅读

单次运行执行器：sdk/benchmark/generic/RUN_BENCHMARK.md
P/C 对照实验：sdk/benchmark/generic/RUN_CONTEXT_MANAGER_COMPARISON.md
L/P 跨修订对照：sdk/benchmark/generic/RUN_LEGACY_P_COMPARISON.md
Agent 配置导出：sdk/benchmark/generic/tools/EXPORT_AGENT_CONFIG.md
本地 Langfuse 栈：sdk/benchmark/infra/langfuse/README.md

仓库内各文档均提供 .zh-CN.md 中文版本；历史实验报告为保留溯源保持原始语言。

【免费下载链接】nexent

项目地址： https://gitcode.com/ModelEngine/nexent

点击查看免费下载

上一篇： vue-router 重定向与别名（Redirect & Alias）完全指南：配置写法、导航守卫差异与源码级原理

下一篇： 10分钟上手IDM-Activation-Script：从使用到贡献的超实用指南

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Nexent Generic Benchmark Runner 实战指南：基于 Langfuse 的智能体端到端评测与上下文处理对照实验

【免费下载链接】nexent

一、框架定位与整体架构

二、仓库与数据布局

三、端到端评测流水线

3.1 准备运行环境

3.2 启动并配置 Langfuse

3.3 导入或选择数据集

3.4 真实单条 smoke 运行

3.5 选择实验类型

单次运行（Single run）

当前版本内的 P/C 对照

跨修订的 L/P 对照

3.6 检查与验证结果

四、单次运行执行器 run_benchmark.py 深度解析

4.1 标准执行与重要选项

4.2 重新评分（Rescoring）

4.3 输出与清单

4.4 完整性检查

五、P/C 上下文处理对照实验详解

5.1 参数与执行语义

5.2 配对结果矩阵与报告解读

5.3 Manifest 对等校验

六、L/P 跨修订回归对照详解

6.1 环境检查

6.2 Smoke 与正式运行

七、评估器注册表与 Agent 配置导出

7.1 评估器

7.2 Agent 配置导出

7.3 标准 Agent 配置的结构

八、失败条目重跑与 Web 证据

8.1 失败条目重跑

8.2 Web 证据与 Langfuse Webhook

九、进一步阅读

【免费下载链接】nexent

相关推荐

Nexent Benchmark 上下文处理 P/C 对照实验：passthrough 与 adaptive_compact 的可归因评测指南

Nexent 上下文处理 P/C 对照实验指南：passthrough 与 adaptive_compact 的可归因对比方法

Nexent Langfuse Webhook 服务实战：从 UI 一键触发 Benchmark 实验与重新评分